@wildo-ai/framework-knowledge 1.1.14 → 1.1.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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/creation-state.md +4 -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 +13 -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.build/playbook.definition.d.ts.map +1 -1
- package/dist/esm/playbooks/bottom_up.build/playbook.definition.js +6 -4
- package/dist/esm/playbooks/bottom_up.build/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/method.md +10 -8
- package/dist/knowledge/playbooks/bottom_up.build/playbook.json +1 -1
- 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/backend.inbound-handlers.definition.md +2 -1
- package/dist/knowledge/references/build-plan.task-graph.config.md +12 -8
- package/dist/knowledge/references/example.electronic-signature.engagement-letter-tool.md +54 -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 +14 -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.decision-notice-handler.md +7 -0
- package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +16 -0
- package/dist/knowledge/references/saas.backend.flows-actors.present-records-tool.md +5 -2
- package/dist/knowledge/references/saas.frontend.composite-view.authoring.md +19 -0
- package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md +46 -0
- package/dist/knowledge/references/saas.frontend.settings-hub.engine-destinations.md +21 -0
- package/dist/knowledge/references/saas.models.flows-actors.agent-definition.md +24 -33
- package/dist/knowledge/references/saas.models.flows-actors.decision-card-wording.md +9 -0
- 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.flows.run-state.md +9 -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 +55 -1
- package/dist/knowledge/registries/playbooks.json +2 -2
- package/dist/knowledge/registries/source-tags.json +1127 -1042
- package/dist/knowledge/skills/INDEX.md +2 -2
- package/dist/knowledge/skills/application-roles-authoring/SKILL.md +20 -4
- 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-app-shell/SKILL.md +4 -0
- package/dist/knowledge/skills/config-saas/references/framework-auditable-event-catalog.md +3 -0
- package/dist/knowledge/skills/config-saas/references/framework-provider-capabilities-api.md +11 -0
- package/dist/knowledge/skills/electronic-signature-deliverables/SKILL.md +69 -19
- package/dist/knowledge/skills/electronic-signature-deliverables/references/signing-inside-the-application.md +113 -0
- package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +32 -5
- 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 +35 -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 +16 -0
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-view-api.md +30 -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-present-records-tool-api.md +5 -2
- package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-remote-a2a-agent-declaration-api.md +207 -0
- package/dist/knowledge/skills/flows-actors-declared-flow/references/framework-start-flow-api.md +9 -0
- package/dist/knowledge/skills/flows-actors-llm-agent-invocation/references/framework-llm-agent-definition-api.md +24 -33
- package/dist/knowledge/skills/human-decision-notices/SKILL.md +5 -1
- package/dist/knowledge/skills/human-decision-notices/references/framework-decision-card-wording-api.md +9 -0
- package/dist/knowledge/skills/human-decision-notices/references/framework-decision-notice-handler-api.md +7 -0
- package/dist/knowledge/skills/inbound-channels/references/framework-inbound-handler-api.md +2 -1
- 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 +27 -1
- package/dist/knowledge/skills/provider-backend-package/SKILL.md +32 -4
- 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/skills/settings-placement-authoring/references/framework-settings-destinations-catalog.md +21 -0
- package/dist/knowledge/skills/views-composite-authoring/SKILL.md +5 -0
- package/dist/knowledge/skills/views-composite-authoring/references/framework-composite-view-contracts-api.md +19 -0
- package/dist/knowledge/topic-index.json +295 -114
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/package.json +4 -4
|
@@ -1,17 +1,21 @@
|
|
|
1
1
|
# Email template ownership and artifact paths
|
|
2
2
|
|
|
3
|
-
Locate the owning backend module's `emailTemplateDefinitions` contribution first
|
|
3
|
+
Locate the owning backend module's `emailTemplateDefinitions` contribution first, and keep templates where its definitions file scans.
|
|
4
|
+
|
|
5
|
+
**A business module's emails live in `backend-api/src/modules/<module>/emails/`, and nowhere else.** That folder holds the definitions file, `emails/module-email-template-definitions.ts`, which calls `scanEmailTemplateDirectory` over `resources/` (and `system/` when the module has system emails) beside it, and the template folders it scans. The module contributes the resulting map as its `emailTemplateDefinitions`. Do not create `email/`, `mail/`, `templates/` or any other folder for a module's emails, and do not put the definitions file at the module's root: the companion writes a module's generated templates, and its preview imports them, under `emails/`, so a template registered from anywhere else is generated where nothing registers it.
|
|
6
|
+
|
|
7
|
+
This is checked. In the build lane, every coding run that writes under a package's `src/modules/`, and the end-of-build checks, run `check:module-layout`, which refuses a file that calls `scanEmailTemplateDirectory` (or is named like a module email definitions file) outside `<module>/emails/`, and states the correction: the `mv` (renaming the whole folder when the folder is the misplaced unit, `mv <module>/email <module>/emails`) and every import to update. Outside the build lane, `rg -l 'scanEmailTemplateDirectory' backend-api/src/modules` must list only files under an `emails/` folder. If a module you work in registers its emails elsewhere, move them there; do not follow the misplaced layout. Write the scanner's `subdir` as a string literal and `keyFromPath` as a function returning `` `email.${…}` `` (or `` `system.${…}` ``): the companion reads both from the call to know which folder registers which refs, and writes nothing for a module whose scanner it cannot read.
|
|
4
8
|
|
|
5
9
|
| Artifact | Current scanner contract |
|
|
6
10
|
|---|---|
|
|
7
11
|
| Authored template | `template.tsx` with a default `EmailTemplateDefinition<TLabels>` export |
|
|
8
12
|
| Authored labels | Co-located `labels.<locale>.ts` with named `labels` export satisfying `TLabels` |
|
|
9
13
|
| Runtime artifacts | Compiled `template.js` and `labels.<locale>.js` under the owning scanner directory |
|
|
10
|
-
| Definition collection | `scanEmailTemplateDirectory` from `@wildo-ai/saas-backend-lib`,
|
|
14
|
+
| Definition collection | `scanEmailTemplateDirectory` from `@wildo-ai/saas-backend-lib`, called from `<email root>/…-email-template-definitions.ts` (a business module's email root is `emails/`) |
|
|
11
15
|
| Runtime wiring | Existing owning backend module contributes the resulting `emailTemplateDefinitions` map |
|
|
12
16
|
|
|
13
17
|
The scanner starts beside its caller's `import.meta.url`, scans its configured `subdir` recursively and uses `keyFromPath` to derive refs. Its default extension is `.js`. It imports the template's default export and the labels module's named `labels` export (also accepts `default.labels`). It does not infer refs from a new enum or inspect an arbitrary TypeScript source folder.
|
|
14
18
|
|
|
15
|
-
In the current skeleton, `backend-api/src/engine/email/email-template-definitions.ts` scans `system/` and `resources/`. `system/password-reset` becomes `system.password_reset`; under `resources/`, `/` becomes `.`, so an operation email for `tasks` / `assign` / target `USER_SELF` lives in `resources/tasks/assign.user-self` and registers `email.tasks.assign.user-self` (the full rule: `references/framework-operation-email-template-ref-api.md`). The engine backend module contributes the map.
|
|
19
|
+
In the current skeleton, `backend-api/src/engine/email/email-template-definitions.ts` scans `system/` and `resources/`. `system/password-reset` becomes `system.password_reset`; under `resources/`, `/` becomes `.`, so an operation email for `tasks` / `assign` / target `USER_SELF` lives in `resources/tasks/assign.user-self` and registers `email.tasks.assign.user-self` (the full rule: `references/framework-operation-email-template-ref-api.md`). The engine backend module contributes the map. That layout is the ENGINE owner's email root (`backend-api/src/engine/email/`, singular, owned by the skeleton); do not copy its folder name into a business module, whose emails live in `emails/` as stated above, and do not move a business module's emails into the engine.
|
|
16
20
|
|
|
17
|
-
|
|
21
|
+
An explicit map (templates imported one by one, no scanner) cannot be read by the companion, which then generates and previews nothing for that module and says so; replace it with the scanner in `emails/` when you work in such a module. For a scanner, adding a correctly named/default-exported template and named locale exports under its root is the registration input; no per-template manual entry is required. In either case, normal compilation/publication and module loading must make the ref visible. Match the sender's typed identifier to the derived ref and verify through preview. Never hand-edit compiled artifacts to make a missing source registration appear fixed.
|
|
@@ -43,7 +43,7 @@ grep is the high-signal check.
|
|
|
43
43
|
2. You did NOT copy the workflow into this stub or re-author it
|
|
44
44
|
elsewhere — the canonical orchestrator stays the single source of
|
|
45
45
|
truth.
|
|
46
|
-
3. The new template
|
|
46
|
+
3. The new template's folder is under the email root its definitions file scans — a business module's `emails/`, which is the ONLY place a module's email definitions may live (`check:module-layout` refuses any other folder and states the move; see `email-add-template`'s `references/email-artifact-paths.md`), the engine's `backend-api/src/engine/email/` — so `ls backend-api/src/modules/<module>/emails/resources/<template-path>` (or the engine's `system/`/`resources/` equivalent) lists it. Ids are derived from that path, never written into the definitions file.
|
|
47
47
|
4. No sender service imports the template module directly — `rg -n "from\s+['\"].*engine/email/<template>/template['\"]" backend-api/src/modules/<module>/` returns empty.
|
|
48
48
|
|
|
49
49
|
## Red Flags
|
|
@@ -27,7 +27,9 @@ transport — you author almost nothing:
|
|
|
27
27
|
- **Exposure is automatic.** Every ACTOR system with an AGENTIC actor bound to an
|
|
28
28
|
agent is served as one A2A skill (`skill.id === system.ref`). Build the actor
|
|
29
29
|
system exactly as for the in-app assistant (`flows-actors-chat-assistant`); no
|
|
30
|
-
per-system A2A flag.
|
|
30
|
+
per-system A2A flag. Give the system `tags` (the keywords another agent matches a
|
|
31
|
+
skill by): A2A 1.0 requires every skill to carry at least one, and a system with
|
|
32
|
+
none is served with its `category`, else its `ref`, as its only tag.
|
|
31
33
|
- **The engine serves two endpoints**: a public agent card at
|
|
32
34
|
`GET /a2a/.well-known/agent-card.json` (discovery) and the Bearer-authenticated
|
|
33
35
|
JSON-RPC endpoint `POST /a2a` (`message/send` blocking, `message/stream` SSE).
|
|
@@ -64,6 +66,9 @@ scope-isolated variants.
|
|
|
64
66
|
actor system; that skill builds the WebSocket view).
|
|
65
67
|
- **Exposing resource CRUD as callable tools** to external agents → that is **MCP**
|
|
66
68
|
(`operation.mcp.exposed`) — the sibling skill `resource-mcp-tool-exposure`, not A2A.
|
|
69
|
+
- **Your agent calling ANOTHER party's A2A agent** (the outbound direction) → declare it in
|
|
70
|
+
`flowsActors.remoteAgents` and name it in the agent's `remoteAgentRefs`; see
|
|
71
|
+
`flows-actors-chat-assistant`, `references/framework-remote-a2a-agent-declaration-api.md`.
|
|
67
72
|
- **A one-shot generation agent** with no conversation → a plain `FlowsActors_Agent`
|
|
68
73
|
invoked by your own service.
|
|
69
74
|
|
|
@@ -81,8 +86,8 @@ declarations in `shared-lib` themselves.)
|
|
|
81
86
|
External agents get a token from YOUR app's OIDC provider. For **user-delegated**
|
|
82
87
|
callers, the `authorizationCode` flow issues a token whose `aud` is the agent card
|
|
83
88
|
`url`. For **machine** callers, provision an **OAuth client** (org- or app-scoped)
|
|
84
|
-
and use the `clientCredentials` flow.
|
|
85
|
-
|
|
89
|
+
and use the `clientCredentials` flow. The agent card always advertises both, as two
|
|
90
|
+
security schemes (`oauth2` and `oauth2ClientCredentials`) either of which satisfies it.
|
|
86
91
|
|
|
87
92
|
### Step 3: Understand what external agents do (you do not author this)
|
|
88
93
|
1. `GET /a2a/.well-known/agent-card.json` → the card (skills + `securitySchemes`).
|
|
@@ -97,6 +102,12 @@ machine turn persists to `organization`/`applicationFlowActorExecutions` (owned
|
|
|
97
102
|
the org/app). Each is scope-isolated — a caller only ever sees its own scope's
|
|
98
103
|
conversations. Nothing to author; confirm the right variant is written.
|
|
99
104
|
|
|
105
|
+
To let an agent that does NOT run on your machine reach a local stack (the card's `url` is your public
|
|
106
|
+
origin, and an outside client follows it), run `wildo local tunnel up --tunnel <machine-tunnel>
|
|
107
|
+
--hostname <app>-<machine>.<your-domain>`: while it runs, your issuer, audiences and card name that
|
|
108
|
+
HTTPS origin, only the protocol paths are forwarded, and your own browser keeps working on localhost.
|
|
109
|
+
Tokens minted before `up` stop working after it. `wildo local tunnel down` puts everything back.
|
|
110
|
+
|
|
100
111
|
### Step 5 (optional): Split the skills across NAMED agents
|
|
101
112
|
|
|
102
113
|
Skip this when one agent card is enough — it is, for most apps.
|
|
@@ -269,6 +280,9 @@ const todoAssistantChatAgent: FlowsActors_Agent = {
|
|
|
269
280
|
functionRefs: [
|
|
270
281
|
TODOS_READ_TOOL_REF,
|
|
271
282
|
TODO_LISTS_READ_TOOL_REF,
|
|
283
|
+
// A recurring todo's occurrences, by the todo's id: they are listed under their todo, which the generic read
|
|
284
|
+
// tool cannot address. See `./todo-occurrences-tool.ts`.
|
|
285
|
+
TODO_OCCURRENCES_TOOL_REF,
|
|
272
286
|
TODOS_CREATE_TOOL_REF,
|
|
273
287
|
TODOS_UPDATE_TOOL_REF,
|
|
274
288
|
// RETRIEVAL grounding — a different KIND of source from the three above. Those return ROWS
|
|
@@ -328,6 +342,7 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
328
342
|
agents: FlowsActors_Agent[];
|
|
329
343
|
functionTools?: FunctionTool[];
|
|
330
344
|
autonomousAgents?: FlowsActors_AutonomousAgentDeclaration[];
|
|
345
|
+
chatAgents?: FlowsActors_ChatAgentDeclaration[];
|
|
331
346
|
} = {
|
|
332
347
|
flowActorSystemsFactoryMap: {
|
|
333
348
|
[TODO_ASSISTANT_SYSTEM_REF]: () => todoAssistantActorSystem,
|
|
@@ -339,6 +354,11 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
339
354
|
},
|
|
340
355
|
agents: [todoAssistantChatAgent, todoTriageAgent, todoDeadlineDrillAgent, todoAutoResolveAgent],
|
|
341
356
|
autonomousAgents: [todosOverdueTriage, todosDeadlineDrill],
|
|
357
|
+
// Who answers a person who writes to the Teams bot (#2665). The Teams messages handler already converses
|
|
358
|
+
// (`../../inbound/teams-bot.inbound-handler.ts`), and with no chat agent declared every such message was refused.
|
|
359
|
+
// The todo assistant answers, as the linked member who wrote and with that member's authority, in every
|
|
360
|
+
// organization that chose no other agent for the connection (Settings > Chat agents).
|
|
361
|
+
chatAgents: [{ ref: 'todos.assistant', systemRef: TODO_ASSISTANT_SYSTEM_REF, isDefault: true }],
|
|
342
362
|
// Generic engine factories instantiated per resource — every tool runs AS THE
|
|
343
363
|
// CALLER (the engine rebuilds a scoped ExecutionContext from the caller's verified
|
|
344
364
|
// auth; identity is never LLM-supplied) and each op's own ACL is enforced by the
|
|
@@ -430,8 +450,10 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
430
450
|
// The engine's question tool (#2720): gated on the OWNER route by construction, so only the person whose turn it
|
|
431
451
|
// is answers it, in the conversation or from their decision inbox.
|
|
432
452
|
askPersonTool(),
|
|
433
|
-
// The records the assistant may show as cards: the same
|
|
434
|
-
|
|
453
|
+
// The records the assistant may show as cards: the same three it reads. An occurrence has no page, so its card opens
|
|
454
|
+
// it in an overlay over the conversation (#2776).
|
|
455
|
+
presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS, TasksManager_ResourceType.TODOS_RECURRING_OCCURRENCES] }),
|
|
456
|
+
todoOccurrencesTool,
|
|
435
457
|
// The overdue-triage agent's one write, ROLE-gated to administrators (#1611). See `./reschedule-todo-tool.ts`.
|
|
436
458
|
rescheduleTodoTool,
|
|
437
459
|
// The deadline drill's four-minute reviewer-routed delete (#1866). See `./deadline-drill-agent.ts`.
|
|
@@ -470,8 +492,8 @@ beyond the original request; conversation history and task status are separate r
|
|
|
470
492
|
| A send carrying a webhook (`configuration.pushNotificationConfig`; 1.0: `configuration.taskPushNotificationConfig`) | A `Task`; a blocking send waits for the turn and returns it in its latest state | The webhook is registered on that task; a streamed send carrying one is refused |
|
|
471
493
|
| `configuration.blocking: false` (1.0: `configuration.returnImmediately: true`) | A `Task` with its own ID | Work continues independently of the request once the task is opened |
|
|
472
494
|
| Direct `message/stream` completes | Message frames and the final reply | No background task; disconnect during generation aborts the turn |
|
|
473
|
-
| Send or stream pauses for approval | A `Task` in `
|
|
474
|
-
| A message to a conversation still waiting for that decision | JSON-RPC error `-32015` (`DECISION_PENDING`) on every send mode, before any task is created; nothing runs or is written | The
|
|
495
|
+
| Send or stream pauses for approval | A `Task` in `auth-required` with a status message; a stream returns it in its terminal frame | The person decides in the application, never through a message on the task (refused, `UnsupportedOperationError`); the task moves on by itself, and `tasks/cancel` withdraws the request |
|
|
496
|
+
| A message to a conversation still waiting for that decision | JSON-RPC error `-32015` (`DECISION_PENDING`) on every send mode, before any task is created; nothing runs or is written | The authorization the task waits for is the person's answer: wait for it, or `tasks/cancel`, which withdraws the decision. A decision raised in the instant between that check and a non-blocking turn ends the new task `failed` |
|
|
475
497
|
|
|
476
498
|
These are the supported 0.2.5 request/state spellings. Other supported dialects use the corresponding
|
|
477
499
|
projected names. **A request is read in the dialect of its method**: a 1.0 `SendMessage` carries parts
|
|
@@ -8,8 +8,9 @@ Read this when you need to know:
|
|
|
8
8
|
|
|
9
9
|
- exactly what an external agent sees (skills = your agentic actor systems, keyed
|
|
10
10
|
`skill.id === system.ref`);
|
|
11
|
-
- how the card advertises auth
|
|
12
|
-
|
|
11
|
+
- how the card advertises auth: two security schemes with one flow each, `oauth2`
|
|
12
|
+
(`authorizationCode`, user-delegated) and `oauth2ClientCredentials` (`clientCredentials`,
|
|
13
|
+
machine callers), listed as alternatives in `security` and `securityRequirements`;
|
|
13
14
|
- what the card `url` means for audience binding (RFC 8707 / D7).
|
|
14
15
|
|
|
15
16
|
## Import Origins
|
|
@@ -45,23 +46,49 @@ export interface A2A_Skill {
|
|
|
45
46
|
* agent's canonical audience: BOTH a USER-delegated and a MACHINE (client-credentials)
|
|
46
47
|
* inbound token MUST carry it as `aud` (RFC 8707 / external-access D7) — a token minted for
|
|
47
48
|
* another surface (including the generic API audience, per the 2026-07-29 flip) is rejected.
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
51
|
-
* machine → the conversation is owned by the org/app).
|
|
52
|
-
* app's own OIDC provider (`/oauth/authorize`, `/oauth/token`).
|
|
49
|
+
* The card advertises BOTH D6 principals as TWO security schemes, one flow each:
|
|
50
|
+
* {@link A2A_DELEGATED_SECURITY_SCHEME} (`authorizationCode`, user-delegated → the conversation is
|
|
51
|
+
* owned by the delegating user) and {@link A2A_MACHINE_SECURITY_SCHEME} (`clientCredentials`, org/app
|
|
52
|
+
* machine → the conversation is owned by the org/app). Either satisfies the requirement. Tokens are
|
|
53
|
+
* minted by the app's own OIDC provider (`/oauth/authorize`, `/oauth/token`).
|
|
53
54
|
*/
|
|
54
55
|
/**
|
|
55
|
-
*
|
|
56
|
+
* The security scheme a USER-delegated client reads: the `authorizationCode` flow. Kept as `oauth2`, the name the card
|
|
57
|
+
* has always used for it.
|
|
56
58
|
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
-
*
|
|
59
|
+
* One flow per scheme because A2A 1.0 makes it so: spec-cite: A2A v1.0.0 specification/a2a.proto, `message OAuthFlows {
|
|
60
|
+
* oneof flow { AuthorizationCodeOAuthFlow authorization_code = 1; ClientCredentialsOAuthFlow client_credentials = 2; … } }`.
|
|
61
|
+
* Both flows in one scheme made the A2A reference SDK refuse the whole card (#3932).
|
|
62
|
+
*/
|
|
63
|
+
export const A2A_DELEGATED_SECURITY_SCHEME = 'oauth2';
|
|
64
|
+
/** The security scheme a MACHINE client reads: the `clientCredentials` flow. See {@link A2A_DELEGATED_SECURITY_SCHEME}. */
|
|
65
|
+
export const A2A_MACHINE_SECURITY_SCHEME = 'oauth2ClientCredentials';
|
|
66
|
+
/**
|
|
67
|
+
* One protocol interface this agent exposes: a URL, the protocol binding spoken there, and the protocol version.
|
|
68
|
+
*
|
|
69
|
+
* spec-cite: A2A v1.0.0 specification/a2a.proto, `message AgentInterface { string url = 1 [REQUIRED]; string
|
|
70
|
+
* protocol_binding = 2 [REQUIRED]; string tenant = 3; string protocol_version = 4 [REQUIRED]; }`, serialized camelCase
|
|
71
|
+
* (§5.5). `protocol_binding` is "an open form string … The core ones officially supported are `JSONRPC`, `GRPC` and
|
|
72
|
+
* `HTTP+JSON`."
|
|
73
|
+
*
|
|
74
|
+
* These were named `transport` and `version` until 2026-11-16, names `AgentInterface` does not have, so a 1.0 client
|
|
75
|
+
* parsing the card read every interface with no binding and no version (#3932).
|
|
60
76
|
*/
|
|
61
77
|
export interface A2A_AgentInterface {
|
|
62
78
|
url: string;
|
|
63
|
-
|
|
64
|
-
|
|
79
|
+
protocolBinding: string;
|
|
80
|
+
protocolVersion: string;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* One 1.0 security requirement: the schemes it needs, each with the scopes required. The card lists alternatives, so a
|
|
85
|
+
* client satisfies any one entry.
|
|
86
|
+
*
|
|
87
|
+
* spec-cite: A2A v1.0.0 specification/a2a.proto, `message SecurityRequirement { map<string, StringList> schemes = 1; }`
|
|
88
|
+
* and `message StringList { repeated string list = 1; }`.
|
|
89
|
+
*/
|
|
90
|
+
export interface A2A_SecurityRequirement {
|
|
91
|
+
schemes: Record<string, { list: string[] }>;
|
|
65
92
|
}
|
|
66
93
|
|
|
67
94
|
export interface A2A_AgentCard {
|
|
@@ -96,15 +123,22 @@ export interface A2A_AgentCard {
|
|
|
96
123
|
defaultOutputModes: string[];
|
|
97
124
|
skills: A2A_Skill[];
|
|
98
125
|
securitySchemes: Record<string, unknown>;
|
|
126
|
+
/** The v0.2.5 requirement list (scheme name → scopes), one entry per alternative. Kept for v0.2.5 clients. */
|
|
99
127
|
security: Record<string, string[]>[];
|
|
128
|
+
/**
|
|
129
|
+
* The same alternatives in the 1.0 shape. spec-cite: A2A v1.0.0 specification/a2a.proto, `AgentCard` —
|
|
130
|
+
* `repeated SecurityRequirement security_requirements = 9`.
|
|
131
|
+
*/
|
|
132
|
+
securityRequirements: A2A_SecurityRequirement[];
|
|
100
133
|
}
|
|
101
134
|
```
|
|
102
135
|
|
|
103
136
|
## The A2A task surface (`tasks/get` / `tasks/cancel`)
|
|
104
137
|
|
|
105
138
|
Read this when an external agent needs to start work it will come back for. A turn that pauses
|
|
106
|
-
for human approval also becomes a task: it reaches `
|
|
107
|
-
|
|
139
|
+
for human approval also becomes a task: it reaches `auth-required` (the protocol's in-task
|
|
140
|
+
authorization, given outside the protocol), carries a status message saying a person decides in the
|
|
141
|
+
application, persists the decision it is waiting on, and leaves that state once its execution moves on. Both paths into a task are live,
|
|
108
142
|
so an integration you build now can encounter either.
|
|
109
143
|
|
|
110
144
|
The key thing to understand is **when a task exists at all** — most turns never create
|
|
@@ -133,11 +167,11 @@ one, and that is deliberate rather than a gap.
|
|
|
133
167
|
* - the turn reached an interrupted state (a human-in-the-loop approval pause).
|
|
134
168
|
*
|
|
135
169
|
* All three triggers are live. The interrupted-state arm needs a runtime that can pause a turn; that
|
|
136
|
-
* is the human-in-the-loop approval gate, and a paused turn
|
|
137
|
-
* `
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
*
|
|
170
|
+
* is the human-in-the-loop approval gate, and a paused turn materialises a task carrying
|
|
171
|
+
* `auth-required` on all three transports (blocking send, non-blocking send, stream), with a status
|
|
172
|
+
* message saying a person decides in the application. The task moves on by itself once they have:
|
|
173
|
+
* poll it, subscribe to it, or register a webhook. A message on the task does not answer the
|
|
174
|
+
* approval, and `tasks/cancel` withdraws it.
|
|
141
175
|
*
|
|
142
176
|
* A blocking turn that answers in one shot, with no webhook, returns an A2A `Message` and writes no task
|
|
143
177
|
* row at all. Both shapes are protocol-conformant: the specification types the
|
|
@@ -201,7 +235,7 @@ export interface A2A_TaskSurfaceContract {
|
|
|
201
235
|
* projection from `FlowsActors_Status` reads it, the transport emits it, and tests
|
|
202
236
|
* pin it.
|
|
203
237
|
*
|
|
204
|
-
* Not every member is emitted by this transport today — `
|
|
238
|
+
* Not every member is emitted by this transport today — `INPUT_REQUIRED` and
|
|
205
239
|
* `REJECTED` have no `FlowsActors_Status` counterpart and are never produced. They
|
|
206
240
|
* are declared because the vocabulary belongs to the protocol, not to us: a client
|
|
207
241
|
* may legitimately receive them from another A2A server, and omitting them would
|
|
@@ -213,13 +247,19 @@ export enum A2A_TaskState {
|
|
|
213
247
|
/** Actively being processed. */
|
|
214
248
|
WORKING = 'working',
|
|
215
249
|
/**
|
|
216
|
-
* Interrupted (non-terminal): the agent needs input
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
* principals are denied rather than parked because no named person can answer for them.
|
|
250
|
+
* Interrupted (non-terminal): the agent needs more input from the client, which a follow-up message
|
|
251
|
+
* on the task gives. NOT emitted by this transport: a turn that answers needs no task, and an
|
|
252
|
+
* approval pause is {@link AUTH_REQUIRED}, because a message does not answer it.
|
|
220
253
|
*/
|
|
221
254
|
INPUT_REQUIRED = 'input-required',
|
|
222
|
-
/**
|
|
255
|
+
/**
|
|
256
|
+
* Interrupted (non-terminal): an authorization the task waits on, given outside the protocol.
|
|
257
|
+
* Emitted when a user-delegated turn reaches an approval-gated tool: the signed pending decision is
|
|
258
|
+
* persisted, an addressable task is materialised, and its status message says a person decides in
|
|
259
|
+
* the application. Their approval or refusal resumes that same execution, and the task moves on
|
|
260
|
+
* without the client sending anything. Machine principals are denied rather than parked, because
|
|
261
|
+
* no named person can answer for them.
|
|
262
|
+
*/
|
|
223
263
|
AUTH_REQUIRED = 'auth-required',
|
|
224
264
|
/** Terminal: finished successfully. */
|
|
225
265
|
COMPLETED = 'completed',
|
|
@@ -204,10 +204,14 @@ export const rescheduleTodoTool: FunctionTool = {
|
|
|
204
204
|
argumentsResource: { resourceType: TasksManager_ResourceType.TODOS },
|
|
205
205
|
description:
|
|
206
206
|
'Propose a new due date for one overdue todo. An organization administrator must approve the change before '
|
|
207
|
-
+ 'it is applied. Resolve the todo id with resource.todos.read first.',
|
|
207
|
+
+ 'it is applied. Resolve the todo id with resource.todos.read first, and give the administrator a one-sentence reason.',
|
|
208
208
|
inputSchema: z.object({
|
|
209
209
|
todoId: z.string().min(1).describe('Id of the todo to reschedule. Resolve it with resource.todos.read.'),
|
|
210
210
|
dueDate: z.string().min(1).describe('The proposed due date, as an ISO 8601 date, e.g. "2026-10-04".'),
|
|
211
|
+
// Shown to the administrator who decides, and nowhere else: it is not written to the todo. Defaulted, so a call that
|
|
212
|
+
// leaves it out still runs, and the approval card then shows the default rather than an empty argument (#3295: an
|
|
213
|
+
// approver's edit is parsed, and a parse that fills a default differs from the raw input).
|
|
214
|
+
reason: z.string().max(280).default('No reason given.').describe('One sentence for the approving administrator: why this date.'),
|
|
211
215
|
}),
|
|
212
216
|
humanApproval: {
|
|
213
217
|
route: HumanDecision_RouteKind.ROLE,
|
|
@@ -215,7 +219,7 @@ export const rescheduleTodoTool: FunctionTool = {
|
|
|
215
219
|
// What the todos UPDATE it runs declares (#2526).
|
|
216
220
|
riskLevel: ResourceOperationRiskLevel.LOW,
|
|
217
221
|
},
|
|
218
|
-
execute: async (args: { todoId: string; dueDate: string }, ctx: FunctionToolExecutionContext): Promise<RescheduleTodoToolResult> => {
|
|
222
|
+
execute: async (args: { todoId: string; dueDate: string; reason: string }, ctx: FunctionToolExecutionContext): Promise<RescheduleTodoToolResult> => {
|
|
219
223
|
const dueDate = new Date(args.dueDate);
|
|
220
224
|
if (Number.isNaN(dueDate.getTime())) throw new Error(`"${args.dueDate}" is not a date.`);
|
|
221
225
|
await dispatchResourceOperationAsTool({
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: flows-actors-chat-assistant
|
|
3
|
-
description: Add a conversational AI assistant to your app that answers questions grounded in your users' own resource data. Use when the user says "add a chat assistant", "add an AI assistant grounded on <resource>", "let users chat with / ask questions about their <resource>", "wire a resourceReadTool", "add a flows-actors chat agent", "expose an actor system as a chat view", "show the records as cards in the chat", "set a deadline or reminders on an approval", or "cap what the assistant spends per organization / per person" — i.e. when the intent is a conversational, tool-grounded assistant surfaced as a standalone view, NOT a one-shot generation agent or a background flow.
|
|
3
|
+
description: Add a conversational AI assistant to your app that answers questions grounded in your users' own resource data. Use when the user says "add a chat assistant", "add an AI assistant grounded on <resource>", "let users chat with / ask questions about their <resource>", "wire a resourceReadTool", "add a flows-actors chat agent", "expose an actor system as a chat view", "show the records as cards in the chat", "set a deadline or reminders on an approval", "let my agent delegate to another company's A2A agent", or "cap what the assistant spends per organization / per person" — i.e. when the intent is a conversational, tool-grounded assistant surfaced as a standalone view, NOT a one-shot generation agent or a background flow.
|
|
4
4
|
user-invocable: false
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -187,6 +187,25 @@ A tool you **write by hand** declares how it reaches the application's data, as
|
|
|
187
187
|
Nothing refuses a tool that declares nothing, but the application's assurance evidence reports it, because a
|
|
188
188
|
tool is what an agent's authority confinement rests on.
|
|
189
189
|
|
|
190
|
+
**Tools from another party's MCP server.** Declare the server on the backend domain module's
|
|
191
|
+
`flowsActors.mcpServers` and list its `ref` in the agent's `mcpRefs` — the full contract is in
|
|
192
|
+
`references/framework-mcp-server-declaration-api.md`. Mind two fields: `credential.secretSlug` is the provider's
|
|
193
|
+
secrets-contract KEY (`accessToken`), never the env-var spelling, or a stored credential is silently missed; and write
|
|
194
|
+
`timeouts` out (`discoveryMs: 5_000, callMs: 30_000`). Startup refuses an `mcpRefs` entry naming no declared server, a
|
|
195
|
+
plaintext `http://` endpoint, a transport the runtime does not speak and a `ref` declared twice. The server's tools are
|
|
196
|
+
offered at turn start, except on a turn an inbound delivery started and when no credential resolves for the server's
|
|
197
|
+
`credential.subject`; a server that does not answer contributes none rather than failing the turn, and every call is
|
|
198
|
+
on the audit trail. The server's answers are another party's text: declare `contentGuardrails.promptInjection` (Step 4).
|
|
199
|
+
|
|
200
|
+
**Another party's A2A agent.** Declare it on the backend domain module's `flowsActors.remoteAgents` and list its `ref`
|
|
201
|
+
in the agent's `remoteAgentRefs`; the agent is offered `a2a_<ref>`, which sends a message and returns the remote
|
|
202
|
+
agent's answer or the task it opened, and inside a conversation `a2a_<ref>_task`, which reads or cancels such a task. The contract is in
|
|
203
|
+
`references/framework-remote-a2a-agent-declaration-api.md`. The tool's description is your `description`, never the
|
|
204
|
+
card's; the credential goes only to the `endpointUrl` you named or, without one, to the card's own host; a task id is
|
|
205
|
+
honoured only for a task the same conversation opened with the same credential, and anything else is refused and
|
|
206
|
+
recorded. The same credential, inbound-delivery and audit rules as an MCP server
|
|
207
|
+
apply, and so does `promptInjection`.
|
|
208
|
+
|
|
190
209
|
### Step 4: Declare the use, the guardrails and the approval gates
|
|
191
210
|
Every agent you author — a chat assistant, a one-shot call from your code, a background agent, the agent
|
|
192
211
|
step of a flow — carries three declarations. They are not options for a sensitive agent: they are what an
|
|
@@ -410,6 +429,9 @@ const todoAssistantChatAgent: FlowsActors_Agent = {
|
|
|
410
429
|
functionRefs: [
|
|
411
430
|
TODOS_READ_TOOL_REF,
|
|
412
431
|
TODO_LISTS_READ_TOOL_REF,
|
|
432
|
+
// A recurring todo's occurrences, by the todo's id: they are listed under their todo, which the generic read
|
|
433
|
+
// tool cannot address. See `./todo-occurrences-tool.ts`.
|
|
434
|
+
TODO_OCCURRENCES_TOOL_REF,
|
|
413
435
|
TODOS_CREATE_TOOL_REF,
|
|
414
436
|
TODOS_UPDATE_TOOL_REF,
|
|
415
437
|
// RETRIEVAL grounding — a different KIND of source from the three above. Those return ROWS
|
|
@@ -469,6 +491,7 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
469
491
|
agents: FlowsActors_Agent[];
|
|
470
492
|
functionTools?: FunctionTool[];
|
|
471
493
|
autonomousAgents?: FlowsActors_AutonomousAgentDeclaration[];
|
|
494
|
+
chatAgents?: FlowsActors_ChatAgentDeclaration[];
|
|
472
495
|
} = {
|
|
473
496
|
flowActorSystemsFactoryMap: {
|
|
474
497
|
[TODO_ASSISTANT_SYSTEM_REF]: () => todoAssistantActorSystem,
|
|
@@ -480,6 +503,11 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
480
503
|
},
|
|
481
504
|
agents: [todoAssistantChatAgent, todoTriageAgent, todoDeadlineDrillAgent, todoAutoResolveAgent],
|
|
482
505
|
autonomousAgents: [todosOverdueTriage, todosDeadlineDrill],
|
|
506
|
+
// Who answers a person who writes to the Teams bot (#2665). The Teams messages handler already converses
|
|
507
|
+
// (`../../inbound/teams-bot.inbound-handler.ts`), and with no chat agent declared every such message was refused.
|
|
508
|
+
// The todo assistant answers, as the linked member who wrote and with that member's authority, in every
|
|
509
|
+
// organization that chose no other agent for the connection (Settings > Chat agents).
|
|
510
|
+
chatAgents: [{ ref: 'todos.assistant', systemRef: TODO_ASSISTANT_SYSTEM_REF, isDefault: true }],
|
|
483
511
|
// Generic engine factories instantiated per resource — every tool runs AS THE
|
|
484
512
|
// CALLER (the engine rebuilds a scoped ExecutionContext from the caller's verified
|
|
485
513
|
// auth; identity is never LLM-supplied) and each op's own ACL is enforced by the
|
|
@@ -571,8 +599,10 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
571
599
|
// The engine's question tool (#2720): gated on the OWNER route by construction, so only the person whose turn it
|
|
572
600
|
// is answers it, in the conversation or from their decision inbox.
|
|
573
601
|
askPersonTool(),
|
|
574
|
-
// The records the assistant may show as cards: the same
|
|
575
|
-
|
|
602
|
+
// The records the assistant may show as cards: the same three it reads. An occurrence has no page, so its card opens
|
|
603
|
+
// it in an overlay over the conversation (#2776).
|
|
604
|
+
presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS, TasksManager_ResourceType.TODOS_RECURRING_OCCURRENCES] }),
|
|
605
|
+
todoOccurrencesTool,
|
|
576
606
|
// The overdue-triage agent's one write, ROLE-gated to administrators (#1611). See `./reschedule-todo-tool.ts`.
|
|
577
607
|
rescheduleTodoTool,
|
|
578
608
|
// The deadline drill's four-minute reviewer-routed delete (#1866). See `./deadline-drill-agent.ts`.
|
|
@@ -583,6 +613,8 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
583
613
|
|
|
584
614
|
## References
|
|
585
615
|
|
|
616
|
+
- `references/framework-remote-a2a-agent-declaration-api.md` — the `FlowsActors_RemoteAgent` declaration an agent's `remoteAgentRefs` names: the `a2a_<ref>` tool it becomes, where the credential may go, what each call does and records
|
|
617
|
+
- `references/framework-mcp-server-declaration-api.md` — the `FlowsActors_McpServer` declaration (transport, credential, timeouts) an agent's `mcpRefs` names
|
|
586
618
|
- `references/framework-model-spend-limits-api.md` — the organization budget and the per-person ceiling every in-app turn is refused against, fail-closed, and the three unit ceilings on embeddings, document extraction and content screening: how to grant them on plans, what the person is told, what each refused call does, the `MODEL_SPEND_LIMIT_REFUSED` audit row each refusal writes, and where each one's usage is shown
|
|
587
619
|
- `references/framework-tool-dispatch-obligations-api.md` — grounding an agent on resource operations, and the two controller-tier gates a HAND-WRITTEN tool must call itself
|
|
588
620
|
- `references/framework-present-records-tool-api.md` — `presentRecordsTool()`: the agent shows its person records as summary cards in the conversation, kept as a reference and fetched with the viewer's session
|
package/dist/knowledge/skills/flows-actors-chat-assistant/examples/todo-assistant.example.md
CHANGED
|
@@ -130,6 +130,9 @@ const todoAssistantChatAgent: FlowsActors_Agent = {
|
|
|
130
130
|
functionRefs: [
|
|
131
131
|
TODOS_READ_TOOL_REF,
|
|
132
132
|
TODO_LISTS_READ_TOOL_REF,
|
|
133
|
+
// A recurring todo's occurrences, by the todo's id: they are listed under their todo, which the generic read
|
|
134
|
+
// tool cannot address. See `./todo-occurrences-tool.ts`.
|
|
135
|
+
TODO_OCCURRENCES_TOOL_REF,
|
|
133
136
|
TODOS_CREATE_TOOL_REF,
|
|
134
137
|
TODOS_UPDATE_TOOL_REF,
|
|
135
138
|
// RETRIEVAL grounding — a different KIND of source from the three above. Those return ROWS
|
|
@@ -189,6 +192,7 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
189
192
|
agents: FlowsActors_Agent[];
|
|
190
193
|
functionTools?: FunctionTool[];
|
|
191
194
|
autonomousAgents?: FlowsActors_AutonomousAgentDeclaration[];
|
|
195
|
+
chatAgents?: FlowsActors_ChatAgentDeclaration[];
|
|
192
196
|
} = {
|
|
193
197
|
flowActorSystemsFactoryMap: {
|
|
194
198
|
[TODO_ASSISTANT_SYSTEM_REF]: () => todoAssistantActorSystem,
|
|
@@ -200,6 +204,11 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
200
204
|
},
|
|
201
205
|
agents: [todoAssistantChatAgent, todoTriageAgent, todoDeadlineDrillAgent, todoAutoResolveAgent],
|
|
202
206
|
autonomousAgents: [todosOverdueTriage, todosDeadlineDrill],
|
|
207
|
+
// Who answers a person who writes to the Teams bot (#2665). The Teams messages handler already converses
|
|
208
|
+
// (`../../inbound/teams-bot.inbound-handler.ts`), and with no chat agent declared every such message was refused.
|
|
209
|
+
// The todo assistant answers, as the linked member who wrote and with that member's authority, in every
|
|
210
|
+
// organization that chose no other agent for the connection (Settings > Chat agents).
|
|
211
|
+
chatAgents: [{ ref: 'todos.assistant', systemRef: TODO_ASSISTANT_SYSTEM_REF, isDefault: true }],
|
|
203
212
|
// Generic engine factories instantiated per resource — every tool runs AS THE
|
|
204
213
|
// CALLER (the engine rebuilds a scoped ExecutionContext from the caller's verified
|
|
205
214
|
// auth; identity is never LLM-supplied) and each op's own ACL is enforced by the
|
|
@@ -291,8 +300,10 @@ export const moduleBackend_FlowsActorsRegistry: {
|
|
|
291
300
|
// The engine's question tool (#2720): gated on the OWNER route by construction, so only the person whose turn it
|
|
292
301
|
// is answers it, in the conversation or from their decision inbox.
|
|
293
302
|
askPersonTool(),
|
|
294
|
-
// The records the assistant may show as cards: the same
|
|
295
|
-
|
|
303
|
+
// The records the assistant may show as cards: the same three it reads. An occurrence has no page, so its card opens
|
|
304
|
+
// it in an overlay over the conversation (#2776).
|
|
305
|
+
presentRecordsTool({ resourceTypes: [TasksManager_ResourceType.TODOS, TasksManager_ResourceType.TODO_LISTS, TasksManager_ResourceType.TODOS_RECURRING_OCCURRENCES] }),
|
|
306
|
+
todoOccurrencesTool,
|
|
296
307
|
// The overdue-triage agent's one write, ROLE-gated to administrators (#1611). See `./reschedule-todo-tool.ts`.
|
|
297
308
|
rescheduleTodoTool,
|
|
298
309
|
// The deadline drill's four-minute reviewer-routed delete (#1866). See `./deadline-drill-agent.ts`.
|
|
@@ -514,6 +514,11 @@ export interface FunctionTool {
|
|
|
514
514
|
* you write by hand, whose input would not read back as records.
|
|
515
515
|
*/
|
|
516
516
|
presentsRecords?: boolean;
|
|
517
|
+
/**
|
|
518
|
+
* The resources whose records the tool SHOWS as cards. Set by {@link presentRecordsTool}; registration refuses one a card
|
|
519
|
+
* cannot read ({@link presentRecordsAddressabilityProblems}, #4011).
|
|
520
|
+
*/
|
|
521
|
+
presentedResourceTypes?: readonly ResourceType[];
|
|
517
522
|
/**
|
|
518
523
|
* The resources the tool SEARCHES through the retrieval index (#2300). Set by {@link retrievalTool}; startup refuses an
|
|
519
524
|
* application whose retrieval tool names a resource that declares no `.ragSource()` field, which would otherwise
|
|
@@ -1157,10 +1162,17 @@ export function functionToolDeliverableDeclarationProblems(
|
|
|
1157
1162
|
* #2914), one sentence per problem with its remedy; empty when they are sound or absent. `declaredFieldsOf` answers the
|
|
1158
1163
|
* fields the resource's main schema declares, or undefined when the resource is not registered (its fields are then not
|
|
1159
1164
|
* checked here: a field the row does not hold is shown and sealed as absent).
|
|
1165
|
+
*
|
|
1166
|
+
* `systemReadAllowedOf` answers whether the resource grants the system READ (`systemAccessPolicy.read`), or undefined when
|
|
1167
|
+
* the resource is not registered. The card, the seal and the currency check all read the row through `readAsSystem`, which
|
|
1168
|
+
* refuses a resource that does not grant it, and that refusal is swallowed into "no record values": every approval then
|
|
1169
|
+
* seals no field and no currency check can compare anything. Measured on Wonder Ledger's live sign-off, where the declared
|
|
1170
|
+
* field set was sealed on none of the seals, so a declaration nothing can read stops the application here instead.
|
|
1160
1171
|
*/
|
|
1161
1172
|
export function functionToolRecordApprovalDeclarationProblems(
|
|
1162
1173
|
tool: Pick<FunctionTool, 'functionRef' | 'sealedRecordFields' | 'approvalReplacesEarlierApprovalOfRow' | 'argumentsResource' | 'requiresHumanApproval' | 'humanApproval' | 'asksThePerson'>,
|
|
1163
1174
|
declaredFieldsOf?: (resourceType: string) => readonly string[] | undefined,
|
|
1175
|
+
systemReadAllowedOf?: (resourceType: string) => boolean | undefined,
|
|
1164
1176
|
): string[] {
|
|
1165
1177
|
const fields = tool.sealedRecordFields;
|
|
1166
1178
|
const replaces = tool.approvalReplacesEarlierApprovalOfRow === true;
|
|
@@ -1184,6 +1196,10 @@ export function functionToolRecordApprovalDeclarationProblems(
|
|
|
1184
1196
|
const unknown = declared ? fields.filter((field) => !declared.includes(field)) : [];
|
|
1185
1197
|
if (unknown.length > 0) problems.push(`${named}, naming ${unknown.join(', ')}, which ${tool.argumentsResource!.resourceType} does not declare.`);
|
|
1186
1198
|
}
|
|
1199
|
+
if (tool.argumentsResource && systemReadAllowedOf?.(tool.argumentsResource.resourceType) === false) {
|
|
1200
|
+
problems.push(`${named}, but ${tool.argumentsResource.resourceType} does not grant the system read the approval card, the seal and the currency check `
|
|
1201
|
+
+ `read the row through: declare systemAccessPolicy.read = ResourceSystemAccessMode.ALLOWED on it.`);
|
|
1202
|
+
}
|
|
1187
1203
|
}
|
|
1188
1204
|
return problems;
|
|
1189
1205
|
}
|
|
@@ -13,6 +13,21 @@ contribution shape:
|
|
|
13
13
|
each part draws the "not injected" placeholder (visible in development, empty in
|
|
14
14
|
production) and the console warns. Import type
|
|
15
15
|
from `@wildo-ai/saas-frontend-lib/companion`.
|
|
16
|
+
- Opening one conversation by link: link to `/conversation?system=<systemRef>&id=<executionId>&context=<contextRef>`,
|
|
17
|
+
the address the engine's own notices and emails use (`conversationLinkPathOf` builds it; `context` is the
|
|
18
|
+
conversation's stored context and may be left out). The page first switches the person to the organization the
|
|
19
|
+
context names, by the same rules a route uses (it says the conversation cannot be opened when the session cannot be
|
|
20
|
+
there). Then, when the context names a record whose resource composite declares `conversationSystemRef` for this
|
|
21
|
+
system, it opens that composite on that record; otherwise the FIRST `flowsActorsViews` entry with that `systemRef`
|
|
22
|
+
(so an assistant whose conversations people are told about needs a view, or the link says the view does not exist).
|
|
23
|
+
The view opens the conversation when the person's history holds it, reading it by id when it is older than the
|
|
24
|
+
newest page; otherwise it says it cannot be opened here and offers a new one, and nothing can be sent until that is
|
|
25
|
+
known. Do not link to a view's own page with a `?conversation=` parameter: on a view already open, that address is
|
|
26
|
+
read as a change of view state and ignored.
|
|
27
|
+
- A chat placed on a record (a resource composite rendering `FlowsActorsView` with the record in
|
|
28
|
+
`contextResourceIdentifiers`): declare `conversationSystemRef: '<systemRef>'` on that composite. Its discussions are
|
|
29
|
+
listed only there, so this is how a link to one finds the page; the engine then hands the linked discussion to the
|
|
30
|
+
`FlowsActorsView` of that system inside it, and your component passes nothing for it.
|
|
16
31
|
- The backend module contribution `flowsActors` — where `flowActorSystemsFactoryMap`,
|
|
17
32
|
`agents`, and **`functionTools`** are registered. (The `functionTools` field is
|
|
18
33
|
the one you populate with `resourceReadTool(...)` instances.)
|
|
@@ -93,6 +108,19 @@ export interface BackendDomainModule extends SharedDomainModule {
|
|
|
93
108
|
* `capabilities.tools.functionRefs`.
|
|
94
109
|
*/
|
|
95
110
|
functionTools?: FunctionTool[];
|
|
111
|
+
/**
|
|
112
|
+
* Another party's MCP servers this module's agents may call (#3958): each one's endpoint and the stored provider
|
|
113
|
+
* connection whose credential reaches it. Reference them from an agent's `capabilities.tools.mcpRefs`. Registration
|
|
114
|
+
* refuses a plaintext `http://` endpoint, and every call goes through the outbound guard. See `FlowsActors_McpServer`.
|
|
115
|
+
*/
|
|
116
|
+
mcpServers?: FlowsActors_McpServer[];
|
|
117
|
+
/**
|
|
118
|
+
* Another party's A2A agents this module's agents may delegate a task to (#3930): each one's card URL and the stored
|
|
119
|
+
* provider connection whose credential reaches it. Reference them from an agent's
|
|
120
|
+
* `capabilities.tools.remoteAgentRefs`. Registration refuses a plaintext `http://` card or endpoint, and every call
|
|
121
|
+
* goes through the outbound guard. See `FlowsActors_RemoteAgent`.
|
|
122
|
+
*/
|
|
123
|
+
remoteAgents?: FlowsActors_RemoteAgent[];
|
|
96
124
|
/**
|
|
97
125
|
* Agents that may run with nobody on a socket — on a schedule or on an inbound delivery (#1611).
|
|
98
126
|
* Declaring one grants nothing: a turn runs in an organization only while one of its OAuth clients
|
|
@@ -501,6 +529,8 @@ function mergeFlowsActors(
|
|
|
501
529
|
) as FlowActorSystem_InitializationFactoryMap,
|
|
502
530
|
agents: modules.flatMap(m => m.flowsActors?.agents ?? []),
|
|
503
531
|
functionTools: modules.flatMap(m => m.flowsActors?.functionTools ?? []),
|
|
532
|
+
mcpServers: modules.flatMap(m => m.flowsActors?.mcpServers ?? []),
|
|
533
|
+
remoteAgents: modules.flatMap(m => m.flowsActors?.remoteAgents ?? []),
|
|
504
534
|
autonomousAgents: modules.flatMap(m => m.flowsActors?.autonomousAgents ?? []),
|
|
505
535
|
chatAgents: modules.flatMap(m => m.flowsActors?.chatAgents ?? []),
|
|
506
536
|
actorExecutionContinuations: modules.flatMap(m => m.flowsActors?.actorExecutionContinuations ?? []),
|