@wildo-ai/framework-knowledge 1.1.14 → 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/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.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 +4 -0
- 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/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/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 +27 -4
- 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.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.http-api-binding.md +51 -0
- 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.system-of-record-error-codes.md +30 -0
- package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
- 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 +1080 -1012
- package/dist/knowledge/skills/INDEX.md +2 -2
- package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +4 -1
- 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/compliance-document-authoring/references/document-composition-privacy-notice.md +4 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
- package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +1 -0
- 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 +31 -9
- package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +27 -4
- 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-module/SKILL.md +3 -0
- 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-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/topic-index.json +231 -84
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +4 -4
|
@@ -103,7 +103,7 @@ navigation, design tokens.
|
|
|
103
103
|
| **`config-saas`** — edit `wildo.saas.config.ts` for modules, services, capabilities, and the compliance declarations (operating entity, jurisdictions, retention, AI posture, client storage, provider choices) | "edit wildo.saas.config.ts", "add a module to SaaS config", "wire a new capability at root", "register a service at the app level", "record our legal entity", "declare which jurisdictions we operate in", "set the retention schedule", "who is the data controller" |
|
|
104
104
|
| **`config-saas-backend`** — edit `saas-config.backend.ts`: auth posture, user types, passkey RP, email From, frontend-service login exposure, and how sign-up ASKS for document acceptance | "change the password policy", "enable magic link / MFA / passkeys", "add a user type", "nobody can log in", "authentication_method_not_supported", "set the From address", "how does sign-up ask people to accept the terms", "make people read the terms before signing up", "clickwrap", "we only need a notice beside the button" |
|
|
105
105
|
| **`configure-billing`** — enable billing / make a backend-reachable provider resolve across the 5-surface config chain; write the billing catalogue; record metered usage on an operation, once per case for a price per case | "enable billing", "turn on Stripe", "billing crash-loops the backend", "wire up subscriptions/checkout", "provider not reachable on the backend", "my provider is authored but the backend can't reach it", "bill each case", "record usage when a case closes" |
|
|
106
|
-
| **`provider-backend-package`** — install and scope a BACKEND provider shipped as its own npm package, so a host loads it on demand | "add the Slack provider", "install a provider package", "integrate a vendor on the backend", "my provider package is installed but the backend can't see it", "provider not present in the composed backend catalog", "exports no backendProviderFragment", "how do I ship our own provider" |
|
|
106
|
+
| **`provider-backend-package`** — install and scope a BACKEND provider shipped as its own npm package, so a host loads it on demand; author one only when no engine provider or registry module fills the need, with the reason recorded | "add the Slack provider", "install a provider package", "integrate a vendor on the backend", "my provider package is installed but the backend can't see it", "provider not present in the composed backend catalog", "exports no backendProviderFragment", "how do I ship our own provider" |
|
|
107
107
|
| **`provider-operation-calls`** — call a connected provider's operation from a backend service (generated typed client) or from a frontend component (the browser door, for operations the application declares) | "call the Slack API from my service", "post to a vendor from the backend", "use the generated provider client", "call a provider operation from a component", "my component needs data from a third-party API", "PROVIDER_OPERATION_REFUSED", "not_browser_reachable" |
|
|
108
108
|
| **`provider-frontend-module`** — author or scope a frontend provider module on any browser surface (application, website, docs site): capability, public keys, CSP, scripts, components; including a facet a provider PACKAGE ships on its `./<ref>/frontend-app` subpath | "add a frontend provider", "load a vendor widget in the browser", "use the Cloudinary picker", "ship a browser part in our provider package", "the provider's component never loads", "which keys may a frontend provider take" |
|
|
109
109
|
| **`provider-frontend-file-picker`** — add or tune the frontend FILE PICKER provider (browser-bound module + contribution + scope; framework file fields resolve its constraints automatically); also how ANY provider component loads on the application, the website and the docs site | "add a file picker", "let users attach files", "restrict uploads to PDFs", "raise the upload size limit", "file field accepts anything", "picker allows too many files", "wire a file upload provider", "put a provider component on the website", "show a vendor widget in the docs" |
|
|
@@ -237,7 +237,7 @@ Anything that changes **backend-api code** beyond schema-driven CRUD.
|
|
|
237
237
|
|
|
238
238
|
| Skill | Trigger phrases |
|
|
239
239
|
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
240
|
-
| **`flows-actors-chat-assistant`** **(orchestrator)** — add a conversational AI assistant grounded on resource data (CHAT agent + `resourceReadTool` + FRONTEND actor system + `/flows-actors/:ref` view) | "add a chat assistant", "add an AI assistant grounded on <resource>", "let users chat with / ask questions about their <resource>", "wire a resourceReadTool", "add a flows-actors chat agent", "expose an actor system as a chat view", "set a deadline on an approval", "remind reviewers before an approval expires", "show the records as cards in the chat" |
|
|
240
|
+
| **`flows-actors-chat-assistant`** **(orchestrator)** — add a conversational AI assistant grounded on resource data (CHAT agent + `resourceReadTool` + FRONTEND actor system + `/flows-actors/:ref` view) | "add a chat assistant", "add an AI assistant grounded on <resource>", "let users chat with / ask questions about their <resource>", "wire a resourceReadTool", "add a flows-actors chat agent", "expose an actor system as a chat view", "set a deadline on an approval", "remind reviewers before an approval expires", "show the records as cards in the chat", "let my agent call a remote A2A agent" |
|
|
241
241
|
| **`flows-actors-llm-agent-invocation`** — author a ONE-SHOT LLM agent and call it from your own backend code (operation key → agent definition → registration → `invokeAgent` envelope → wrapped output); text or schema-constrained structured output, no conversation and no view | "summarize this with AI", "classify / categorize these with an LLM", "extract fields from this text", "call Claude / GPT from the backend", "add an AI agent that generates X", "get structured JSON out of a model", "score or triage this automatically", "invokeAgent" |
|
|
242
242
|
| **`configure-coding-agent`** — configure the autonomous agent that edits THIS application's own workspace (ACP execution profile → ceiling → host-configuration posture → per-agent limits you cannot configure away) | "set up the coding agent", "let the AI edit my app", "switch to Codex / OpenCode", "use a different model for coding tasks", "the coding agent can't start", "execution profile not found", "my coding run changed nothing", "the agent asked for permission and there was nobody to answer" |
|
|
243
243
|
| **`flows-actors-a2a-exposure`** — expose your agentic actor systems to EXTERNAL AI agents over Agent2Agent (auto-exposed skills + OIDC/OAuth auth; user-delegated OR machine principal → scope-owned conversations) | "expose my actor as an A2A agent", "let other AI agents call my assistant", "agent2agent", "A2A endpoint", "machine / client-credentials access to my chat agent", "how do external agents authenticate to my actor", "agent card" |
|
|
@@ -57,11 +57,14 @@ one typed module record.
|
|
|
57
57
|
| Module DI container | `backend-api/src/modules/<slug>/addons/container.ts` (NOT scaffolded — create it when a module owns injectable services; merged from `backend-api/src/index.ts`) |
|
|
58
58
|
| Module services aggregator | `backend-api/src/modules/<slug>/addons/services/index.ts` |
|
|
59
59
|
| Module controllers aggregator | `backend-api/src/modules/<slug>/addons/controllers/index.ts` |
|
|
60
|
-
| Module email template definitions | `backend-api/src/modules/<slug>/emails/
|
|
60
|
+
| Module email template definitions | `backend-api/src/modules/<slug>/emails/module-email-template-definitions.ts` (scans `resources/`, `system/`) |
|
|
61
|
+
| Module custom operations | `backend-api/src/modules/<slug>/resources/<resource>/*.operation.ts` (any depth under `resources/`; the scan reads nowhere else) |
|
|
61
62
|
| Engine i18n barrel (single owner) | `backend-api/src/engine/i18n/index.ts` (calls `scanCustomLabelsDirectory`) |
|
|
62
63
|
| Module backend registry | `backend-api/src/modules-registry.backend.ts` (`BackendOwnedModule[]`) |
|
|
63
64
|
| `BackendOwnedModule` type | `backend-api/src/backend-owned-module.ts` |
|
|
64
65
|
|
|
66
|
+
**These folders are the rule, not a suggestion.** A module's email definitions and templates live in `emails/` (never `email/` or the module root) and its custom operations under `resources/`: the companion generates and previews a module's emails only under `emails/`, and `resources/index.ts` registers only the operations it scans. The build lane's `check:module-layout` refuses either file elsewhere and states the move (`mv`) and the imports to update.
|
|
67
|
+
|
|
65
68
|
## When to Use
|
|
66
69
|
|
|
67
70
|
- Authoring a new backend module (must wire the
|
package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md
CHANGED
|
@@ -30,6 +30,19 @@ export interface BackendDomainModule extends SharedDomainModule {
|
|
|
30
30
|
* `capabilities.tools.functionRefs`.
|
|
31
31
|
*/
|
|
32
32
|
functionTools?: FunctionTool[];
|
|
33
|
+
/**
|
|
34
|
+
* Another party's MCP servers this module's agents may call (#3958): each one's endpoint and the stored provider
|
|
35
|
+
* connection whose credential reaches it. Reference them from an agent's `capabilities.tools.mcpRefs`. Registration
|
|
36
|
+
* refuses a plaintext `http://` endpoint, and every call goes through the outbound guard. See `FlowsActors_McpServer`.
|
|
37
|
+
*/
|
|
38
|
+
mcpServers?: FlowsActors_McpServer[];
|
|
39
|
+
/**
|
|
40
|
+
* Another party's A2A agents this module's agents may delegate a task to (#3930): each one's card URL and the stored
|
|
41
|
+
* provider connection whose credential reaches it. Reference them from an agent's
|
|
42
|
+
* `capabilities.tools.remoteAgentRefs`. Registration refuses a plaintext `http://` card or endpoint, and every call
|
|
43
|
+
* goes through the outbound guard. See `FlowsActors_RemoteAgent`.
|
|
44
|
+
*/
|
|
45
|
+
remoteAgents?: FlowsActors_RemoteAgent[];
|
|
33
46
|
/**
|
|
34
47
|
* Agents that may run with nobody on a socket — on a schedule or on an inbound delivery (#1611).
|
|
35
48
|
* Declaring one grants nothing: a turn runs in an organization only while one of its OAuth clients
|
|
@@ -438,6 +451,8 @@ function mergeFlowsActors(
|
|
|
438
451
|
) as FlowActorSystem_InitializationFactoryMap,
|
|
439
452
|
agents: modules.flatMap(m => m.flowsActors?.agents ?? []),
|
|
440
453
|
functionTools: modules.flatMap(m => m.flowsActors?.functionTools ?? []),
|
|
454
|
+
mcpServers: modules.flatMap(m => m.flowsActors?.mcpServers ?? []),
|
|
455
|
+
remoteAgents: modules.flatMap(m => m.flowsActors?.remoteAgents ?? []),
|
|
441
456
|
autonomousAgents: modules.flatMap(m => m.flowsActors?.autonomousAgents ?? []),
|
|
442
457
|
chatAgents: modules.flatMap(m => m.flowsActors?.chatAgents ?? []),
|
|
443
458
|
actorExecutionContinuations: modules.flatMap(m => m.flowsActors?.actorExecutionContinuations ?? []),
|
|
@@ -27,6 +27,8 @@ hooks. Custom operations are auto-scanned from
|
|
|
27
27
|
`backend-api/src/modules/<slug>/resources/**/*.operation.ts` by
|
|
28
28
|
`scanDefaultExports` and registered through the
|
|
29
29
|
`BackendDomainModule.operations` slot (`backend-addon-wiring`).
|
|
30
|
+
An operation file anywhere else is never registered, and a build task's
|
|
31
|
+
`check:module-layout` refuses it with the move into `resources/<resource>/`.
|
|
30
32
|
|
|
31
33
|
A custom operation file is the spot where:
|
|
32
34
|
|
|
@@ -51,7 +53,7 @@ REPLACE and `overrideAll` have distinct ownership rules described in Step 5.
|
|
|
51
53
|
| Operation auto-scanner | `backend-api/src/modules/<slug>/resources/index.ts` (`scanDefaultExports`) |
|
|
52
54
|
| Operation path types | `@wildo-ai/saas-models` (`CoreResourceOperation`, `ResourceOperationVariantType`) |
|
|
53
55
|
| Custom impl factory + helpers | `@wildo-ai/saas-backend-lib` (`createResourceCustomServiceImplementation`, `ResourcesRegistryBackendService`) |
|
|
54
|
-
| Resource configuration (parity) | `shared-lib/src/modules/<slug>/resources/<resource>/<resource>.
|
|
56
|
+
| Resource configuration (parity) | `shared-lib/src/modules/<slug>/resources/<resource>/<resource>.resources-config.ts` |
|
|
55
57
|
| Repository service | injected via `utils.<resourceRepositoryService>` inside handlers |
|
|
56
58
|
|
|
57
59
|
## When to Use
|
|
@@ -307,6 +307,10 @@ actually controls.
|
|
|
307
307
|
one — and `privacy.consentDecidedAt`, stamped by the server when they decide. An empty set WITH an
|
|
308
308
|
instant is "declined everything"; no instant is "never asked". A notice must not state the second
|
|
309
309
|
as the first.
|
|
310
|
+
- per-person `privacy.offeredPurposes` — the purposes a consent surface actually showed the person
|
|
311
|
+
when they decided, accumulated over their decisions. A decision covers only what was shown: when
|
|
312
|
+
the application starts asking for a purpose after someone decided, the consent prompt asks them
|
|
313
|
+
for that purpose alone, and a notice must not describe them as having declined it.
|
|
310
314
|
- `analytics.requiresConsent` (default `true`) — whether the application's analytics rest on
|
|
311
315
|
`ANALYTICS`. It governs analytics alone, never use of the service.
|
|
312
316
|
- the visitor tier: a marketing website keeps a visitor's decision in their browser and starts a
|
|
@@ -93,6 +93,13 @@ export const PROVIDER_CAPABILITY_DISCLOSURES: Readonly<Record<BuiltinProviderCap
|
|
|
93
93
|
carriedBy: 'each signer\'s name and email address, and the document sent for signature, which the vendor holds signed',
|
|
94
94
|
linkableToSubjectByApplication: true,
|
|
95
95
|
},
|
|
96
|
+
// Embedded signing: the signer's name and e-mail again, to open their signing page, and the page the vendor serves in a
|
|
97
|
+
// frame of the application, which reaches the vendor from the signer's browser with the application's origin.
|
|
98
|
+
[BUILTIN_PROVIDER_CAPABILITY.EMBEDDED_ELECTRONIC_SIGNATURE]: {
|
|
99
|
+
categories: [PersonalDataCategory.IDENTITY, PersonalDataCategory.CONTACT_DETAILS],
|
|
100
|
+
carriedBy: 'each signer\'s name and email address, sent again to open their signing page, and the signer\'s browser, which loads that page from the vendor',
|
|
101
|
+
linkableToSubjectByApplication: true,
|
|
102
|
+
},
|
|
96
103
|
[BUILTIN_PROVIDER_CAPABILITY.BILLING]: {
|
|
97
104
|
categories: [PersonalDataCategory.IDENTITY, PersonalDataCategory.CONTACT_DETAILS, PersonalDataCategory.FINANCIAL],
|
|
98
105
|
carriedBy: 'the customer name and email address, and the payment, subscription and invoice records',
|
|
@@ -263,6 +263,7 @@ Reads and changes of application data that are recorded for review.
|
|
|
263
263
|
|
|
264
264
|
| Event | Wire value | Severity | What it records |
|
|
265
265
|
| --- | --- | --- | --- |
|
|
266
|
+
| `A2A_REMOTE_AGENT_CALL` | `a2a_remote_agent_call` | Information | |
|
|
266
267
|
| `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. |
|
|
267
268
|
| `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. |
|
|
268
269
|
| `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`). |
|
|
@@ -292,6 +292,17 @@ export const BUILTIN_PROVIDER_CAPABILITY = {
|
|
|
292
292
|
* levels its contract declares. Maps to `EngineCapability.ELECTRONIC_SIGNATURE`.
|
|
293
293
|
*/
|
|
294
294
|
ELECTRONIC_SIGNATURE: 'ELECTRONIC_SIGNATURE',
|
|
295
|
+
/**
|
|
296
|
+
* Provider ALSO lets a signer sign inside the application, in a frame showing the vendor's signing page, instead of
|
|
297
|
+
* from the vendor's e-mail (embedded signing). Maps to `EngineCapability.ELECTRONIC_SIGNATURE`, the slot it shares with
|
|
298
|
+
* {@link ELECTRONIC_SIGNATURE}, and is claimed only beside it.
|
|
299
|
+
*
|
|
300
|
+
* A token of its own because vendors split here: DocuSign, Yousign, BoldSign, SignNow and Adobe Acrobat Sign answer a
|
|
301
|
+
* signing page URL the application can frame; IgniSign, Dropbox Sign and Universign need their own browser script, so
|
|
302
|
+
* their providers sign from the e-mail only. The claim is the provider's statement that its contract declares
|
|
303
|
+
* `embeddedSigning`; the engine refuses at startup a claim with no such declaration.
|
|
304
|
+
*/
|
|
305
|
+
EMBEDDED_ELECTRONIC_SIGNATURE: 'EMBEDDED_ELECTRONIC_SIGNATURE',
|
|
295
306
|
/**
|
|
296
307
|
* Single billing-engagement capability covering everything from
|
|
297
308
|
* Checkout-style hosted flows to first-party PaymentIntent flows.
|
|
@@ -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
|