@wildo-ai/framework-knowledge 1.1.13 → 1.1.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
- package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +12 -4
- package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +4 -0
- package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
- package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
- package/dist/esm/framework-knowledge.definitions.js +9 -0
- package/dist/esm/framework-knowledge.definitions.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.assemble-verify/playbook.definition.js.map +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.d.ts +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js +1 -1
- package/dist/esm/playbooks/bottom_up.integration-plan/playbook.definition.js.map +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/authority-basis.json +1 -1
- package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
- package/dist/knowledge/manifest.json +7 -7
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/method.md +7 -0
- package/dist/knowledge/playbooks/bottom_up.assemble-verify/playbook.json +2 -2
- package/dist/knowledge/playbooks/bottom_up.build-decompose/method.md +27 -10
- package/dist/knowledge/playbooks/bottom_up.build-decompose/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/method.md +13 -9
- package/dist/knowledge/playbooks/bottom_up.build-dispatch/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
- package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +1 -1
- package/dist/knowledge/playbooks/bottom_up.integration-plan/method.md +20 -5
- package/dist/knowledge/playbooks/bottom_up.integration-plan/playbook.json +2 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +15 -2
- package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
- package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
- package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
- package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
- package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
- package/dist/knowledge/references/example.config.navigation.full.md +14 -0
- package/dist/knowledge/references/example.flows-actors.autonomous-agent.reviewed-write.md +6 -2
- package/dist/knowledge/references/example.flows-actors.chat-assistant.md +13 -2
- package/dist/knowledge/references/example.inbound.email-to-todo.md +33 -2
- package/dist/knowledge/references/example.module.relationships.discriminator.md +7 -1
- package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
- package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
- package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md +2 -0
- package/dist/knowledge/references/integration-plan.config.md +78 -8
- package/dist/knowledge/references/platform.config.environment.deployment.md +84 -5
- package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
- package/dist/knowledge/references/saas.backend.domain-module.md +15 -0
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-agent-card.md +43 -11
- package/dist/knowledge/references/saas.backend.flows-actors.a2a-task-surface.md +17 -11
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +11 -0
- package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
- package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
- package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
- package/dist/knowledge/references/saas.models.flows-actors.mcp-server-declaration.md +63 -0
- package/dist/knowledge/references/saas.models.flows-actors.outbound-credential.md +61 -0
- package/dist/knowledge/references/saas.models.flows-actors.remote-agent-declaration.md +56 -0
- package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
- package/dist/knowledge/references/saas.models.http-api-binding.md +51 -0
- package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
- package/dist/knowledge/references/saas.models.privacy.provider-capability-disclosure.md +7 -0
- package/dist/knowledge/references/saas.models.provider-capabilities.md +11 -0
- package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
- package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
- package/dist/knowledge/references/saas.models.system-of-record-error-codes.md +30 -0
- package/dist/knowledge/references/saas.rag.retrieval-scores.md +4 -2
- package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
- package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
- package/dist/knowledge/registries/framework-topics.json +45 -1
- package/dist/knowledge/registries/playbooks.json +2 -2
- package/dist/knowledge/registries/source-tags.json +1175 -1107
- package/dist/knowledge/skills/INDEX.md +2 -2
- package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +9 -2
- package/dist/knowledge/skills/backend-addon-wiring/references/framework-backend-bootstrap-api.md +15 -0
- package/dist/knowledge/skills/backend-custom-operation/SKILL.md +3 -1
- package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
- package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +21 -1
- package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +15 -2
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
- package/dist/knowledge/skills/compliance-document-authoring/references/framework-recipient-disclosures.md +7 -0
- package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
- package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
- package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
- package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +1 -0
- package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +15 -1
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
- package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +12 -5
- package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
- package/dist/knowledge/skills/email-add-template/SKILL.md +3 -2
- package/dist/knowledge/skills/email-add-template/references/email-artifact-paths.md +8 -4
- package/dist/knowledge/skills/email-definition-wiring/SKILL.md +1 -1
- package/dist/knowledge/skills/flows-actors-a2a-exposure/SKILL.md +29 -7
- package/dist/knowledge/skills/flows-actors-a2a-exposure/references/framework-flows-actors-a2a-contract.md +66 -26
- package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +6 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +34 -3
- package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md +13 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +11 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +15 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-mcp-server-declaration-api.md +139 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +169 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
- package/dist/knowledge/skills/inbound-channels/references/receiving-email.md +33 -2
- package/dist/knowledge/skills/infra-environment-config/SKILL.md +39 -13
- package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +84 -5
- package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
- package/dist/knowledge/skills/local-environment-bootstrap/references/wildo-cli-bootstrap-commands.md +26 -0
- package/dist/knowledge/skills/module-registration/references/framework-domain-modules-api.md +15 -0
- package/dist/knowledge/skills/module-relationships/SKILL.md +20 -1
- package/dist/knowledge/skills/provider-backend-package/SKILL.md +13 -2
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-provider-consent-api.md +2 -0
- package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
- package/dist/knowledge/skills/provider-frontend-module/SKILL.md +3 -0
- package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
- package/dist/knowledge/skills/resource-add-module/SKILL.md +8 -2
- package/dist/knowledge/skills/resource-add-module/references/module-scaffold-layout.md +17 -0
- package/dist/knowledge/skills/resource-chat-commands/SKILL.md +1 -1
- package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
- package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -3
- package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
- package/dist/knowledge/skills/resource-external-data/references/framework-http-api-binding-api.md +51 -0
- package/dist/knowledge/skills/resource-external-data/references/incremental-extraction.md +14 -5
- package/dist/knowledge/skills/resource-external-data/references/read-through-writes.md +30 -0
- package/dist/knowledge/skills/resource-mcp-tool-exposure/references/mcp-client-registration-postures.md +5 -0
- package/dist/knowledge/skills/resource-rag-source-fields/references/framework-rag-retrieval-api.md +4 -2
- package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
- package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
- package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
- package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
- package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
- package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
- package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
- package/dist/knowledge/topic-index.json +326 -179
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +4 -4
|
@@ -7,6 +7,12 @@
|
|
|
7
7
|
/** The template the answer is rendered from — `emails/resources/todos/email-intake.received/`. */
|
|
8
8
|
export const TODO_EMAIL_RECEIVED_TEMPLATE_REF = 'email.todos.email-intake.received';
|
|
9
9
|
|
|
10
|
+
/** The answer to "summary" on a linked thread — `emails/resources/todos/email-intake.summary/`. */
|
|
11
|
+
export const TODO_EMAIL_SUMMARY_TEMPLATE_REF = 'email.todos.email-intake.summary';
|
|
12
|
+
|
|
13
|
+
/** What a sender writes, alone, on a linked thread to receive the todo's summary PDF. */
|
|
14
|
+
export const TODO_EMAIL_SUMMARY_REQUEST = 'summary';
|
|
15
|
+
|
|
10
16
|
/** The route tag of the screened address, `acme+screened@…`. */
|
|
11
17
|
export const TODO_EMAIL_SCREENED_ROUTE_TAG = 'screened';
|
|
12
18
|
|
|
@@ -86,8 +92,32 @@ async function addFollowUpOnce(ctx: InboundChannelHandlerContextBase, todoId: st
|
|
|
86
92
|
await ctx.resources.update(TasksManager_ResourceType.TODOS, todoId, { checklist: [...checklist, { label: `${label} ${marker}`, done: false }] });
|
|
87
93
|
}
|
|
88
94
|
|
|
95
|
+
/** A follow-up whose whole text is the word {@link TODO_EMAIL_SUMMARY_REQUEST}, in any case. */
|
|
96
|
+
function asksForSummary(message: InboundMessage<InboundChannelKind.EMAIL>): boolean {
|
|
97
|
+
return (message.strippedReply ?? message.text).trim().toLowerCase() === TODO_EMAIL_SUMMARY_REQUEST;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Answers "summary" with the todo's generated summary PDF attached (#1856). The handler names the file; the engine
|
|
102
|
+
* checks it with the handler's own read (the file belongs to the organization, is servable, and the todo still holds
|
|
103
|
+
* it) before the reply is queued. A todo with no summary yet gets the same template, saying so.
|
|
104
|
+
*/
|
|
105
|
+
async function replyWithSummary(ctx: InboundChannelHandlerContext<InboundReplyMode.THREAD>, todoId: string): Promise<void> {
|
|
106
|
+
const todo = await ctx.resources.read<Todos>(TasksManager_ResourceType.TODOS, todoId);
|
|
107
|
+
if (!todo) throw Object.assign(new Error('The todo this thread is about no longer exists'), { name: 'TodoNotFound' });
|
|
108
|
+
// A `z_file` value is typed as either shape (one file, or `fileIds` for a multi-file field); this field holds one.
|
|
109
|
+
const summary = todo.generatedSummaryPdf;
|
|
110
|
+
const summaryFileId = summary && 'fileId' in summary ? summary.fileId : undefined;
|
|
111
|
+
await ctx.reply({
|
|
112
|
+
templateRef: TODO_EMAIL_SUMMARY_TEMPLATE_REF,
|
|
113
|
+
variables: { todoTitle: todo.title, hasSummary: Boolean(summaryFileId) },
|
|
114
|
+
...(summaryFileId ? { attachmentFileIds: [summaryFileId] } : {}),
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
|
|
89
118
|
/**
|
|
90
|
-
* What both answering handlers do: a message on a thread already linked to a todo is a follow-up
|
|
119
|
+
* What both answering handlers do: a message on a thread already linked to a todo is a follow-up (or, when it
|
|
120
|
+
* reads only "summary", a request for the todo's summary PDF); any other
|
|
91
121
|
* becomes a new todo, the thread is linked to it, and the sender is answered.
|
|
92
122
|
*/
|
|
93
123
|
async function intake(
|
|
@@ -96,7 +126,8 @@ async function intake(
|
|
|
96
126
|
): Promise<void> {
|
|
97
127
|
const linked = message.thread.linkedResource;
|
|
98
128
|
if (linked?.resourceType === TasksManager_ResourceType.TODOS) {
|
|
99
|
-
await
|
|
129
|
+
if (asksForSummary(message)) await replyWithSummary(ctx, linked.resourceId);
|
|
130
|
+
else await addFollowUpOnce(ctx, linked.resourceId, message);
|
|
100
131
|
return;
|
|
101
132
|
}
|
|
102
133
|
const list = await resolveTargetList(ctx, message.payload.routeTag);
|
|
@@ -12,7 +12,13 @@
|
|
|
12
12
|
foreignKeyField: 'todoId',
|
|
13
13
|
// Static discriminator: only applies when parent todo is RECURRING
|
|
14
14
|
discriminator: { discriminatorField: todosRecurringTypeField, values: [Todos_RecurrenceType.RECURRING] },
|
|
15
|
-
|
|
15
|
+
// LAZY: a recurring todo gains an occurrence every time it comes due, so a daily todo's set only grows, and deleting
|
|
16
|
+
// it should not delete years of rows inside the request. The delete enqueues the teardown; the child-teardown job
|
|
17
|
+
// removes the occurrences once the delete has committed, and re-checks later if it runs first (#2586). Until then
|
|
18
|
+
// an occurrence may outlive its todo briefly. It is the application's one
|
|
19
|
+
// LAZY edge, so the boot report lists it under [dependent-lifecycle-deferred]. No subject erasure reaches it: no
|
|
20
|
+
// user edge composes a todo or a todo list, and a tenant purge RETAINS todos (the ORGANIZATIONS edge above).
|
|
21
|
+
childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.LAZY, maxDepth: 1 } } },
|
|
16
22
|
// Only applies to RECURRING todos (Edge Case #2 handled in backend). LIST context is open so the
|
|
17
23
|
// todo page can list a recurring todo's occurrences (#1787); occurrences declare no SEARCH.
|
|
18
24
|
contextPolicy: {
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
* read from the row. ACCEPT and DECLINE arriving at the same moment on one SENT quote both pass the
|
|
38
38
|
* condition, but only the first write finds the quote still SENT. The second matches no row and is
|
|
39
39
|
* refused with 409 `version_conflict` (re-read the quote and decide again). One after the other, the second is
|
|
40
|
-
* refused by the condition itself (
|
|
40
|
+
* refused by the condition itself (409 `service_resource_operation_disabled`: it read only the row). Nothing is declared for
|
|
41
41
|
* this: the condition is the declaration.
|
|
42
42
|
*/
|
|
43
43
|
export enum Quote_Status {
|
|
@@ -22,7 +22,7 @@ const CHANGE_STATUS_ACTION = {
|
|
|
22
22
|
surface: ResourceOperationFrontendSurface.EMBEDDED,
|
|
23
23
|
iconOverride: CircleDot,
|
|
24
24
|
actionPresentation: ResourceOperationActionPresentation.INLINE,
|
|
25
|
-
// Explicit ORDER in the bar. Status is the verb reached for most often on a todo, so it leads;
|
|
25
|
+
// Explicit ORDER in the bar. Status is the verb reached for most often on a todo, so it leads; the move follows (MOVE_TO_LIST, 7).
|
|
26
26
|
// Without this the bar orders by registration, which is an artefact of how the config file was written rather than
|
|
27
27
|
// of how the actions are used — and `actionDisclosure` caps the bar at three, so ordering decides WHICH three survive.
|
|
28
28
|
// Lower comes first, and it must be BELOW 10: that is Edit's default, and every custom operation built on UPDATE
|
|
@@ -189,11 +189,17 @@ const REOPEN_ACTION = {
|
|
|
189
189
|
// foreign key declared to `todoLists`), so "Move to ▾" lists the lists and picking one moves the todo.
|
|
190
190
|
// It is named apart from the route's `todoListId`, the SOURCE list when the todo is opened inside it
|
|
191
191
|
// (see `Todos_MoveToListRequestDto`). It is how a capture leaves the Inbox for its week (#2622).
|
|
192
|
+
//
|
|
193
|
+
// Priority 7, BELOW 10, for CHANGE_STATUS's reason: Edit defaults to 10 and every UPDATE-like custom verb (Make
|
|
194
|
+
// recurring, Unassign…) inherits it, and the detail bar keeps three. At 30 the pick never held a slot: a todo's
|
|
195
|
+
// header read Change status, Edit, Make recurring, and "Move to" sat in the `…` menu, where a DROPDOWN degrades to
|
|
196
|
+
// the overlay form that marks no current list (#3861). Moving is what a todo in the Inbox is opened for, so it
|
|
197
|
+
// takes the slot Make recurring held; it follows the status verbs (5, 6) and leads Edit.
|
|
192
198
|
[Todos_Operations.MOVE_TO_LIST, {
|
|
193
199
|
surface: ResourceOperationFrontendSurface.EMBEDDED,
|
|
194
200
|
iconOverride: FolderInput,
|
|
195
201
|
actionPresentation: ResourceOperationActionPresentation.DROPDOWN,
|
|
196
|
-
displayPriority:
|
|
202
|
+
displayPriority: 7,
|
|
197
203
|
}],
|
|
198
204
|
// These three pair off with ASSIGN and with each other: exactly one of
|
|
199
205
|
// ASSIGN/UNASSIGN applies to a todo, and exactly one of
|
package/dist/knowledge/references/external-connectors.frontend-provider-consent-classification.md
CHANGED
|
@@ -43,6 +43,8 @@ export const PROVIDER_CAPABILITY_FRONTEND_CONSENT_CLASSIFICATION = Object.freeze
|
|
|
43
43
|
SMS: SERVER_ONLY,
|
|
44
44
|
// #2293: a deliverable is sent for signature from the backend; the vendor's signing page is its own, not a browser SDK.
|
|
45
45
|
ELECTRONIC_SIGNATURE: SERVER_ONLY,
|
|
46
|
+
// The frame is the application's own engine component, not a browser module the provider loads.
|
|
47
|
+
EMBEDDED_ELECTRONIC_SIGNATURE: SERVER_ONLY,
|
|
46
48
|
SSO_SAML: SERVER_ONLY,
|
|
47
49
|
LLM_CHAT: SERVER_ONLY,
|
|
48
50
|
LLM_EMBEDDINGS: SERVER_ONLY,
|
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
```typescript
|
|
12
12
|
*
|
|
13
13
|
* WHAT RUNS BESIDE THE BACKEND, and what the application reaches out to (#1495) — its workers, its
|
|
14
|
-
* minions, the providers it binds,
|
|
14
|
+
* minions, the providers it binds, the channels work arrives on (#1630), and the needs no existing
|
|
15
|
+
* provider fills, each with why (#3992): the only door to authoring a new provider.
|
|
15
16
|
*
|
|
16
17
|
* ## Why this family exists
|
|
17
18
|
*
|
|
@@ -84,16 +85,12 @@ export const INTEGRATION_PROVIDER_BINDING_SKILL_REF: Readonly<Record<ProviderBin
|
|
|
84
85
|
*/
|
|
85
86
|
export const INTEGRATION_INBOUND_CHANNEL_SKILL_REF = 'inbound-channels';
|
|
86
87
|
|
|
87
|
-
/** Stable prefixes the trusted runtime stamps; a provider supplies only the slug. */
|
|
88
|
-
export const INTEGRATION_WORKER_REF_PREFIX = 'worker-';
|
|
89
|
-
export const INTEGRATION_MINION_REF_PREFIX = 'minion-';
|
|
90
|
-
|
|
91
88
|
const SlugSchema = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
|
|
92
89
|
const NonEmptyStringSchema = z.string().trim().min(1);
|
|
93
90
|
|
|
94
91
|
/** One worker: an HTTP-only subprocess the backend delegates to. */
|
|
95
92
|
export const IntegrationWorkerPlanSchema = z.strictObject({
|
|
96
|
-
workerRef:
|
|
93
|
+
workerRef: IntegrationWorkerRefSchema,
|
|
97
94
|
runtime: z.enum(BuildPlanWorkerRuntime).systemEnum('BuildPlanWorkerRuntime'),
|
|
98
95
|
/** What the backend delegates to it, and why that cannot happen inside a request. */
|
|
99
96
|
purpose: NonEmptyStringSchema,
|
|
@@ -109,7 +106,7 @@ export type IntegrationWorkerPlan = z.infer<typeof IntegrationWorkerPlanSchema>;
|
|
|
109
106
|
|
|
110
107
|
/** One minion: a cron unit that wakes itself. */
|
|
111
108
|
export const IntegrationMinionPlanSchema = z.strictObject({
|
|
112
|
-
minionRef:
|
|
109
|
+
minionRef: IntegrationMinionRefSchema,
|
|
113
110
|
/** What happens because time passed, and why it is not a request. */
|
|
114
111
|
purpose: NonEmptyStringSchema,
|
|
115
112
|
/** The named behaviours its tick performs. At least one: a minion that does nothing is a schedule with no work. */
|
|
@@ -151,6 +148,63 @@ export const IntegrationProviderBindingPlanSchema = z.strictObject({
|
|
|
151
148
|
});
|
|
152
149
|
export type IntegrationProviderBindingPlan = z.infer<typeof IntegrationProviderBindingPlanSchema>;
|
|
153
150
|
|
|
151
|
+
/**
|
|
152
|
+
* The ref of a planned WORKER or MINION (`worker-<slug>`, `minion-<slug>`): the surface that wires an unprovided need for
|
|
153
|
+
* itself (#3995 item 6). The prefix says which collection it names, so a worker and a minion sharing a slug stay distinct.
|
|
154
|
+
*/
|
|
155
|
+
const IntegrationExecutionSurfaceRefSchema = z.string().regex(
|
|
156
|
+
new RegExp(`^(?:${INTEGRATION_WORKER_REF_PREFIX}|${INTEGRATION_MINION_REF_PREFIX})[a-z0-9]+(?:-[a-z0-9]+)*$`),
|
|
157
|
+
);
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* A need NO provider the framework already has fills (#3992), recorded so that a provider is authored only for a reason
|
|
161
|
+
* someone wrote down. App creation USES the engine's providers and the registry's modules; authoring a new one is the last
|
|
162
|
+
* resort (Paul, 2026-11-16), and only an entry here may become a build task that authors a provider package. A binding may
|
|
163
|
+
* name a provider that does not exist yet only when an entry here names it.
|
|
164
|
+
*
|
|
165
|
+
* ## Who wires it: a provider binding, or the worker or minion named by `wiredByRef` (#3995 item 6)
|
|
166
|
+
*
|
|
167
|
+
* A need reaches the build in one of two ways. Either a {@link IntegrationProviderBindingPlanSchema binding} names its
|
|
168
|
+
* `providerRef` on the runtime owner that needs it (backend, companion, application frontend, website), and that binding's
|
|
169
|
+
* task authors the provider; or {@link wiredByRef} names the planned worker or minion that alone uses it, and THAT
|
|
170
|
+
* surface's task authors the provider and declares it in the surface's own scope
|
|
171
|
+
* (`providers.scopes.workers.<key>` / `providers.scopes.minions.<key>`, which the worker and minion tasks already write).
|
|
172
|
+
*
|
|
173
|
+
* Decided by what the framework already does: a worker's or minion's provider is declared on that surface's own
|
|
174
|
+
* `providers` block and belongs to the task that builds it (see {@link ProviderBindingScope}), so the plan names the
|
|
175
|
+
* surface rather than inventing a scope for it. Rejected: adding `WORKER` and `MINION` members to `ProviderBindingScope`.
|
|
176
|
+
* The scope is a closed set of SINGLE owners, each with one declaration file a landing probe reads and one skill; a
|
|
177
|
+
* worker or minion scope is keyed per surface (`scopes.workers.<key>`), so a bare `WORKER` member would name no file and
|
|
178
|
+
* no surface, and carrying the key would turn every binding into a second worker-or-minion reference beside the one
|
|
179
|
+
* this field already is. It would also give a minion's provider a task of its own, apart from the minion that holds its
|
|
180
|
+
* whitelist and its schedule, which the scope's own contract forbids.
|
|
181
|
+
*/
|
|
182
|
+
export const IntegrationUnprovidedNeedSchema = z.strictObject({
|
|
183
|
+
/**
|
|
184
|
+
* The ref the provider to author will have: what the binding that wires it names as its `providerRef`. The entry's
|
|
185
|
+
* business key, on its OWN schema instance: the workbench takes an entry's own key out of its reading, and a key sharing
|
|
186
|
+
* an instance with another aspect's headline (a binding is headed by its `providerRef`) would either stay printed or
|
|
187
|
+
* blank that headline.
|
|
188
|
+
*/
|
|
189
|
+
providerRef: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
|
|
190
|
+
/** What the application needs from outside, in its own words — "send invoices through the client's Fortnox ledger". */
|
|
191
|
+
need: NonEmptyStringSchema,
|
|
192
|
+
/**
|
|
193
|
+
* Why no engine provider and no registry module fills it: a vendor none of them offers, a behaviour they lack, or a
|
|
194
|
+
* business obligation that names a vendor. Checked against the lists the planner was shown; "it seemed simpler" is not one.
|
|
195
|
+
*/
|
|
196
|
+
whyNoExistingProvider: NonEmptyStringSchema,
|
|
197
|
+
/**
|
|
198
|
+
* The planned worker or minion that wires this provider for itself (`worker-<slug>`, `minion-<slug>`), when no other
|
|
199
|
+
* runtime owner uses it. Its build task then authors the provider and declares it in that surface's own scope. Absent
|
|
200
|
+
* when a provider binding wires it; both may be present when the surface and a runtime owner both use it.
|
|
201
|
+
*/
|
|
202
|
+
wiredByRef: IntegrationExecutionSurfaceRefSchema.optional(),
|
|
203
|
+
/** The requirements it is accountable to. */
|
|
204
|
+
servesRefs: z.array(NonEmptyStringSchema).default([]),
|
|
205
|
+
});
|
|
206
|
+
export type IntegrationUnprovidedNeed = z.infer<typeof IntegrationUnprovidedNeedSchema>;
|
|
207
|
+
|
|
154
208
|
/**
|
|
155
209
|
* One channel work ARRIVES on (#1630, #3394): the application declares that messages on this channel are
|
|
156
210
|
* work it acts on, which is what makes the foundation enable the channel's engine capability
|
|
@@ -172,7 +226,9 @@ export type IntegrationInboundChannelPlan = z.infer<typeof IntegrationInboundCha
|
|
|
172
226
|
* THE integration-plan payload.
|
|
173
227
|
*
|
|
174
228
|
* **Artifact-family id: `integration-plan`.** Produced by `bottom_up.integration-plan`, consumed by
|
|
175
|
-
* `bottom_up.build-decompose`, which emits one task per worker, minion, provider binding and inbound channel.
|
|
229
|
+
* `bottom_up.build-decompose`, which emits one task per worker, minion, provider binding and inbound channel. A binding
|
|
230
|
+
* whose provider is an {@link IntegrationUnprovidedNeedSchema unprovided need}, or the worker or minion such a need names
|
|
231
|
+
* as `wiredByRef`, is the one task that AUTHORS the provider; every other binding wires a provider that exists.
|
|
176
232
|
*
|
|
177
233
|
* Every collection may be EMPTY and the whole plan is still meaningful: most applications need no
|
|
178
234
|
* worker and no minion, and saying so is an answer. There is no `min(1)` anywhere here, and that is
|
|
@@ -189,7 +245,16 @@ export const IntegrationPlanSchema = z.object({
|
|
|
189
245
|
providerBindings: z.array(IntegrationProviderBindingPlanSchema).default([]),
|
|
190
246
|
/** Channels work arrives on. Empty for an application no message ever reaches, which is most of them. */
|
|
191
247
|
inboundChannels: z.array(IntegrationInboundChannelPlanSchema).default([]),
|
|
248
|
+
/** Needs no existing provider fills, each with why (#3992). Empty for nearly every application, and that is the point. */
|
|
249
|
+
unprovidedNeeds: z.array(IntegrationUnprovidedNeedSchema).default([]),
|
|
192
250
|
}).superRefine((plan, context) => {
|
|
251
|
+
const unprovided = new Set<string>();
|
|
252
|
+
plan.unprovidedNeeds.forEach((need, index) => {
|
|
253
|
+
if (unprovided.has(need.providerRef)) {
|
|
254
|
+
context.addIssue({ code: 'custom', message: `the unprovided need ${need.providerRef} is recorded twice; one entry says why it is authored`, path: ['unprovidedNeeds', index, 'providerRef'] });
|
|
255
|
+
}
|
|
256
|
+
unprovided.add(need.providerRef);
|
|
257
|
+
});
|
|
193
258
|
const workerRefs = new Set<string>();
|
|
194
259
|
plan.workers.forEach((worker, index) => {
|
|
195
260
|
if (workerRefs.has(worker.workerRef)) {
|
|
@@ -204,6 +269,11 @@ export const IntegrationPlanSchema = z.object({
|
|
|
204
269
|
}
|
|
205
270
|
minionRefs.add(minion.minionRef);
|
|
206
271
|
});
|
|
272
|
+
// A need wired by a surface the plan does not run would be authored for nothing (#3995 item 6).
|
|
273
|
+
plan.unprovidedNeeds.forEach((need, index) => {
|
|
274
|
+
if (need.wiredByRef === undefined || workerRefs.has(need.wiredByRef) || minionRefs.has(need.wiredByRef)) return;
|
|
275
|
+
context.addIssue({ code: 'custom', message: `the unprovided need ${need.providerRef} is wired by ${need.wiredByRef}, which this plan neither runs as a worker nor as a minion`, path: ['unprovidedNeeds', index, 'wiredByRef'] });
|
|
276
|
+
});
|
|
207
277
|
/*
|
|
208
278
|
* One provider bound TWICE on one scope is one declaration written twice — the config carries a
|
|
209
279
|
* single entry per ref per scope, so the second is either a duplicate or a disagreement, and
|
|
@@ -152,18 +152,27 @@ export function resolveDefaultLocalDataStorage(locationType: WildoLocationType):
|
|
|
152
152
|
* Both lanes render a profile: the Docker Compose generator, and the Kubernetes manifests (workloads, the mongod
|
|
153
153
|
* routing parameters, secrets, persistent volumes and readiness) since #2303's second slice.
|
|
154
154
|
*
|
|
155
|
-
* ##
|
|
155
|
+
* ## The queue
|
|
156
156
|
*
|
|
157
|
-
*
|
|
158
|
-
*
|
|
159
|
-
*
|
|
157
|
+
* `SMALL`'s background work runs on the application's own database (`QueueAdapterType.DATABASE`, selected by
|
|
158
|
+
* `queueAdapterTypeOfEnvironmentServiceProfile`), and the platform scheduler delivers its occurrences to the backend over
|
|
159
|
+
* HTTP rather than onto a broker. A minion is confined to its own queues there by a PostgreSQL row-level security policy;
|
|
160
|
+
* MongoDB has none, so a MongoDB application's minions are refused under `SMALL` (`describeMinionsRefusedByEnvironmentServiceProfile`).
|
|
161
|
+
*
|
|
162
|
+
* ## No broker
|
|
163
|
+
*
|
|
164
|
+
* Since #2303 slice D a `SMALL` environment runs no RabbitMQ at all (`environmentServiceProfileRunsMessageBroker`): neither
|
|
165
|
+
* lane renders it, no env file carries `RABBITMQ_*`, no runtime joins its network segment, and apps-manager (told through
|
|
166
|
+
* `PLATFORM_ENVIRONMENT_SERVICE_PROFILE`) initializes no admin client and mints, revokes or restores no vhost or credential.
|
|
167
|
+
* A `backingServices.rabbitmq` declaration beside it is refused.
|
|
160
168
|
*/
|
|
161
169
|
export enum EnvironmentServiceProfile {
|
|
162
170
|
/** Every service the environment's declarations ask for. The default when nothing is authored. */
|
|
163
171
|
FULL = 'full',
|
|
164
172
|
/**
|
|
165
173
|
* The footprint for a small deployment: no ClamAV, no immudb, no mongot
|
|
166
|
-
* ({@link servicesOmittedByEnvironmentServiceProfile})
|
|
174
|
+
* ({@link servicesOmittedByEnvironmentServiceProfile}), one database family, and background work on the application's
|
|
175
|
+
* own database instead of RabbitMQ, which it does not run (minions only on PostgreSQL). Vector search remains available on PostgreSQL
|
|
167
176
|
* (pgvector is part of the PostgreSQL image, not a separate service).
|
|
168
177
|
*/
|
|
169
178
|
SMALL = 'small',
|
|
@@ -219,6 +228,76 @@ export function environmentServiceProfileRunsOneDatabaseFamily(profile: Environm
|
|
|
219
228
|
}
|
|
220
229
|
}
|
|
221
230
|
|
|
231
|
+
/**
|
|
232
|
+
* The queue an environment's application processes share (#2303), as its profile decides it. Total over
|
|
233
|
+
* {@link EnvironmentServiceProfile}: a member added tomorrow fails the build until somebody decides.
|
|
234
|
+
*
|
|
235
|
+
* `FULL` runs RabbitMQ; `SMALL` exists to run without a broker, so its processes share the DATABASE queue, kept in
|
|
236
|
+
* the application's own database (`QueueAdapterType.DATABASE`). Read by the application's container when it binds its
|
|
237
|
+
* queue adapter, so the backend and its minions (which receive the same profile) always choose the same queue.
|
|
238
|
+
*
|
|
239
|
+
* Derived rather than authored: a separate `queueTransport` field beside `serviceProfile` was considered and rejected.
|
|
240
|
+
* `FULL` with the database queue would run a broker nothing uses, and `SMALL` with RabbitMQ would defeat the profile's
|
|
241
|
+
* purpose; neither has a use, and a second field would let them be declared.
|
|
242
|
+
*/
|
|
243
|
+
export function queueAdapterTypeOfEnvironmentServiceProfile(profile: EnvironmentServiceProfile): QueueAdapterType {
|
|
244
|
+
switch (profile) {
|
|
245
|
+
case EnvironmentServiceProfile.FULL:
|
|
246
|
+
return QueueAdapterType.RABBITMQ;
|
|
247
|
+
case EnvironmentServiceProfile.SMALL:
|
|
248
|
+
return QueueAdapterType.DATABASE;
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* Whether an environment under `profile` runs a message broker at all (#2303 slice D). Derived from
|
|
254
|
+
* {@link queueAdapterTypeOfEnvironmentServiceProfile}, never authored: the broker exists to carry the RabbitMQ queue, and
|
|
255
|
+
* under the DATABASE queue nothing in the environment uses one (the platform scheduler delivers over HTTP). Absent profile
|
|
256
|
+
* ⇒ {@link DEFAULT_ENVIRONMENT_SERVICE_PROFILE}.
|
|
257
|
+
*
|
|
258
|
+
* The ONE answer every broker decision reads: whether a deployment lane renders RabbitMQ, whether an env file carries
|
|
259
|
+
* `RABBITMQ_*`, whether apps-manager initializes its RabbitMQ admin client and mints a vhost and credentials, and whether
|
|
260
|
+
* a `backingServices.rabbitmq` declaration contradicts the profile. Total over the queue vocabulary through the switch
|
|
261
|
+
* below, so a third queue adapter must decide here whether it needs a broker.
|
|
262
|
+
*/
|
|
263
|
+
export function environmentServiceProfileRunsMessageBroker(profile: EnvironmentServiceProfile | undefined): boolean {
|
|
264
|
+
switch (queueAdapterTypeOfEnvironmentServiceProfile(profile ?? DEFAULT_ENVIRONMENT_SERVICE_PROFILE)) {
|
|
265
|
+
case QueueAdapterType.RABBITMQ:
|
|
266
|
+
return true;
|
|
267
|
+
case QueueAdapterType.DATABASE:
|
|
268
|
+
case QueueAdapterType.MEMORY:
|
|
269
|
+
return false;
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* Why an application that declares minions cannot run under `profile` on `applicationDatabaseEngine`, or undefined when it
|
|
275
|
+
* can (#2303).
|
|
276
|
+
*
|
|
277
|
+
* Under the DATABASE queue a minion takes its ticks from the application's shared queue table, where a plain table grant
|
|
278
|
+
* would let it read and delete every queued job of its application; its RabbitMQ credential is confined to its own
|
|
279
|
+
* queues. On PostgreSQL the same confinement is a row-level security policy (`deriveMinionDatabaseQueueConfinement`,
|
|
280
|
+
* applied through the owed-grants contract), so minions run. MongoDB has no row-level security, so a MongoDB
|
|
281
|
+
* application's minions are refused under that queue, at render and at boot, with the remedy named. Both refusals read
|
|
282
|
+
* this one function.
|
|
283
|
+
*/
|
|
284
|
+
export function describeMinionsRefusedByEnvironmentServiceProfile(
|
|
285
|
+
profile: EnvironmentServiceProfile,
|
|
286
|
+
applicationDatabaseEngine: DatabaseEngine,
|
|
287
|
+
): string | undefined {
|
|
288
|
+
if (queueAdapterTypeOfEnvironmentServiceProfile(profile) !== QueueAdapterType.DATABASE) return undefined;
|
|
289
|
+
switch (applicationDatabaseEngine) {
|
|
290
|
+
case DatabaseEngine.POSTGRESQL:
|
|
291
|
+
return undefined;
|
|
292
|
+
case DatabaseEngine.MONGODB:
|
|
293
|
+
return `This environment runs the '${profile}' service profile (\`serviceProfile\` in wildo.infra.<env>.config.ts), whose `
|
|
294
|
+
+ 'background work runs on the application\'s own database instead of RabbitMQ, and the application persists to '
|
|
295
|
+
+ 'MongoDB, which cannot confine a minion to its own queues there (only PostgreSQL row-level security can). Remove the '
|
|
296
|
+
+ `minions from wildo.saas.config.ts, set applicationDatabase.engine to '${DatabaseEngine.POSTGRESQL}', or set `
|
|
297
|
+
+ `serviceProfile to '${EnvironmentServiceProfile.FULL}'.`;
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
|
|
222
301
|
/** Whether `profile` omits `service`. Absent profile ⇒ {@link DEFAULT_ENVIRONMENT_SERVICE_PROFILE}. */
|
|
223
302
|
export function environmentServiceProfileOmits(
|
|
224
303
|
profile: EnvironmentServiceProfile | undefined,
|
|
@@ -33,11 +33,22 @@
|
|
|
33
33
|
* provider call, or on an audit row that has to exist before the operation answers), so the write stays best effort,
|
|
34
34
|
* reported under its own reason rather than as unreviewed. Say why at the declaration.
|
|
35
35
|
*
|
|
36
|
-
*
|
|
36
|
+
* DELEGATES_WRITES_TO_AUDITED_OPERATIONS records a third review (#2297): the hooks write nothing themselves. They select a
|
|
37
|
+
* population that nothing bounds (a purge of a whole scope, of every row past a cutoff) and remove it in pages of at most
|
|
38
|
+
* 100 rows, each through a declared operation of the resource (its hook-less internal `DELETE_MANY`), which the framework
|
|
39
|
+
* runs in its own transaction with its own audit row. So every row the operation removes is recorded through a crash, and
|
|
40
|
+
* the answer stays "everything was purged". The operation runs outside any framework transaction (inside one, the
|
|
41
|
+
* delegated writes would join it, unbounded), and its own row is a summary of those writes, written after them, best
|
|
42
|
+
* effort. Accepted only on a REPLACE handler without `transactionalCore`, and honoured only on a multi-row verb
|
|
43
|
+
* (`DELETE_MANY`, `UPDATE_MANY`, or a custom operation borrowing one); elsewhere the write is reported as unreviewed. The
|
|
44
|
+
* engine's purges walk their pages with an engine-internal helper that applications do not receive.
|
|
45
|
+
*
|
|
46
|
+
* A registration with `transactionalCore: true` already runs its hooks in a transaction and needs none of these. Refused beside an
|
|
37
47
|
* `overrideAll` handler, which replaces the pipeline whose transaction this is about.
|
|
38
48
|
*/
|
|
39
49
|
export enum ResourceCustomServiceImplementationHookTransactionPosture {
|
|
40
50
|
RUNS_INSIDE_TRANSACTION = 'runs_inside_transaction',
|
|
41
51
|
STAYS_OUTSIDE_TRANSACTION = 'stays_outside_transaction',
|
|
52
|
+
DELEGATES_WRITES_TO_AUDITED_OPERATIONS = 'delegates_writes_to_audited_operations',
|
|
42
53
|
}
|
|
43
54
|
```
|
|
@@ -27,6 +27,19 @@ export interface BackendDomainModule extends SharedDomainModule {
|
|
|
27
27
|
* `capabilities.tools.functionRefs`.
|
|
28
28
|
*/
|
|
29
29
|
functionTools?: FunctionTool[];
|
|
30
|
+
/**
|
|
31
|
+
* Another party's MCP servers this module's agents may call (#3958): each one's endpoint and the stored provider
|
|
32
|
+
* connection whose credential reaches it. Reference them from an agent's `capabilities.tools.mcpRefs`. Registration
|
|
33
|
+
* refuses a plaintext `http://` endpoint, and every call goes through the outbound guard. See `FlowsActors_McpServer`.
|
|
34
|
+
*/
|
|
35
|
+
mcpServers?: FlowsActors_McpServer[];
|
|
36
|
+
/**
|
|
37
|
+
* Another party's A2A agents this module's agents may delegate a task to (#3930): each one's card URL and the stored
|
|
38
|
+
* provider connection whose credential reaches it. Reference them from an agent's
|
|
39
|
+
* `capabilities.tools.remoteAgentRefs`. Registration refuses a plaintext `http://` card or endpoint, and every call
|
|
40
|
+
* goes through the outbound guard. See `FlowsActors_RemoteAgent`.
|
|
41
|
+
*/
|
|
42
|
+
remoteAgents?: FlowsActors_RemoteAgent[];
|
|
30
43
|
/**
|
|
31
44
|
* Agents that may run with nobody on a socket — on a schedule or on an inbound delivery (#1611).
|
|
32
45
|
* Declaring one grants nothing: a turn runs in an organization only while one of its OAuth clients
|
|
@@ -435,6 +448,8 @@ function mergeFlowsActors(
|
|
|
435
448
|
) as FlowActorSystem_InitializationFactoryMap,
|
|
436
449
|
agents: modules.flatMap(m => m.flowsActors?.agents ?? []),
|
|
437
450
|
functionTools: modules.flatMap(m => m.flowsActors?.functionTools ?? []),
|
|
451
|
+
mcpServers: modules.flatMap(m => m.flowsActors?.mcpServers ?? []),
|
|
452
|
+
remoteAgents: modules.flatMap(m => m.flowsActors?.remoteAgents ?? []),
|
|
438
453
|
autonomousAgents: modules.flatMap(m => m.flowsActors?.autonomousAgents ?? []),
|
|
439
454
|
chatAgents: modules.flatMap(m => m.flowsActors?.chatAgents ?? []),
|
|
440
455
|
actorExecutionContinuations: modules.flatMap(m => m.flowsActors?.actorExecutionContinuations ?? []),
|
|
@@ -33,23 +33,49 @@ export interface A2A_Skill {
|
|
|
33
33
|
* agent's canonical audience: BOTH a USER-delegated and a MACHINE (client-credentials)
|
|
34
34
|
* inbound token MUST carry it as `aud` (RFC 8707 / external-access D7) — a token minted for
|
|
35
35
|
* another surface (including the generic API audience, per the 2026-07-29 flip) is rejected.
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
* machine → the conversation is owned by the org/app).
|
|
40
|
-
* app's own OIDC provider (`/oauth/authorize`, `/oauth/token`).
|
|
36
|
+
* The card advertises BOTH D6 principals as TWO security schemes, one flow each:
|
|
37
|
+
* {@link A2A_DELEGATED_SECURITY_SCHEME} (`authorizationCode`, user-delegated → the conversation is
|
|
38
|
+
* owned by the delegating user) and {@link A2A_MACHINE_SECURITY_SCHEME} (`clientCredentials`, org/app
|
|
39
|
+
* machine → the conversation is owned by the org/app). Either satisfies the requirement. Tokens are
|
|
40
|
+
* minted by the app's own OIDC provider (`/oauth/authorize`, `/oauth/token`).
|
|
41
41
|
*/
|
|
42
42
|
/**
|
|
43
|
-
*
|
|
43
|
+
* The security scheme a USER-delegated client reads: the `authorizationCode` flow. Kept as `oauth2`, the name the card
|
|
44
|
+
* has always used for it.
|
|
44
45
|
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
46
|
+
* One flow per scheme because A2A 1.0 makes it so: spec-cite: A2A v1.0.0 specification/a2a.proto, `message OAuthFlows {
|
|
47
|
+
* oneof flow { AuthorizationCodeOAuthFlow authorization_code = 1; ClientCredentialsOAuthFlow client_credentials = 2; … } }`.
|
|
48
|
+
* Both flows in one scheme made the A2A reference SDK refuse the whole card (#3932).
|
|
49
|
+
*/
|
|
50
|
+
export const A2A_DELEGATED_SECURITY_SCHEME = 'oauth2';
|
|
51
|
+
/** The security scheme a MACHINE client reads: the `clientCredentials` flow. See {@link A2A_DELEGATED_SECURITY_SCHEME}. */
|
|
52
|
+
export const A2A_MACHINE_SECURITY_SCHEME = 'oauth2ClientCredentials';
|
|
53
|
+
/**
|
|
54
|
+
* One protocol interface this agent exposes: a URL, the protocol binding spoken there, and the protocol version.
|
|
55
|
+
*
|
|
56
|
+
* spec-cite: A2A v1.0.0 specification/a2a.proto, `message AgentInterface { string url = 1 [REQUIRED]; string
|
|
57
|
+
* protocol_binding = 2 [REQUIRED]; string tenant = 3; string protocol_version = 4 [REQUIRED]; }`, serialized camelCase
|
|
58
|
+
* (§5.5). `protocol_binding` is "an open form string … The core ones officially supported are `JSONRPC`, `GRPC` and
|
|
59
|
+
* `HTTP+JSON`."
|
|
60
|
+
*
|
|
61
|
+
* These were named `transport` and `version` until 2026-11-16, names `AgentInterface` does not have, so a 1.0 client
|
|
62
|
+
* parsing the card read every interface with no binding and no version (#3932).
|
|
48
63
|
*/
|
|
49
64
|
export interface A2A_AgentInterface {
|
|
50
65
|
url: string;
|
|
51
|
-
|
|
52
|
-
|
|
66
|
+
protocolBinding: string;
|
|
67
|
+
protocolVersion: string;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* One 1.0 security requirement: the schemes it needs, each with the scopes required. The card lists alternatives, so a
|
|
72
|
+
* client satisfies any one entry.
|
|
73
|
+
*
|
|
74
|
+
* spec-cite: A2A v1.0.0 specification/a2a.proto, `message SecurityRequirement { map<string, StringList> schemes = 1; }`
|
|
75
|
+
* and `message StringList { repeated string list = 1; }`.
|
|
76
|
+
*/
|
|
77
|
+
export interface A2A_SecurityRequirement {
|
|
78
|
+
schemes: Record<string, { list: string[] }>;
|
|
53
79
|
}
|
|
54
80
|
|
|
55
81
|
export interface A2A_AgentCard {
|
|
@@ -84,6 +110,12 @@ export interface A2A_AgentCard {
|
|
|
84
110
|
defaultOutputModes: string[];
|
|
85
111
|
skills: A2A_Skill[];
|
|
86
112
|
securitySchemes: Record<string, unknown>;
|
|
113
|
+
/** The v0.2.5 requirement list (scheme name → scopes), one entry per alternative. Kept for v0.2.5 clients. */
|
|
87
114
|
security: Record<string, string[]>[];
|
|
115
|
+
/**
|
|
116
|
+
* The same alternatives in the 1.0 shape. spec-cite: A2A v1.0.0 specification/a2a.proto, `AgentCard` —
|
|
117
|
+
* `repeated SecurityRequirement security_requirements = 9`.
|
|
118
|
+
*/
|
|
119
|
+
securityRequirements: A2A_SecurityRequirement[];
|
|
88
120
|
}
|
|
89
121
|
```
|
|
@@ -23,11 +23,11 @@
|
|
|
23
23
|
* - the turn reached an interrupted state (a human-in-the-loop approval pause).
|
|
24
24
|
*
|
|
25
25
|
* All three triggers are live. The interrupted-state arm needs a runtime that can pause a turn; that
|
|
26
|
-
* is the human-in-the-loop approval gate, and a paused turn
|
|
27
|
-
* `
|
|
28
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
26
|
+
* is the human-in-the-loop approval gate, and a paused turn materialises a task carrying
|
|
27
|
+
* `auth-required` on all three transports (blocking send, non-blocking send, stream), with a status
|
|
28
|
+
* message saying a person decides in the application. The task moves on by itself once they have:
|
|
29
|
+
* poll it, subscribe to it, or register a webhook. A message on the task does not answer the
|
|
30
|
+
* approval, and `tasks/cancel` withdraws it.
|
|
31
31
|
*
|
|
32
32
|
* A blocking turn that answers in one shot, with no webhook, returns an A2A `Message` and writes no task
|
|
33
33
|
* row at all. Both shapes are protocol-conformant: the specification types the
|
|
@@ -91,7 +91,7 @@ export interface A2A_TaskSurfaceContract {
|
|
|
91
91
|
* projection from `FlowsActors_Status` reads it, the transport emits it, and tests
|
|
92
92
|
* pin it.
|
|
93
93
|
*
|
|
94
|
-
* Not every member is emitted by this transport today — `
|
|
94
|
+
* Not every member is emitted by this transport today — `INPUT_REQUIRED` and
|
|
95
95
|
* `REJECTED` have no `FlowsActors_Status` counterpart and are never produced. They
|
|
96
96
|
* are declared because the vocabulary belongs to the protocol, not to us: a client
|
|
97
97
|
* may legitimately receive them from another A2A server, and omitting them would
|
|
@@ -103,13 +103,19 @@ export enum A2A_TaskState {
|
|
|
103
103
|
/** Actively being processed. */
|
|
104
104
|
WORKING = 'working',
|
|
105
105
|
/**
|
|
106
|
-
* Interrupted (non-terminal): the agent needs input
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
* principals are denied rather than parked because no named person can answer for them.
|
|
106
|
+
* Interrupted (non-terminal): the agent needs more input from the client, which a follow-up message
|
|
107
|
+
* on the task gives. NOT emitted by this transport: a turn that answers needs no task, and an
|
|
108
|
+
* approval pause is {@link AUTH_REQUIRED}, because a message does not answer it.
|
|
110
109
|
*/
|
|
111
110
|
INPUT_REQUIRED = 'input-required',
|
|
112
|
-
/**
|
|
111
|
+
/**
|
|
112
|
+
* Interrupted (non-terminal): an authorization the task waits on, given outside the protocol.
|
|
113
|
+
* Emitted when a user-delegated turn reaches an approval-gated tool: the signed pending decision is
|
|
114
|
+
* persisted, an addressable task is materialised, and its status message says a person decides in
|
|
115
|
+
* the application. Their approval or refusal resumes that same execution, and the task moves on
|
|
116
|
+
* without the client sending anything. Machine principals are denied rather than parked, because
|
|
117
|
+
* no named person can answer for them.
|
|
118
|
+
*/
|
|
113
119
|
AUTH_REQUIRED = 'auth-required',
|
|
114
120
|
/** Terminal: finished successfully. */
|
|
115
121
|
COMPLETED = 'completed',
|
|
@@ -972,10 +972,17 @@ export function functionToolDeliverableDeclarationProblems(
|
|
|
972
972
|
* #2914), one sentence per problem with its remedy; empty when they are sound or absent. `declaredFieldsOf` answers the
|
|
973
973
|
* fields the resource's main schema declares, or undefined when the resource is not registered (its fields are then not
|
|
974
974
|
* checked here: a field the row does not hold is shown and sealed as absent).
|
|
975
|
+
*
|
|
976
|
+
* `systemReadAllowedOf` answers whether the resource grants the system READ (`systemAccessPolicy.read`), or undefined when
|
|
977
|
+
* the resource is not registered. The card, the seal and the currency check all read the row through `readAsSystem`, which
|
|
978
|
+
* refuses a resource that does not grant it, and that refusal is swallowed into "no record values": every approval then
|
|
979
|
+
* seals no field and no currency check can compare anything. Measured on Wonder Ledger's live sign-off, where the declared
|
|
980
|
+
* field set was sealed on none of the seals, so a declaration nothing can read stops the application here instead.
|
|
975
981
|
*/
|
|
976
982
|
export function functionToolRecordApprovalDeclarationProblems(
|
|
977
983
|
tool: Pick<FunctionTool, 'functionRef' | 'sealedRecordFields' | 'approvalReplacesEarlierApprovalOfRow' | 'argumentsResource' | 'requiresHumanApproval' | 'humanApproval' | 'asksThePerson'>,
|
|
978
984
|
declaredFieldsOf?: (resourceType: string) => readonly string[] | undefined,
|
|
985
|
+
systemReadAllowedOf?: (resourceType: string) => boolean | undefined,
|
|
979
986
|
): string[] {
|
|
980
987
|
const fields = tool.sealedRecordFields;
|
|
981
988
|
const replaces = tool.approvalReplacesEarlierApprovalOfRow === true;
|
|
@@ -999,6 +1006,10 @@ export function functionToolRecordApprovalDeclarationProblems(
|
|
|
999
1006
|
const unknown = declared ? fields.filter((field) => !declared.includes(field)) : [];
|
|
1000
1007
|
if (unknown.length > 0) problems.push(`${named}, naming ${unknown.join(', ')}, which ${tool.argumentsResource!.resourceType} does not declare.`);
|
|
1001
1008
|
}
|
|
1009
|
+
if (tool.argumentsResource && systemReadAllowedOf?.(tool.argumentsResource.resourceType) === false) {
|
|
1010
|
+
problems.push(`${named}, but ${tool.argumentsResource.resourceType} does not grant the system read the approval card, the seal and the currency check `
|
|
1011
|
+
+ `read the row through: declare systemAccessPolicy.read = ResourceSystemAccessMode.ALLOWED on it.`);
|
|
1012
|
+
}
|
|
1002
1013
|
}
|
|
1003
1014
|
return problems;
|
|
1004
1015
|
}
|