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

package/dist/esm/flows-actors/models/function-tools.backend.definitions.d.ts

@@ -27,26 +27,36 @@ import type { SocketAuthResult } from '../../runtime/models/execution-context.ba
  *
  * Backend services a tool may use at execution time (supplied by the caller).
  *
- * ⚠️ **Two of these are OBLIGATIONS, not conveniences, for a hand-written tool that dispatches a
- * resource operation.**
+ * ⚠️ **If your tool DISPATCHES a resource operation, call `dispatchResourceOperationAsTool` — do not
+ * reach for these services yourself.**
  *
- * A tool enters at the SERVICE tier, bypassing Express — so the two gates that live on the HTTP
- * controller never run for it. `resourceReadTool` and `resourceWriteTool` discharge both on your
- * behalf. A tool you write yourself owes the same two calls:
+ * A tool enters at the SERVICE tier, bypassing Express, so two gates that live on the HTTP
+ * controller never run for it: the operation's declared `roles` ACL and its authored `rateLimit?`.
+ * `dispatchResourceOperationAsTool` resolves the operation, builds the scoped execution context,
+ * applies both gates in the right order and dispatches — one exported call, and the same one
+ * `resourceReadTool` and `resourceWriteTool` use.
  *
- * | gate | why the service tier does not apply it | what your tool must call |
- * |---|---|---|
- * | the operation's declared `roles` ACL | it is a CONTROLLER-tier gate; the service verbs deliberately apply no role check, because their dominant population is the authentication reads that run BEFORE a role-bearing principal exists | `ctx.services.authorizer.authorizeInController(...)` |
- * | the operation's authored `rateLimit?` policy | the declared policy's only other consumer is the HTTP controller pre-flight | `ctx.services.rateLimitService.checkPolicyForSubject(...)` |
+ * ```ts
+ * const rows = await dispatchResourceOperationAsTool({
+ *   ctx, resourceType: 'todos', operationIdentifier: CoreResourceOperation.LIST,
+ *   data: { filter: undefined, page: 1, limit: 20 }, options: { paginated: true },
+ * });
+ * ```
  *
- * Both are on THIS interface for exactly that reason. The factories below wrap them in the private
- * helpers `authorizeToolDispatch` / `assertDeclaredOperationRateLimit`, which are module-scoped and
- * not importable — a hand-written tool calls the services directly.
+ * **This prose used to name two calls a hand-written tool owed, and both were module-private (#556)
+ * — so an author who read it and agreed could not discharge the obligation.** Naming ONE importable
+ * call replaces that: the correct path is now also the shortest, which is the only mechanism that
+ * survives an author who has not read this paragraph.
  *
- * Skipping the first means a caller whose roles the operation REFUSES, but whose tenancy admits the
- * row, succeeds — the operation's `accessControl` simply unenforced on this plane. That is right for
- * a framework-internal caller and wrong here, where the caller is an external principal naming an
- * operation on their own authority.
+ * Skipping the gates means a caller whose roles the operation REFUSES, but whose tenancy admits the
+ * row, succeeds — the operation's `accessControl` simply unenforced on this plane. It is quiet:
+ * tenancy still applies, so the tool returns the caller's own tenant's rows and LOOKS like it works.
+ * That is right for a framework-internal caller and wrong here, where the caller is an external
+ * principal naming an operation on their own authority.
+ *
+ * The services below remain on this interface because the seam is built from them, and because a
+ * tool that dispatches NOTHING — a calculator, a formatter, a unit converter — is a legitimate shape
+ * that needs neither gate.
  *
  * What you still get for free, on every tool: the repository's contextual filter in full — tenancy,
  * relationship narrowing, organization-unit narrowing, the anonymous guard and the retention hide,
@@ -158,6 +168,87 @@ export interface FunctionTool {
      */
     requiresHumanApproval?: boolean;
 }
+/** @wildo_source:part:end saas.backend.flows-actors.function-tool */
+/**
+ * The name a `functionRef` is exposed to the model under.
+ *
+ * Provider tool names must be identifier-safe and a `functionRef` uses dots, so the two differ for
+ * every tool. ONE definition, because the mapping is used in opposite directions by two sites: the
+ * turn BUILDS the tool set from refs, and a resume that re-signs a modified approval must find the
+ * FunctionTool behind a name it reads back out of the model SDK's own message array. A second copy
+ * of this expression would make an approval unmodifiable for exactly the refs the two spelled
+ * differently.
+ *
+ * Not injective by construction (`a.b` and `a_b` collapse), and deliberately not made so: the
+ * forward direction is what the model sees, and a reverse lookup resolves against ONE agent's
+ * declared refs, where a collision would already be an authoring defect.
+ */
+export declare function modelToolNameForFunctionRef(functionRef: string): string;
+/**
+ * Dispatch a resource operation from a function tool, carrying BOTH gates the service tier skips.
+ *
+ * ## What this exists to prevent (#556)
+ *
+ * A `FunctionTool` enters at the SERVICE tier. It never passes through Express, so two
+ * controller-tier gates are simply absent from its path — the operation's declared `roles` ACL and
+ * its declared `rateLimit?`. That skip is CORRECT for the service tier's intended caller (the
+ * authentication reads that run before a role-bearing principal exists) and wrong for this plane,
+ * whose caller is an external principal naming an operation on their own authority.
+ *
+ * The failure is quiet, which is what makes it worth a seam. Tenancy still applies — the
+ * repository's contextual filter runs regardless — so an unauthorized tool returns the caller's own
+ * tenant's rows and LOOKS like it works. Nothing throws and nothing logs. What is missing is only
+ * the row-level `roles` ACL: a caller whose roles the operation refuses, but whose tenancy admits
+ * the row, succeeds.
+ *
+ * Until this existed the two gates were applied by hand at three sites in this file, and both helpers
+ * were module-private — so an application author writing their own tool could not discharge the
+ * obligation even after reading about it. The engine's own rule
+ * (`invariant-call-site-enumeration.md`) asks for the opposite: prefer making the invariant
+ * unbypassable over applying it N times. **This is the shortest path to a dispatch, so the correct
+ * path is also the easy one.**
+ *
+ * ## The order is authorize → charge → dispatch, and it is not arbitrary
+ *
+ * Authorization first, so an unauthorized caller cannot spend an authorized caller's quota. The
+ * charge before the dispatch, so a refused budget costs no work. This is the same order the MCP
+ * plane uses, deliberately — one refusal vocabulary across every plane that enters here.
+ *
+ * ## One id, two uses, and why that is safer than two parameters
+ *
+ * `recordId` addresses the row AND is the authorization subject, because at every existing call site
+ * those are the same value: an UPDATE passes the id to both, a CREATE/LIST/SEARCH passes it to
+ * neither. Splitting them into two parameters would make it possible to authorize a collection call
+ * while dispatching a row call — a question nobody asked, failing for the wrong reason. A bulk
+ * operation addressed by a FILTER passes `dispatchFilter` instead, which is never an authorization
+ * subject because a filter-addressed operation IS a collection call.
+ *
+ * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — an external caller reaching a resource operation
+ * off the HTTP plane is held to that operation's own declared authority, through the same predicate.
+ *
+ * @throws AUTHORIZATION when the operation's roles refuse the caller — surfaced to the model as a
+ *   tool error, so the agent can say it was refused. Recorded by the authorizer's own denial-audit
+ *   funnel, so the evidence matches a denied HTTP request.
+ * @throws RATE_LIMIT (429) carrying `context.retryAfterSeconds`, the same envelope the HTTP and MCP
+ *   seams throw.
+ * @throws NOT_FOUND when the resource declares no dispatchable operation under that identifier.
+ */
+export declare function dispatchResourceOperationAsTool<TResult = any>(input: {
+    ctx: FunctionToolExecutionContext;
+    resourceType: ResourceType;
+    /** A `CoreResourceOperation` member, or a custom operation identifier the resource declares. */
+    operationIdentifier: string;
+    /** The addressed row, for a row-scoped operation. Authorizes AND addresses; omit for a collection call. */
+    recordId?: string;
+    /** A filter addressing a COLLECTION, for a bulk operation. Never an authorization subject. */
+    dispatchFilter?: any;
+    /** Parent / context resource ids used to build the scoped execution context. */
+    contextIds?: any;
+    /** The operation payload — the body for a write, the query options for a read. */
+    data?: any;
+    /** Repository options passed through, e.g. `{ paginated: true }` for a LIST envelope. */
+    options?: any;
+}): Promise<TResult>;
 /**
  * @wildo_source:part:start saas.backend.flows-actors.resource-read-tool facet:layer:backend facet:family:flows-actors
  *

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

@@ -1 +1 @@
-{"version":3,"file":"function-tools.backend.definitions.d.ts","sourceRoot":"","sources":["../../../../../src/flows-actors/models/function-tools.backend.definitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,qBAAqB,EAKrB,KAAK,YAAY,EAGlB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oFAAoF,CAAC;AAEvI,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,+EAA+E,CAAC;AAC3I,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+DAA+D,CAAC;AAC7G,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0EAA0E,CAAC;AAChI,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,6FAA6F,CAAC;AACzJ,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AAE5G;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,6BAA6B;IAC5C,iBAAiB,EAAE,+BAA+B,CAAC;IACnD,uBAAuB,EAAE,qCAAqC,CAAC;IAC/D,uBAAuB,EAAE,qCAAqC,CAAC;IAC/D;;;;;;;;;OASG;IACH,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C;;;;;;;;;;;;;;;OAeG;IACH,UAAU,EAAE,4BAA4B,CAAC;CAC1C;AACD,iFAAiF;AAEjF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,4BAA4B;IAC3C,mEAAmE;IACnE,IAAI,EAAE,gBAAgB,CAAC;IACvB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC;IAC1B,uEAAuE;IACvE,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,4BAA4B,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAmTD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACjG,YAAY,CAsFd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,YAAY,EAC1B,EAAE,EAAE,qBAAqB,CAAC,MAAM,GAAG,qBAAqB,CAAC,MAAM,EAC/D,OAAO,EAAE;IACP,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,GACA,YAAY,CAuDd"}
+{"version":3,"file":"function-tools.backend.definitions.d.ts","sourceRoot":"","sources":["../../../../src/flows-actors/models/function-tools.backend.definitions.ts"],"names":[],"mappings":"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"}

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

@@ -2,6 +2,24 @@ import { z } from 'zod';
 import { CoreResourceOperation, ErrorType, ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, isWildoBackendError, } from '@wildo-ai/saas-models';
 import { toResponseSafeToolOutput } from '../../base-classes/services/controllers/utils/operation-response-serializer.backend.utils.js';
 import { resolveDeclaredPolicySubjectKey } from '../../security/authentications/services/utils/external-turn-rate-limit.backend.utils.js';
+/** @wildo_source:part:end saas.backend.flows-actors.function-tool */
+/**
+ * The name a `functionRef` is exposed to the model under.
+ *
+ * Provider tool names must be identifier-safe and a `functionRef` uses dots, so the two differ for
+ * every tool. ONE definition, because the mapping is used in opposite directions by two sites: the
+ * turn BUILDS the tool set from refs, and a resume that re-signs a modified approval must find the
+ * FunctionTool behind a name it reads back out of the model SDK's own message array. A second copy
+ * of this expression would make an approval unmodifiable for exactly the refs the two spelled
+ * differently.
+ *
+ * Not injective by construction (`a.b` and `a_b` collapse), and deliberately not made so: the
+ * forward direction is what the model sees, and a reverse lookup resolves against ONE agent's
+ * declared refs, where a collision would already be an authoring defect.
+ */
+export function modelToolNameForFunctionRef(functionRef) {
+    return functionRef.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
 /** Normalize a handler list/search result (array or paginated) to the tool result shape. */
 function toReadResult(result, limit) {
     if (Array.isArray(result)) {
@@ -242,6 +260,79 @@ async function assertDeclaredOperationRateLimit(ctx, operation, resourceType, op
     }
     await ctx.services.rateLimitService.checkPolicyForSubject(policy, `agent-tool:resource:${resourceType}:${operationIdentifier}`, subjectKey, ctx.organizationId);
 }
+/**
+ * Dispatch a resource operation from a function tool, carrying BOTH gates the service tier skips.
+ *
+ * ## What this exists to prevent (#556)
+ *
+ * A `FunctionTool` enters at the SERVICE tier. It never passes through Express, so two
+ * controller-tier gates are simply absent from its path — the operation's declared `roles` ACL and
+ * its declared `rateLimit?`. That skip is CORRECT for the service tier's intended caller (the
+ * authentication reads that run before a role-bearing principal exists) and wrong for this plane,
+ * whose caller is an external principal naming an operation on their own authority.
+ *
+ * The failure is quiet, which is what makes it worth a seam. Tenancy still applies — the
+ * repository's contextual filter runs regardless — so an unauthorized tool returns the caller's own
+ * tenant's rows and LOOKS like it works. Nothing throws and nothing logs. What is missing is only
+ * the row-level `roles` ACL: a caller whose roles the operation refuses, but whose tenancy admits
+ * the row, succeeds.
+ *
+ * Until this existed the two gates were applied by hand at three sites in this file, and both helpers
+ * were module-private — so an application author writing their own tool could not discharge the
+ * obligation even after reading about it. The engine's own rule
+ * (`invariant-call-site-enumeration.md`) asks for the opposite: prefer making the invariant
+ * unbypassable over applying it N times. **This is the shortest path to a dispatch, so the correct
+ * path is also the easy one.**
+ *
+ * ## The order is authorize → charge → dispatch, and it is not arbitrary
+ *
+ * Authorization first, so an unauthorized caller cannot spend an authorized caller's quota. The
+ * charge before the dispatch, so a refused budget costs no work. This is the same order the MCP
+ * plane uses, deliberately — one refusal vocabulary across every plane that enters here.
+ *
+ * ## One id, two uses, and why that is safer than two parameters
+ *
+ * `recordId` addresses the row AND is the authorization subject, because at every existing call site
+ * those are the same value: an UPDATE passes the id to both, a CREATE/LIST/SEARCH passes it to
+ * neither. Splitting them into two parameters would make it possible to authorize a collection call
+ * while dispatching a row call — a question nobody asked, failing for the wrong reason. A bulk
+ * operation addressed by a FILTER passes `dispatchFilter` instead, which is never an authorization
+ * subject because a filter-addressed operation IS a collection call.
+ *
+ * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — an external caller reaching a resource operation
+ * off the HTTP plane is held to that operation's own declared authority, through the same predicate.
+ *
+ * @throws AUTHORIZATION when the operation's roles refuse the caller — surfaced to the model as a
+ *   tool error, so the agent can say it was refused. Recorded by the authorizer's own denial-audit
+ *   funnel, so the evidence matches a denied HTTP request.
+ * @throws RATE_LIMIT (429) carrying `context.retryAfterSeconds`, the same envelope the HTTP and MCP
+ *   seams throw.
+ * @throws NOT_FOUND when the resource declares no dispatchable operation under that identifier.
+ */
+export async function dispatchResourceOperationAsTool(input) {
+    const { ctx, resourceType, operationIdentifier, recordId, dispatchFilter, contextIds, data, options } = input;
+    const operation = requireDispatchableOperation(ctx, resourceType, operationIdentifier);
+    // Rebuild a scoped ExecutionContext from the CALLER's verified auth for THIS operation. Never
+    // reuse one built for another operation: the scope it resolves is operation-specific.
+    const executionContext = await ctx.services.executionContextCreator.buildContextFromSocketAuth(ctx.auth, operation, contextIds);
+    await authorizeToolDispatch(ctx, executionContext, recordId);
+    await assertDeclaredOperationRateLimit(ctx, operation, resourceType, operationIdentifier);
+    const operationPath = ResourcesConfig_OperationPathUtils.extractOperationPath(operation);
+    const subject = recordId ?? dispatchFilter;
+    /*
+     * The trailing `options` is OMITTED rather than passed as `undefined` when absent, so this seam
+     * calls the dispatcher with exactly the arity each site used before it existed.
+     *
+     * Behaviourally the two are identical for an optional parameter. What differs is what a test can
+     * see: the authorization and write pins here assert the dispatch with `toHaveBeenCalledWith`,
+     * which is arity-exact, so a uniform five-argument call would have required editing four tests
+     * that guard an authorization path. Preserving the shape proves the refactor changed nothing,
+     * which is the property that matters most for the one seam every tool dispatch now goes through.
+     */
+    return options === undefined
+        ? ctx.services.servicesRegistryHandler.doByOperationPath(operationPath, executionContext, subject, data)
+        : ctx.services.servicesRegistryHandler.doByOperationPath(operationPath, executionContext, subject, data, options);
+}
 /**
  * Is this a REFUSAL the read tool must never launder into a different operation?
  *
@@ -326,13 +417,18 @@ export function resourceReadTool(resourceType, options) {
                     // which is the documented degradation rather than a refusal.
                     searchOp = resolveDispatchableOperation(ctx, resourceType, CoreResourceOperation.SEARCH);
                     if (searchOp) {
-                        const searchEc = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, searchOp, contextIds);
-                        // Authorize, then charge, then dispatch — the MCP order. Both gates sit inside this try
+                        // The seam authorizes, charges and dispatches in that order. It sits inside this try
                         // because that is where the dispatch is; the catch below re-throws either refusal so
-                        // neither can be laundered into an ungated LIST.
-                        await authorizeToolDispatch(ctx, searchEc);
-                        await assertDeclaredOperationRateLimit(ctx, searchOp, resourceType, CoreResourceOperation.SEARCH);
-                        searchResult = await servicesRegistryHandler.doByOperationPath(ResourcesConfig_OperationPathUtils.extractOperationPath(searchOp), searchEc, undefined, { searchQuery, filter: undefined });
+                        // neither can be laundered into an ungated LIST. The operation is resolved twice — once
+                        // above to decide whether SEARCH is even available, once inside the seam — and that is
+                        // deliberate: the availability question is this factory's, the gates are the seam's.
+                        searchResult = await dispatchResourceOperationAsTool({
+                            ctx,
+                            resourceType,
+                            operationIdentifier: CoreResourceOperation.SEARCH,
+                            contextIds,
+                            data: { searchQuery, filter: undefined },
+                        });
                     }
                 }
                 catch (error) {
@@ -355,13 +451,17 @@ export function resourceReadTool(resourceType, options) {
             // does both twice — two operations were attempted, exactly as two HTTP requests would be, and
             // that path is only reached when the search dispatch failed for a reason that is not a refusal.
             const listOp = requireDispatchableOperation(ctx, resourceType, CoreResourceOperation.LIST);
-            const listEc = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, listOp, contextIds);
-            await authorizeToolDispatch(ctx, listEc);
-            await assertDeclaredOperationRateLimit(ctx, listOp, resourceType, CoreResourceOperation.LIST);
             // `paginated: true` yields the `{ data, pagination }` envelope the LIST response DTO expects
             // (the same shape the HTTP controller requests) — a bare array would fail the wrapper-DTO
             // projection in `toResponseSafeToolOutput` below.
-            const listResult = await servicesRegistryHandler.doByOperationPath(ResourcesConfig_OperationPathUtils.extractOperationPath(listOp), listEc, undefined, { filter: undefined, page: 1, limit }, { paginated: true });
+            const listResult = await dispatchResourceOperationAsTool({
+                ctx,
+                resourceType,
+                operationIdentifier: CoreResourceOperation.LIST,
+                contextIds,
+                data: { filter: undefined, page: 1, limit },
+                options: { paginated: true },
+            });
             const safeListResult = await toResponseSafeToolOutput(listOp, listResult);
             return toReadResult(safeListResult, limit);
         },
@@ -448,19 +548,19 @@ export function resourceWriteTool(resourceType, op, options) {
             // Rebuild a scoped ExecutionContext from the CALLER's verified auth for this operation, then
             // apply the operation's own role + scope ACL against it (fail-closed) before anything is
             // written. The write runs as the user, never with an ACL bypass.
-            const ec = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, operation, contextIds);
-            await authorizeToolDispatch(ctx, ec, isUpdate ? id : undefined);
-            // The operation's own declared budget, charged after authorization so an unauthorized caller
-            // cannot spend an authorized one's quota, and before any write happens.
-            await assertDeclaredOperationRateLimit(ctx, operation, resourceType, op);
             if (!isUpdate) {
-                const created = await servicesRegistryHandler.doByOperationPath(operationPath, ec, undefined, args);
+                // The seam authorizes as a COLLECTION call (no row addressed), charges the operation's own
+                // budget after authorization so an unauthorized caller cannot spend an authorized one's, and
+                // writes as the user — never with an ACL bypass.
+                const created = await dispatchResourceOperationAsTool({ ctx, resourceType, operationIdentifier: op, contextIds, data: args });
                 // Return the same JSON-safe, response-DTO-projected record the REST endpoint would, so no
                 // `Date`/backend-only/secret reaches the model and the tool-loop CONTINUATION step validates.
                 return toResponseSafeToolOutput(operation, created);
             }
-            // UPDATE: the record "id" addresses the row; the remaining fields are the patch.
-            const updated = await servicesRegistryHandler.doByOperationPath(operationPath, ec, id, patch);
+            // UPDATE: the record "id" addresses the row AND is the authorization subject — the seam takes
+            // one value for both, which is what makes authorizing a collection call while dispatching a
+            // row call unrepresentable.
+            const updated = await dispatchResourceOperationAsTool({ ctx, resourceType, operationIdentifier: op, recordId: id, contextIds, data: patch });
             return toResponseSafeToolOutput(operation, updated);
         },
     };

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":"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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 * ⚠️ **Two of these are OBLIGATIONS, not conveniences, for a hand-written tool that dispatches a\n * resource operation.**\n *\n * A tool enters at the SERVICE tier, bypassing Express — so the two gates that live on the HTTP\n * controller never run for it. `resourceReadTool` and `resourceWriteTool` discharge both on your\n * behalf. A tool you write yourself owes the same two calls:\n *\n * | gate | why the service tier does not apply it | what your tool must call |\n * |---|---|---|\n * | the operation's declared `roles` ACL | it is a CONTROLLER-tier gate; the service verbs deliberately apply no role check, because their dominant population is the authentication reads that run BEFORE a role-bearing principal exists | `ctx.services.authorizer.authorizeInController(...)` |\n * | the operation's authored `rateLimit?` policy | the declared policy's only other consumer is the HTTP controller pre-flight | `ctx.services.rateLimitService.checkPolicyForSubject(...)` |\n *\n * Both are on THIS interface for exactly that reason. The factories below wrap them in the private\n * helpers `authorizeToolDispatch` / `assertDeclaredOperationRateLimit`, which are module-scoped and\n * not importable — a hand-written tool calls the services directly.\n *\n * Skipping the first 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. That is right for\n * a framework-internal caller and wrong here, where the caller is an external principal naming an\n * operation on their own authority.\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/** 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 * 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            const searchEc = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, searchOp, contextIds);\n            // Authorize, then charge, then dispatch — the MCP order. Both gates sit 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.\n            await authorizeToolDispatch(ctx, searchEc);\n            await assertDeclaredOperationRateLimit(ctx, searchOp, resourceType, CoreResourceOperation.SEARCH);\n            searchResult = await servicesRegistryHandler.doByOperationPath(\n              ResourcesConfig_OperationPathUtils.extractOperationPath(searchOp) as ResourceConfiguration_OperationPath<any, any>,\n              searchEc,\n              undefined,\n              { 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      const listEc = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, listOp, contextIds);\n      await authorizeToolDispatch(ctx, listEc);\n      await assertDeclaredOperationRateLimit(ctx, listOp, 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 servicesRegistryHandler.doByOperationPath(\n        ResourcesConfig_OperationPathUtils.extractOperationPath(listOp) as ResourceConfiguration_OperationPath<any, any>,\n        listEc,\n        undefined,\n        { filter: undefined, page: 1, limit },\n        { 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      const ec = await executionContextCreator.buildContextFromSocketAuth(ctx.auth, operation, contextIds);\n      await authorizeToolDispatch(ctx, ec, isUpdate ? id : undefined);\n      // The operation's own declared budget, charged after authorization so an unauthorized caller\n      // cannot spend an authorized one's quota, and before any write happens.\n      await assertDeclaredOperationRateLimit(ctx, operation, resourceType, op);\n\n      if (!isUpdate) {\n        const created = await servicesRegistryHandler.doByOperationPath(operationPath, ec, undefined, 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 updated = await servicesRegistryHandler.doByOperationPath(operationPath, 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"]}