@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.
- package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +12 -4
- package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +4 -0
- package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.definitions.js +9 -0
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
- package/dist/knowledge/manifest.json +7 -7
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
- package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
- package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
- package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
- package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
- package/dist/knowledge/references/example.config.navigation.full.md +14 -0
- package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +6 -2
- package/dist/knowledge/references/example.flows-actors.chat-assistant.md +13 -2
- package/dist/knowledge/references/example.inbound.email-to-todo.md +33 -2
- package/dist/knowledge/references/example.module.relationships.discriminator.md +7 -1
- package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
- package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
- package/dist/knowledge/references/integration-plan.config.md +78 -8
- package/dist/knowledge/references/platform.config.environment.deployment.md +84 -5
- package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
- package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +11 -0
- package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
- package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
- package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
- package/dist/knowledge/references/saas.models.flows-actors.mcp-server-declaration.md +63 -0
- package/dist/knowledge/references/saas.models.flows-actors.outbound-credential.md +61 -0
- package/dist/knowledge/references/saas.models.flows-actors.remote-agent-declaration.md +56 -0
- package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
- package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
- package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
- package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
- package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
- package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
- package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
- package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
- package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
- package/dist/knowledge/registries/framework-topics.json +45 -1
- package/dist/knowledge/registries/playbooks.json +2 -2
- package/dist/knowledge/registries/source-tags.json +1175 -1107
- package/dist/knowledge/skills/INDEX.md +2 -2
- package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +9 -2
- package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
- package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
- package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +21 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +15 -2
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
- package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
- package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +1 -0
- package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +15 -1
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
- package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +12 -5
- package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
- package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
- package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
- package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
- package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +34 -3
- package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +11 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +15 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +169 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
- package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +39 -13
- package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +84 -5
- package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
- package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
- package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
- package/dist/knowledge/skills/module-relationships/SKILL.md +20 -1
- package/dist/knowledge/skills/provider-backend-package/SKILL.md +13 -2
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
- package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
- package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
- package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
- package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
- package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -3
- package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
- package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
- package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
- package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
- package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
- package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
- package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
- package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
- package/dist/knowledge/topic-index.json +326 -179
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +4 -4
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: electronic-signature-deliverables
|
|
3
|
-
description: Have a deliverable a person approved signed by them with their own electronic signature, through a trust-service vendor, after the approval is sealed. Covers `FunctionTool.electronicSignature` (the level and who signs), the `ELECTRONIC_SIGNATURE` capability and its provider, what makes a signature request SIGNED (the validated signed document, never the vendor's word), the evidence it keeps, and the vendor's notifications. Use when the user says "the client must e-sign the engagement letter", "send the approved report for electronic signature", "we need an advanced electronic signature", "eIDAS signature on the deliverable", "the signature request stays open",
|
|
3
|
+
description: Have a deliverable a person approved signed by them with their own electronic signature, through a trust-service vendor, after the approval is sealed. Covers `FunctionTool.electronicSignature` (the level and who signs), the `ELECTRONIC_SIGNATURE` capability and its provider, what makes a signature request SIGNED (the validated signed document, never the vendor's word), the evidence it keeps, and the vendor's notifications. Use when the user says "the client must e-sign the engagement letter", "send the approved report for electronic signature", "we need an advanced electronic signature", "eIDAS signature on the deliverable", "the signature request stays open", "why is the signed document rejected", or "let the client sign inside the app".
|
|
4
4
|
user-invocable: false
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -25,7 +25,8 @@ electronic signature. Some deliverables need more: the approver's OWN advanced e
|
|
|
25
25
|
trust-service vendor (an engagement letter, a regulated filing, a contract). This is opt-in per deliverable. You declare
|
|
26
26
|
it on the agent tool whose call names the file; once a person approves the call and its seal is SEALED, the engine sends
|
|
27
27
|
exactly the approved bytes to the vendor, tracks the request, and makes it SIGNED only when the signed PDF the vendor
|
|
28
|
-
returns validates
|
|
28
|
+
returns validates: its signature covers the document and nothing was added after it, and, when the provider pins its
|
|
29
|
+
vendor's certificates (an advanced level needs them), it chains to one. Nothing in your code sends, polls or validates.
|
|
29
30
|
|
|
30
31
|
## App Paths
|
|
31
32
|
|
|
@@ -35,6 +36,7 @@ returns validates against the trust anchors its provider pins. Nothing in your c
|
|
|
35
36
|
| The capability and its provider | `wildo.saas.config.ts` → `engineCapabilities` (`ELECTRONIC_SIGNATURE`) and its provider selection |
|
|
36
37
|
| The vendor's notification endpoint | the provider's contract (`notificationEndpointKey`), enabled with the provider's webhooks |
|
|
37
38
|
| The requests and their evidence | the engine's `signatureRequests` resource (route-less; read through the service tier) |
|
|
39
|
+
| Signing inside the application | `frontend/src/**` → the record's page renders `EmbeddedSigningFrame` |
|
|
38
40
|
|
|
39
41
|
## When to Use
|
|
40
42
|
|
|
@@ -66,11 +68,14 @@ returns validates against the trust anchors its provider pins. Nothing in your c
|
|
|
66
68
|
deliverable, re-reads open requests, and moves a request to SIGNED only on a validated signed document, keeping the
|
|
67
69
|
signed PDF and the validation's evidence. Declined, expired and cancelled requests end; a document that proves another
|
|
68
70
|
signer or a lower level ends the request FAILED; a document that does not validate leaves it open.
|
|
69
|
-
6. **
|
|
71
|
+
6. **Let signers sign inside the application** (optional), with a provider claiming `EMBEDDED_ELECTRONIC_SIGNATURE`
|
|
72
|
+
(Yousign, DocuSign): render `EmbeddedSigningFrame` on the record's page and admit the vendor's frame origin in the
|
|
73
|
+
frontend's CSP. See `references/signing-inside-the-application.md`.
|
|
74
|
+
7. **Verify** with the checks below, then run the migration skill: the request's evidence fields are columns.
|
|
70
75
|
|
|
71
76
|
## Worked Example
|
|
72
77
|
|
|
73
|
-
<!-- TIER C WAIVER:
|
|
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. -->
|
|
74
79
|
```ts
|
|
75
80
|
export const sendEngagementLetter: FunctionTool = {
|
|
76
81
|
functionRef: 'ledger.sendEngagementLetter',
|
|
@@ -89,6 +94,7 @@ signed PDF validates.
|
|
|
89
94
|
## References
|
|
90
95
|
|
|
91
96
|
- `references/what-makes-a-request-signed.md` — the request's states, what the validation checks, the evidence it keeps, the notifications, and the stated limits.
|
|
97
|
+
- `references/signing-inside-the-application.md` — embedded signing: what the provider declares, the `EmbeddedSigningFrame` component, its route and its answers.
|
|
92
98
|
- The tool's `electronicSignature`, `deliverableFileArgument` and approval gate are documented in `flows-actors-chat-assistant`'s `references/framework-flows-actors-tool-api.md`.
|
|
93
99
|
|
|
94
100
|
## Verification
|
|
@@ -114,13 +120,14 @@ rg -n "requiredLevel: *'|signers: *\[ *'" backend-api/src
|
|
|
114
120
|
| "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. |
|
|
115
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. |
|
|
116
122
|
| "Let the model choose who signs." | Signers come from a closed vocabulary (`FunctionTool_SignerSource`), never from what the model wrote. |
|
|
123
|
+
| "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. |
|
|
117
124
|
| "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. |
|
|
118
125
|
|
|
119
126
|
## Red Flags
|
|
120
127
|
|
|
121
128
|
- A tool declaring `electronicSignature` with no `deliverableFileArgument` — startup refuses it; catch it with the declarations command.
|
|
122
129
|
- A string literal level or signer — catch with the literal command.
|
|
123
|
-
- Requests staying open with "
|
|
130
|
+
- Requests staying open with "does not chain" — the provider's contract pins the wrong environment's anchors; the capability check catches a missing provider.
|
|
124
131
|
- A deliverable sent from tool code by hand — catch it by reviewing every file the declarations command lists.
|
|
125
132
|
|
|
126
133
|
## Related Skills
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Signing inside the application (embedded signing)
|
|
2
|
+
|
|
3
|
+
By default the vendor e-mails each signer a link to its signing page. With embedded signing, a signer who is signed in to
|
|
4
|
+
your application signs in a frame of it instead, on the page where they meet the record.
|
|
5
|
+
|
|
6
|
+
## Which vendors can
|
|
7
|
+
|
|
8
|
+
Embedded signing is its own provider capability, `EMBEDDED_ELECTRONIC_SIGNATURE`, claimed beside
|
|
9
|
+
`ELECTRONIC_SIGNATURE` by a provider whose vendor answers a signing page URL the application can frame:
|
|
10
|
+
|
|
11
|
+
| Vendor | Embedded | Registry provider |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| Yousign | yes | `providers/yousign` |
|
|
14
|
+
| DocuSign | yes (the application's own account, JWT grant) | `providers/docusign-esignature` |
|
|
15
|
+
| BoldSign, SignNow, Adobe Acrobat Sign | the vendor can | none yet |
|
|
16
|
+
| IgniSign, Dropbox Sign, Universign | no: their embedded mode needs their own browser script | IgniSign: `providers/ignisign`, e-mail only |
|
|
17
|
+
|
|
18
|
+
## What it takes
|
|
19
|
+
|
|
20
|
+
1. **A provider that claims it.** Its contract carries an `embeddedSigning` block (the vendor's frame origins, and two
|
|
21
|
+
functions: build the vendor call that asks for one signer's signing page, and read its URL from the answer, or `null`
|
|
22
|
+
while it is not that signer's turn) and lists `openSigningSession` in its `operations`. A claim without the block
|
|
23
|
+
refuses startup; a block without the claim is never offered. Whether its signers sign in the application or from the
|
|
24
|
+
vendor's e-mail is the provider's own configuration, a constant at the top of its `exchange.ts`.
|
|
25
|
+
2. **The vendor's frame origins in the CSP, which you do not write.** `wildo config sync` records the origins the
|
|
26
|
+
provider declares, and `wildo dev sync-csp` adds them to the SaaS frontend's `frame-src`: run both after installing or
|
|
27
|
+
selecting the provider. The engine refuses a signing page on any other origin. Some vendors also require your
|
|
28
|
+
application's domain to be allowed in their own dashboard (Yousign) before their page may be framed.
|
|
29
|
+
3. **Room at the bottom of the last page.** Each signer's signature field goes there, two per row: vendors that need a
|
|
30
|
+
placed field (DocuSign, Yousign) get the last page the engine measured.
|
|
31
|
+
4. **The frame on the record's page**, from `@wildo-ai/saas-frontend-lib`:
|
|
32
|
+
|
|
33
|
+
## Import Origins
|
|
34
|
+
|
|
35
|
+
- `@wildo-ai/saas-frontend-lib`
|
|
36
|
+
|
|
37
|
+
## Source Excerpts
|
|
38
|
+
|
|
39
|
+
### Origin Package: `@wildo-ai/saas-frontend-lib`
|
|
40
|
+
|
|
41
|
+
```tsx
|
|
42
|
+
/**
|
|
43
|
+
* Embedded signing: the signed-in person signs a record's deliverable at the signature vendor, inside a frame of the
|
|
44
|
+
* application, instead of following the vendor's e-mail. Import from `@wildo-ai/saas-frontend-lib`.
|
|
45
|
+
*
|
|
46
|
+
* Place it where the person meets the record (an engagement letter's page, say). On mount it asks the backend for the
|
|
47
|
+
* vendor's signing page (`signatureRequestSigners.openSigningSession`). The answer is given only to a signer an open
|
|
48
|
+
* request on that record names and the vendor says has not signed yet, so for anybody else, once the person has signed,
|
|
49
|
+
* and when the request's provider signs from its e-mail only, the component renders NOTHING. The page is valid for
|
|
50
|
+
* 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
|
|
51
|
+
* has not come (signers who sign in turn) is shown nothing either, until it does.
|
|
52
|
+
*
|
|
53
|
+
* When the person is done, a vendor that redirects sends the frame to the application's own {@link SIGNING_RETURN_PAGE_PATH};
|
|
54
|
+
* the frame sees it arrive (it is now same-origin), closes, and calls `onSigningReturned`. A vendor that does not redirect
|
|
55
|
+
* (or redirects to another of the application's origins) keeps showing its own end page. Either way nothing here says the
|
|
56
|
+
* document is signed: every vendor's own guidance is that the end of the frame is not the outcome, and the request becomes
|
|
57
|
+
* SIGNED only once the engine has validated the signed document, at its next re-read (poll or vendor notification).
|
|
58
|
+
*
|
|
59
|
+
* What it needs elsewhere: a provider that claims `EMBEDDED_ELECTRONIC_SIGNATURE` and declares `embeddedSigning`, and a
|
|
60
|
+
* `wildo config sync` then `wildo dev sync-csp` since it was added, which put the vendor's signing origins in the SaaS
|
|
61
|
+
* frontend's CSP `frame-src` from the provider's own declaration; without them the browser refuses to load the frame.
|
|
62
|
+
*
|
|
63
|
+
* It renders no words of its own: the application passes the frame's accessible `title`.
|
|
64
|
+
*/
|
|
65
|
+
export interface EmbeddedSigningFrameProps {
|
|
66
|
+
/** The record the deliverable belongs to: the signature request's `linkedResourceType`. */
|
|
67
|
+
readonly linkedResourceType: string;
|
|
68
|
+
/** The record the deliverable belongs to: the signature request's `linkedResourceId`. */
|
|
69
|
+
readonly linkedResourceId: string;
|
|
70
|
+
/** The frame's accessible name (WCAG 4.1.2), in the person's language, e.g. "Sign the engagement letter". */
|
|
71
|
+
readonly title: string;
|
|
72
|
+
/** Called once the person left the vendor's page. Re-read the record if you show its signature state. */
|
|
73
|
+
readonly onSigningReturned?: () => void;
|
|
74
|
+
readonly className?: string;
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Give it the record the deliverable belongs to (the same `linkedResourceType` / `linkedResourceId` the request carries) and
|
|
79
|
+
the frame's accessible title, from your labels.
|
|
80
|
+
|
|
81
|
+
## What happens
|
|
82
|
+
|
|
83
|
+
- On mount the frame asks `POST /api/v1/applications/{applicationId}/signature-request-signers/open-signing-session`.
|
|
84
|
+
Any signed-in user may ask; a page is answered only to a signer an open request on that record names, keyed on the
|
|
85
|
+
caller's own user id, on their own request: a machine credential or a one-off token is refused, and a client the person
|
|
86
|
+
delegated to (A2A, MCP) cannot reach the route at all. Before opening a page the engine asks the vendor whether this
|
|
87
|
+
signer has already signed. For
|
|
88
|
+
anyone else, once the person has signed, and when the request's provider signs from its e-mail only, the frame renders
|
|
89
|
+
nothing.
|
|
90
|
+
- Each opening is a HIGH-risk operation, so the audit trail records who opened a signing page and when.
|
|
91
|
+
- The page URL is valid for minutes and is never stored, which is why it is asked for when the person is in front of it.
|
|
92
|
+
- When the person is done, a vendor that redirects sends the frame to the application's own signing-return page
|
|
93
|
+
(`SIGNING_RETURN_PAGE_PATH`; the engine hands it to the vendor when sending and when opening the session), the frame
|
|
94
|
+
closes and calls `onSigningReturned`. A vendor that does not redirect keeps showing its own end page. Neither says the
|
|
95
|
+
document is signed: the request becomes SIGNED only once the engine has validated the signed document, at its next
|
|
96
|
+
re-read.
|
|
97
|
+
|
|
98
|
+
| Answer | Meaning |
|
|
99
|
+
|---|---|
|
|
100
|
+
| 201 | The signing page: its `url` and, when the vendor says, `expiresAt` |
|
|
101
|
+
| 400 | The return URL is not on one of the application's own frontends |
|
|
102
|
+
| 403 | Not a person on their own request (a machine credential, a one-off token) |
|
|
103
|
+
| 404 | Nothing on that record left for this person to sign |
|
|
104
|
+
| 409 | The request's provider signs from its e-mail only (the frame renders nothing) |
|
|
105
|
+
| 502 | The vendor answered no page; asking again may succeed |
|
|
106
|
+
|
|
107
|
+
## Limits
|
|
108
|
+
|
|
109
|
+
- Only the signer can be shown their page. An administrator cannot open it on their behalf.
|
|
110
|
+
- A signer whose turn has not come (signers who sign in turn) is shown nothing until it does.
|
|
111
|
+
- The return page renders nothing: the application's root does not boot on it, so no session is restored inside the frame.
|
|
112
|
+
- With a provider whose vendor sends no e-mail to an embedded signer, the person learns of the document only where your
|
|
113
|
+
application shows the frame. Put it where they will see it, or tell them yourself.
|
|
@@ -207,10 +207,10 @@ co-location conventions.
|
|
|
207
207
|
|
|
208
208
|
### Step 4: Contribute the definition through its owning module
|
|
209
209
|
|
|
210
|
-
Inspect the
|
|
210
|
+
Inspect the owning backend module's `emailTemplateDefinitions` slot first. A business module's emails live in `backend-api/src/modules/<module>/emails/`, registered by `emails/module-email-template-definitions.ts` scanning `resources/` (and `system/`); never create `email/` or another folder for them, and never add a second definitions file. The build lane's `check:module-layout` refuses a module's email definitions outside `emails/` and states the move (`mv`) that corrects it. If the module registers them elsewhere, move them to `emails/` (folder and imports) before adding the template.
|
|
211
211
|
|
|
212
212
|
- The scanner loads `template.js` default exports and co-located `labels.<locale>.js` named `labels` exports. Author their TypeScript sources and let the normal compiler publish them; a new `.tsx` file alone is not a loaded runtime template.
|
|
213
|
-
- The scanner's `keyFromPath` owns the template ref. The skeleton maps `system/<name>` to `system.<name_with_underscores>`, and under `resources/` turns the path into the ref by replacing `/` with `.`.
|
|
213
|
+
- The scanner's `keyFromPath` owns the template ref. The skeleton maps `system/<name>` to `system.<name_with_underscores>`, and under `resources/` turns the path into the ref by replacing `/` with `.`. A business module's scanner keeps that standard mapping (`subdir` written as a string, `keyFromPath` returning `` `email.${…}` `` with `/` turned into `.`): the companion reads the folder and the prefix from the call to place generated templates, and assumes the rest of the mapping. Match the sender's typed ref to it; creating an enum with a different value does not rename the scanned ref.
|
|
214
214
|
- **An operation's email (a `userNotifications` EMAIL entry) has a derived ref:** `email.<resource>.<operation>[.<variantKey>].<target>[_<customNotificationRef>]`, so its directory is `resources/<resource>/<operation>[.<variantKey>].<target>[_<customNotificationRef>]/` — for example `resources/todos/change_status.admin.users-custom_notify-creator/`. The target segment is always there, and an operation with a keyed variant needs one template per variant. A missing one only WARNS at startup (it refuses only for a token-bearing operation), and the email is silently never sent. Read `references/framework-operation-email-template-ref-api.md` before naming the directory.
|
|
215
215
|
- **Declare before you code.** A non-user recipient at an address on the record is `recipientEmailField`; another organization named on the record (the other party of something two organizations share) is `recipientOrganizationIdField` on an organization target; an email owed whatever the preferences is `alwaysDeliver: true`. Send from custom code with `EmailBackendService.send` only for an attachment, several or nested addresses, cc / bcc / threading, or a non-user's own language. Read `references/framework-email-send-api.md`.
|
|
216
216
|
- Contribute the resulting map through the existing owning backend module. For an explicit map, add the imported definition and locale labels there; for a scanner, put the correctly exported files under the scanned directory. Do not manually edit generated definitions or add duplicate registrations.
|
|
@@ -391,6 +391,7 @@ single self-contained reference shape for app developers.
|
|
|
391
391
|
- [ ] Labels exist for **every** user-visible string (one key per string), satisfying the typed `TLabels` interface key-for-key
|
|
392
392
|
- [ ] Labels files exist for every supported locale (parallel key sets across locales)
|
|
393
393
|
- [ ] Compiled template and labels resolve under the owning module’s scanner/map, and its ref matches the sender’s typed id
|
|
394
|
+
- [ ] A business module's email definitions file and templates are under `backend-api/src/modules/<module>/emails/` (the build lane's `check:module-layout` refuses any other folder; `rg -l 'scanEmailTemplateDirectory' backend-api/src/modules` lists only `emails/` files)
|
|
394
395
|
- [ ] An operation email's directory carries the full derived ref (`<operation>[.<variantKey>].<target>[_<customNotificationRef>]`), one per keyed variant, and startup logs no unresolved operation email
|
|
395
396
|
- [ ] Definition explicitly selects `EmailTemplateType.*` and the corresponding provider capability is configured
|
|
396
397
|
- [ ] Definition is typed `EmailTemplateDefinition<TLabels>` (not `any`, not bare `EmailTemplateDefinition`)
|
|
@@ -1,17 +1,21 @@
|
|
|
1
1
|
# Email template ownership and artifact paths
|
|
2
2
|
|
|
3
|
-
Locate the owning backend module's `emailTemplateDefinitions` contribution first
|
|
3
|
+
Locate the owning backend module's `emailTemplateDefinitions` contribution first, and keep templates where its definitions file scans.
|
|
4
|
+
|
|
5
|
+
**A business module's emails live in `backend-api/src/modules/<module>/emails/`, and nowhere else.** That folder holds the definitions file, `emails/module-email-template-definitions.ts`, which calls `scanEmailTemplateDirectory` over `resources/` (and `system/` when the module has system emails) beside it, and the template folders it scans. The module contributes the resulting map as its `emailTemplateDefinitions`. Do not create `email/`, `mail/`, `templates/` or any other folder for a module's emails, and do not put the definitions file at the module's root: the companion writes a module's generated templates, and its preview imports them, under `emails/`, so a template registered from anywhere else is generated where nothing registers it.
|
|
6
|
+
|
|
7
|
+
This is checked. In the build lane, every coding run that writes under a package's `src/modules/`, and the end-of-build checks, run `check:module-layout`, which refuses a file that calls `scanEmailTemplateDirectory` (or is named like a module email definitions file) outside `<module>/emails/`, and states the correction: the `mv` (renaming the whole folder when the folder is the misplaced unit, `mv <module>/email <module>/emails`) and every import to update. Outside the build lane, `rg -l 'scanEmailTemplateDirectory' backend-api/src/modules` must list only files under an `emails/` folder. If a module you work in registers its emails elsewhere, move them there; do not follow the misplaced layout. Write the scanner's `subdir` as a string literal and `keyFromPath` as a function returning `` `email.${…}` `` (or `` `system.${…}` ``): the companion reads both from the call to know which folder registers which refs, and writes nothing for a module whose scanner it cannot read.
|
|
4
8
|
|
|
5
9
|
| Artifact | Current scanner contract |
|
|
6
10
|
|---|---|
|
|
7
11
|
| Authored template | `template.tsx` with a default `EmailTemplateDefinition<TLabels>` export |
|
|
8
12
|
| Authored labels | Co-located `labels.<locale>.ts` with named `labels` export satisfying `TLabels` |
|
|
9
13
|
| Runtime artifacts | Compiled `template.js` and `labels.<locale>.js` under the owning scanner directory |
|
|
10
|
-
| Definition collection | `scanEmailTemplateDirectory` from `@wildo-ai/saas-backend-lib`,
|
|
14
|
+
| Definition collection | `scanEmailTemplateDirectory` from `@wildo-ai/saas-backend-lib`, called from `<email root>/…-email-template-definitions.ts` (a business module's email root is `emails/`) |
|
|
11
15
|
| Runtime wiring | Existing owning backend module contributes the resulting `emailTemplateDefinitions` map |
|
|
12
16
|
|
|
13
17
|
The scanner starts beside its caller's `import.meta.url`, scans its configured `subdir` recursively and uses `keyFromPath` to derive refs. Its default extension is `.js`. It imports the template's default export and the labels module's named `labels` export (also accepts `default.labels`). It does not infer refs from a new enum or inspect an arbitrary TypeScript source folder.
|
|
14
18
|
|
|
15
|
-
In the current skeleton, `backend-api/src/engine/email/email-template-definitions.ts` scans `system/` and `resources/`. `system/password-reset` becomes `system.password_reset`; under `resources/`, `/` becomes `.`, so an operation email for `tasks` / `assign` / target `USER_SELF` lives in `resources/tasks/assign.user-self` and registers `email.tasks.assign.user-self` (the full rule: `references/framework-operation-email-template-ref-api.md`). The engine backend module contributes the map.
|
|
19
|
+
In the current skeleton, `backend-api/src/engine/email/email-template-definitions.ts` scans `system/` and `resources/`. `system/password-reset` becomes `system.password_reset`; under `resources/`, `/` becomes `.`, so an operation email for `tasks` / `assign` / target `USER_SELF` lives in `resources/tasks/assign.user-self` and registers `email.tasks.assign.user-self` (the full rule: `references/framework-operation-email-template-ref-api.md`). The engine backend module contributes the map. That layout is the ENGINE owner's email root (`backend-api/src/engine/email/`, singular, owned by the skeleton); do not copy its folder name into a business module, whose emails live in `emails/` as stated above, and do not move a business module's emails into the engine.
|
|
16
20
|
|
|
17
|
-
|
|
21
|
+
An explicit map (templates imported one by one, no scanner) cannot be read by the companion, which then generates and previews nothing for that module and says so; replace it with the scanner in `emails/` when you work in such a module. For a scanner, adding a correctly named/default-exported template and named locale exports under its root is the registration input; no per-template manual entry is required. In either case, normal compilation/publication and module loading must make the ref visible. Match the sender's typed identifier to the derived ref and verify through preview. Never hand-edit compiled artifacts to make a missing source registration appear fixed.
|
|
@@ -43,7 +43,7 @@ grep is the high-signal check.
|
|
|
43
43
|
2. You did NOT copy the workflow into this stub or re-author it
|
|
44
44
|
elsewhere — the canonical orchestrator stays the single source of
|
|
45
45
|
truth.
|
|
46
|
-
3. The new template
|
|
46
|
+
3. The new template's folder is under the email root its definitions file scans — a business module's `emails/`, which is the ONLY place a module's email definitions may live (`check:module-layout` refuses any other folder and states the move; see `email-add-template`'s `references/email-artifact-paths.md`), the engine's `backend-api/src/engine/email/` — so `ls backend-api/src/modules/<module>/emails/resources/<template-path>` (or the engine's `system/`/`resources/` equivalent) lists it. Ids are derived from that path, never written into the definitions file.
|
|
47
47
|
4. No sender service imports the template module directly — `rg -n "from\s+['\"].*engine/email/<template>/template['\"]" backend-api/src/modules/<module>/` returns empty.
|
|
48
48
|
|
|
49
49
|
## Red Flags
|
|
@@ -27,7 +27,9 @@ transport — you author almost nothing:
|
|
|
27
27
|
- **Exposure is automatic.** Every ACTOR system with an AGENTIC actor bound to an
|
|
28
28
|
agent is served as one A2A skill (`skill.id === system.ref`). Build the actor
|
|
29
29
|
system exactly as for the in-app assistant (`flows-actors-chat-assistant`); no
|
|
30
|
-
per-system A2A flag.
|
|
30
|
+
per-system A2A flag. Give the system `tags` (the keywords another agent matches a
|
|
31
|
+
skill by): A2A 1.0 requires every skill to carry at least one, and a system with
|
|
32
|
+
none is served with its `category`, else its `ref`, as its only tag.
|
|
31
33
|
- **The engine serves two endpoints**: a public agent card at
|
|
32
34
|
`GET /a2a/.well-known/agent-card.json` (discovery) and the Bearer-authenticated
|
|
33
35
|
JSON-RPC endpoint `POST /a2a` (`message/send` blocking, `message/stream` SSE).
|
|
@@ -64,6 +66,9 @@ scope-isolated variants.
|
|
|
64
66
|
actor system; that skill builds the WebSocket view).
|
|
65
67
|
- **Exposing resource CRUD as callable tools** to external agents → that is **MCP**
|
|
66
68
|
(`operation.mcp.exposed`) — the sibling skill `resource-mcp-tool-exposure`, not A2A.
|
|
69
|
+
- **Your agent calling ANOTHER party's A2A agent** (the outbound direction) → declare it in
|
|
70
|
+
`flowsActors.remoteAgents` and name it in the agent's `remoteAgentRefs`; see
|
|
71
|
+
`flows-actors-chat-assistant`, `references/framework-remote-a2a-agent-declaration-api.md`.
|
|
67
72
|
- **A one-shot generation agent** with no conversation → a plain `FlowsActors_Agent`
|
|
68
73
|
invoked by your own service.
|
|
69
74
|
|
|
@@ -81,8 +86,8 @@ declarations in `shared-lib` themselves.)
|
|
|
81
86
|
External agents get a token from YOUR app's OIDC provider. For **user-delegated**
|
|
82
87
|
callers, the `authorizationCode` flow issues a token whose `aud` is the agent card
|
|
83
88
|
`url`. For **machine** callers, provision an **OAuth client** (org- or app-scoped)
|
|
84
|
-
and use the `clientCredentials` flow.
|
|
85
|
-
|
|
89
|
+
and use the `clientCredentials` flow. The agent card always advertises both, as two
|
|
90
|
+
security schemes (`oauth2` and `oauth2ClientCredentials`) either of which satisfies it.
|
|
86
91
|
|
|
87
92
|
### Step 3: Understand what external agents do (you do not author this)
|
|
88
93
|
1. `GET /a2a/.well-known/agent-card.json` → the card (skills + `securitySchemes`).
|
|
@@ -97,6 +102,12 @@ machine turn persists to `organization`/`applicationFlowActorExecutions` (owned
|
|
|
97
102
|
the org/app). Each is scope-isolated — a caller only ever sees its own scope's
|
|
98
103
|
conversations. Nothing to author; confirm the right variant is written.
|
|
99
104
|
|
|
105
|
+
To let an agent that does NOT run on your machine reach a local stack (the card's `url` is your public
|
|
106
|
+
origin, and an outside client follows it), run `wildo local tunnel up --tunnel <machine-tunnel>
|
|
107
|
+
--hostname <app>-<machine>.<your-domain>`: while it runs, your issuer, audiences and card name that
|
|
108
|
+
HTTPS origin, only the protocol paths are forwarded, and your own browser keeps working on localhost.
|
|
109
|
+
Tokens minted before `up` stop working after it. `wildo local tunnel down` puts everything back.
|
|
110
|
+
|
|
100
111
|
### Step 5 (optional): Split the skills across NAMED agents
|
|
101
112
|
|
|
102
113
|
Skip this when one agent card is enough — it is, for most apps.
|
|
@@ -269,6 +280,9 @@ const todoAssistantChatAgent: FlowsActors_Agent = {
|
|
|
269
280
|
functionRefs: [
|
|
270
281
|
TODOS_READ_TOOL_REF,
|
|
271
282
|
TODO_LISTS_READ_TOOL_REF,
|
|
283
|
+
// A recurring todo's occurrences, by the todo's id: they are listed under their todo, which the generic read
|
|
284
|
+
// tool cannot address. See `./todo-occurrences-tool.ts`.
|
|
285
|
+
TODO_OCCURRENCES_TOOL_REF,
|
|
272
286
|
TODOS_CREATE_TOOL_REF,
|
|
273
287
|
TODOS_UPDATE_TOOL_REF,
|
|
274
288
|
// RETRIEVAL grounding — a different KIND of source from the three above. Those return ROWS
|
|
@@ -328,6 +342,7 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
328
342
|
agents: FlowsActors_Agent[];
|
|
329
343
|
functionTools?: FunctionTool[];
|
|
330
344
|
autonomousAgents?: FlowsActors_AutonomousAgentDeclaration[];
|
|
345
|
+
chatAgents?: FlowsActors_ChatAgentDeclaration[];
|
|
331
346
|
} = {
|
|
332
347
|
flowActorSystemsFactoryMap: {
|
|
333
348
|
[TODO_ASSISTANT_SYSTEM_REF]: () => todoAssistantActorSystem,
|
|
@@ -339,6 +354,11 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
339
354
|
},
|
|
340
355
|
agents: [todoAssistantChatAgent, todoTriageAgent, todoDeadlineDrillAgent, todoAutoResolveAgent],
|
|
341
356
|
autonomousAgents: [todosOverdueTriage, todosDeadlineDrill],
|
|
357
|
+
// Who answers a person who writes to the Teams bot (#2665). The Teams messages handler already converses
|
|
358
|
+
// (`../../inbound/teams-bot.inbound-handler.ts`), and with no chat agent declared every such message was refused.
|
|
359
|
+
// The todo assistant answers, as the linked member who wrote and with that member's authority, in every
|
|
360
|
+
// organization that chose no other agent for the connection (Settings > Chat agents).
|
|
361
|
+
chatAgents: [{ ref: 'todos.assistant', systemRef: TODO_ASSISTANT_SYSTEM_REF, isDefault: true }],
|
|
342
362
|
// Generic engine factories instantiated per resource — every tool runs AS THE
|
|
343
363
|
// CALLER (the engine rebuilds a scoped ExecutionContext from the caller's verified
|
|
344
364
|
// auth; identity is never LLM-supplied) and each op's own ACL is enforced by the
|
|
@@ -430,8 +450,10 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
430
450
|
// The engine's question tool (#2720): gated on the OWNER route by construction, so only the person whose turn it
|
|
431
451
|
// is answers it, in the conversation or from their decision inbox.
|
|
432
452
|
askPersonTool(),
|
|
433
|
-
// The records the assistant may show as cards: the same
|
|
434
|
-
|
|
453
|
+
// The records the assistant may show as cards: the same three it reads. An occurrence has no page, so its card opens
|
|
454
|
+
// it in an overlay over the conversation (#2776).
|
|
455
|
+
presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS, TasksManager_ResourceType.TODOS_RECURRING_OCCURRENCES] }),
|
|
456
|
+
todoOccurrencesTool,
|
|
435
457
|
// The overdue-triage agent's one write, ROLE-gated to administrators (#1611). See `./reschedule-todo-tool.ts`.
|
|
436
458
|
rescheduleTodoTool,
|
|
437
459
|
// The deadline drill's four-minute reviewer-routed delete (#1866). See `./deadline-drill-agent.ts`.
|
|
@@ -470,8 +492,8 @@ beyond the original request; conversation history and task status are separate r
|
|
|
470
492
|
| A send carrying a webhook (`configuration.pushNotificationConfig`; 1.0: `configuration.taskPushNotificationConfig`) | A `Task`; a blocking send waits for the turn and returns it in its latest state | The webhook is registered on that task; a streamed send carrying one is refused |
|
|
471
493
|
| `configuration.blocking: false` (1.0: `configuration.returnImmediately: true`) | A `Task` with its own ID | Work continues independently of the request once the task is opened |
|
|
472
494
|
| Direct `message/stream` completes | Message frames and the final reply | No background task; disconnect during generation aborts the turn |
|
|
473
|
-
| Send or stream pauses for approval | A `Task` in `
|
|
474
|
-
| A message to a conversation still waiting for that decision | JSON-RPC error `-32015` (`DECISION_PENDING`) on every send mode, before any task is created; nothing runs or is written | The
|
|
495
|
+
| Send or stream pauses for approval | A `Task` in `auth-required` with a status message; a stream returns it in its terminal frame | The person decides in the application, never through a message on the task (refused, `UnsupportedOperationError`); the task moves on by itself, and `tasks/cancel` withdraws the request |
|
|
496
|
+
| A message to a conversation still waiting for that decision | JSON-RPC error `-32015` (`DECISION_PENDING`) on every send mode, before any task is created; nothing runs or is written | The authorization the task waits for is the person's answer: wait for it, or `tasks/cancel`, which withdraws the decision. A decision raised in the instant between that check and a non-blocking turn ends the new task `failed` |
|
|
475
497
|
|
|
476
498
|
These are the supported 0.2.5 request/state spellings. Other supported dialects use the corresponding
|
|
477
499
|
projected names. **A request is read in the dialect of its method**: a 1.0 `SendMessage` carries parts
|
|
@@ -8,8 +8,9 @@ Read this when you need to know:
|
|
|
8
8
|
|
|
9
9
|
- exactly what an external agent sees (skills = your agentic actor systems, keyed
|
|
10
10
|
`skill.id === system.ref`);
|
|
11
|
-
- how the card advertises auth
|
|
12
|
-
|
|
11
|
+
- how the card advertises auth: two security schemes with one flow each, `oauth2`
|
|
12
|
+
(`authorizationCode`, user-delegated) and `oauth2ClientCredentials` (`clientCredentials`,
|
|
13
|
+
machine callers), listed as alternatives in `security` and `securityRequirements`;
|
|
13
14
|
- what the card `url` means for audience binding (RFC 8707 / D7).
|
|
14
15
|
|
|
15
16
|
## Import Origins
|
|
@@ -45,23 +46,49 @@ export interface A2A_Skill {
|
|
|
45
46
|
* agent's canonical audience: BOTH a USER-delegated and a MACHINE (client-credentials)
|
|
46
47
|
* inbound token MUST carry it as `aud` (RFC 8707 / external-access D7) — a token minted for
|
|
47
48
|
* another surface (including the generic API audience, per the 2026-07-29 flip) is rejected.
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
* machine → the conversation is owned by the org/app).
|
|
52
|
-
* app's own OIDC provider (`/oauth/authorize`, `/oauth/token`).
|
|
49
|
+
* The card advertises BOTH D6 principals as TWO security schemes, one flow each:
|
|
50
|
+
* {@link A2A_DELEGATED_SECURITY_SCHEME} (`authorizationCode`, user-delegated → the conversation is
|
|
51
|
+
* owned by the delegating user) and {@link A2A_MACHINE_SECURITY_SCHEME} (`clientCredentials`, org/app
|
|
52
|
+
* machine → the conversation is owned by the org/app). Either satisfies the requirement. Tokens are
|
|
53
|
+
* minted by the app's own OIDC provider (`/oauth/authorize`, `/oauth/token`).
|
|
53
54
|
*/
|
|
54
55
|
/**
|
|
55
|
-
*
|
|
56
|
+
* The security scheme a USER-delegated client reads: the `authorizationCode` flow. Kept as `oauth2`, the name the card
|
|
57
|
+
* has always used for it.
|
|
56
58
|
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
59
|
+
* One flow per scheme because A2A 1.0 makes it so: spec-cite: A2A v1.0.0 specification/a2a.proto, `message OAuthFlows {
|
|
60
|
+
* oneof flow { AuthorizationCodeOAuthFlow authorization_code = 1; ClientCredentialsOAuthFlow client_credentials = 2; … } }`.
|
|
61
|
+
* Both flows in one scheme made the A2A reference SDK refuse the whole card (#3932).
|
|
62
|
+
*/
|
|
63
|
+
export const A2A_DELEGATED_SECURITY_SCHEME = 'oauth2';
|
|
64
|
+
/** The security scheme a MACHINE client reads: the `clientCredentials` flow. See {@link A2A_DELEGATED_SECURITY_SCHEME}. */
|
|
65
|
+
export const A2A_MACHINE_SECURITY_SCHEME = 'oauth2ClientCredentials';
|
|
66
|
+
/**
|
|
67
|
+
* One protocol interface this agent exposes: a URL, the protocol binding spoken there, and the protocol version.
|
|
68
|
+
*
|
|
69
|
+
* spec-cite: A2A v1.0.0 specification/a2a.proto, `message AgentInterface { string url = 1 [REQUIRED]; string
|
|
70
|
+
* protocol_binding = 2 [REQUIRED]; string tenant = 3; string protocol_version = 4 [REQUIRED]; }`, serialized camelCase
|
|
71
|
+
* (§5.5). `protocol_binding` is "an open form string … The core ones officially supported are `JSONRPC`, `GRPC` and
|
|
72
|
+
* `HTTP+JSON`."
|
|
73
|
+
*
|
|
74
|
+
* These were named `transport` and `version` until 2026-11-16, names `AgentInterface` does not have, so a 1.0 client
|
|
75
|
+
* parsing the card read every interface with no binding and no version (#3932).
|
|
60
76
|
*/
|
|
61
77
|
export interface A2A_AgentInterface {
|
|
62
78
|
url: string;
|
|
63
|
-
|
|
64
|
-
|
|
79
|
+
protocolBinding: string;
|
|
80
|
+
protocolVersion: string;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* One 1.0 security requirement: the schemes it needs, each with the scopes required. The card lists alternatives, so a
|
|
85
|
+
* client satisfies any one entry.
|
|
86
|
+
*
|
|
87
|
+
* spec-cite: A2A v1.0.0 specification/a2a.proto, `message SecurityRequirement { map<string, StringList> schemes = 1; }`
|
|
88
|
+
* and `message StringList { repeated string list = 1; }`.
|
|
89
|
+
*/
|
|
90
|
+
export interface A2A_SecurityRequirement {
|
|
91
|
+
schemes: Record<string, { list: string[] }>;
|
|
65
92
|
}
|
|
66
93
|
|
|
67
94
|
export interface A2A_AgentCard {
|
|
@@ -96,15 +123,22 @@ export interface A2A_AgentCard {
|
|
|
96
123
|
defaultOutputModes: string[];
|
|
97
124
|
skills: A2A_Skill[];
|
|
98
125
|
securitySchemes: Record<string, unknown>;
|
|
126
|
+
/** The v0.2.5 requirement list (scheme name → scopes), one entry per alternative. Kept for v0.2.5 clients. */
|
|
99
127
|
security: Record<string, string[]>[];
|
|
128
|
+
/**
|
|
129
|
+
* The same alternatives in the 1.0 shape. spec-cite: A2A v1.0.0 specification/a2a.proto, `AgentCard` —
|
|
130
|
+
* `repeated SecurityRequirement security_requirements = 9`.
|
|
131
|
+
*/
|
|
132
|
+
securityRequirements: A2A_SecurityRequirement[];
|
|
100
133
|
}
|
|
101
134
|
```
|
|
102
135
|
|
|
103
136
|
## The A2A task surface (`tasks/get` / `tasks/cancel`)
|
|
104
137
|
|
|
105
138
|
Read this when an external agent needs to start work it will come back for. A turn that pauses
|
|
106
|
-
for human approval also becomes a task: it reaches `
|
|
107
|
-
|
|
139
|
+
for human approval also becomes a task: it reaches `auth-required` (the protocol's in-task
|
|
140
|
+
authorization, given outside the protocol), carries a status message saying a person decides in the
|
|
141
|
+
application, persists the decision it is waiting on, and leaves that state once its execution moves on. Both paths into a task are live,
|
|
108
142
|
so an integration you build now can encounter either.
|
|
109
143
|
|
|
110
144
|
The key thing to understand is **when a task exists at all** — most turns never create
|
|
@@ -133,11 +167,11 @@ one, and that is deliberate rather than a gap.
|
|
|
133
167
|
* - the turn reached an interrupted state (a human-in-the-loop approval pause).
|
|
134
168
|
*
|
|
135
169
|
* All three triggers are live. The interrupted-state arm needs a runtime that can pause a turn; that
|
|
136
|
-
* is the human-in-the-loop approval gate, and a paused turn
|
|
137
|
-
* `
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
*
|
|
170
|
+
* is the human-in-the-loop approval gate, and a paused turn materialises a task carrying
|
|
171
|
+
* `auth-required` on all three transports (blocking send, non-blocking send, stream), with a status
|
|
172
|
+
* message saying a person decides in the application. The task moves on by itself once they have:
|
|
173
|
+
* poll it, subscribe to it, or register a webhook. A message on the task does not answer the
|
|
174
|
+
* approval, and `tasks/cancel` withdraws it.
|
|
141
175
|
*
|
|
142
176
|
* A blocking turn that answers in one shot, with no webhook, returns an A2A `Message` and writes no task
|
|
143
177
|
* row at all. Both shapes are protocol-conformant: the specification types the
|
|
@@ -201,7 +235,7 @@ export interface A2A_TaskSurfaceContract {
|
|
|
201
235
|
* projection from `FlowsActors_Status` reads it, the transport emits it, and tests
|
|
202
236
|
* pin it.
|
|
203
237
|
*
|
|
204
|
-
* Not every member is emitted by this transport today — `
|
|
238
|
+
* Not every member is emitted by this transport today — `INPUT_REQUIRED` and
|
|
205
239
|
* `REJECTED` have no `FlowsActors_Status` counterpart and are never produced. They
|
|
206
240
|
* are declared because the vocabulary belongs to the protocol, not to us: a client
|
|
207
241
|
* may legitimately receive them from another A2A server, and omitting them would
|
|
@@ -213,13 +247,19 @@ export enum A2A_TaskState {
|
|
|
213
247
|
/** Actively being processed. */
|
|
214
248
|
WORKING = 'working',
|
|
215
249
|
/**
|
|
216
|
-
* Interrupted (non-terminal): the agent needs input
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
* principals are denied rather than parked because no named person can answer for them.
|
|
250
|
+
* Interrupted (non-terminal): the agent needs more input from the client, which a follow-up message
|
|
251
|
+
* on the task gives. NOT emitted by this transport: a turn that answers needs no task, and an
|
|
252
|
+
* approval pause is {@link AUTH_REQUIRED}, because a message does not answer it.
|
|
220
253
|
*/
|
|
221
254
|
INPUT_REQUIRED = 'input-required',
|
|
222
|
-
/**
|
|
255
|
+
/**
|
|
256
|
+
* Interrupted (non-terminal): an authorization the task waits on, given outside the protocol.
|
|
257
|
+
* Emitted when a user-delegated turn reaches an approval-gated tool: the signed pending decision is
|
|
258
|
+
* persisted, an addressable task is materialised, and its status message says a person decides in
|
|
259
|
+
* the application. Their approval or refusal resumes that same execution, and the task moves on
|
|
260
|
+
* without the client sending anything. Machine principals are denied rather than parked, because
|
|
261
|
+
* no named person can answer for them.
|
|
262
|
+
*/
|
|
223
263
|
AUTH_REQUIRED = 'auth-required',
|
|
224
264
|
/** Terminal: finished successfully. */
|
|
225
265
|
COMPLETED = 'completed',
|
|
@@ -204,10 +204,14 @@ export const rescheduleTodoTool: FunctionTool = {
|
|
|
204
204
|
argumentsResource: { resourceType: TasksManager_ResourceType.TODOS },
|
|
205
205
|
description:
|
|
206
206
|
'Propose a new due date for one overdue todo. An organization administrator must approve the change before '
|
|
207
|
-
+ 'it is applied. Resolve the todo id with resource.todos.read first.',
|
|
207
|
+
+ 'it is applied. Resolve the todo id with resource.todos.read first, and give the administrator a one-sentence reason.',
|
|
208
208
|
inputSchema: z.object({
|
|
209
209
|
todoId: z.string().min(1).describe('Id of the todo to reschedule. Resolve it with resource.todos.read.'),
|
|
210
210
|
dueDate: z.string().min(1).describe('The proposed due date, as an ISO 8601 date, e.g. "2026-10-04".'),
|
|
211
|
+
// Shown to the administrator who decides, and nowhere else: it is not written to the todo. Defaulted, so a call that
|
|
212
|
+
// leaves it out still runs, and the approval card then shows the default rather than an empty argument (#3295: an
|
|
213
|
+
// approver's edit is parsed, and a parse that fills a default differs from the raw input).
|
|
214
|
+
reason: z.string().max(280).default('No reason given.').describe('One sentence for the approving administrator: why this date.'),
|
|
211
215
|
}),
|
|
212
216
|
humanApproval: {
|
|
213
217
|
route: HumanDecision_RouteKind.ROLE,
|
|
@@ -215,7 +219,7 @@ export const rescheduleTodoTool: FunctionTool = {
|
|
|
215
219
|
// What the todos UPDATE it runs declares (#2526).
|
|
216
220
|
riskLevel: ResourceOperationRiskLevel.LOW,
|
|
217
221
|
},
|
|
218
|
-
execute: async (args: { todoId: string; dueDate: string }, ctx: FunctionToolExecutionContext): Promise<RescheduleTodoToolResult> => {
|
|
222
|
+
execute: async (args: { todoId: string; dueDate: string; reason: string }, ctx: FunctionToolExecutionContext): Promise<RescheduleTodoToolResult> => {
|
|
219
223
|
const dueDate = new Date(args.dueDate);
|
|
220
224
|
if (Number.isNaN(dueDate.getTime())) throw new Error(`"${args.dueDate}" is not a date.`);
|
|
221
225
|
await dispatchResourceOperationAsTool({
|