@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/flows-actors/models/function-tools.backend.definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"function-tools.backend.definitions.js","sourceRoot":"","sources":["../../../../../src/flows-actors/models/function-tools.backend.definitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAA2D,MAAM,uBAAuB,CAAC;AAEvH,OAAO,EAAE,wBAAwB,EAAE,MAAM,wGAAwG,CAAC;AA+GlJ,4FAA4F;AAC5F,SAAS,YAAY,CAAC,MAAe,EAAE,KAAa;IAClD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;IAC5E,CAAC;IACD,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,MAAM,IAAI,KAAK,CAAC,OAAO,CAAE,MAA8B,CAAC,IAAI,CAAC,EAAE,CAAC;QACpH,MAAM,KAAK,GAAG,MAAmD,CAAC;QAClE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;IAClH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,YAA0B,EAC1B,OAAkG;IAElG,0EAA0E;IAC1E,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,EAAE,CAAC;IACjD,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,GAAG,CAAC;IAE1C,OAAO;QACL,WAAW,EAAE,OAAO,EAAE,WAAW,IAAI,YAAY,YAAY,OAAO;QACpE,WAAW,EACT,OAAO,EAAE,WAAW;YACpB,+BAA+B,YAAY,kDAAkD;gBAC7F,uHAAuH;QACzH,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE;SACxD,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,IAA8C,EAAE,GAAiC,EAAmC,EAAE;YACpI,MAAM,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,GAAG,GAAG,CAAC,QAAQ,CAAC;YAC7F,MAAM,KAAK,GAAG,OAAO,IAAI,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;YAC9F,MAAM,WAAW,GAAG,OAAO,IAAI,EAAE,WAAW,KAAK,QAAQ,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;YACtI,MAAM,UAAU,GAA2B,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAE5G,4EAA4E;YAC5E,+DAA+D;YAC/D,IAAI,WAAW,EAAE,CAAC;gBAChB,0FAA0F;gBAC1F,6FAA6F;gBAC7F,0FAA0F;gBAC1F,4FAA4F;gBAC5F,uFAAuF;gBACvF,IAAI,QAAoE,CAAC;gBACzE,IAAI,YAAqB,CAAC;gBAC1B,IAAI,CAAC;oBACH,QAAQ,GAAG,iBAAiB,CAAC,oBAAoB,CAC/C,iBAAiB,CAAC,8BAA8B,CAAC,YAAY,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAC7F,CAAC;oBACF,MAAM,QAAQ,GAAG,MAAM,uBAAuB,CAAC,0BAA0B,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;oBAC1G,YAAY,GAAG,MAAM,uBAAuB,CAAC,MAAM,CAAC,YAAY,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;gBAC3F,CAAC;gBAAC,MAAM,CAAC;oBACP,QAAQ,GAAG,SAAS,CAAC,CAAC,qFAAqF;gBAC7G,CAAC;gBACD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,uFAAuF;oBACvF,kFAAkF;oBAClF,MAAM,gBAAgB,GAAG,MAAM,wBAAwB,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;oBAChF,OAAO,YAAY,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;gBAC/C,CAAC;YACH,CAAC;YAED,MAAM,MAAM,GAAG,iBAAiB,CAAC,oBAAoB,CACnD,iBAAiB,CAAC,8BAA8B,CAAC,YAAY,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAC3F,CAAC;YACF,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAAC,0BAA0B,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;YACtG,6FAA6F;YAC7F,0FAA0F;YAC1F,kDAAkD;YAClD,MAAM,UAAU,GAAG,MAAM,uBAAuB,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAChI,MAAM,cAAc,GAAG,MAAM,wBAAwB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAC1E,OAAO,YAAY,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,iBAAiB,CAC/B,YAA0B,EAC1B,EAA+D,EAC/D,OAcC;IAED,2EAA2E;IAC3E,OAAO;QACL,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,YAAY,YAAY,IAAI,EAAE,EAAE;QACpE,qBAAqB,EAAE,OAAO,CAAC,qBAAqB;QACpD,WAAW,EACT,OAAO,CAAC,WAAW;YACnB,CAAC,EAAE,KAAK,qBAAqB,CAAC,MAAM;gBAClC,CAAC,CAAC,iBAAiB,YAAY,yLAAyL;gBACxN,CAAC,CAAC,uBAAuB,YAAY,sFAAsF,CAAC;QAChI,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,OAAO,EAAE,KAAK,EAAE,IAA6B,EAAE,GAAiC,EAAoB,EAAE;YACpG,MAAM,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,GAAG,GAAG,CAAC,QAAQ,CAAC;YAC7F,MAAM,UAAU,GAA2B,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAE5G,6EAA6E;YAC7E,8EAA8E;YAC9E,gFAAgF;YAChF,MAAM,SAAS,GAAG,iBAAiB,CAAC,oBAAoB,CACtD,iBAAiB,CAAC,8BAA8B,CAAC,YAAY,EAAE,EAAE,CAAC,CACnE,CAAC;YACF,MAAM,EAAE,GAAG,MAAM,uBAAuB,CAAC,0BAA0B,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;YAErG,IAAI,EAAE,KAAK,qBAAqB,CAAC,MAAM,EAAE,CAAC;gBACxC,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;gBAC7E,0FAA0F;gBAC1F,8FAA8F;gBAC9F,OAAO,wBAAwB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACtD,CAAC;YAED,iFAAiF;YACjF,MAAM,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,GAAG,IAAuB,CAAC;YACjD,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9C,MAAM,IAAI,KAAK,CACb,qBAAqB,YAAY,kFAAkF,CACpH,CAAC;YACJ,CAAC;YACD,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;YAClF,OAAO,wBAAwB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACtD,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { z } from 'zod';\nimport { CoreResourceOperation, type ResourceType, type ResourceConfiguration_Operation } from '@wildo-ai/saas-models';\n\nimport { toResponseSafeToolOutput } from '~wildo-backend-lib/base-classes/services/controllers/utils/operation-response-serializer.backend.utils';\nimport type { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport type { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';\nimport type { SocketAuthResult } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\n\n/**\n * Function-Tool Contract (backend)\n * ================================\n *\n * An executable tool an AI agent can call during an invocation (the runtime\n * behind an agent's declarative `capabilities.tools.functionRefs`). Unlike the\n * shared agent/system schemas, a `FunctionTool` carries backend execution logic,\n * so it lives in `saas-backend-lib`, not `saas-models`.\n *\n * Tools are registered per-application through\n * `BackendDomainModule.flowsActors.functionTools`, indexed by `functionRef` in\n * the `FlowsActorsRegistryService`, and resolved + wired into the AI-SDK `tools`\n * parameter by `AgentsBackendService` when a streaming invocation runs. The\n * engine supplies the execution *context* (caller identity + backend services)\n * at call time; the tool itself stays a pure, reusable declaration.\n */\n\n/** Backend services a tool may use at execution time (supplied by the caller). */\nexport interface FunctionToolExecutionServices {\n  resourcesRegistry: ResourcesRegistryBackendService;\n  servicesRegistryHandler: ServicesRegistryHandlerBackendService;\n  executionContextCreator: ExecutionContextCreatorBackendService;\n}\n\n/**\n * @wildo_source:part:start saas.backend.flows-actors.function-tool facet:layer:backend facet:family:flows-actors\n *\n * Execution context threaded into every tool call. Carries the CALLER's verified\n * identity (`auth`) so a tool reads/writes as the user with the user's own\n * visibility — never trusting LLM-supplied identity — plus the backend services\n * the tool may use. The engine supplies this at call time; a tool never fabricates\n * identity from the model's arguments.\n *\n * Import path: `@wildo-ai/saas-backend-lib`.\n */\nexport interface FunctionToolExecutionContext {\n  /** The authenticated caller (server-verified identity + roles). */\n  auth: SocketAuthResult;\n  /** Active organization scope for the call, when applicable. */\n  organizationId?: string;\n  /** Backend services the tool may use. */\n  services: FunctionToolExecutionServices;\n}\n\n/**\n * A single agent-callable tool (grounding / action an agent can invoke).\n *\n * Register instances on a backend module's `flowsActors.functionTools`; reference\n * one from an agent's `capabilities.tools.functionRefs` by its `functionRef`. The\n * engine resolves each declared ref into an AI-SDK tool at invocation time and\n * calls `execute(args, context)` with the caller's {@link FunctionToolExecutionContext}\n * (so the tool acts as the user, with the user's own visibility). For reading a\n * resource, prefer the `resourceReadTool(resourceType)` factory over a hand-written\n * tool. Import path: `@wildo-ai/saas-backend-lib`.\n *\n * @example\n *   // a custom tool\n *   const echoTool: FunctionTool = {\n *     functionRef: 'demo.echo',\n *     description: 'Echo the provided text back.',\n *     inputSchema: z.object({ text: z.string() }),\n *     execute: async (args) => ({ echoed: args.text }),\n *   };\n */\nexport interface FunctionTool {\n  /** Stable id referenced from `agent.capabilities.tools.functionRefs`. */\n  functionRef: string;\n  /** Natural-language description shown to the model (what the tool does + when). */\n  description: string;\n  /** Zod schema of the tool's arguments (surfaced to the model). */\n  inputSchema: z.ZodTypeAny;\n  /** Execute the tool with validated args under the caller's context. */\n  execute: (args: any, context: FunctionToolExecutionContext) => Promise<unknown>;\n  /**\n   * Require a HUMAN decision before this tool runs (human-in-the-loop).\n   *\n   * When set, a turn that reaches this tool SUSPENDS instead of executing it: the run state is\n   * persisted, the execution moves to `AWAITING_APPROVAL`, and the caller is asked to approve or\n   * deny. Approving resumes the turn and runs the tool; denying resumes it and tells the model the\n   * call was refused, so the agent can respond rather than silently stalling.\n   *\n   * Declare it on tools whose effect a person should authorise — sending money, emailing a\n   * customer, deleting at scale — not on reads.\n   *\n   * ⚠️ Two things worth knowing before you set this:\n   *\n   * 1. **It requires a configured approval secret.** Approval decisions are HMAC-signed so a client\n   *    cannot forge one. A turn that would expose an approval-gated tool with no secret configured\n   *    REFUSES TO RUN rather than falling back to unsigned approvals — the tools someone bothered to\n   *    gate are exactly the ones where a forged approval matters most.\n   * 2. **This is Wildo's declaration, not the model SDK's.** The engine translates it into the\n   *    SDK's call-level approval configuration. Do not reach for the SDK's own tool-level\n   *    `needsApproval`: it is deprecated, and approval is handled at the call level now.\n   */\n  requiresHumanApproval?: boolean;\n}\n/** @wildo_source:part:end saas.backend.flows-actors.function-tool */\n\n/** Uniform, model-facing result shape for read tools. */\ninterface ResourceReadToolResult {\n  data: unknown[];\n  pagination?: unknown;\n  truncated?: boolean;\n}\n\n/** Normalize a handler list/search result (array or paginated) to the tool result shape. */\nfunction toReadResult(result: unknown, limit: number): ResourceReadToolResult {\n  if (Array.isArray(result)) {\n    return { data: result.slice(0, limit), truncated: result.length > limit };\n  }\n  if (result && typeof result === 'object' && 'data' in result && Array.isArray((result as { data: unknown[] }).data)) {\n    const paged = result as { data: unknown[]; pagination?: unknown };\n    return { data: paged.data.slice(0, limit), pagination: paged.pagination, truncated: paged.data.length > limit };\n  }\n  return { data: [] };\n}\n\n/**\n * @wildo_source:part:start saas.backend.flows-actors.resource-read-tool facet:layer:backend facet:family:flows-actors\n *\n * Generic resource-read tool factory. Produces a {@link FunctionTool} that lets\n * an agent look up records of ONE resource type **scoped to the calling user**,\n * with that user's own visibility — no `systemAccessPolicy` bypass. Instantiate\n * it per resource an agent should be able to read (e.g. `resourceReadTool(TODOS)`),\n * making any registered resource agent-readable without hand-writing a tool.\n *\n * The tool reads through the normal service path under a user `ExecutionContext`\n * rebuilt from the caller's socket auth, so the framework's contextual filter +\n * role ACL apply exactly as for the user's own request. Identity is NEVER taken\n * from the model — only the `searchQuery` / `limit` args are. Its `functionRef`\n * defaults to `resource.<resourceType>.read` — reference that exact string from\n * your agent's `capabilities.tools.functionRefs`. Import path:\n * `@wildo-ai/saas-backend-lib`.\n *\n * @param resourceType  the resource to expose (any registered `ResourceType`).\n * @param options       optional `functionRef` / `description` / `defaultLimit` / `maxLimit` overrides.\n * @example\n *   // in a backend module's `flowsActors.functionTools` contribution:\n *   functionTools: [resourceReadTool(TasksManager_ResourceType.TODOS)]\n *   // and on the agent:\n *   capabilities: { tools: { functionRefs: ['resource.todos.read'], mcpRefs: [] } }\n */\nexport function resourceReadTool(\n  resourceType: ResourceType,\n  options?: { functionRef?: string; description?: string; defaultLimit?: number; maxLimit?: number },\n): FunctionTool {\n  /** @wildo_source:part:end saas.backend.flows-actors.resource-read-tool */\n  const defaultLimit = options?.defaultLimit ?? 50;\n  const maxLimit = options?.maxLimit ?? 100;\n\n  return {\n    functionRef: options?.functionRef ?? `resource.${resourceType}.read`,\n    description:\n      options?.description ??\n      `Look up the current user's \"${resourceType}\" records to answer their questions about them. ` +\n      `Optionally pass a free-text searchQuery to narrow the results. Only the current user's own records are ever returned.`,\n    inputSchema: z.object({\n      searchQuery: z.string().optional(),\n      limit: z.number().int().min(1).max(maxLimit).optional(),\n    }),\n    execute: async (args: { searchQuery?: string; limit?: number }, ctx: FunctionToolExecutionContext): Promise<ResourceReadToolResult> => {\n      const { resourcesRegistry, servicesRegistryHandler, executionContextCreator } = ctx.services;\n      const limit = typeof args?.limit === 'number' ? Math.min(args.limit, maxLimit) : defaultLimit;\n      const searchQuery = typeof args?.searchQuery === 'string' && args.searchQuery.trim().length > 0 ? args.searchQuery.trim() : undefined;\n      const contextIds: Record<string, string> = ctx.organizationId ? { organizationId: ctx.organizationId } : {};\n\n      // Prefer SEARCH when a query is supplied AND the resource supports it; fall\n      // back to a scoped LIST. Both run as the user (no ACL bypass).\n      if (searchQuery) {\n        // The fallback catch covers ONLY op-resolution + the search call — a resource may have no\n        // SEARCH operation, in which case we degrade to a scoped LIST. It deliberately does NOT wrap\n        // the response-DTO projection below: a projection failure there is a real server contract\n        // violation (a record that violates its own response DTO) and must surface as a tool error,\n        // exactly as it would on the LIST path — never silently degrade to an unfiltered LIST.\n        let searchOp: ResourceConfiguration_Operation<any, any, any> | undefined;\n        let searchResult: unknown;\n        try {\n          searchOp = resourcesRegistry.getOperationFromPath(\n            resourcesRegistry.getServiceOperationPathDefault(resourceType, CoreResourceOperation.SEARCH),\n          );\n          const searchEc = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, searchOp, contextIds);\n          searchResult = await servicesRegistryHandler.search(resourceType, searchEc, searchQuery);\n        } catch {\n          searchOp = undefined; // Resource has no SEARCH operation (or it failed to resolve) — fall through to LIST.\n        }\n        if (searchOp !== undefined) {\n          // Project through the SEARCH operation's response DTO + JSON wire step, exactly as the\n          // REST controller does, so no `Date`/backend-only/secret field reaches the model.\n          const safeSearchResult = await toResponseSafeToolOutput(searchOp, searchResult);\n          return toReadResult(safeSearchResult, limit);\n        }\n      }\n\n      const listOp = resourcesRegistry.getOperationFromPath(\n        resourcesRegistry.getServiceOperationPathDefault(resourceType, CoreResourceOperation.LIST),\n      );\n      const listEc = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, listOp, contextIds);\n      // `paginated: true` yields the `{ data, pagination }` envelope the LIST response DTO expects\n      // (the same shape the HTTP controller requests) — a bare array would fail the wrapper-DTO\n      // projection in `toResponseSafeToolOutput` below.\n      const listResult = await servicesRegistryHandler.list(resourceType, listEc, undefined, { page: 1, limit }, { paginated: true });\n      const safeListResult = await toResponseSafeToolOutput(listOp, listResult);\n      return toReadResult(safeListResult, limit);\n    },\n  };\n}\n\n/**\n * @wildo_source:part:start saas.backend.flows-actors.resource-write-tool facet:layer:backend facet:family:flows-actors\n *\n * Generic resource-WRITE tool factory. The mutating sibling of {@link resourceReadTool}.\n * Produces a {@link FunctionTool} that lets an agent CREATE or UPDATE ONE resource\n * type **as the calling user**, under the caller's own `ExecutionContext` rebuilt\n * from their verified socket auth — no `systemAccessPolicy` bypass, and identity is\n * NEVER taken from the model. The resource's own CREATE / UPDATE `accessControl`\n * (roles + parent scope) is enforced by the service tier exactly as for the user's\n * own HTTP request, so authorization is **fail-closed**: a caller lacking the\n * operation's role gets a thrown authz error, not a silent write. Owner FKs and\n * other server-set fields are EC-injected / `excludeFromCreate`, so the model can\n * never spoof ownership through the tool arguments.\n *\n * Unlike the read tool (whose args are a fixed `{ searchQuery, limit }`), a write\n * tool's arguments are resource-specific, so the caller MUST supply the model-facing\n * `inputSchema` — the create/update field contract shown to the model. Keep it to the\n * fields the model should legitimately set. For `UPDATE`, include the record `id` in\n * the schema; the factory splits `id` out to address the row and passes the remaining\n * fields as the patch.\n *\n * `functionRef` defaults to `resource.<resourceType>.<op>` (e.g. `resource.todos.create`)\n * — reference that exact string from your agent's `capabilities.tools.functionRefs`.\n * Import path: `@wildo-ai/saas-backend-lib`.\n *\n * @param resourceType  the resource to expose (any registered `ResourceType`).\n * @param op            `CoreResourceOperation.CREATE` or `CoreResourceOperation.UPDATE`.\n * @param options       `{ inputSchema, functionRef?, description? }` — `inputSchema` is REQUIRED (the model-facing argument contract).\n * @example\n *   // in a backend module's `flowsActors.functionTools` contribution:\n *   functionTools: [\n *     resourceWriteTool(TasksManager_ResourceType.TODOS, CoreResourceOperation.CREATE, {\n *       inputSchema: z.object({ title: z.string(), todoListId: z.string(), description: z.string().optional() }),\n *     }),\n *   ]\n *   // and on the agent:\n *   capabilities: { tools: { functionRefs: ['resource.todos.create'], mcpRefs: [] } }\n */\nexport function resourceWriteTool(\n  resourceType: ResourceType,\n  op: CoreResourceOperation.CREATE | CoreResourceOperation.UPDATE,\n  options: {\n    inputSchema: z.ZodTypeAny;\n    functionRef?: string;\n    description?: string;\n    /**\n     * Gate this write behind a HUMAN decision (see {@link FunctionTool.requiresHumanApproval}).\n     *\n     * Without this passthrough the flag was declarable only by hand-rolling a `FunctionTool`, so\n     * the approval gate was unreachable from the factory every app author actually uses — a\n     * capability present in the contract and absent from the authoring surface. Reads are not\n     * offered the option: approval exists to gate EFFECTS, and gating a read teaches authors to\n     * approve things reflexively, which is how an approval prompt stops being read.\n     */\n    requiresHumanApproval?: boolean;\n  },\n): FunctionTool {\n  /** @wildo_source:part:end saas.backend.flows-actors.resource-write-tool */\n  return {\n    functionRef: options.functionRef ?? `resource.${resourceType}.${op}`,\n    requiresHumanApproval: options.requiresHumanApproval,\n    description:\n      options.description ??\n      (op === CoreResourceOperation.CREATE\n        ? `Create a new \"${resourceType}\" record on behalf of the current user from the provided fields. The record is owned by and scoped to the current user; ownership fields are set by the system, not from the arguments.`\n        : `Update an existing \"${resourceType}\" record the current user owns. Pass the record \"id\" plus only the fields to change.`),\n    inputSchema: options.inputSchema,\n    execute: async (args: Record<string, unknown>, ctx: FunctionToolExecutionContext): Promise<unknown> => {\n      const { resourcesRegistry, servicesRegistryHandler, executionContextCreator } = ctx.services;\n      const contextIds: Record<string, string> = ctx.organizationId ? { organizationId: ctx.organizationId } : {};\n\n      // Rebuild a scoped ExecutionContext from the CALLER's verified auth for this\n      // operation. The service tier then enforces the op's role + scope ACL against\n      // this EC (fail-closed) — the write runs as the user, never with an ACL bypass.\n      const operation = resourcesRegistry.getOperationFromPath(\n        resourcesRegistry.getServiceOperationPathDefault(resourceType, op),\n      );\n      const ec = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, operation, contextIds);\n\n      if (op === CoreResourceOperation.CREATE) {\n        const created = await servicesRegistryHandler.create(resourceType, ec, args);\n        // Return the same JSON-safe, response-DTO-projected record the REST endpoint would, so no\n        // `Date`/backend-only/secret reaches the model and the tool-loop CONTINUATION step validates.\n        return toResponseSafeToolOutput(operation, created);\n      }\n\n      // UPDATE: the record \"id\" addresses the row; the remaining fields are the patch.\n      const { id, ...patch } = args as { id?: string };\n      if (typeof id !== 'string' || id.length === 0) {\n        throw new Error(\n          `resourceWriteTool(${resourceType}, update): the \"id\" argument is required — declare it in the tool's inputSchema.`,\n        );\n      }\n      const updated = await servicesRegistryHandler.update(resourceType, ec, id, patch);\n      return toResponseSafeToolOutput(operation, updated);\n    },\n  };\n}\n"]}
+{"version":3,"file":"function-tools.backend.definitions.js","sourceRoot":"","sources":["../../../../src/flows-actors/models/function-tools.backend.definitions.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport {\n  CoreResourceOperation,\n  ErrorType,\n  ResourceOperationVariantType,\n  ResourcesConfig_OperationPathUtils,\n  isWildoBackendError,\n  type ResourceType,\n  type ResourceConfiguration_Operation,\n  type ResourceConfiguration_OperationPath,\n} from '@wildo-ai/saas-models';\n\nimport { toResponseSafeToolOutput } from '~wildo-backend-lib/base-classes/services/controllers/utils/operation-response-serializer.backend.utils';\nimport { resolveDeclaredPolicySubjectKey } from '~wildo-backend-lib/security/authentications/services/utils/external-turn-rate-limit.backend.utils';\nimport type { AuthorizationsBackendService } from '~wildo-backend-lib/security/authorizations/services/authorizations.backend.service';\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport type { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';\nimport type { RateLimitBackendService } from '~wildo-backend-lib/errors/services/rate-limit.backend.service';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport type { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';\nimport type { SocketAuthResult } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\n\n/**\n * Function-Tool Contract (backend)\n * ================================\n *\n * An executable tool an AI agent can call during an invocation (the runtime\n * behind an agent's declarative `capabilities.tools.functionRefs`). Unlike the\n * shared agent/system schemas, a `FunctionTool` carries backend execution logic,\n * so it lives in `saas-backend-lib`, not `saas-models`.\n *\n * Tools are registered per-application through\n * `BackendDomainModule.flowsActors.functionTools`, indexed by `functionRef` in\n * the `FlowsActorsRegistryService`, and resolved + wired into the AI-SDK `tools`\n * parameter by `AgentsBackendService` when a streaming invocation runs. The\n * engine supplies the execution *context* (caller identity + backend services)\n * at call time; the tool itself stays a pure, reusable declaration.\n */\n\n/**\n * @wildo_source:part:start saas.backend.flows-actors.tool-dispatch-obligations facet:layer:backend facet:audience:app-developer\n *\n * Backend services a tool may use at execution time (supplied by the caller).\n *\n * ⚠️ **If your tool DISPATCHES a resource operation, call `dispatchResourceOperationAsTool` — do not\n * reach for these services yourself.**\n *\n * A tool enters at the SERVICE tier, bypassing Express, so two gates that live on the HTTP\n * controller never run for it: the operation's declared `roles` ACL and its authored `rateLimit?`.\n * `dispatchResourceOperationAsTool` resolves the operation, builds the scoped execution context,\n * applies both gates in the right order and dispatches — one exported call, and the same one\n * `resourceReadTool` and `resourceWriteTool` use.\n *\n * ```ts\n * const rows = await dispatchResourceOperationAsTool({\n *   ctx, resourceType: 'todos', operationIdentifier: CoreResourceOperation.LIST,\n *   data: { filter: undefined, page: 1, limit: 20 }, options: { paginated: true },\n * });\n * ```\n *\n * **This prose used to name two calls a hand-written tool owed, and both were module-private (#556)\n * — so an author who read it and agreed could not discharge the obligation.** Naming ONE importable\n * call replaces that: the correct path is now also the shortest, which is the only mechanism that\n * survives an author who has not read this paragraph.\n *\n * Skipping the gates means a caller whose roles the operation REFUSES, but whose tenancy admits the\n * row, succeeds — the operation's `accessControl` simply unenforced on this plane. It is quiet:\n * tenancy still applies, so the tool returns the caller's own tenant's rows and LOOKS like it works.\n * That is right for a framework-internal caller and wrong here, where the caller is an external\n * principal naming an operation on their own authority.\n *\n * The services below remain on this interface because the seam is built from them, and because a\n * tool that dispatches NOTHING — a calculator, a formatter, a unit converter — is a legitimate shape\n * that needs neither gate.\n *\n * What you still get for free, on every tool: the repository's contextual filter in full — tenancy,\n * relationship narrowing, organization-unit narrowing, the anonymous guard and the retention hide,\n * all fail-closed — plus the whole operation pipeline of validation, enabled conditions, custom\n * implementation and hooks.\n */\nexport interface FunctionToolExecutionServices {\n  resourcesRegistry: ResourcesRegistryBackendService;\n  servicesRegistryHandler: ServicesRegistryHandlerBackendService;\n  executionContextCreator: ExecutionContextCreatorBackendService;\n  /**\n   * Enforces an operation's OWN authored `rateLimit?` policy on this plane.\n   *\n   * Present because a tool DISPATCHES A RESOURCE OPERATION while bypassing Express, so the\n   * declared policy's only other consumer — the HTTP controller pre-flight — never runs. A\n   * hand-written {@link FunctionTool} that dispatches an operation itself owes the same charge —\n   * call `checkPolicyForSubject(...)` on THIS service. (The factories below wrap it in the\n   * module-private `assertDeclaredOperationRateLimit`, which is not importable from outside this\n   * file; the service on this interface is the reachable path.)\n   */\n  rateLimitService: RateLimitBackendService;\n  /**\n   * Applies the dispatched operation's own declared `roles` ACL.\n   *\n   * Present because a tool enters at the SERVICE tier, and **the role gate is a CONTROLLER-tier\n   * gate** — `ServicesRegistryHandlerBackendService`'s verbs apply the repository's contextual\n   * filter and the whole operation pipeline, and deliberately apply no role check, because their\n   * dominant population is the authentication reads that run before a role-bearing principal\n   * exists. That is right for a framework-internal caller and wrong for this plane, whose caller is\n   * an external principal (an A2A agent, or a user's own WebSocket) naming an operation on their\n   * own authority. Without this the operation's `accessControl` was simply unenforced here: a\n   * caller whose roles the operation refuses, but whose tenancy admits the row, succeeded.\n   *\n   * A hand-written {@link FunctionTool} that dispatches a resource operation owes the same call —\n   * `authorizeInController(idOrIds, executionContext)` on THIS service. (The factories below wrap it\n   * in the module-private `authorizeToolDispatch`, which is not importable from outside this file.)\n   */\n  authorizer: AuthorizationsBackendService;\n}\n/** @wildo_source:part:end saas.backend.flows-actors.tool-dispatch-obligations */\n\n/**\n * @wildo_source:part:start saas.backend.flows-actors.function-tool facet:layer:backend facet:family:flows-actors\n *\n * Execution context threaded into every tool call. Carries the CALLER's verified\n * identity (`auth`) so a tool reads/writes as the user with the user's own\n * visibility — never trusting LLM-supplied identity — plus the backend services\n * the tool may use. The engine supplies this at call time; a tool never fabricates\n * identity from the model's arguments.\n *\n * Import path: `@wildo-ai/saas-backend-lib`.\n */\nexport interface FunctionToolExecutionContext {\n  /** The authenticated caller (server-verified identity + roles). */\n  auth: SocketAuthResult;\n  /** Active organization scope for the call, when applicable. */\n  organizationId?: string;\n  /** Backend services the tool may use. */\n  services: FunctionToolExecutionServices;\n}\n\n/**\n * A single agent-callable tool (grounding / action an agent can invoke).\n *\n * Register instances on a backend module's `flowsActors.functionTools`; reference\n * one from an agent's `capabilities.tools.functionRefs` by its `functionRef`. The\n * engine resolves each declared ref into an AI-SDK tool at invocation time and\n * calls `execute(args, context)` with the caller's {@link FunctionToolExecutionContext}\n * (so the tool acts as the user, with the user's own visibility). For reading a\n * resource, prefer the `resourceReadTool(resourceType)` factory over a hand-written\n * tool. Import path: `@wildo-ai/saas-backend-lib`.\n *\n * @example\n *   // a custom tool\n *   const echoTool: FunctionTool = {\n *     functionRef: 'demo.echo',\n *     description: 'Echo the provided text back.',\n *     inputSchema: z.object({ text: z.string() }),\n *     execute: async (args) => ({ echoed: args.text }),\n *   };\n */\nexport interface FunctionTool {\n  /** Stable id referenced from `agent.capabilities.tools.functionRefs`. */\n  functionRef: string;\n  /** Natural-language description shown to the model (what the tool does + when). */\n  description: string;\n  /** Zod schema of the tool's arguments (surfaced to the model). */\n  inputSchema: z.ZodTypeAny;\n  /** Execute the tool with validated args under the caller's context. */\n  execute: (args: any, context: FunctionToolExecutionContext) => Promise<unknown>;\n  /**\n   * Require a HUMAN decision before this tool runs (human-in-the-loop).\n   *\n   * When set, a turn that reaches this tool SUSPENDS instead of executing it: the run state is\n   * persisted, the execution moves to `AWAITING_APPROVAL`, and the caller is asked to approve or\n   * deny. Approving resumes the turn and runs the tool; denying resumes it and tells the model the\n   * call was refused, so the agent can respond rather than silently stalling.\n   *\n   * Declare it on tools whose effect a person should authorise — sending money, emailing a\n   * customer, deleting at scale — not on reads.\n   *\n   * ⚠️ Two things worth knowing before you set this:\n   *\n   * 1. **It requires a configured approval secret.** Approval decisions are HMAC-signed so a client\n   *    cannot forge one. A turn that would expose an approval-gated tool with no secret configured\n   *    REFUSES TO RUN rather than falling back to unsigned approvals — the tools someone bothered to\n   *    gate are exactly the ones where a forged approval matters most.\n   * 2. **This is Wildo's declaration, not the model SDK's.** The engine translates it into the\n   *    SDK's call-level approval configuration. Do not reach for the SDK's own tool-level\n   *    `needsApproval`: it is deprecated, and approval is handled at the call level now.\n   */\n  requiresHumanApproval?: boolean;\n}\n/** @wildo_source:part:end saas.backend.flows-actors.function-tool */\n\n/**\n * The name a `functionRef` is exposed to the model under.\n *\n * Provider tool names must be identifier-safe and a `functionRef` uses dots, so the two differ for\n * every tool. ONE definition, because the mapping is used in opposite directions by two sites: the\n * turn BUILDS the tool set from refs, and a resume that re-signs a modified approval must find the\n * FunctionTool behind a name it reads back out of the model SDK's own message array. A second copy\n * of this expression would make an approval unmodifiable for exactly the refs the two spelled\n * differently.\n *\n * Not injective by construction (`a.b` and `a_b` collapse), and deliberately not made so: the\n * forward direction is what the model sees, and a reverse lookup resolves against ONE agent's\n * declared refs, where a collision would already be an authoring defect.\n */\nexport function modelToolNameForFunctionRef(functionRef: string): string {\n  return functionRef.replace(/[^a-zA-Z0-9_-]/g, '_');\n}\n\n/** Uniform, model-facing result shape for read tools. */\ninterface ResourceReadToolResult {\n  data: unknown[];\n  pagination?: unknown;\n  truncated?: boolean;\n}\n\n/** Normalize a handler list/search result (array or paginated) to the tool result shape. */\nfunction toReadResult(result: unknown, limit: number): ResourceReadToolResult {\n  if (Array.isArray(result)) {\n    return { data: result.slice(0, limit), truncated: result.length > limit };\n  }\n  if (result && typeof result === 'object' && 'data' in result && Array.isArray((result as { data: unknown[] }).data)) {\n    const paged = result as { data: unknown[]; pagination?: unknown };\n    return { data: paged.data.slice(0, limit), pagination: paged.pagination, truncated: paged.data.length > limit };\n  }\n  return { data: [] };\n}\n\n/**\n * Resolve the operation a tool DISPATCHES for `(resourceType, operationIdentifier)`: the\n * URL-BEARING default, and nothing else.\n *\n * ## The defect this closes — `authorize ≡ advertise ≡ execute`\n *\n * Both factories used to resolve through `getServiceOperationPathDefault`, and they dispatched\n * through the `ServicesRegistryHandlerBackendService` convenience verbs (`create` / `update` /\n * `list` / `search`), which re-resolve the same way. That resolver PREFERS an `INTERNAL_CALL`\n * default over the URL-bearing one — deliberately, because it is the SERVICE layer's native\n * transport and the trusted internal callers it was written for want exactly that. This plane is\n * not one of them: it faces an external principal and advertises a public operation to a model.\n *\n * So for a resource declaring BOTH defaults, the tool advertised one operation and executed\n * another — a different `requestDto` validating the model's arguments, a different response DTO,\n * a different `roles` declaration, and different prefix / postfix / custom-impl side effects.\n *\n * **Measured 2026-09-08, and exactly one resource declares both: `organizations` CREATE.** The\n * divergence there is not cosmetic. Its `INTERNAL_CALL` default is the transport registration owns,\n * so the shared CREATE prefix treats that path as registration-managed and SKIPS the\n * `org_type_creation_restricted` guard that confines creation-policy-managed organization types to\n * the registration flow; and the founding-owner postfix is registered on the DEFAULT `API_CALL`\n * variant ONLY, so the internal path writes no owner membership. An agent tool wired to\n * `resourceWriteTool(ORGANIZATIONS, CREATE)` therefore created a tenant with no owner — precisely\n * the stranded state `administrative-continuity-floors.md` exists to prevent — while also reaching\n * a restricted organization type. The MCP tool plane had already made this exact decision and wrote\n * down the reasoning (`McpServerBackendService.callTool`); this plane simply had not.\n *\n * ## Why \"no URL-bearing default\" now REFUSES, and why that is the safe direction\n *\n * This is a behaviour change, and it is intended. A resource whose only default for an identifier\n * is `INTERNAL_CALL` has NO HTTP surface, and its author reasoned from exactly that: `users` LIST\n * declares `roles: []` and says in as many words that the empty set \"is inert here precisely\n * because it is not URL-bearing\". A tool that dispatched it made a route-less, deliberately\n * unexposed operation reachable by an external agent — the opposite of what the declaration\n * assumed. Refusing is fail-closed, and the refusal names the resource and the operation so an app\n * author who genuinely wants that surface exposed can declare a URL-bearing default for it.\n *\n * @returns the URL-bearing default operation, or `undefined` when the resource declares none.\n */\nfunction resolveDispatchableOperation(\n  ctx: FunctionToolExecutionContext,\n  resourceType: ResourceType,\n  operationIdentifier: string,\n): ResourceConfiguration_Operation<any, any, any> | undefined {\n  const { resourcesRegistry } = ctx.services;\n  // Non-throwing probe FIRST: `getOperationPathDefault` mints an alert-grade INTERNAL error on its\n  // miss path, and merely CONSTRUCTING a Wildo error fires its backend actions (LOG / ALERT /\n  // METRICS) before any `catch` could downgrade them. A resource with no URL-bearing default for\n  // this identifier is an ordinary, expected shape here — not an incident.\n  if (!resourcesRegistry.hasOperationPathDefault(resourceType, operationIdentifier)) {\n    return undefined;\n  }\n  return resourcesRegistry.getOperationFromPath(\n    resourcesRegistry.getOperationPathDefault(resourceType, operationIdentifier),\n  );\n}\n\n/** {@link resolveDispatchableOperation}, refusing rather than returning `undefined`. */\nfunction requireDispatchableOperation(\n  ctx: FunctionToolExecutionContext,\n  resourceType: ResourceType,\n  operationIdentifier: string,\n): ResourceConfiguration_Operation<any, any, any> {\n  const operation = resolveDispatchableOperation(ctx, resourceType, operationIdentifier);\n  if (!operation) {\n    throw new Error(\n      `Agent function tool for \"${resourceType}.${operationIdentifier}\": the resource declares no default URL-bearing `\n      + 'variant for this operation, so there is no publicly-advertised operation for the tool to dispatch. Declare an '\n      + 'API_CALL default for it, or expose a different operation.',\n    );\n  }\n  return operation;\n}\n\n/**\n * Apply the dispatched operation's OWN `roles` ACL — the gate this plane was missing entirely.\n *\n * ## What was broken\n *\n * A function tool dispatches a resource operation through\n * `ServicesRegistryHandlerBackendService`, i.e. it enters at the SERVICE tier. The service tier\n * applies the repository's contextual filter (tenancy, FK narrowing, unit narrowing, the anonymous\n * guard, the retention row-hide — all fail-closed) and the whole operation pipeline (Zod, enabled\n * conditions, custom impl, hooks). It applies NO role check, and that is deliberate and\n * load-bearing: its dominant population is authentication, SCIM provisioning, webhook routing and\n * sweeps, which run BEFORE a role-bearing principal exists. Enforcing declared roles there would\n * deny the reads that ESTABLISH identity.\n *\n * `AuthorizationsBackendService.authorizeInController` is therefore the ONLY place an operation's\n * declared `roles` are checked, and it is mounted at the CONTROLLER tier — the boundary, because\n * that is where an untrusted principal names an operation.\n *\n * **This plane is that boundary and did not ask.** A tool call arrives from an external principal\n * (an A2A agent's token, or a user's own WebSocket) naming an operation on their own authority, and\n * dispatched it with the role ACL unread. A caller whose roles the operation refuses, but whose\n * tenancy admits the row, succeeded — so `roles: [ORG_MEMBER]` on Wonder Todos' todos CREATE, and\n * `roles: [APP_USER]` on the organizations self-service CREATE, were both statements about the HTTP\n * door only. Worse, the factories' own JSDoc, the app's registration comment and\n * `authenticateExternalToken`'s contract all asserted the opposite, so the gap read as closed.\n *\n * The MCP plane, which faces the same class of caller through a different transport, has always run\n * this gate (`McpServerBackendService.callTool`). This is the same call, on the sibling plane.\n *\n * ## Collection vs row\n *\n * `idOrIds` is `undefined` for CREATE / LIST / SEARCH (collection: roles + parent scope) and the\n * addressed record id for UPDATE (row: additionally FK reachability and per-row access). Passing a\n * value in the row's place for a collection call would authorize a READ of a row whose id happens\n * to be a scope id — a question nobody asked, failing for the wrong reason.\n *\n * Refusals are recorded by the authorizer's own denial-audit funnel, so a tool call denied here\n * produces the same `RESOURCE_OPERATION_DENIED` evidence a denied HTTP request produces.\n *\n * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — an external caller reaching a resource operation\n * off the HTTP plane is held to that operation's own declared authority, through the same predicate.\n *\n * @throws AUTHORIZATION — surfaced to the model as a tool error, so the agent can say it was refused.\n */\nasync function authorizeToolDispatch(\n  ctx: FunctionToolExecutionContext,\n  executionContext: ExecutionContext<any>,\n  idOrIds?: string,\n): Promise<void> {\n  await ctx.services.authorizer.authorizeInController(idOrIds, executionContext);\n}\n\n/**\n * Charge ONE dispatch against the operation's own authored `rateLimit?` policy, before the\n * dispatch happens.\n *\n * ## What was broken\n *\n * `rateLimit?` is authored on an `API_CALL` / `API_CALL_WITH_CALLBACK` variant and had exactly\n * two consumers: `RateLimitBackendService.checkPolicyForVariant` at the HTTP controller\n * pre-flight, and `McpServerBackendService.assertOperationRateLimitPolicy` on the MCP tool plane.\n * The factories below dispatch the SAME operations through the SAME service pipeline while\n * bypassing Express entirely, so the identical operation was throttled over REST, throttled over\n * MCP, and unthrottled as an agent tool.\n *\n * The exposure is larger here than on either of those planes, which is why this is not merely a\n * consistency fix. A2A's blanket per-principal cap (`A2A_EXTERNAL_TURN_RATE_MAX`) bounds TURNS,\n * and one turn's tool loop may issue arbitrarily many tool calls — so an operation declaring\n * `requestsPerMinute: 5` could be dispatched far more than five times a minute by an external\n * caller spending a single turn. MCP has no such multiplier: one `tools/call` is one dispatch, so\n * its transport cap bounds dispatches 1:1.\n *\n * ## The policy is read off the operation actually being DISPATCHED — which is now the right one\n *\n * This guard originally re-resolved the URL-bearing default for itself, because the factories\n * dispatched the `INTERNAL_CALL` default and `rateLimit?` does not exist on that variant at all —\n * so reading the dispatched operation would have made the guard permanently inert for precisely\n * the resources that declare both. That divergence is gone: {@link resolveDispatchableOperation}\n * makes the URL-bearing default the dispatched operation, and this function takes it as an\n * argument. Policy-source and dispatch-target are now the same object rather than two resolutions\n * that agreed by discipline — which is what stops them separating again.\n *\n * Reading a single declaration as the OPERATION's budget is the framework's own established\n * reading of the field, not an invention: `resources-config.shared.factory.ts` projects\n * `rateLimit: defaultApiCallVariant.rateLimit` onto every derived auto-variant, stating that \"a\n * single declaration on the default URL-bearing variant covers all derived auto-variants\".\n *\n * ## Subject: the CREDENTIAL, not the tenant\n *\n * See {@link resolveDeclaredPolicySubjectKey} for the full argument. In short, an authored\n * `requestsPerMinute` has always meant \"per CLIENT\" — the HTTP seam keys on the source IP — so\n * the faithful translation onto a plane whose callers are credentials is the credential, then the\n * delegated user, then the owning scope. Keying on the tenant would silently make the same\n * declared number several times stricter here than over REST for any tenant running more than one\n * agent. Every branch reads a SERVER-VERIFIED field of the caller's auth; nothing here may ever be\n * sourced from a tool argument, or the throttle becomes opt-out by a model choosing a fresh bucket.\n *\n * ## Scope: a THIRD bucket, deliberately\n *\n * `agent-tool:resource:<resource>:<operation>`, distinct from the HTTP seam's\n * `resource:<resource>:<operation>` and MCP's `mcp:resource:<resource>:<operation>`. The three\n * count different SUBJECTS (an IP, a credential, a credential on a different transport); one\n * shared bucket would mix identity spaces and let a browser's traffic spend an agent's budget.\n *\n * ## Ordering: AFTER authorization\n *\n * Reversed 2026-09-08, when the role gate landed beside it, and MCP's argument is adopted verbatim:\n * a caller who may not run the operation at all must be refused with AUTHORIZATION rather than told\n * how much of a budget they have, and must not consume a slot of a budget that is not theirs —\n * which would let an unauthorized caller exhaust an authorized one's quota. The HTTP seam orders\n * these the other way round because it has no choice (`checkPolicyForVariant` runs pre-flight,\n * before the execution context authorization needs exists); here the identity is already resolved,\n * so the safer order is available and is taken.\n *\n * ## Postures\n *\n * - **No declared policy, or a non-HTTP default** -> no-op, zero Redis traffic. The overwhelmingly\n *   common case: most operations declare nothing.\n * - **Unkeyable subject with a policy declared** -> REFUSE. This diverges from MCP's\n *   proceed-and-log, and the reason is the tool-loop multiplier described above: there, an\n *   unkeyed call is still bounded 1:1 by the transport's per-principal cap, so proceeding costs a\n *   bounded amount; here an unkeyed turn could drive an uncounted, unbounded loop against an\n *   endpoint whose author asked for a budget. The branch is structurally unreachable — a tool runs\n *   only inside an authenticated turn, and an authenticated principal always carries one of the\n *   four identity fields — so the refusal costs nothing today and cannot decay into a silent hole.\n * - **Limiter outage** -> propagates, exactly as it does over HTTP and MCP for the same declared\n *   policy. An authored budget must not quietly become \"unlimited\" on one plane while it is a 500\n *   on the others. (Contrast `assertExternalTurnWithinRate`, the framework-default abuse throttle,\n *   which fails OPEN because nobody declared it.)\n *\n * ## Call-site enumeration, so the next reader does not re-derive it\n *\n * The invariant is \"a resource operation dispatched on behalf of an external CLIENT is charged\n * against its declared budget\". Enumerated 2026-09-08 over every caller of the generic service\n * dispatch (`doByOperationPath` and the `ServicesRegistryHandlerBackendService` verbs):\n *\n * | Plane | Verdict |\n * |---|---|\n * | REST route (`ControllerResourceBackendService.doOperation`) | charged — `checkPolicyForVariant`, IP-keyed |\n * | MCP `tools/call` (`McpServerBackendService`) | charged — `checkPolicyForSubject`, credential-keyed |\n * | Agent function tool (here; reachable over A2A and the app WebSocket) | charged — this function |\n * | Queue job executor (`job-executor.backend.service.ts`) | **N/A** — a REPLAY of an operation already authorized, and already charged, at enqueue time (`isWorkerExecution: true`). Charging again would double-count one client request and throttle a background worker against a client's budget |\n * | Minion-scoped handler (`saas-minions-lib`) | **N/A** — same worker plane, one scope deeper |\n * | Custom controllers (SCIM, charts, flows-actors) | **N/A** — the separate authoring surface: they declare their own policy and call `checkPolicy` inline (SCIM does, with its own scope key) rather than inheriting a resource operation's |\n * | Engine-internal collaborators (auth, org, RAG, seeding, retention) | **N/A** — not client-driven; reached from a plane that already charged, or from a system path with no client at all |\n *\n * The rule that generalises: a NEW plane that dispatches a resource operation on a client's behalf\n * owes its own `checkPolicyForSubject` call — AND its own `authorizeInController`. Nothing\n * structural forces either; both fields are simply unread where nobody reads them, which is how\n * both the MCP plane and this one shipped unthrottled, and how this one shipped unauthorized.\n *\n * @throws RATE_LIMIT (429) carrying `context.retryAfterSeconds` — the same envelope the HTTP and\n *   MCP seams throw, so one refusal vocabulary covers all three planes. The AI SDK surfaces it to\n *   the model as a tool error, so the agent can tell the user it is being throttled.\n */\nasync function assertDeclaredOperationRateLimit(\n  ctx: FunctionToolExecutionContext,\n  operation: ResourceConfiguration_Operation<any, any, any>,\n  resourceType: ResourceType,\n  operationIdentifier: string,\n): Promise<void> {\n  // Defensive: `resolveDispatchableOperation` already filters to URL-bearing variants, so this\n  // narrow exists to reach `rateLimit` on the union rather than to exclude a reachable case.\n  if (\n    operation.variantType !== ResourceOperationVariantType.API_CALL\n    && operation.variantType !== ResourceOperationVariantType.API_CALL_WITH_CALLBACK\n  ) {\n    return;\n  }\n  const policy = operation.rateLimit;\n  if (!policy) {\n    return;\n  }\n\n  const subjectKey = resolveDeclaredPolicySubjectKey(ctx.auth?.initiatorIds);\n  if (!subjectKey) {\n    throw new Error(\n      `Agent function tool for \"${resourceType}.${operationIdentifier}\": the operation declares a rateLimit policy but the `\n      + 'caller carries no server-verified identity to count it against, so the declared budget cannot be honoured.',\n    );\n  }\n\n  await ctx.services.rateLimitService.checkPolicyForSubject(\n    policy,\n    `agent-tool:resource:${resourceType}:${operationIdentifier}`,\n    subjectKey,\n    ctx.organizationId,\n  );\n}\n\n/**\n * Dispatch a resource operation from a function tool, carrying BOTH gates the service tier skips.\n *\n * ## What this exists to prevent (#556)\n *\n * A `FunctionTool` enters at the SERVICE tier. It never passes through Express, so two\n * controller-tier gates are simply absent from its path — the operation's declared `roles` ACL and\n * its declared `rateLimit?`. That skip is CORRECT for the service tier's intended caller (the\n * authentication reads that run before a role-bearing principal exists) and wrong for this plane,\n * whose caller is an external principal naming an operation on their own authority.\n *\n * The failure is quiet, which is what makes it worth a seam. Tenancy still applies — the\n * repository's contextual filter runs regardless — so an unauthorized tool returns the caller's own\n * tenant's rows and LOOKS like it works. Nothing throws and nothing logs. What is missing is only\n * the row-level `roles` ACL: a caller whose roles the operation refuses, but whose tenancy admits\n * the row, succeeds.\n *\n * Until this existed the two gates were applied by hand at three sites in this file, and both helpers\n * were module-private — so an application author writing their own tool could not discharge the\n * obligation even after reading about it. The engine's own rule\n * (`invariant-call-site-enumeration.md`) asks for the opposite: prefer making the invariant\n * unbypassable over applying it N times. **This is the shortest path to a dispatch, so the correct\n * path is also the easy one.**\n *\n * ## The order is authorize → charge → dispatch, and it is not arbitrary\n *\n * Authorization first, so an unauthorized caller cannot spend an authorized caller's quota. The\n * charge before the dispatch, so a refused budget costs no work. This is the same order the MCP\n * plane uses, deliberately — one refusal vocabulary across every plane that enters here.\n *\n * ## One id, two uses, and why that is safer than two parameters\n *\n * `recordId` addresses the row AND is the authorization subject, because at every existing call site\n * those are the same value: an UPDATE passes the id to both, a CREATE/LIST/SEARCH passes it to\n * neither. Splitting them into two parameters would make it possible to authorize a collection call\n * while dispatching a row call — a question nobody asked, failing for the wrong reason. A bulk\n * operation addressed by a FILTER passes `dispatchFilter` instead, which is never an authorization\n * subject because a filter-addressed operation IS a collection call.\n *\n * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — an external caller reaching a resource operation\n * off the HTTP plane is held to that operation's own declared authority, through the same predicate.\n *\n * @throws AUTHORIZATION when the operation's roles refuse the caller — surfaced to the model as a\n *   tool error, so the agent can say it was refused. Recorded by the authorizer's own denial-audit\n *   funnel, so the evidence matches a denied HTTP request.\n * @throws RATE_LIMIT (429) carrying `context.retryAfterSeconds`, the same envelope the HTTP and MCP\n *   seams throw.\n * @throws NOT_FOUND when the resource declares no dispatchable operation under that identifier.\n */\nexport async function dispatchResourceOperationAsTool<TResult = any>(input: {\n  ctx: FunctionToolExecutionContext;\n  resourceType: ResourceType;\n  /** A `CoreResourceOperation` member, or a custom operation identifier the resource declares. */\n  operationIdentifier: string;\n  /** The addressed row, for a row-scoped operation. Authorizes AND addresses; omit for a collection call. */\n  recordId?: string;\n  /** A filter addressing a COLLECTION, for a bulk operation. Never an authorization subject. */\n  dispatchFilter?: any;\n  /** Parent / context resource ids used to build the scoped execution context. */\n  contextIds?: any;\n  /** The operation payload — the body for a write, the query options for a read. */\n  data?: any;\n  /** Repository options passed through, e.g. `{ paginated: true }` for a LIST envelope. */\n  options?: any;\n}): Promise<TResult> {\n  const { ctx, resourceType, operationIdentifier, recordId, dispatchFilter, contextIds, data, options } = input;\n\n  const operation = requireDispatchableOperation(ctx, resourceType, operationIdentifier);\n  // Rebuild a scoped ExecutionContext from the CALLER's verified auth for THIS operation. Never\n  // reuse one built for another operation: the scope it resolves is operation-specific.\n  const executionContext = await ctx.services.executionContextCreator.buildContextFromSocketAuth(ctx.auth, operation, contextIds);\n\n  await authorizeToolDispatch(ctx, executionContext, recordId);\n  await assertDeclaredOperationRateLimit(ctx, operation, resourceType, operationIdentifier);\n\n  const operationPath = ResourcesConfig_OperationPathUtils.extractOperationPath(operation) as ResourceConfiguration_OperationPath<any, any>;\n  const subject = recordId ?? dispatchFilter;\n\n  /*\n   * The trailing `options` is OMITTED rather than passed as `undefined` when absent, so this seam\n   * calls the dispatcher with exactly the arity each site used before it existed.\n   *\n   * Behaviourally the two are identical for an optional parameter. What differs is what a test can\n   * see: the authorization and write pins here assert the dispatch with `toHaveBeenCalledWith`,\n   * which is arity-exact, so a uniform five-argument call would have required editing four tests\n   * that guard an authorization path. Preserving the shape proves the refactor changed nothing,\n   * which is the property that matters most for the one seam every tool dispatch now goes through.\n   */\n  return options === undefined\n    ? ctx.services.servicesRegistryHandler.doByOperationPath(operationPath, executionContext, subject, data)\n    : ctx.services.servicesRegistryHandler.doByOperationPath(operationPath, executionContext, subject, data, options);\n}\n\n/**\n * Is this a REFUSAL the read tool must never launder into a different operation?\n *\n * Exists for exactly one reason: the read tool's SEARCH branch degrades to a scoped LIST on any\n * throw, and a refusal swallowed there would silently become an UNGATED LIST — the guard present\n * and inert, which is worse than absent because it reads as enforced. Two refusal kinds qualify:\n *\n *  - **RATE_LIMIT** — a declared budget is an application's statement about the endpoint, not a\n *    reason to reach for a different one.\n *  - **AUTHORIZATION** — stronger still. A denial has already been RECORDED by the authorizer's\n *    audit funnel, so proceeding would leave a `RESOURCE_OPERATION_DENIED` row beside a request\n *    that then succeeded, making the access trail describe something that did not happen.\n *\n * A genuine \"this resource has no URL-bearing SEARCH operation\" still degrades, unchanged.\n */\nfunction isNonDegradableRefusal(error: unknown): boolean {\n  return isWildoBackendError(error)\n    && (error.type === ErrorType.RATE_LIMIT || error.type === ErrorType.AUTHORIZATION);\n}\n\n/**\n * @wildo_source:part:start saas.backend.flows-actors.resource-read-tool facet:layer:backend facet:family:flows-actors\n *\n * Generic resource-read tool factory. Produces a {@link FunctionTool} that lets\n * an agent look up records of ONE resource type **scoped to the calling user**,\n * with that user's own visibility — no `systemAccessPolicy` bypass. Instantiate\n * it per resource an agent should be able to read (e.g. `resourceReadTool(TODOS)`),\n * making any registered resource agent-readable without hand-writing a tool.\n *\n * The tool dispatches the resource's PUBLIC, URL-bearing default LIST / SEARCH — the same\n * operation a REST client reaches — under a user `ExecutionContext` rebuilt from the caller's\n * socket auth, and applies that operation's own declared `roles` ACL through\n * `AuthorizationsBackendService.authorizeInController` before dispatching it. So the framework's\n * contextual filter AND the role ACL apply exactly as for the user's own request. (The role gate\n * is named explicitly because it does NOT come free with the service path: the service tier\n * applies tenancy and the operation pipeline and no role check, so a tool that merely dispatched\n * would run with the ACL unread — which is what this factory did until 2026-09-08.) A resource\n * that declares no URL-bearing default for the operation is REFUSED rather than served through its\n * route-less internal variant. Identity is NEVER taken\n * from the model — only the `searchQuery` / `limit` args are. Its `functionRef`\n * defaults to `resource.<resourceType>.read` — reference that exact string from\n * your agent's `capabilities.tools.functionRefs`. Import path:\n * `@wildo-ai/saas-backend-lib`.\n *\n * @param resourceType  the resource to expose (any registered `ResourceType`).\n * @param options       optional `functionRef` / `description` / `defaultLimit` / `maxLimit` overrides.\n * @example\n *   // in a backend module's `flowsActors.functionTools` contribution:\n *   functionTools: [resourceReadTool(TasksManager_ResourceType.TODOS)]\n *   // and on the agent:\n *   capabilities: { tools: { functionRefs: ['resource.todos.read'], mcpRefs: [] } }\n */\nexport function resourceReadTool(\n  resourceType: ResourceType,\n  options?: { functionRef?: string; description?: string; defaultLimit?: number; maxLimit?: number },\n): FunctionTool {\n  /** @wildo_source:part:end saas.backend.flows-actors.resource-read-tool */\n  const defaultLimit = options?.defaultLimit ?? 50;\n  const maxLimit = options?.maxLimit ?? 100;\n\n  return {\n    functionRef: options?.functionRef ?? `resource.${resourceType}.read`,\n    description:\n      options?.description ??\n      `Look up the current user's \"${resourceType}\" records to answer their questions about them. ` +\n      `Optionally pass a free-text searchQuery to narrow the results. Only the current user's own records are ever returned.`,\n    inputSchema: z.object({\n      searchQuery: z.string().optional(),\n      limit: z.number().int().min(1).max(maxLimit).optional(),\n    }),\n    execute: async (args: { searchQuery?: string; limit?: number }, ctx: FunctionToolExecutionContext): Promise<ResourceReadToolResult> => {\n      const { servicesRegistryHandler, executionContextCreator } = ctx.services;\n      const limit = typeof args?.limit === 'number' ? Math.min(args.limit, maxLimit) : defaultLimit;\n      const searchQuery = typeof args?.searchQuery === 'string' && args.searchQuery.trim().length > 0 ? args.searchQuery.trim() : undefined;\n      const contextIds: Record<string, string> = ctx.organizationId ? { organizationId: ctx.organizationId } : {};\n\n      // Prefer SEARCH when a query is supplied AND the resource EXPOSES it; fall back to a scoped\n      // LIST. Both run as the user, under the operation's own role ACL (no bypass).\n      if (searchQuery) {\n        // The fallback catch covers ONLY op-resolution + the search call — a resource may expose no\n        // SEARCH operation, in which case we degrade to a scoped LIST. It deliberately does NOT wrap\n        // the response-DTO projection below: a projection failure there is a real server contract\n        // violation (a record that violates its own response DTO) and must surface as a tool error,\n        // exactly as it would on the LIST path — never silently degrade to an unfiltered LIST.\n        let searchOp: ResourceConfiguration_Operation<any, any, any> | undefined;\n        let searchResult: unknown;\n        try {\n          // Non-throwing: a resource with no URL-bearing SEARCH default has nothing to expose here,\n          // which is the documented degradation rather than a refusal.\n          searchOp = resolveDispatchableOperation(ctx, resourceType, CoreResourceOperation.SEARCH);\n          if (searchOp) {\n            // The seam authorizes, charges and dispatches in that order. It sits inside this try\n            // because that is where the dispatch is; the catch below re-throws either refusal so\n            // neither can be laundered into an ungated LIST. The operation is resolved twice — once\n            // above to decide whether SEARCH is even available, once inside the seam — and that is\n            // deliberate: the availability question is this factory's, the gates are the seam's.\n            searchResult = await dispatchResourceOperationAsTool({\n              ctx,\n              resourceType,\n              operationIdentifier: CoreResourceOperation.SEARCH,\n              contextIds,\n              data: { searchQuery, filter: undefined },\n            });\n          }\n        } catch (error) {\n          // A declared budget, or a role refusal, is a statement about THIS endpoint — not a reason\n          // to reach for a different one. Degrading here would answer the model with LIST results\n          // the caller was just refused: enforcement that reports success.\n          if (isNonDegradableRefusal(error)) throw error;\n          searchOp = undefined; // SEARCH failed to resolve or dispatch — fall through to LIST.\n        }\n        if (searchOp !== undefined) {\n          // Project through the SEARCH operation's response DTO + JSON wire step, exactly as the\n          // REST controller does, so no `Date`/backend-only/secret field reaches the model.\n          const safeSearchResult = await toResponseSafeToolOutput(searchOp, searchResult);\n          return toReadResult(safeSearchResult, limit);\n        }\n      }\n\n      // LIST is a distinct operation with its own ACL and its own declared budget, so it is\n      // authorized and charged separately. A call that resolved SEARCH and then degraded to LIST\n      // does both twice — two operations were attempted, exactly as two HTTP requests would be, and\n      // that path is only reached when the search dispatch failed for a reason that is not a refusal.\n      const listOp = requireDispatchableOperation(ctx, resourceType, CoreResourceOperation.LIST);\n      // `paginated: true` yields the `{ data, pagination }` envelope the LIST response DTO expects\n      // (the same shape the HTTP controller requests) — a bare array would fail the wrapper-DTO\n      // projection in `toResponseSafeToolOutput` below.\n      const listResult = await dispatchResourceOperationAsTool({\n        ctx,\n        resourceType,\n        operationIdentifier: CoreResourceOperation.LIST,\n        contextIds,\n        data: { filter: undefined, page: 1, limit },\n        options: { paginated: true },\n      });\n      const safeListResult = await toResponseSafeToolOutput(listOp, listResult);\n      return toReadResult(safeListResult, limit);\n    },\n  };\n}\n\n/**\n * @wildo_source:part:start saas.backend.flows-actors.resource-write-tool facet:layer:backend facet:family:flows-actors\n *\n * Generic resource-WRITE tool factory. The mutating sibling of {@link resourceReadTool}.\n * Produces a {@link FunctionTool} that lets an agent CREATE or UPDATE ONE resource\n * type **as the calling user**, under the caller's own `ExecutionContext` rebuilt\n * from their verified socket auth — no `systemAccessPolicy` bypass, and identity is\n * NEVER taken from the model. It dispatches the resource's PUBLIC, URL-bearing default CREATE /\n * UPDATE — the same operation a REST client reaches, with the same request DTO validating the\n * model's arguments and the same prefix / postfix side effects — and applies that operation's own\n * `accessControl` (roles + parent scope, plus per-row access on UPDATE) through\n * `AuthorizationsBackendService.authorizeInController` before the write. Authorization is therefore\n * **fail-closed**: a caller lacking the operation's role gets a thrown authz error, not a silent\n * write.\n *\n * Both halves of that are load-bearing and neither came free, so do not simplify them away. The\n * service tier applies tenancy and the operation pipeline and NO role check, and the service\n * layer's own default resolver PREFERS a route-less `INTERNAL_CALL` variant over the public one —\n * so before 2026-09-08 this factory dispatched a different operation from the one it advertises,\n * with the ACL unread. On `organizations` CREATE that combination created ownerless tenants.\n *\n * A resource that declares no URL-bearing default for the operation is REFUSED rather than written\n * through its internal variant. Owner FKs and\n * other server-set fields are EC-injected / `excludeFromCreate`, so the model can\n * never spoof ownership through the tool arguments.\n *\n * Unlike the read tool (whose args are a fixed `{ searchQuery, limit }`), a write\n * tool's arguments are resource-specific, so the caller MUST supply the model-facing\n * `inputSchema` — the create/update field contract shown to the model. Keep it to the\n * fields the model should legitimately set. For `UPDATE`, include the record `id` in\n * the schema; the factory splits `id` out to address the row and passes the remaining\n * fields as the patch.\n *\n * `functionRef` defaults to `resource.<resourceType>.<op>` (e.g. `resource.todos.create`)\n * — reference that exact string from your agent's `capabilities.tools.functionRefs`.\n * Import path: `@wildo-ai/saas-backend-lib`.\n *\n * @param resourceType  the resource to expose (any registered `ResourceType`).\n * @param op            `CoreResourceOperation.CREATE` or `CoreResourceOperation.UPDATE`.\n * @param options       `{ inputSchema, functionRef?, description? }` — `inputSchema` is REQUIRED (the model-facing argument contract).\n * @example\n *   // in a backend module's `flowsActors.functionTools` contribution:\n *   functionTools: [\n *     resourceWriteTool(TasksManager_ResourceType.TODOS, CoreResourceOperation.CREATE, {\n *       inputSchema: z.object({ title: z.string(), todoListId: z.string(), description: z.string().optional() }),\n *     }),\n *   ]\n *   // and on the agent:\n *   capabilities: { tools: { functionRefs: ['resource.todos.create'], mcpRefs: [] } }\n */\nexport function resourceWriteTool(\n  resourceType: ResourceType,\n  op: CoreResourceOperation.CREATE | CoreResourceOperation.UPDATE,\n  options: {\n    inputSchema: z.ZodTypeAny;\n    functionRef?: string;\n    description?: string;\n    /**\n     * Gate this write behind a HUMAN decision (see {@link FunctionTool.requiresHumanApproval}).\n     *\n     * Without this passthrough the flag was declarable only by hand-rolling a `FunctionTool`, so\n     * the approval gate was unreachable from the factory every app author actually uses — a\n     * capability present in the contract and absent from the authoring surface. Reads are not\n     * offered the option: approval exists to gate EFFECTS, and gating a read teaches authors to\n     * approve things reflexively, which is how an approval prompt stops being read.\n     */\n    requiresHumanApproval?: boolean;\n  },\n): FunctionTool {\n  /** @wildo_source:part:end saas.backend.flows-actors.resource-write-tool */\n  return {\n    functionRef: options.functionRef ?? `resource.${resourceType}.${op}`,\n    requiresHumanApproval: options.requiresHumanApproval,\n    description:\n      options.description ??\n      (op === CoreResourceOperation.CREATE\n        ? `Create a new \"${resourceType}\" record on behalf of the current user from the provided fields. The record is owned by and scoped to the current user; ownership fields are set by the system, not from the arguments.`\n        : `Update an existing \"${resourceType}\" record the current user owns. Pass the record \"id\" plus only the fields to change.`),\n    inputSchema: options.inputSchema,\n    execute: async (args: Record<string, unknown>, ctx: FunctionToolExecutionContext): Promise<unknown> => {\n      const { servicesRegistryHandler, executionContextCreator } = ctx.services;\n      const contextIds: Record<string, string> = ctx.organizationId ? { organizationId: ctx.organizationId } : {};\n\n      // UPDATE addresses a row; CREATE does not. Split FIRST, before anything is resolved: this is\n      // a check on the tool AUTHOR's own `inputSchema`, independent of the registry, and surfacing\n      // it ahead of a resolution failure keeps the actionable message the actionable one.\n      // `authorizeInController` then takes the addressed id and runs the row-scoped phases only\n      // when there is one.\n      const isUpdate = op === CoreResourceOperation.UPDATE;\n      const { id, ...patch } = args as { id?: string };\n      if (isUpdate && (typeof id !== 'string' || id.length === 0)) {\n        throw new Error(\n          `resourceWriteTool(${resourceType}, update): the \"id\" argument is required — declare it in the tool's inputSchema.`,\n        );\n      }\n\n      // The operation the tool ADVERTISES is the resource's public, URL-bearing default; dispatch\n      // that exact one rather than re-resolving through the service layer's INTERNAL-preferred\n      // resolver. See `resolveDispatchableOperation` for what diverged and what it cost.\n      const operation = requireDispatchableOperation(ctx, resourceType, op);\n      const operationPath = ResourcesConfig_OperationPathUtils.extractOperationPath(operation) as ResourceConfiguration_OperationPath<any, any>;\n\n      // Rebuild a scoped ExecutionContext from the CALLER's verified auth for this operation, then\n      // apply the operation's own role + scope ACL against it (fail-closed) before anything is\n      // written. The write runs as the user, never with an ACL bypass.\n      if (!isUpdate) {\n        // The seam authorizes as a COLLECTION call (no row addressed), charges the operation's own\n        // budget after authorization so an unauthorized caller cannot spend an authorized one's, and\n        // writes as the user — never with an ACL bypass.\n        const created = await dispatchResourceOperationAsTool({ ctx, resourceType, operationIdentifier: op, contextIds, data: args });\n        // Return the same JSON-safe, response-DTO-projected record the REST endpoint would, so no\n        // `Date`/backend-only/secret reaches the model and the tool-loop CONTINUATION step validates.\n        return toResponseSafeToolOutput(operation, created);\n      }\n\n      // UPDATE: the record \"id\" addresses the row AND is the authorization subject — the seam takes\n      // one value for both, which is what makes authorizing a collection call while dispatching a\n      // row call unrepresentable.\n      const updated = await dispatchResourceOperationAsTool({ ctx, resourceType, operationIdentifier: op, recordId: id, contextIds, data: patch });\n      return toResponseSafeToolOutput(operation, updated);\n    },\n  };\n}\n"]}

package/dist/esm/flows-actors/models/market-generation.actors-system.backend.definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"market-generation.actors-system.backend.definitions.d.ts","sourceRoot":"","sources":["../../../../../src/flows-actors/models/market-generation.actors-system.backend.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EACL,iBAAiB,EAKlB,MAAM,uBAAuB,CAAC;AAU/B,eAAO,MAAM,2BAA2B,EAAG,yBAAkC,CAAC;AAE9E,eAAO,MAAM,qBAAqB,EAAE,iBAkCnC,CAAC;AACF,0DAA0D"}
+{"version":3,"file":"market-generation.actors-system.backend.definitions.d.ts","sourceRoot":"","sources":["../../../../src/flows-actors/models/market-generation.actors-system.backend.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EACL,iBAAiB,EAKlB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,2BAA2B,EAAG,yBAAkC,CAAC;AAE9E,eAAO,MAAM,qBAAqB,EAAE,iBAoCnC,CAAC;AACF,0DAA0D"}

package/dist/esm/flows-actors/models/market-generation.actors-system.backend.definitions.js

@@ -39,7 +39,7 @@
  * override with a lower temperature.
  */
 import { FlowsActors_Agent_Skill_Type, FlowsActors_Agent_Status, ResourceOperationRiskLevel, ResourcePrimaryScope, } from '@wildo-ai/saas-models';
-import { LLMProvider_GenerateTextInputSchema, LLMProvider_GenerateTextOutputSchema, LLMProvider_OperationContext_BaseSchema, LLMProvider_OperationKey, LLM_Model, } from '@wildo-ai/external-connectors-models';
+import { LLMProvider_GenerateTextInputSchema, LLMProvider_GenerateTextOutputSchema, LLMProvider_OperationContext_BaseSchema, LLMProvider_OperationKey, LLM_Model_Applicability } from '@wildo-ai/external-connectors-models';
 export const MARKET_GENERATION_AGENT_REF = 'market.generation.agent';
 export const marketGenerationAgent = {
     ref: MARKET_GENERATION_AGENT_REF,
@@ -47,7 +47,9 @@ export const marketGenerationAgent = {
     status: FlowsActors_Agent_Status.ACTIVE,
     config: {
         providerRef: 'openai',
-        model: LLM_Model.OPEN_AI_GPT_5_6_TERRA,
+        // STRUCTURED_AUTHORING: a market snapshot generated against a declared schema (#439).
+        // Resolves to `gpt-5.6-terra` on `openai` today — the model this pinned.
+        modelApplicability: LLM_Model_Applicability.STRUCTURED_AUTHORING,
         operationKey: LLMProvider_OperationKey.GENERATE_TEXT,
         // No sampling params: the GPT-5.6 family rejects non-default temperature (verified live 2026-07-16).
         accessControl: [{

package/dist/esm/flows-actors/models/market-generation.actors-system.backend.definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"market-generation.actors-system.backend.definitions.js","sourceRoot":"","sources":["../../../../../src/flows-actors/models/market-generation.actors-system.backend.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAEL,4BAA4B,EAC5B,wBAAwB,EACxB,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mCAAmC,EACnC,oCAAoC,EACpC,uCAAuC,EAEvC,wBAAwB,EACxB,SAAS,GACV,MAAM,sCAAsC,CAAC;AAE9C,MAAM,CAAC,MAAM,2BAA2B,GAAG,yBAAkC,CAAC;AAE9E,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,GAAG,EAAE,2BAA2B;IAChC,WAAW,EAAE,yBAAyB;IACtC,MAAM,EAAE,wBAAwB,CAAC,MAAM;IACvC,MAAM,EAAE;QACN,WAAW,EAAE,QAAQ;QACrB,KAAK,EAAE,SAAS,CAAC,qBAAqB;QACtC,YAAY,EAAE,wBAAwB,CAAC,aAAa;QACpD,qGAAqG;QACrG,aAAa,EAAE,CAAC;gBACd,YAAY,EAAE,oBAAoB,CAAC,WAAW;gBAC9C,gBAAgB,EAAE,KAAK;aACxB,CAAC;QACF,SAAS,EAAE,0BAA0B,CAAC,GAAG;KAC1C;IACD,mBAAmB,EAAE;QACnB,YAAY,EAAE,wBAAwB,CAAC,aAAa;QACpD,WAAW,EAAE,QAAQ;QACrB,WAAW,EAAE,mCAAmC;QAChD,YAAY,EAAE,oCAAoC;QAClD,sBAAsB,EAAE,uCAAuC;KAClB;IAC/C,UAAU,EAAE;QACV,IAAI,EAAE,oFAAoF;cACtF,2FAA2F;cAC3F,uFAAuF;QAC3F,OAAO,EAAE,4FAA4F;cACjG,4FAA4F;cAC5F,gGAAgG;cAChG,qGAAqG;QACzG,SAAS,EAAE,4BAA4B,CAAC,UAAU;QAClD,YAAY,EAAE,EAAE;KACjB;IACD,SAAS,EAAE,0BAA0B;CACtC,CAAC;AACF,0DAA0D","sourcesContent":["/**\n * @wildo_source:part:start saas.market.generation-agent facet:layer:backend facet:family:market\n *\n * Market generation agent — framework default (Phase 4.2).\n *\n * The market generation agent is a free-form text-generation LLM agent\n * driven by the `wildo market generate` CLI. It receives a fully\n * rendered prompt (market-context block + Mustache-substituted\n * `MarketMessageTemplate` body) and returns the LLM's prose output as a\n * single string.\n *\n * Import path: `@wildo-ai/saas-backend-lib`.\n *\n * **Framework default + application override.** This constant is the\n * default agent the dev companion registers under\n * `MARKET_GENERATION_AGENT_REF` when the application authors no\n * override. An application chooses its own LLM provider / model /\n * persona by exporting a `marketGenerationAgentOverride` on its backend\n * companion-exports (`BackendCompanionExports.marketGenerationAgentOverride`);\n * the companion registers the override in place of this default. The\n * override MUST keep `ref: MARKET_GENERATION_AGENT_REF` — the companion's\n * market service invokes the agent by that fixed ref, so the override\n * replaces the default under the same identity (an override under a\n * different ref would never be reached). The ref is authored here (not\n * in the companion) precisely so an application's `backend-api` can\n * import it to author a valid override.\n *\n * Why `GENERATE_TEXT` instead of `GENERATE_STRUCTURED`: Phase-4.2\n * outputs are always free-form prose (landing-page hero copy,\n * objection-response email body, etc.). A structured schema would force\n * every template author to also author a matching Zod schema per\n * variant. Mirrors the companion's `emailTemplateGenerationAgent`\n * pattern (a build-time `GENERATE_TEXT` scaffolding agent).\n *\n * Temperature note: 0.6 is intentionally higher than\n * `email-template.generation.agent` (0.4) because marketing copy\n * benefits from more creative latitude than email-template TSX\n * scaffolding. An application that wants deterministic reruns authors an\n * override with a lower temperature.\n */\n\nimport {\n  FlowsActors_Agent,\n  FlowsActors_Agent_Skill_Type,\n  FlowsActors_Agent_Status,\n  ResourceOperationRiskLevel,\n  ResourcePrimaryScope,\n} from '@wildo-ai/saas-models';\nimport {\n  LLMProvider_GenerateTextInputSchema,\n  LLMProvider_GenerateTextOutputSchema,\n  LLMProvider_OperationContext_BaseSchema,\n  LLMProvider_OperationDefinitionBase,\n  LLMProvider_OperationKey,\n  LLM_Model,\n} from '@wildo-ai/external-connectors-models';\n\nexport const MARKET_GENERATION_AGENT_REF = 'market.generation.agent' as const;\n\nexport const marketGenerationAgent: FlowsActors_Agent = {\n  ref: MARKET_GENERATION_AGENT_REF,\n  displayName: 'Market Generation Agent',\n  status: FlowsActors_Agent_Status.ACTIVE,\n  config: {\n    providerRef: 'openai',\n    model: LLM_Model.OPEN_AI_GPT_5_6_TERRA,\n    operationKey: LLMProvider_OperationKey.GENERATE_TEXT,\n    // No sampling params: the GPT-5.6 family rejects non-default temperature (verified live 2026-07-16).\n    accessControl: [{\n      primaryScope: ResourcePrimaryScope.APPLICATION,\n      requiresApproval: false,\n    }],\n    riskLevel: ResourceOperationRiskLevel.LOW,\n  },\n  operationDefinition: {\n    operationKey: LLMProvider_OperationKey.GENERATE_TEXT,\n    providerRef: 'openai',\n    inputSchema: LLMProvider_GenerateTextInputSchema,\n    outputSchema: LLMProvider_GenerateTextOutputSchema,\n    operationContextSchema: LLMProvider_OperationContext_BaseSchema,\n  } satisfies LLMProvider_OperationDefinitionBase,\n  promptSpec: {\n    role: 'You are a senior B2B SaaS marketing writer. You receive an English market-context '\n      + 'briefing followed by a single concrete writing task. The briefing is the source of truth '\n      + 'for ICP, benefits, voice, and any objections — never invent facts that contradict it.',\n    persona: 'You write tight, customer-led copy. You favour the reader\\'s outcomes over feature lists, '\n      + 'never use marketing clichés (\"game-changer\", \"revolutionary\", \"synergy\"), and respect the '\n      + 'preferred tone of voice from the briefing. When the task asks for a specific output language, '\n      + 'you write the entire response in that language while keeping proper nouns and product names intact.',\n    skillType: FlowsActors_Agent_Skill_Type.GENERATION,\n    instructions: [],\n  },\n  createdAt: '2026-04-17T00:00:00.000Z',\n};\n/** @wildo_source:part:end saas.market.generation-agent */\n"]}
+{"version":3,"file":"market-generation.actors-system.backend.definitions.js","sourceRoot":"","sources":["../../../../src/flows-actors/models/market-generation.actors-system.backend.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAEL,4BAA4B,EAC5B,wBAAwB,EACxB,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,mCAAmC,EAAE,oCAAoC,EAAE,uCAAuC,EAAuC,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAElQ,MAAM,CAAC,MAAM,2BAA2B,GAAG,yBAAkC,CAAC;AAE9E,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,GAAG,EAAE,2BAA2B;IAChC,WAAW,EAAE,yBAAyB;IACtC,MAAM,EAAE,wBAAwB,CAAC,MAAM;IACvC,MAAM,EAAE;QACN,WAAW,EAAE,QAAQ;QACrB,sFAAsF;QACtF,yEAAyE;QACzE,kBAAkB,EAAE,uBAAuB,CAAC,oBAAoB;QAChE,YAAY,EAAE,wBAAwB,CAAC,aAAa;QACpD,qGAAqG;QACrG,aAAa,EAAE,CAAC;gBACd,YAAY,EAAE,oBAAoB,CAAC,WAAW;gBAC9C,gBAAgB,EAAE,KAAK;aACxB,CAAC;QACF,SAAS,EAAE,0BAA0B,CAAC,GAAG;KAC1C;IACD,mBAAmB,EAAE;QACnB,YAAY,EAAE,wBAAwB,CAAC,aAAa;QACpD,WAAW,EAAE,QAAQ;QACrB,WAAW,EAAE,mCAAmC;QAChD,YAAY,EAAE,oCAAoC;QAClD,sBAAsB,EAAE,uCAAuC;KAClB;IAC/C,UAAU,EAAE;QACV,IAAI,EAAE,oFAAoF;cACtF,2FAA2F;cAC3F,uFAAuF;QAC3F,OAAO,EAAE,4FAA4F;cACjG,4FAA4F;cAC5F,gGAAgG;cAChG,qGAAqG;QACzG,SAAS,EAAE,4BAA4B,CAAC,UAAU;QAClD,YAAY,EAAE,EAAE;KACjB;IACD,SAAS,EAAE,0BAA0B;CACtC,CAAC;AACF,0DAA0D","sourcesContent":["/**\n * @wildo_source:part:start saas.market.generation-agent facet:layer:backend facet:family:market\n *\n * Market generation agent — framework default (Phase 4.2).\n *\n * The market generation agent is a free-form text-generation LLM agent\n * driven by the `wildo market generate` CLI. It receives a fully\n * rendered prompt (market-context block + Mustache-substituted\n * `MarketMessageTemplate` body) and returns the LLM's prose output as a\n * single string.\n *\n * Import path: `@wildo-ai/saas-backend-lib`.\n *\n * **Framework default + application override.** This constant is the\n * default agent the dev companion registers under\n * `MARKET_GENERATION_AGENT_REF` when the application authors no\n * override. An application chooses its own LLM provider / model /\n * persona by exporting a `marketGenerationAgentOverride` on its backend\n * companion-exports (`BackendCompanionExports.marketGenerationAgentOverride`);\n * the companion registers the override in place of this default. The\n * override MUST keep `ref: MARKET_GENERATION_AGENT_REF` — the companion's\n * market service invokes the agent by that fixed ref, so the override\n * replaces the default under the same identity (an override under a\n * different ref would never be reached). The ref is authored here (not\n * in the companion) precisely so an application's `backend-api` can\n * import it to author a valid override.\n *\n * Why `GENERATE_TEXT` instead of `GENERATE_STRUCTURED`: Phase-4.2\n * outputs are always free-form prose (landing-page hero copy,\n * objection-response email body, etc.). A structured schema would force\n * every template author to also author a matching Zod schema per\n * variant. Mirrors the companion's `emailTemplateGenerationAgent`\n * pattern (a build-time `GENERATE_TEXT` scaffolding agent).\n *\n * Temperature note: 0.6 is intentionally higher than\n * `email-template.generation.agent` (0.4) because marketing copy\n * benefits from more creative latitude than email-template TSX\n * scaffolding. An application that wants deterministic reruns authors an\n * override with a lower temperature.\n */\n\nimport {\n  FlowsActors_Agent,\n  FlowsActors_Agent_Skill_Type,\n  FlowsActors_Agent_Status,\n  ResourceOperationRiskLevel,\n  ResourcePrimaryScope,\n} from '@wildo-ai/saas-models';\nimport { LLMProvider_GenerateTextInputSchema, LLMProvider_GenerateTextOutputSchema, LLMProvider_OperationContext_BaseSchema, LLMProvider_OperationDefinitionBase, LLMProvider_OperationKey, LLM_Model_Applicability } from '@wildo-ai/external-connectors-models';\n\nexport const MARKET_GENERATION_AGENT_REF = 'market.generation.agent' as const;\n\nexport const marketGenerationAgent: FlowsActors_Agent = {\n  ref: MARKET_GENERATION_AGENT_REF,\n  displayName: 'Market Generation Agent',\n  status: FlowsActors_Agent_Status.ACTIVE,\n  config: {\n    providerRef: 'openai',\n    // STRUCTURED_AUTHORING: a market snapshot generated against a declared schema (#439).\n    // Resolves to `gpt-5.6-terra` on `openai` today — the model this pinned.\n    modelApplicability: LLM_Model_Applicability.STRUCTURED_AUTHORING,\n    operationKey: LLMProvider_OperationKey.GENERATE_TEXT,\n    // No sampling params: the GPT-5.6 family rejects non-default temperature (verified live 2026-07-16).\n    accessControl: [{\n      primaryScope: ResourcePrimaryScope.APPLICATION,\n      requiresApproval: false,\n    }],\n    riskLevel: ResourceOperationRiskLevel.LOW,\n  },\n  operationDefinition: {\n    operationKey: LLMProvider_OperationKey.GENERATE_TEXT,\n    providerRef: 'openai',\n    inputSchema: LLMProvider_GenerateTextInputSchema,\n    outputSchema: LLMProvider_GenerateTextOutputSchema,\n    operationContextSchema: LLMProvider_OperationContext_BaseSchema,\n  } satisfies LLMProvider_OperationDefinitionBase,\n  promptSpec: {\n    role: 'You are a senior B2B SaaS marketing writer. You receive an English market-context '\n      + 'briefing followed by a single concrete writing task. The briefing is the source of truth '\n      + 'for ICP, benefits, voice, and any objections — never invent facts that contradict it.',\n    persona: 'You write tight, customer-led copy. You favour the reader\\'s outcomes over feature lists, '\n      + 'never use marketing clichés (\"game-changer\", \"revolutionary\", \"synergy\"), and respect the '\n      + 'preferred tone of voice from the briefing. When the task asks for a specific output language, '\n      + 'you write the entire response in that language while keeping proper nouns and product names intact.',\n    skillType: FlowsActors_Agent_Skill_Type.GENERATION,\n    instructions: [],\n  },\n  createdAt: '2026-04-17T00:00:00.000Z',\n};\n/** @wildo_source:part:end saas.market.generation-agent */\n"]}

package/dist/esm/flows-actors/models/mcp-client.backend.definitions.d.ts

@@ -0,0 +1,113 @@
+import type { FlowsActors_McpServer } from '@wildo-ai/saas-models';
+/**
+ * The protocol revision this client speaks, sent as `protocolVersion` in `initialize` and as the
+ * `MCP-Protocol-Version` header on every later request.
+ *
+ * spec-cite: MCP 2025-06-18 — Lifecycle §Version Negotiation (the client MUST send a protocol
+ * version it supports, and SHOULD send the latest it supports) and Transports §Protocol Version
+ * Header (`MCP-Protocol-Version: 2025-06-18`).
+ *
+ * A pinned constant rather than a per-server setting: version negotiation is the protocol's own
+ * mechanism, and letting an application declare a version per server would put a wire-compatibility
+ * decision in application config where nobody can reason about it.
+ */
+export declare const MCP_CLIENT_PROTOCOL_VERSION = "2025-06-18";
+/** What this client tells a server it is. Sent as `clientInfo` in `initialize`. */
+export declare const MCP_CLIENT_INFO: {
+    readonly name: "wildo-engine";
+    readonly version: "1";
+};
+/**
+ * How a call to somebody else's server ended.
+ *
+ * A CLOSED vocabulary, and the reason it is not `{ ok: boolean; error?: string }` is the whole point
+ * of #491: an MCP call is a REMOTE call, and the mistake to avoid is modelling it as a second kind
+ * of local function. A local function returns or throws. This can be refused before it leaves, never
+ * arrive, arrive late, arrive malformed, or arrive perfectly carrying the server's own failure — and
+ * those five mean different things to the agent and to whoever reads the audit trail.
+ */
+export declare enum McpOutcomeKind {
+    /** The call completed and the server answered. */
+    OK = "ok",
+    /**
+     * REFUSED before any request left this process — the target failed the outbound guard (a private
+     * or reserved address, credentials in the URL, a special-use hostname). Distinct from UNREACHABLE
+     * because nothing was contacted: this is our own refusal, and it names a misconfiguration rather
+     * than somebody else's outage.
+     */
+    REFUSED_TARGET = "refused_target",
+    /** The request left and no answer came back — DNS, connection, TLS, or a non-2xx HTTP status. */
+    UNREACHABLE = "unreachable",
+    /** The bounded budget elapsed first. Kept apart from UNREACHABLE: a slow server is not a down one. */
+    TIMED_OUT = "timed_out",
+    /**
+     * The server answered, and the answer was not the protocol — a JSON-RPC `error`, an unparseable
+     * body, or a result missing the field its method must return. Someone's server is wrong; that is
+     * a different remedy from a network fault and must not be reported as one.
+     */
+    PROTOCOL_ERROR = "protocol_error",
+    /**
+     * The TOOL failed, and the protocol worked perfectly — a `tools/call` result carrying
+     * `isError: true`.
+     *
+     * spec-cite: MCP 2025-06-18 — Tools §Error Handling ("Tool Execution Errors: Reported in tool
+     * results with `isError: true`", listed against Protocol Errors as the other mechanism).
+     *
+     * This is the outcome an AGENT should reason about and retry or route around, and the one an
+     * operator should NOT be paged for. Collapsing it into PROTOCOL_ERROR would make every rate limit
+     * and every business-rule refusal look like a broken server.
+     */
+    TOOL_ERROR = "tool_error"
+}
+/** One tool a server offers, as far as an agent needs it. */
+export interface McpToolDescriptor {
+    name: string;
+    /** Optional human-readable name for display. */
+    title?: string;
+    description?: string;
+    /** JSON Schema for the tool's parameters, passed through to the model unchanged. */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * A live session with one server.
+ *
+ * `sessionId` is `null` for a stateless server, and that is not a degraded case — assigning one is
+ * optional.
+ *
+ * spec-cite: MCP 2025-06-18 — Transports §Session Management (a server "MAY assign a session ID at
+ * initialization time, by including it in an `Mcp-Session-Id` header"; when one is returned the
+ * client "MUST include it in the `Mcp-Session-Id` header on all of their subsequent HTTP requests").
+ */
+export interface McpSession {
+    readonly server: FlowsActors_McpServer;
+    readonly sessionId: string | null;
+    readonly tools: readonly McpToolDescriptor[];
+}
+/**
+ * Why a call did not produce a usable answer. Carries no URL — see `destinationHost`.
+ *
+ * ONE type shared by both outcomes rather than a failure arm written twice: every caller handles
+ * failure identically (report it, contribute no tool, let the turn continue), and two structurally
+ * identical arms would drift the moment one grew a field.
+ */
+export interface McpFailureOutcome {
+    kind: Exclude<McpOutcomeKind, McpOutcomeKind.OK>;
+    /** The server ref, so a reader can find the declaration that named it. */
+    mcpServerRef: string;
+    /** HOST only. An MCP endpoint routinely carries a tenant or session id in its path. */
+    destinationHost: string;
+    /** A short, non-sensitive account of what went wrong, safe for a log and an audit row. */
+    detail: string;
+}
+export type McpDiscoveryOutcome = {
+    kind: McpOutcomeKind.OK;
+    session: McpSession;
+} | McpFailureOutcome;
+export type McpToolCallOutcome = {
+    kind: McpOutcomeKind.OK;
+    /** Unstructured result blocks, passed to the model as the tool's answer. */
+    content: unknown[];
+    /** Present when the tool declares an output schema and returned structured data. */
+    structuredContent?: Record<string, unknown>;
+} | McpFailureOutcome;
+//# sourceMappingURL=mcp-client.backend.definitions.d.ts.map

package/dist/esm/flows-actors/models/mcp-client.backend.definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.backend.definitions.d.ts","sourceRoot":"","sources":["../../../../src/flows-actors/models/mcp-client.backend.definitions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAMnE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,eAAe,CAAC;AAExD,mFAAmF;AACnF,eAAO,MAAM,eAAe;;;CAAkD,CAAC;AAE/E;;;;;;;;GAQG;AACH,oBAAY,cAAc;IACxB,kDAAkD;IAClD,EAAE,OAAO;IACT;;;;;OAKG;IACH,cAAc,mBAAmB;IACjC,iGAAiG;IACjG,WAAW,gBAAgB;IAC3B,sGAAsG;IACtG,SAAS,cAAc;IACvB;;;;OAIG;IACH,cAAc,mBAAmB;IACjC;;;;;;;;;;OAUG;IACH,UAAU,eAAe;CAC1B;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAC,cAAc,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC;IACjD,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,eAAe,EAAE,MAAM,CAAC;IACxB,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,cAAc,CAAC,EAAE,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GAChD,iBAAiB,CAAC;AAEtB,MAAM,MAAM,kBAAkB,GAC1B;IACE,IAAI,EAAE,cAAc,CAAC,EAAE,CAAC;IACxB,4EAA4E;IAC5E,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C,GACD,iBAAiB,CAAC"}

package/dist/esm/flows-actors/models/mcp-client.backend.definitions.js

@@ -0,0 +1,62 @@
+//===============================================================
+//  MCP CLIENT — the contract a turn reads
+//===============================================================
+/**
+ * The protocol revision this client speaks, sent as `protocolVersion` in `initialize` and as the
+ * `MCP-Protocol-Version` header on every later request.
+ *
+ * spec-cite: MCP 2025-06-18 — Lifecycle §Version Negotiation (the client MUST send a protocol
+ * version it supports, and SHOULD send the latest it supports) and Transports §Protocol Version
+ * Header (`MCP-Protocol-Version: 2025-06-18`).
+ *
+ * A pinned constant rather than a per-server setting: version negotiation is the protocol's own
+ * mechanism, and letting an application declare a version per server would put a wire-compatibility
+ * decision in application config where nobody can reason about it.
+ */
+export const MCP_CLIENT_PROTOCOL_VERSION = '2025-06-18';
+/** What this client tells a server it is. Sent as `clientInfo` in `initialize`. */
+export const MCP_CLIENT_INFO = { name: 'wildo-engine', version: '1' };
+/**
+ * How a call to somebody else's server ended.
+ *
+ * A CLOSED vocabulary, and the reason it is not `{ ok: boolean; error?: string }` is the whole point
+ * of #491: an MCP call is a REMOTE call, and the mistake to avoid is modelling it as a second kind
+ * of local function. A local function returns or throws. This can be refused before it leaves, never
+ * arrive, arrive late, arrive malformed, or arrive perfectly carrying the server's own failure — and
+ * those five mean different things to the agent and to whoever reads the audit trail.
+ */
+export var McpOutcomeKind;
+(function (McpOutcomeKind) {
+    /** The call completed and the server answered. */
+    McpOutcomeKind["OK"] = "ok";
+    /**
+     * REFUSED before any request left this process — the target failed the outbound guard (a private
+     * or reserved address, credentials in the URL, a special-use hostname). Distinct from UNREACHABLE
+     * because nothing was contacted: this is our own refusal, and it names a misconfiguration rather
+     * than somebody else's outage.
+     */
+    McpOutcomeKind["REFUSED_TARGET"] = "refused_target";
+    /** The request left and no answer came back — DNS, connection, TLS, or a non-2xx HTTP status. */
+    McpOutcomeKind["UNREACHABLE"] = "unreachable";
+    /** The bounded budget elapsed first. Kept apart from UNREACHABLE: a slow server is not a down one. */
+    McpOutcomeKind["TIMED_OUT"] = "timed_out";
+    /**
+     * The server answered, and the answer was not the protocol — a JSON-RPC `error`, an unparseable
+     * body, or a result missing the field its method must return. Someone's server is wrong; that is
+     * a different remedy from a network fault and must not be reported as one.
+     */
+    McpOutcomeKind["PROTOCOL_ERROR"] = "protocol_error";
+    /**
+     * The TOOL failed, and the protocol worked perfectly — a `tools/call` result carrying
+     * `isError: true`.
+     *
+     * spec-cite: MCP 2025-06-18 — Tools §Error Handling ("Tool Execution Errors: Reported in tool
+     * results with `isError: true`", listed against Protocol Errors as the other mechanism).
+     *
+     * This is the outcome an AGENT should reason about and retry or route around, and the one an
+     * operator should NOT be paged for. Collapsing it into PROTOCOL_ERROR would make every rate limit
+     * and every business-rule refusal look like a broken server.
+     */
+    McpOutcomeKind["TOOL_ERROR"] = "tool_error";
+})(McpOutcomeKind || (McpOutcomeKind = {}));
+//# sourceMappingURL=mcp-client.backend.definitions.js.map

package/dist/esm/flows-actors/models/mcp-client.backend.definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.backend.definitions.js","sourceRoot":"","sources":["../../../../src/flows-actors/models/mcp-client.backend.definitions.ts"],"names":[],"mappings":"AAEA,iEAAiE;AACjE,0CAA0C;AAC1C,iEAAiE;AAEjE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,YAAY,CAAC;AAExD,mFAAmF;AACnF,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,EAAW,CAAC;AAE/E;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,cAgCX;AAhCD,WAAY,cAAc;IACxB,kDAAkD;IAClD,2BAAS,CAAA;IACT;;;;;OAKG;IACH,mDAAiC,CAAA;IACjC,iGAAiG;IACjG,6CAA2B,CAAA;IAC3B,sGAAsG;IACtG,yCAAuB,CAAA;IACvB;;;;OAIG;IACH,mDAAiC,CAAA;IACjC;;;;;;;;;;OAUG;IACH,2CAAyB,CAAA;AAC3B,CAAC,EAhCW,cAAc,KAAd,cAAc,QAgCzB","sourcesContent":["import type { FlowsActors_McpServer } from '@wildo-ai/saas-models';\n\n//===============================================================\n//  MCP CLIENT — the contract a turn reads\n//===============================================================\n\n/**\n * The protocol revision this client speaks, sent as `protocolVersion` in `initialize` and as the\n * `MCP-Protocol-Version` header on every later request.\n *\n * spec-cite: MCP 2025-06-18 — Lifecycle §Version Negotiation (the client MUST send a protocol\n * version it supports, and SHOULD send the latest it supports) and Transports §Protocol Version\n * Header (`MCP-Protocol-Version: 2025-06-18`).\n *\n * A pinned constant rather than a per-server setting: version negotiation is the protocol's own\n * mechanism, and letting an application declare a version per server would put a wire-compatibility\n * decision in application config where nobody can reason about it.\n */\nexport const MCP_CLIENT_PROTOCOL_VERSION = '2025-06-18';\n\n/** What this client tells a server it is. Sent as `clientInfo` in `initialize`. */\nexport const MCP_CLIENT_INFO = { name: 'wildo-engine', version: '1' } as const;\n\n/**\n * How a call to somebody else's server ended.\n *\n * A CLOSED vocabulary, and the reason it is not `{ ok: boolean; error?: string }` is the whole point\n * of #491: an MCP call is a REMOTE call, and the mistake to avoid is modelling it as a second kind\n * of local function. A local function returns or throws. This can be refused before it leaves, never\n * arrive, arrive late, arrive malformed, or arrive perfectly carrying the server's own failure — and\n * those five mean different things to the agent and to whoever reads the audit trail.\n */\nexport enum McpOutcomeKind {\n  /** The call completed and the server answered. */\n  OK = 'ok',\n  /**\n   * REFUSED before any request left this process — the target failed the outbound guard (a private\n   * or reserved address, credentials in the URL, a special-use hostname). Distinct from UNREACHABLE\n   * because nothing was contacted: this is our own refusal, and it names a misconfiguration rather\n   * than somebody else's outage.\n   */\n  REFUSED_TARGET = 'refused_target',\n  /** The request left and no answer came back — DNS, connection, TLS, or a non-2xx HTTP status. */\n  UNREACHABLE = 'unreachable',\n  /** The bounded budget elapsed first. Kept apart from UNREACHABLE: a slow server is not a down one. */\n  TIMED_OUT = 'timed_out',\n  /**\n   * The server answered, and the answer was not the protocol — a JSON-RPC `error`, an unparseable\n   * body, or a result missing the field its method must return. Someone's server is wrong; that is\n   * a different remedy from a network fault and must not be reported as one.\n   */\n  PROTOCOL_ERROR = 'protocol_error',\n  /**\n   * The TOOL failed, and the protocol worked perfectly — a `tools/call` result carrying\n   * `isError: true`.\n   *\n   * spec-cite: MCP 2025-06-18 — Tools §Error Handling (\"Tool Execution Errors: Reported in tool\n   * results with `isError: true`\", listed against Protocol Errors as the other mechanism).\n   *\n   * This is the outcome an AGENT should reason about and retry or route around, and the one an\n   * operator should NOT be paged for. Collapsing it into PROTOCOL_ERROR would make every rate limit\n   * and every business-rule refusal look like a broken server.\n   */\n  TOOL_ERROR = 'tool_error',\n}\n\n/** One tool a server offers, as far as an agent needs it. */\nexport interface McpToolDescriptor {\n  name: string;\n  /** Optional human-readable name for display. */\n  title?: string;\n  description?: string;\n  /** JSON Schema for the tool's parameters, passed through to the model unchanged. */\n  inputSchema: Record<string, unknown>;\n}\n\n/**\n * A live session with one server.\n *\n * `sessionId` is `null` for a stateless server, and that is not a degraded case — assigning one is\n * optional.\n *\n * spec-cite: MCP 2025-06-18 — Transports §Session Management (a server \"MAY assign a session ID at\n * initialization time, by including it in an `Mcp-Session-Id` header\"; when one is returned the\n * client \"MUST include it in the `Mcp-Session-Id` header on all of their subsequent HTTP requests\").\n */\nexport interface McpSession {\n  readonly server: FlowsActors_McpServer;\n  readonly sessionId: string | null;\n  readonly tools: readonly McpToolDescriptor[];\n}\n\n/**\n * Why a call did not produce a usable answer. Carries no URL — see `destinationHost`.\n *\n * ONE type shared by both outcomes rather than a failure arm written twice: every caller handles\n * failure identically (report it, contribute no tool, let the turn continue), and two structurally\n * identical arms would drift the moment one grew a field.\n */\nexport interface McpFailureOutcome {\n  kind: Exclude<McpOutcomeKind, McpOutcomeKind.OK>;\n  /** The server ref, so a reader can find the declaration that named it. */\n  mcpServerRef: string;\n  /** HOST only. An MCP endpoint routinely carries a tenant or session id in its path. */\n  destinationHost: string;\n  /** A short, non-sensitive account of what went wrong, safe for a log and an audit row. */\n  detail: string;\n}\n\nexport type McpDiscoveryOutcome =\n  | { kind: McpOutcomeKind.OK; session: McpSession }\n  | McpFailureOutcome;\n\nexport type McpToolCallOutcome =\n  | {\n      kind: McpOutcomeKind.OK;\n      /** Unstructured result blocks, passed to the model as the tool's answer. */\n      content: unknown[];\n      /** Present when the tool declares an output schema and returned structured data. */\n      structuredContent?: Record<string, unknown>;\n    }\n  | McpFailureOutcome;\n"]}

package/dist/esm/flows-actors/services/__tests__/fixtures/meta-workflow-evaluation-treatment.test-fixture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta-workflow-evaluation-treatment.test-fixture.d.ts","sourceRoot":"","sources":["../../../../../../../src/flows-actors/services/__tests__/fixtures/meta-workflow-evaluation-treatment.test-fixture.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,0CAA0C,EAChD,MAAM,sCAAsC,CAAC;AAS9C,MAAM,WAAW,0CAA0C;IACzD,UAAU,EAAE,0CAA0C,CAAC;IACvD,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wBAAgB,gDAAgD,CAC9D,MAAM,SAAY,EAClB,WAAW,UAAQ,GAClB,0CAA0C,CAiM5C"}
+{"version":3,"file":"meta-workflow-evaluation-treatment.test-fixture.d.ts","sourceRoot":"","sources":["../../../../../../src/flows-actors/services/__tests__/fixtures/meta-workflow-evaluation-treatment.test-fixture.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,0CAA0C,EAChD,MAAM,sCAAsC,CAAC;AAS9C,MAAM,WAAW,0CAA0C;IACzD,UAAU,EAAE,0CAA0C,CAAC;IACvD,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wBAAgB,gDAAgD,CAC9D,MAAM,SAAY,EAClB,WAAW,UAAQ,GAClB,0CAA0C,CAiM5C"}

package/dist/esm/flows-actors/services/actors-system.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actors-system.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/flows-actors/services/actors-system.backend.service.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAG1B,OAAO,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAC7F,OAAO,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAC9G,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAWhE,OAAO,EACL,WAAW,EACX,qBAAqB,EAEtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAmBL,KAAK,iBAAiB,EAMtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EAOxB,MAAM,uBAAuB,CAAC;AAa/B;;;;;;;;;;;;;GAaG;AACH,qBACa,0BAA0B;IAKA,OAAO,CAAC,QAAQ,CAAC,MAAM;IACV,OAAO,CAAC,QAAQ,CAAC,YAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa;IANjF,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;gBAG3B,MAAM,EAAE,aAAa,EACR,YAAY,EAAE,0BAA0B,EACjC,mBAAmB,EAAE,0BAA0B,EACrD,aAAa,EAAE,oBAAoB;IAYvG;;;OAGG;IACU,YAAY,CAAC,SAAS,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA4B3F;;OAEG;YACW,oBAAoB;IAsClC;;OAEG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA0B3B;;OAEG;IACI,kBAAkB,IAAI,WAAW,EAAE;IAM1C;;OAEG;IACI,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAQ1D;;OAEG;IACI,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW;IAmBrD;;OAEG;IACI,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAYxE;;OAEG;IACI,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAenE,YAAY,IAAI;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB;IAoCY,mBAAmB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,YAAY,CAAC,EAAE,iBAAiB,GAC/B,OAAO,CAAC,kBAAkB,CAAC;IAqO9B,sFAAsF;IACtF,OAAO,CAAC,wBAAwB;IA8DhC;;;;OAIG;YACW,4BAA4B;IAgD1C,qFAAqF;YACvE,wBAAwB;IAuDtC,oFAAoF;YACtE,oBAAoB;IAgBlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;YAwBzB,kBAAkB;IA8EhC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAM;IAElD;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,0BAA0B;YAsBpB,sBAAsB;IAoDpC,gFAAgF;IAChF;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAiBjC,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,eAAe;IAWvB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;YAcf,eAAe;IA0D7B,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,uBAAuB;CAgBhC"}
+{"version":3,"file":"actors-system.backend.service.d.ts","sourceRoot":"","sources":["../../../../src/flows-actors/services/actors-system.backend.service.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAG1B,OAAO,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAC7F,OAAO,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAC9G,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAWhE,OAAO,EACL,WAAW,EACX,qBAAqB,EAEtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAmBL,KAAK,iBAAiB,EAMtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EAOxB,MAAM,uBAAuB,CAAC;AAa/B;;;;;;;;;;;;;GAaG;AACH,qBACa,0BAA0B;IAKA,OAAO,CAAC,QAAQ,CAAC,MAAM;IACV,OAAO,CAAC,QAAQ,CAAC,YAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa;IANjF,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;gBAG3B,MAAM,EAAE,aAAa,EACR,YAAY,EAAE,0BAA0B,EACjC,mBAAmB,EAAE,0BAA0B,EACrD,aAAa,EAAE,oBAAoB;IAYvG;;;OAGG;IACU,YAAY,CAAC,SAAS,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA4B3F;;OAEG;YACW,oBAAoB;IAsClC;;OAEG;IACH,OAAO,CAAC,eAAe;IAiBvB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA0B3B;;OAEG;IACI,kBAAkB,IAAI,WAAW,EAAE;IAM1C;;OAEG;IACI,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAQ1D;;OAEG;IACI,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW;IAmBrD;;OAEG;IACI,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAYxE;;OAEG;IACI,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAenE,YAAY,IAAI;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB;IAoCY,mBAAmB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,YAAY,CAAC,EAAE,iBAAiB,GAC/B,OAAO,CAAC,kBAAkB,CAAC;IAmO9B,sFAAsF;IACtF,OAAO,CAAC,wBAAwB;IA8DhC;;;;OAIG;YACW,4BAA4B;IAgD1C,qFAAqF;YACvE,wBAAwB;IAuDtC,oFAAoF;YACtE,oBAAoB;IAgBlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;YAwBzB,kBAAkB;IA8EhC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAM;IAElD;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,0BAA0B;YAsBpB,sBAAsB;IAoDpC,gFAAgF;IAChF;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAiBjC,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,eAAe;IAWvB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;YAcf,eAAe;IA0D7B,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,uBAAuB;CAgBhC"}

package/dist/esm/flows-actors/services/actors-system.backend.service.js

@@ -407,7 +407,6 @@ let ActorsSystemBackendService = class ActorsSystemBackendService {
                 // No synthesis: the schema documents its absence for exactly this state.
                 roundBudget: plan.roundBudget,
                 status: DeliberationStatus.REJECTED,
-                charterInputsDigests: plan.charterInputsDigests,
                 humanDecision: null,
                 startedAt,
                 finishedAt: new Date().toISOString(),
@@ -436,7 +435,6 @@ let ActorsSystemBackendService = class ActorsSystemBackendService {
             concurrence: ActorsSystemBackendService_1.computeConcurrence(synthesis.winnerRef, finalVerdicts),
             roundBudget: plan.roundBudget,
             status,
-            charterInputsDigests: plan.charterInputsDigests,
             humanDecision: null,
             startedAt,
             finishedAt: new Date().toISOString(),