@wildo-ai/framework-knowledge 1.1.13 → 1.1.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +12 -4
  4. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +4 -0
  5. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  6. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  7. package/dist/esm/framework-knowledge.definitions.js +9 -0
  8. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  9. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
  10. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
  11. package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
  12. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
  13. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
  14. package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
  15. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  16. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  17. package/dist/knowledge/manifest.json +7 -7
  18. package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
  19. package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
  20. package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
  21. package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
  22. package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
  23. package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
  24. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
  25. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
  26. package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
  27. package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
  28. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -2
  29. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  30. package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
  31. package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
  32. package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
  33. package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
  34. package/dist/knowledge/references/example.config.navigation.full.md +14 -0
  35. package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +6 -2
  36. package/dist/knowledge/references/example.flows-actors.chat-assistant.md +13 -2
  37. package/dist/knowledge/references/example.inbound.email-to-todo.md +33 -2
  38. package/dist/knowledge/references/example.module.relationships.discriminator.md +7 -1
  39. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
  40. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
  41. package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
  42. package/dist/knowledge/references/integration-plan.config.md +78 -8
  43. package/dist/knowledge/references/platform.config.environment.deployment.md +84 -5
  44. package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
  45. package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
  46. package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
  47. package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
  48. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +11 -0
  49. package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
  50. package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
  51. package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
  52. package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
  53. package/dist/knowledge/references/saas.models.flows-actors.mcp-server-declaration.md +63 -0
  54. package/dist/knowledge/references/saas.models.flows-actors.outbound-credential.md +61 -0
  55. package/dist/knowledge/references/saas.models.flows-actors.remote-agent-declaration.md +56 -0
  56. package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
  57. package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
  58. package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
  59. package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
  60. package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
  61. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
  62. package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
  63. package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
  64. package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
  65. package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
  66. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  67. package/dist/knowledge/registries/framework-topics.json +45 -1
  68. package/dist/knowledge/registries/playbooks.json +2 -2
  69. package/dist/knowledge/registries/source-tags.json +1175 -1107
  70. package/dist/knowledge/skills/INDEX.md +2 -2
  71. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +9 -2
  72. package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
  73. package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
  74. package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
  75. package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +21 -1
  76. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +15 -2
  77. package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
  78. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
  79. package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
  80. package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
  81. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
  82. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
  83. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +1 -0
  84. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +15 -1
  85. package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
  86. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +12 -5
  87. package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
  88. package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
  89. package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
  90. package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
  91. package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
  92. package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
  93. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
  94. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +34 -3
  95. package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
  96. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +11 -0
  97. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +15 -0
  98. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
  99. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +169 -0
  100. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
  101. package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
  102. package/dist/knowledge/skills/infra-environment-config/SKILL.md +39 -13
  103. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +84 -5
  104. package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
  105. package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
  106. package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
  107. package/dist/knowledge/skills/module-relationships/SKILL.md +20 -1
  108. package/dist/knowledge/skills/provider-backend-package/SKILL.md +13 -2
  109. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
  110. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
  111. package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
  112. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
  113. package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
  114. package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
  115. package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
  116. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
  117. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -3
  118. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
  119. package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
  120. package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
  121. package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
  122. package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
  123. package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
  124. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
  125. package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
  126. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
  127. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
  128. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
  129. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
  130. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
  131. package/dist/knowledge/topic-index.json +326 -179
  132. package/dist/tsconfig.build.tsbuildinfo +1 -1
  133. package/package.json +4 -4
@@ -702,6 +702,21 @@
702
702
  },
703
703
  });
704
704
  }
705
+ // #3786: a PERSON is erased through `eraseSubjectAsSystem` only. That door consults both administrative-continuity
706
+ // floors, takes down the organization only the person lived in, and tears down their dependents; this one scrubs the
707
+ // row alone and consulted no floor, so a direct scrub of the last owner or super-administrator stranded the tenant or
708
+ // the application with no refusal and no record. It has no production caller, so the sibling door is closed rather
709
+ // than given a second copy of the orchestration: an invariant held at one door of two is not held.
710
+ if (isOrganizationOwnerFloorGovernedSubjectResource(resourceType) || isSuperAdminFloorGovernedSubjectResource(resourceType)) {
711
+ throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
712
+ context: {
713
+ reason: 'person_erased_through_subject_erasure',
714
+ resourceType,
715
+ message: `'${String(resourceType)}' rows are people: erase them through eraseSubjectAsSystem, which applies the `
716
+ + 'administrative-continuity floors, takes down an organization only they belonged to, and tears down their dependents.',
717
+ },
718
+ });
719
+ }
705
720
  await this.impersonalizeRowsAsSystem(resourceType, typeof id_or_ids === 'string' ? [id_or_ids] : id_or_ids, options, ExternalDataCopyScrubCause.ERASURE_REQUEST);
706
721
  }
707
722
 
@@ -1160,13 +1175,26 @@
1160
1175
  // either, so reporting that first gives the operator the outer problem to solve.
1161
1176
  //
1162
1177
  // Also BEFORE `eraseSubjectInPlace`, so a refusal from either guard leaves nothing written.
1163
- await this.assertOrganizationOwnerFloorForSubjectErasure(
1178
+ const organizationsLeavingWithSubjects = await this.assertOrganizationOwnerFloorForSubjectErasure(
1164
1179
  resourceType,
1165
1180
  subjectIds,
1166
1181
  systemContext,
1167
1182
  options?.acknowledgeOrganizationOwnerFloorBreach,
1168
1183
  );
1169
1184
 
1185
+ // ── The organizations only the subjects lived in go with them (#3786) ──
1186
+ //
1187
+ // The floor refuses stranding, and these strand nobody: the subjects are their last usable owners AND their only
1188
+ // living members, which is the ordinary state of a person who signed up alone. Marked here, after both floors and
1189
+ // before anything of the subjects is written, so a refusal above still leaves nothing written and a failed mark
1190
+ // leaves the subjects untouched. See `takeDownOrganizationsLeavingWithSubjects` for why the outcome is explicit
1191
+ // rather than one transaction.
1192
+ const organizationsTakenDownWithSubject = await this.takeDownOrganizationsLeavingWithSubjects(
1193
+ organizationsLeavingWithSubjects,
1194
+ resourceType,
1195
+ subjectIds,
1196
+ );
1197
+
1170
1198
  // An erasure guard stood here (D6 stance 6c): rows in a system of record refused the erasure until a per-request
1171
1199
  // acknowledgement no request schema could carry. Removed by #2559 (epic #2558): the system of record answers requests
1172
1200
  // about its own records, and each such resource's effect reports HANDLED_AT_SOURCE, naming it, post-commit.
@@ -1187,6 +1215,7 @@
1187
1215
  const report = await this.getServicesRegistryHandler()
1188
1216
  .getService(resourceType)
1189
1217
  .eraseSubjectInPlace(resourceType, subjectIds, systemContext, options);
1218
+ if (organizationsTakenDownWithSubject.length > 0) report.organizationsTakenDownWithSubject = organizationsTakenDownWithSubject;
1190
1219
 
1191
1220
  // ── External, non-transactional effects — POST-COMMIT by construction ──
1192
1221
  //
@@ -155,6 +155,36 @@ export const SHELL_GHOST_LAYER_ATTRIBUTE = 'data-shell-ghost-layer';
155
155
  /** The attribute every ghost carries, with its kind (`ShellGhostKind`). */
156
156
  export const SHELL_GHOST_ATTRIBUTE = 'data-shell-ghost';
157
157
 
158
+ /**
159
+ * The markers a still picture of an engine element must NOT carry: everything a query for the real element, or for a
160
+ * control inside it, finds it by. A picture (a discarded pane leaving, an image behind an expanded pane, a pressed row
161
+ * flying into its pane) is inert and takes no pointer, but it is still in the document while it fades, and a picture
162
+ * that kept these was found by those queries as though it were the thing it shows.
163
+ *
164
+ * Measured 2026-11-14 on Your Application (morph layout): a closed todo pane's picture kept `data-navigation-back` for the
165
+ * ~650ms it took to leave, so a lookup of the pane's back control found the picture's (#3764 had to wait it out in
166
+ * `browser-nav-zones`). It never took a click (inert, `pointer-events: none`: the point under it hit the list), but
167
+ * the zone's own back control is identified by that attribute, and a picture must not answer to it.
168
+ *
169
+ * Styling hooks (`data-slot`, `data-state`) are NOT here: a picture keeps the look of what it shows. A caller that
170
+ * needs a narrower picture strips more on its own.
171
+ */
172
+ export const SHELL_PICTURE_STRIPPED_ATTRIBUTES: readonly string[] = [
173
+ 'id',
174
+ // The engine's pane and region markers.
175
+ 'data-content-area',
176
+ 'data-panel-id',
177
+ 'data-zone-hidden',
178
+ 'data-zone-emphasized',
179
+ 'data-component-area',
180
+ SHELL_OBJECT_ATTRIBUTE,
181
+ // The engine's control hooks: a zone's back control, an operation's trigger, a navigation item, a rail entry.
182
+ 'data-navigation-back',
183
+ 'data-operation-id',
184
+ 'data-nav-item-id',
185
+ 'data-ref',
186
+ ];
187
+
158
188
  /** The two kinds of ghost. */
159
189
  export enum ShellGhostKind {
160
190
  /** A dismissed side pane, flying away. */
@@ -0,0 +1,46 @@
1
+ # saas.frontend.electronic-signatures.embedded-signing-frame
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-frontend-lib`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-frontend-lib`
10
+
11
+ ```tsx
12
+ /**
13
+ * Embedded signing: the signed-in person signs a record's deliverable at the signature vendor, inside a frame of the
14
+ * application, instead of following the vendor's e-mail. Import from `@wildo-ai/saas-frontend-lib`.
15
+ *
16
+ * Place it where the person meets the record (an engagement letter's page, say). On mount it asks the backend for the
17
+ * vendor's signing page (`signatureRequestSigners.openSigningSession`). The answer is given only to a signer an open
18
+ * request on that record names and the vendor says has not signed yet, so for anybody else, once the person has signed,
19
+ * and when the request's provider signs from its e-mail only, the component renders NOTHING. The page is valid for
20
+ * minutes and is never stored, which is why it is asked for here, when the person is in front of it. A signer whose turn
21
+ * has not come (signers who sign in turn) is shown nothing either, until it does.
22
+ *
23
+ * When the person is done, a vendor that redirects sends the frame to the application's own {@link SIGNING_RETURN_PAGE_PATH};
24
+ * the frame sees it arrive (it is now same-origin), closes, and calls `onSigningReturned`. A vendor that does not redirect
25
+ * (or redirects to another of the application's origins) keeps showing its own end page. Either way nothing here says the
26
+ * document is signed: every vendor's own guidance is that the end of the frame is not the outcome, and the request becomes
27
+ * SIGNED only once the engine has validated the signed document, at its next re-read (poll or vendor notification).
28
+ *
29
+ * What it needs elsewhere: a provider that claims `EMBEDDED_ELECTRONIC_SIGNATURE` and declares `embeddedSigning`, and a
30
+ * `wildo config sync` then `wildo dev sync-csp` since it was added, which put the vendor's signing origins in the SaaS
31
+ * frontend's CSP `frame-src` from the provider's own declaration; without them the browser refuses to load the frame.
32
+ *
33
+ * It renders no words of its own: the application passes the frame's accessible `title`.
34
+ */
35
+ export interface EmbeddedSigningFrameProps {
36
+ /** The record the deliverable belongs to: the signature request's `linkedResourceType`. */
37
+ readonly linkedResourceType: string;
38
+ /** The record the deliverable belongs to: the signature request's `linkedResourceId`. */
39
+ readonly linkedResourceId: string;
40
+ /** The frame's accessible name (WCAG 4.1.2), in the person's language, e.g. "Sign the engagement letter". */
41
+ readonly title: string;
42
+ /** Called once the person left the vendor's page. Re-read the record if you show its signature state. */
43
+ readonly onSigningReturned?: () => void;
44
+ readonly className?: string;
45
+ }
46
+ ```
@@ -106,45 +106,36 @@ export type FlowsActors_Agent = {
106
106
  /**
107
107
  * References to MCP servers the agent may reach.
108
108
  *
109
- * ## CHECKED, NOT YET CALLABLE (#491)
109
+ * ## Checked at startup, called at turn start (#491, #3958)
110
110
  *
111
- * Each ref must name an MCP server the APPLICATION declared (`FlowsActors_McpServer`), and
112
- * `FlowsActorsRegistryService` REFUSES at initialization an agent whose refs name none. That
113
- * closes the shape this field was in: it used to resolve against nothing, so a shipped catalog
114
- * carried seven refs (`filesystem-mcp`, `git-mcp`, `browser-mcp`, `mongodb-mcp`, …) that named
115
- * no server anywhere while the agent card rendered them as capabilities — a claim shown to a
116
- * user about a reach the agent did not have. The catalog is gone and the card no longer
117
- * renders these.
111
+ * Each ref must name an MCP server the APPLICATION declared (`FlowsActors_McpServer`, on a backend domain
112
+ * module's `flowsActors.mcpServers`), and startup REFUSES an agent whose refs name none. That closes the shape
113
+ * this field was in: it used to resolve against nothing, so a shipped
114
+ * catalog carried seven refs that named no server anywhere — a claim about a reach the agent did not have.
118
115
  *
119
- * The check is deliberately stricter than `functionRefs`, which skip an unknown ref with a
120
- * debug line: an unknown `functionRef` costs an agent one tool, whereas these were presented
121
- * as a capability, and a refusal makes the old state unreachable rather than fixed once.
116
+ * The check is deliberately stricter than `functionRefs`, which skip an unknown ref with a debug line: an unknown
117
+ * `functionRef` costs an agent one tool, whereas these name another party's server.
122
118
  *
123
- * ## What is still missing before a ref becomes a CALLABLE tool
124
- *
125
- * The declaration is checkable; the call is not yet made. `AgentsBackendService` resolves
126
- * `functionRefs` and nothing else, so an agent carrying `mcpRefs` still has exactly the reach
127
- * its `functionRefs` give it.
128
- *
129
- * 1. **An MCP client.** `saas-backend-lib/src/mcp/` is the SERVER Wildo exposes to external MCP
130
- * clients. There is no client, and no MCP client SDK in any manifest.
131
- * 2. ~~A server registry~~ — BUILT. `registry.mcpServers`, declared per application.
132
- * 3. **Credential resolution at call time.** Decided 2026-09-09: the call carries the acting
133
- * user's own delegated provider credential where present and the organization's connection
134
- * otherwise, from `userProviderCredentials` / `organizationProviderCredentials` rather than
135
- * a store invented for MCP. `FlowsActors_McpCredentialSubject` records that choice per
136
- * server; nothing reads it yet.
119
+ * At turn start the agent opens a session with each named server, using the credential the server's declared
120
+ * `credential.subject` selects, and is offered the server's tools. They are withheld on a turn an inbound
121
+ * delivery started and when no credential resolves; a server that does not answer contributes no tools rather
122
+ * than failing the turn. Every tool call, and a target the outbound guard refuses, is recorded on the audit
123
+ * trail; an unreachable or slow server is logged.
124
+ */
125
+ mcpRefs: string[],
126
+ /**
127
+ * References to remote A2A agents the agent may delegate a task to (#3930).
137
128
  *
138
- * Also decided, and not yet implemented: an unreachable server contributes NO tools to a turn
139
- * rather than failing it — tools are discovered at turn start — and a call that fails mid-turn
140
- * returns a typed error the agent can reason about. Both emit an audit event, because a server
141
- * quietly unreachable for a week must be visible as that rather than as an agent that became
142
- * less capable for no stated reason.
129
+ * Each ref must name a remote agent the APPLICATION declared (`FlowsActors_RemoteAgent`, on a backend domain
130
+ * module's `flowsActors.remoteAgents`); startup REFUSES an agent whose refs name none, as for `mcpRefs`.
143
131
  *
144
- * Restoring these to any surface that presents them as a capability belongs in the same change
145
- * that makes them callable.
132
+ * At turn start the agent is offered one tool per named remote agent, described by the declaration (never by the
133
+ * remote card). A call sends the agent's message to the remote agent over A2A 1.0 with the credential the
134
+ * declaration's `credential.subject` selects, and returns the remote reply, or the remote task's state and ids
135
+ * when it is still running or waits for input. Withheld on a turn an inbound delivery started and when no
136
+ * credential resolves. Every call is recorded on the audit trail.
146
137
  */
147
- mcpRefs: string[],
138
+ remoteAgentRefs?: string[],
148
139
  },
149
140
  },
150
141
 
@@ -0,0 +1,63 @@
1
+ # saas.models.flows-actors.mcp-server-declaration
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-models`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-models`
10
+
11
+ ```typescript
12
+ *
13
+ * How the runtime reaches the server.
14
+ *
15
+ * A closed vocabulary rather than a free string: the transport decides the whole connection
16
+ * lifecycle — how a session opens, whether the server can push, how a stream ends — so a value
17
+ * nobody implemented must be unrepresentable rather than discovered at the first call.
18
+ *
19
+ * STDIO is deliberately ABSENT. It launches a local subprocess, which is the coding-agent lane's
20
+ * shape and not an application's: a generated application runs in a container it does not control,
21
+ * and "the agent may spawn a process" is a different security decision from "the agent may call an
22
+ * endpoint". Adding it later is a decision, not an omission.
23
+ */
24
+ export enum FlowsActors_McpTransport {
25
+ /** Streamable HTTP — the current MCP transport for remote servers. */
26
+ HTTP_STREAM = 'http_stream',
27
+ /**
28
+ * Server-sent events — the earlier remote transport, still widely deployed. The client speaks Streamable HTTP only,
29
+ * so startup REFUSES a server declared with it (#3958) rather than failing every turn as a protocol error.
30
+ */
31
+ SSE = 'sse',
32
+ }
33
+
34
+
35
+ /**
36
+ * Bounds on a call that leaves the trust boundary.
37
+ *
38
+ * Present with defaults rather than optional-and-unbounded, because an MCP call is a REMOTE call and
39
+ * the mistake this whole issue warns against is modelling it as a second kind of local function. A
40
+ * local function cannot hang; this can, and an unbounded tool call holds a model turn open for as
41
+ * long as somebody else's server feels like it.
42
+ */
43
+ export const FlowsActors_McpServerTimeoutsSchema = z.object({
44
+ /** How long tool DISCOVERY may take before the server contributes no tools to the turn. */
45
+ discoveryMs: z.number().int().positive().default(5_000),
46
+ /** How long one tool CALL may take before it returns a typed timeout to the agent. */
47
+ callMs: z.number().int().positive().default(30_000),
48
+ });
49
+ export type FlowsActors_McpServerTimeouts = z.infer<typeof FlowsActors_McpServerTimeoutsSchema>;
50
+
51
+ export const FlowsActors_McpServerSchema = z.object({
52
+ /** The value an agent's `capabilities.tools.mcpRefs` names. Unique within an application. */
53
+ ref: z.string().min(1),
54
+ displayName: z.string().min(1),
55
+ transport: z.enum(FlowsActors_McpTransport),
56
+ /** The server's endpoint. `https` in every deployed environment; the runtime refuses plaintext. */
57
+ url: z.string().url(),
58
+ /** Which stored provider credential authorizes the calls (`FlowsActors_OutboundCredentialSchema`). */
59
+ credential: FlowsActors_OutboundCredentialSchema,
60
+ timeouts: FlowsActors_McpServerTimeoutsSchema.default({ discoveryMs: 5_000, callMs: 30_000 }),
61
+ });
62
+ export type FlowsActors_McpServer = z.infer<typeof FlowsActors_McpServerSchema>;
63
+ ```
@@ -0,0 +1,61 @@
1
+ # saas.models.flows-actors.outbound-credential
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-models`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-models`
10
+
11
+ ```typescript
12
+ /**
13
+ * WHOSE credential the call carries.
14
+ *
15
+ * The distinction is not a preference. A tool call that reaches a third party on a user's behalf
16
+ * should be attributable to that user AT THE FAR END — that is what makes it revocable there and
17
+ * auditable by the party being called. An application-wide service identity loses that: every
18
+ * user's call looks identical to the server, and one leaked credential exposes every tenant.
19
+ */
20
+ export enum FlowsActors_OutboundCredentialSubject {
21
+ /**
22
+ * The acting user's own delegated credential, falling back to the organization's connection when
23
+ * the user has none. The default, and the reason a fallback exists at all: an agent acting for a
24
+ * user who has never connected the server would otherwise have no path, which would make every
25
+ * unattended and batch turn impossible.
26
+ */
27
+ USER_THEN_ORGANIZATION = 'user_then_organization',
28
+ /** The organization's connection only — for a server the tenant connects once on everyone's behalf. */
29
+ ORGANIZATION = 'organization',
30
+ /** The acting user's own credential only. No fallback: a user who has not connected cannot call. */
31
+ USER = 'user',
32
+ }
33
+
34
+ /**
35
+ * Which stored credential authorizes the call.
36
+ *
37
+ * `providerRef` names a provider the application has already connected, so the credential comes from
38
+ * `organizationProviderCredentials` / `userProviderCredentials` rather than from a store invented
39
+ * for one kind of call. Those exist, carry per-tenant isolation by construction, and already have the connect and
40
+ * consent flow in front of them — a second credential store for this one call shape would be a
41
+ * second thing to rotate, audit and leak.
42
+ */
43
+ export const FlowsActors_OutboundCredentialSchema = z.object({
44
+ providerRef: z.string().min(1),
45
+ /**
46
+ * The provider's `secretsContract` KEY (`accessToken`) — the one both credential resolver ports
47
+ * require, and NOT the slot's env-var spelling (`VENDOR_ACCESS_TOKEN`) the env projection names.
48
+ * Stored credentials are keyed on the key (#624), and this value reaches the stores verbatim, so a
49
+ * spelling here misses a credential that exists.
50
+ *
51
+ * DECLARED rather than derived, because it is not derivable: a provider's contract may carry
52
+ * several secrets, and which of them authorizes the endpoint is a fact about that vendor's
53
+ * deployment rather than anything the framework can compute. Guessing a conventional name would
54
+ * resolve the wrong secret silently — the resolver would find a credential, spend it, and be
55
+ * refused by the far server for a reason no log here would explain.
56
+ */
57
+ secretSlug: z.string().min(1),
58
+ subject: z.enum(FlowsActors_OutboundCredentialSubject).default(FlowsActors_OutboundCredentialSubject.USER_THEN_ORGANIZATION),
59
+ });
60
+ export type FlowsActors_OutboundCredential = z.infer<typeof FlowsActors_OutboundCredentialSchema>;
61
+ ```
@@ -0,0 +1,56 @@
1
+ # saas.models.flows-actors.remote-agent-declaration
2
+
3
+ ## Import Origins
4
+
5
+ - `@wildo-ai/saas-models`
6
+
7
+ ## Source Excerpts
8
+
9
+ ### Origin Package: `@wildo-ai/saas-models`
10
+
11
+ ```typescript
12
+ /**
13
+ * Bounds on a call that leaves the trust boundary. Present with defaults, because a remote agent can take as long as it
14
+ * likes and an unbounded call would hold the calling agent's turn open for that long.
15
+ */
16
+ export const FlowsActors_RemoteAgentTimeoutsSchema = z.object({
17
+ /** How long fetching the remote agent's card may take. */
18
+ cardMs: z.number().int().positive().default(5_000),
19
+ /**
20
+ * How long one delegation may take, end to end: the send, then reading the task until it ends or pauses. A task still
21
+ * running at the deadline is returned to the calling agent as still running, with its ids; it is never cancelled.
22
+ */
23
+ callMs: z.number().int().positive().default(60_000),
24
+ });
25
+ export type FlowsActors_RemoteAgentTimeouts = z.infer<typeof FlowsActors_RemoteAgentTimeoutsSchema>;
26
+
27
+ /**
28
+ * Another party's A2A agent the application's agents may delegate a task to (A2A 1.0, JSON-RPC binding).
29
+ *
30
+ * The runtime fetches the agent card from `cardUrl` WITHOUT the credential and sends the credential to one of the card's
31
+ * JSON-RPC interfaces at protocol version 1.0, and only to one the application named too: with `endpointUrl` declared,
32
+ * the interface at exactly that URL; without it, the card's first such interface, and only when it is on the card's own
33
+ * host. A card cannot redirect a credential to a host the application never named.
34
+ */
35
+ export const FlowsActors_RemoteAgentSchema = z.object({
36
+ /** The value an agent's `capabilities.tools.remoteAgentRefs` names. Unique within an application. */
37
+ ref: z.string().min(1),
38
+ displayName: z.string().min(1),
39
+ /**
40
+ * What the remote agent does, in the application's words. It is the description of the tool the calling model is
41
+ * offered — the card's own description never reaches the model.
42
+ */
43
+ description: z.string().min(1),
44
+ /** Where the agent card is served, `https://` (e.g. `https://agent.example.com/.well-known/agent-card.json`). */
45
+ cardUrl: z.string().url(),
46
+ /**
47
+ * The interface URL the credential is sent to, exactly. Declare it when the agent's interface is on another host than
48
+ * its card, or to pin which of the card's interfaces is used. The credential is resolved for this URL.
49
+ */
50
+ endpointUrl: z.string().url().optional(),
51
+ /** Which stored provider credential authorizes the calls, and whose. Required: an anonymous remote agent is not admitted. */
52
+ credential: FlowsActors_OutboundCredentialSchema,
53
+ timeouts: FlowsActors_RemoteAgentTimeoutsSchema.default({ cardMs: 5_000, callMs: 60_000 }),
54
+ });
55
+ export type FlowsActors_RemoteAgent = z.infer<typeof FlowsActors_RemoteAgentSchema>;
56
+ ```
@@ -28,6 +28,12 @@ export enum FrontendProviderPublicConfigRefusal {
28
28
  * key is called and whichever vendor the secret belongs to. Never negotiable.
29
29
  */
30
30
  SECRET_VALUE = 'SECRET_VALUE',
31
+ /**
32
+ * A provider contract marks a slot browser-public (`holdsBrowserPublicValue`) whose environment variable is one of the
33
+ * FRAMEWORK's own runtime secrets — a database password, a signing key. The mark would serve that value to every
34
+ * browser, and the backend's value screen cannot see framework secrets, so the contract is refused outright.
35
+ */
36
+ BROWSER_PUBLIC_SLOT_NAMES_FRAMEWORK_SECRET = 'BROWSER_PUBLIC_SLOT_NAMES_FRAMEWORK_SECRET',
31
37
  }
32
38
  ```
33
39
 
@@ -248,6 +248,34 @@ export const HttpApiFieldMappingSchema = z.strictObject({
248
248
  create: z.string().min(1).optional(),
249
249
  update: z.string().min(1).optional(),
250
250
  }).optional(),
251
+ /**
252
+ * #3953 — WRITE this field through a LOOKUP (Odoo only): a create or update sends `remoteField` of this object instead
253
+ * of the mapping's own `remoteField`, set to the id of the ONE `lookupEntityRef` record whose `lookupRemoteField`
254
+ * equals the value the resource holds. Reads keep the mapping's own `remoteField`.
255
+ *
256
+ * For a field the system of record shows as a code but stores as a reference to another record. On Odoo a partner's
257
+ * `country_code` is the RELATED `country_id.code`: it reads the ISO code, and a write to it is accepted and discarded
258
+ * (measured on Odoo 19.0). The country is written through `country_id`, a many2one to `res.country`:
259
+ *
260
+ * ```ts
261
+ * { localField: 'country', remoteField: 'country_code',
262
+ * writeThrough: { remoteField: 'country_id', lookupEntityRef: 'res.country', lookupRemoteField: 'code' } }
263
+ * ```
264
+ *
265
+ * Each write with a value looks it up once more (one `search_read` on the lookup model, before anything is sent). The
266
+ * match is EXACT and case-sensitive (`'fr'` names no country whose code is `'FR'`), and Odoo leaves archived records
267
+ * of the lookup model out by default. A value no record matches is refused as the caller's
268
+ * (`SYSTEM_OF_RECORD_WRITE_VALUE_UNRESOLVED`); a value several records match, or a `remoteField` that Odoo does not
269
+ * describe as a many2one to `lookupEntityRef`, is refused as the binding's (`SYSTEM_OF_RECORD_WRITE_LOOKUP_INVALID`).
270
+ * Nothing is sent either way. An empty value (`null` or `''`) unsets the reference (Odoo's `false`). Refused at
271
+ * registration on any other dialect, on a binding that opens neither create nor update, and when the field it writes is
272
+ * another mapping's field or another write-through's.
273
+ */
274
+ writeThrough: z.strictObject({
275
+ remoteField: z.string().min(1),
276
+ lookupEntityRef: z.string().min(1),
277
+ lookupRemoteField: z.string().min(1),
278
+ }).optional(),
251
279
  });
252
280
  ```
253
281
 
@@ -947,6 +975,29 @@ export function assertHttpApiBindingDialectCoherence(binding: HttpApiResourceBin
947
975
  }
948
976
  }
949
977
 
978
+ // #3953 — a write through a lookup is Odoo's (a code shown, a reference stored), and only a write uses it.
979
+ for (const mapping of binding.fieldMappings) {
980
+ if (mapping.writeThrough === undefined) continue;
981
+ const at = `fieldMappings('${mapping.localField}').writeThrough`;
982
+ if (binding.dialect !== HttpApiTransportDialect.ODOO_JSONRPC && binding.dialect !== HttpApiTransportDialect.ODOO_JSON2) {
983
+ throw new Error(`${at}: declared on a ${binding.dialect} binding. It resolves a value through a lookup on another Odoo model before a write, and only the Odoo dialects compile one.`);
984
+ }
985
+ if (!binding.writableVerbs.includes(HttpApiWriteVerb.CREATE) && !binding.writableVerbs.includes(HttpApiWriteVerb.UPDATE)) {
986
+ throw new Error(`${at}: this binding opens neither create nor update, so nothing would ever be written through it. Remove it, or open the verb.`);
987
+ }
988
+ // Two values for one remote field in one write: whichever is written last would win, silently.
989
+ const target = mapping.writeThrough.remoteField;
990
+ const clash = binding.fieldMappings.find((other) => other !== mapping
991
+ && (other.remoteField === target || other.writeThrough?.remoteField === target));
992
+ if (clash !== undefined) {
993
+ throw new Error(`${at}: writes '${target}', which fieldMappings('${clash.localField}') also writes. One remote field takes one value per write.`);
994
+ }
995
+ // The population's create values are the engine's (#2552): a create writes them, and the lookup would replace one.
996
+ if (Object.prototype.hasOwnProperty.call(binding.populationFilter?.createValues ?? {}, target)) {
997
+ throw new Error(`${at}: writes '${target}', which the population filter's createValues also writes on every create. One remote field takes one value per write.`);
998
+ }
999
+ }
1000
+
950
1001
  // #2552 — the population filter: expressible by this dialect's list, and satisfied by what a create writes.
951
1002
  assertHttpApiPopulationFilterCoherence(binding as never);
952
1003