@uns-kit/assistant-workflow 2.0.73 → 2.0.75

package/README.md

@@ -20,12 +20,51 @@ pnpm add @uns-kit/assistant-workflow
   MCP, and controlled REPL integrations;
 - deterministic plan/run construction, execution queues, parity checks, and
   safe trace/report serialization;
+- exact host-provided tool handoff selection, bound to a rebuilt invocation,
+  reviewed allowlist, and application-owned argument validator;
 - definition packages, catalog loading, replay, evaluation, and review helpers.
 
 The package deliberately does not contain provider credentials, database access,
 HTTP transport, UNS-specific tool implementations, or application-specific
 workflow definitions.
 
+## Exact Tool Handoffs
+
+When a host has rebuilt a workflow plan and wants to delegate exactly one
+reviewed read-only tool, use `selectAssistantWorkflowApprovedToolInvocation`.
+It does not infer arguments from assistant text or choose among broad tool
+permissions: it binds one host-provided handoff to one invocation in the rebuilt
+plan and rejects ambiguous handoffs.
+
+```ts
+import { selectAssistantWorkflowApprovedToolInvocation } from "@uns-kit/assistant-workflow";
+
+const approved = selectAssistantWorkflowApprovedToolInvocation({
+  invocations: rebuiltRun.toolInvocationQueue.invocations,
+  handoffs: [{
+    invocationId: "fetch_document:read_document",
+    toolName: "read_document",
+    args: { documentId: "manual-1" },
+  }],
+  policies: [{
+    toolName: "read_document",
+    normalizeArgs: (args) =>
+      typeof args.documentId === "string" && Object.keys(args).length === 1
+        ? { documentId: args.documentId }
+        : null,
+  }],
+  allowedToolNames: ["read_document"],
+});
+
+if (approved) {
+  // `approved.args` passed the application-owned exact argument contract.
+}
+```
+
+Tool schemas remain application-owned. The caller must pass only the exact
+controller/host handoff that it already reviewed; multiple handoffs or multiple
+matching policies return `null`.
+
 ## Development
 
 ```bash

package/dist/index.d.ts

@@ -50,6 +50,7 @@ export * from "./run-report.js";
 export * from "./run-report-batch.js";
 export * from "./run-report-json.js";
 export * from "./tool-invocations.js";
+export * from "./tool-handoffs.js";
 export * from "./tool-provider-executors.js";
 export * from "./tool-result-cache.js";
 export * from "./tool-runtime.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,qCAAqC,CAAC;AACpD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,qCAAqC,CAAC;AACpD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -50,6 +50,7 @@ export * from "./run-report.js";
 export * from "./run-report-batch.js";
 export * from "./run-report-json.js";
 export * from "./tool-invocations.js";
+export * from "./tool-handoffs.js";
 export * from "./tool-provider-executors.js";
 export * from "./tool-result-cache.js";
 export * from "./tool-runtime.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,qCAAqC,CAAC;AACpD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC","sourcesContent":["export * from \"./clarification-policy.js\";\nexport * from \"./decision.js\";\nexport * from \"./definition.js\";\nexport * from \"./definition-catalog.js\";\nexport * from \"./definition-catalog-replay.js\";\nexport * from \"./definition-diagnostics.js\";\nexport * from \"./definition-diff.js\";\nexport * from \"./definition-json.js\";\nexport * from \"./definition-manifest.js\";\nexport * from \"./definition-package.js\";\nexport * from \"./definition-package-executor.js\";\nexport * from \"./definition-package-execution-json.js\";\nexport * from \"./definition-package-execution-replay.js\";\nexport * from \"./definition-package-loader.js\";\nexport * from \"./definition-package-resolver.js\";\nexport * from \"./definition-package-review.js\";\nexport * from \"./definition-package-replay.js\";\nexport * from \"./definition-package-run.js\";\nexport * from \"./definition-package-run-report.js\";\nexport * from \"./definition-package-selection.js\";\nexport * from \"./definition-package-smoke.js\";\nexport * from \"./definition-tuning.js\";\nexport * from \"./definition-tuning-approval.js\";\nexport * from \"./definition-tuning-json.js\";\nexport * from \"./definition-tuning-promotion.js\";\nexport * from \"./definition-tuning-replay.js\";\nexport * from \"./definition-tuning-review.js\";\nexport * from \"./definition-tuning-review-artifact.js\";\nexport * from \"./definition-tuning-source-patch.js\";\nexport * from \"./direct-route-invocation.js\";\nexport * from \"./direct-route-policy.js\";\nexport * from \"./eval-case.js\";\nexport * from \"./eval-replay.js\";\nexport * from \"./eval-result.js\";\nexport * from \"./eval-runner.js\";\nexport * from \"./eval-suite.js\";\nexport * from \"./execution-plan.js\";\nexport * from \"./hosted-tool-policy.js\";\nexport * from \"./memory-policy.js\";\nexport * from \"./memory-updates.js\";\nexport * from \"./outcome.js\";\nexport * from \"./outcome-trace.js\";\nexport * from \"./policy-resolution.js\";\nexport * from \"./planner-compiler.js\";\nexport * from \"./planning.js\";\nexport * from \"./run.js\";\nexport * from \"./run-parity.js\";\nexport * from \"./run-evaluation.js\";\nexport * from \"./run-report.js\";\nexport * from \"./run-report-batch.js\";\nexport * from \"./run-report-json.js\";\nexport * from \"./tool-invocations.js\";\nexport * from \"./tool-provider-executors.js\";\nexport * from \"./tool-result-cache.js\";\nexport * from \"./tool-runtime.js\";\nexport * from \"./tool-selection-evaluation.js\";\nexport * from \"./tool-selection-json.js\";\nexport * from \"./tool-selection-policy.js\";\nexport * from \"./tool-selection-rules.js\";\nexport * from \"./tool-selection-replay.js\";\nexport * from \"./tool-selection-trace-export.js\";\nexport * from \"./tool-results.js\";\nexport * from \"./trace-events.js\";\nexport * from \"./trace-payload.js\";\nexport * from \"./trace-stages.js\";\nexport * from \"./trace-report.js\";\nexport * from \"./trace-replay.js\";\nexport * from \"./tool-bindings.js\";\nexport * from \"./tool-capabilities.js\";\nexport * from \"./tool-executor.js\";\nexport * from \"./tool-fixtures.js\";\nexport * from \"./value-readers.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,qCAAqC,CAAC;AACpD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC","sourcesContent":["export * from \"./clarification-policy.js\";\nexport * from \"./decision.js\";\nexport * from \"./definition.js\";\nexport * from \"./definition-catalog.js\";\nexport * from \"./definition-catalog-replay.js\";\nexport * from \"./definition-diagnostics.js\";\nexport * from \"./definition-diff.js\";\nexport * from \"./definition-json.js\";\nexport * from \"./definition-manifest.js\";\nexport * from \"./definition-package.js\";\nexport * from \"./definition-package-executor.js\";\nexport * from \"./definition-package-execution-json.js\";\nexport * from \"./definition-package-execution-replay.js\";\nexport * from \"./definition-package-loader.js\";\nexport * from \"./definition-package-resolver.js\";\nexport * from \"./definition-package-review.js\";\nexport * from \"./definition-package-replay.js\";\nexport * from \"./definition-package-run.js\";\nexport * from \"./definition-package-run-report.js\";\nexport * from \"./definition-package-selection.js\";\nexport * from \"./definition-package-smoke.js\";\nexport * from \"./definition-tuning.js\";\nexport * from \"./definition-tuning-approval.js\";\nexport * from \"./definition-tuning-json.js\";\nexport * from \"./definition-tuning-promotion.js\";\nexport * from \"./definition-tuning-replay.js\";\nexport * from \"./definition-tuning-review.js\";\nexport * from \"./definition-tuning-review-artifact.js\";\nexport * from \"./definition-tuning-source-patch.js\";\nexport * from \"./direct-route-invocation.js\";\nexport * from \"./direct-route-policy.js\";\nexport * from \"./eval-case.js\";\nexport * from \"./eval-replay.js\";\nexport * from \"./eval-result.js\";\nexport * from \"./eval-runner.js\";\nexport * from \"./eval-suite.js\";\nexport * from \"./execution-plan.js\";\nexport * from \"./hosted-tool-policy.js\";\nexport * from \"./memory-policy.js\";\nexport * from \"./memory-updates.js\";\nexport * from \"./outcome.js\";\nexport * from \"./outcome-trace.js\";\nexport * from \"./policy-resolution.js\";\nexport * from \"./planner-compiler.js\";\nexport * from \"./planning.js\";\nexport * from \"./run.js\";\nexport * from \"./run-parity.js\";\nexport * from \"./run-evaluation.js\";\nexport * from \"./run-report.js\";\nexport * from \"./run-report-batch.js\";\nexport * from \"./run-report-json.js\";\nexport * from \"./tool-invocations.js\";\nexport * from \"./tool-handoffs.js\";\nexport * from \"./tool-provider-executors.js\";\nexport * from \"./tool-result-cache.js\";\nexport * from \"./tool-runtime.js\";\nexport * from \"./tool-selection-evaluation.js\";\nexport * from \"./tool-selection-json.js\";\nexport * from \"./tool-selection-policy.js\";\nexport * from \"./tool-selection-rules.js\";\nexport * from \"./tool-selection-replay.js\";\nexport * from \"./tool-selection-trace-export.js\";\nexport * from \"./tool-results.js\";\nexport * from \"./trace-events.js\";\nexport * from \"./trace-payload.js\";\nexport * from \"./trace-stages.js\";\nexport * from \"./trace-report.js\";\nexport * from \"./trace-replay.js\";\nexport * from \"./tool-bindings.js\";\nexport * from \"./tool-capabilities.js\";\nexport * from \"./tool-executor.js\";\nexport * from \"./tool-fixtures.js\";\nexport * from \"./value-readers.js\";\n"]}

package/dist/tool-handoffs.d.ts

@@ -0,0 +1,40 @@
+import type { AssistantWorkflowToolInvocation } from "./tool-invocations.js";
+export type AssistantWorkflowToolInvocationHandoffArgs = Readonly<Record<string, unknown>>;
+/**
+ * Controller or host-provided arguments for one exact invocation in a rebuilt
+ * workflow plan. The runtime must never derive a handoff from model text.
+ */
+export type AssistantWorkflowToolInvocationHandoff = {
+    invocationId: string;
+    toolName: string;
+    args: AssistantWorkflowToolInvocationHandoffArgs;
+};
+/**
+ * Application-owned validation for a reviewed, explicitly handed-off tool.
+ * Keeping this as a function lets each application enforce its own precise
+ * argument contract without the workflow package owning tool schemas.
+ */
+export type AssistantWorkflowToolInvocationHandoffPolicy = {
+    toolName: string;
+    normalizeArgs: (args: AssistantWorkflowToolInvocationHandoffArgs) => AssistantWorkflowToolInvocationHandoffArgs | null;
+};
+export type AssistantWorkflowApprovedToolInvocation<TPolicy extends AssistantWorkflowToolInvocationHandoffPolicy = AssistantWorkflowToolInvocationHandoffPolicy> = {
+    policy: TPolicy;
+    invocation: AssistantWorkflowToolInvocation;
+    args: AssistantWorkflowToolInvocationHandoffArgs;
+};
+export type SelectAssistantWorkflowApprovedToolInvocationInput<TPolicy extends AssistantWorkflowToolInvocationHandoffPolicy = AssistantWorkflowToolInvocationHandoffPolicy> = {
+    invocations: readonly AssistantWorkflowToolInvocation[];
+    handoffs: readonly AssistantWorkflowToolInvocationHandoff[];
+    policies: readonly TPolicy[];
+    allowedToolNames: readonly string[];
+};
+/**
+ * Selects one exact, allowlisted invocation from a rebuilt workflow plan.
+ *
+ * This intentionally accepts exactly one controller/host handoff. Multiple
+ * records are rejected rather than silently ignoring broader authorization.
+ * Argument validation remains application-owned through the supplied policy.
+ */
+export declare function selectAssistantWorkflowApprovedToolInvocation<TPolicy extends AssistantWorkflowToolInvocationHandoffPolicy>(input: SelectAssistantWorkflowApprovedToolInvocationInput<TPolicy>): AssistantWorkflowApprovedToolInvocation<TPolicy> | null;
+//# sourceMappingURL=tool-handoffs.d.ts.map

package/dist/tool-handoffs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-handoffs.d.ts","sourceRoot":"","sources":["../src/tool-handoffs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC;AAE7E,MAAM,MAAM,0CAA0C,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE3F;;;GAGG;AACH,MAAM,MAAM,sCAAsC,GAAG;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,0CAA0C,CAAC;CAClD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,CACb,IAAI,EAAE,0CAA0C,KAC7C,0CAA0C,GAAG,IAAI,CAAC;CACxD,CAAC;AAEF,MAAM,MAAM,uCAAuC,CACjD,OAAO,SAAS,4CAA4C,GAAG,4CAA4C,IACzG;IACF,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,+BAA+B,CAAC;IAC5C,IAAI,EAAE,0CAA0C,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,kDAAkD,CAC5D,OAAO,SAAS,4CAA4C,GAAG,4CAA4C,IACzG;IACF,WAAW,EAAE,SAAS,+BAA+B,EAAE,CAAC;IACxD,QAAQ,EAAE,SAAS,sCAAsC,EAAE,CAAC;IAC5D,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,6CAA6C,CAC3D,OAAO,SAAS,4CAA4C,EAE5D,KAAK,EAAE,kDAAkD,CAAC,OAAO,CAAC,GACjE,uCAAuC,CAAC,OAAO,CAAC,GAAG,IAAI,CAgBzD"}

package/dist/tool-handoffs.js

@@ -0,0 +1,33 @@
+/**
+ * Selects one exact, allowlisted invocation from a rebuilt workflow plan.
+ *
+ * This intentionally accepts exactly one controller/host handoff. Multiple
+ * records are rejected rather than silently ignoring broader authorization.
+ * Argument validation remains application-owned through the supplied policy.
+ */
+export function selectAssistantWorkflowApprovedToolInvocation(input) {
+    if (input.handoffs.length !== 1)
+        return null;
+    const allowedToolNames = new Set(input.allowedToolNames);
+    const approved = [];
+    for (const policy of input.policies) {
+        if (!allowedToolNames.has(policy.toolName))
+            continue;
+        for (const invocation of input.invocations) {
+            if (invocation.toolName !== policy.toolName)
+                continue;
+            const handoff = findExactHandoff(input.handoffs, invocation);
+            if (!handoff)
+                continue;
+            const args = policy.normalizeArgs(handoff.args);
+            if (args)
+                approved.push({ policy, invocation, args });
+        }
+    }
+    return approved.length === 1 ? approved[0] ?? null : null;
+}
+function findExactHandoff(handoffs, invocation) {
+    const matches = handoffs.filter((handoff) => handoff.invocationId === invocation.id && handoff.toolName === invocation.toolName);
+    return matches.length === 1 ? matches[0] ?? null : null;
+}
+//# sourceMappingURL=tool-handoffs.js.map

package/dist/tool-handoffs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-handoffs.js","sourceRoot":"","sources":["../src/tool-handoffs.ts"],"names":[],"mappings":"AA2CA;;;;;;GAMG;AACH,MAAM,UAAU,6CAA6C,CAG3D,KAAkE;IAElE,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE7C,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAuD,EAAE,CAAC;IACxE,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC;YAAE,SAAS;QACrD,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;YAC3C,IAAI,UAAU,CAAC,QAAQ,KAAK,MAAM,CAAC,QAAQ;gBAAE,SAAS;YACtD,MAAM,OAAO,GAAG,gBAAgB,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YAC7D,IAAI,CAAC,OAAO;gBAAE,SAAS;YACvB,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAChD,IAAI,IAAI;gBAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC;AAED,SAAS,gBAAgB,CACvB,QAA2D,EAC3D,UAA2C;IAE3C,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAC7B,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,YAAY,KAAK,UAAU,CAAC,EAAE,IAAI,OAAO,CAAC,QAAQ,KAAK,UAAU,CAAC,QAAQ,CAChG,CAAC;IACF,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1D,CAAC","sourcesContent":["import type { AssistantWorkflowToolInvocation } from \"./tool-invocations.js\";\n\nexport type AssistantWorkflowToolInvocationHandoffArgs = Readonly<Record<string, unknown>>;\n\n/**\n * Controller or host-provided arguments for one exact invocation in a rebuilt\n * workflow plan. The runtime must never derive a handoff from model text.\n */\nexport type AssistantWorkflowToolInvocationHandoff = {\n  invocationId: string;\n  toolName: string;\n  args: AssistantWorkflowToolInvocationHandoffArgs;\n};\n\n/**\n * Application-owned validation for a reviewed, explicitly handed-off tool.\n * Keeping this as a function lets each application enforce its own precise\n * argument contract without the workflow package owning tool schemas.\n */\nexport type AssistantWorkflowToolInvocationHandoffPolicy = {\n  toolName: string;\n  normalizeArgs: (\n    args: AssistantWorkflowToolInvocationHandoffArgs,\n  ) => AssistantWorkflowToolInvocationHandoffArgs | null;\n};\n\nexport type AssistantWorkflowApprovedToolInvocation<\n  TPolicy extends AssistantWorkflowToolInvocationHandoffPolicy = AssistantWorkflowToolInvocationHandoffPolicy,\n> = {\n  policy: TPolicy;\n  invocation: AssistantWorkflowToolInvocation;\n  args: AssistantWorkflowToolInvocationHandoffArgs;\n};\n\nexport type SelectAssistantWorkflowApprovedToolInvocationInput<\n  TPolicy extends AssistantWorkflowToolInvocationHandoffPolicy = AssistantWorkflowToolInvocationHandoffPolicy,\n> = {\n  invocations: readonly AssistantWorkflowToolInvocation[];\n  handoffs: readonly AssistantWorkflowToolInvocationHandoff[];\n  policies: readonly TPolicy[];\n  allowedToolNames: readonly string[];\n};\n\n/**\n * Selects one exact, allowlisted invocation from a rebuilt workflow plan.\n *\n * This intentionally accepts exactly one controller/host handoff. Multiple\n * records are rejected rather than silently ignoring broader authorization.\n * Argument validation remains application-owned through the supplied policy.\n */\nexport function selectAssistantWorkflowApprovedToolInvocation<\n  TPolicy extends AssistantWorkflowToolInvocationHandoffPolicy,\n>(\n  input: SelectAssistantWorkflowApprovedToolInvocationInput<TPolicy>,\n): AssistantWorkflowApprovedToolInvocation<TPolicy> | null {\n  if (input.handoffs.length !== 1) return null;\n\n  const allowedToolNames = new Set(input.allowedToolNames);\n  const approved: AssistantWorkflowApprovedToolInvocation<TPolicy>[] = [];\n  for (const policy of input.policies) {\n    if (!allowedToolNames.has(policy.toolName)) continue;\n    for (const invocation of input.invocations) {\n      if (invocation.toolName !== policy.toolName) continue;\n      const handoff = findExactHandoff(input.handoffs, invocation);\n      if (!handoff) continue;\n      const args = policy.normalizeArgs(handoff.args);\n      if (args) approved.push({ policy, invocation, args });\n    }\n  }\n  return approved.length === 1 ? approved[0] ?? null : null;\n}\n\nfunction findExactHandoff(\n  handoffs: readonly AssistantWorkflowToolInvocationHandoff[],\n  invocation: AssistantWorkflowToolInvocation,\n): AssistantWorkflowToolInvocationHandoff | null {\n  const matches = handoffs.filter(\n    (handoff) => handoff.invocationId === invocation.id && handoff.toolName === invocation.toolName,\n  );\n  return matches.length === 1 ? matches[0] ?? null : null;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uns-kit/assistant-workflow",
-  "version": "2.0.73",
+  "version": "2.0.75",
   "description": "Typed, provider-neutral workflow definitions, policies, execution plans, and trace helpers for assistants.",
   "author": "Aljosa Vister",
   "license": "MIT",
@@ -253,6 +253,10 @@
       "types": "./dist/tool-invocations.d.ts",
       "default": "./dist/tool-invocations.js"
     },
+    "./tool-handoffs": {
+      "types": "./dist/tool-handoffs.d.ts",
+      "default": "./dist/tool-handoffs.js"
+    },
     "./tool-provider-executors": {
       "types": "./dist/tool-provider-executors.d.ts",
       "default": "./dist/tool-provider-executors.js"