@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
package/dist/knowledge/references/saas.frontend.electronic-signatures.embedded-signing-frame.md
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# saas.frontend.electronic-signatures.embedded-signing-frame
|
|
2
|
+
|
|
3
|
+
## Import Origins
|
|
4
|
+
|
|
5
|
+
- `@wildo-ai/saas-frontend-lib`
|
|
6
|
+
|
|
7
|
+
## Source Excerpts
|
|
8
|
+
|
|
9
|
+
### Origin Package: `@wildo-ai/saas-frontend-lib`
|
|
10
|
+
|
|
11
|
+
```tsx
|
|
12
|
+
/**
|
|
13
|
+
* Embedded signing: the signed-in person signs a record's deliverable at the signature vendor, inside a frame of the
|
|
14
|
+
* application, instead of following the vendor's e-mail. Import from `@wildo-ai/saas-frontend-lib`.
|
|
15
|
+
*
|
|
16
|
+
* Place it where the person meets the record (an engagement letter's page, say). On mount it asks the backend for the
|
|
17
|
+
* vendor's signing page (`signatureRequestSigners.openSigningSession`). The answer is given only to a signer an open
|
|
18
|
+
* request on that record names and the vendor says has not signed yet, so for anybody else, once the person has signed,
|
|
19
|
+
* and when the request's provider signs from its e-mail only, the component renders NOTHING. The page is valid for
|
|
20
|
+
* minutes and is never stored, which is why it is asked for here, when the person is in front of it. A signer whose turn
|
|
21
|
+
* has not come (signers who sign in turn) is shown nothing either, until it does.
|
|
22
|
+
*
|
|
23
|
+
* When the person is done, a vendor that redirects sends the frame to the application's own {@link SIGNING_RETURN_PAGE_PATH};
|
|
24
|
+
* the frame sees it arrive (it is now same-origin), closes, and calls `onSigningReturned`. A vendor that does not redirect
|
|
25
|
+
* (or redirects to another of the application's origins) keeps showing its own end page. Either way nothing here says the
|
|
26
|
+
* document is signed: every vendor's own guidance is that the end of the frame is not the outcome, and the request becomes
|
|
27
|
+
* SIGNED only once the engine has validated the signed document, at its next re-read (poll or vendor notification).
|
|
28
|
+
*
|
|
29
|
+
* What it needs elsewhere: a provider that claims `EMBEDDED_ELECTRONIC_SIGNATURE` and declares `embeddedSigning`, and a
|
|
30
|
+
* `wildo config sync` then `wildo dev sync-csp` since it was added, which put the vendor's signing origins in the SaaS
|
|
31
|
+
* frontend's CSP `frame-src` from the provider's own declaration; without them the browser refuses to load the frame.
|
|
32
|
+
*
|
|
33
|
+
* It renders no words of its own: the application passes the frame's accessible `title`.
|
|
34
|
+
*/
|
|
35
|
+
export interface EmbeddedSigningFrameProps {
|
|
36
|
+
/** The record the deliverable belongs to: the signature request's `linkedResourceType`. */
|
|
37
|
+
readonly linkedResourceType: string;
|
|
38
|
+
/** The record the deliverable belongs to: the signature request's `linkedResourceId`. */
|
|
39
|
+
readonly linkedResourceId: string;
|
|
40
|
+
/** The frame's accessible name (WCAG 4.1.2), in the person's language, e.g. "Sign the engagement letter". */
|
|
41
|
+
readonly title: string;
|
|
42
|
+
/** Called once the person left the vendor's page. Re-read the record if you show its signature state. */
|
|
43
|
+
readonly onSigningReturned?: () => void;
|
|
44
|
+
readonly className?: string;
|
|
45
|
+
}
|
|
46
|
+
```
|
|
@@ -234,6 +234,18 @@ export enum EngineSettingsDestinationRef {
|
|
|
234
234
|
* owner/admin, the roles that bind a client to an agent.
|
|
235
235
|
*/
|
|
236
236
|
AUTONOMOUS_AGENTS = 'autonomous-agents',
|
|
237
|
+
/**
|
|
238
|
+
* What THIS organization's declared FLOWS and ACTOR SYSTEMS did (#3990): every run on the actor plane, newest first,
|
|
239
|
+
* and each run's history, its tasks (what each actor was asked and produced) and, for a flow, the steps it went
|
|
240
|
+
* through, each with when it happened, in the reader's time zone. Org owner/admin, the people the route admits (an
|
|
241
|
+
* administrator of the organization through an organization-wide role, or the application super-administrator).
|
|
242
|
+
*
|
|
243
|
+
* Beside {@link AGENT_RUNS}, never merged into it: those are CONVERSATIONS (a chat, an A2A client's turn) with their
|
|
244
|
+
* transcripts, read under the execution resource's roles; these are the runs of declared systems, which no resource
|
|
245
|
+
* routes. No capability gate: a flow runs with no language model, so an application declaring flows and no
|
|
246
|
+
* `AI_LLM` still has activity to read; one declaring neither shows an empty list, and may remove the placement.
|
|
247
|
+
*/
|
|
248
|
+
AGENT_ACTIVITY = 'agent-activity',
|
|
237
249
|
/**
|
|
238
250
|
* Which of the application's chat agents answers the organization's people on each chat connection (#2665): Slack,
|
|
239
251
|
* Microsoft Teams. Org owner/admin, the roles the `organizationChatSettings` writes accept. A connection with no choice
|
|
@@ -363,6 +375,15 @@ export enum EngineSettingsDestinationRef {
|
|
|
363
375
|
* application row. What a run consumed is answered to an application cost reader by the run's `usage` operation.
|
|
364
376
|
*/
|
|
365
377
|
APPLICATION_AGENT_RUNS = 'application-agent-runs',
|
|
378
|
+
/**
|
|
379
|
+
* What the declared flows and actor systems did in EVERY organization (#3990): the same page as
|
|
380
|
+
* {@link AGENT_ACTIVITY}, across tenants, each run naming the organization it worked for. An APPLICATION-WIDE read, so
|
|
381
|
+
* it is admitted under the application's audit read policy (`resolveAuditApplicationReadAccess`): the
|
|
382
|
+
* super-administrator role alone under ROLE_BASED, and a live application access grant a second administrator signed
|
|
383
|
+
* under INDEPENDENT_APPROVAL. Every read is recorded (`PLATFORM_DIRECTORY_ACCESS`, naming the grant when there is one).
|
|
384
|
+
* Super-admin, the role the route admits.
|
|
385
|
+
*/
|
|
386
|
+
APPLICATION_AGENT_ACTIVITY = 'application-agent-activity',
|
|
366
387
|
/**
|
|
367
388
|
* Which agents the application's super-administrator switched off for EVERY organization (#2843), each with the
|
|
368
389
|
* justification it was suspended with, and the Suspend and Resume actions. Super-admin, the role both verbs require;
|
|
@@ -106,45 +106,36 @@ export type FlowsActors_Agent = {
|
|
|
106
106
|
/**
|
|
107
107
|
* References to MCP servers the agent may reach.
|
|
108
108
|
*
|
|
109
|
-
* ##
|
|
109
|
+
* ## Checked at startup, called at turn start (#491, #3958)
|
|
110
110
|
*
|
|
111
|
-
* Each ref must name an MCP server the APPLICATION declared (`FlowsActors_McpServer
|
|
112
|
-
* `
|
|
113
|
-
*
|
|
114
|
-
* carried seven refs
|
|
115
|
-
* no server anywhere while the agent card rendered them as capabilities — a claim shown to a
|
|
116
|
-
* user about a reach the agent did not have. The catalog is gone and the card no longer
|
|
117
|
-
* renders these.
|
|
111
|
+
* Each ref must name an MCP server the APPLICATION declared (`FlowsActors_McpServer`, on a backend domain
|
|
112
|
+
* module's `flowsActors.mcpServers`), and startup REFUSES an agent whose refs name none. That closes the shape
|
|
113
|
+
* this field was in: it used to resolve against nothing, so a shipped
|
|
114
|
+
* catalog carried seven refs that named no server anywhere — a claim about a reach the agent did not have.
|
|
118
115
|
*
|
|
119
|
-
* The check is deliberately stricter than `functionRefs`, which skip an unknown ref with a
|
|
120
|
-
*
|
|
121
|
-
* as a capability, and a refusal makes the old state unreachable rather than fixed once.
|
|
116
|
+
* The check is deliberately stricter than `functionRefs`, which skip an unknown ref with a debug line: an unknown
|
|
117
|
+
* `functionRef` costs an agent one tool, whereas these name another party's server.
|
|
122
118
|
*
|
|
123
|
-
*
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
*
|
|
132
|
-
* 3. **Credential resolution at call time.** Decided 2026-09-09: the call carries the acting
|
|
133
|
-
* user's own delegated provider credential where present and the organization's connection
|
|
134
|
-
* otherwise, from `userProviderCredentials` / `organizationProviderCredentials` rather than
|
|
135
|
-
* a store invented for MCP. `FlowsActors_McpCredentialSubject` records that choice per
|
|
136
|
-
* server; nothing reads it yet.
|
|
119
|
+
* At turn start the agent opens a session with each named server, using the credential the server's declared
|
|
120
|
+
* `credential.subject` selects, and is offered the server's tools. They are withheld on a turn an inbound
|
|
121
|
+
* delivery started and when no credential resolves; a server that does not answer contributes no tools rather
|
|
122
|
+
* than failing the turn. Every tool call, and a target the outbound guard refuses, is recorded on the audit
|
|
123
|
+
* trail; an unreachable or slow server is logged.
|
|
124
|
+
*/
|
|
125
|
+
mcpRefs: string[],
|
|
126
|
+
/**
|
|
127
|
+
* References to remote A2A agents the agent may delegate a task to (#3930).
|
|
137
128
|
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
* returns a typed error the agent can reason about. Both emit an audit event, because a server
|
|
141
|
-
* quietly unreachable for a week must be visible as that rather than as an agent that became
|
|
142
|
-
* less capable for no stated reason.
|
|
129
|
+
* Each ref must name a remote agent the APPLICATION declared (`FlowsActors_RemoteAgent`, on a backend domain
|
|
130
|
+
* module's `flowsActors.remoteAgents`); startup REFUSES an agent whose refs name none, as for `mcpRefs`.
|
|
143
131
|
*
|
|
144
|
-
*
|
|
145
|
-
*
|
|
132
|
+
* At turn start the agent is offered one tool per named remote agent, described by the declaration (never by the
|
|
133
|
+
* remote card). A call sends the agent's message to the remote agent over A2A 1.0 with the credential the
|
|
134
|
+
* declaration's `credential.subject` selects, and returns the remote reply, or the remote task's state and ids
|
|
135
|
+
* when it is still running or waits for input. Withheld on a turn an inbound delivery started and when no
|
|
136
|
+
* credential resolves. Every call is recorded on the audit trail.
|
|
146
137
|
*/
|
|
147
|
-
|
|
138
|
+
remoteAgentRefs?: string[],
|
|
148
139
|
},
|
|
149
140
|
},
|
|
150
141
|
|
|
@@ -78,6 +78,15 @@ export type HumanDecisionPhrase =
|
|
|
78
78
|
| { readonly kind: HumanDecisionPhraseKind.TOOL; readonly toolName: string }
|
|
79
79
|
| { readonly kind: HumanDecisionPhraseKind.RESOURCE_OPERATION; readonly resourceType: string; readonly operationIdentifier: string };
|
|
80
80
|
|
|
81
|
+
/**
|
|
82
|
+
* The words of the button a chat copy of a decision carries when it is answered in the application only (#2797): a
|
|
83
|
+
* decision that asks values, or has more options than a card shows. What a decision-notice handler passes to its
|
|
84
|
+
* vendor helper's `openInApplication`, beside `ctx.decisionUrl(decisionRef)`.
|
|
85
|
+
*/
|
|
86
|
+
export function humanDecisionOpenInApplicationPhrase(): HumanDecisionPhrase {
|
|
87
|
+
return { kind: HumanDecisionPhraseKind.LABEL, labelRef: 'noticeOpenInApplication' };
|
|
88
|
+
}
|
|
89
|
+
|
|
81
90
|
/** The full key a LABEL, ROLE or TOOL phrase names in an application's label tree; `undefined` for TEXT, which names none. */
|
|
82
91
|
export function humanDecisionPhraseLabelKey(phrase: HumanDecisionPhrase): string | undefined {
|
|
83
92
|
switch (phrase.kind) {
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# saas.models.flows-actors.mcp-server-declaration
|
|
2
|
+
|
|
3
|
+
## Import Origins
|
|
4
|
+
|
|
5
|
+
- `@wildo-ai/saas-models`
|
|
6
|
+
|
|
7
|
+
## Source Excerpts
|
|
8
|
+
|
|
9
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
10
|
+
|
|
11
|
+
```typescript
|
|
12
|
+
*
|
|
13
|
+
* How the runtime reaches the server.
|
|
14
|
+
*
|
|
15
|
+
* A closed vocabulary rather than a free string: the transport decides the whole connection
|
|
16
|
+
* lifecycle — how a session opens, whether the server can push, how a stream ends — so a value
|
|
17
|
+
* nobody implemented must be unrepresentable rather than discovered at the first call.
|
|
18
|
+
*
|
|
19
|
+
* STDIO is deliberately ABSENT. It launches a local subprocess, which is the coding-agent lane's
|
|
20
|
+
* shape and not an application's: a generated application runs in a container it does not control,
|
|
21
|
+
* and "the agent may spawn a process" is a different security decision from "the agent may call an
|
|
22
|
+
* endpoint". Adding it later is a decision, not an omission.
|
|
23
|
+
*/
|
|
24
|
+
export enum FlowsActors_McpTransport {
|
|
25
|
+
/** Streamable HTTP — the current MCP transport for remote servers. */
|
|
26
|
+
HTTP_STREAM = 'http_stream',
|
|
27
|
+
/**
|
|
28
|
+
* Server-sent events — the earlier remote transport, still widely deployed. The client speaks Streamable HTTP only,
|
|
29
|
+
* so startup REFUSES a server declared with it (#3958) rather than failing every turn as a protocol error.
|
|
30
|
+
*/
|
|
31
|
+
SSE = 'sse',
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Bounds on a call that leaves the trust boundary.
|
|
37
|
+
*
|
|
38
|
+
* Present with defaults rather than optional-and-unbounded, because an MCP call is a REMOTE call and
|
|
39
|
+
* the mistake this whole issue warns against is modelling it as a second kind of local function. A
|
|
40
|
+
* local function cannot hang; this can, and an unbounded tool call holds a model turn open for as
|
|
41
|
+
* long as somebody else's server feels like it.
|
|
42
|
+
*/
|
|
43
|
+
export const FlowsActors_McpServerTimeoutsSchema = z.object({
|
|
44
|
+
/** How long tool DISCOVERY may take before the server contributes no tools to the turn. */
|
|
45
|
+
discoveryMs: z.number().int().positive().default(5_000),
|
|
46
|
+
/** How long one tool CALL may take before it returns a typed timeout to the agent. */
|
|
47
|
+
callMs: z.number().int().positive().default(30_000),
|
|
48
|
+
});
|
|
49
|
+
export type FlowsActors_McpServerTimeouts = z.infer<typeof FlowsActors_McpServerTimeoutsSchema>;
|
|
50
|
+
|
|
51
|
+
export const FlowsActors_McpServerSchema = z.object({
|
|
52
|
+
/** The value an agent's `capabilities.tools.mcpRefs` names. Unique within an application. */
|
|
53
|
+
ref: z.string().min(1),
|
|
54
|
+
displayName: z.string().min(1),
|
|
55
|
+
transport: z.enum(FlowsActors_McpTransport),
|
|
56
|
+
/** The server's endpoint. `https` in every deployed environment; the runtime refuses plaintext. */
|
|
57
|
+
url: z.string().url(),
|
|
58
|
+
/** Which stored provider credential authorizes the calls (`FlowsActors_OutboundCredentialSchema`). */
|
|
59
|
+
credential: FlowsActors_OutboundCredentialSchema,
|
|
60
|
+
timeouts: FlowsActors_McpServerTimeoutsSchema.default({ discoveryMs: 5_000, callMs: 30_000 }),
|
|
61
|
+
});
|
|
62
|
+
export type FlowsActors_McpServer = z.infer<typeof FlowsActors_McpServerSchema>;
|
|
63
|
+
```
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# saas.models.flows-actors.outbound-credential
|
|
2
|
+
|
|
3
|
+
## Import Origins
|
|
4
|
+
|
|
5
|
+
- `@wildo-ai/saas-models`
|
|
6
|
+
|
|
7
|
+
## Source Excerpts
|
|
8
|
+
|
|
9
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
10
|
+
|
|
11
|
+
```typescript
|
|
12
|
+
/**
|
|
13
|
+
* WHOSE credential the call carries.
|
|
14
|
+
*
|
|
15
|
+
* The distinction is not a preference. A tool call that reaches a third party on a user's behalf
|
|
16
|
+
* should be attributable to that user AT THE FAR END — that is what makes it revocable there and
|
|
17
|
+
* auditable by the party being called. An application-wide service identity loses that: every
|
|
18
|
+
* user's call looks identical to the server, and one leaked credential exposes every tenant.
|
|
19
|
+
*/
|
|
20
|
+
export enum FlowsActors_OutboundCredentialSubject {
|
|
21
|
+
/**
|
|
22
|
+
* The acting user's own delegated credential, falling back to the organization's connection when
|
|
23
|
+
* the user has none. The default, and the reason a fallback exists at all: an agent acting for a
|
|
24
|
+
* user who has never connected the server would otherwise have no path, which would make every
|
|
25
|
+
* unattended and batch turn impossible.
|
|
26
|
+
*/
|
|
27
|
+
USER_THEN_ORGANIZATION = 'user_then_organization',
|
|
28
|
+
/** The organization's connection only — for a server the tenant connects once on everyone's behalf. */
|
|
29
|
+
ORGANIZATION = 'organization',
|
|
30
|
+
/** The acting user's own credential only. No fallback: a user who has not connected cannot call. */
|
|
31
|
+
USER = 'user',
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Which stored credential authorizes the call.
|
|
36
|
+
*
|
|
37
|
+
* `providerRef` names a provider the application has already connected, so the credential comes from
|
|
38
|
+
* `organizationProviderCredentials` / `userProviderCredentials` rather than from a store invented
|
|
39
|
+
* for one kind of call. Those exist, carry per-tenant isolation by construction, and already have the connect and
|
|
40
|
+
* consent flow in front of them — a second credential store for this one call shape would be a
|
|
41
|
+
* second thing to rotate, audit and leak.
|
|
42
|
+
*/
|
|
43
|
+
export const FlowsActors_OutboundCredentialSchema = z.object({
|
|
44
|
+
providerRef: z.string().min(1),
|
|
45
|
+
/**
|
|
46
|
+
* The provider's `secretsContract` KEY (`accessToken`) — the one both credential resolver ports
|
|
47
|
+
* require, and NOT the slot's env-var spelling (`VENDOR_ACCESS_TOKEN`) the env projection names.
|
|
48
|
+
* Stored credentials are keyed on the key (#624), and this value reaches the stores verbatim, so a
|
|
49
|
+
* spelling here misses a credential that exists.
|
|
50
|
+
*
|
|
51
|
+
* DECLARED rather than derived, because it is not derivable: a provider's contract may carry
|
|
52
|
+
* several secrets, and which of them authorizes the endpoint is a fact about that vendor's
|
|
53
|
+
* deployment rather than anything the framework can compute. Guessing a conventional name would
|
|
54
|
+
* resolve the wrong secret silently — the resolver would find a credential, spend it, and be
|
|
55
|
+
* refused by the far server for a reason no log here would explain.
|
|
56
|
+
*/
|
|
57
|
+
secretSlug: z.string().min(1),
|
|
58
|
+
subject: z.enum(FlowsActors_OutboundCredentialSubject).default(FlowsActors_OutboundCredentialSubject.USER_THEN_ORGANIZATION),
|
|
59
|
+
});
|
|
60
|
+
export type FlowsActors_OutboundCredential = z.infer<typeof FlowsActors_OutboundCredentialSchema>;
|
|
61
|
+
```
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# saas.models.flows-actors.remote-agent-declaration
|
|
2
|
+
|
|
3
|
+
## Import Origins
|
|
4
|
+
|
|
5
|
+
- `@wildo-ai/saas-models`
|
|
6
|
+
|
|
7
|
+
## Source Excerpts
|
|
8
|
+
|
|
9
|
+
### Origin Package: `@wildo-ai/saas-models`
|
|
10
|
+
|
|
11
|
+
```typescript
|
|
12
|
+
/**
|
|
13
|
+
* Bounds on a call that leaves the trust boundary. Present with defaults, because a remote agent can take as long as it
|
|
14
|
+
* likes and an unbounded call would hold the calling agent's turn open for that long.
|
|
15
|
+
*/
|
|
16
|
+
export const FlowsActors_RemoteAgentTimeoutsSchema = z.object({
|
|
17
|
+
/** How long fetching the remote agent's card may take. */
|
|
18
|
+
cardMs: z.number().int().positive().default(5_000),
|
|
19
|
+
/**
|
|
20
|
+
* How long one delegation may take, end to end: the send, then reading the task until it ends or pauses. A task still
|
|
21
|
+
* running at the deadline is returned to the calling agent as still running, with its ids; it is never cancelled.
|
|
22
|
+
*/
|
|
23
|
+
callMs: z.number().int().positive().default(60_000),
|
|
24
|
+
});
|
|
25
|
+
export type FlowsActors_RemoteAgentTimeouts = z.infer<typeof FlowsActors_RemoteAgentTimeoutsSchema>;
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Another party's A2A agent the application's agents may delegate a task to (A2A 1.0, JSON-RPC binding).
|
|
29
|
+
*
|
|
30
|
+
* The runtime fetches the agent card from `cardUrl` WITHOUT the credential and sends the credential to one of the card's
|
|
31
|
+
* JSON-RPC interfaces at protocol version 1.0, and only to one the application named too: with `endpointUrl` declared,
|
|
32
|
+
* the interface at exactly that URL; without it, the card's first such interface, and only when it is on the card's own
|
|
33
|
+
* host. A card cannot redirect a credential to a host the application never named.
|
|
34
|
+
*/
|
|
35
|
+
export const FlowsActors_RemoteAgentSchema = z.object({
|
|
36
|
+
/** The value an agent's `capabilities.tools.remoteAgentRefs` names. Unique within an application. */
|
|
37
|
+
ref: z.string().min(1),
|
|
38
|
+
displayName: z.string().min(1),
|
|
39
|
+
/**
|
|
40
|
+
* What the remote agent does, in the application's words. It is the description of the tool the calling model is
|
|
41
|
+
* offered — the card's own description never reaches the model.
|
|
42
|
+
*/
|
|
43
|
+
description: z.string().min(1),
|
|
44
|
+
/** Where the agent card is served, `https://` (e.g. `https://agent.example.com/.well-known/agent-card.json`). */
|
|
45
|
+
cardUrl: z.string().url(),
|
|
46
|
+
/**
|
|
47
|
+
* The interface URL the credential is sent to, exactly. Declare it when the agent's interface is on another host than
|
|
48
|
+
* its card, or to pin which of the card's interfaces is used. The credential is resolved for this URL.
|
|
49
|
+
*/
|
|
50
|
+
endpointUrl: z.string().url().optional(),
|
|
51
|
+
/** Which stored provider credential authorizes the calls, and whose. Required: an anonymous remote agent is not admitted. */
|
|
52
|
+
credential: FlowsActors_OutboundCredentialSchema,
|
|
53
|
+
timeouts: FlowsActors_RemoteAgentTimeoutsSchema.default({ cardMs: 5_000, callMs: 60_000 }),
|
|
54
|
+
});
|
|
55
|
+
export type FlowsActors_RemoteAgent = z.infer<typeof FlowsActors_RemoteAgentSchema>;
|
|
56
|
+
```
|
|
@@ -14,6 +14,15 @@ export const FlowRun_NodeStateSchema = z.object({
|
|
|
14
14
|
nodeType: z.enum(Flow_Node_Type),
|
|
15
15
|
nodeRef: z.string().min(1),
|
|
16
16
|
status: z.enum(FlowsActors_Status),
|
|
17
|
+
/**
|
|
18
|
+
* When the node took the status it carries, as an ISO instant (#3990): the trigger and a finish when the run reached
|
|
19
|
+
* them, a step when it completed, failed or began waiting, and a waiting step again when its question was answered or
|
|
20
|
+
* the run ended there. What the Agent activity page's flow timeline shows, in the reader's time zone.
|
|
21
|
+
*
|
|
22
|
+
* Optional because a run written before it was recorded carries none; a reader shows such a node without a time
|
|
23
|
+
* rather than inventing one.
|
|
24
|
+
*/
|
|
25
|
+
statusAt: z.iso.datetime().optional(),
|
|
17
26
|
/** What the step produced (a STEP that completed), JSON-safe. */
|
|
18
27
|
output: z.json().optional(),
|
|
19
28
|
/** Why the step failed, in words for the person reading the run (never a stack). */
|
|
@@ -248,6 +248,34 @@ export const HttpApiFieldMappingSchema = z.strictObject({
|
|
|
248
248
|
create: z.string().min(1).optional(),
|
|
249
249
|
update: z.string().min(1).optional(),
|
|
250
250
|
}).optional(),
|
|
251
|
+
/**
|
|
252
|
+
* #3953 — WRITE this field through a LOOKUP (Odoo only): a create or update sends `remoteField` of this object instead
|
|
253
|
+
* of the mapping's own `remoteField`, set to the id of the ONE `lookupEntityRef` record whose `lookupRemoteField`
|
|
254
|
+
* equals the value the resource holds. Reads keep the mapping's own `remoteField`.
|
|
255
|
+
*
|
|
256
|
+
* For a field the system of record shows as a code but stores as a reference to another record. On Odoo a partner's
|
|
257
|
+
* `country_code` is the RELATED `country_id.code`: it reads the ISO code, and a write to it is accepted and discarded
|
|
258
|
+
* (measured on Odoo 19.0). The country is written through `country_id`, a many2one to `res.country`:
|
|
259
|
+
*
|
|
260
|
+
* ```ts
|
|
261
|
+
* { localField: 'country', remoteField: 'country_code',
|
|
262
|
+
* writeThrough: { remoteField: 'country_id', lookupEntityRef: 'res.country', lookupRemoteField: 'code' } }
|
|
263
|
+
* ```
|
|
264
|
+
*
|
|
265
|
+
* Each write with a value looks it up once more (one `search_read` on the lookup model, before anything is sent). The
|
|
266
|
+
* match is EXACT and case-sensitive (`'fr'` names no country whose code is `'FR'`), and Odoo leaves archived records
|
|
267
|
+
* of the lookup model out by default. A value no record matches is refused as the caller's
|
|
268
|
+
* (`SYSTEM_OF_RECORD_WRITE_VALUE_UNRESOLVED`); a value several records match, or a `remoteField` that Odoo does not
|
|
269
|
+
* describe as a many2one to `lookupEntityRef`, is refused as the binding's (`SYSTEM_OF_RECORD_WRITE_LOOKUP_INVALID`).
|
|
270
|
+
* Nothing is sent either way. An empty value (`null` or `''`) unsets the reference (Odoo's `false`). Refused at
|
|
271
|
+
* registration on any other dialect, on a binding that opens neither create nor update, and when the field it writes is
|
|
272
|
+
* another mapping's field or another write-through's.
|
|
273
|
+
*/
|
|
274
|
+
writeThrough: z.strictObject({
|
|
275
|
+
remoteField: z.string().min(1),
|
|
276
|
+
lookupEntityRef: z.string().min(1),
|
|
277
|
+
lookupRemoteField: z.string().min(1),
|
|
278
|
+
}).optional(),
|
|
251
279
|
});
|
|
252
280
|
```
|
|
253
281
|
|
|
@@ -947,6 +975,29 @@ export function assertHttpApiBindingDialectCoherence(binding: HttpApiResourceBin
|
|
|
947
975
|
}
|
|
948
976
|
}
|
|
949
977
|
|
|
978
|
+
// #3953 — a write through a lookup is Odoo's (a code shown, a reference stored), and only a write uses it.
|
|
979
|
+
for (const mapping of binding.fieldMappings) {
|
|
980
|
+
if (mapping.writeThrough === undefined) continue;
|
|
981
|
+
const at = `fieldMappings('${mapping.localField}').writeThrough`;
|
|
982
|
+
if (binding.dialect !== HttpApiTransportDialect.ODOO_JSONRPC && binding.dialect !== HttpApiTransportDialect.ODOO_JSON2) {
|
|
983
|
+
throw new Error(`${at}: declared on a ${binding.dialect} binding. It resolves a value through a lookup on another Odoo model before a write, and only the Odoo dialects compile one.`);
|
|
984
|
+
}
|
|
985
|
+
if (!binding.writableVerbs.includes(HttpApiWriteVerb.CREATE) && !binding.writableVerbs.includes(HttpApiWriteVerb.UPDATE)) {
|
|
986
|
+
throw new Error(`${at}: this binding opens neither create nor update, so nothing would ever be written through it. Remove it, or open the verb.`);
|
|
987
|
+
}
|
|
988
|
+
// Two values for one remote field in one write: whichever is written last would win, silently.
|
|
989
|
+
const target = mapping.writeThrough.remoteField;
|
|
990
|
+
const clash = binding.fieldMappings.find((other) => other !== mapping
|
|
991
|
+
&& (other.remoteField === target || other.writeThrough?.remoteField === target));
|
|
992
|
+
if (clash !== undefined) {
|
|
993
|
+
throw new Error(`${at}: writes '${target}', which fieldMappings('${clash.localField}') also writes. One remote field takes one value per write.`);
|
|
994
|
+
}
|
|
995
|
+
// The population's create values are the engine's (#2552): a create writes them, and the lookup would replace one.
|
|
996
|
+
if (Object.prototype.hasOwnProperty.call(binding.populationFilter?.createValues ?? {}, target)) {
|
|
997
|
+
throw new Error(`${at}: writes '${target}', which the population filter's createValues also writes on every create. One remote field takes one value per write.`);
|
|
998
|
+
}
|
|
999
|
+
}
|
|
1000
|
+
|
|
950
1001
|
// #2552 — the population filter: expressible by this dialect's list, and satisfied by what a create writes.
|
|
951
1002
|
assertHttpApiPopulationFilterCoherence(binding as never);
|
|
952
1003
|
|
|
@@ -58,6 +58,13 @@ export const PROVIDER_CAPABILITY_DISCLOSURES: Readonly<Record<BuiltinProviderCap
|
|
|
58
58
|
carriedBy: 'each signer\'s name and email address, and the document sent for signature, which the vendor holds signed',
|
|
59
59
|
linkableToSubjectByApplication: true,
|
|
60
60
|
},
|
|
61
|
+
// Embedded signing: the signer's name and e-mail again, to open their signing page, and the page the vendor serves in a
|
|
62
|
+
// frame of the application, which reaches the vendor from the signer's browser with the application's origin.
|
|
63
|
+
[BUILTIN_PROVIDER_CAPABILITY.EMBEDDED_ELECTRONIC_SIGNATURE]: {
|
|
64
|
+
categories: [PersonalDataCategory.IDENTITY, PersonalDataCategory.CONTACT_DETAILS],
|
|
65
|
+
carriedBy: 'each signer\'s name and email address, sent again to open their signing page, and the signer\'s browser, which loads that page from the vendor',
|
|
66
|
+
linkableToSubjectByApplication: true,
|
|
67
|
+
},
|
|
61
68
|
[BUILTIN_PROVIDER_CAPABILITY.BILLING]: {
|
|
62
69
|
categories: [PersonalDataCategory.IDENTITY, PersonalDataCategory.CONTACT_DETAILS, PersonalDataCategory.FINANCIAL],
|
|
63
70
|
carriedBy: 'the customer name and email address, and the payment, subscription and invoice records',
|
|
@@ -41,6 +41,17 @@ export const BUILTIN_PROVIDER_CAPABILITY = {
|
|
|
41
41
|
* levels its contract declares. Maps to `EngineCapability.ELECTRONIC_SIGNATURE`.
|
|
42
42
|
*/
|
|
43
43
|
ELECTRONIC_SIGNATURE: 'ELECTRONIC_SIGNATURE',
|
|
44
|
+
/**
|
|
45
|
+
* Provider ALSO lets a signer sign inside the application, in a frame showing the vendor's signing page, instead of
|
|
46
|
+
* from the vendor's e-mail (embedded signing). Maps to `EngineCapability.ELECTRONIC_SIGNATURE`, the slot it shares with
|
|
47
|
+
* {@link ELECTRONIC_SIGNATURE}, and is claimed only beside it.
|
|
48
|
+
*
|
|
49
|
+
* A token of its own because vendors split here: DocuSign, Yousign, BoldSign, SignNow and Adobe Acrobat Sign answer a
|
|
50
|
+
* signing page URL the application can frame; IgniSign, Dropbox Sign and Universign need their own browser script, so
|
|
51
|
+
* their providers sign from the e-mail only. The claim is the provider's statement that its contract declares
|
|
52
|
+
* `embeddedSigning`; the engine refuses at startup a claim with no such declaration.
|
|
53
|
+
*/
|
|
54
|
+
EMBEDDED_ELECTRONIC_SIGNATURE: 'EMBEDDED_ELECTRONIC_SIGNATURE',
|
|
44
55
|
/**
|
|
45
56
|
* Single billing-engagement capability covering everything from
|
|
46
57
|
* Checkout-style hosted flows to first-party PaymentIntent flows.
|
|
@@ -256,6 +256,36 @@ export enum SystemOfRecordErrorCode {
|
|
|
256
256
|
*/
|
|
257
257
|
WRITE_FIELD_NOT_WRITABLE = 'SYSTEM_OF_RECORD_WRITE_FIELD_NOT_WRITABLE',
|
|
258
258
|
|
|
259
|
+
/**
|
|
260
|
+
* REQUEST — a create or update refused, with a CONFIGURATION error type, because the binding maps a field onto a
|
|
261
|
+
* remote field the system of record COMPUTES and does not store, so a
|
|
262
|
+
* write to it would be accepted and discarded (#3953). Odoo answers `true` to a `create` or `write` naming such a field
|
|
263
|
+
* and keeps nothing: measured on Odoo 19.0, `res.partner.country_code` (related to `country_id.code`) written alone
|
|
264
|
+
* read back `false`. Refused before anything is sent, because the alternative is a write reported as done that changed
|
|
265
|
+
* nothing. The context names the field and, when the system of record says so, the field it is computed from
|
|
266
|
+
* (`computedFrom`), which is the one to write.
|
|
267
|
+
*
|
|
268
|
+
* Not the caller's to fix: the binding's mapping is wrong for writes, so it is a configuration error.
|
|
269
|
+
*/
|
|
270
|
+
WRITE_FIELD_COMPUTED_REMOTELY = 'SYSTEM_OF_RECORD_WRITE_FIELD_COMPUTED_REMOTELY',
|
|
271
|
+
|
|
272
|
+
/**
|
|
273
|
+
* REQUEST — a field written through a lookup (`fieldMappings[].writeThrough`, #3953) holds a value no record of the
|
|
274
|
+
* lookup model matches (an ISO country code Odoo does not know, or `'fr'` where the records hold `'FR'`: the match is
|
|
275
|
+
* exact). Refused before anything is sent: writing nothing would report the field as written, and writing a guess
|
|
276
|
+
* would put the row in the wrong place. The context names the field, the lookup model and the value.
|
|
277
|
+
*/
|
|
278
|
+
WRITE_VALUE_UNRESOLVED = 'SYSTEM_OF_RECORD_WRITE_VALUE_UNRESOLVED',
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* REQUEST — a create or update refused, with a CONFIGURATION error type, because a field's write-through lookup
|
|
282
|
+
* (`fieldMappings[].writeThrough`, #3953) cannot name ONE record: the
|
|
283
|
+
* value matches several records of the lookup model (the lookup field does not identify a record), a match carries no
|
|
284
|
+
* integer id, or the field written is not a many2one to the lookup model as the system of record describes it. The
|
|
285
|
+
* binding's fault, not the caller's; nothing is sent. The context names the field, the lookup model and why.
|
|
286
|
+
*/
|
|
287
|
+
WRITE_LOOKUP_INVALID = 'SYSTEM_OF_RECORD_WRITE_LOOKUP_INVALID',
|
|
288
|
+
|
|
259
289
|
/**
|
|
260
290
|
* REQUEST — the write was SENT and nobody knows whether the system of record applied it: the call
|
|
261
291
|
* timed out, the connection dropped after the request left, or a gateway answered for the vendor.
|
|
@@ -25,7 +25,9 @@
|
|
|
25
25
|
* return the passage. A passage found only by the lexical arm carries no `vectorRank`, and every
|
|
26
26
|
* passage in a lexical-only call carries none — which is the expected state when the application
|
|
27
27
|
* configures no embeddings provider, or when text was committed more recently than the background
|
|
28
|
-
* worker has embedded it.
|
|
28
|
+
* worker has embedded it. Such a not-yet-embedded passage is not ranked BELOW embedded ones for that
|
|
29
|
+
* reason alone: when the vector arm ran and could not rank it, its `fusion` counts its lexical rank for
|
|
30
|
+
* both arms, so text written a minute ago competes on its wording from the moment it is committed.
|
|
29
31
|
*
|
|
30
32
|
* @example
|
|
31
33
|
* // Show the strongest passages, and say WHY each was found.
|
|
@@ -42,7 +44,7 @@
|
|
|
42
44
|
export interface RagChunkRetrievalScores {
|
|
43
45
|
/** Reciprocal-rank-fusion score. Ordering key. Not a probability and not comparable across queries. */
|
|
44
46
|
fusion: number;
|
|
45
|
-
/** 1-based rank within the vector arm, absent when that arm did not return this chunk. */
|
|
47
|
+
/** 1-based rank within the vector arm, absent when that arm did not return this chunk (never imputed). */
|
|
46
48
|
vectorRank?: number;
|
|
47
49
|
/** Cosine similarity in `[-1, 1]` (`1 - cosine_distance`). Absent with the rank. */
|
|
48
50
|
vectorSimilarity?: number;
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "framework-topics",
|
|
3
3
|
"metadata": {
|
|
4
|
-
"generatedAt": "2026-11-
|
|
4
|
+
"generatedAt": "2026-11-18T19:00:50.034Z",
|
|
5
5
|
"description": "Topic registry derived from extracted framework-knowledge tags."
|
|
6
6
|
},
|
|
7
7
|
"entries": {
|
|
@@ -792,6 +792,16 @@
|
|
|
792
792
|
"referenceFilePath": "references/example.data-seeding.row-reference.md",
|
|
793
793
|
"sourceReferenceCount": 1
|
|
794
794
|
},
|
|
795
|
+
"example.electronic-signature.engagement-letter-tool": {
|
|
796
|
+
"topicId": "example.electronic-signature.engagement-letter-tool",
|
|
797
|
+
"title": "Example Electronic Signature Engagement Letter Tool",
|
|
798
|
+
"categories": [
|
|
799
|
+
"example",
|
|
800
|
+
"example.electronic-signature"
|
|
801
|
+
],
|
|
802
|
+
"referenceFilePath": "references/example.electronic-signature.engagement-letter-tool.md",
|
|
803
|
+
"sourceReferenceCount": 1
|
|
804
|
+
},
|
|
795
805
|
"example.email.template.minimal": {
|
|
796
806
|
"topicId": "example.email.template.minimal",
|
|
797
807
|
"title": "Example Email Template Minimal",
|
|
@@ -4527,6 +4537,17 @@
|
|
|
4527
4537
|
"referenceFilePath": "references/saas.frontend.domain-module.md",
|
|
4528
4538
|
"sourceReferenceCount": 1
|
|
4529
4539
|
},
|
|
4540
|
+
"saas.frontend.electronic-signatures.embedded-signing-frame": {
|
|
4541
|
+
"topicId": "saas.frontend.electronic-signatures.embedded-signing-frame",
|
|
4542
|
+
"title": "Saas Frontend Electronic Signatures Embedded Signing Frame",
|
|
4543
|
+
"categories": [
|
|
4544
|
+
"saas",
|
|
4545
|
+
"saas.frontend",
|
|
4546
|
+
"saas.frontend.electronic-signatures"
|
|
4547
|
+
],
|
|
4548
|
+
"referenceFilePath": "references/saas.frontend.electronic-signatures.embedded-signing-frame.md",
|
|
4549
|
+
"sourceReferenceCount": 1
|
|
4550
|
+
},
|
|
4530
4551
|
"saas.frontend.embedded-resource-descent": {
|
|
4531
4552
|
"topicId": "saas.frontend.embedded-resource-descent",
|
|
4532
4553
|
"title": "Saas Frontend Embedded Resource Descent",
|
|
@@ -5743,6 +5764,17 @@
|
|
|
5743
5764
|
"referenceFilePath": "references/saas.models.flows-actors.human-input-form.md",
|
|
5744
5765
|
"sourceReferenceCount": 1
|
|
5745
5766
|
},
|
|
5767
|
+
"saas.models.flows-actors.mcp-server-declaration": {
|
|
5768
|
+
"topicId": "saas.models.flows-actors.mcp-server-declaration",
|
|
5769
|
+
"title": "Saas Models Flows Actors Mcp Server Declaration",
|
|
5770
|
+
"categories": [
|
|
5771
|
+
"saas",
|
|
5772
|
+
"saas.models",
|
|
5773
|
+
"saas.models.flows-actors"
|
|
5774
|
+
],
|
|
5775
|
+
"referenceFilePath": "references/saas.models.flows-actors.mcp-server-declaration.md",
|
|
5776
|
+
"sourceReferenceCount": 1
|
|
5777
|
+
},
|
|
5746
5778
|
"saas.models.flows-actors.operation-approval-pending": {
|
|
5747
5779
|
"topicId": "saas.models.flows-actors.operation-approval-pending",
|
|
5748
5780
|
"title": "Saas Models Flows Actors Operation Approval Pending",
|
|
@@ -5765,6 +5797,28 @@
|
|
|
5765
5797
|
"referenceFilePath": "references/saas.models.flows-actors.operation-approval-requirement.md",
|
|
5766
5798
|
"sourceReferenceCount": 1
|
|
5767
5799
|
},
|
|
5800
|
+
"saas.models.flows-actors.outbound-credential": {
|
|
5801
|
+
"topicId": "saas.models.flows-actors.outbound-credential",
|
|
5802
|
+
"title": "Saas Models Flows Actors Outbound Credential",
|
|
5803
|
+
"categories": [
|
|
5804
|
+
"saas",
|
|
5805
|
+
"saas.models",
|
|
5806
|
+
"saas.models.flows-actors"
|
|
5807
|
+
],
|
|
5808
|
+
"referenceFilePath": "references/saas.models.flows-actors.outbound-credential.md",
|
|
5809
|
+
"sourceReferenceCount": 1
|
|
5810
|
+
},
|
|
5811
|
+
"saas.models.flows-actors.remote-agent-declaration": {
|
|
5812
|
+
"topicId": "saas.models.flows-actors.remote-agent-declaration",
|
|
5813
|
+
"title": "Saas Models Flows Actors Remote Agent Declaration",
|
|
5814
|
+
"categories": [
|
|
5815
|
+
"saas",
|
|
5816
|
+
"saas.models",
|
|
5817
|
+
"saas.models.flows-actors"
|
|
5818
|
+
],
|
|
5819
|
+
"referenceFilePath": "references/saas.models.flows-actors.remote-agent-declaration.md",
|
|
5820
|
+
"sourceReferenceCount": 1
|
|
5821
|
+
},
|
|
5768
5822
|
"saas.models.flows-actors.review-calendar": {
|
|
5769
5823
|
"topicId": "saas.models.flows-actors.review-calendar",
|
|
5770
5824
|
"title": "Saas Models Flows Actors Review Calendar",
|