> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Maya: a Calendar chief of staff
> Turn today's Google Calendar into one operating brief, with conflicts flagged and source status stated plainly instead of invented.
Maya is a TypeScript agent that reads a bounded window of your Google Calendar, normalizes the events, detects overlaps, and asks one LLM call to write a short executive summary. It posts the brief to Slack, or returns the rendered text so another tool can deliver it.
```text theme={null}
schedule or request -> bounded Calendar read -> normalize + detect conflicts
-> one grounded synthesis
-> Slack post or returned text
```
View the agent and its source on the Agent Hub.
## At a glance
* **Agent type:** auto-managed [TypeScript agent](/guide/coded-agents)
* **Integrations:** [Google Calendar](/integrations/google-calendar) (read-only) and, for direct delivery, [Slack](/integrations/slack)
* **Runs from:** a [schedule trigger](/platform/schedule-triggers), or a session with JSON input
* **LLM calls:** one per brief
**What it does:**
* Reads a window that starts now, runs for a set number of hours, and never crosses local midnight in your timezone
* Keeps at most 20 source events, 12 events in the brief, and 6 conflicts
* States when the Calendar was only partly available, or unavailable, instead of filling the gap
* Gives each day's brief a stable ID, and checks Slack for it before posting, so a retry doesn't post twice
* Returns the brief instead of posting it when called with `delivery: "return"`
* Has no tools that create or change Calendar events
## How it works
Workspace variables set the timezone, the Calendar, the look-ahead period, the Slack channel, and the Slack bot's identity. The input can't override the channel.
Maya reads the configured Calendar once. Synchronous helpers normalize the timestamps and detect overlaps. Event descriptions, URLs, and provider IDs never reach the LLM prompt.
The LLM receives a capped packet of normalized events and writes only the executive summary. Deterministic code renders the headings, event lines, conflicts, source status, and the brief's ID marker.
In direct mode, Maya reads one page of the Slack channel's history first. If it finds its own message with today's marker, it skips the post. In return mode, it makes no Slack calls and returns the rendered text.
## Build the agent
### Define the input and output
Configuration lives in [workspace variables](/platform/workspace-variables). The input chooses how Maya was invoked and how to deliver, but can't supply a Calendar ID or a Slack destination:
```ts theme={null}
import { agent, type Task } from "@guildai/agents-sdk";
import { z } from "zod";
const inputSchema = z.object({
type: z.enum(["text", "timer"]).optional(),
text: z.string().max(8_000).optional(),
runAt: z.string().datetime().optional(),
deliveryKey: z
.string()
.min(1)
.max(64)
.regex(/^[A-Za-z0-9._-]+$/)
.optional(),
delivery: z.enum(["slack", "return"]).optional(),
});
const outputSchema = z.object({
status: z.enum([
"completed",
"partial",
"failed",
"skipped",
"deduplicated",
]),
text: z.string().max(6_000),
brief: briefSchema,
notification: z.object({
subject: z.string().max(120),
text: z.string().max(6_000),
}),
deliveryReceipt: deliveryReceiptSchema,
deliveryHandoff: z.object({
kind: z.literal("notification"),
channel: z.literal("slack"),
configuredChannel: z.string().max(100),
delivered: z.boolean(),
payload: z.object({
subject: z.string().max(120),
text: z.string().max(6_000),
}),
receipt: deliveryReceiptSchema,
}),
warnings: z.array(z.string().max(120)).max(8),
message: z.string().max(200),
});
```
The full source also accepts a bounded Slack event envelope, for correlation when another Slack app invokes Maya.
### Register the Calendar and Slack tools
Only the Calendar read comes from a service package. Each Slack operation is registered on its own with `guildServiceTool`:
```ts theme={null}
import {
consoleTools,
guildServiceTool,
pick,
} from "@guildai/agents-sdk";
import { GoogleCalendarOauthTools } from "@guildai-services/guildlabs~google-calendar-oauth";
const tools = {
...pick(GoogleCalendarOauthTools, [
"google_calendar_oauth_events_list",
]),
slack_conversations_history: guildServiceTool("slack", {
description:
"Read one bounded channel page to suppress sequential duplicate briefs.",
inputSchema: slackHistoryInputSchema,
outputSchema: slackHistoryOutputSchema,
}),
slack_chat_post_message: guildServiceTool("slack", {
description: "Post one brief to the configured Slack channel.",
inputSchema: slackPostMessageInputSchema,
outputSchema: slackPostMessageOutputSchema,
}),
...consoleTools,
};
```
The published source also rewrites the Calendar tool's service name to `google-calendar-oauth`, the integration's name in the live catalog. That's needed only because the `1.0.0` package it pins was generated before a codegen fix. A package version generated after the fix already carries the right name and doesn't need the rewrite.
### Resolve the local-day window
The look-ahead period never crosses local midnight:
```ts theme={null}
export function resolveBriefWindow(
runAtInput: string | undefined,
timezone: string,
lookAheadHours: number,
): BriefWindow {
const runAt = runAtInput ? new Date(runAtInput) : new Date();
if (Number.isNaN(runAt.getTime())) {
throw new Error("runAt must be a valid ISO timestamp.");
}
const localDate = dateInTimezone(runAt, timezone);
const endOfLocalDay = zonedMidnight(addDays(localDate, 1), timezone);
const lookAheadEnd = new Date(runAt.getTime() + lookAheadHours * 3_600_000);
const end =
lookAheadEnd.getTime() < endOfLocalDay.getTime()
? lookAheadEnd
: endOfLocalDay;
return {
start: runAt.toISOString(),
end: end.toISOString(),
localDate,
};
}
```
### Detect conflicts without the LLM
Conflict detection is deterministic and capped. Because the events are sorted, the inner loop stops as soon as later events can no longer overlap:
```ts theme={null}
export function detectCalendarConflicts(
events: CalendarEvent[],
): ConflictDetection {
const timed = events
.filter((event) => !event.allDay)
.map((event) => ({
event,
startMs: Date.parse(event.start),
endMs: Date.parse(event.end),
}))
.filter((entry) => entry.endMs > entry.startMs)
.sort((left, right) => left.startMs - right.startMs);
const conflicts: CalendarConflict[] = [];
let totalDetected = 0;
for (let leftIndex = 0; leftIndex < timed.length; leftIndex += 1) {
const left = timed[leftIndex];
for (let rightIndex = leftIndex + 1; rightIndex < timed.length; rightIndex += 1) {
const right = timed[rightIndex];
if (right.startMs >= left.endMs) break;
const overlapMs =
Math.min(left.endMs, right.endMs) -
Math.max(left.startMs, right.startMs);
if (overlapMs <= 0) continue;
totalDetected += 1;
if (conflicts.length < 6) {
conflicts.push({
firstEventId: left.event.id,
secondEventId: right.event.id,
firstTitle: left.event.title,
secondTitle: right.event.title,
overlapMinutes: Math.max(1, Math.round(overlapMs / 60_000)),
});
}
}
}
return {
conflicts,
summary: {
totalDetected,
retained: conflicts.length,
truncated: totalDetected > conflicts.length,
},
};
}
```
### Gather, synthesize, and deliver
The I/O stays thin. Normalization and rendering are synchronous helpers kept outside the compiled state machine, as [Coded agents](/guide/coded-agents#keep-heavy-work-in-synchronous-helpers-not-async-ones) recommends:
```ts theme={null}
async function run(input: Input, task: Task): Promise