@wildo-ai/framework-knowledge 1.1.14 → 1.1.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/creation-state.md +4 -1
  4. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  5. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  6. package/dist/esm/framework-knowledge.definitions.js +13 -0
  7. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  8. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  9. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
  10. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  11. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +6 -4
  13. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  14. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
  15. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
  16. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  17. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  18. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  19. package/dist/knowledge/manifest.json +7 -7
  20. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
  21. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
  22. package/dist/knowledge/playbooks/bottom_up.build/method.md +10 -8
  23. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +1 -1
  24. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
  25. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
  26. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
  27. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
  28. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
  29. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
  30. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +4 -0
  31. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  32. package/dist/knowledge/references/backend.inbound-handlers.definition.md +2 -1
  33. package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
  34. package/dist/knowledge/references/example.electronic-signature.engagement-letter-tool.md +54 -0
  35. package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +6 -2
  36. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +13 -2
  37. package/dist/knowledge/references/example.inbound.email-to-todo.md +33 -2
  38. package/dist/knowledge/references/example.module.relationships.discriminator.md +14 -1
  39. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
  40. package/dist/knowledge/references/integration-plan.config.md +78 -8
  41. package/dist/knowledge/references/platform.config.environment.deployment.md +27 -4
  42. package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
  43. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
  44. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
  45. package/dist/knowledge/references/saas.backend.flows-actors.decision-notice-handler.md +7 -0
  46. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +16 -0
  47. package/dist/knowledge/references/saas.backend.flows-actors.present-records-tool.md +5 -2
  48. package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +19 -0
  49. package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
  50. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +21 -0
  51. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
  52. package/dist/knowledge/references/saas.models.flows-actors.decision-card-wording.md +9 -0
  53. package/dist/knowledge/references/saas.models.flows-actors.mcp-server-declaration.md +63 -0
  54. package/dist/knowledge/references/saas.models.flows-actors.outbound-credential.md +61 -0
  55. package/dist/knowledge/references/saas.models.flows-actors.remote-agent-declaration.md +56 -0
  56. package/dist/knowledge/references/saas.models.flows.run-state.md +9 -0
  57. package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
  58. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
  59. package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
  60. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
  61. package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
  62. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  63. package/dist/knowledge/registries/framework-topics.json +55 -1
  64. package/dist/knowledge/registries/playbooks.json +2 -2
  65. package/dist/knowledge/registries/source-tags.json +1127 -1042
  66. package/dist/knowledge/skills/INDEX.md +2 -2
  67. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +20 -4
  68. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +4 -1
  69. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
  70. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
  71. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +4 -0
  72. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
  73. package/dist/knowledge/skills/config-app-shell/SKILL.md +4 -0
  74. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +3 -0
  75. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
  76. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +69 -19
  77. package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
  78. package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +32 -5
  79. package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
  80. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
  81. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
  82. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
  83. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
  84. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
  85. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +35 -3
  86. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
  87. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +16 -0
  88. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +30 -0
  89. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
  90. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-present-records-tool-api.md +5 -2
  91. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +207 -0
  92. package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-start-flow-api.md +9 -0
  93. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
  94. package/dist/knowledge/skills/human-decision-notices/SKILL.md +5 -1
  95. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-card-wording-api.md +9 -0
  96. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-notice-handler-api.md +7 -0
  97. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +2 -1
  98. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
  99. package/dist/knowledge/skills/infra-environment-config/SKILL.md +31 -9
  100. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +27 -4
  101. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
  102. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
  103. package/dist/knowledge/skills/module-relationships/SKILL.md +27 -1
  104. package/dist/knowledge/skills/provider-backend-package/SKILL.md +32 -4
  105. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
  106. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
  107. package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
  108. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
  109. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
  110. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
  111. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
  112. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
  113. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
  114. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
  115. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +21 -0
  116. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +5 -0
  117. package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +19 -0
  118. package/dist/knowledge/topic-index.json +295 -114
  119. package/dist/tsconfig.build.tsbuildinfo +1 -1
  120. package/package.json +4 -4
@@ -1,17 +1,21 @@
1
1
  # Email template ownership and artifact paths
2
2
 
3
- Locate the owning backend module's `emailTemplateDefinitions` contribution first. There is no mandatory `module-email-template-definitions.ts` filename or universal `notifications/email` root.
3
+ Locate the owning backend module's `emailTemplateDefinitions` contribution first, and keep templates where its definitions file scans.
4
+
5
+ **A business module's emails live in `backend-api/src/modules/<module>/emails/`, and nowhere else.** That folder holds the definitions file, `emails/module-email-template-definitions.ts`, which calls `scanEmailTemplateDirectory` over `resources/` (and `system/` when the module has system emails) beside it, and the template folders it scans. The module contributes the resulting map as its `emailTemplateDefinitions`. Do not create `email/`, `mail/`, `templates/` or any other folder for a module's emails, and do not put the definitions file at the module's root: the companion writes a module's generated templates, and its preview imports them, under `emails/`, so a template registered from anywhere else is generated where nothing registers it.
6
+
7
+ This is checked. In the build lane, every coding run that writes under a package's `src/modules/`, and the end-of-build checks, run `check:module-layout`, which refuses a file that calls `scanEmailTemplateDirectory` (or is named like a module email definitions file) outside `<module>/emails/`, and states the correction: the `mv` (renaming the whole folder when the folder is the misplaced unit, `mv <module>/email <module>/emails`) and every import to update. Outside the build lane, `rg -l 'scanEmailTemplateDirectory' backend-api/src/modules` must list only files under an `emails/` folder. If a module you work in registers its emails elsewhere, move them there; do not follow the misplaced layout. Write the scanner's `subdir` as a string literal and `keyFromPath` as a function returning `` `email.${…}` `` (or `` `system.${…}` ``): the companion reads both from the call to know which folder registers which refs, and writes nothing for a module whose scanner it cannot read.
4
8
 
5
9
  | Artifact | Current scanner contract |
6
10
  |---|---|
7
11
  | Authored template | `template.tsx` with a default `EmailTemplateDefinition<TLabels>` export |
8
12
  | Authored labels | Co-located `labels.<locale>.ts` with named `labels` export satisfying `TLabels` |
9
13
  | Runtime artifacts | Compiled `template.js` and `labels.<locale>.js` under the owning scanner directory |
10
- | Definition collection | `scanEmailTemplateDirectory` from `@wildo-ai/saas-backend-lib`, or the application's existing explicit map |
14
+ | Definition collection | `scanEmailTemplateDirectory` from `@wildo-ai/saas-backend-lib`, called from `<email root>/…-email-template-definitions.ts` (a business module's email root is `emails/`) |
11
15
  | Runtime wiring | Existing owning backend module contributes the resulting `emailTemplateDefinitions` map |
12
16
 
13
17
  The scanner starts beside its caller's `import.meta.url`, scans its configured `subdir` recursively and uses `keyFromPath` to derive refs. Its default extension is `.js`. It imports the template's default export and the labels module's named `labels` export (also accepts `default.labels`). It does not infer refs from a new enum or inspect an arbitrary TypeScript source folder.
14
18
 
15
- In the current skeleton, `backend-api/src/engine/email/email-template-definitions.ts` scans `system/` and `resources/`. `system/password-reset` becomes `system.password_reset`; under `resources/`, `/` becomes `.`, so an operation email for `tasks` / `assign` / target `USER_SELF` lives in `resources/tasks/assign.user-self` and registers `email.tasks.assign.user-self` (the full rule: `references/framework-operation-email-template-ref-api.md`). The engine backend module contributes the map. Business-module email definitions should follow their existing module-owned contribution rather than being moved into the engine merely to match this example.
19
+ In the current skeleton, `backend-api/src/engine/email/email-template-definitions.ts` scans `system/` and `resources/`. `system/password-reset` becomes `system.password_reset`; under `resources/`, `/` becomes `.`, so an operation email for `tasks` / `assign` / target `USER_SELF` lives in `resources/tasks/assign.user-self` and registers `email.tasks.assign.user-self` (the full rule: `references/framework-operation-email-template-ref-api.md`). The engine backend module contributes the map. That layout is the ENGINE owner's email root (`backend-api/src/engine/email/`, singular, owned by the skeleton); do not copy its folder name into a business module, whose emails live in `emails/` as stated above, and do not move a business module's emails into the engine.
16
20
 
17
- For an explicit map, follow its existing `EmailTemplateDefinitionsMap` shape and preserve its labels wiring. For a scanner, adding a correctly named/default-exported template and named locale exports under its root is the registration input; no per-template manual entry is required. In either case, normal compilation/publication and module loading must make the ref visible. Match the sender's typed identifier to the derived ref and verify through preview. Never hand-edit compiled artifacts to make a missing source registration appear fixed.
21
+ An explicit map (templates imported one by one, no scanner) cannot be read by the companion, which then generates and previews nothing for that module and says so; replace it with the scanner in `emails/` when you work in such a module. For a scanner, adding a correctly named/default-exported template and named locale exports under its root is the registration input; no per-template manual entry is required. In either case, normal compilation/publication and module loading must make the ref visible. Match the sender's typed identifier to the derived ref and verify through preview. Never hand-edit compiled artifacts to make a missing source registration appear fixed.
@@ -43,7 +43,7 @@ grep is the high-signal check.
43
43
  2. You did NOT copy the workflow into this stub or re-author it
44
44
  elsewhere — the canonical orchestrator stays the single source of
45
45
  truth.
46
- 3. The new template id appears in the registry — `rg -n "<template-id>" backend-api/src/engine/email/module-email-template-definitions.ts` returns at least one line.
46
+ 3. The new template's folder is under the email root its definitions file scans — a business module's `emails/`, which is the ONLY place a module's email definitions may live (`check:module-layout` refuses any other folder and states the move; see `email-add-template`'s `references/email-artifact-paths.md`), the engine's `backend-api/src/engine/email/` — so `ls backend-api/src/modules/<module>/emails/resources/<template-path>` (or the engine's `system/`/`resources/` equivalent) lists it. Ids are derived from that path, never written into the definitions file.
47
47
  4. No sender service imports the template module directly — `rg -n "from\s+['\"].*engine/email/<template>/template['\"]" backend-api/src/modules/<module>/` returns empty.
48
48
 
49
49
  ## Red Flags
@@ -27,7 +27,9 @@ transport — you author almost nothing:
27
27
  - **Exposure is automatic.** Every ACTOR system with an AGENTIC actor bound to an
28
28
  agent is served as one A2A skill (`skill.id === system.ref`). Build the actor
29
29
  system exactly as for the in-app assistant (`flows-actors-chat-assistant`); no
30
- per-system A2A flag.
30
+ per-system A2A flag. Give the system `tags` (the keywords another agent matches a
31
+ skill by): A2A 1.0 requires every skill to carry at least one, and a system with
32
+ none is served with its `category`, else its `ref`, as its only tag.
31
33
  - **The engine serves two endpoints**: a public agent card at
32
34
  `GET /a2a/.well-known/agent-card.json` (discovery) and the Bearer-authenticated
33
35
  JSON-RPC endpoint `POST /a2a` (`message/send` blocking, `message/stream` SSE).
@@ -64,6 +66,9 @@ scope-isolated variants.
64
66
  actor system; that skill builds the WebSocket view).
65
67
  - **Exposing resource CRUD as callable tools** to external agents → that is **MCP**
66
68
  (`operation.mcp.exposed`) — the sibling skill `resource-mcp-tool-exposure`, not A2A.
69
+ - **Your agent calling ANOTHER party's A2A agent** (the outbound direction) → declare it in
70
+ `flowsActors.remoteAgents` and name it in the agent's `remoteAgentRefs`; see
71
+ `flows-actors-chat-assistant`, `references/framework-remote-a2a-agent-declaration-api.md`.
67
72
  - **A one-shot generation agent** with no conversation → a plain `FlowsActors_Agent`
68
73
  invoked by your own service.
69
74
 
@@ -81,8 +86,8 @@ declarations in `shared-lib` themselves.)
81
86
  External agents get a token from YOUR app's OIDC provider. For **user-delegated**
82
87
  callers, the `authorizationCode` flow issues a token whose `aud` is the agent card
83
88
  `url`. For **machine** callers, provision an **OAuth client** (org- or app-scoped)
84
- and use the `clientCredentials` flow. Configure both in your auth/OIDC config;
85
- the agent card advertises whichever flows are available.
89
+ and use the `clientCredentials` flow. The agent card always advertises both, as two
90
+ security schemes (`oauth2` and `oauth2ClientCredentials`) either of which satisfies it.
86
91
 
87
92
  ### Step 3: Understand what external agents do (you do not author this)
88
93
  1. `GET /a2a/.well-known/agent-card.json` → the card (skills + `securitySchemes`).
@@ -97,6 +102,12 @@ machine turn persists to `organization`/`applicationFlowActorExecutions` (owned
97
102
  the org/app). Each is scope-isolated — a caller only ever sees its own scope's
98
103
  conversations. Nothing to author; confirm the right variant is written.
99
104
 
105
+ To let an agent that does NOT run on your machine reach a local stack (the card's `url` is your public
106
+ origin, and an outside client follows it), run `wildo local tunnel up --tunnel <machine-tunnel>
107
+ --hostname <app>-<machine>.<your-domain>`: while it runs, your issuer, audiences and card name that
108
+ HTTPS origin, only the protocol paths are forwarded, and your own browser keeps working on localhost.
109
+ Tokens minted before `up` stop working after it. `wildo local tunnel down` puts everything back.
110
+
100
111
  ### Step 5 (optional): Split the skills across NAMED agents
101
112
 
102
113
  Skip this when one agent card is enough — it is, for most apps.
@@ -269,6 +280,9 @@ const todoAssistantChatAgent: FlowsActors_Agent = {
269
280
  functionRefs: [
270
281
  TODOS_READ_TOOL_REF,
271
282
  TODO_LISTS_READ_TOOL_REF,
283
+ // A recurring todo's occurrences, by the todo's id: they are listed under their todo, which the generic read
284
+ // tool cannot address. See `./todo-occurrences-tool.ts`.
285
+ TODO_OCCURRENCES_TOOL_REF,
272
286
  TODOS_CREATE_TOOL_REF,
273
287
  TODOS_UPDATE_TOOL_REF,
274
288
  // RETRIEVAL grounding — a different KIND of source from the three above. Those return ROWS
@@ -328,6 +342,7 @@ export const moduleBackend_FlowsActorsRegistry: {
328
342
  agents: FlowsActors_Agent[];
329
343
  functionTools?: FunctionTool[];
330
344
  autonomousAgents?: FlowsActors_AutonomousAgentDeclaration[];
345
+ chatAgents?: FlowsActors_ChatAgentDeclaration[];
331
346
  } = {
332
347
  flowActorSystemsFactoryMap: {
333
348
  [TODO_ASSISTANT_SYSTEM_REF]: () => todoAssistantActorSystem,
@@ -339,6 +354,11 @@ export const moduleBackend_FlowsActorsRegistry: {
339
354
  },
340
355
  agents: [todoAssistantChatAgent, todoTriageAgent, todoDeadlineDrillAgent, todoAutoResolveAgent],
341
356
  autonomousAgents: [todosOverdueTriage, todosDeadlineDrill],
357
+ // Who answers a person who writes to the Teams bot (#2665). The Teams messages handler already converses
358
+ // (`../../inbound/teams-bot.inbound-handler.ts`), and with no chat agent declared every such message was refused.
359
+ // The todo assistant answers, as the linked member who wrote and with that member's authority, in every
360
+ // organization that chose no other agent for the connection (Settings > Chat agents).
361
+ chatAgents: [{ ref: 'todos.assistant', systemRef: TODO_ASSISTANT_SYSTEM_REF, isDefault: true }],
342
362
  // Generic engine factories instantiated per resource — every tool runs AS THE
343
363
  // CALLER (the engine rebuilds a scoped ExecutionContext from the caller's verified
344
364
  // auth; identity is never LLM-supplied) and each op's own ACL is enforced by the
@@ -430,8 +450,10 @@ export const moduleBackend_FlowsActorsRegistry: {
430
450
  // The engine's question tool (#2720): gated on the OWNER route by construction, so only the person whose turn it
431
451
  // is answers it, in the conversation or from their decision inbox.
432
452
  askPersonTool(),
433
- // The records the assistant may show as cards: the same two it reads.
434
- presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS] }),
453
+ // The records the assistant may show as cards: the same three it reads. An occurrence has no page, so its card opens
454
+ // it in an overlay over the conversation (#2776).
455
+ presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS, TasksManager_ResourceType.TODOS_RECURRING_OCCURRENCES] }),
456
+ todoOccurrencesTool,
435
457
  // The overdue-triage agent's one write, ROLE-gated to administrators (#1611). See `./reschedule-todo-tool.ts`.
436
458
  rescheduleTodoTool,
437
459
  // The deadline drill's four-minute reviewer-routed delete (#1866). See `./deadline-drill-agent.ts`.
@@ -470,8 +492,8 @@ beyond the original request; conversation history and task status are separate r
470
492
  | A send carrying a webhook (`configuration.pushNotificationConfig`; 1.0: `configuration.taskPushNotificationConfig`) | A `Task`; a blocking send waits for the turn and returns it in its latest state | The webhook is registered on that task; a streamed send carrying one is refused |
471
493
  | `configuration.blocking: false` (1.0: `configuration.returnImmediately: true`) | A `Task` with its own ID | Work continues independently of the request once the task is opened |
472
494
  | Direct `message/stream` completes | Message frames and the final reply | No background task; disconnect during generation aborts the turn |
473
- | Send or stream pauses for approval | A `Task` in `input-required`; a stream returns it in its terminal frame | The task reports the pause; the human decision uses the application's approval channel |
474
- | A message to a conversation still waiting for that decision | JSON-RPC error `-32015` (`DECISION_PENDING`) on every send mode, before any task is created; nothing runs or is written | The input the task waits for is the person's answer: wait for it, or `tasks/cancel`, which withdraws the decision. A decision raised in the instant between that check and a non-blocking turn ends the new task `failed` |
495
+ | Send or stream pauses for approval | A `Task` in `auth-required` with a status message; a stream returns it in its terminal frame | The person decides in the application, never through a message on the task (refused, `UnsupportedOperationError`); the task moves on by itself, and `tasks/cancel` withdraws the request |
496
+ | A message to a conversation still waiting for that decision | JSON-RPC error `-32015` (`DECISION_PENDING`) on every send mode, before any task is created; nothing runs or is written | The authorization the task waits for is the person's answer: wait for it, or `tasks/cancel`, which withdraws the decision. A decision raised in the instant between that check and a non-blocking turn ends the new task `failed` |
475
497
 
476
498
  These are the supported 0.2.5 request/state spellings. Other supported dialects use the corresponding
477
499
  projected names. **A request is read in the dialect of its method**: a 1.0 `SendMessage` carries parts
@@ -8,8 +8,9 @@ Read this when you need to know:
8
8
 
9
9
  - exactly what an external agent sees (skills = your agentic actor systems, keyed
10
10
  `skill.id === system.ref`);
11
- - how the card advertises auth (`securitySchemes.oauth2.flows` — `authorizationCode`
12
- for user-delegated, `clientCredentials` for machine callers);
11
+ - how the card advertises auth: two security schemes with one flow each, `oauth2`
12
+ (`authorizationCode`, user-delegated) and `oauth2ClientCredentials` (`clientCredentials`,
13
+ machine callers), listed as alternatives in `security` and `securityRequirements`;
13
14
  - what the card `url` means for audience binding (RFC 8707 / D7).
14
15
 
15
16
  ## Import Origins
@@ -45,23 +46,49 @@ export interface A2A_Skill {
45
46
  * agent's canonical audience: BOTH a USER-delegated and a MACHINE (client-credentials)
46
47
  * inbound token MUST carry it as `aud` (RFC 8707 / external-access D7) — a token minted for
47
48
  * another surface (including the generic API audience, per the 2026-07-29 flip) is rejected.
48
- * `securitySchemes.oauth2.flows`
49
- * advertises BOTH D6 principals — `authorizationCode` (user-delegated → the
50
- * conversation is owned by the delegating user) and `clientCredentials` (org/app
51
- * machine → the conversation is owned by the org/app). Tokens are minted by the
52
- * app's own OIDC provider (`/oauth/authorize`, `/oauth/token`).
49
+ * The card advertises BOTH D6 principals as TWO security schemes, one flow each:
50
+ * {@link A2A_DELEGATED_SECURITY_SCHEME} (`authorizationCode`, user-delegated → the conversation is
51
+ * owned by the delegating user) and {@link A2A_MACHINE_SECURITY_SCHEME} (`clientCredentials`, org/app
52
+ * machine → the conversation is owned by the org/app). Either satisfies the requirement. Tokens are
53
+ * minted by the app's own OIDC provider (`/oauth/authorize`, `/oauth/token`).
53
54
  */
54
55
  /**
55
- * One protocol interface this agent exposes — a URL, a transport, and the version it speaks there.
56
+ * The security scheme a USER-delegated client reads: the `authorizationCode` flow. Kept as `oauth2`, the name the card
57
+ * has always used for it.
56
58
  *
57
- * spec-cite: A2A 1.0 proto `AgentInterface` — `url` (REQUIRED), and *"The version of the A2A
58
- * protocol this interface exposes. Use the latest supported minor version per major version.
59
- * Examples: `"0.3"`, `"1.0"`"*.
59
+ * One flow per scheme because A2A 1.0 makes it so: spec-cite: A2A v1.0.0 specification/a2a.proto, `message OAuthFlows {
60
+ * oneof flow { AuthorizationCodeOAuthFlow authorization_code = 1; ClientCredentialsOAuthFlow client_credentials = 2; … } }`.
61
+ * Both flows in one scheme made the A2A reference SDK refuse the whole card (#3932).
62
+ */
63
+ export const A2A_DELEGATED_SECURITY_SCHEME = 'oauth2';
64
+ /** The security scheme a MACHINE client reads: the `clientCredentials` flow. See {@link A2A_DELEGATED_SECURITY_SCHEME}. */
65
+ export const A2A_MACHINE_SECURITY_SCHEME = 'oauth2ClientCredentials';
66
+ /**
67
+ * One protocol interface this agent exposes: a URL, the protocol binding spoken there, and the protocol version.
68
+ *
69
+ * spec-cite: A2A v1.0.0 specification/a2a.proto, `message AgentInterface { string url = 1 [REQUIRED]; string
70
+ * protocol_binding = 2 [REQUIRED]; string tenant = 3; string protocol_version = 4 [REQUIRED]; }`, serialized camelCase
71
+ * (§5.5). `protocol_binding` is "an open form string … The core ones officially supported are `JSONRPC`, `GRPC` and
72
+ * `HTTP+JSON`."
73
+ *
74
+ * These were named `transport` and `version` until 2026-11-16, names `AgentInterface` does not have, so a 1.0 client
75
+ * parsing the card read every interface with no binding and no version (#3932).
60
76
  */
61
77
  export interface A2A_AgentInterface {
62
78
  url: string;
63
- transport: string;
64
- version: string;
79
+ protocolBinding: string;
80
+ protocolVersion: string;
81
+ }
82
+
83
+ /**
84
+ * One 1.0 security requirement: the schemes it needs, each with the scopes required. The card lists alternatives, so a
85
+ * client satisfies any one entry.
86
+ *
87
+ * spec-cite: A2A v1.0.0 specification/a2a.proto, `message SecurityRequirement { map<string, StringList> schemes = 1; }`
88
+ * and `message StringList { repeated string list = 1; }`.
89
+ */
90
+ export interface A2A_SecurityRequirement {
91
+ schemes: Record<string, { list: string[] }>;
65
92
  }
66
93
 
67
94
  export interface A2A_AgentCard {
@@ -96,15 +123,22 @@ export interface A2A_AgentCard {
96
123
  defaultOutputModes: string[];
97
124
  skills: A2A_Skill[];
98
125
  securitySchemes: Record<string, unknown>;
126
+ /** The v0.2.5 requirement list (scheme name → scopes), one entry per alternative. Kept for v0.2.5 clients. */
99
127
  security: Record<string, string[]>[];
128
+ /**
129
+ * The same alternatives in the 1.0 shape. spec-cite: A2A v1.0.0 specification/a2a.proto, `AgentCard` —
130
+ * `repeated SecurityRequirement security_requirements = 9`.
131
+ */
132
+ securityRequirements: A2A_SecurityRequirement[];
100
133
  }
101
134
  ```
102
135
 
103
136
  ## The A2A task surface (`tasks/get` / `tasks/cancel`)
104
137
 
105
138
  Read this when an external agent needs to start work it will come back for. A turn that pauses
106
- for human approval also becomes a task: it reaches `input-required`, persists the decision it is
107
- waiting on, and leaves that state once its execution moves on. Both paths into a task are live,
139
+ for human approval also becomes a task: it reaches `auth-required` (the protocol's in-task
140
+ authorization, given outside the protocol), carries a status message saying a person decides in the
141
+ application, persists the decision it is waiting on, and leaves that state once its execution moves on. Both paths into a task are live,
108
142
  so an integration you build now can encounter either.
109
143
 
110
144
  The key thing to understand is **when a task exists at all** — most turns never create
@@ -133,11 +167,11 @@ one, and that is deliberate rather than a gap.
133
167
  * - the turn reached an interrupted state (a human-in-the-loop approval pause).
134
168
  *
135
169
  * All three triggers are live. The interrupted-state arm needs a runtime that can pause a turn; that
136
- * is the human-in-the-loop approval gate, and a paused turn now materialises a task carrying
137
- * `input-required` on all three transports (blocking send, non-blocking send, stream). An earlier
138
- * revision of this note warned that the arm was inert and `input-required` never emitted — true
139
- * when written, and left here in corrected form because a reader who remembers the old claim would
140
- * otherwise conclude the state is decorative and safe to drop.
170
+ * is the human-in-the-loop approval gate, and a paused turn materialises a task carrying
171
+ * `auth-required` on all three transports (blocking send, non-blocking send, stream), with a status
172
+ * message saying a person decides in the application. The task moves on by itself once they have:
173
+ * poll it, subscribe to it, or register a webhook. A message on the task does not answer the
174
+ * approval, and `tasks/cancel` withdraws it.
141
175
  *
142
176
  * A blocking turn that answers in one shot, with no webhook, returns an A2A `Message` and writes no task
143
177
  * row at all. Both shapes are protocol-conformant: the specification types the
@@ -201,7 +235,7 @@ export interface A2A_TaskSurfaceContract {
201
235
  * projection from `FlowsActors_Status` reads it, the transport emits it, and tests
202
236
  * pin it.
203
237
  *
204
- * Not every member is emitted by this transport today — `AUTH_REQUIRED` and
238
+ * Not every member is emitted by this transport today — `INPUT_REQUIRED` and
205
239
  * `REJECTED` have no `FlowsActors_Status` counterpart and are never produced. They
206
240
  * are declared because the vocabulary belongs to the protocol, not to us: a client
207
241
  * may legitimately receive them from another A2A server, and omitting them would
@@ -213,13 +247,19 @@ export enum A2A_TaskState {
213
247
  /** Actively being processed. */
214
248
  WORKING = 'working',
215
249
  /**
216
- * Interrupted (non-terminal): the agent needs input. The current transport emits this when a
217
- * user-delegated turn reaches an approval-gated tool, persists the signed pending decision and
218
- * materialises an addressable task. Approval or refusal resumes that same execution; machine
219
- * principals are denied rather than parked because no named person can answer for them.
250
+ * Interrupted (non-terminal): the agent needs more input from the client, which a follow-up message
251
+ * on the task gives. NOT emitted by this transport: a turn that answers needs no task, and an
252
+ * approval pause is {@link AUTH_REQUIRED}, because a message does not answer it.
220
253
  */
221
254
  INPUT_REQUIRED = 'input-required',
222
- /** Interrupted (non-terminal): authentication needed. NOT emitted by this transport. */
255
+ /**
256
+ * Interrupted (non-terminal): an authorization the task waits on, given outside the protocol.
257
+ * Emitted when a user-delegated turn reaches an approval-gated tool: the signed pending decision is
258
+ * persisted, an addressable task is materialised, and its status message says a person decides in
259
+ * the application. Their approval or refusal resumes that same execution, and the task moves on
260
+ * without the client sending anything. Machine principals are denied rather than parked, because
261
+ * no named person can answer for them.
262
+ */
223
263
  AUTH_REQUIRED = 'auth-required',
224
264
  /** Terminal: finished successfully. */
225
265
  COMPLETED = 'completed',
@@ -204,10 +204,14 @@ export const rescheduleTodoTool: FunctionTool = {
204
204
  argumentsResource: { resourceType: TasksManager_ResourceType.TODOS },
205
205
  description:
206
206
  'Propose a new due date for one overdue todo. An organization administrator must approve the change before '
207
- + 'it is applied. Resolve the todo id with resource.todos.read first.',
207
+ + 'it is applied. Resolve the todo id with resource.todos.read first, and give the administrator a one-sentence reason.',
208
208
  inputSchema: z.object({
209
209
  todoId: z.string().min(1).describe('Id of the todo to reschedule. Resolve it with resource.todos.read.'),
210
210
  dueDate: z.string().min(1).describe('The proposed due date, as an ISO 8601 date, e.g. "2026-10-04".'),
211
+ // Shown to the administrator who decides, and nowhere else: it is not written to the todo. Defaulted, so a call that
212
+ // leaves it out still runs, and the approval card then shows the default rather than an empty argument (#3295: an
213
+ // approver's edit is parsed, and a parse that fills a default differs from the raw input).
214
+ reason: z.string().max(280).default('No reason given.').describe('One sentence for the approving administrator: why this date.'),
211
215
  }),
212
216
  humanApproval: {
213
217
  route: HumanDecision_RouteKind.ROLE,
@@ -215,7 +219,7 @@ export const rescheduleTodoTool: FunctionTool = {
215
219
  // What the todos UPDATE it runs declares (#2526).
216
220
  riskLevel: ResourceOperationRiskLevel.LOW,
217
221
  },
218
- execute: async (args: { todoId: string; dueDate: string }, ctx: FunctionToolExecutionContext): Promise<RescheduleTodoToolResult> => {
222
+ execute: async (args: { todoId: string; dueDate: string; reason: string }, ctx: FunctionToolExecutionContext): Promise<RescheduleTodoToolResult> => {
219
223
  const dueDate = new Date(args.dueDate);
220
224
  if (Number.isNaN(dueDate.getTime())) throw new Error(`"${args.dueDate}" is not a date.`);
221
225
  await dispatchResourceOperationAsTool({
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: flows-actors-chat-assistant
3
- description: Add a conversational AI assistant to your app that answers questions grounded in your users' own resource data. Use when the user says "add a chat assistant", "add an AI assistant grounded on <resource>", "let users chat with / ask questions about their <resource>", "wire a resourceReadTool", "add a flows-actors chat agent", "expose an actor system as a chat view", "show the records as cards in the chat", "set a deadline or reminders on an approval", or "cap what the assistant spends per organization / per person" — i.e. when the intent is a conversational, tool-grounded assistant surfaced as a standalone view, NOT a one-shot generation agent or a background flow.
3
+ description: Add a conversational AI assistant to your app that answers questions grounded in your users' own resource data. Use when the user says "add a chat assistant", "add an AI assistant grounded on <resource>", "let users chat with / ask questions about their <resource>", "wire a resourceReadTool", "add a flows-actors chat agent", "expose an actor system as a chat view", "show the records as cards in the chat", "set a deadline or reminders on an approval", "let my agent delegate to another company's A2A agent", or "cap what the assistant spends per organization / per person" — i.e. when the intent is a conversational, tool-grounded assistant surfaced as a standalone view, NOT a one-shot generation agent or a background flow.
4
4
  user-invocable: false
5
5
  ---
6
6
 
@@ -187,6 +187,25 @@ A tool you **write by hand** declares how it reaches the application's data, as
187
187
  Nothing refuses a tool that declares nothing, but the application's assurance evidence reports it, because a
188
188
  tool is what an agent's authority confinement rests on.
189
189
 
190
+ **Tools from another party's MCP server.** Declare the server on the backend domain module's
191
+ `flowsActors.mcpServers` and list its `ref` in the agent's `mcpRefs` — the full contract is in
192
+ `references/framework-mcp-server-declaration-api.md`. Mind two fields: `credential.secretSlug` is the provider's
193
+ secrets-contract KEY (`accessToken`), never the env-var spelling, or a stored credential is silently missed; and write
194
+ `timeouts` out (`discoveryMs: 5_000, callMs: 30_000`). Startup refuses an `mcpRefs` entry naming no declared server, a
195
+ plaintext `http://` endpoint, a transport the runtime does not speak and a `ref` declared twice. The server's tools are
196
+ offered at turn start, except on a turn an inbound delivery started and when no credential resolves for the server's
197
+ `credential.subject`; a server that does not answer contributes none rather than failing the turn, and every call is
198
+ on the audit trail. The server's answers are another party's text: declare `contentGuardrails.promptInjection` (Step 4).
199
+
200
+ **Another party's A2A agent.** Declare it on the backend domain module's `flowsActors.remoteAgents` and list its `ref`
201
+ in the agent's `remoteAgentRefs`; the agent is offered `a2a_<ref>`, which sends a message and returns the remote
202
+ agent's answer or the task it opened, and inside a conversation `a2a_<ref>_task`, which reads or cancels such a task. The contract is in
203
+ `references/framework-remote-a2a-agent-declaration-api.md`. The tool's description is your `description`, never the
204
+ card's; the credential goes only to the `endpointUrl` you named or, without one, to the card's own host; a task id is
205
+ honoured only for a task the same conversation opened with the same credential, and anything else is refused and
206
+ recorded. The same credential, inbound-delivery and audit rules as an MCP server
207
+ apply, and so does `promptInjection`.
208
+
190
209
  ### Step 4: Declare the use, the guardrails and the approval gates
191
210
  Every agent you author — a chat assistant, a one-shot call from your code, a background agent, the agent
192
211
  step of a flow — carries three declarations. They are not options for a sensitive agent: they are what an
@@ -410,6 +429,9 @@ const todoAssistantChatAgent: FlowsActors_Agent = {
410
429
  functionRefs: [
411
430
  TODOS_READ_TOOL_REF,
412
431
  TODO_LISTS_READ_TOOL_REF,
432
+ // A recurring todo's occurrences, by the todo's id: they are listed under their todo, which the generic read
433
+ // tool cannot address. See `./todo-occurrences-tool.ts`.
434
+ TODO_OCCURRENCES_TOOL_REF,
413
435
  TODOS_CREATE_TOOL_REF,
414
436
  TODOS_UPDATE_TOOL_REF,
415
437
  // RETRIEVAL grounding — a different KIND of source from the three above. Those return ROWS
@@ -469,6 +491,7 @@ export const moduleBackend_FlowsActorsRegistry: {
469
491
  agents: FlowsActors_Agent[];
470
492
  functionTools?: FunctionTool[];
471
493
  autonomousAgents?: FlowsActors_AutonomousAgentDeclaration[];
494
+ chatAgents?: FlowsActors_ChatAgentDeclaration[];
472
495
  } = {
473
496
  flowActorSystemsFactoryMap: {
474
497
  [TODO_ASSISTANT_SYSTEM_REF]: () => todoAssistantActorSystem,
@@ -480,6 +503,11 @@ export const moduleBackend_FlowsActorsRegistry: {
480
503
  },
481
504
  agents: [todoAssistantChatAgent, todoTriageAgent, todoDeadlineDrillAgent, todoAutoResolveAgent],
482
505
  autonomousAgents: [todosOverdueTriage, todosDeadlineDrill],
506
+ // Who answers a person who writes to the Teams bot (#2665). The Teams messages handler already converses
507
+ // (`../../inbound/teams-bot.inbound-handler.ts`), and with no chat agent declared every such message was refused.
508
+ // The todo assistant answers, as the linked member who wrote and with that member's authority, in every
509
+ // organization that chose no other agent for the connection (Settings > Chat agents).
510
+ chatAgents: [{ ref: 'todos.assistant', systemRef: TODO_ASSISTANT_SYSTEM_REF, isDefault: true }],
483
511
  // Generic engine factories instantiated per resource — every tool runs AS THE
484
512
  // CALLER (the engine rebuilds a scoped ExecutionContext from the caller's verified
485
513
  // auth; identity is never LLM-supplied) and each op's own ACL is enforced by the
@@ -571,8 +599,10 @@ export const moduleBackend_FlowsActorsRegistry: {
571
599
  // The engine's question tool (#2720): gated on the OWNER route by construction, so only the person whose turn it
572
600
  // is answers it, in the conversation or from their decision inbox.
573
601
  askPersonTool(),
574
- // The records the assistant may show as cards: the same two it reads.
575
- presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS] }),
602
+ // The records the assistant may show as cards: the same three it reads. An occurrence has no page, so its card opens
603
+ // it in an overlay over the conversation (#2776).
604
+ presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS, TasksManager_ResourceType.TODOS_RECURRING_OCCURRENCES] }),
605
+ todoOccurrencesTool,
576
606
  // The overdue-triage agent's one write, ROLE-gated to administrators (#1611). See `./reschedule-todo-tool.ts`.
577
607
  rescheduleTodoTool,
578
608
  // The deadline drill's four-minute reviewer-routed delete (#1866). See `./deadline-drill-agent.ts`.
@@ -583,6 +613,8 @@ export const moduleBackend_FlowsActorsRegistry: {
583
613
 
584
614
  ## References
585
615
 
616
+ - `references/framework-remote-a2a-agent-declaration-api.md` — the `FlowsActors_RemoteAgent` declaration an agent's `remoteAgentRefs` names: the `a2a_<ref>` tool it becomes, where the credential may go, what each call does and records
617
+ - `references/framework-mcp-server-declaration-api.md` — the `FlowsActors_McpServer` declaration (transport, credential, timeouts) an agent's `mcpRefs` names
586
618
  - `references/framework-model-spend-limits-api.md` — the organization budget and the per-person ceiling every in-app turn is refused against, fail-closed, and the three unit ceilings on embeddings, document extraction and content screening: how to grant them on plans, what the person is told, what each refused call does, the `MODEL_SPEND_LIMIT_REFUSED` audit row each refusal writes, and where each one's usage is shown
587
619
  - `references/framework-tool-dispatch-obligations-api.md` — grounding an agent on resource operations, and the two controller-tier gates a HAND-WRITTEN tool must call itself
588
620
  - `references/framework-present-records-tool-api.md` — `presentRecordsTool()`: the agent shows its person records as summary cards in the conversation, kept as a reference and fetched with the viewer's session
@@ -130,6 +130,9 @@ const todoAssistantChatAgent: FlowsActors_Agent = {
130
130
  functionRefs: [
131
131
  TODOS_READ_TOOL_REF,
132
132
  TODO_LISTS_READ_TOOL_REF,
133
+ // A recurring todo's occurrences, by the todo's id: they are listed under their todo, which the generic read
134
+ // tool cannot address. See `./todo-occurrences-tool.ts`.
135
+ TODO_OCCURRENCES_TOOL_REF,
133
136
  TODOS_CREATE_TOOL_REF,
134
137
  TODOS_UPDATE_TOOL_REF,
135
138
  // RETRIEVAL grounding — a different KIND of source from the three above. Those return ROWS
@@ -189,6 +192,7 @@ export const moduleBackend_FlowsActorsRegistry: {
189
192
  agents: FlowsActors_Agent[];
190
193
  functionTools?: FunctionTool[];
191
194
  autonomousAgents?: FlowsActors_AutonomousAgentDeclaration[];
195
+ chatAgents?: FlowsActors_ChatAgentDeclaration[];
192
196
  } = {
193
197
  flowActorSystemsFactoryMap: {
194
198
  [TODO_ASSISTANT_SYSTEM_REF]: () => todoAssistantActorSystem,
@@ -200,6 +204,11 @@ export const moduleBackend_FlowsActorsRegistry: {
200
204
  },
201
205
  agents: [todoAssistantChatAgent, todoTriageAgent, todoDeadlineDrillAgent, todoAutoResolveAgent],
202
206
  autonomousAgents: [todosOverdueTriage, todosDeadlineDrill],
207
+ // Who answers a person who writes to the Teams bot (#2665). The Teams messages handler already converses
208
+ // (`../../inbound/teams-bot.inbound-handler.ts`), and with no chat agent declared every such message was refused.
209
+ // The todo assistant answers, as the linked member who wrote and with that member's authority, in every
210
+ // organization that chose no other agent for the connection (Settings > Chat agents).
211
+ chatAgents: [{ ref: 'todos.assistant', systemRef: TODO_ASSISTANT_SYSTEM_REF, isDefault: true }],
203
212
  // Generic engine factories instantiated per resource — every tool runs AS THE
204
213
  // CALLER (the engine rebuilds a scoped ExecutionContext from the caller's verified
205
214
  // auth; identity is never LLM-supplied) and each op's own ACL is enforced by the
@@ -291,8 +300,10 @@ export const moduleBackend_FlowsActorsRegistry: {
291
300
  // The engine's question tool (#2720): gated on the OWNER route by construction, so only the person whose turn it
292
301
  // is answers it, in the conversation or from their decision inbox.
293
302
  askPersonTool(),
294
- // The records the assistant may show as cards: the same two it reads.
295
- presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS] }),
303
+ // The records the assistant may show as cards: the same three it reads. An occurrence has no page, so its card opens
304
+ // it in an overlay over the conversation (#2776).
305
+ presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS, TasksManager_ResourceType.TODOS_RECURRING_OCCURRENCES] }),
306
+ todoOccurrencesTool,
296
307
  // The overdue-triage agent's one write, ROLE-gated to administrators (#1611). See `./reschedule-todo-tool.ts`.
297
308
  rescheduleTodoTool,
298
309
  // The deadline drill's four-minute reviewer-routed delete (#1866). See `./deadline-drill-agent.ts`.
@@ -514,6 +514,11 @@ export interface FunctionTool {
514
514
  * you write by hand, whose input would not read back as records.
515
515
  */
516
516
  presentsRecords?: boolean;
517
+ /**
518
+ * The resources whose records the tool SHOWS as cards. Set by {@link presentRecordsTool}; registration refuses one a card
519
+ * cannot read ({@link presentRecordsAddressabilityProblems}, #4011).
520
+ */
521
+ presentedResourceTypes?: readonly ResourceType[];
517
522
  /**
518
523
  * The resources the tool SEARCHES through the retrieval index (#2300). Set by {@link retrievalTool}; startup refuses an
519
524
  * application whose retrieval tool names a resource that declares no `.ragSource()` field, which would otherwise
@@ -1157,10 +1162,17 @@ export function functionToolDeliverableDeclarationProblems(
1157
1162
  * #2914), one sentence per problem with its remedy; empty when they are sound or absent. `declaredFieldsOf` answers the
1158
1163
  * fields the resource's main schema declares, or undefined when the resource is not registered (its fields are then not
1159
1164
  * checked here: a field the row does not hold is shown and sealed as absent).
1165
+ *
1166
+ * `systemReadAllowedOf` answers whether the resource grants the system READ (`systemAccessPolicy.read`), or undefined when
1167
+ * the resource is not registered. The card, the seal and the currency check all read the row through `readAsSystem`, which
1168
+ * refuses a resource that does not grant it, and that refusal is swallowed into "no record values": every approval then
1169
+ * seals no field and no currency check can compare anything. Measured on Wonder Ledger's live sign-off, where the declared
1170
+ * field set was sealed on none of the seals, so a declaration nothing can read stops the application here instead.
1160
1171
  */
1161
1172
  export function functionToolRecordApprovalDeclarationProblems(
1162
1173
  tool: Pick<FunctionTool, 'functionRef' | 'sealedRecordFields' | 'approvalReplacesEarlierApprovalOfRow' | 'argumentsResource' | 'requiresHumanApproval' | 'humanApproval' | 'asksThePerson'>,
1163
1174
  declaredFieldsOf?: (resourceType: string) => readonly string[] | undefined,
1175
+ systemReadAllowedOf?: (resourceType: string) => boolean | undefined,
1164
1176
  ): string[] {
1165
1177
  const fields = tool.sealedRecordFields;
1166
1178
  const replaces = tool.approvalReplacesEarlierApprovalOfRow === true;
@@ -1184,6 +1196,10 @@ export function functionToolRecordApprovalDeclarationProblems(
1184
1196
  const unknown = declared ? fields.filter((field) => !declared.includes(field)) : [];
1185
1197
  if (unknown.length > 0) problems.push(`${named}, naming ${unknown.join(', ')}, which ${tool.argumentsResource!.resourceType} does not declare.`);
1186
1198
  }
1199
+ if (tool.argumentsResource && systemReadAllowedOf?.(tool.argumentsResource.resourceType) === false) {
1200
+ problems.push(`${named}, but ${tool.argumentsResource.resourceType} does not grant the system read the approval card, the seal and the currency check `
1201
+ + `read the row through: declare systemAccessPolicy.read = ResourceSystemAccessMode.ALLOWED on it.`);
1202
+ }
1187
1203
  }
1188
1204
  return problems;
1189
1205
  }
@@ -13,6 +13,21 @@ contribution shape:
13
13
  each part draws the "not injected" placeholder (visible in development, empty in
14
14
  production) and the console warns. Import type
15
15
  from `@wildo-ai/saas-frontend-lib/companion`.
16
+ - Opening one conversation by link: link to `/conversation?system=<systemRef>&id=<executionId>&context=<contextRef>`,
17
+ the address the engine's own notices and emails use (`conversationLinkPathOf` builds it; `context` is the
18
+ conversation's stored context and may be left out). The page first switches the person to the organization the
19
+ context names, by the same rules a route uses (it says the conversation cannot be opened when the session cannot be
20
+ there). Then, when the context names a record whose resource composite declares `conversationSystemRef` for this
21
+ system, it opens that composite on that record; otherwise the FIRST `flowsActorsViews` entry with that `systemRef`
22
+ (so an assistant whose conversations people are told about needs a view, or the link says the view does not exist).
23
+ The view opens the conversation when the person's history holds it, reading it by id when it is older than the
24
+ newest page; otherwise it says it cannot be opened here and offers a new one, and nothing can be sent until that is
25
+ known. Do not link to a view's own page with a `?conversation=` parameter: on a view already open, that address is
26
+ read as a change of view state and ignored.
27
+ - A chat placed on a record (a resource composite rendering `FlowsActorsView` with the record in
28
+ `contextResourceIdentifiers`): declare `conversationSystemRef: '<systemRef>'` on that composite. Its discussions are
29
+ listed only there, so this is how a link to one finds the page; the engine then hands the linked discussion to the
30
+ `FlowsActorsView` of that system inside it, and your component passes nothing for it.
16
31
  - The backend module contribution `flowsActors` — where `flowActorSystemsFactoryMap`,
17
32
  `agents`, and **`functionTools`** are registered. (The `functionTools` field is
18
33
  the one you populate with `resourceReadTool(...)` instances.)
@@ -93,6 +108,19 @@ export interface BackendDomainModule extends SharedDomainModule {
93
108
  * `capabilities.tools.functionRefs`.
94
109
  */
95
110
  functionTools?: FunctionTool[];
111
+ /**
112
+ * Another party's MCP servers this module's agents may call (#3958): each one's endpoint and the stored provider
113
+ * connection whose credential reaches it. Reference them from an agent's `capabilities.tools.mcpRefs`. Registration
114
+ * refuses a plaintext `http://` endpoint, and every call goes through the outbound guard. See `FlowsActors_McpServer`.
115
+ */
116
+ mcpServers?: FlowsActors_McpServer[];
117
+ /**
118
+ * Another party's A2A agents this module's agents may delegate a task to (#3930): each one's card URL and the stored
119
+ * provider connection whose credential reaches it. Reference them from an agent's
120
+ * `capabilities.tools.remoteAgentRefs`. Registration refuses a plaintext `http://` card or endpoint, and every call
121
+ * goes through the outbound guard. See `FlowsActors_RemoteAgent`.
122
+ */
123
+ remoteAgents?: FlowsActors_RemoteAgent[];
96
124
  /**
97
125
  * Agents that may run with nobody on a socket — on a schedule or on an inbound delivery (#1611).
98
126
  * Declaring one grants nothing: a turn runs in an organization only while one of its OAuth clients
@@ -501,6 +529,8 @@ function mergeFlowsActors(
501
529
  ) as FlowActorSystem_InitializationFactoryMap,
502
530
  agents: modules.flatMap(m => m.flowsActors?.agents ?? []),
503
531
  functionTools: modules.flatMap(m => m.flowsActors?.functionTools ?? []),
532
+ mcpServers: modules.flatMap(m => m.flowsActors?.mcpServers ?? []),
533
+ remoteAgents: modules.flatMap(m => m.flowsActors?.remoteAgents ?? []),
504
534
  autonomousAgents: modules.flatMap(m => m.flowsActors?.autonomousAgents ?? []),
505
535
  chatAgents: modules.flatMap(m => m.flowsActors?.chatAgents ?? []),
506
536
  actorExecutionContinuations: modules.flatMap(m => m.flowsActors?.actorExecutionContinuations ?? []),