Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/api-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,7 @@ Canvas (React Flow shape; `position` and extra fields are kept for the editor):
```

Rules (the engine answers `400` with `issues` otherwise) **[tested]**:
- Node types: `trigger` (exactly one; optional `inputs` and `schedule`), `agent` (the Mind itself, `{ prompt }`), `tool` (`{ tool, args }`, `tool` = a tool key such as `near_view_account`, `add_numbers`, `get_time`), `http` (the `http_request` tool), `condition` (`left` is one reference, `op` is `eq | ne | lt | lte | gt | gte`, `right` a literal). At most 20 nodes.
- Node types: `trigger` (exactly one; optional `inputs` and `schedule`), `agent` (the Mind itself, `{ prompt }`), `tool` (`{ tool, args }`, `tool` = a tool key such as `near_view_account`, `add_numbers`, `get_time`), `http` (the `http_request` tool), `condition` (`left` is one reference, `op` is `eq | ne | lt | lte | gt | gte`, `right` a literal).. An If compares one value, never a list: every tool that returns a list of results also returns `count` (#264: `googlecalendar_list_events` `events`, `googlecalendar_find_free_time` `slots`, `gmail_list_emails` / `outlook_list_emails` `emails`, `mail_list` `messages`, `list_payments` `payments`, `get_quotes` `quotes`, `googlesheets_find_spreadsheets` `spreadsheets`, `googlesheets_read_range` `values`, `googledrive_find_files` `files`, `slack_list_channels` `channels`, `notion_search` `results`, `notion_query_database` `rows`, `zoom_list_meetings` `meetings`), so "Number of events > 0" is `{{steps.<node>.count}}` `gt` `0`; `{{steps.<node>.events.length}}` is refused with `400 invalid_workflow`. An agent step's reply is `{{steps.<node>.text}}`, compared as exact text (`"Yes"` is not `eq` `"yes"`) **[tested: `engine/test/workflows.test.ts` (count on the sample calendar takes the then way, `events.length` refused), 11 Nov; agent `text` saved and run once by hand]**. At most 20 nodes.
- Shape (#164): a tree from the trigger. Nodes are agent/tool/http steps, conditions (If) and `{ type: "end" }`. An If's `then` / `else` edges start its yes / no ways, and its edge **without** `sourceHandle` starts what comes after both ways. A way whose last step has no next step (or an empty way) carries on after its If; a way that reaches an End stops that path. Ifs may sit anywhere: in the main line, inside a way, inside a way of a way. No joins or loops (every node has one way in), End has no next step, and steps after an If whose ways both end are refused. Inside any way, `{{steps.…}}` may name steps earlier on the same path back to the trigger, never another way's. Runs stream `node.*` for every step at any depth, and the run history lists every step that ran, in order **[tested: unit, local engine runs of three paths, an engine restart, a scheduled fire in `test/autopilot.test.ts`, 10 Nov]**.
- Older shape, still accepted as is: trigger → a chain of agent/tool/http nodes → optionally one condition whose `then` edge (required) and `else` edge each lead to a chain of agent/tool/http nodes (#153; no condition inside a way, one next step per node). No cycles, no unreachable nodes. Two **one-step** ways may not need the same input with different values (e.g. two single agent ways); a way of two or more steps has its own mappings, so that limit does not apply to it. Inside a way, `{{steps.…}}` may name earlier steps of the main chain or of the same way, never the other way.
- Runs: steps inside a way stream `node.started` / `node.finished` with their own canvas node ids, like any step. The run history (`GET …/runs`) keeps a multi-step way's **final output only**, under its last node (Mastra does not keep the steps inside a nested workflow in the run snapshot) **[tested: unit, local engine run, a scheduled fire in `test/autopilot.test.ts`, 10 Nov]**.
Expand Down
1 change: 1 addition & 0 deletions engine/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ AI engine: a Mastra server that runs each Mind (soul, skills, tools, memory, sch
- **Zoom (#246, `src/zoom.ts`, skill `zoom`):** toolkit `zoom` (Composio-managed OAUTH2, `GET /api/v3/toolkits/zoom` read live 11 Nov: 92 tools, version `20261105_00`) is in `TOOLKITS` and `App`; calls go through `appCall` (try-out refused, `NoActiveConnection` → "Zoom is not connected"). Tools: `zoom_list_meetings` (`ZOOM_LIST_MEETINGS`: `user_id: "me"`, `type` `upcoming` / `previous_meetings`, `page_size: 30`; sorted by us, ids as strings, `start_url` and passcodes never returned; each meeting carries `startLocal`/`endLocal` like the calendar tools), `zoom_create_meeting` (`requireApproval` + #167 switch; `ZOOM_CREATE_A_MEETING`: `user_id: "me"`, `type: 2`, `topic`, `start_time` in GMT (`…Z`), `timezone: "UTC"` (without it Zoom uses the account's zone), `duration`, optional `agenda`; the model's `start` must match `ISO_WITH_OFFSET` and `checkOwnerOffset`; nothing else is sent, so no guests, registrants, alternative hosts or settings: the schema's `settings.meeting_invitees` is free-form objects of undocumented effect) and `zoom_meeting_summary` (read only: `ZOOM_LIST_PAST_MEETING_INSTANCES` with the numeric `meetingId`, then `ZOOM_GET_A_MEETING_SUMMARY` with an instance UUID, the first and last two instances tried, latest wins; the list's `uuid` is the fallback when the instance list fails, since the managed app's scope list has no `meeting:read:list_past_instances`; an empty `summary_content` or any refusal is `status: "none"` with `NO_SUMMARY`). `src/zoom.ts` and `src/tools.ts` import each other (time zone helpers / registry): safe only while `tools.ts` loads first. Unit tests `test/zoom.test.ts`; live prompt test `test/skills-zoom.test.ts` (fake Composio, Asia/Jakarta, a fresh user per test so working memory from the summary test can't answer the no-summary one): 3/3 runs passed on 11 Nov. Nothing seen against a real Zoom account.
- **Notion database rows (#247 item 4, `notion_query_database`, `notion_update_row` in `src/apps.ts`):** schemas read live 11 Nov with `?version=latest` (`20261101_00`). `notion_query_database` (read only, no approval) calls `NOTION_QUERY_DATABASE_WITH_FILTER` (`database_id`, Notion's own `filter` object passed through, `sorts` by property, `page_size` ≤ 50 → `results[]` Notion page objects) and returns each row as `{ id, title, url, editedAt, properties: { <name>: { type, value } } }`, values flattened to text by `notionValue` in the form the update takes (checkbox `True`/`False`, date `start` or `start/end`, multi_select `a, b`, status/select the option name); relation, rollup, files and other types are left out. `notion_update_row` (`requireApproval` and a #167 switch) takes `rowId`, `rowTitle` and `properties: [{ name, type, oldValue, newValue }]` (one list with both values per property, so the card pairs them without matching names); the playbook reads the row first and passes what it read, so the card shows old → new. `execute` re-reads the row with `NOTION_RETRIEVE_PAGE` and returns `status: "refused"` without writing if it is archived or in the trash, not a database row, its title is not `rowTitle`, a property is missing or of another type, or a value no longer matches `oldValue` (multi_select order, checkbox case and number form ignored). Then `NOTION_UPDATE_ROW_DATABASE` with `row_id`, `properties: [{ name, type, value }]` and always `delete_row: false` (that flag archives the row); `icon`/`cover` are never sent. Writable types are `notion_add_row`'s plus `status` (Notion's built-in Status property, which "mark it done" needs). An empty `newValue` is a clear: refused by `beforeApproval` (no card) and again in `execute`. Seen live (fake Composio): the model once sent `old-value`/`new-value` beside `oldValue`/`newValue`; Zod drops unknown keys before `execute`, but the card's args are the raw ones, so the FE and Telegram cards read only `oldValue`/`newValue`. Live test with a fake Composio: `test/skills-notion-update.test.ts` (due this week; mark the right one of two similar rows done; a row changed while the card waited is refused). Not tried on a real Notion database. Since 11 Nov the same checks (`rowRefusal`) also run in `beforeApproval`, so an invented row id, a wrong title or a changed value never gets a card (the full suite once saw the model pass "row-renew-domain" for `r14`).
- **Free time and moving events (#247 item 3, `googlecalendar_find_free_time` and `googlecalendar_move_event` in `src/tools.ts`, helpers in `src/calendar.ts`), in `daily-planner` and `calendar-conflicts`.** Schemas read live 11 Nov with `?version=latest`, all version `20261110_00`. **Free time** (read only, no approval): `GOOGLECALENDAR_FIND_FREE_SLOTS` (`items: ["primary"]`, `time_min`/`time_max` ISO UTC, `timezone: "UTC"` → `data.calendars.primary.busy[]`/`free[]`, `is_reliable: false` when Google could not read the calendar, which we turn into an error, never "all free"). Its `free` gaps ignore length and time of day (nights count), so `freeSlots` works out the gaps from `busy` itself: at least `minutes` (15 to 480, default 60), only between `dayStart` and `dayEnd` (default 09:00 to 18:00) on the owner's clock (`zonedInstant`, Intl offsets, settles across a clock change), from now rounded up to the quarter hour; each slot carries `startLocal`/`endLocal`. Try-outs use `sampleBusy()` from `SAMPLE_CALENDAR`, no Composio. `GOOGLECALENDAR_FREE_BUSY_QUERY` gives the same busy list and was not needed. **Moving** (`requireApproval`, a #167 switch): **`GOOGLECALENDAR_PATCH_EVENT`, not `GOOGLECALENDAR_UPDATE_EVENT`**: UPDATE replaces the whole event ("omitted fields can be cleared", and its `create_meeting_room` defaults to true, which adds a Meet link); PATCH changes only what is sent. We send only `calendar_id: "primary"`, `event_id`, `start_time`, `end_time` (RFC3339 with offset) and `send_updates: "none"`, never `attendees`, so guests stay and nobody is emailed, guests or not. Arguments `eventId`, `title` (for the card), `oldStart`/`oldEnd` (the event's `start`/`end` exactly as `googlecalendar_list_events` gave them; the card shows From and To from them), `newStart`/`newEnd` (owner's offset, `checkOwnerOffset`, 1 min to 24 h). `beforeApproval` (it gets a plain object view of the request context, wrapped by `asContext`) reads the event with `GOOGLECALENDAR_EVENTS_GET` and refuses before any card (`status: "refused"`) when the time is unchanged, the event is not at the old time (compared as instants), is cancelled or all-day, the owner is not its organizer (`organizer.self` is left out unless true), or the read fails; `execute` reads it again just before writing (a card shown a while ago, or a rule that skipped it). The result has `guests` (count) and `guestsEmailed: false` so the Mind can say the owner may want to tell them. Recurring events: the list uses `singleEvents`, so ids are instance ids and only that occurrence moves (from Google's docs on the schema, not seen live). Try-outs move a `SAMPLE_CALENDAR` event on paper (`moveSampleEvent`, refused if it is not at the old time), nothing saved. Live test with a fake Composio: `test/skills-calendar-move.test.ts` (3/3 runs on 11 Nov: list first, card with old and new time, nothing written before approve, a stale event refused on approve, free time asks nothing). Not tried against a real Google Calendar.
- **`count` on list tools (#264, `withCount` in `src/counted.ts`):** a Builder If compares one number or text, and Mastra checks its path against the step's output schema, where an array has no `length` (`stepResults.cal.events.length` → `invalid-predicate-reference`). So every tool that returns a list of results is built as `createTool(withCount('<list field>', { … }))`: `count: number` is added to its output schema and filled after `execute` from that field's length (0 when absent; a validation `{ error }` is left alone). It wraps the config before `createTool`, because `Tool` converts `outputSchema` in its constructor. New list tools must use it: `test/counted.test.ts` fails for any registry tool with a top-level array and no `count`, except the one-item and write results in `NOT_RESULT_LISTS`. An agent step's reply is `{{steps.<node>.text}}` and already works in an If, but Mastra's predicates compare exact text (`eq`, `in`); the Mind answered `Yes` to a yes/no prompt, so `eq "yes"` took the else way (11 Nov).
- **Calendar conflict check (#192, skill `calendar-conflicts`):** `get_time` + `googlecalendar_list_events` once, reports overlaps and zero-gap pairs, suggests moves (a slot from `googlecalendar_find_free_time` since #247), and changes nothing unless the owner asks: then `googlecalendar_move_event` (approval) or `googlecalendar_create_event` for a buffer. `SAMPLE_CALENDAR` has one overlap (`demo-cal-7` inside `demo-cal-3`) and one back-to-back pair (`demo-cal-4` → `demo-cal-8`).
- **Thread titles (#86, `src/titles.ts`):** on a thread's first run (no Mastra thread with that id yet), `makeTitle` asks `config.titleModel` (`z-ai/glm-5.3-flash`, the cheapest Confidential TEE chat model, through the same verified transport) for a 3 to 6 word title of the first message. It starts *before* the run, so it is usually ready when the run ends, and is sent as `thread.titled` `{ threadId, title }` after `run.finished` and before `run.verified`. It never throws: a failure or the 30 s limit means no event, and the backend keeps the first-message cut. GLM sometimes reasons ~300 tokens on a one-word message (26 s measured for "tes" on 9 Nov), so keep `titleMaxOutputTokens` and `titleTimeoutMs` generous. The title call is not part of the run's verification.
- **House style (`src/mind.ts` `WRITING_STYLE_RULE`):** every Mind's system prompt says never to use em or en dashes (a comma, colon, full stop or parentheses instead; ranges with "to" or a hyphen). Measured 9 Nov: 16 em + 12 en dashes in 5 replies before, 0 after. Keep new playbooks and templates free of them too, or the model copies them.
Expand Down
2 changes: 1 addition & 1 deletion engine/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"dev": "node --env-file=.env --import tsx src/server.ts",
"test": "node --env-file=.env --import tsx --test test/*.test.ts",
"typecheck": "tsc --noEmit",
"test:unit": "node --import tsx --test test/skills.test.ts test/templates.test.ts test/graph.test.ts test/secrets.test.ts test/verify.test.ts test/tools.test.ts test/builder.test.ts test/wallet-tools.test.ts test/email.test.ts test/composio.test.ts test/calendar.test.ts test/apps.test.ts test/titles.test.ts test/mail-tools.test.ts test/mind.test.ts test/attacks.test.ts test/auto-approve-rules.test.ts test/zoom.test.ts"
"test:unit": "node --import tsx --test test/skills.test.ts test/templates.test.ts test/graph.test.ts test/secrets.test.ts test/verify.test.ts test/tools.test.ts test/builder.test.ts test/wallet-tools.test.ts test/email.test.ts test/composio.test.ts test/calendar.test.ts test/apps.test.ts test/titles.test.ts test/mail-tools.test.ts test/mind.test.ts test/attacks.test.ts test/auto-approve-rules.test.ts test/zoom.test.ts test/counted.test.ts"
},
"dependencies": {
"@ai-sdk/openai-compatible": "3.0.82",
Expand Down
Loading
Loading