@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
@@ -107,6 +107,9 @@ const todoAssistantChatAgent: FlowsActors_Agent = {
107
107
  functionRefs: [
108
108
  TODOS_READ_TOOL_REF,
109
109
  TODO_LISTS_READ_TOOL_REF,
110
+ // A recurring todo's occurrences, by the todo's id: they are listed under their todo, which the generic read
111
+ // tool cannot address. See `./todo-occurrences-tool.ts`.
112
+ TODO_OCCURRENCES_TOOL_REF,
110
113
  TODOS_CREATE_TOOL_REF,
111
114
  TODOS_UPDATE_TOOL_REF,
112
115
  // RETRIEVAL grounding — a different KIND of source from the three above. Those return ROWS
@@ -166,6 +169,7 @@ export const moduleBackend_FlowsActorsRegistry: {
166
169
  agents: FlowsActors_Agent[];
167
170
  functionTools?: FunctionTool[];
168
171
  autonomousAgents?: FlowsActors_AutonomousAgentDeclaration[];
172
+ chatAgents?: FlowsActors_ChatAgentDeclaration[];
169
173
  } = {
170
174
  flowActorSystemsFactoryMap: {
171
175
  [TODO_ASSISTANT_SYSTEM_REF]: () => todoAssistantActorSystem,
@@ -177,6 +181,11 @@ export const moduleBackend_FlowsActorsRegistry: {
177
181
  },
178
182
  agents: [todoAssistantChatAgent, todoTriageAgent, todoDeadlineDrillAgent, todoAutoResolveAgent],
179
183
  autonomousAgents: [todosOverdueTriage, todosDeadlineDrill],
184
+ // Who answers a person who writes to the Teams bot (#2665). The Teams messages handler already converses
185
+ // (`../../inbound/teams-bot.inbound-handler.ts`), and with no chat agent declared every such message was refused.
186
+ // The todo assistant answers, as the linked member who wrote and with that member's authority, in every
187
+ // organization that chose no other agent for the connection (Settings > Chat agents).
188
+ chatAgents: [{ ref: 'todos.assistant', systemRef: TODO_ASSISTANT_SYSTEM_REF, isDefault: true }],
180
189
  // Generic engine factories instantiated per resource — every tool runs AS THE
181
190
  // CALLER (the engine rebuilds a scoped ExecutionContext from the caller's verified
182
191
  // auth; identity is never LLM-supplied) and each op's own ACL is enforced by the
@@ -268,8 +277,10 @@ export const moduleBackend_FlowsActorsRegistry: {
268
277
  // The engine's question tool (#2720): gated on the OWNER route by construction, so only the person whose turn it
269
278
  // is answers it, in the conversation or from their decision inbox.
270
279
  askPersonTool(),
271
- // The records the assistant may show as cards: the same two it reads.
272
- presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS] }),
280
+ // The records the assistant may show as cards: the same three it reads. An occurrence has no page, so its card opens
281
+ // it in an overlay over the conversation (#2776).
282
+ presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS, TasksManager_ResourceType.TODOS_RECURRING_OCCURRENCES] }),
283
+ todoOccurrencesTool,
273
284
  // The overdue-triage agent's one write, ROLE-gated to administrators (#1611). See `./reschedule-todo-tool.ts`.
274
285
  rescheduleTodoTool,
275
286
  // The deadline drill's four-minute reviewer-routed delete (#1866). See `./deadline-drill-agent.ts`.
@@ -7,6 +7,12 @@
7
7
  /** The template the answer is rendered from — `emails/resources/todos/email-intake.received/`. */
8
8
  export const TODO_EMAIL_RECEIVED_TEMPLATE_REF = 'email.todos.email-intake.received';
9
9
 
10
+ /** The answer to "summary" on a linked thread — `emails/resources/todos/email-intake.summary/`. */
11
+ export const TODO_EMAIL_SUMMARY_TEMPLATE_REF = 'email.todos.email-intake.summary';
12
+
13
+ /** What a sender writes, alone, on a linked thread to receive the todo's summary PDF. */
14
+ export const TODO_EMAIL_SUMMARY_REQUEST = 'summary';
15
+
10
16
  /** The route tag of the screened address, `acme+screened@…`. */
11
17
  export const TODO_EMAIL_SCREENED_ROUTE_TAG = 'screened';
12
18
 
@@ -86,8 +92,32 @@ async function addFollowUpOnce(ctx: InboundChannelHandlerContextBase, todoId: st
86
92
  await ctx.resources.update(TasksManager_ResourceType.TODOS, todoId, { checklist: [...checklist, { label: `${label} ${marker}`, done: false }] });
87
93
  }
88
94
 
95
+ /** A follow-up whose whole text is the word {@link TODO_EMAIL_SUMMARY_REQUEST}, in any case. */
96
+ function asksForSummary(message: InboundMessage<InboundChannelKind.EMAIL>): boolean {
97
+ return (message.strippedReply ?? message.text).trim().toLowerCase() === TODO_EMAIL_SUMMARY_REQUEST;
98
+ }
99
+
100
+ /**
101
+ * Answers "summary" with the todo's generated summary PDF attached (#1856). The handler names the file; the engine
102
+ * checks it with the handler's own read (the file belongs to the organization, is servable, and the todo still holds
103
+ * it) before the reply is queued. A todo with no summary yet gets the same template, saying so.
104
+ */
105
+ async function replyWithSummary(ctx: InboundChannelHandlerContext<InboundReplyMode.THREAD>, todoId: string): Promise<void> {
106
+ const todo = await ctx.resources.read<Todos>(TasksManager_ResourceType.TODOS, todoId);
107
+ if (!todo) throw Object.assign(new Error('The todo this thread is about no longer exists'), { name: 'TodoNotFound' });
108
+ // A `z_file` value is typed as either shape (one file, or `fileIds` for a multi-file field); this field holds one.
109
+ const summary = todo.generatedSummaryPdf;
110
+ const summaryFileId = summary && 'fileId' in summary ? summary.fileId : undefined;
111
+ await ctx.reply({
112
+ templateRef: TODO_EMAIL_SUMMARY_TEMPLATE_REF,
113
+ variables: { todoTitle: todo.title, hasSummary: Boolean(summaryFileId) },
114
+ ...(summaryFileId ? { attachmentFileIds: [summaryFileId] } : {}),
115
+ });
116
+ }
117
+
89
118
  /**
90
- * What both answering handlers do: a message on a thread already linked to a todo is a follow-up; any other
119
+ * What both answering handlers do: a message on a thread already linked to a todo is a follow-up (or, when it
120
+ * reads only "summary", a request for the todo's summary PDF); any other
91
121
  * becomes a new todo, the thread is linked to it, and the sender is answered.
92
122
  */
93
123
  async function intake(
@@ -96,7 +126,8 @@ async function intake(
96
126
  ): Promise<void> {
97
127
  const linked = message.thread.linkedResource;
98
128
  if (linked?.resourceType === TasksManager_ResourceType.TODOS) {
99
- await addFollowUpOnce(ctx, linked.resourceId, message);
129
+ if (asksForSummary(message)) await replyWithSummary(ctx, linked.resourceId);
130
+ else await addFollowUpOnce(ctx, linked.resourceId, message);
100
131
  return;
101
132
  }
102
133
  const list = await resolveTargetList(ctx, message.payload.routeTag);
@@ -10,9 +10,22 @@
10
10
  {
11
11
  nature: RelationshipNature.COMPOSITION,
12
12
  foreignKeyField: 'todoId',
13
+ // OPTIONAL_CONTEXT, as for tasks: an occurrence is routed under its todo (the todo page lists them) AND directly
14
+ // under its organization, `/organizations/{organizationId}/todos-recurring-occurrences/{todosRecurringOccurrenceId}`.
15
+ // A record shown by id alone needs the second: the Todo Assistant's cards (`presentRecordsTool`) know the
16
+ // organization and the record, never its todo, so with only the nested route a card read "Unavailable" (no
17
+ // endpoint) and opened nothing (#4011). Every occurrence carries its own `organizationId` (the anchor above), so the
18
+ // organization-level route is confined by tenancy like every other organization resource.
19
+ accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.OPTIONAL_CONTEXT,
13
20
  // Static discriminator: only applies when parent todo is RECURRING
14
21
  discriminator: { discriminatorField: todosRecurringTypeField, values: [Todos_RecurrenceType.RECURRING] },
15
- childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.IMMEDIATE, maxDepth: 1 } } },
22
+ // LAZY: a recurring todo gains an occurrence every time it comes due, so a daily todo's set only grows, and deleting
23
+ // it should not delete years of rows inside the request. The delete enqueues the teardown; the child-teardown job
24
+ // removes the occurrences once the delete has committed, and re-checks later if it runs first (#2586). Until then
25
+ // an occurrence may outlive its todo briefly. It is the application's one
26
+ // LAZY edge, so the boot report lists it under [dependent-lifecycle-deferred]. No subject erasure reaches it: no
27
+ // user edge composes a todo or a todo list, and a tenant purge RETAINS todos (the ORGANIZATIONS edge above).
28
+ childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.LAZY, maxDepth: 1 } } },
16
29
  // Only applies to RECURRING todos (Edge Case #2 handled in backend). LIST context is open so the
17
30
  // todo page can list a recurring todo's occurrences (#1787); occurrences declare no SEARCH.
18
31
  contextPolicy: {
@@ -43,6 +43,8 @@ export const PROVIDER_CAPABILITY_FRONTEND_CONSENT_CLASSIFICATION = Object.freeze
43
43
  SMS: SERVER_ONLY,
44
44
  // #2293: a deliverable is sent for signature from the backend; the vendor's signing page is its own, not a browser SDK.
45
45
  ELECTRONIC_SIGNATURE: SERVER_ONLY,
46
+ // The frame is the application's own engine component, not a browser module the provider loads.
47
+ EMBEDDED_ELECTRONIC_SIGNATURE: SERVER_ONLY,
46
48
  SSO_SAML: SERVER_ONLY,
47
49
  LLM_CHAT: SERVER_ONLY,
48
50
  LLM_EMBEDDINGS: SERVER_ONLY,
@@ -11,7 +11,8 @@
11
11
  ```typescript
12
12
  *
13
13
  * WHAT RUNS BESIDE THE BACKEND, and what the application reaches out to (#1495) — its workers, its
14
- * minions, the providers it binds, and the channels work arrives on (#1630).
14
+ * minions, the providers it binds, the channels work arrives on (#1630), and the needs no existing
15
+ * provider fills, each with why (#3992): the only door to authoring a new provider.
15
16
  *
16
17
  * ## Why this family exists
17
18
  *
@@ -84,16 +85,12 @@ export const INTEGRATION_PROVIDER_BINDING_SKILL_REF: Readonly<Record<ProviderBin
84
85
  */
85
86
  export const INTEGRATION_INBOUND_CHANNEL_SKILL_REF = 'inbound-channels';
86
87
 
87
- /** Stable prefixes the trusted runtime stamps; a provider supplies only the slug. */
88
- export const INTEGRATION_WORKER_REF_PREFIX = 'worker-';
89
- export const INTEGRATION_MINION_REF_PREFIX = 'minion-';
90
-
91
88
  const SlugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
92
89
  const NonEmptyStringSchema = z.string().trim().min(1);
93
90
 
94
91
  /** One worker: an HTTP-only subprocess the backend delegates to. */
95
92
  export const IntegrationWorkerPlanSchema = z.strictObject({
96
- workerRef: z.string().regex(new RegExp(`^${INTEGRATION_WORKER_REF_PREFIX}[a-z0-9]+(?:-[a-z0-9]+)*$`)),
93
+ workerRef: IntegrationWorkerRefSchema,
97
94
  runtime: z.enum(BuildPlanWorkerRuntime).systemEnum('BuildPlanWorkerRuntime'),
98
95
  /** What the backend delegates to it, and why that cannot happen inside a request. */
99
96
  purpose: NonEmptyStringSchema,
@@ -109,7 +106,7 @@ export type IntegrationWorkerPlan = z.infer<typeof IntegrationWorkerPlanSchema>;
109
106
 
110
107
  /** One minion: a cron unit that wakes itself. */
111
108
  export const IntegrationMinionPlanSchema = z.strictObject({
112
- minionRef: z.string().regex(new RegExp(`^${INTEGRATION_MINION_REF_PREFIX}[a-z0-9]+(?:-[a-z0-9]+)*$`)),
109
+ minionRef: IntegrationMinionRefSchema,
113
110
  /** What happens because time passed, and why it is not a request. */
114
111
  purpose: NonEmptyStringSchema,
115
112
  /** The named behaviours its tick performs. At least one: a minion that does nothing is a schedule with no work. */
@@ -151,6 +148,63 @@ export const IntegrationProviderBindingPlanSchema = z.strictObject({
151
148
  });
152
149
  export type IntegrationProviderBindingPlan = z.infer<typeof IntegrationProviderBindingPlanSchema>;
153
150
 
151
+ /**
152
+ * The ref of a planned WORKER or MINION (`worker-<slug>`, `minion-<slug>`): the surface that wires an unprovided need for
153
+ * itself (#3995 item 6). The prefix says which collection it names, so a worker and a minion sharing a slug stay distinct.
154
+ */
155
+ const IntegrationExecutionSurfaceRefSchema = z.string().regex(
156
+ new RegExp(`^(?:${INTEGRATION_WORKER_REF_PREFIX}|${INTEGRATION_MINION_REF_PREFIX})[a-z0-9]+(?:-[a-z0-9]+)*$`),
157
+ );
158
+
159
+ /**
160
+ * A need NO provider the framework already has fills (#3992), recorded so that a provider is authored only for a reason
161
+ * someone wrote down. App creation USES the engine's providers and the registry's modules; authoring a new one is the last
162
+ * resort (Paul, 2026-11-16), and only an entry here may become a build task that authors a provider package. A binding may
163
+ * name a provider that does not exist yet only when an entry here names it.
164
+ *
165
+ * ## Who wires it: a provider binding, or the worker or minion named by `wiredByRef` (#3995 item 6)
166
+ *
167
+ * A need reaches the build in one of two ways. Either a {@link IntegrationProviderBindingPlanSchema binding} names its
168
+ * `providerRef` on the runtime owner that needs it (backend, companion, application frontend, website), and that binding's
169
+ * task authors the provider; or {@link wiredByRef} names the planned worker or minion that alone uses it, and THAT
170
+ * surface's task authors the provider and declares it in the surface's own scope
171
+ * (`providers.scopes.workers.<key>` / `providers.scopes.minions.<key>`, which the worker and minion tasks already write).
172
+ *
173
+ * Decided by what the framework already does: a worker's or minion's provider is declared on that surface's own
174
+ * `providers` block and belongs to the task that builds it (see {@link ProviderBindingScope}), so the plan names the
175
+ * surface rather than inventing a scope for it. Rejected: adding `WORKER` and `MINION` members to `ProviderBindingScope`.
176
+ * The scope is a closed set of SINGLE owners, each with one declaration file a landing probe reads and one skill; a
177
+ * worker or minion scope is keyed per surface (`scopes.workers.<key>`), so a bare `WORKER` member would name no file and
178
+ * no surface, and carrying the key would turn every binding into a second worker-or-minion reference beside the one
179
+ * this field already is. It would also give a minion's provider a task of its own, apart from the minion that holds its
180
+ * whitelist and its schedule, which the scope's own contract forbids.
181
+ */
182
+ export const IntegrationUnprovidedNeedSchema = z.strictObject({
183
+ /**
184
+ * The ref the provider to author will have: what the binding that wires it names as its `providerRef`. The entry's
185
+ * business key, on its OWN schema instance: the workbench takes an entry's own key out of its reading, and a key sharing
186
+ * an instance with another aspect's headline (a binding is headed by its `providerRef`) would either stay printed or
187
+ * blank that headline.
188
+ */
189
+ providerRef: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
190
+ /** What the application needs from outside, in its own words — "send invoices through the client's Fortnox ledger". */
191
+ need: NonEmptyStringSchema,
192
+ /**
193
+ * Why no engine provider and no registry module fills it: a vendor none of them offers, a behaviour they lack, or a
194
+ * business obligation that names a vendor. Checked against the lists the planner was shown; "it seemed simpler" is not one.
195
+ */
196
+ whyNoExistingProvider: NonEmptyStringSchema,
197
+ /**
198
+ * The planned worker or minion that wires this provider for itself (`worker-<slug>`, `minion-<slug>`), when no other
199
+ * runtime owner uses it. Its build task then authors the provider and declares it in that surface's own scope. Absent
200
+ * when a provider binding wires it; both may be present when the surface and a runtime owner both use it.
201
+ */
202
+ wiredByRef: IntegrationExecutionSurfaceRefSchema.optional(),
203
+ /** The requirements it is accountable to. */
204
+ servesRefs: z.array(NonEmptyStringSchema).default([]),
205
+ });
206
+ export type IntegrationUnprovidedNeed = z.infer<typeof IntegrationUnprovidedNeedSchema>;
207
+
154
208
  /**
155
209
  * One channel work ARRIVES on (#1630, #3394): the application declares that messages on this channel are
156
210
  * work it acts on, which is what makes the foundation enable the channel's engine capability
@@ -172,7 +226,9 @@ export type IntegrationInboundChannelPlan = z.infer<typeof IntegrationInboundCha
172
226
  * THE integration-plan payload.
173
227
  *
174
228
  * **Artifact-family id: `integration-plan`.** Produced by `bottom_up.integration-plan`, consumed by
175
- * `bottom_up.build-decompose`, which emits one task per worker, minion, provider binding and inbound channel.
229
+ * `bottom_up.build-decompose`, which emits one task per worker, minion, provider binding and inbound channel. A binding
230
+ * whose provider is an {@link IntegrationUnprovidedNeedSchema unprovided need}, or the worker or minion such a need names
231
+ * as `wiredByRef`, is the one task that AUTHORS the provider; every other binding wires a provider that exists.
176
232
  *
177
233
  * Every collection may be EMPTY and the whole plan is still meaningful: most applications need no
178
234
  * worker and no minion, and saying so is an answer. There is no `min(1)` anywhere here, and that is
@@ -189,7 +245,16 @@ export const IntegrationPlanSchema = z.object({
189
245
  providerBindings: z.array(IntegrationProviderBindingPlanSchema).default([]),
190
246
  /** Channels work arrives on. Empty for an application no message ever reaches, which is most of them. */
191
247
  inboundChannels: z.array(IntegrationInboundChannelPlanSchema).default([]),
248
+ /** Needs no existing provider fills, each with why (#3992). Empty for nearly every application, and that is the point. */
249
+ unprovidedNeeds: z.array(IntegrationUnprovidedNeedSchema).default([]),
192
250
  }).superRefine((plan, context) => {
251
+ const unprovided = new Set<string>();
252
+ plan.unprovidedNeeds.forEach((need, index) => {
253
+ if (unprovided.has(need.providerRef)) {
254
+ context.addIssue({ code: 'custom', message: `the unprovided need ${need.providerRef} is recorded twice; one entry says why it is authored`, path: ['unprovidedNeeds', index, 'providerRef'] });
255
+ }
256
+ unprovided.add(need.providerRef);
257
+ });
193
258
  const workerRefs = new Set<string>();
194
259
  plan.workers.forEach((worker, index) => {
195
260
  if (workerRefs.has(worker.workerRef)) {
@@ -204,6 +269,11 @@ export const IntegrationPlanSchema = z.object({
204
269
  }
205
270
  minionRefs.add(minion.minionRef);
206
271
  });
272
+ // A need wired by a surface the plan does not run would be authored for nothing (#3995 item 6).
273
+ plan.unprovidedNeeds.forEach((need, index) => {
274
+ if (need.wiredByRef === undefined || workerRefs.has(need.wiredByRef) || minionRefs.has(need.wiredByRef)) return;
275
+ context.addIssue({ code: 'custom', message: `the unprovided need ${need.providerRef} is wired by ${need.wiredByRef}, which this plan neither runs as a worker nor as a minion`, path: ['unprovidedNeeds', index, 'wiredByRef'] });
276
+ });
207
277
  /*
208
278
  * One provider bound TWICE on one scope is one declaration written twice — the config carries a
209
279
  * single entry per ref per scope, so the second is either a duplicate or a disagreement, and
@@ -159,10 +159,12 @@ export function resolveDefaultLocalDataStorage(locationType: WildoLocationType):
159
159
  * HTTP rather than onto a broker. A minion is confined to its own queues there by a PostgreSQL row-level security policy;
160
160
  * MongoDB has none, so a MongoDB application's minions are refused under `SMALL` (`describeMinionsRefusedByEnvironmentServiceProfile`).
161
161
  *
162
- * ## What it does not change yet
162
+ * ## No broker
163
163
  *
164
- * The broker's provisioning: under every profile the environment still runs RabbitMQ and apps-manager still mints the
165
- * application's vhost and credentials, though a `SMALL` application's processes no longer use them. Tracked by #2303.
164
+ * Since #2303 slice D a `SMALL` environment runs no RabbitMQ at all (`environmentServiceProfileRunsMessageBroker`): neither
165
+ * lane renders it, no env file carries `RABBITMQ_*`, no runtime joins its network segment, and apps-manager (told through
166
+ * `PLATFORM_ENVIRONMENT_SERVICE_PROFILE`) initializes no admin client and mints, revokes or restores no vhost or credential.
167
+ * A `backingServices.rabbitmq` declaration beside it is refused.
166
168
  */
167
169
  export enum EnvironmentServiceProfile {
168
170
  /** Every service the environment's declarations ask for. The default when nothing is authored. */
@@ -170,7 +172,7 @@ export enum EnvironmentServiceProfile {
170
172
  /**
171
173
  * The footprint for a small deployment: no ClamAV, no immudb, no mongot
172
174
  * ({@link servicesOmittedByEnvironmentServiceProfile}), one database family, and background work on the application's
173
- * own database instead of RabbitMQ (minions only on PostgreSQL). Vector search remains available on PostgreSQL
175
+ * own database instead of RabbitMQ, which it does not run (minions only on PostgreSQL). Vector search remains available on PostgreSQL
174
176
  * (pgvector is part of the PostgreSQL image, not a separate service).
175
177
  */
176
178
  SMALL = 'small',
@@ -247,6 +249,27 @@ export function queueAdapterTypeOfEnvironmentServiceProfile(profile: Environment
247
249
  }
248
250
  }
249
251
 
252
+ /**
253
+ * Whether an environment under `profile` runs a message broker at all (#2303 slice D). Derived from
254
+ * {@link queueAdapterTypeOfEnvironmentServiceProfile}, never authored: the broker exists to carry the RabbitMQ queue, and
255
+ * under the DATABASE queue nothing in the environment uses one (the platform scheduler delivers over HTTP). Absent profile
256
+ * ⇒ {@link DEFAULT_ENVIRONMENT_SERVICE_PROFILE}.
257
+ *
258
+ * The ONE answer every broker decision reads: whether a deployment lane renders RabbitMQ, whether an env file carries
259
+ * `RABBITMQ_*`, whether apps-manager initializes its RabbitMQ admin client and mints a vhost and credentials, and whether
260
+ * a `backingServices.rabbitmq` declaration contradicts the profile. Total over the queue vocabulary through the switch
261
+ * below, so a third queue adapter must decide here whether it needs a broker.
262
+ */
263
+ export function environmentServiceProfileRunsMessageBroker(profile: EnvironmentServiceProfile | undefined): boolean {
264
+ switch (queueAdapterTypeOfEnvironmentServiceProfile(profile ?? DEFAULT_ENVIRONMENT_SERVICE_PROFILE)) {
265
+ case QueueAdapterType.RABBITMQ:
266
+ return true;
267
+ case QueueAdapterType.DATABASE:
268
+ case QueueAdapterType.MEMORY:
269
+ return false;
270
+ }
271
+ }
272
+
250
273
  /**
251
274
  * Why an application that declares minions cannot run under `profile` on `applicationDatabaseEngine`, or undefined when it
252
275
  * can (#2303).
@@ -27,6 +27,19 @@ export interface BackendDomainModule extends SharedDomainModule {
27
27
  * `capabilities.tools.functionRefs`.
28
28
  */
29
29
  functionTools?: FunctionTool[];
30
+ /**
31
+ * Another party's MCP servers this module's agents may call (#3958): each one's endpoint and the stored provider
32
+ * connection whose credential reaches it. Reference them from an agent's `capabilities.tools.mcpRefs`. Registration
33
+ * refuses a plaintext `http://` endpoint, and every call goes through the outbound guard. See `FlowsActors_McpServer`.
34
+ */
35
+ mcpServers?: FlowsActors_McpServer[];
36
+ /**
37
+ * Another party's A2A agents this module's agents may delegate a task to (#3930): each one's card URL and the stored
38
+ * provider connection whose credential reaches it. Reference them from an agent's
39
+ * `capabilities.tools.remoteAgentRefs`. Registration refuses a plaintext `http://` card or endpoint, and every call
40
+ * goes through the outbound guard. See `FlowsActors_RemoteAgent`.
41
+ */
42
+ remoteAgents?: FlowsActors_RemoteAgent[];
30
43
  /**
31
44
  * Agents that may run with nobody on a socket — on a schedule or on an inbound delivery (#1611).
32
45
  * Declaring one grants nothing: a turn runs in an organization only while one of its OAuth clients
@@ -435,6 +448,8 @@ function mergeFlowsActors(
435
448
  ) as FlowActorSystem_InitializationFactoryMap,
436
449
  agents: modules.flatMap(m => m.flowsActors?.agents ?? []),
437
450
  functionTools: modules.flatMap(m => m.flowsActors?.functionTools ?? []),
451
+ mcpServers: modules.flatMap(m => m.flowsActors?.mcpServers ?? []),
452
+ remoteAgents: modules.flatMap(m => m.flowsActors?.remoteAgents ?? []),
438
453
  autonomousAgents: modules.flatMap(m => m.flowsActors?.autonomousAgents ?? []),
439
454
  chatAgents: modules.flatMap(m => m.flowsActors?.chatAgents ?? []),
440
455
  actorExecutionContinuations: modules.flatMap(m => m.flowsActors?.actorExecutionContinuations ?? []),
@@ -33,23 +33,49 @@ export interface A2A_Skill {
33
33
  * agent's canonical audience: BOTH a USER-delegated and a MACHINE (client-credentials)
34
34
  * inbound token MUST carry it as `aud` (RFC 8707 / external-access D7) — a token minted for
35
35
  * another surface (including the generic API audience, per the 2026-07-29 flip) is rejected.
36
- * `securitySchemes.oauth2.flows`
37
- * advertises BOTH D6 principals — `authorizationCode` (user-delegated → the
38
- * conversation is owned by the delegating user) and `clientCredentials` (org/app
39
- * machine → the conversation is owned by the org/app). Tokens are minted by the
40
- * app's own OIDC provider (`/oauth/authorize`, `/oauth/token`).
36
+ * The card advertises BOTH D6 principals as TWO security schemes, one flow each:
37
+ * {@link A2A_DELEGATED_SECURITY_SCHEME} (`authorizationCode`, user-delegated → the conversation is
38
+ * owned by the delegating user) and {@link A2A_MACHINE_SECURITY_SCHEME} (`clientCredentials`, org/app
39
+ * machine → the conversation is owned by the org/app). Either satisfies the requirement. Tokens are
40
+ * minted by the app's own OIDC provider (`/oauth/authorize`, `/oauth/token`).
41
41
  */
42
42
  /**
43
- * One protocol interface this agent exposes — a URL, a transport, and the version it speaks there.
43
+ * The security scheme a USER-delegated client reads: the `authorizationCode` flow. Kept as `oauth2`, the name the card
44
+ * has always used for it.
44
45
  *
45
- * spec-cite: A2A 1.0 proto `AgentInterface` — `url` (REQUIRED), and *"The version of the A2A
46
- * protocol this interface exposes. Use the latest supported minor version per major version.
47
- * Examples: `"0.3"`, `"1.0"`"*.
46
+ * One flow per scheme because A2A 1.0 makes it so: spec-cite: A2A v1.0.0 specification/a2a.proto, `message OAuthFlows {
47
+ * oneof flow { AuthorizationCodeOAuthFlow authorization_code = 1; ClientCredentialsOAuthFlow client_credentials = 2; … } }`.
48
+ * Both flows in one scheme made the A2A reference SDK refuse the whole card (#3932).
49
+ */
50
+ export const A2A_DELEGATED_SECURITY_SCHEME = 'oauth2';
51
+ /** The security scheme a MACHINE client reads: the `clientCredentials` flow. See {@link A2A_DELEGATED_SECURITY_SCHEME}. */
52
+ export const A2A_MACHINE_SECURITY_SCHEME = 'oauth2ClientCredentials';
53
+ /**
54
+ * One protocol interface this agent exposes: a URL, the protocol binding spoken there, and the protocol version.
55
+ *
56
+ * spec-cite: A2A v1.0.0 specification/a2a.proto, `message AgentInterface { string url = 1 [REQUIRED]; string
57
+ * protocol_binding = 2 [REQUIRED]; string tenant = 3; string protocol_version = 4 [REQUIRED]; }`, serialized camelCase
58
+ * (§5.5). `protocol_binding` is "an open form string … The core ones officially supported are `JSONRPC`, `GRPC` and
59
+ * `HTTP+JSON`."
60
+ *
61
+ * These were named `transport` and `version` until 2026-11-16, names `AgentInterface` does not have, so a 1.0 client
62
+ * parsing the card read every interface with no binding and no version (#3932).
48
63
  */
49
64
  export interface A2A_AgentInterface {
50
65
  url: string;
51
- transport: string;
52
- version: string;
66
+ protocolBinding: string;
67
+ protocolVersion: string;
68
+ }
69
+
70
+ /**
71
+ * One 1.0 security requirement: the schemes it needs, each with the scopes required. The card lists alternatives, so a
72
+ * client satisfies any one entry.
73
+ *
74
+ * spec-cite: A2A v1.0.0 specification/a2a.proto, `message SecurityRequirement { map<string, StringList> schemes = 1; }`
75
+ * and `message StringList { repeated string list = 1; }`.
76
+ */
77
+ export interface A2A_SecurityRequirement {
78
+ schemes: Record<string, { list: string[] }>;
53
79
  }
54
80
 
55
81
  export interface A2A_AgentCard {
@@ -84,6 +110,12 @@ export interface A2A_AgentCard {
84
110
  defaultOutputModes: string[];
85
111
  skills: A2A_Skill[];
86
112
  securitySchemes: Record<string, unknown>;
113
+ /** The v0.2.5 requirement list (scheme name → scopes), one entry per alternative. Kept for v0.2.5 clients. */
87
114
  security: Record<string, string[]>[];
115
+ /**
116
+ * The same alternatives in the 1.0 shape. spec-cite: A2A v1.0.0 specification/a2a.proto, `AgentCard` —
117
+ * `repeated SecurityRequirement security_requirements = 9`.
118
+ */
119
+ securityRequirements: A2A_SecurityRequirement[];
88
120
  }
89
121
  ```
@@ -23,11 +23,11 @@
23
23
  * - the turn reached an interrupted state (a human-in-the-loop approval pause).
24
24
  *
25
25
  * All three triggers are live. The interrupted-state arm needs a runtime that can pause a turn; that
26
- * is the human-in-the-loop approval gate, and a paused turn now materialises a task carrying
27
- * `input-required` on all three transports (blocking send, non-blocking send, stream). An earlier
28
- * revision of this note warned that the arm was inert and `input-required` never emitted — true
29
- * when written, and left here in corrected form because a reader who remembers the old claim would
30
- * otherwise conclude the state is decorative and safe to drop.
26
+ * is the human-in-the-loop approval gate, and a paused turn materialises a task carrying
27
+ * `auth-required` on all three transports (blocking send, non-blocking send, stream), with a status
28
+ * message saying a person decides in the application. The task moves on by itself once they have:
29
+ * poll it, subscribe to it, or register a webhook. A message on the task does not answer the
30
+ * approval, and `tasks/cancel` withdraws it.
31
31
  *
32
32
  * A blocking turn that answers in one shot, with no webhook, returns an A2A `Message` and writes no task
33
33
  * row at all. Both shapes are protocol-conformant: the specification types the
@@ -91,7 +91,7 @@ export interface A2A_TaskSurfaceContract {
91
91
  * projection from `FlowsActors_Status` reads it, the transport emits it, and tests
92
92
  * pin it.
93
93
  *
94
- * Not every member is emitted by this transport today — `AUTH_REQUIRED` and
94
+ * Not every member is emitted by this transport today — `INPUT_REQUIRED` and
95
95
  * `REJECTED` have no `FlowsActors_Status` counterpart and are never produced. They
96
96
  * are declared because the vocabulary belongs to the protocol, not to us: a client
97
97
  * may legitimately receive them from another A2A server, and omitting them would
@@ -103,13 +103,19 @@ export enum A2A_TaskState {
103
103
  /** Actively being processed. */
104
104
  WORKING = 'working',
105
105
  /**
106
- * Interrupted (non-terminal): the agent needs input. The current transport emits this when a
107
- * user-delegated turn reaches an approval-gated tool, persists the signed pending decision and
108
- * materialises an addressable task. Approval or refusal resumes that same execution; machine
109
- * principals are denied rather than parked because no named person can answer for them.
106
+ * Interrupted (non-terminal): the agent needs more input from the client, which a follow-up message
107
+ * on the task gives. NOT emitted by this transport: a turn that answers needs no task, and an
108
+ * approval pause is {@link AUTH_REQUIRED}, because a message does not answer it.
110
109
  */
111
110
  INPUT_REQUIRED = 'input-required',
112
- /** Interrupted (non-terminal): authentication needed. NOT emitted by this transport. */
111
+ /**
112
+ * Interrupted (non-terminal): an authorization the task waits on, given outside the protocol.
113
+ * Emitted when a user-delegated turn reaches an approval-gated tool: the signed pending decision is
114
+ * persisted, an addressable task is materialised, and its status message says a person decides in
115
+ * the application. Their approval or refusal resumes that same execution, and the task moves on
116
+ * without the client sending anything. Machine principals are denied rather than parked, because
117
+ * no named person can answer for them.
118
+ */
113
119
  AUTH_REQUIRED = 'auth-required',
114
120
  /** Terminal: finished successfully. */
115
121
  COMPLETED = 'completed',
@@ -200,6 +200,13 @@ export interface HumanDecisionNoticeContext {
200
200
  * `language` from the application's labels. A missing label shows its key.
201
201
  */
202
202
  readonly words: HumanDecisionNoticeWords;
203
+ /**
204
+ * The decision's address in the application's Decisions inbox (the frontend's public URL and the inbox path), for the
205
+ * link a card carries: a decision that asks fields, or has more options than a card shows, is answered there, so its
206
+ * card is that link alone (the Slack and Teams helpers' `openInApplication`). `undefined` in a process that knows no
207
+ * frontend it can name: post no link then, rather than invent one.
208
+ */
209
+ readonly decisionUrl: (decisionRef: string) => string | undefined;
203
210
  }
204
211
 
205
212
  /** The retry an application may tune. */
@@ -329,6 +329,11 @@ export interface FunctionTool {
329
329
  * you write by hand, whose input would not read back as records.
330
330
  */
331
331
  presentsRecords?: boolean;
332
+ /**
333
+ * The resources whose records the tool SHOWS as cards. Set by {@link presentRecordsTool}; registration refuses one a card
334
+ * cannot read ({@link presentRecordsAddressabilityProblems}, #4011).
335
+ */
336
+ presentedResourceTypes?: readonly ResourceType[];
332
337
  /**
333
338
  * The resources the tool SEARCHES through the retrieval index (#2300). Set by {@link retrievalTool}; startup refuses an
334
339
  * application whose retrieval tool names a resource that declares no `.ragSource()` field, which would otherwise
@@ -972,10 +977,17 @@ export function functionToolDeliverableDeclarationProblems(
972
977
  * #2914), one sentence per problem with its remedy; empty when they are sound or absent. `declaredFieldsOf` answers the
973
978
  * fields the resource's main schema declares, or undefined when the resource is not registered (its fields are then not
974
979
  * checked here: a field the row does not hold is shown and sealed as absent).
980
+ *
981
+ * `systemReadAllowedOf` answers whether the resource grants the system READ (`systemAccessPolicy.read`), or undefined when
982
+ * the resource is not registered. The card, the seal and the currency check all read the row through `readAsSystem`, which
983
+ * refuses a resource that does not grant it, and that refusal is swallowed into "no record values": every approval then
984
+ * seals no field and no currency check can compare anything. Measured on Wonder Ledger's live sign-off, where the declared
985
+ * field set was sealed on none of the seals, so a declaration nothing can read stops the application here instead.
975
986
  */
976
987
  export function functionToolRecordApprovalDeclarationProblems(
977
988
  tool: Pick<FunctionTool, 'functionRef' | 'sealedRecordFields' | 'approvalReplacesEarlierApprovalOfRow' | 'argumentsResource' | 'requiresHumanApproval' | 'humanApproval' | 'asksThePerson'>,
978
989
  declaredFieldsOf?: (resourceType: string) => readonly string[] | undefined,
990
+ systemReadAllowedOf?: (resourceType: string) => boolean | undefined,
979
991
  ): string[] {
980
992
  const fields = tool.sealedRecordFields;
981
993
  const replaces = tool.approvalReplacesEarlierApprovalOfRow === true;
@@ -999,6 +1011,10 @@ export function functionToolRecordApprovalDeclarationProblems(
999
1011
  const unknown = declared ? fields.filter((field) => !declared.includes(field)) : [];
1000
1012
  if (unknown.length > 0) problems.push(`${named}, naming ${unknown.join(', ')}, which ${tool.argumentsResource!.resourceType} does not declare.`);
1001
1013
  }
1014
+ if (tool.argumentsResource && systemReadAllowedOf?.(tool.argumentsResource.resourceType) === false) {
1015
+ problems.push(`${named}, but ${tool.argumentsResource.resourceType} does not grant the system read the approval card, the seal and the currency check `
1016
+ + `read the row through: declare systemAccessPolicy.read = ResourceSystemAccessMode.ALLOWED on it.`);
1017
+ }
1002
1018
  }
1003
1019
  return problems;
1004
1020
  }
@@ -43,8 +43,10 @@ export const PRESENT_RECORDS_FUNCTION_REF = 'engine.present-records';
43
43
  * conversation's text only), so it reads a record again before acting on it.
44
44
  *
45
45
  * `resourceTypes` are the resources the agent may show. Grant only resources it can already read. Each needs a READ
46
- * operation reachable over HTTP, and its summary is the resource's authored summary layout, else the engine's default
47
- * from its summary fields.
46
+ * operation reachable over HTTP by the record's id and its tenancy alone, since a card knows no parent of its record:
47
+ * a resource routed only under a parent (`REQUIRES_CONTEXT`) is refused at startup, so route it under its tenancy too
48
+ * with `accessScopeStrategy: OPTIONAL_CONTEXT` on the parent edge. Its summary is the resource's authored summary
49
+ * layout, else the engine's default from its summary fields.
48
50
  *
49
51
  * Import path: `@wildo-ai/saas-backend-lib`.
50
52
  *
@@ -73,6 +75,7 @@ export function presentRecordsTool(options: {
73
75
  }),
74
76
  effect: FunctionToolEffect.READ,
75
77
  presentsRecords: true,
78
+ presentedResourceTypes: resourceTypes,
76
79
  personalDataOutput: { kind: FunctionToolPersonalDataOutputKind.NOT_FROM_RECORDS, reason: 'It returns which record ids were shown or unavailable, never their fields.' },
77
80
  authority: { kind: FunctionToolAuthorityKind.PRINCIPAL_RESOURCE_OPERATION },
78
81
  execute: async (args: PresentRecords_ToolInput, ctx: FunctionToolExecutionContext): Promise<PresentRecords_ToolResult> => {
@@ -122,6 +122,20 @@ export interface ResourceCompositeViewAuthoringConfig extends CompositeViewAutho
122
122
  * silently.
123
123
  */
124
124
  operationLike?: CoreResourceOperation;
125
+ /**
126
+ * The actor system whose conversations this view hosts ON ITS RECORD (#4043): the `systemRef` of the
127
+ * `FlowsActorsView` it renders with the record in that view's context.
128
+ *
129
+ * A conversation opened on a record is listed only there, so a link to it (a notice, an email: the
130
+ * conversation-link page) must open THIS view on that record rather than the system's standalone view, which
131
+ * lists another context. Declaring the system is what lets the engine find this view from a conversation, and it
132
+ * hands the linked conversation to the `FlowsActorsView` of that system inside it — the view's component passes
133
+ * nothing for it.
134
+ *
135
+ * Omitted when the view hosts no conversation. Resource composites only: an application-level view has no record,
136
+ * so its conversations are the standalone view's.
137
+ */
138
+ conversationSystemRef?: string;
125
139
  }
126
140
 
127
141
  export interface CompositeViewDefinition {
@@ -158,6 +172,11 @@ export interface CompositeViewDefinition {
158
172
  zoneContentMaxWidth?: ResponsiveMaxWidth;
159
173
  /** See {@link CompositeViewAuthoringConfig.zoneContentFillsHeight}. Mirrored from authoring. */
160
174
  zoneContentFillsHeight?: boolean;
175
+ /**
176
+ * See {@link ResourceCompositeViewAuthoringConfig.conversationSystemRef}. Mirrored from a RESOURCE composite's
177
+ * authoring by the registry, which is not Zod-parsed; an application-level definition never carries it.
178
+ */
179
+ conversationSystemRef?: string;
161
180
  }
162
181
 
163
182
  export type AppCompositeViewsConfig = Record<string, CompositeViewAuthoringConfig>;