@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
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# Another party's A2A agent — the declaration contract
|
|
2
|
+
|
|
3
|
+
Read this when an agent should hand a task to an agent someone else runs, over A2A 1.0. It surfaces the
|
|
4
|
+
`FlowsActors_RemoteAgent` you put on a backend domain module's `flowsActors.remoteAgents`, and whose `ref` an
|
|
5
|
+
agent lists in `capabilities.tools.remoteAgentRefs`.
|
|
6
|
+
|
|
7
|
+
What the calling agent gets:
|
|
8
|
+
|
|
9
|
+
- One tool per remote agent, named `a2a_<ref>`, described by YOUR `description` (the remote card's own text never
|
|
10
|
+
reaches the model). It takes one argument, `message`, and returns `{ answer, taskState?, taskId?, contextId? }`, or
|
|
11
|
+
`{ error, detail, taskId?, contextId? }` naming how the call failed (`refused_target`, `unreachable`, `timed_out`,
|
|
12
|
+
`protocol_error`, `remote_task_failed`, `remote_request_refused`, `incompatible_agent`, `rate_budget_exhausted`), with
|
|
13
|
+
the remote task's ids when one was opened before the failure.
|
|
14
|
+
- Each call is a new request: the remote agent answers it directly or opens a new task. The model cannot pass a task or
|
|
15
|
+
context id, so it cannot continue, read or cancel a remote task. A task still running when `callMs` elapses comes back
|
|
16
|
+
as an answer carrying its last-read state and ids, and keeps running there; it is never cancelled.
|
|
17
|
+
- A blank or missing `message` is refused before anything is sent.
|
|
18
|
+
- The tool is offered only when a credential resolves for `credential.subject`, never on a turn an inbound delivery
|
|
19
|
+
started, and never under the name of a tool already offered that turn.
|
|
20
|
+
|
|
21
|
+
What the runtime does on each call:
|
|
22
|
+
|
|
23
|
+
- Fetches the card from `cardUrl` WITHOUT the credential and keeps it for as long as its `Cache-Control` allows (five
|
|
24
|
+
minutes by default, one hour at most, never with `no-store` or `no-cache`). It reads the card's JSON-RPC interfaces at
|
|
25
|
+
protocol version 1.0 (any 1.0 patch).
|
|
26
|
+
- Sends the credential, as a bearer token, to one of those interfaces only: with `endpointUrl` declared, the interface
|
|
27
|
+
at exactly that URL, which is also the URL the credential is resolved for; without it, the card's first such
|
|
28
|
+
interface, and only when it is on the card's own host. A card whose interface is on another host is refused unless
|
|
29
|
+
you declared that interface as `endpointUrl`.
|
|
30
|
+
- Sends `SendMessage`, then reads the task with `GetTask` until it ends, pauses for input or `callMs` elapses. Every
|
|
31
|
+
JSON-RPC request carries `A2A-Version: 1.0`. Each response body is read within the same deadline and refused past a
|
|
32
|
+
size ceiling.
|
|
33
|
+
- Goes through the outbound guard, so a private, loopback or metadata address is refused before anything leaves, and
|
|
34
|
+
through the connection's rate budget when the credential has one.
|
|
35
|
+
- Records every call as an `a2a_remote_agent_call` audit row: the remote agent, the host the credential went to, the
|
|
36
|
+
outcome, the remote task id and state, and whose credential it spent. Never the message, never the answer.
|
|
37
|
+
|
|
38
|
+
The fields:
|
|
39
|
+
|
|
40
|
+
- `cardUrl` / `endpointUrl` — `https://` only; startup refuses `http://`. Declare `endpointUrl` when the agent's
|
|
41
|
+
interface is on another host than its card, or to pin which of its interfaces is used.
|
|
42
|
+
- `credential` — required. `secretSlug` is the provider's secrets-contract KEY (`accessToken`), never the env-var
|
|
43
|
+
spelling: a wrong spelling silently misses the stored credential, and the tool is then never offered.
|
|
44
|
+
- `timeouts` — `cardMs` (default 5 000) and `callMs` (default 60 000). Write them out: the type you author against is
|
|
45
|
+
the parsed one.
|
|
46
|
+
|
|
47
|
+
Startup refuses a declaration the schema refuses, a `ref` declared twice, a plaintext URL, and an agent whose
|
|
48
|
+
`remoteAgentRefs` names no declaration (`agent_remote_agent_ref_names_no_declared_remote_agent`).
|
|
49
|
+
|
|
50
|
+
The remote agent's answer is another party's text. Declare `contentGuardrails.promptInjection` on the calling agent,
|
|
51
|
+
and under `contentGuardrails.personalData` the answer reaches the model withheld whole, because nothing says which of
|
|
52
|
+
its words are personal data.
|
|
53
|
+
|
|
54
|
+
## Import Origins
|
|
55
|
+
|
|
56
|
+
- `@wildo-ai/saas-models`
|
|
57
|
+
|
|
58
|
+
## Source Excerpts
|
|
59
|
+
|
|
60
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
61
|
+
|
|
62
|
+
```typescript
|
|
63
|
+
/**
|
|
64
|
+
* Bounds on a call that leaves the trust boundary. Present with defaults, because a remote agent can take as long as it
|
|
65
|
+
* likes and an unbounded call would hold the calling agent's turn open for that long.
|
|
66
|
+
*/
|
|
67
|
+
export const FlowsActors_RemoteAgentTimeoutsSchema = z.object({
|
|
68
|
+
/** How long fetching the remote agent's card may take. */
|
|
69
|
+
cardMs: z.number().int().positive().default(5_000),
|
|
70
|
+
/**
|
|
71
|
+
* How long one delegation may take, end to end: the send, then reading the task until it ends or pauses. A task still
|
|
72
|
+
* running at the deadline is returned to the calling agent as still running, with its ids; it is never cancelled.
|
|
73
|
+
*/
|
|
74
|
+
callMs: z.number().int().positive().default(60_000),
|
|
75
|
+
});
|
|
76
|
+
export type FlowsActors_RemoteAgentTimeouts = z.infer<typeof FlowsActors_RemoteAgentTimeoutsSchema>;
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Another party's A2A agent the application's agents may delegate a task to (A2A 1.0, JSON-RPC binding).
|
|
80
|
+
*
|
|
81
|
+
* The runtime fetches the agent card from `cardUrl` WITHOUT the credential and sends the credential to one of the card's
|
|
82
|
+
* JSON-RPC interfaces at protocol version 1.0, and only to one the application named too: with `endpointUrl` declared,
|
|
83
|
+
* the interface at exactly that URL; without it, the card's first such interface, and only when it is on the card's own
|
|
84
|
+
* host. A card cannot redirect a credential to a host the application never named.
|
|
85
|
+
*/
|
|
86
|
+
export const FlowsActors_RemoteAgentSchema = z.object({
|
|
87
|
+
/** The value an agent's `capabilities.tools.remoteAgentRefs` names. Unique within an application. */
|
|
88
|
+
ref: z.string().min(1),
|
|
89
|
+
displayName: z.string().min(1),
|
|
90
|
+
/**
|
|
91
|
+
* What the remote agent does, in the application's words. It is the description of the tool the calling model is
|
|
92
|
+
* offered — the card's own description never reaches the model.
|
|
93
|
+
*/
|
|
94
|
+
description: z.string().min(1),
|
|
95
|
+
/** Where the agent card is served, `https://` (e.g. `https://agent.example.com/.well-known/agent-card.json`). */
|
|
96
|
+
cardUrl: z.string().url(),
|
|
97
|
+
/**
|
|
98
|
+
* The interface URL the credential is sent to, exactly. Declare it when the agent's interface is on another host than
|
|
99
|
+
* its card, or to pin which of the card's interfaces is used. The credential is resolved for this URL.
|
|
100
|
+
*/
|
|
101
|
+
endpointUrl: z.string().url().optional(),
|
|
102
|
+
/** Which stored provider credential authorizes the calls, and whose. Required: an anonymous remote agent is not admitted. */
|
|
103
|
+
credential: FlowsActors_OutboundCredentialSchema,
|
|
104
|
+
timeouts: FlowsActors_RemoteAgentTimeoutsSchema.default({ cardMs: 5_000, callMs: 60_000 }),
|
|
105
|
+
});
|
|
106
|
+
export type FlowsActors_RemoteAgent = z.infer<typeof FlowsActors_RemoteAgentSchema>;
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
The credential's own contract, shared with MCP servers:
|
|
110
|
+
|
|
111
|
+
## Import Origins
|
|
112
|
+
|
|
113
|
+
- `@wildo-ai/saas-models`
|
|
114
|
+
|
|
115
|
+
## Source Excerpts
|
|
116
|
+
|
|
117
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
/**
|
|
121
|
+
* WHOSE credential the call carries.
|
|
122
|
+
*
|
|
123
|
+
* The distinction is not a preference. A tool call that reaches a third party on a user's behalf
|
|
124
|
+
* should be attributable to that user AT THE FAR END — that is what makes it revocable there and
|
|
125
|
+
* auditable by the party being called. An application-wide service identity loses that: every
|
|
126
|
+
* user's call looks identical to the server, and one leaked credential exposes every tenant.
|
|
127
|
+
*/
|
|
128
|
+
export enum FlowsActors_OutboundCredentialSubject {
|
|
129
|
+
/**
|
|
130
|
+
* The acting user's own delegated credential, falling back to the organization's connection when
|
|
131
|
+
* the user has none. The default, and the reason a fallback exists at all: an agent acting for a
|
|
132
|
+
* user who has never connected the server would otherwise have no path, which would make every
|
|
133
|
+
* unattended and batch turn impossible.
|
|
134
|
+
*/
|
|
135
|
+
USER_THEN_ORGANIZATION = 'user_then_organization',
|
|
136
|
+
/** The organization's connection only — for a server the tenant connects once on everyone's behalf. */
|
|
137
|
+
ORGANIZATION = 'organization',
|
|
138
|
+
/** The acting user's own credential only. No fallback: a user who has not connected cannot call. */
|
|
139
|
+
USER = 'user',
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Which stored credential authorizes the call.
|
|
144
|
+
*
|
|
145
|
+
* `providerRef` names a provider the application has already connected, so the credential comes from
|
|
146
|
+
* `organizationProviderCredentials` / `userProviderCredentials` rather than from a store invented
|
|
147
|
+
* for one kind of call. Those exist, carry per-tenant isolation by construction, and already have the connect and
|
|
148
|
+
* consent flow in front of them — a second credential store for this one call shape would be a
|
|
149
|
+
* second thing to rotate, audit and leak.
|
|
150
|
+
*/
|
|
151
|
+
export const FlowsActors_OutboundCredentialSchema = z.object({
|
|
152
|
+
providerRef: z.string().min(1),
|
|
153
|
+
/**
|
|
154
|
+
* The provider's `secretsContract` KEY (`accessToken`) — the one both credential resolver ports
|
|
155
|
+
* require, and NOT the slot's env-var spelling (`VENDOR_ACCESS_TOKEN`) the env projection names.
|
|
156
|
+
* Stored credentials are keyed on the key (#624), and this value reaches the stores verbatim, so a
|
|
157
|
+
* spelling here misses a credential that exists.
|
|
158
|
+
*
|
|
159
|
+
* DECLARED rather than derived, because it is not derivable: a provider's contract may carry
|
|
160
|
+
* several secrets, and which of them authorizes the endpoint is a fact about that vendor's
|
|
161
|
+
* deployment rather than anything the framework can compute. Guessing a conventional name would
|
|
162
|
+
* resolve the wrong secret silently — the resolver would find a credential, spend it, and be
|
|
163
|
+
* refused by the far server for a reason no log here would explain.
|
|
164
|
+
*/
|
|
165
|
+
secretSlug: z.string().min(1),
|
|
166
|
+
subject: z.enum(FlowsActors_OutboundCredentialSubject).default(FlowsActors_OutboundCredentialSubject.USER_THEN_ORGANIZATION),
|
|
167
|
+
});
|
|
168
|
+
export type FlowsActors_OutboundCredential = z.infer<typeof FlowsActors_OutboundCredentialSchema>;
|
|
169
|
+
```
|
|
@@ -131,45 +131,36 @@ export type FlowsActors_Agent = {
|
|
|
131
131
|
/**
|
|
132
132
|
* References to MCP servers the agent may reach.
|
|
133
133
|
*
|
|
134
|
-
* ##
|
|
134
|
+
* ## Checked at startup, called at turn start (#491, #3958)
|
|
135
135
|
*
|
|
136
|
-
* Each ref must name an MCP server the APPLICATION declared (`FlowsActors_McpServer
|
|
137
|
-
* `
|
|
138
|
-
*
|
|
139
|
-
* carried seven refs
|
|
140
|
-
* no server anywhere while the agent card rendered them as capabilities — a claim shown to a
|
|
141
|
-
* user about a reach the agent did not have. The catalog is gone and the card no longer
|
|
142
|
-
* renders these.
|
|
136
|
+
* Each ref must name an MCP server the APPLICATION declared (`FlowsActors_McpServer`, on a backend domain
|
|
137
|
+
* module's `flowsActors.mcpServers`), and startup REFUSES an agent whose refs name none. That closes the shape
|
|
138
|
+
* this field was in: it used to resolve against nothing, so a shipped
|
|
139
|
+
* catalog carried seven refs that named no server anywhere — a claim about a reach the agent did not have.
|
|
143
140
|
*
|
|
144
|
-
* The check is deliberately stricter than `functionRefs`, which skip an unknown ref with a
|
|
145
|
-
*
|
|
146
|
-
* as a capability, and a refusal makes the old state unreachable rather than fixed once.
|
|
141
|
+
* The check is deliberately stricter than `functionRefs`, which skip an unknown ref with a debug line: an unknown
|
|
142
|
+
* `functionRef` costs an agent one tool, whereas these name another party's server.
|
|
147
143
|
*
|
|
148
|
-
*
|
|
149
|
-
*
|
|
150
|
-
*
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
*
|
|
157
|
-
* 3. **Credential resolution at call time.** Decided 2026-09-09: the call carries the acting
|
|
158
|
-
* user's own delegated provider credential where present and the organization's connection
|
|
159
|
-
* otherwise, from `userProviderCredentials` / `organizationProviderCredentials` rather than
|
|
160
|
-
* a store invented for MCP. `FlowsActors_McpCredentialSubject` records that choice per
|
|
161
|
-
* server; nothing reads it yet.
|
|
144
|
+
* At turn start the agent opens a session with each named server, using the credential the server's declared
|
|
145
|
+
* `credential.subject` selects, and is offered the server's tools. They are withheld on a turn an inbound
|
|
146
|
+
* delivery started and when no credential resolves; a server that does not answer contributes no tools rather
|
|
147
|
+
* than failing the turn. Every tool call, and a target the outbound guard refuses, is recorded on the audit
|
|
148
|
+
* trail; an unreachable or slow server is logged.
|
|
149
|
+
*/
|
|
150
|
+
mcpRefs: string[],
|
|
151
|
+
/**
|
|
152
|
+
* References to remote A2A agents the agent may delegate a task to (#3930).
|
|
162
153
|
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
165
|
-
* returns a typed error the agent can reason about. Both emit an audit event, because a server
|
|
166
|
-
* quietly unreachable for a week must be visible as that rather than as an agent that became
|
|
167
|
-
* less capable for no stated reason.
|
|
154
|
+
* Each ref must name a remote agent the APPLICATION declared (`FlowsActors_RemoteAgent`, on a backend domain
|
|
155
|
+
* module's `flowsActors.remoteAgents`); startup REFUSES an agent whose refs name none, as for `mcpRefs`.
|
|
168
156
|
*
|
|
169
|
-
*
|
|
170
|
-
*
|
|
157
|
+
* At turn start the agent is offered one tool per named remote agent, described by the declaration (never by the
|
|
158
|
+
* remote card). A call sends the agent's message to the remote agent over A2A 1.0 with the credential the
|
|
159
|
+
* declaration's `credential.subject` selects, and returns the remote reply, or the remote task's state and ids
|
|
160
|
+
* when it is still running or waits for input. Withheld on a turn an inbound delivery started and when no
|
|
161
|
+
* credential resolves. Every call is recorded on the audit trail.
|
|
171
162
|
*/
|
|
172
|
-
|
|
163
|
+
remoteAgentRefs?: string[],
|
|
173
164
|
},
|
|
174
165
|
},
|
|
175
166
|
|
|
@@ -177,6 +177,12 @@ unconfirmed todo and never answers; a follow-up on a linked thread becomes a che
|
|
|
177
177
|
/** The template the answer is rendered from — `emails/resources/todos/email-intake.received/`. */
|
|
178
178
|
export const TODO_EMAIL_RECEIVED_TEMPLATE_REF = 'email.todos.email-intake.received';
|
|
179
179
|
|
|
180
|
+
/** The answer to "summary" on a linked thread — `emails/resources/todos/email-intake.summary/`. */
|
|
181
|
+
export const TODO_EMAIL_SUMMARY_TEMPLATE_REF = 'email.todos.email-intake.summary';
|
|
182
|
+
|
|
183
|
+
/** What a sender writes, alone, on a linked thread to receive the todo's summary PDF. */
|
|
184
|
+
export const TODO_EMAIL_SUMMARY_REQUEST = 'summary';
|
|
185
|
+
|
|
180
186
|
/** The route tag of the screened address, `acme+screened@…`. */
|
|
181
187
|
export const TODO_EMAIL_SCREENED_ROUTE_TAG = 'screened';
|
|
182
188
|
|
|
@@ -256,8 +262,32 @@ async function addFollowUpOnce(ctx: InboundChannelHandlerContextBase, todoId: st
|
|
|
256
262
|
await ctx.resources.update(TasksManager_ResourceType.TODOS, todoId, { checklist: [...checklist, { label: `${label} ${marker}`, done: false }] });
|
|
257
263
|
}
|
|
258
264
|
|
|
265
|
+
/** A follow-up whose whole text is the word {@link TODO_EMAIL_SUMMARY_REQUEST}, in any case. */
|
|
266
|
+
function asksForSummary(message: InboundMessage<InboundChannelKind.EMAIL>): boolean {
|
|
267
|
+
return (message.strippedReply ?? message.text).trim().toLowerCase() === TODO_EMAIL_SUMMARY_REQUEST;
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
/**
|
|
271
|
+
* Answers "summary" with the todo's generated summary PDF attached (#1856). The handler names the file; the engine
|
|
272
|
+
* checks it with the handler's own read (the file belongs to the organization, is servable, and the todo still holds
|
|
273
|
+
* it) before the reply is queued. A todo with no summary yet gets the same template, saying so.
|
|
274
|
+
*/
|
|
275
|
+
async function replyWithSummary(ctx: InboundChannelHandlerContext<InboundReplyMode.THREAD>, todoId: string): Promise<void> {
|
|
276
|
+
const todo = await ctx.resources.read<Todos>(TasksManager_ResourceType.TODOS, todoId);
|
|
277
|
+
if (!todo) throw Object.assign(new Error('The todo this thread is about no longer exists'), { name: 'TodoNotFound' });
|
|
278
|
+
// A `z_file` value is typed as either shape (one file, or `fileIds` for a multi-file field); this field holds one.
|
|
279
|
+
const summary = todo.generatedSummaryPdf;
|
|
280
|
+
const summaryFileId = summary && 'fileId' in summary ? summary.fileId : undefined;
|
|
281
|
+
await ctx.reply({
|
|
282
|
+
templateRef: TODO_EMAIL_SUMMARY_TEMPLATE_REF,
|
|
283
|
+
variables: { todoTitle: todo.title, hasSummary: Boolean(summaryFileId) },
|
|
284
|
+
...(summaryFileId ? { attachmentFileIds: [summaryFileId] } : {}),
|
|
285
|
+
});
|
|
286
|
+
}
|
|
287
|
+
|
|
259
288
|
/**
|
|
260
|
-
* What both answering handlers do: a message on a thread already linked to a todo is a follow-up
|
|
289
|
+
* What both answering handlers do: a message on a thread already linked to a todo is a follow-up (or, when it
|
|
290
|
+
* reads only "summary", a request for the todo's summary PDF); any other
|
|
261
291
|
* becomes a new todo, the thread is linked to it, and the sender is answered.
|
|
262
292
|
*/
|
|
263
293
|
async function intake(
|
|
@@ -266,7 +296,8 @@ async function intake(
|
|
|
266
296
|
): Promise<void> {
|
|
267
297
|
const linked = message.thread.linkedResource;
|
|
268
298
|
if (linked?.resourceType === TasksManager_ResourceType.TODOS) {
|
|
269
|
-
await
|
|
299
|
+
if (asksForSummary(message)) await replyWithSummary(ctx, linked.resourceId);
|
|
300
|
+
else await addFollowUpOnce(ctx, linked.resourceId, message);
|
|
270
301
|
return;
|
|
271
302
|
}
|
|
272
303
|
const list = await resolveTargetList(ctx, message.payload.routeTag);
|
|
@@ -809,8 +809,10 @@ platform runs. `serviceProfile: EnvironmentServiceProfile.SMALL` (import
|
|
|
809
809
|
it from `@wildo-ai/platform-config-lib`) keeps the services the platform
|
|
810
810
|
cannot run without (one database, the cache and the object store) and
|
|
811
811
|
drops three optional ones. Its background work (queued jobs, scheduled
|
|
812
|
-
batches) runs on the application's own database instead of RabbitMQ
|
|
813
|
-
|
|
812
|
+
batches) runs on the application's own database instead of RabbitMQ, and the
|
|
813
|
+
environment runs no broker at all: no RabbitMQ container, no `RABBITMQ_*`
|
|
814
|
+
settings, no broker credential. A `backingServices.rabbitmq` declaration beside
|
|
815
|
+
`SMALL` is refused; remove it when you switch an environment to `SMALL`:
|
|
814
816
|
|
|
815
817
|
| Service the profile drops | Capability it backs | What happens if the application declares the capability anyway |
|
|
816
818
|
|---|---|---|
|
|
@@ -850,6 +852,10 @@ Rules the descriptor enforces when the file is parsed:
|
|
|
850
852
|
- `SMALL` beside `backingServices.clamav` or `.immudb` with
|
|
851
853
|
`source: SELF` is refused. The two statements contradict each other;
|
|
852
854
|
remove one.
|
|
855
|
+
- `SMALL` beside any `backingServices.rabbitmq` declaration is refused:
|
|
856
|
+
the profile runs no broker, so a self-hosted one contradicts it and a
|
|
857
|
+
managed one would be a broker nothing uses. A hosted application that
|
|
858
|
+
declares a vhost on a `SMALL` host is refused the same way.
|
|
853
859
|
- `SMALL` with two database families is refused, and the message names
|
|
854
860
|
the declarations that bring each one in: a second store in
|
|
855
861
|
`backingServices`, a platform `database.engine` that differs from the
|
|
@@ -868,17 +874,33 @@ record that contradicts the profile, for an environment whose
|
|
|
868
874
|
`config.json` was written before the profile was authored: run
|
|
869
875
|
`wildo config sync` after changing the descriptor.
|
|
870
876
|
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
877
|
+
Under `SMALL` the platform's scheduler delivers each scheduled run to the
|
|
878
|
+
application backend over HTTP, and the backend queues it in its own
|
|
879
|
+
database, so nothing needs a broker: RabbitMQ is not rendered on either
|
|
880
|
+
lane and the platform mints no broker credential for any application.
|
|
881
|
+
|
|
882
|
+
On a local Kubernetes (Kind) environment the scheduler runs in the
|
|
883
|
+
cluster while the backends run on your machine, so its pod reaches them
|
|
884
|
+
at `host.docker.internal`, as compose does. Docker Desktop resolves that
|
|
885
|
+
name inside the cluster; on Docker Engine for Linux the pod maps it to
|
|
886
|
+
the Docker bridge gateway, which the backend also listens on. Rootless
|
|
887
|
+
Docker has no such address, and scheduled runs there stay undelivered:
|
|
888
|
+
each retry records the host gateway address the scheduler dialled.
|
|
875
889
|
|
|
876
890
|
Moving between profiles migrates no data. Going to `SMALL`, the next
|
|
877
891
|
`wildo local dev` / `wildo local up` stops the dropped containers and
|
|
878
|
-
keeps their data volumes.
|
|
892
|
+
keeps their data volumes. Jobs still queued in RabbitMQ at that moment
|
|
893
|
+
are not moved to the database queue: let the queues drain (or accept
|
|
894
|
+
losing what is left) before switching. Going back to `FULL`, each service starts
|
|
879
895
|
from what it kept or from empty: mongot rebuilds its indexes from the
|
|
880
|
-
collections,
|
|
881
|
-
database audit trail does)
|
|
896
|
+
collections, a new immudb holds no earlier audit history (the
|
|
897
|
+
database audit trail does), and RabbitMQ starts from the data it kept:
|
|
898
|
+
the broker users and vhosts it held come back, and an application with
|
|
899
|
+
none is minted its credentials at its next registration (the next
|
|
900
|
+
`wildo local dev`). An application withdrawn while the environment was
|
|
901
|
+
`SMALL` could not have its broker credentials revoked (the withdrawal
|
|
902
|
+
names them); withdraw it again after switching back, or delete the
|
|
903
|
+
broker's data directory before switching.
|
|
882
904
|
|
|
883
905
|
## Choosing the application's store — and what it obliges
|
|
884
906
|
|
|
@@ -161,10 +161,12 @@ export function resolveDefaultLocalDataStorage(locationType: WildoLocationType):
|
|
|
161
161
|
* HTTP rather than onto a broker. A minion is confined to its own queues there by a PostgreSQL row-level security policy;
|
|
162
162
|
* MongoDB has none, so a MongoDB application's minions are refused under `SMALL` (`describeMinionsRefusedByEnvironmentServiceProfile`).
|
|
163
163
|
*
|
|
164
|
-
* ##
|
|
164
|
+
* ## No broker
|
|
165
165
|
*
|
|
166
|
-
*
|
|
167
|
-
*
|
|
166
|
+
* Since #2303 slice D a `SMALL` environment runs no RabbitMQ at all (`environmentServiceProfileRunsMessageBroker`): neither
|
|
167
|
+
* lane renders it, no env file carries `RABBITMQ_*`, no runtime joins its network segment, and apps-manager (told through
|
|
168
|
+
* `PLATFORM_ENVIRONMENT_SERVICE_PROFILE`) initializes no admin client and mints, revokes or restores no vhost or credential.
|
|
169
|
+
* A `backingServices.rabbitmq` declaration beside it is refused.
|
|
168
170
|
*/
|
|
169
171
|
export enum EnvironmentServiceProfile {
|
|
170
172
|
/** Every service the environment's declarations ask for. The default when nothing is authored. */
|
|
@@ -172,7 +174,7 @@ export enum EnvironmentServiceProfile {
|
|
|
172
174
|
/**
|
|
173
175
|
* The footprint for a small deployment: no ClamAV, no immudb, no mongot
|
|
174
176
|
* ({@link servicesOmittedByEnvironmentServiceProfile}), one database family, and background work on the application's
|
|
175
|
-
* own database instead of RabbitMQ (minions only on PostgreSQL). Vector search remains available on PostgreSQL
|
|
177
|
+
* own database instead of RabbitMQ, which it does not run (minions only on PostgreSQL). Vector search remains available on PostgreSQL
|
|
176
178
|
* (pgvector is part of the PostgreSQL image, not a separate service).
|
|
177
179
|
*/
|
|
178
180
|
SMALL = 'small',
|
|
@@ -249,6 +251,27 @@ export function queueAdapterTypeOfEnvironmentServiceProfile(profile: Environment
|
|
|
249
251
|
}
|
|
250
252
|
}
|
|
251
253
|
|
|
254
|
+
/**
|
|
255
|
+
* Whether an environment under `profile` runs a message broker at all (#2303 slice D). Derived from
|
|
256
|
+
* {@link queueAdapterTypeOfEnvironmentServiceProfile}, never authored: the broker exists to carry the RabbitMQ queue, and
|
|
257
|
+
* under the DATABASE queue nothing in the environment uses one (the platform scheduler delivers over HTTP). Absent profile
|
|
258
|
+
* ⇒ {@link DEFAULT_ENVIRONMENT_SERVICE_PROFILE}.
|
|
259
|
+
*
|
|
260
|
+
* The ONE answer every broker decision reads: whether a deployment lane renders RabbitMQ, whether an env file carries
|
|
261
|
+
* `RABBITMQ_*`, whether apps-manager initializes its RabbitMQ admin client and mints a vhost and credentials, and whether
|
|
262
|
+
* a `backingServices.rabbitmq` declaration contradicts the profile. Total over the queue vocabulary through the switch
|
|
263
|
+
* below, so a third queue adapter must decide here whether it needs a broker.
|
|
264
|
+
*/
|
|
265
|
+
export function environmentServiceProfileRunsMessageBroker(profile: EnvironmentServiceProfile | undefined): boolean {
|
|
266
|
+
switch (queueAdapterTypeOfEnvironmentServiceProfile(profile ?? DEFAULT_ENVIRONMENT_SERVICE_PROFILE)) {
|
|
267
|
+
case QueueAdapterType.RABBITMQ:
|
|
268
|
+
return true;
|
|
269
|
+
case QueueAdapterType.DATABASE:
|
|
270
|
+
case QueueAdapterType.MEMORY:
|
|
271
|
+
return false;
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
|
|
252
275
|
/**
|
|
253
276
|
* Why an application that declares minions cannot run under `profile` on `applicationDatabaseEngine`, or undefined when it
|
|
254
277
|
* can (#2303).
|
package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md
CHANGED
|
@@ -272,6 +272,32 @@ wildo local deregister --reason "scratch application, no longer used"
|
|
|
272
272
|
wildo local restore && wildo local dev
|
|
273
273
|
```
|
|
274
274
|
|
|
275
|
+
### `wildo local jobs` / `wildo local jobs run`
|
|
276
|
+
|
|
277
|
+
Run one of the application's scheduled jobs NOW instead of waiting for its next tick, on the platform
|
|
278
|
+
the active environment names. Run from the application root; `--app <slug>` disambiguates.
|
|
279
|
+
|
|
280
|
+
| Command | Effect |
|
|
281
|
+
|------|--------|
|
|
282
|
+
| `wildo local jobs` | Lists the application's scheduled jobs, each with the selector `run` takes, beside the number of jobs the scheduler holds for every application (an empty list beside a total of 0 means the scheduler holds nothing yet: has the backend booted?). `--json` prints one document. |
|
|
283
|
+
| `wildo local jobs run <selector>` | Runs that job's ordinary execution once, asynchronously, through the scheduler's manual trigger. Its schedule does not change, and a disabled schedule still runs. The answer means the occurrence was queued for the backend; read its effect where the job writes, a moment later. |
|
|
284
|
+
| `wildo local jobs run <selector> --reason "<why>"` | Records why on the platform audit row every run request leaves. |
|
|
285
|
+
|
|
286
|
+
The selector is application-relative: `<resourceType>.<operation>[:<variantKey>]` for a resource
|
|
287
|
+
operation declared with a cron schedule (the variant may be left out when the operation has one
|
|
288
|
+
schedule), `batch:<ref>` for a custom batch, `minion-tick:<name>` for a minion's tick. Never type the
|
|
289
|
+
platform's job id: the verb resolves the selector against the listing. It refuses a job of another
|
|
290
|
+
application and a job the scheduler no longer holds, and it fails (exit 1) when the run could not be
|
|
291
|
+
queued; it is sent once, never retried, because a re-send could run the job twice.
|
|
292
|
+
|
|
293
|
+
```bash
|
|
294
|
+
# What is scheduled, and the selectors:
|
|
295
|
+
wildo local jobs
|
|
296
|
+
|
|
297
|
+
# Produce now what an hourly job would write at the top of the hour:
|
|
298
|
+
wildo local jobs run <resourceType>.<operation> --reason "checking what the job writes"
|
|
299
|
+
```
|
|
300
|
+
|
|
275
301
|
### `wildo config sync`
|
|
276
302
|
|
|
277
303
|
Regenerate one or more **generated artifact domains** from the
|
package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md
CHANGED
|
@@ -186,6 +186,19 @@ export interface BackendDomainModule extends SharedDomainModule {
|
|
|
186
186
|
* `capabilities.tools.functionRefs`.
|
|
187
187
|
*/
|
|
188
188
|
functionTools?: FunctionTool[];
|
|
189
|
+
/**
|
|
190
|
+
* Another party's MCP servers this module's agents may call (#3958): each one's endpoint and the stored provider
|
|
191
|
+
* connection whose credential reaches it. Reference them from an agent's `capabilities.tools.mcpRefs`. Registration
|
|
192
|
+
* refuses a plaintext `http://` endpoint, and every call goes through the outbound guard. See `FlowsActors_McpServer`.
|
|
193
|
+
*/
|
|
194
|
+
mcpServers?: FlowsActors_McpServer[];
|
|
195
|
+
/**
|
|
196
|
+
* Another party's A2A agents this module's agents may delegate a task to (#3930): each one's card URL and the stored
|
|
197
|
+
* provider connection whose credential reaches it. Reference them from an agent's
|
|
198
|
+
* `capabilities.tools.remoteAgentRefs`. Registration refuses a plaintext `http://` card or endpoint, and every call
|
|
199
|
+
* goes through the outbound guard. See `FlowsActors_RemoteAgent`.
|
|
200
|
+
*/
|
|
201
|
+
remoteAgents?: FlowsActors_RemoteAgent[];
|
|
189
202
|
/**
|
|
190
203
|
* Agents that may run with nobody on a socket — on a schedule or on an inbound delivery (#1611).
|
|
191
204
|
* Declaring one grants nothing: a turn runs in an organization only while one of its OAuth clients
|
|
@@ -594,6 +607,8 @@ function mergeFlowsActors(
|
|
|
594
607
|
) as FlowActorSystem_InitializationFactoryMap,
|
|
595
608
|
agents: modules.flatMap(m => m.flowsActors?.agents ?? []),
|
|
596
609
|
functionTools: modules.flatMap(m => m.flowsActors?.functionTools ?? []),
|
|
610
|
+
mcpServers: modules.flatMap(m => m.flowsActors?.mcpServers ?? []),
|
|
611
|
+
remoteAgents: modules.flatMap(m => m.flowsActors?.remoteAgents ?? []),
|
|
597
612
|
autonomousAgents: modules.flatMap(m => m.flowsActors?.autonomousAgents ?? []),
|
|
598
613
|
chatAgents: modules.flatMap(m => m.flowsActors?.chatAgents ?? []),
|
|
599
614
|
actorExecutionContinuations: modules.flatMap(m => m.flowsActors?.actorExecutionContinuations ?? []),
|
|
@@ -115,6 +115,19 @@ one `[dependent-lifecycle-unclassified]` warning. Declare one of four on the edg
|
|
|
115
115
|
- `onParentDelete: { enabled: false }` — the rows deliberately outlive their parent
|
|
116
116
|
intact (evidence of an erasure, for example). Say why in a comment.
|
|
117
117
|
|
|
118
|
+
**`mode: LAZY` defers a `DELETE` teardown to the queue.** Use it on an edge whose child set
|
|
119
|
+
only grows (one row per day a recurring item came due, one per event) so that deleting the
|
|
120
|
+
parent does not delete thousands of rows inside the request: the delete enqueues the
|
|
121
|
+
teardown, and the child-teardown job removes the children once the delete has committed,
|
|
122
|
+
re-checking later if it runs first. Until then the children briefly outlive their parent.
|
|
123
|
+
Two limits, both enforced:
|
|
124
|
+
|
|
125
|
+
- A subject erasure whose plan reaches a LAZY edge, at any depth, is REFUSED: an erasure
|
|
126
|
+
cannot wait for a queue. Keep LAZY off any edge an erasure must cross (anything a user
|
|
127
|
+
edge composes). The backend lists every LAZY edge at boot under one
|
|
128
|
+
`[dependent-lifecycle-deferred]` warning.
|
|
129
|
+
- LAZY takes the `DELETE` strategy only. Boot refuses it beside `IMPERSONALIZE_AND_RETAIN`.
|
|
130
|
+
|
|
118
131
|
Mind `maxDepth` where edges meet: a deeper budget carries a child's own DELETE cascade
|
|
119
132
|
further down, and can hard-delete rows another edge of the same parent retains.
|
|
120
133
|
|
|
@@ -471,7 +484,13 @@ when the parent's `recurringType` is `RECURRING`:
|
|
|
471
484
|
foreignKeyField: 'todoId',
|
|
472
485
|
// Static discriminator: only applies when parent todo is RECURRING
|
|
473
486
|
discriminator: { discriminatorField: todosRecurringTypeField, values: [Todos_RecurrenceType.RECURRING] },
|
|
474
|
-
|
|
487
|
+
// LAZY: a recurring todo gains an occurrence every time it comes due, so a daily todo's set only grows, and deleting
|
|
488
|
+
// it should not delete years of rows inside the request. The delete enqueues the teardown; the child-teardown job
|
|
489
|
+
// removes the occurrences once the delete has committed, and re-checks later if it runs first (#2586). Until then
|
|
490
|
+
// an occurrence may outlive its todo briefly. It is the application's one
|
|
491
|
+
// LAZY edge, so the boot report lists it under [dependent-lifecycle-deferred]. No subject erasure reaches it: no
|
|
492
|
+
// user edge composes a todo or a todo list, and a tenant purge RETAINS todos (the ORGANIZATIONS edge above).
|
|
493
|
+
childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.LAZY, maxDepth: 1 } } },
|
|
475
494
|
// Only applies to RECURRING todos (Edge Case #2 handled in backend). LIST context is open so the
|
|
476
495
|
// todo page can list a recurring todo's occurrences (#1787); occurrences declare no SEARCH.
|
|
477
496
|
contextPolicy: {
|
|
@@ -20,12 +20,21 @@ Read and apply these patterns from the application-developer point of view:
|
|
|
20
20
|
|
|
21
21
|
## Overview
|
|
22
22
|
|
|
23
|
-
Backend providers have three packaging homes
|
|
23
|
+
Backend providers have three packaging homes, and they are tried IN ORDER. Use what the
|
|
24
|
+
framework already has; author a provider only when nothing below fills the need:
|
|
24
25
|
|
|
25
26
|
- **Engine modules** come with the engine's provider package; enabling one needs no separate vendor package.
|
|
26
27
|
- **Provider modules from the module registry.** `wildo registry add wildo/providers/<ref>` copies the framework's module for one vendor into `providers/<ref>/` and makes it the application's own: its backend part becomes the workspace package `@<your-scope>/provider-<ref>` (`providers/<ref>/backend/`), and its browser part, when it has one, `@<your-scope>/provider-<ref>-frontend` (`providers/<ref>/frontend/`). You own the copy and may edit it; `wildo registry update` keeps and warns about a file you changed instead of overwriting it. `wildo registry search --domain wildo --kind provider` lists the modules on offer; add `--engine-capability <CAPABILITY>` for the ones that fill a capability (`AI_DOCUMENT_EXTRACTION`, say) or `--maturity proven` for the ones that have met the real vendor. A hit that adds operations to another provider says so, and is bound as that provider.
|
|
27
28
|
- **Separately authored packages** use `@wildo-ai/provider-<ref>` or the application's own scope, for example `@acme/provider-crm`. Any other package — another scope, or an own-scope one not named `provider-*` — is admitted only when the application lists it in `providers.packages`.
|
|
28
29
|
|
|
30
|
+
**Author last, and only for a recorded reason.** Before authoring anything, check the engine's
|
|
31
|
+
providers and `wildo registry search --domain wildo --kind provider`. Author a new provider only
|
|
32
|
+
when none of them fills the need (a vendor none offers, a behaviour they lack, or a business
|
|
33
|
+
obligation that names a vendor), and only when that reason is recorded: in a creation run, the
|
|
34
|
+
integration plan's `unprovidedNeeds` entry for the provider's ref; otherwise, in the provider
|
|
35
|
+
package's own README. "It was quicker to write one" is not a reason, and a hand-written copy of a
|
|
36
|
+
registry module is a fork nothing updates.
|
|
37
|
+
|
|
29
38
|
Discovery reads companion contributions to establish each provider's identity and import path.
|
|
30
39
|
Runtime scope then decides which hosts may load it. A worker that declares one email sender does
|
|
31
40
|
not acquire access to every provider just because their packages are installed.
|
|
@@ -64,7 +73,9 @@ Never edit the generated artifacts. They are overwritten by every
|
|
|
64
73
|
companion in addition to the backend.
|
|
65
74
|
- Diagnosing a startup refusal that names a provider ref.
|
|
66
75
|
- Authoring an application-owned provider package under the
|
|
67
|
-
application's own npm scope
|
|
76
|
+
application's own npm scope, ONLY after the engine's providers and the
|
|
77
|
+
registry were checked and offer nothing that fills the need, with the reason
|
|
78
|
+
recorded (see "Author last" above).
|
|
68
79
|
- Adding operations to a provider another package or the engine owns
|
|
69
80
|
(an "augmentation", e.g. chat operations on a CRM provider another
|
|
70
81
|
package ships),
|
|
@@ -69,6 +69,8 @@ export const PROVIDER_CAPABILITY_FRONTEND_CONSENT_CLASSIFICATION = Object.freeze
|
|
|
69
69
|
SMS: SERVER_ONLY,
|
|
70
70
|
// #2293: a deliverable is sent for signature from the backend; the vendor's signing page is its own, not a browser SDK.
|
|
71
71
|
ELECTRONIC_SIGNATURE: SERVER_ONLY,
|
|
72
|
+
// The frame is the application's own engine component, not a browser module the provider loads.
|
|
73
|
+
EMBEDDED_ELECTRONIC_SIGNATURE: SERVER_ONLY,
|
|
72
74
|
SSO_SAML: SERVER_ONLY,
|
|
73
75
|
LLM_CHAT: SERVER_ONLY,
|
|
74
76
|
LLM_EMBEDDINGS: SERVER_ONLY,
|
|
@@ -69,6 +69,9 @@ surfaces it serves; `wildo registry search --domain wildo --kind provider`
|
|
|
69
69
|
lists the modules. If one exists, install it with
|
|
70
70
|
`wildo registry add wildo/providers/<ref>` and skip to Step 4: you supply its
|
|
71
71
|
keys, you do not author it. Read `references/package-frontend-facets.md`.
|
|
72
|
+
Author a module only when neither the engine nor the registry ships the
|
|
73
|
+
vendor's browser part, and record why (in a creation run, the integration
|
|
74
|
+
plan's `unprovidedNeeds` entry for its ref).
|
|
72
75
|
|
|
73
76
|
### Step 2: Choose the capability and the facet
|
|
74
77
|
|
|
@@ -85,7 +85,9 @@ SaaS configuration key, contribution `moduleId` and semantics `relatedModuleId`
|
|
|
85
85
|
- Frontend: author a `FrontendModule` containing resource UI behavior, composite views and the
|
|
86
86
|
intended app-shell contribution. Re-exporting a resources barrel is not a frontend registration.
|
|
87
87
|
- Backend: author the application-local `BackendOwnedModule` and its `backendModule` contribution.
|
|
88
|
-
Follow
|
|
88
|
+
Follow `backend-addon-wiring` for actors and email templates. A module's emails live in `emails/` and its
|
|
89
|
+
custom operations under `resources/`, never in a folder of your own: `check:module-layout` refuses a module file
|
|
90
|
+
outside its conventional folder (`references/module-scaffold-layout.md` lists them). Labels are engine-owned;
|
|
89
91
|
do not add a per-module `customLabels` owner or `i18n/` directory.
|
|
90
92
|
- Specifications: export the named `ModuleBusinessSemantics` value and the applicable resource/view
|
|
91
93
|
specification maps. This slice does not require a default export.
|
|
@@ -135,6 +137,7 @@ Add business-specific operations and UI behavior through their own authoring wor
|
|
|
135
137
|
- [ ] Backend discovery sees the emitted default owner and its expected backend contribution.
|
|
136
138
|
- [ ] The SaaS configuration contains the module binding, separate from source registration.
|
|
137
139
|
- [ ] Public entrypoints expose the intended shared and specification declarations.
|
|
140
|
+
- [ ] Every conventional module file is in its conventional folder (`check:module-layout`; `emails/`, `resources/`).
|
|
138
141
|
- [ ] Package checks pass and the relevant running application surface uses the contribution.
|
|
139
142
|
|
|
140
143
|
Locate the standard registration anchors from the application root:
|
|
@@ -145,6 +148,8 @@ rg -n 'applicationFrontendModules' frontend/src/modules/index.ts
|
|
|
145
148
|
rg -n 'applicationModuleBusinessSemantics' specifications/src/module-registry.specification.ts
|
|
146
149
|
rg -n 'scanSubdirDefaultExports' backend-api/src/modules/index.ts
|
|
147
150
|
rg -n 'applicationModules|services' wildo.saas.config.ts
|
|
151
|
+
# A module's email definitions outside emails/ (expect no output; check:module-layout says the same)
|
|
152
|
+
rg -l 'scanEmailTemplateDirectory' backend-api/src/modules | rg -v '/emails/'
|
|
148
153
|
```
|
|
149
154
|
|
|
150
155
|
These searches locate owners; inspect list membership and runtime output rather than treating
|
|
@@ -157,11 +162,12 @@ matching text as proof of successful loading. For a custom topology, follow its
|
|
|
157
162
|
- The backend scanner is edited to add a manual module list.
|
|
158
163
|
- A running process is checked before the new emitted module has been published.
|
|
159
164
|
- Empty copied folders, stale exports or a duplicated label owner remain from the reference module.
|
|
165
|
+
- A module's emails sit in `email/` (or any folder but `emails/`), or a resource file sits outside `resources/`: `check:module-layout` fails the task until it is moved.
|
|
160
166
|
|
|
161
167
|
## References
|
|
162
168
|
|
|
163
169
|
- `references/framework-composition-scenarios-api.md` — complete commands, preview and collision behavior.
|
|
164
|
-
- `references/module-scaffold-layout.md` — package layout
|
|
170
|
+
- `references/module-scaffold-layout.md` — package layout, explicit registration checklist, and the conventional folders `check:module-layout` holds a module to.
|
|
165
171
|
- `references/framework-new-module-wiring-api.md` — source-backed SaaS and shared module contracts.
|
|
166
172
|
|
|
167
173
|
## Related Skills
|