@wildo-ai/framework-knowledge 1.1.13 → 1.1.15

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 (133) 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/composites-and-the-loop.md +12 -4
  4. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +4 -0
  5. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  6. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  7. package/dist/esm/framework-knowledge.definitions.js +9 -0
  8. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  9. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  10. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
  11. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
  13. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
  14. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  15. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  16. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  17. package/dist/knowledge/manifest.json +7 -7
  18. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
  19. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
  20. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
  21. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
  22. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
  23. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
  24. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
  25. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
  26. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
  27. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
  28. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -2
  29. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  30. package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
  31. package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
  32. package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
  33. package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
  34. package/dist/knowledge/references/example.config.navigation.full.md +14 -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 +7 -1
  39. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
  40. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
  41. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
  42. package/dist/knowledge/references/integration-plan.config.md +78 -8
  43. package/dist/knowledge/references/platform.config.environment.deployment.md +84 -5
  44. package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
  45. package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
  46. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
  47. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
  48. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +11 -0
  49. package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
  50. package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
  51. package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
  52. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
  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.frontend-provider-public-config-contract.md +6 -0
  57. package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
  58. package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
  59. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
  60. package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
  61. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
  62. package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
  63. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
  64. package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
  65. package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
  66. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  67. package/dist/knowledge/registries/framework-topics.json +45 -1
  68. package/dist/knowledge/registries/playbooks.json +2 -2
  69. package/dist/knowledge/registries/source-tags.json +1175 -1107
  70. package/dist/knowledge/skills/INDEX.md +2 -2
  71. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +9 -2
  72. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
  73. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
  74. package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
  75. package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +21 -1
  76. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +15 -2
  77. package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
  78. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
  79. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
  80. package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
  81. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
  82. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
  83. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +1 -0
  84. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +15 -1
  85. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
  86. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +12 -5
  87. package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
  88. package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
  89. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
  90. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
  91. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
  92. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
  93. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
  94. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +34 -3
  95. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
  96. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +11 -0
  97. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +15 -0
  98. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
  99. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +169 -0
  100. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
  101. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
  102. package/dist/knowledge/skills/infra-environment-config/SKILL.md +39 -13
  103. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +84 -5
  104. package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
  105. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
  106. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
  107. package/dist/knowledge/skills/module-relationships/SKILL.md +20 -1
  108. package/dist/knowledge/skills/provider-backend-package/SKILL.md +13 -2
  109. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
  110. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
  111. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
  112. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
  113. package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
  114. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
  115. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
  116. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
  117. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -3
  118. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
  119. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
  120. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
  121. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
  122. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
  123. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
  124. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
  125. package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
  126. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
  127. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
  128. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
  129. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
  130. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
  131. package/dist/knowledge/topic-index.json +326 -179
  132. package/dist/tsconfig.build.tsbuildinfo +1 -1
  133. package/package.json +4 -4
@@ -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,24 @@ 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 one tool, `a2a_<ref>`, that sends a message and returns the
202
+ remote agent's answer, or the remote task still running with its ids. 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; the model
205
+ cannot continue or cancel a remote task, and one still running at `callMs` comes back with its state and ids. The same credential, inbound-delivery and audit rules as an MCP server
206
+ apply, and so does `promptInjection`.
207
+
190
208
  ### Step 4: Declare the use, the guardrails and the approval gates
191
209
  Every agent you author — a chat assistant, a one-shot call from your code, a background agent, the agent
192
210
  step of a flow — carries three declarations. They are not options for a sensitive agent: they are what an
@@ -410,6 +428,9 @@ const todoAssistantChatAgent: FlowsActors_Agent = {
410
428
  functionRefs: [
411
429
  TODOS_READ_TOOL_REF,
412
430
  TODO_LISTS_READ_TOOL_REF,
431
+ // A recurring todo's occurrences, by the todo's id: they are listed under their todo, which the generic read
432
+ // tool cannot address. See `./todo-occurrences-tool.ts`.
433
+ TODO_OCCURRENCES_TOOL_REF,
413
434
  TODOS_CREATE_TOOL_REF,
414
435
  TODOS_UPDATE_TOOL_REF,
415
436
  // RETRIEVAL grounding — a different KIND of source from the three above. Those return ROWS
@@ -469,6 +490,7 @@ export const moduleBackend_FlowsActorsRegistry: {
469
490
  agents: FlowsActors_Agent[];
470
491
  functionTools?: FunctionTool[];
471
492
  autonomousAgents?: FlowsActors_AutonomousAgentDeclaration[];
493
+ chatAgents?: FlowsActors_ChatAgentDeclaration[];
472
494
  } = {
473
495
  flowActorSystemsFactoryMap: {
474
496
  [TODO_ASSISTANT_SYSTEM_REF]: () => todoAssistantActorSystem,
@@ -480,6 +502,11 @@ export const moduleBackend_FlowsActorsRegistry: {
480
502
  },
481
503
  agents: [todoAssistantChatAgent, todoTriageAgent, todoDeadlineDrillAgent, todoAutoResolveAgent],
482
504
  autonomousAgents: [todosOverdueTriage, todosDeadlineDrill],
505
+ // Who answers a person who writes to the Teams bot (#2665). The Teams messages handler already converses
506
+ // (`../../inbound/teams-bot.inbound-handler.ts`), and with no chat agent declared every such message was refused.
507
+ // The todo assistant answers, as the linked member who wrote and with that member's authority, in every
508
+ // organization that chose no other agent for the connection (Settings > Chat agents).
509
+ chatAgents: [{ ref: 'todos.assistant', systemRef: TODO_ASSISTANT_SYSTEM_REF, isDefault: true }],
483
510
  // Generic engine factories instantiated per resource — every tool runs AS THE
484
511
  // CALLER (the engine rebuilds a scoped ExecutionContext from the caller's verified
485
512
  // auth; identity is never LLM-supplied) and each op's own ACL is enforced by the
@@ -571,8 +598,10 @@ export const moduleBackend_FlowsActorsRegistry: {
571
598
  // The engine's question tool (#2720): gated on the OWNER route by construction, so only the person whose turn it
572
599
  // is answers it, in the conversation or from their decision inbox.
573
600
  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] }),
601
+ // The records the assistant may show as cards: the same three it reads. An occurrence has no page, so its card opens
602
+ // it in an overlay over the conversation (#2776).
603
+ presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS, TasksManager_ResourceType.TODOS_RECURRING_OCCURRENCES] }),
604
+ todoOccurrencesTool,
576
605
  // The overdue-triage agent's one write, ROLE-gated to administrators (#1611). See `./reschedule-todo-tool.ts`.
577
606
  rescheduleTodoTool,
578
607
  // The deadline drill's four-minute reviewer-routed delete (#1866). See `./deadline-drill-agent.ts`.
@@ -583,6 +612,8 @@ export const moduleBackend_FlowsActorsRegistry: {
583
612
 
584
613
  ## References
585
614
 
615
+ - `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
616
+ - `references/framework-mcp-server-declaration-api.md` — the `FlowsActors_McpServer` declaration (transport, credential, timeouts) an agent's `mcpRefs` names
586
617
  - `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
618
  - `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
619
  - `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`.
@@ -1157,10 +1157,17 @@ export function functionToolDeliverableDeclarationProblems(
1157
1157
  * #2914), one sentence per problem with its remedy; empty when they are sound or absent. `declaredFieldsOf` answers the
1158
1158
  * fields the resource's main schema declares, or undefined when the resource is not registered (its fields are then not
1159
1159
  * checked here: a field the row does not hold is shown and sealed as absent).
1160
+ *
1161
+ * `systemReadAllowedOf` answers whether the resource grants the system READ (`systemAccessPolicy.read`), or undefined when
1162
+ * the resource is not registered. The card, the seal and the currency check all read the row through `readAsSystem`, which
1163
+ * refuses a resource that does not grant it, and that refusal is swallowed into "no record values": every approval then
1164
+ * seals no field and no currency check can compare anything. Measured on Wonder Ledger's live sign-off, where the declared
1165
+ * field set was sealed on none of the seals, so a declaration nothing can read stops the application here instead.
1160
1166
  */
1161
1167
  export function functionToolRecordApprovalDeclarationProblems(
1162
1168
  tool: Pick<FunctionTool, 'functionRef' | 'sealedRecordFields' | 'approvalReplacesEarlierApprovalOfRow' | 'argumentsResource' | 'requiresHumanApproval' | 'humanApproval' | 'asksThePerson'>,
1163
1169
  declaredFieldsOf?: (resourceType: string) => readonly string[] | undefined,
1170
+ systemReadAllowedOf?: (resourceType: string) => boolean | undefined,
1164
1171
  ): string[] {
1165
1172
  const fields = tool.sealedRecordFields;
1166
1173
  const replaces = tool.approvalReplacesEarlierApprovalOfRow === true;
@@ -1184,6 +1191,10 @@ export function functionToolRecordApprovalDeclarationProblems(
1184
1191
  const unknown = declared ? fields.filter((field) => !declared.includes(field)) : [];
1185
1192
  if (unknown.length > 0) problems.push(`${named}, naming ${unknown.join(', ')}, which ${tool.argumentsResource!.resourceType} does not declare.`);
1186
1193
  }
1194
+ if (tool.argumentsResource && systemReadAllowedOf?.(tool.argumentsResource.resourceType) === false) {
1195
+ problems.push(`${named}, but ${tool.argumentsResource.resourceType} does not grant the system read the approval card, the seal and the currency check `
1196
+ + `read the row through: declare systemAccessPolicy.read = ResourceSystemAccessMode.ALLOWED on it.`);
1197
+ }
1187
1198
  }
1188
1199
  return problems;
1189
1200
  }
@@ -93,6 +93,19 @@ export interface BackendDomainModule extends SharedDomainModule {
93
93
  * `capabilities.tools.functionRefs`.
94
94
  */
95
95
  functionTools?: FunctionTool[];
96
+ /**
97
+ * Another party's MCP servers this module's agents may call (#3958): each one's endpoint and the stored provider
98
+ * connection whose credential reaches it. Reference them from an agent's `capabilities.tools.mcpRefs`. Registration
99
+ * refuses a plaintext `http://` endpoint, and every call goes through the outbound guard. See `FlowsActors_McpServer`.
100
+ */
101
+ mcpServers?: FlowsActors_McpServer[];
102
+ /**
103
+ * Another party's A2A agents this module's agents may delegate a task to (#3930): each one's card URL and the stored
104
+ * provider connection whose credential reaches it. Reference them from an agent's
105
+ * `capabilities.tools.remoteAgentRefs`. Registration refuses a plaintext `http://` card or endpoint, and every call
106
+ * goes through the outbound guard. See `FlowsActors_RemoteAgent`.
107
+ */
108
+ remoteAgents?: FlowsActors_RemoteAgent[];
96
109
  /**
97
110
  * Agents that may run with nobody on a socket — on a schedule or on an inbound delivery (#1611).
98
111
  * Declaring one grants nothing: a turn runs in an organization only while one of its OAuth clients
@@ -501,6 +514,8 @@ function mergeFlowsActors(
501
514
  ) as FlowActorSystem_InitializationFactoryMap,
502
515
  agents: modules.flatMap(m => m.flowsActors?.agents ?? []),
503
516
  functionTools: modules.flatMap(m => m.flowsActors?.functionTools ?? []),
517
+ mcpServers: modules.flatMap(m => m.flowsActors?.mcpServers ?? []),
518
+ remoteAgents: modules.flatMap(m => m.flowsActors?.remoteAgents ?? []),
504
519
  autonomousAgents: modules.flatMap(m => m.flowsActors?.autonomousAgents ?? []),
505
520
  chatAgents: modules.flatMap(m => m.flowsActors?.chatAgents ?? []),
506
521
  actorExecutionContinuations: modules.flatMap(m => m.flowsActors?.actorExecutionContinuations ?? []),
@@ -0,0 +1,139 @@
1
+ # Another party's MCP server — the declaration contract
2
+
3
+ Read this when an agent should call tools from an MCP server someone else runs. It surfaces the
4
+ `FlowsActors_McpServer` you put on a backend domain module's `flowsActors.mcpServers`, and whose `ref`
5
+ an agent lists in `capabilities.tools.mcpRefs`:
6
+
7
+ - `transport` — `HTTP_STREAM` (Streamable HTTP) is the one the runtime speaks.
8
+ - `url` — the server's `https://` endpoint; startup refuses `http://`.
9
+ - `credential` — a `FlowsActors_OutboundCredential`, the stored provider connection whose token reaches the server:
10
+ `providerRef`, `secretSlug` (the provider's secrets-contract KEY, e.g. `accessToken`, never the
11
+ env-var spelling such as `VENDOR_ACCESS_TOKEN`: a wrong spelling misses a stored credential
12
+ silently), and `subject` (`USER_THEN_ORGANIZATION`, `ORGANIZATION` or `USER`).
13
+ - `timeouts` — `discoveryMs` (opening a session and listing tools, default 5 000) and `callMs` (one
14
+ tool call, default 30 000). Write them out: the type an application authors against is the parsed
15
+ one, so the defaults do not make them optional there.
16
+
17
+ ## Import Origins
18
+
19
+ - `@wildo-ai/saas-models`
20
+
21
+ ## Source Excerpts
22
+
23
+ ### Origin Package: `@wildo-ai/saas-models`
24
+
25
+ ```typescript
26
+ *
27
+ * How the runtime reaches the server.
28
+ *
29
+ * A closed vocabulary rather than a free string: the transport decides the whole connection
30
+ * lifecycle — how a session opens, whether the server can push, how a stream ends — so a value
31
+ * nobody implemented must be unrepresentable rather than discovered at the first call.
32
+ *
33
+ * STDIO is deliberately ABSENT. It launches a local subprocess, which is the coding-agent lane's
34
+ * shape and not an application's: a generated application runs in a container it does not control,
35
+ * and "the agent may spawn a process" is a different security decision from "the agent may call an
36
+ * endpoint". Adding it later is a decision, not an omission.
37
+ */
38
+ export enum FlowsActors_McpTransport {
39
+ /** Streamable HTTP — the current MCP transport for remote servers. */
40
+ HTTP_STREAM = 'http_stream',
41
+ /**
42
+ * Server-sent events — the earlier remote transport, still widely deployed. The client speaks Streamable HTTP only,
43
+ * so startup REFUSES a server declared with it (#3958) rather than failing every turn as a protocol error.
44
+ */
45
+ SSE = 'sse',
46
+ }
47
+
48
+
49
+ /**
50
+ * Bounds on a call that leaves the trust boundary.
51
+ *
52
+ * Present with defaults rather than optional-and-unbounded, because an MCP call is a REMOTE call and
53
+ * the mistake this whole issue warns against is modelling it as a second kind of local function. A
54
+ * local function cannot hang; this can, and an unbounded tool call holds a model turn open for as
55
+ * long as somebody else's server feels like it.
56
+ */
57
+ export const FlowsActors_McpServerTimeoutsSchema = z.object({
58
+ /** How long tool DISCOVERY may take before the server contributes no tools to the turn. */
59
+ discoveryMs: z.number().int().positive().default(5_000),
60
+ /** How long one tool CALL may take before it returns a typed timeout to the agent. */
61
+ callMs: z.number().int().positive().default(30_000),
62
+ });
63
+ export type FlowsActors_McpServerTimeouts = z.infer<typeof FlowsActors_McpServerTimeoutsSchema>;
64
+
65
+ export const FlowsActors_McpServerSchema = z.object({
66
+ /** The value an agent's `capabilities.tools.mcpRefs` names. Unique within an application. */
67
+ ref: z.string().min(1),
68
+ displayName: z.string().min(1),
69
+ transport: z.enum(FlowsActors_McpTransport),
70
+ /** The server's endpoint. `https` in every deployed environment; the runtime refuses plaintext. */
71
+ url: z.string().url(),
72
+ /** Which stored provider credential authorizes the calls (`FlowsActors_OutboundCredentialSchema`). */
73
+ credential: FlowsActors_OutboundCredentialSchema,
74
+ timeouts: FlowsActors_McpServerTimeoutsSchema.default({ discoveryMs: 5_000, callMs: 30_000 }),
75
+ });
76
+ export type FlowsActors_McpServer = z.infer<typeof FlowsActors_McpServerSchema>;
77
+ ```
78
+
79
+ The credential's own contract, shared with remote A2A agents:
80
+
81
+ ## Import Origins
82
+
83
+ - `@wildo-ai/saas-models`
84
+
85
+ ## Source Excerpts
86
+
87
+ ### Origin Package: `@wildo-ai/saas-models`
88
+
89
+ ```typescript
90
+ /**
91
+ * WHOSE credential the call carries.
92
+ *
93
+ * The distinction is not a preference. A tool call that reaches a third party on a user's behalf
94
+ * should be attributable to that user AT THE FAR END — that is what makes it revocable there and
95
+ * auditable by the party being called. An application-wide service identity loses that: every
96
+ * user's call looks identical to the server, and one leaked credential exposes every tenant.
97
+ */
98
+ export enum FlowsActors_OutboundCredentialSubject {
99
+ /**
100
+ * The acting user's own delegated credential, falling back to the organization's connection when
101
+ * the user has none. The default, and the reason a fallback exists at all: an agent acting for a
102
+ * user who has never connected the server would otherwise have no path, which would make every
103
+ * unattended and batch turn impossible.
104
+ */
105
+ USER_THEN_ORGANIZATION = 'user_then_organization',
106
+ /** The organization's connection only — for a server the tenant connects once on everyone's behalf. */
107
+ ORGANIZATION = 'organization',
108
+ /** The acting user's own credential only. No fallback: a user who has not connected cannot call. */
109
+ USER = 'user',
110
+ }
111
+
112
+ /**
113
+ * Which stored credential authorizes the call.
114
+ *
115
+ * `providerRef` names a provider the application has already connected, so the credential comes from
116
+ * `organizationProviderCredentials` / `userProviderCredentials` rather than from a store invented
117
+ * for one kind of call. Those exist, carry per-tenant isolation by construction, and already have the connect and
118
+ * consent flow in front of them — a second credential store for this one call shape would be a
119
+ * second thing to rotate, audit and leak.
120
+ */
121
+ export const FlowsActors_OutboundCredentialSchema = z.object({
122
+ providerRef: z.string().min(1),
123
+ /**
124
+ * The provider's `secretsContract` KEY (`accessToken`) — the one both credential resolver ports
125
+ * require, and NOT the slot's env-var spelling (`VENDOR_ACCESS_TOKEN`) the env projection names.
126
+ * Stored credentials are keyed on the key (#624), and this value reaches the stores verbatim, so a
127
+ * spelling here misses a credential that exists.
128
+ *
129
+ * DECLARED rather than derived, because it is not derivable: a provider's contract may carry
130
+ * several secrets, and which of them authorizes the endpoint is a fact about that vendor's
131
+ * deployment rather than anything the framework can compute. Guessing a conventional name would
132
+ * resolve the wrong secret silently — the resolver would find a credential, spend it, and be
133
+ * refused by the far server for a reason no log here would explain.
134
+ */
135
+ secretSlug: z.string().min(1),
136
+ subject: z.enum(FlowsActors_OutboundCredentialSubject).default(FlowsActors_OutboundCredentialSubject.USER_THEN_ORGANIZATION),
137
+ });
138
+ export type FlowsActors_OutboundCredential = z.infer<typeof FlowsActors_OutboundCredentialSchema>;
139
+ ```
@@ -0,0 +1,169 @@
1
+ # Another party's A2A agent — the declaration contract
2
+
3
+ Read this when an agent should hand a task to an agent someone else runs, over A2A 1.0. It surfaces the
4
+ `FlowsActors_RemoteAgent` you put on a backend domain module's `flowsActors.remoteAgents`, and whose `ref` an
5
+ agent lists in `capabilities.tools.remoteAgentRefs`.
6
+
7
+ What the calling agent gets:
8
+
9
+ - One tool per remote agent, named `a2a_<ref>`, described by YOUR `description` (the remote card's own text never
10
+ reaches the model). It takes one argument, `message`, and returns `{ answer, taskState?, taskId?, contextId? }`, or
11
+ `{ error, detail, taskId?, contextId? }` naming how the call failed (`refused_target`, `unreachable`, `timed_out`,
12
+ `protocol_error`, `remote_task_failed`, `remote_request_refused`, `incompatible_agent`, `rate_budget_exhausted`), with
13
+ the remote task's ids when one was opened before the failure.
14
+ - Each call is a new request: the remote agent answers it directly or opens a new task. The model cannot pass a task or
15
+ context id, so it cannot continue, read or cancel a remote task. A task still running when `callMs` elapses comes back
16
+ as an answer carrying its last-read state and ids, and keeps running there; it is never cancelled.
17
+ - A blank or missing `message` is refused before anything is sent.
18
+ - The tool is offered only when a credential resolves for `credential.subject`, never on a turn an inbound delivery
19
+ started, and never under the name of a tool already offered that turn.
20
+
21
+ What the runtime does on each call:
22
+
23
+ - Fetches the card from `cardUrl` WITHOUT the credential and keeps it for as long as its `Cache-Control` allows (five
24
+ minutes by default, one hour at most, never with `no-store` or `no-cache`). It reads the card's JSON-RPC interfaces at
25
+ protocol version 1.0 (any 1.0 patch).
26
+ - Sends the credential, as a bearer token, to one of those interfaces only: with `endpointUrl` declared, the interface
27
+ at exactly that URL, which is also the URL the credential is resolved for; without it, the card's first such
28
+ interface, and only when it is on the card's own host. A card whose interface is on another host is refused unless
29
+ you declared that interface as `endpointUrl`.
30
+ - Sends `SendMessage`, then reads the task with `GetTask` until it ends, pauses for input or `callMs` elapses. Every
31
+ JSON-RPC request carries `A2A-Version: 1.0`. Each response body is read within the same deadline and refused past a
32
+ size ceiling.
33
+ - Goes through the outbound guard, so a private, loopback or metadata address is refused before anything leaves, and
34
+ through the connection's rate budget when the credential has one.
35
+ - Records every call as an `a2a_remote_agent_call` audit row: the remote agent, the host the credential went to, the
36
+ outcome, the remote task id and state, and whose credential it spent. Never the message, never the answer.
37
+
38
+ The fields:
39
+
40
+ - `cardUrl` / `endpointUrl` — `https://` only; startup refuses `http://`. Declare `endpointUrl` when the agent's
41
+ interface is on another host than its card, or to pin which of its interfaces is used.
42
+ - `credential` — required. `secretSlug` is the provider's secrets-contract KEY (`accessToken`), never the env-var
43
+ spelling: a wrong spelling silently misses the stored credential, and the tool is then never offered.
44
+ - `timeouts` — `cardMs` (default 5 000) and `callMs` (default 60 000). Write them out: the type you author against is
45
+ the parsed one.
46
+
47
+ Startup refuses a declaration the schema refuses, a `ref` declared twice, a plaintext URL, and an agent whose
48
+ `remoteAgentRefs` names no declaration (`agent_remote_agent_ref_names_no_declared_remote_agent`).
49
+
50
+ The remote agent's answer is another party's text. Declare `contentGuardrails.promptInjection` on the calling agent,
51
+ and under `contentGuardrails.personalData` the answer reaches the model withheld whole, because nothing says which of
52
+ its words are personal data.
53
+
54
+ ## Import Origins
55
+
56
+ - `@wildo-ai/saas-models`
57
+
58
+ ## Source Excerpts
59
+
60
+ ### Origin Package: `@wildo-ai/saas-models`
61
+
62
+ ```typescript
63
+ /**
64
+ * Bounds on a call that leaves the trust boundary. Present with defaults, because a remote agent can take as long as it
65
+ * likes and an unbounded call would hold the calling agent's turn open for that long.
66
+ */
67
+ export const FlowsActors_RemoteAgentTimeoutsSchema = z.object({
68
+ /** How long fetching the remote agent's card may take. */
69
+ cardMs: z.number().int().positive().default(5_000),
70
+ /**
71
+ * How long one delegation may take, end to end: the send, then reading the task until it ends or pauses. A task still
72
+ * running at the deadline is returned to the calling agent as still running, with its ids; it is never cancelled.
73
+ */
74
+ callMs: z.number().int().positive().default(60_000),
75
+ });
76
+ export type FlowsActors_RemoteAgentTimeouts = z.infer<typeof FlowsActors_RemoteAgentTimeoutsSchema>;
77
+
78
+ /**
79
+ * Another party's A2A agent the application's agents may delegate a task to (A2A 1.0, JSON-RPC binding).
80
+ *
81
+ * The runtime fetches the agent card from `cardUrl` WITHOUT the credential and sends the credential to one of the card's
82
+ * JSON-RPC interfaces at protocol version 1.0, and only to one the application named too: with `endpointUrl` declared,
83
+ * the interface at exactly that URL; without it, the card's first such interface, and only when it is on the card's own
84
+ * host. A card cannot redirect a credential to a host the application never named.
85
+ */
86
+ export const FlowsActors_RemoteAgentSchema = z.object({
87
+ /** The value an agent's `capabilities.tools.remoteAgentRefs` names. Unique within an application. */
88
+ ref: z.string().min(1),
89
+ displayName: z.string().min(1),
90
+ /**
91
+ * What the remote agent does, in the application's words. It is the description of the tool the calling model is
92
+ * offered — the card's own description never reaches the model.
93
+ */
94
+ description: z.string().min(1),
95
+ /** Where the agent card is served, `https://` (e.g. `https://agent.example.com/.well-known/agent-card.json`). */
96
+ cardUrl: z.string().url(),
97
+ /**
98
+ * The interface URL the credential is sent to, exactly. Declare it when the agent's interface is on another host than
99
+ * its card, or to pin which of the card's interfaces is used. The credential is resolved for this URL.
100
+ */
101
+ endpointUrl: z.string().url().optional(),
102
+ /** Which stored provider credential authorizes the calls, and whose. Required: an anonymous remote agent is not admitted. */
103
+ credential: FlowsActors_OutboundCredentialSchema,
104
+ timeouts: FlowsActors_RemoteAgentTimeoutsSchema.default({ cardMs: 5_000, callMs: 60_000 }),
105
+ });
106
+ export type FlowsActors_RemoteAgent = z.infer<typeof FlowsActors_RemoteAgentSchema>;
107
+ ```
108
+
109
+ The credential's own contract, shared with MCP servers:
110
+
111
+ ## Import Origins
112
+
113
+ - `@wildo-ai/saas-models`
114
+
115
+ ## Source Excerpts
116
+
117
+ ### Origin Package: `@wildo-ai/saas-models`
118
+
119
+ ```typescript
120
+ /**
121
+ * WHOSE credential the call carries.
122
+ *
123
+ * The distinction is not a preference. A tool call that reaches a third party on a user's behalf
124
+ * should be attributable to that user AT THE FAR END — that is what makes it revocable there and
125
+ * auditable by the party being called. An application-wide service identity loses that: every
126
+ * user's call looks identical to the server, and one leaked credential exposes every tenant.
127
+ */
128
+ export enum FlowsActors_OutboundCredentialSubject {
129
+ /**
130
+ * The acting user's own delegated credential, falling back to the organization's connection when
131
+ * the user has none. The default, and the reason a fallback exists at all: an agent acting for a
132
+ * user who has never connected the server would otherwise have no path, which would make every
133
+ * unattended and batch turn impossible.
134
+ */
135
+ USER_THEN_ORGANIZATION = 'user_then_organization',
136
+ /** The organization's connection only — for a server the tenant connects once on everyone's behalf. */
137
+ ORGANIZATION = 'organization',
138
+ /** The acting user's own credential only. No fallback: a user who has not connected cannot call. */
139
+ USER = 'user',
140
+ }
141
+
142
+ /**
143
+ * Which stored credential authorizes the call.
144
+ *
145
+ * `providerRef` names a provider the application has already connected, so the credential comes from
146
+ * `organizationProviderCredentials` / `userProviderCredentials` rather than from a store invented
147
+ * for one kind of call. Those exist, carry per-tenant isolation by construction, and already have the connect and
148
+ * consent flow in front of them — a second credential store for this one call shape would be a
149
+ * second thing to rotate, audit and leak.
150
+ */
151
+ export const FlowsActors_OutboundCredentialSchema = z.object({
152
+ providerRef: z.string().min(1),
153
+ /**
154
+ * The provider's `secretsContract` KEY (`accessToken`) — the one both credential resolver ports
155
+ * require, and NOT the slot's env-var spelling (`VENDOR_ACCESS_TOKEN`) the env projection names.
156
+ * Stored credentials are keyed on the key (#624), and this value reaches the stores verbatim, so a
157
+ * spelling here misses a credential that exists.
158
+ *
159
+ * DECLARED rather than derived, because it is not derivable: a provider's contract may carry
160
+ * several secrets, and which of them authorizes the endpoint is a fact about that vendor's
161
+ * deployment rather than anything the framework can compute. Guessing a conventional name would
162
+ * resolve the wrong secret silently — the resolver would find a credential, spend it, and be
163
+ * refused by the far server for a reason no log here would explain.
164
+ */
165
+ secretSlug: z.string().min(1),
166
+ subject: z.enum(FlowsActors_OutboundCredentialSubject).default(FlowsActors_OutboundCredentialSubject.USER_THEN_ORGANIZATION),
167
+ });
168
+ export type FlowsActors_OutboundCredential = z.infer<typeof FlowsActors_OutboundCredentialSchema>;
169
+ ```
@@ -131,45 +131,36 @@ export type FlowsActors_Agent = {
131
131
  /**
132
132
  * References to MCP servers the agent may reach.
133
133
  *
134
- * ## CHECKED, NOT YET CALLABLE (#491)
134
+ * ## Checked at startup, called at turn start (#491, #3958)
135
135
  *
136
- * Each ref must name an MCP server the APPLICATION declared (`FlowsActors_McpServer`), and
137
- * `FlowsActorsRegistryService` REFUSES at initialization an agent whose refs name none. That
138
- * closes the shape this field was in: it used to resolve against nothing, so a shipped catalog
139
- * carried seven refs (`filesystem-mcp`, `git-mcp`, `browser-mcp`, `mongodb-mcp`, …) that named
140
- * no server anywhere while the agent card rendered them as capabilities — a claim shown to a
141
- * user about a reach the agent did not have. The catalog is gone and the card no longer
142
- * renders these.
136
+ * Each ref must name an MCP server the APPLICATION declared (`FlowsActors_McpServer`, on a backend domain
137
+ * module's `flowsActors.mcpServers`), and startup REFUSES an agent whose refs name none. That closes the shape
138
+ * this field was in: it used to resolve against nothing, so a shipped
139
+ * catalog carried seven refs that named no server anywhere — a claim about a reach the agent did not have.
143
140
  *
144
- * The check is deliberately stricter than `functionRefs`, which skip an unknown ref with a
145
- * debug line: an unknown `functionRef` costs an agent one tool, whereas these were presented
146
- * as a capability, and a refusal makes the old state unreachable rather than fixed once.
141
+ * The check is deliberately stricter than `functionRefs`, which skip an unknown ref with a debug line: an unknown
142
+ * `functionRef` costs an agent one tool, whereas these name another party's server.
147
143
  *
148
- * ## What is still missing before a ref becomes a CALLABLE tool
149
- *
150
- * The declaration is checkable; the call is not yet made. `AgentsBackendService` resolves
151
- * `functionRefs` and nothing else, so an agent carrying `mcpRefs` still has exactly the reach
152
- * its `functionRefs` give it.
153
- *
154
- * 1. **An MCP client.** `saas-backend-lib/src/mcp/` is the SERVER Wildo exposes to external MCP
155
- * clients. There is no client, and no MCP client SDK in any manifest.
156
- * 2. ~~A server registry~~ — BUILT. `registry.mcpServers`, declared per application.
157
- * 3. **Credential resolution at call time.** Decided 2026-09-09: the call carries the acting
158
- * user's own delegated provider credential where present and the organization's connection
159
- * otherwise, from `userProviderCredentials` / `organizationProviderCredentials` rather than
160
- * a store invented for MCP. `FlowsActors_McpCredentialSubject` records that choice per
161
- * server; nothing reads it yet.
144
+ * At turn start the agent opens a session with each named server, using the credential the server's declared
145
+ * `credential.subject` selects, and is offered the server's tools. They are withheld on a turn an inbound
146
+ * delivery started and when no credential resolves; a server that does not answer contributes no tools rather
147
+ * than failing the turn. Every tool call, and a target the outbound guard refuses, is recorded on the audit
148
+ * trail; an unreachable or slow server is logged.
149
+ */
150
+ mcpRefs: string[],
151
+ /**
152
+ * References to remote A2A agents the agent may delegate a task to (#3930).
162
153
  *
163
- * Also decided, and not yet implemented: an unreachable server contributes NO tools to a turn
164
- * rather than failing it — tools are discovered at turn start — and a call that fails mid-turn
165
- * returns a typed error the agent can reason about. Both emit an audit event, because a server
166
- * quietly unreachable for a week must be visible as that rather than as an agent that became
167
- * less capable for no stated reason.
154
+ * Each ref must name a remote agent the APPLICATION declared (`FlowsActors_RemoteAgent`, on a backend domain
155
+ * module's `flowsActors.remoteAgents`); startup REFUSES an agent whose refs name none, as for `mcpRefs`.
168
156
  *
169
- * Restoring these to any surface that presents them as a capability belongs in the same change
170
- * that makes them callable.
157
+ * At turn start the agent is offered one tool per named remote agent, described by the declaration (never by the
158
+ * remote card). A call sends the agent's message to the remote agent over A2A 1.0 with the credential the
159
+ * declaration's `credential.subject` selects, and returns the remote reply, or the remote task's state and ids
160
+ * when it is still running or waits for input. Withheld on a turn an inbound delivery started and when no
161
+ * credential resolves. Every call is recorded on the audit trail.
171
162
  */
172
- mcpRefs: string[],
163
+ remoteAgentRefs?: string[],
173
164
  },
174
165
  },
175
166
 
@@ -177,6 +177,12 @@ unconfirmed todo and never answers; a follow-up on a linked thread becomes a che
177
177
  /** The template the answer is rendered from — `emails/resources/todos/email-intake.received/`. */
178
178
  export const TODO_EMAIL_RECEIVED_TEMPLATE_REF = 'email.todos.email-intake.received';
179
179
 
180
+ /** The answer to "summary" on a linked thread — `emails/resources/todos/email-intake.summary/`. */
181
+ export const TODO_EMAIL_SUMMARY_TEMPLATE_REF = 'email.todos.email-intake.summary';
182
+
183
+ /** What a sender writes, alone, on a linked thread to receive the todo's summary PDF. */
184
+ export const TODO_EMAIL_SUMMARY_REQUEST = 'summary';
185
+
180
186
  /** The route tag of the screened address, `acme+screened@…`. */
181
187
  export const TODO_EMAIL_SCREENED_ROUTE_TAG = 'screened';
182
188
 
@@ -256,8 +262,32 @@ async function addFollowUpOnce(ctx: InboundChannelHandlerContextBase, todoId: st
256
262
  await ctx.resources.update(TasksManager_ResourceType.TODOS, todoId, { checklist: [...checklist, { label: `${label} ${marker}`, done: false }] });
257
263
  }
258
264
 
265
+ /** A follow-up whose whole text is the word {@link TODO_EMAIL_SUMMARY_REQUEST}, in any case. */
266
+ function asksForSummary(message: InboundMessage<InboundChannelKind.EMAIL>): boolean {
267
+ return (message.strippedReply ?? message.text).trim().toLowerCase() === TODO_EMAIL_SUMMARY_REQUEST;
268
+ }
269
+
270
+ /**
271
+ * Answers "summary" with the todo's generated summary PDF attached (#1856). The handler names the file; the engine
272
+ * checks it with the handler's own read (the file belongs to the organization, is servable, and the todo still holds
273
+ * it) before the reply is queued. A todo with no summary yet gets the same template, saying so.
274
+ */
275
+ async function replyWithSummary(ctx: InboundChannelHandlerContext<InboundReplyMode.THREAD>, todoId: string): Promise<void> {
276
+ const todo = await ctx.resources.read<Todos>(TasksManager_ResourceType.TODOS, todoId);
277
+ if (!todo) throw Object.assign(new Error('The todo this thread is about no longer exists'), { name: 'TodoNotFound' });
278
+ // A `z_file` value is typed as either shape (one file, or `fileIds` for a multi-file field); this field holds one.
279
+ const summary = todo.generatedSummaryPdf;
280
+ const summaryFileId = summary && 'fileId' in summary ? summary.fileId : undefined;
281
+ await ctx.reply({
282
+ templateRef: TODO_EMAIL_SUMMARY_TEMPLATE_REF,
283
+ variables: { todoTitle: todo.title, hasSummary: Boolean(summaryFileId) },
284
+ ...(summaryFileId ? { attachmentFileIds: [summaryFileId] } : {}),
285
+ });
286
+ }
287
+
259
288
  /**
260
- * What both answering handlers do: a message on a thread already linked to a todo is a follow-up; any other
289
+ * What both answering handlers do: a message on a thread already linked to a todo is a follow-up (or, when it
290
+ * reads only "summary", a request for the todo's summary PDF); any other
261
291
  * becomes a new todo, the thread is linked to it, and the sender is answered.
262
292
  */
263
293
  async function intake(
@@ -266,7 +296,8 @@ async function intake(
266
296
  ): Promise<void> {
267
297
  const linked = message.thread.linkedResource;
268
298
  if (linked?.resourceType === TasksManager_ResourceType.TODOS) {
269
- await addFollowUpOnce(ctx, linked.resourceId, message);
299
+ if (asksForSummary(message)) await replyWithSummary(ctx, linked.resourceId);
300
+ else await addFollowUpOnce(ctx, linked.resourceId, message);
270
301
  return;
271
302
  }
272
303
  const list = await resolveTargetList(ctx, message.payload.routeTag);