@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
@@ -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
+ ```
@@ -87,8 +87,10 @@ export const PRESENT_RECORDS_FUNCTION_REF = 'engine.present-records';
87
87
  * conversation's text only), so it reads a record again before acting on it.
88
88
  *
89
89
  * `resourceTypes` are the resources the agent may show. Grant only resources it can already read. Each needs a READ
90
- * operation reachable over HTTP, and its summary is the resource's authored summary layout, else the engine's default
91
- * from its summary fields.
90
+ * operation reachable over HTTP by the record's id and its tenancy alone, since a card knows no parent of its record:
91
+ * a resource routed only under a parent (`REQUIRES_CONTEXT`) is refused at startup, so route it under its tenancy too
92
+ * with `accessScopeStrategy: OPTIONAL_CONTEXT` on the parent edge. Its summary is the resource's authored summary
93
+ * layout, else the engine's default from its summary fields.
92
94
  *
93
95
  * Import path: `@wildo-ai/saas-backend-lib`.
94
96
  *
@@ -117,6 +119,7 @@ export function presentRecordsTool(options: {
117
119
  }),
118
120
  effect: FunctionToolEffect.READ,
119
121
  presentsRecords: true,
122
+ presentedResourceTypes: resourceTypes,
120
123
  personalDataOutput: { kind: FunctionToolPersonalDataOutputKind.NOT_FROM_RECORDS, reason: 'It returns which record ids were shown or unavailable, never their fields.' },
121
124
  authority: { kind: FunctionToolAuthorityKind.PRINCIPAL_RESOURCE_OPERATION },
122
125
  execute: async (args: PresentRecords_ToolInput, ctx: FunctionToolExecutionContext): Promise<PresentRecords_ToolResult> => {
@@ -0,0 +1,207 @@
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, per remote agent:
8
+
9
+ - `a2a_<ref>`, described by YOUR `description` (the remote card's own text never reaches the model). It takes a
10
+ `message` and returns `{ answer, taskState?, taskId?, contextId? }`, or `{ error, detail, taskId?, contextId? }`
11
+ naming how the call failed (`refused_target`, `unreachable`, `timed_out`, `protocol_error`, `remote_task_failed`,
12
+ `remote_request_refused`, `incompatible_agent`, `rate_budget_exhausted`), with the remote task's ids when one was
13
+ opened before the failure. Without a `taskId` it is a new request, which the remote agent answers directly or by
14
+ opening a task. A task still running when `callMs` elapses comes back as an answer carrying its last-read state and
15
+ ids, and keeps running there; it is never cancelled. When the remote card advertises `capabilities.streaming`, the
16
+ call follows the task as a stream (`SendStreamingMessage`): progress and partial results arrive as they happen, and
17
+ the call returns as soon as the task ends or waits for input. An agent that refuses the stream before opening a task
18
+ is sent the message without one, and a stream that drops is followed by reading the task; nothing to declare.
19
+ - Inside a conversation (a chat thread, an A2A conversation, an autonomous turn), two more abilities:
20
+ - `a2a_<ref>` also takes a `taskId`: the message is then the next message of that task, which is how the agent
21
+ answers a task waiting for input (`input-required`) or adds to one still working.
22
+ - `a2a_<ref>_task` takes a `taskId` and an `action`, `read` (the task's state, status message and results now) or
23
+ `cancel` (ask the remote agent to stop it; a task already finished is refused by the remote agent).
24
+ - A task id is honoured only for a task THIS conversation opened, through THIS remote agent, with the very credential
25
+ that resolves now: not another member's credential of the same kind, and not one reconnected since (a new credential
26
+ may authenticate another account at the remote agent). Every task a send or a continuation returns is recorded for the
27
+ conversation before the model sees its id; when the record cannot be written, the answer reaches the model without
28
+ the ids, and a task another conversation already holds does not reach it at all. Any other id is refused before
29
+ anything is sent, with `remote_task_not_owned` or `remote_task_credential_changed`, and the refusal is recorded at
30
+ MEDIUM risk: a remote task id is a capability at the remote party, an organization's credential is shared by all its
31
+ conversations, and an injected prompt may try to act on another conversation's task. The model learns only that it
32
+ may not act on that task, never whose it is.
33
+ - Outside a conversation (a one-shot invocation), there is nothing to own a task, so no `taskId` is accepted and no task
34
+ tool is offered.
35
+ - **Pushes.** Inside a conversation, when a call returns while the remote task is still running or paused, and the
36
+ remote agent's card advertises `capabilities.pushNotifications`, the engine asks the remote agent to push the task's
37
+ updates to the application (`POST /api/v1/a2a-remote-task-pushes`), with a token used for that one task only (only its
38
+ hash is stored). A push is accepted only with that token and only about that task. When the task ends (recorded once:
39
+ nothing pushed after its end is), or waits for input or authorization (recorded each time it asks, up to 20 times per
40
+ task), the update is recorded and the conversation's person is told twice: a live notice if they are connected at
41
+ that moment (`notifications_custom.remote_agent_task_updated`), and an email (`system.remote_agent_task_updated`)
42
+ for when they are not. The email is sent for an end, and for a wait the first time it asks after the person's last
43
+ turn in that conversation; a task that asks again before then gets the live notice only. Both open the conversation, through the engine's conversation-link page (`/conversation`,
44
+ which opens the conversation in its own organization, on the record it was opened on when a resource composite
45
+ declares `conversationSystemRef` for that system, else in the `flowsActorsViews` entry whose `systemRef` is the
46
+ conversation's system, so give that system a view). Neither says what the news is, nor carries the remote agent's words. The push starts NO agent turn. At the conversation's
47
+ next turn, `a2a_<ref>_task`'s description gives the latest report of each task, newest first, and the agent reads the
48
+ result through that tool.
49
+ A push needs the application's backend to be reachable at a public `https://` address (`runtime.endPoints` public
50
+ URL; in development, a tunnel): without one, no push is registered and the agent reads the task when asked.
51
+ - A blank or missing `message`, an unknown `action`, or an extra argument is refused before anything is sent.
52
+ - The tools are offered only when a credential resolves for `credential.subject`, never on a turn an inbound delivery
53
+ started, and never under the name of a tool already offered that turn.
54
+
55
+ What the runtime does on each call:
56
+
57
+ - Fetches the card from `cardUrl` WITHOUT the credential and keeps it for as long as its `Cache-Control` allows (five
58
+ minutes by default, one hour at most, never with `no-store` or `no-cache`). It reads the card's JSON-RPC interfaces at
59
+ protocol version 1.0 (any 1.0 patch).
60
+ - Sends the credential, as a bearer token, to one of those interfaces only: with `endpointUrl` declared, the interface
61
+ at exactly that URL, which is also the URL the credential is resolved for; without it, the card's first such
62
+ interface, and only when it is on the card's own host. A card whose interface is on another host is refused unless
63
+ you declared that interface as `endpointUrl`.
64
+ - Sends `SendMessage` (carrying the task's ids on a continuation), then reads the task with `GetTask` until it ends,
65
+ pauses for input or `callMs` elapses; a read or a cancellation is one `GetTask` or `CancelTask`. Every JSON-RPC
66
+ request carries `A2A-Version: 1.0`. Each response body is read within the same deadline and refused past a size
67
+ ceiling.
68
+ - Goes through the outbound guard, so a private, loopback or metadata address is refused before anything leaves, and
69
+ through the connection's rate budget when the credential has one.
70
+ - Records every act as an `a2a_remote_agent_call` audit row: what it was (`send`, `continue`, `read`, `cancel`), the
71
+ remote agent, the host the credential went to, the outcome, the remote task id and state, and whose credential it
72
+ spent. Never the message, never the answer. Which conversation opened which task is kept in the engine's
73
+ `remoteAgentTasks` records for the application's `OPERATIONAL_LOGS` period; past it, a task can no longer be acted on
74
+ from that conversation.
75
+
76
+ The fields:
77
+
78
+ - `cardUrl` / `endpointUrl` — `https://` only; startup refuses `http://`. Declare `endpointUrl` when the agent's
79
+ interface is on another host than its card, or to pin which of its interfaces is used.
80
+ - `credential` — required. `secretSlug` is the provider's secrets-contract KEY (`accessToken`), never the env-var
81
+ spelling: a wrong spelling silently misses the stored credential, and the tool is then never offered.
82
+ - `timeouts` — `cardMs` (default 5 000) and `callMs` (default 60 000). Write them out: the type you author against is
83
+ the parsed one.
84
+
85
+ Startup refuses a declaration the schema refuses, a `ref` declared twice, a plaintext URL, and an agent whose
86
+ `remoteAgentRefs` names no declaration (`agent_remote_agent_ref_names_no_declared_remote_agent`).
87
+
88
+ The remote agent's answer is another party's text. Declare `contentGuardrails.promptInjection` on the calling agent,
89
+ and under `contentGuardrails.personalData` the answer reaches the model withheld whole, because nothing says which of
90
+ its words are personal data.
91
+
92
+ ## Import Origins
93
+
94
+ - `@wildo-ai/saas-models`
95
+
96
+ ## Source Excerpts
97
+
98
+ ### Origin Package: `@wildo-ai/saas-models`
99
+
100
+ ```typescript
101
+ /**
102
+ * Bounds on a call that leaves the trust boundary. Present with defaults, because a remote agent can take as long as it
103
+ * likes and an unbounded call would hold the calling agent's turn open for that long.
104
+ */
105
+ export const FlowsActors_RemoteAgentTimeoutsSchema = z.object({
106
+ /** How long fetching the remote agent's card may take. */
107
+ cardMs: z.number().int().positive().default(5_000),
108
+ /**
109
+ * How long one delegation may take, end to end: the send, then reading the task until it ends or pauses. A task still
110
+ * running at the deadline is returned to the calling agent as still running, with its ids; it is never cancelled.
111
+ */
112
+ callMs: z.number().int().positive().default(60_000),
113
+ });
114
+ export type FlowsActors_RemoteAgentTimeouts = z.infer<typeof FlowsActors_RemoteAgentTimeoutsSchema>;
115
+
116
+ /**
117
+ * Another party's A2A agent the application's agents may delegate a task to (A2A 1.0, JSON-RPC binding).
118
+ *
119
+ * The runtime fetches the agent card from `cardUrl` WITHOUT the credential and sends the credential to one of the card's
120
+ * JSON-RPC interfaces at protocol version 1.0, and only to one the application named too: with `endpointUrl` declared,
121
+ * the interface at exactly that URL; without it, the card's first such interface, and only when it is on the card's own
122
+ * host. A card cannot redirect a credential to a host the application never named.
123
+ */
124
+ export const FlowsActors_RemoteAgentSchema = z.object({
125
+ /** The value an agent's `capabilities.tools.remoteAgentRefs` names. Unique within an application. */
126
+ ref: z.string().min(1),
127
+ displayName: z.string().min(1),
128
+ /**
129
+ * What the remote agent does, in the application's words. It is the description of the tool the calling model is
130
+ * offered — the card's own description never reaches the model.
131
+ */
132
+ description: z.string().min(1),
133
+ /** Where the agent card is served, `https://` (e.g. `https://agent.example.com/.well-known/agent-card.json`). */
134
+ cardUrl: z.string().url(),
135
+ /**
136
+ * The interface URL the credential is sent to, exactly. Declare it when the agent's interface is on another host than
137
+ * its card, or to pin which of the card's interfaces is used. The credential is resolved for this URL.
138
+ */
139
+ endpointUrl: z.string().url().optional(),
140
+ /** Which stored provider credential authorizes the calls, and whose. Required: an anonymous remote agent is not admitted. */
141
+ credential: FlowsActors_OutboundCredentialSchema,
142
+ timeouts: FlowsActors_RemoteAgentTimeoutsSchema.default({ cardMs: 5_000, callMs: 60_000 }),
143
+ });
144
+ export type FlowsActors_RemoteAgent = z.infer<typeof FlowsActors_RemoteAgentSchema>;
145
+ ```
146
+
147
+ The credential's own contract, shared with MCP servers:
148
+
149
+ ## Import Origins
150
+
151
+ - `@wildo-ai/saas-models`
152
+
153
+ ## Source Excerpts
154
+
155
+ ### Origin Package: `@wildo-ai/saas-models`
156
+
157
+ ```typescript
158
+ /**
159
+ * WHOSE credential the call carries.
160
+ *
161
+ * The distinction is not a preference. A tool call that reaches a third party on a user's behalf
162
+ * should be attributable to that user AT THE FAR END — that is what makes it revocable there and
163
+ * auditable by the party being called. An application-wide service identity loses that: every
164
+ * user's call looks identical to the server, and one leaked credential exposes every tenant.
165
+ */
166
+ export enum FlowsActors_OutboundCredentialSubject {
167
+ /**
168
+ * The acting user's own delegated credential, falling back to the organization's connection when
169
+ * the user has none. The default, and the reason a fallback exists at all: an agent acting for a
170
+ * user who has never connected the server would otherwise have no path, which would make every
171
+ * unattended and batch turn impossible.
172
+ */
173
+ USER_THEN_ORGANIZATION = 'user_then_organization',
174
+ /** The organization's connection only — for a server the tenant connects once on everyone's behalf. */
175
+ ORGANIZATION = 'organization',
176
+ /** The acting user's own credential only. No fallback: a user who has not connected cannot call. */
177
+ USER = 'user',
178
+ }
179
+
180
+ /**
181
+ * Which stored credential authorizes the call.
182
+ *
183
+ * `providerRef` names a provider the application has already connected, so the credential comes from
184
+ * `organizationProviderCredentials` / `userProviderCredentials` rather than from a store invented
185
+ * for one kind of call. Those exist, carry per-tenant isolation by construction, and already have the connect and
186
+ * consent flow in front of them — a second credential store for this one call shape would be a
187
+ * second thing to rotate, audit and leak.
188
+ */
189
+ export const FlowsActors_OutboundCredentialSchema = z.object({
190
+ providerRef: z.string().min(1),
191
+ /**
192
+ * The provider's `secretsContract` KEY (`accessToken`) — the one both credential resolver ports
193
+ * require, and NOT the slot's env-var spelling (`VENDOR_ACCESS_TOKEN`) the env projection names.
194
+ * Stored credentials are keyed on the key (#624), and this value reaches the stores verbatim, so a
195
+ * spelling here misses a credential that exists.
196
+ *
197
+ * DECLARED rather than derived, because it is not derivable: a provider's contract may carry
198
+ * several secrets, and which of them authorizes the endpoint is a fact about that vendor's
199
+ * deployment rather than anything the framework can compute. Guessing a conventional name would
200
+ * resolve the wrong secret silently — the resolver would find a credential, spend it, and be
201
+ * refused by the far server for a reason no log here would explain.
202
+ */
203
+ secretSlug: z.string().min(1),
204
+ subject: z.enum(FlowsActors_OutboundCredentialSubject).default(FlowsActors_OutboundCredentialSubject.USER_THEN_ORGANIZATION),
205
+ });
206
+ export type FlowsActors_OutboundCredential = z.infer<typeof FlowsActors_OutboundCredentialSchema>;
207
+ ```
@@ -99,6 +99,15 @@ export const FlowRun_NodeStateSchema = z.object({
99
99
  nodeType: z.enum(Flow_Node_Type),
100
100
  nodeRef: z.string().min(1),
101
101
  status: z.enum(FlowsActors_Status),
102
+ /**
103
+ * When the node took the status it carries, as an ISO instant (#3990): the trigger and a finish when the run reached
104
+ * them, a step when it completed, failed or began waiting, and a waiting step again when its question was answered or
105
+ * the run ended there. What the Agent activity page's flow timeline shows, in the reader's time zone.
106
+ *
107
+ * Optional because a run written before it was recorded carries none; a reader shows such a node without a time
108
+ * rather than inventing one.
109
+ */
110
+ statusAt: z.iso.datetime().optional(),
102
111
  /** What the step produced (a STEP that completed), JSON-safe. */
103
112
  output: z.json().optional(),
104
113
  /** Why the step failed, in words for the person reading the run (never a stack). */
@@ -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
 
@@ -110,7 +110,11 @@ Each helper passes over a person who already holds a card, and over one its own
110
110
  gets ONE card, in the first vendor that reached them: Slack here, and Teams for someone Slack could not reach (no
111
111
  linked Slack account, or Slack refused). Put the vendor you prefer first. Run every vendor before throwing: a helper
112
112
  that throws stops nothing else here, so a Slack outage does not leave Teams cards unposted or standing, and the
113
- first failure is still thrown, so the engine retries the notice (step 4: one card must not leave the others standing). `decisionLink` and `recordingYourAnswer` return the application's own words for the
113
+ first failure is still thrown, so the engine retries the notice (step 4: one card must not leave the others standing). `decisionLink` is the decision in the application, for a card that cannot carry its answer (it asks values, or has
114
+ more options than a card shows): `({ language, decisionRef }) => ({ url: ctx.decisionUrl(decisionRef), label:
115
+ ctx.words(humanDecisionOpenInApplicationPhrase(), language) })`, with the phrase from `@wildo-ai/saas-models`. Without a
116
+ link such a decision cannot be posted and its notice goes DEAD, naming it. `ctx.decisionUrl` answers `undefined` only in
117
+ a process that knows no frontend: pass no link then, never an invented one. `recordingYourAnswer` returns the application's own words for the
114
118
  reader's language; `applicationBot` names the Teams bot that starts a personal chat with someone who has none yet.
115
119
 
116
120
  ## References
@@ -86,6 +86,15 @@ export type HumanDecisionPhrase =
86
86
  | { readonly kind: HumanDecisionPhraseKind.TOOL; readonly toolName: string }
87
87
  | { readonly kind: HumanDecisionPhraseKind.RESOURCE_OPERATION; readonly resourceType: string; readonly operationIdentifier: string };
88
88
 
89
+ /**
90
+ * The words of the button a chat copy of a decision carries when it is answered in the application only (#2797): a
91
+ * decision that asks values, or has more options than a card shows. What a decision-notice handler passes to its
92
+ * vendor helper's `openInApplication`, beside `ctx.decisionUrl(decisionRef)`.
93
+ */
94
+ export function humanDecisionOpenInApplicationPhrase(): HumanDecisionPhrase {
95
+ return { kind: HumanDecisionPhraseKind.LABEL, labelRef: 'noticeOpenInApplication' };
96
+ }
97
+
89
98
  /** The full key a LABEL, ROLE or TOOL phrase names in an application's label tree; `undefined` for TEXT, which names none. */
90
99
  export function humanDecisionPhraseLabelKey(phrase: HumanDecisionPhrase): string | undefined {
91
100
  switch (phrase.kind) {
@@ -209,6 +209,13 @@ export interface HumanDecisionNoticeContext {
209
209
  * `language` from the application's labels. A missing label shows its key.
210
210
  */
211
211
  readonly words: HumanDecisionNoticeWords;
212
+ /**
213
+ * The decision's address in the application's Decisions inbox (the frontend's public URL and the inbox path), for the
214
+ * link a card carries: a decision that asks fields, or has more options than a card shows, is answered there, so its
215
+ * card is that link alone (the Slack and Teams helpers' `openInApplication`). `undefined` in a process that knows no
216
+ * frontend it can name: post no link then, rather than invent one.
217
+ */
218
+ readonly decisionUrl: (decisionRef: string) => string | undefined;
212
219
  }
213
220
 
214
221
  /** The retry an application may tune. */
@@ -284,7 +284,8 @@ export type InboundChatDecisionAnswer =
284
284
  readonly outcome: HumanDecision_ActOutcome;
285
285
  /**
286
286
  * #2923: where the person answers this decision instead, when a chat answer cannot settle it (it requires a step-up,
287
- * which a chat answer cannot carry, or its kind does not admit a chat answer): the decision's address in the
287
+ * which a chat answer cannot carry, its kind does not admit a chat answer, or, #2797, the person is a representative
288
+ * whose granting organization asks a second factor a chat cannot prove): the decision's address in the
288
289
  * application's inbox. Present exactly then, and when the application has a public address. A handler posts it as
289
290
  * the message's link (`openInApplication`), never a refusal with nowhere to go.
290
291
  */
@@ -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);