@wildo-ai/framework-knowledge 1.1.15 → 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 (53) 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 +4 -0
  7. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  8. package/dist/esm/playbooks/bottom_up.build/playbook.definition.d.ts.map +1 -1
  9. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +6 -4
  10. package/dist/esm/playbooks/bottom_up.build/playbook.definition.js.map +1 -1
  11. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
  12. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  13. package/dist/knowledge/manifest.json +7 -7
  14. package/dist/knowledge/playbooks/bottom_up.build/method.md +10 -8
  15. package/dist/knowledge/playbooks/bottom_up.build/playbook.json +1 -1
  16. package/dist/knowledge/references/backend.inbound-handlers.definition.md +2 -1
  17. package/dist/knowledge/references/example.electronic-signature.engagement-letter-tool.md +54 -0
  18. package/dist/knowledge/references/example.module.relationships.discriminator.md +7 -0
  19. package/dist/knowledge/references/saas.backend.flows-actors.decision-notice-handler.md +7 -0
  20. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +5 -0
  21. package/dist/knowledge/references/saas.backend.flows-actors.present-records-tool.md +5 -2
  22. package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +19 -0
  23. package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +21 -0
  24. package/dist/knowledge/references/saas.models.flows-actors.decision-card-wording.md +9 -0
  25. package/dist/knowledge/references/saas.models.flows.run-state.md +9 -0
  26. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  27. package/dist/knowledge/registries/framework-topics.json +11 -1
  28. package/dist/knowledge/registries/playbooks.json +1 -1
  29. package/dist/knowledge/registries/source-tags.json +1019 -1002
  30. package/dist/knowledge/skills/application-roles-authoring/SKILL.md +20 -4
  31. package/dist/knowledge/skills/config-app-shell/SKILL.md +4 -0
  32. package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +2 -0
  33. package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +58 -15
  34. package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +1 -1
  35. package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +32 -5
  36. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +5 -4
  37. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +5 -0
  38. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +15 -0
  39. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-present-records-tool-api.md +5 -2
  40. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +55 -17
  41. package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-start-flow-api.md +9 -0
  42. package/dist/knowledge/skills/human-decision-notices/SKILL.md +5 -1
  43. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-card-wording-api.md +9 -0
  44. package/dist/knowledge/skills/human-decision-notices/references/framework-decision-notice-handler-api.md +7 -0
  45. package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +2 -1
  46. package/dist/knowledge/skills/module-relationships/SKILL.md +7 -0
  47. package/dist/knowledge/skills/provider-backend-package/SKILL.md +19 -2
  48. package/dist/knowledge/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +21 -0
  49. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +5 -0
  50. package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +19 -0
  51. package/dist/knowledge/topic-index.json +104 -70
  52. package/dist/tsconfig.build.tsbuildinfo +1 -1
  53. package/package.json +4 -4
@@ -103,9 +103,22 @@ UPDATE.
103
103
 
104
104
  ### Step 5 — Specify and label it
105
105
 
106
- Author a role specification (`spec-family-update`) so the purpose grounds the role's labels, and make
107
- sure `roleSpecifications` in `specifications/src/companion-exports.ts` spreads the application's role
108
- specifications beside `engineRoleSpecifications`. Then regenerate labels (`i18n-label-generation`).
106
+ Every custom role gets its own specification, in the same task as the role. The application's
107
+ customer documentation describes each organization role from it, and refuses to publish a role
108
+ that has none.
109
+
110
+ - **File and name:** one file per role, `specifications/src/engine/roles/<role>.role.specification.ts`
111
+ with the role's name in kebab case, exporting `<role>RoleSpecification` in camel case. For
112
+ `FIELD_TECHNICIAN`: `field-technician.role.specification.ts` exporting
113
+ `fieldTechnicianRoleSpecification`, built with `appLevelRoleSpecificationFromDefinition`
114
+ (`spec-family-update`).
115
+ - **Guidance:** write `purpose`, `businessRole`, `authorityBoundary`, `useWhen`, `avoidWhen` and
116
+ `businessConstraints`. The documentation needs every one except `businessRole`, and a role whose
117
+ specification lacks one is not finished.
118
+ - **Wiring:** import it in `specifications/src/companion-exports.ts` and add it to
119
+ `roleSpecifications` there, beside `engineRoleSpecifications`, through `buildRoleSpecificationMap`.
120
+
121
+ Then regenerate labels (`i18n-label-generation`).
109
122
 
110
123
  ### Step 6 — Check who can give it to people
111
124
 
@@ -137,7 +150,7 @@ The complete office/field wiring — role table, organization type, operation ro
137
150
  - [ ] Every custom role is named in at least one operation's `roles`.
138
151
  - [ ] Every operation naming a custom role that tenant administrators must be able to grant also names `ORG_ADMIN` (or a role on its chain), or the role is grantable by the platform super-administrator only.
139
152
  - [ ] No resource stores roles, permissions or role assignments.
140
- - [ ] Each role has a specification and labels.
153
+ - [ ] Each role has `specifications/src/engine/roles/<role>.role.specification.ts` with `purpose`, `authorityBoundary`, `useWhen`, `avoidWhen` and `businessConstraints`, wired into `roleSpecifications`, and labels.
141
154
 
142
155
  ### Grep invariants
143
156
 
@@ -146,6 +159,8 @@ The complete office/field wiring — role table, organization type, operation ro
146
159
  rg -n "role: '" shared-lib/src/engine/roles.ts
147
160
  # each declared role is offered (repeat per role name)
148
161
  rg -n "'FIELD_TECHNICIAN'" wildo.saas.config.ts
162
+ # each declared role has its specification, wired into the companion exports (repeat per role name)
163
+ rg -n "fieldTechnicianRoleSpecification" specifications/src/engine/roles specifications/src/companion-exports.ts
149
164
  # each declared role is named on an operation (repeat per role name)
150
165
  rg -l "'FIELD_TECHNICIAN'" shared-lib/src/modules
151
166
  # grantable by administrators: every role list naming the custom role should also name ORG_MEMBER/ORG_ADMIN (or a role on their chain)
@@ -168,6 +183,7 @@ rg -li "permission|roleassignment|accessrole" shared-lib/src/modules --glob '*.s
168
183
  ## Red Flags
169
184
 
170
185
  - A custom role in `roles.ts` that no operation names (catch with the **named on an operation** grep).
186
+ - A custom role with no `<role>RoleSpecification`, or one the companion exports never add to `roleSpecifications`: the customer documentation refuses to publish (catch with the **specification** grep).
171
187
  - A custom organization role missing from `availableOrgRoles` (catch with the **offered** grep).
172
188
  - A custom role tenant administrators must give, named alone on an operation they cannot call (catch with the **grantable by administrators** grep).
173
189
  - A resource whose schema stores roles, permissions or assignments (catch with the **modelling roles as data** grep — must return empty).
@@ -94,6 +94,10 @@ and an `order`), `placedOnThisSurface` (each entry with its `shellIdentity`, its
94
94
  members' section).
95
95
  - A user-menu task lists the placed settings destinations in `USER_DROPDOWN.settingsEntries`; it has no audience.
96
96
  - Nothing declined may remain on any surface.
97
+ - A placed view that was built as a resource operation's custom view (`customView` on one operation in the resource's
98
+ ui-behavior) has no launcher of its own: place a `RESOURCE_OPERATION` entry for that operation. The placement reads it
99
+ as the view when the component's name starts with the view ref's words (`view-enquiry-capture` is carried by an entry
100
+ opening the operation bound to `EnquiryCaptureCustomView`); the shell oracle shows that entry with `hostedCustomView`.
97
101
  - The task lands when `wildo context info app-shell-placement-content` lists every placed identity on the surface,
98
102
  shown to the audience the plan decided, and none of the declined ones. Run it before finishing.
99
103
 
@@ -135,6 +135,7 @@ Access decisions: what an identity was allowed or refused.
135
135
  | `PROVIDER_ACCOUNT_CLAIM_REFUSED` | `provider_account_claim_refused` | Warning | An organization's claim of a vendor account that routes inbound deliveries was REFUSED because another organization's enabled connection already holds it: a connect, or turning a stored connection back on. |
136
136
  | `PROVIDER_CONNECTION_SIGN_IN_AUTHORITY_REFUSED` | `provider_connection_sign_in_authority_refused` | Warning | A connection was REFUSED because the person signing in to the vendor lacked the authority its provider requires of that sign-in (`oauth2.idTokenRequirements`): a Microsoft 365 tenant claim by someone who is not one of the tenant's Global or Teams Administrators, or who is a guest. |
137
137
  | `PROVIDER_DATA_RESIDENCY_REFUSED` | `provider_data_residency_refused` | Warning | A provider call made for an organization was refused before anything was sent, because the organization pins its data to places (`Organization.dataResidency`) the provider cannot be shown to stay inside: its chosen region processes elsewhere, nothing states where it processes, or the call would spend an owner's own connected account nobody placed. |
138
+ | `PROVIDER_GRANT_EXPORTED` | `provider_grant_exported` | Warning | A stored OAuth2 grant LEFT this deployment in its portable form (grant seeding, 2026-11-18): a super-administrator of a development or test deployment exported it so another such deployment can import it. |
138
139
  | `PROVIDER_OPERATION_DENIED` | `provider_operation_denied` | Warning | |
139
140
  | `RELATIONSHIP_CAPABILITY_EXPIRED` | `relationship_capability_expired` | Warning | A lent capability reached its stated end and was relabelled EXPIRED by the credential-expiry sweep: the lending ended on schedule, nobody acting. |
140
141
  | `RELATIONSHIP_CAPABILITY_GRANTED` | `relationship_capability_granted` | Critical | A granting organization lent a representing organization's representatives a named administrative capability, until a stated end. |
@@ -264,6 +265,7 @@ Reads and changes of application data that are recorded for review.
264
265
  | Event | Wire value | Severity | What it records |
265
266
  | --- | --- | --- | --- |
266
267
  | `A2A_REMOTE_AGENT_CALL` | `a2a_remote_agent_call` | Information | |
268
+ | `A2A_REMOTE_TASK_PUSH` | `a2a_remote_task_push` | Information | |
267
269
  | `AGENT_BEHAVIOR_REPORT_RECEIVED` | `agent_behavior_report_received` | Warning, raised to Critical by an occurrence that says so | A person reported an agent's reply. |
268
270
  | `AGENT_BEHAVIOR_REPORTED_TURN_READ` | `agent_behavior_reported_turn_read` | Warning | An administrator read the reply a report is about, from the reporter's conversation (`readReportedTurn`): a person's conversation read by someone else, so every read is recorded, with whether the turn was still there. |
269
271
  | `AGENT_CONTENT_QUARANTINED` | `agent_content_quarantined` | Critical | A classifier found a prompt-injection attack in content somebody else wrote, and the agent's model never read it: a tool result reached it as a quarantine notice, or an inbound delivery did not start its turn (`contentSource`). |
@@ -60,8 +60,8 @@ vendor's certificates (an advanced level needs them), it chains to one. Nothing
60
60
  `@wildo-ai/saas-backend-lib`. `APPROVER` signs what they approved. Registration refuses a declaration without a
61
61
  deliverable, with no signer, or naming a source twice.
62
62
  3. **Enable `ELECTRONIC_SIGNATURE`** in `wildo.saas.config.ts` and select a provider that applies the level. Startup
63
- refuses a declared level with the capability off, a provider that does not apply it, a provider pinning no trust
64
- anchor for its environment, and a vendor test environment outside development and test.
63
+ refuses a declared level with the capability off, a provider that does not apply it, an advanced level from a
64
+ provider pinning no trust anchor for its environment, and a vendor test environment outside development and test.
65
65
  4. **Enable the vendor's notifications** when its provider names a `notificationEndpointKey`. A notification is never
66
66
  believed: it only causes a re-read. Without it, the poll re-reads open requests every five minutes.
67
67
  5. **Know what happens next** (`references/what-makes-a-request-signed.md`): the poll sends each newly sealed
@@ -75,21 +75,64 @@ vendor's certificates (an advanced level needs them), it chains to one. Nothing
75
75
 
76
76
  ## Worked Example
77
77
 
78
- <!-- TIER C WAIVER: the registry has electronic-signature providers (ignisign, yousign, docusign-esignature), but no dogfood application installs one, so none enables ELECTRONIC_SIGNATURE (startup refuses an enabled capability with no provider) and there is no Tier A site to anchor. -->
79
- ```ts
80
- export const sendEngagementLetter: FunctionTool = {
81
- functionRef: 'ledger.sendEngagementLetter',
82
- inputSchema: z.object({ clientId: z.string(), letterFileId: z.string() }),
83
- humanApproval: { route: HumanDecision_RouteKind.OWNER },
78
+
79
+ ## Usage Example
80
+
81
+ ```typescript
82
+ const RequestEngagementLetterSignature_InputSchema = z.object({
83
+ engagementId: z.string().min(1).describe('The engagement. Resolve it with resource.engagements.read.'),
84
+ letterFileId: z.string().min(1).max(200)
85
+ .describe('The id of the engagement\'s letter PDF: `engagementLetter.fileId` as resource.engagements.read returned it. The client signs this file, byte for byte.'),
86
+ });
87
+ type RequestEngagementLetterSignature_Input = z.infer<typeof RequestEngagementLetterSignature_InputSchema>;
88
+
89
+ /** The engagement's fields the client approves beside the letter: shown on the card and committed to by the seal. */
90
+ export const ENGAGEMENT_LETTER_SEALED_FIELDS = ['engagementReference', 'services', 'closeCadence', 'startsOn', 'endsOn'] as const;
91
+
92
+ export const requestEngagementLetterSignatureTool: FunctionTool = {
93
+ functionRef: REQUEST_ENGAGEMENT_LETTER_SIGNATURE_TOOL_REF,
94
+ authority: {
95
+ kind: FunctionToolAuthorityKind.NO_APPLICATION_DATA,
96
+ reason: 'It reads and writes nothing: once the client approves, the engine itself sends the approved letter for signature.',
97
+ },
98
+ effect: FunctionToolEffect.WRITE,
99
+ description:
100
+ 'Ask the client to sign the engagement letter electronically. Pass the engagement id and the id of its letter PDF '
101
+ + '(engagementLetter.fileId from resource.engagements.read); the firm uploads the letter on the engagement first. '
102
+ + 'The client\'s administrator approves the letter, then signs it inside the application, on the engagement\'s page. '
103
+ + 'Call it only when the user asks, then say it is waiting for the client\'s administrator.',
104
+ inputSchema: RequestEngagementLetterSignature_InputSchema,
105
+ personalDataOutput: {
106
+ kind: FunctionToolPersonalDataOutputKind.NOT_FROM_RECORDS,
107
+ reason: 'It returns the two ids it was called with and a fixed sentence; it reads no record.',
108
+ },
109
+ humanApproval: {
110
+ route: HumanDecision_RouteKind.ROLE,
111
+ eligibleRole: CORE_ORG_ROLES.ORG_ADMIN,
112
+ // Signing commits the client to the mandate.
113
+ riskLevel: ResourceOperationRiskLevel.HIGH,
114
+ },
115
+ argumentsResource: { resourceType: ClientEngagements_ResourceType.ENGAGEMENTS, rowIdArgument: 'engagementId' },
84
116
  deliverableFileArgument: 'letterFileId',
85
- electronicSignature: { requiredLevel: ElectronicSignature_Level.ADVANCED, signers: [FunctionTool_SignerSource.APPROVER] },
86
- execute: async (args) => ({ queued: args.letterFileId }),
117
+ sealedRecordFields: ENGAGEMENT_LETTER_SEALED_FIELDS,
118
+ // A letter re-issued and approved again replaces the earlier approval of the same engagement.
119
+ approvalReplacesEarlierApprovalOfRow: true,
120
+ electronicSignature: { requiredLevel: ElectronicSignature_Level.SIMPLE, signers: [FunctionTool_SignerSource.APPROVER] },
121
+ execute: async (args: RequestEngagementLetterSignature_Input) => ({
122
+ engagementId: args.engagementId,
123
+ letterFileId: args.letterFileId,
124
+ // What happens next is the engine's, within minutes and not here: the approved letter is sent for the approver's
125
+ // signature. Said as what WILL happen, never as done.
126
+ next: 'The client\'s administrator approved the letter. The application sends it for their signature within a few minutes; they sign it on the engagement\'s page.',
127
+ }),
87
128
  };
88
129
  ```
89
130
 
90
- The person approves the call with the letter in front of them. Its seal binds the letter's bytes. Within five minutes
91
- the letter goes to the vendor for that person to sign at the advanced level, and the request becomes SIGNED once the
92
- signed PDF validates.
131
+ The firm's assistant names the engagement and its letter. The decision goes to `ORG_ADMIN` in the client organization,
132
+ a role no firm expert holds there, so the person who approves, and therefore signs, is the client. The seal binds the
133
+ letter's bytes and the engagement's terms (`sealedRecordFields`) and is linked to the engagement (`argumentsResource`),
134
+ which is the record whose page shows the signing frame. Within five minutes the letter goes to the vendor for that
135
+ person to sign, and the request becomes SIGNED once the signed PDF validates.
93
136
 
94
137
  ## References
95
138
 
@@ -116,9 +159,9 @@ rg -n "requiredLevel: *'|signers: *\[ *'" backend-api/src
116
159
 
117
160
  | Rationalization | Reality |
118
161
  |---|---|
119
- | "The vendor says it is completed, so mark it signed." | The vendor's status is a claim. Only a signed PDF that validates (byte range, the bytes sent, a chain to the pinned anchors, revocation data, no SHA-1) makes it SIGNED. |
162
+ | "The vendor says it is completed, so mark it signed." | The vendor's status is a claim. Only a signed PDF that validates (byte range, the bytes sent, no SHA-1, and a chain to the pinned anchors with revocation data when the provider pins them) makes it SIGNED. |
120
163
  | "Send the document from my tool's `execute`." | Then nothing binds what is signed to what was approved, and nothing tracks or validates it. Declare `electronicSignature`; the engine sends the sealed bytes. |
121
- | "Use the vendor's sandbox in production while we wait for the contract." | A sandbox chain never reaches the production anchors, so every request would stay open. Startup refuses it outside development and test. |
164
+ | "Use the vendor's sandbox in production while we wait for the contract." | Startup refuses a vendor test environment outside development and test. There, a sandbox document is accepted unvalidated so the flow can be run end to end, and its evidence says so (`accepted_from_test_environment`); in production only a validated document makes a request SIGNED. |
122
165
  | "Let the model choose who signs." | Signers come from a closed vocabulary (`FunctionTool_SignerSource`), never from what the model wrote. |
123
166
  | "The signer came back from the signing frame, so mark it signed." | Coming back says they left the vendor's page. Only the validated signed document, at the next re-read, makes it SIGNED. |
124
167
  | "Rewrite the PDF to add a cover page after signing." | Anything appended after the last signature but validation data is refused: what was signed would no longer be the document. |
@@ -93,7 +93,7 @@ the frame's accessible title, from your labels.
93
93
  (`SIGNING_RETURN_PAGE_PATH`; the engine hands it to the vendor when sending and when opening the session), the frame
94
94
  closes and calls `onSigningReturned`. A vendor that does not redirect keeps showing its own end page. Neither says the
95
95
  document is signed: the request becomes SIGNED only once the engine has validated the signed document, at its next
96
- re-read.
96
+ re-read (in a vendor's test environment in development or test, once it has accepted it unvalidated, marked so).
97
97
 
98
98
  | Answer | Meaning |
99
99
  |---|---|
@@ -6,7 +6,7 @@
6
6
  |---|---|---|
7
7
  | SENT | Sent; nobody has signed yet, as far as the vendor reports. | no |
8
8
  | PARTIALLY_SIGNED | The vendor reports that some signers signed. A claim, never evidence. | no |
9
- | SIGNED | The signed document validated and proves every signer at the required level. | yes |
9
+ | SIGNED | The signed document validated and proves every signer at the required level (`validatedAt` set); or, in a vendor's test environment in development or test only, it was accepted unvalidated (no `validatedAt`, see below). | yes |
10
10
  | DECLINED | A signer refused. | yes |
11
11
  | EXPIRED | The vendor's deadline passed. | yes |
12
12
  | CANCELLED | Withdrawn before it was signed, at the vendor or because its record went. | yes |
@@ -25,10 +25,12 @@ A vendor's "completed" moves nothing by itself. The engine downloads the signed
25
25
  `/Annots` and a document security store (`/DSS`) may be added. After the last signature, only a `/DSS` update.
26
26
  Every appended cross-reference section must be one the check read, chained to the one before it, so a section hidden
27
27
  inside a stream's data cannot be the one a PDF reader follows.
28
- - **The chain.** The signer's certificate chains, at the claimed signing time (which must fall within the request's
29
- life), to an anchor the provider pins for its vendor environment.
30
- - **Revocation.** Every certificate below the anchor has a CRL or OCSP response saying it is not revoked: the one the
31
- signature carries, or a CRL fetched now from the certificate's distribution point.
28
+ - **The signing time.** The time the signature claims falls within the request's life.
29
+ - **The chain, when the provider pins certificates.** The signer's certificate chains, at that time, to an anchor the
30
+ provider pins for its vendor environment. Pinning is optional: a provider that pins none is validated without its
31
+ chain, proves the simple level only, and its evidence records `chainCheck: not_checked`. An advanced level needs it.
32
+ - **Revocation, with the chain.** Every certificate below the anchor has a CRL or OCSP response saying it is not
33
+ revoked: the one the signature carries, or a CRL fetched now from the certificate's distribution point.
32
34
  - **Algorithms.** SHA-256, SHA-384 or SHA-512 throughout; SHA-1 and RSA keys under 2048 bits are refused.
33
35
  - **Signer and level.** At ADVANCED, every signer's certificate names their e-mail address and carries a certificate
34
36
  policy the provider declares as advanced.
@@ -36,6 +38,27 @@ A vendor's "completed" moves nothing by itself. The engine downloads the signed
36
38
  A document that fails any check leaves the request open (the poll reads it again). One that validates but proves another
37
39
  signer or a lower level ends it FAILED.
38
40
 
41
+ ## A vendor's test environment
42
+
43
+ A vendor's sandbox (Yousign's, DocuSign's demo) applies no legal signature: its document carries a visual signature only,
44
+ so it never validates. In a development or test runtime, when the vendor reports the request complete and the validator
45
+ refuses its document, the engine still records the request SIGNED, so the whole flow can be run before production:
46
+
47
+ - it moves through its own event, `evidence_accepted_from_test_environment`, and carries no `validatedAt`: a SIGNED
48
+ request with `validatedAt` validated, one without it did not, and nothing names it as a validated copy;
49
+ - the evidence file says `standing: accepted_from_test_environment` and keeps the validator's refusal as
50
+ `testEnvironmentRefusal`; it proves no signer;
51
+ - the `SIGNATURE_REQUEST_MOVED` event says `evidenceStanding: accepted_from_test_environment`;
52
+ - the vendor returning exactly the bytes that were sent is never accepted: that is a provider downloading the original,
53
+ which would leave every production request open, and the sandbox run is where it must show;
54
+ - a document that proves ANOTHER signer or a lower level is still refused (FAILED);
55
+ - both conditions are required: a NON_PRODUCTION vendor environment AND a development or test runtime. Startup already
56
+ refuses a vendor test environment anywhere else, and an undeclared runtime environment is production.
57
+
58
+ In production nothing changes: a document that does not validate keeps the request open, and the backend logs why, once
59
+ per request and kind of refusal (`its evidence is refused`), with the validator's own words, so a vendor whose real documents
60
+ the validator refuses is diagnosed rather than guessed at.
61
+
39
62
  ## The evidence it keeps
40
63
 
41
64
  A SIGNED request names two files of its own, written in the same move: the signed PDF (a vendor-signed copy of the
@@ -67,6 +90,10 @@ poll re-reads that request within five minutes.
67
90
  ## Stated limits
68
91
 
69
92
  - One document per request. A request the vendor split into several documents is left open.
93
+ - The vendor environment is read when the request is re-read (from the provider's base URL then), not recorded when it
94
+ was sent. Switching a provider's base URL between sandbox and production while requests are open makes them read in
95
+ the new environment: anchors chosen, and a test-environment acceptance decided, by the URL in force. Development only,
96
+ since production refuses a sandbox URL at startup.
70
97
  - A signer's e-mail address is compared as it is now. One changed since the invitation does not match the certificate;
71
98
  a signer with no address on record leaves the request open.
72
99
  - An OCSP response the signature carries counts only once it verifies (signed by the certificate's issuer or a responder
@@ -198,11 +198,12 @@ offered at turn start, except on a turn an inbound delivery started and when no
198
198
  on the audit trail. The server's answers are another party's text: declare `contentGuardrails.promptInjection` (Step 4).
199
199
 
200
200
  **Another party's A2A agent.** Declare it on the backend domain module's `flowsActors.remoteAgents` and list its `ref`
201
- in the agent's `remoteAgentRefs`; the agent is offered one tool, `a2a_<ref>`, that sends a message and returns the
202
- remote agent's answer, or the remote task still running with its ids. The contract is in
201
+ in the agent's `remoteAgentRefs`; the agent is offered `a2a_<ref>`, which sends a message and returns the remote
202
+ agent's answer or the task it opened, and inside a conversation `a2a_<ref>_task`, which reads or cancels such a task. The contract is in
203
203
  `references/framework-remote-a2a-agent-declaration-api.md`. The tool's description is your `description`, never the
204
- card's; the credential goes only to the `endpointUrl` you named or, without one, to the card's own host; the model
205
- cannot continue or cancel a remote task, and one still running at `callMs` comes back with its state and ids. The same credential, inbound-delivery and audit rules as an MCP server
204
+ card's; the credential goes only to the `endpointUrl` you named or, without one, to the card's own host; a task id is
205
+ honoured only for a task the same conversation opened with the same credential, and anything else is refused and
206
+ recorded. The same credential, inbound-delivery and audit rules as an MCP server
206
207
  apply, and so does `promptInjection`.
207
208
 
208
209
  ### Step 4: Declare the use, the guardrails and the approval gates
@@ -514,6 +514,11 @@ export interface FunctionTool {
514
514
  * you write by hand, whose input would not read back as records.
515
515
  */
516
516
  presentsRecords?: boolean;
517
+ /**
518
+ * The resources whose records the tool SHOWS as cards. Set by {@link presentRecordsTool}; registration refuses one a card
519
+ * cannot read ({@link presentRecordsAddressabilityProblems}, #4011).
520
+ */
521
+ presentedResourceTypes?: readonly ResourceType[];
517
522
  /**
518
523
  * The resources the tool SEARCHES through the retrieval index (#2300). Set by {@link retrievalTool}; startup refuses an
519
524
  * application whose retrieval tool names a resource that declares no `.ragSource()` field, which would otherwise
@@ -13,6 +13,21 @@ contribution shape:
13
13
  each part draws the "not injected" placeholder (visible in development, empty in
14
14
  production) and the console warns. Import type
15
15
  from `@wildo-ai/saas-frontend-lib/companion`.
16
+ - Opening one conversation by link: link to `/conversation?system=<systemRef>&id=<executionId>&context=<contextRef>`,
17
+ the address the engine's own notices and emails use (`conversationLinkPathOf` builds it; `context` is the
18
+ conversation's stored context and may be left out). The page first switches the person to the organization the
19
+ context names, by the same rules a route uses (it says the conversation cannot be opened when the session cannot be
20
+ there). Then, when the context names a record whose resource composite declares `conversationSystemRef` for this
21
+ system, it opens that composite on that record; otherwise the FIRST `flowsActorsViews` entry with that `systemRef`
22
+ (so an assistant whose conversations people are told about needs a view, or the link says the view does not exist).
23
+ The view opens the conversation when the person's history holds it, reading it by id when it is older than the
24
+ newest page; otherwise it says it cannot be opened here and offers a new one, and nothing can be sent until that is
25
+ known. Do not link to a view's own page with a `?conversation=` parameter: on a view already open, that address is
26
+ read as a change of view state and ignored.
27
+ - A chat placed on a record (a resource composite rendering `FlowsActorsView` with the record in
28
+ `contextResourceIdentifiers`): declare `conversationSystemRef: '<systemRef>'` on that composite. Its discussions are
29
+ listed only there, so this is how a link to one finds the page; the engine then hands the linked discussion to the
30
+ `FlowsActorsView` of that system inside it, and your component passes nothing for it.
16
31
  - The backend module contribution `flowsActors` — where `flowActorSystemsFactoryMap`,
17
32
  `agents`, and **`functionTools`** are registered. (The `functionTools` field is
18
33
  the one you populate with `resourceReadTool(...)` instances.)
@@ -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> => {
@@ -4,18 +4,52 @@ Read this when an agent should hand a task to an agent someone else runs, over A
4
4
  `FlowsActors_RemoteAgent` you put on a backend domain module's `flowsActors.remoteAgents`, and whose `ref` an
5
5
  agent lists in `capabilities.tools.remoteAgentRefs`.
6
6
 
7
- What the calling agent gets:
8
-
9
- - One tool per remote agent, named `a2a_<ref>`, described by YOUR `description` (the remote card's own text never
10
- reaches the model). It takes one argument, `message`, and returns `{ answer, taskState?, taskId?, contextId? }`, or
11
- `{ error, detail, taskId?, contextId? }` naming how the call failed (`refused_target`, `unreachable`, `timed_out`,
12
- `protocol_error`, `remote_task_failed`, `remote_request_refused`, `incompatible_agent`, `rate_budget_exhausted`), with
13
- the remote task's ids when one was opened before the failure.
14
- - Each call is a new request: the remote agent answers it directly or opens a new task. The model cannot pass a task or
15
- context id, so it cannot continue, read or cancel a remote task. A task still running when `callMs` elapses comes back
16
- as an answer carrying its last-read state and ids, and keeps running there; it is never cancelled.
17
- - A blank or missing `message` is refused before anything is sent.
18
- - The tool is offered only when a credential resolves for `credential.subject`, never on a turn an inbound delivery
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
19
53
  started, and never under the name of a tool already offered that turn.
20
54
 
21
55
  What the runtime does on each call:
@@ -27,13 +61,17 @@ What the runtime does on each call:
27
61
  at exactly that URL, which is also the URL the credential is resolved for; without it, the card's first such
28
62
  interface, and only when it is on the card's own host. A card whose interface is on another host is refused unless
29
63
  you declared that interface as `endpointUrl`.
30
- - Sends `SendMessage`, then reads the task with `GetTask` until it ends, pauses for input or `callMs` elapses. Every
31
- JSON-RPC request carries `A2A-Version: 1.0`. Each response body is read within the same deadline and refused past a
32
- size ceiling.
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.
33
68
  - Goes through the outbound guard, so a private, loopback or metadata address is refused before anything leaves, and
34
69
  through the connection's rate budget when the credential has one.
35
- - Records every call as an `a2a_remote_agent_call` audit row: the remote agent, the host the credential went to, the
36
- outcome, the remote task id and state, and whose credential it spent. Never the message, never the answer.
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.
37
75
 
38
76
  The fields:
39
77
 
@@ -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). */
@@ -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
  */
@@ -482,6 +482,13 @@ when the parent's `recurringType` is `RECURRING`:
482
482
  {
483
483
  nature: RelationshipNature.COMPOSITION,
484
484
  foreignKeyField: 'todoId',
485
+ // OPTIONAL_CONTEXT, as for tasks: an occurrence is routed under its todo (the todo page lists them) AND directly
486
+ // under its organization, `/organizations/{organizationId}/todos-recurring-occurrences/{todosRecurringOccurrenceId}`.
487
+ // A record shown by id alone needs the second: the Todo Assistant's cards (`presentRecordsTool`) know the
488
+ // organization and the record, never its todo, so with only the nested route a card read "Unavailable" (no
489
+ // endpoint) and opened nothing (#4011). Every occurrence carries its own `organizationId` (the anchor above), so the
490
+ // organization-level route is confined by tenancy like every other organization resource.
491
+ accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.OPTIONAL_CONTEXT,
485
492
  // Static discriminator: only applies when parent todo is RECURRING
486
493
  discriminator: { discriminatorField: todosRecurringTypeField, values: [Todos_RecurrenceType.RECURRING] },
487
494
  // LAZY: a recurring todo gains an occurrence every time it comes due, so a daily todo's set only grows, and deleting
@@ -340,7 +340,24 @@ endpoint host (Workday's `WORKDAY_API_HOST` names its token endpoint too),
340
340
  the connect flow refuses a loopback host in every environment, because that
341
341
  endpoint is the vendor's `https` host and receives the client secret. A
342
342
  provider whose account is connected through OAuth2 cannot be connected to a
343
- local double this way.
343
+ local double through a host slot.
344
+
345
+ A REST provider with ONE fixed `baseUrl` (Slack's `https://slack.com/api`)
346
+ re-points the whole of it instead: declare `baseUrlOverrideEnvVarName` on the
347
+ REST contract and the same name as a REGISTRATION slot of the secrets
348
+ contract (`SLACK_API_BASE_URL`). In development and test only, a value naming
349
+ a local double (`127.0.0.1:<port>`) sends every operation there with the same
350
+ credential, and the OAuth2 token, revocation and userinfo endpoints written
351
+ under the base follow it, so an e2e lane plays the vendor's Web API and the
352
+ install's code exchange (the `authorizeUrl` is a browser address and stays the
353
+ vendor's: the lane drives the callback itself). Startup refuses it set in any
354
+ other environment, set to anything but a local double, declared beside
355
+ `baseUrlEnvVarName`, `baseUrlHostEnvVarName`, `baseUrlConnectionFact`, a
356
+ templated base or OAuth2 endpoint, `clientCredentials` or `oauth2.audiences`,
357
+ and named by no REGISTRATION slot. Over plain http the double can assert any
358
+ ID-token claim (the engine leaves that signature to TLS), which is why it is a
359
+ development tool only; `wildo local doctor` and `wildo providers probe` still
360
+ call the vendor.
344
361
 
345
362
  There is no other way to re-point a provider. `providerConfigurations` cannot
346
363
  carry `runtimeContract` or `endpoints`: those belong to the provider module,
@@ -868,7 +885,7 @@ disagree with the package.
868
885
  | "The augmentation is installed, so its operations are available." | Nothing applies until `providers.augmentations.<baseRef>` names the package and `wildo config sync` records it; the artifact grep below shows whether it did. |
869
886
  | "I declared `EXTERNAL_ERASURE_OPERATION`, so an erasure reaches the vendor." | Only with a `subjectErasureEffect` on the module AND the application's `subjectReferences`. Without the effect the stance promises a door nobody built; without the references the engine has nothing to erase by. Either way every erasure reads NOT_REGISTERED, unless the operator declared the vendor's own deletion window as the answer instead. |
870
887
  | "I will document the setting and ask the application to call my validation function at boot." | Nothing calls a function an application was asked to call. Declare it as `configurationCheck`: the backend runs it at boot and `wildo local doctor` runs it, both as a WARN, with no application code. |
871
- | "I will override the provider's `runtimeContract.baseUrl` in `providerConfigurations` to reach my local double." | The configuration is refused: the module owns where its key goes. Set the host slot to `127.0.0.1:<port>` in a development environment instead; staging and production refuse it. |
888
+ | "I will override the provider's `runtimeContract.baseUrl` in `providerConfigurations` to reach my local double." | The configuration is refused: the module owns where its key goes. Set the host slot to `127.0.0.1:<port>` in a development environment instead, or, for a fixed base URL, the module's `baseUrlOverrideEnvVarName` variable; staging and production refuse both. |
872
889
  | "Our provider also handles email, so I will give it the email arm." | Composition refuses a non-MAIN provider that declares an engine slot's runtime arm while claiming no capability for it. Declare the capability that names the slot — that is what makes it a deliberate substitution rather than an accident. |
873
890
 
874
891
  ## Red Flags
@@ -241,6 +241,18 @@ export enum EngineSettingsDestinationRef {
241
241
  * owner/admin, the roles that bind a client to an agent.
242
242
  */
243
243
  AUTONOMOUS_AGENTS = 'autonomous-agents',
244
+ /**
245
+ * What THIS organization's declared FLOWS and ACTOR SYSTEMS did (#3990): every run on the actor plane, newest first,
246
+ * and each run's history, its tasks (what each actor was asked and produced) and, for a flow, the steps it went
247
+ * through, each with when it happened, in the reader's time zone. Org owner/admin, the people the route admits (an
248
+ * administrator of the organization through an organization-wide role, or the application super-administrator).
249
+ *
250
+ * Beside {@link AGENT_RUNS}, never merged into it: those are CONVERSATIONS (a chat, an A2A client's turn) with their
251
+ * transcripts, read under the execution resource's roles; these are the runs of declared systems, which no resource
252
+ * routes. No capability gate: a flow runs with no language model, so an application declaring flows and no
253
+ * `AI_LLM` still has activity to read; one declaring neither shows an empty list, and may remove the placement.
254
+ */
255
+ AGENT_ACTIVITY = 'agent-activity',
244
256
  /**
245
257
  * Which of the application's chat agents answers the organization's people on each chat connection (#2665): Slack,
246
258
  * Microsoft Teams. Org owner/admin, the roles the `organizationChatSettings` writes accept. A connection with no choice
@@ -370,6 +382,15 @@ export enum EngineSettingsDestinationRef {
370
382
  * application row. What a run consumed is answered to an application cost reader by the run's `usage` operation.
371
383
  */
372
384
  APPLICATION_AGENT_RUNS = 'application-agent-runs',
385
+ /**
386
+ * What the declared flows and actor systems did in EVERY organization (#3990): the same page as
387
+ * {@link AGENT_ACTIVITY}, across tenants, each run naming the organization it worked for. An APPLICATION-WIDE read, so
388
+ * it is admitted under the application's audit read policy (`resolveAuditApplicationReadAccess`): the
389
+ * super-administrator role alone under ROLE_BASED, and a live application access grant a second administrator signed
390
+ * under INDEPENDENT_APPROVAL. Every read is recorded (`PLATFORM_DIRECTORY_ACCESS`, naming the grant when there is one).
391
+ * Super-admin, the role the route admits.
392
+ */
393
+ APPLICATION_AGENT_ACTIVITY = 'application-agent-activity',
373
394
  /**
374
395
  * Which agents the application's super-administrator switched off for EVERY organization (#2843), each with the
375
396
  * justification it was suspended with, and the Suspend and Resume actions. Super-admin, the role both verbs require;