@intutic/gate 1.10.1

package/dist/vercel.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Vercel AI SDK adapter: `intuticToolApproval()` and `withIntuticProxy()`.
+ *
+ * `@intutic/gate/vercel` — a framework-specific specialization of the same
+ * idea `wrapTools.ts` implements generically (see that file's module doc):
+ * wrap the framework's own veto point around this package's `Gate.guard()`.
+ *
+ * The `ai` package (v6+) exposes a documented pre-execution veto point: a
+ * `toolApproval` callback accepted by `generateText`/`streamText` and
+ * `ToolLoopAgent`. It runs once per tool call, before execution, and its
+ * return value decides whether the call proceeds.
+ *
+ * ## Confirmed against a real install
+ *
+ * `ai@7.0.68` + `@ai-sdk/openai@4.0.43` were installed in a scratch directory
+ * and `node_modules/ai/dist/index.d.ts` read directly (not inferred from
+ * docs alone). The relevant types:
+ *
+ * ```ts
+ * type ToolApprovalStatus =
+ *   | undefined | 'not-applicable' | 'approved' | 'denied' | 'user-approval'
+ *   | { type: 'not-applicable'; reason?: never }
+ *   | { type: 'approved'; reason?: string }
+ *   | { type: 'denied'; reason?: string }
+ *   | { type: 'user-approval'; reason?: never }
+ *
+ * type GenericToolApprovalFunction<TOOLS, TOOLS_CONTEXT, RUNTIME_CONTEXT> = (options: {
+ *   toolCall: TypedToolCall<TOOLS>        // { toolName: string; input: ... ; ... }
+ *   tools: TOOLS | undefined
+ *   toolsContext: TOOLS_CONTEXT
+ *   runtimeContext: RUNTIME_CONTEXT
+ *   messages: ModelMessage[]
+ * }) => MaybePromiseLike<ToolApprovalStatus>
+ *
+ * type ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT> =
+ *   GenericToolApprovalFunction<...> | { [toolName]?: ToolApprovalStatus | SingleToolApprovalFunction<...> }
+ * ```
+ * (`generateText`/`streamText`/`ToolLoopAgent` all accept
+ * `toolApproval?: ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT>`.)
+ *
+ * `'not-applicable'` (also spelled `{ type: 'not-applicable' }`, and
+ * `undefined` is treated the same) means "this gate has no opinion, proceed
+ * normally" — exactly matching the plan's description. `'denied'` (or
+ * `{ type: 'denied', reason }`) vetoes the call before execution; the SDK
+ * hands `reason` back to the model in place of a tool result. This adapter
+ * implements `GenericToolApprovalFunction`, the whole-config form (not the
+ * per-tool-keyed form), so a single `intuticToolApproval()` call covers every
+ * tool in `tools`.
+ *
+ * ## Known, documented limitation — no env-var LLM routing
+ *
+ * Unlike almost every other harness in this codebase (which honour
+ * `OPENAI_BASE_URL`/`ANTHROPIC_BASE_URL` or an equivalent), the Vercel AI SDK
+ * has NO environment-variable-based base-URL override mechanism. Routing LLM
+ * traffic through the Intutic proxy requires IN-CODE provider construction —
+ * `createOpenAI({ baseURL })`, `createGateway({ baseURL })`, etc. — not a
+ * sourced `.env.intutic` file the way `langchainAdapter`/`langgraphAdapter`
+ * and the rest of the SDK-gated family work. `withIntuticProxy()` below is a
+ * small factory wrapper for that in-code construction; it does not — and
+ * cannot — make this "zero-code" the way an env-var-honouring harness's
+ * integration correctly can claim to be. See
+ * `apps/docs/integrations/vercel-ai-sdk.md` for the operator-facing version
+ * of this same limitation, stated plainly rather than oversold.
+ */
+import { type Gate } from './gate.js';
+/** Structural copy of `ai`'s `ToolApprovalStatus` — this package does not
+ *  depend on `ai` at runtime, so the shape is declared here rather than
+ *  imported. Confirmed field-for-field against `ai@7.0.68`'s
+ *  `dist/index.d.ts` (see module doc). */
+export type VercelToolApprovalStatus = undefined | 'not-applicable' | 'approved' | 'denied' | 'user-approval' | {
+    type: 'not-applicable';
+    reason?: undefined;
+} | {
+    type: 'approved';
+    reason?: string;
+} | {
+    type: 'denied';
+    reason?: string;
+} | {
+    type: 'user-approval';
+    reason?: undefined;
+};
+/** Structural copy of `ai`'s `TypedToolCall` — the fields this adapter
+ *  actually reads (`toolName`, `input`); the real type carries more. */
+export interface VercelToolCall {
+    toolName: string;
+    input: unknown;
+}
+/** Structural copy of the options object `ai`'s `GenericToolApprovalFunction`
+ *  receives — the whole-config form of `toolApproval` accepted by
+ *  `generateText`/`streamText`/`ToolLoopAgent`. Only `toolCall` is read here;
+ *  the rest pass through the structural type so this function is assignable
+ *  to the real (wider) signature. */
+export interface VercelToolApprovalOptions {
+    toolCall: VercelToolCall;
+    [key: string]: unknown;
+}
+/** Structural copy of `ai`'s `GenericToolApprovalFunction` — the exact shape
+ *  `toolApproval` expects. */
+export type VercelToolApproval = (options: VercelToolApprovalOptions) => Promise<VercelToolApprovalStatus>;
+export interface IntuticToolApprovalOptions {
+    /** Overrides the process-wide installed gate (`install(new Gate(...))`). */
+    gate?: Gate;
+}
+/**
+ * Builds a `toolApproval` callback matching `ai`'s `GenericToolApprovalFunction`
+ * signature, for direct use on `generateText`/`streamText`/`ToolLoopAgent`:
+ *
+ * ```ts
+ * import { generateText } from 'ai'
+ * import { Gate, install } from '@intutic/gate'
+ * import { intuticToolApproval } from '@intutic/gate/vercel'
+ *
+ * install(new Gate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID }))
+ *
+ * await generateText({
+ *   model,
+ *   tools,
+ *   toolApproval: intuticToolApproval(),
+ * })
+ * ```
+ *
+ * Resolves to `'not-applicable'` on allow (this gate has no opinion; any
+ * other approval mechanism the caller has configured still applies) and to
+ * `{ type: 'denied', reason }` on refusal — `reason` is the
+ * `[Intutic Governance] BLOCKED: ...` message, handed back to the model in
+ * place of a tool result.
+ *
+ * Requires a `Gate` — either passed via `{ gate }` here, or installed
+ * process-wide with `install(new Gate(...))`. A call with neither throws,
+ * refusing to run the tool unguarded rather than silently skipping
+ * enforcement — same posture as `wrapTool`/`intuticHooks`.
+ */
+export declare function intuticToolApproval(opts?: IntuticToolApprovalOptions): VercelToolApproval;
+/**
+ * Resolves the Intutic proxy URL the same way the rest of this codebase does
+ * — `INTUTIC_PROXY_URL`, falling back to the local default every CLI command
+ * and env-writer here shares (`tools/cli/src/commands/exec.ts`,
+ * `tools/cli/src/lib/onboarding.ts`, `services/sync-daemon/src/agentReporter.ts`).
+ * Not re-hardcoded per call site — one resolution rule, reused.
+ */
+export declare function intuticProxyUrl(): string;
+/**
+ * Wraps a provider-constructing function so it points at the Intutic proxy.
+ *
+ * The Vercel AI SDK has no env-var base-URL override (see module doc), so
+ * routing LLM traffic through the proxy is IN-CODE: pass the provider
+ * factory you would otherwise call directly (`createOpenAI`, `createGateway`,
+ * any `@ai-sdk/*` `create*` export or compatible custom factory that accepts
+ * a `{ baseURL }`-shaped options object) and get back one pre-configured to
+ * call the proxy instead of the provider's real endpoint:
+ *
+ * ```ts
+ * import { createOpenAI } from '@ai-sdk/openai'
+ * import { withIntuticProxy } from '@intutic/gate/vercel'
+ *
+ * const openai = withIntuticProxy(createOpenAI)({ apiKey: process.env.OPENAI_API_KEY })
+ * const model = openai('gpt-5-mini')
+ * ```
+ *
+ * `baseUrl` overrides the resolved proxy URL (see {@link intuticProxyUrl});
+ * omit it to use `INTUTIC_PROXY_URL`/the local default, same as every other
+ * harness in this codebase.
+ *
+ * This does NOT make Vercel AI SDK integration "zero-code": every provider
+ * construction call site in the caller's application must go through this
+ * wrapper (or otherwise set `baseURL` itself) for LLM egress to be governed
+ * — there is no ambient env var this package (or any other) can set to
+ * achieve the same effect for this framework.
+ */
+export declare function withIntuticProxy<TOptions extends {
+    baseURL?: string;
+}, TProvider>(providerFactory: (options: TOptions) => TProvider, baseUrl?: string): (options: TOptions) => TProvider;
+//# sourceMappingURL=vercel.d.ts.map

package/dist/vercel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel.d.ts","sourceRoot":"","sources":["../src/vercel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,EAAwB,KAAK,IAAI,EAAE,MAAM,WAAW,CAAA;AAG3D;;;0CAG0C;AAC1C,MAAM,MAAM,wBAAwB,GAChC,SAAS,GACT,gBAAgB,GAChB,UAAU,GACV,QAAQ,GACR,eAAe,GACf;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,CAAA;AAEjD;wEACwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;qCAIqC;AACrC,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,cAAc,CAAA;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;8BAC8B;AAC9B,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,wBAAwB,CAAC,CAAA;AAEtC,MAAM,WAAW,0BAA0B;IACzC,4EAA4E;IAC5E,IAAI,CAAC,EAAE,IAAI,CAAA;CACZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,0BAA+B,GAAG,kBAAkB,CAmB7F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,SAAS;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,EACrC,SAAS,EACT,eAAe,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,OAAO,EAAE,QAAQ,KAAK,SAAS,CAGvG"}

package/dist/vercel.js

@@ -0,0 +1,157 @@
+/**
+ * Vercel AI SDK adapter: `intuticToolApproval()` and `withIntuticProxy()`.
+ *
+ * `@intutic/gate/vercel` — a framework-specific specialization of the same
+ * idea `wrapTools.ts` implements generically (see that file's module doc):
+ * wrap the framework's own veto point around this package's `Gate.guard()`.
+ *
+ * The `ai` package (v6+) exposes a documented pre-execution veto point: a
+ * `toolApproval` callback accepted by `generateText`/`streamText` and
+ * `ToolLoopAgent`. It runs once per tool call, before execution, and its
+ * return value decides whether the call proceeds.
+ *
+ * ## Confirmed against a real install
+ *
+ * `ai@7.0.68` + `@ai-sdk/openai@4.0.43` were installed in a scratch directory
+ * and `node_modules/ai/dist/index.d.ts` read directly (not inferred from
+ * docs alone). The relevant types:
+ *
+ * ```ts
+ * type ToolApprovalStatus =
+ *   | undefined | 'not-applicable' | 'approved' | 'denied' | 'user-approval'
+ *   | { type: 'not-applicable'; reason?: never }
+ *   | { type: 'approved'; reason?: string }
+ *   | { type: 'denied'; reason?: string }
+ *   | { type: 'user-approval'; reason?: never }
+ *
+ * type GenericToolApprovalFunction<TOOLS, TOOLS_CONTEXT, RUNTIME_CONTEXT> = (options: {
+ *   toolCall: TypedToolCall<TOOLS>        // { toolName: string; input: ... ; ... }
+ *   tools: TOOLS | undefined
+ *   toolsContext: TOOLS_CONTEXT
+ *   runtimeContext: RUNTIME_CONTEXT
+ *   messages: ModelMessage[]
+ * }) => MaybePromiseLike<ToolApprovalStatus>
+ *
+ * type ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT> =
+ *   GenericToolApprovalFunction<...> | { [toolName]?: ToolApprovalStatus | SingleToolApprovalFunction<...> }
+ * ```
+ * (`generateText`/`streamText`/`ToolLoopAgent` all accept
+ * `toolApproval?: ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT>`.)
+ *
+ * `'not-applicable'` (also spelled `{ type: 'not-applicable' }`, and
+ * `undefined` is treated the same) means "this gate has no opinion, proceed
+ * normally" — exactly matching the plan's description. `'denied'` (or
+ * `{ type: 'denied', reason }`) vetoes the call before execution; the SDK
+ * hands `reason` back to the model in place of a tool result. This adapter
+ * implements `GenericToolApprovalFunction`, the whole-config form (not the
+ * per-tool-keyed form), so a single `intuticToolApproval()` call covers every
+ * tool in `tools`.
+ *
+ * ## Known, documented limitation — no env-var LLM routing
+ *
+ * Unlike almost every other harness in this codebase (which honour
+ * `OPENAI_BASE_URL`/`ANTHROPIC_BASE_URL` or an equivalent), the Vercel AI SDK
+ * has NO environment-variable-based base-URL override mechanism. Routing LLM
+ * traffic through the Intutic proxy requires IN-CODE provider construction —
+ * `createOpenAI({ baseURL })`, `createGateway({ baseURL })`, etc. — not a
+ * sourced `.env.intutic` file the way `langchainAdapter`/`langgraphAdapter`
+ * and the rest of the SDK-gated family work. `withIntuticProxy()` below is a
+ * small factory wrapper for that in-code construction; it does not — and
+ * cannot — make this "zero-code" the way an env-var-honouring harness's
+ * integration correctly can claim to be. See
+ * `apps/docs/integrations/vercel-ai-sdk.md` for the operator-facing version
+ * of this same limitation, stated plainly rather than oversold.
+ */
+import { active as activeGate } from './gate.js';
+import { IntuticGateRefusal } from './errors.js';
+/**
+ * Builds a `toolApproval` callback matching `ai`'s `GenericToolApprovalFunction`
+ * signature, for direct use on `generateText`/`streamText`/`ToolLoopAgent`:
+ *
+ * ```ts
+ * import { generateText } from 'ai'
+ * import { Gate, install } from '@intutic/gate'
+ * import { intuticToolApproval } from '@intutic/gate/vercel'
+ *
+ * install(new Gate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID }))
+ *
+ * await generateText({
+ *   model,
+ *   tools,
+ *   toolApproval: intuticToolApproval(),
+ * })
+ * ```
+ *
+ * Resolves to `'not-applicable'` on allow (this gate has no opinion; any
+ * other approval mechanism the caller has configured still applies) and to
+ * `{ type: 'denied', reason }` on refusal — `reason` is the
+ * `[Intutic Governance] BLOCKED: ...` message, handed back to the model in
+ * place of a tool result.
+ *
+ * Requires a `Gate` — either passed via `{ gate }` here, or installed
+ * process-wide with `install(new Gate(...))`. A call with neither throws,
+ * refusing to run the tool unguarded rather than silently skipping
+ * enforcement — same posture as `wrapTool`/`intuticHooks`.
+ */
+export function intuticToolApproval(opts = {}) {
+    return async ({ toolCall }) => {
+        const g = opts.gate ?? activeGate();
+        if (g === null) {
+            throw new Error('No gate configured: call install(new Gate(...)) from @intutic/gate, or pass ' +
+                '{ gate } to intuticToolApproval(). Refusing to run the tool unguarded.');
+        }
+        try {
+            await g.guard(toolCall.toolName, (toolCall.input ?? {}));
+            return 'not-applicable';
+        }
+        catch (exc) {
+            if (exc instanceof IntuticGateRefusal) {
+                return { type: 'denied', reason: exc.message };
+            }
+            throw exc;
+        }
+    };
+}
+/**
+ * Resolves the Intutic proxy URL the same way the rest of this codebase does
+ * — `INTUTIC_PROXY_URL`, falling back to the local default every CLI command
+ * and env-writer here shares (`tools/cli/src/commands/exec.ts`,
+ * `tools/cli/src/lib/onboarding.ts`, `services/sync-daemon/src/agentReporter.ts`).
+ * Not re-hardcoded per call site — one resolution rule, reused.
+ */
+export function intuticProxyUrl() {
+    return process.env.INTUTIC_PROXY_URL || 'http://localhost:4000';
+}
+/**
+ * Wraps a provider-constructing function so it points at the Intutic proxy.
+ *
+ * The Vercel AI SDK has no env-var base-URL override (see module doc), so
+ * routing LLM traffic through the proxy is IN-CODE: pass the provider
+ * factory you would otherwise call directly (`createOpenAI`, `createGateway`,
+ * any `@ai-sdk/*` `create*` export or compatible custom factory that accepts
+ * a `{ baseURL }`-shaped options object) and get back one pre-configured to
+ * call the proxy instead of the provider's real endpoint:
+ *
+ * ```ts
+ * import { createOpenAI } from '@ai-sdk/openai'
+ * import { withIntuticProxy } from '@intutic/gate/vercel'
+ *
+ * const openai = withIntuticProxy(createOpenAI)({ apiKey: process.env.OPENAI_API_KEY })
+ * const model = openai('gpt-5-mini')
+ * ```
+ *
+ * `baseUrl` overrides the resolved proxy URL (see {@link intuticProxyUrl});
+ * omit it to use `INTUTIC_PROXY_URL`/the local default, same as every other
+ * harness in this codebase.
+ *
+ * This does NOT make Vercel AI SDK integration "zero-code": every provider
+ * construction call site in the caller's application must go through this
+ * wrapper (or otherwise set `baseURL` itself) for LLM egress to be governed
+ * — there is no ambient env var this package (or any other) can set to
+ * achieve the same effect for this framework.
+ */
+export function withIntuticProxy(providerFactory, baseUrl) {
+    const url = baseUrl ?? intuticProxyUrl();
+    return (options) => providerFactory({ ...options, baseURL: url });
+}
+//# sourceMappingURL=vercel.js.map

package/dist/vercel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel.js","sourceRoot":"","sources":["../src/vercel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,EAAE,MAAM,IAAI,UAAU,EAAa,MAAM,WAAW,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AA6ChD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAmC,EAAE;IACvE,OAAO,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,UAAU,EAAE,CAAA;QACnC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,8EAA8E;gBAC5E,wEAAwE,CAC3E,CAAA;QACH,CAAC;QACD,IAAI,CAAC;YACH,MAAM,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAA4B,CAAC,CAAA;YACnF,OAAO,gBAAgB,CAAA;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;gBACtC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAA;YAChD,CAAC;YACD,MAAM,GAAG,CAAA;QACX,CAAC;IACH,CAAC,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,uBAAuB,CAAA;AACjE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gBAAgB,CAG9B,eAAiD,EAAE,OAAgB;IACnE,MAAM,GAAG,GAAG,OAAO,IAAI,eAAe,EAAE,CAAA;IACxC,OAAO,CAAC,OAAiB,EAAa,EAAE,CAAC,eAAe,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAA;AACxF,CAAC"}

package/dist/workflow.d.ts

@@ -0,0 +1,209 @@
+/**
+ * `@ai-sdk/workflow` adapter: `intuticNeedsApproval()`, `withIntuticApproval()`,
+ * `wrapWorkflowTools()`, and the FatalError-compatible `IntuticWorkflowRefusal`.
+ *
+ * `@intutic/gate/workflow` — the same idea `vercel.ts` implements for the base
+ * `ai` package (wrap the framework's own veto point around this package's
+ * `Gate.guard()`), reshaped for Vercel's DURABLE workflow-agent runtime, where
+ * two facts change the adapter's whole design:
+ *
+ * ## 1. The veto surface is per-tool `needsApproval`, not an agent option
+ *
+ * Confirmed against a real install (`@ai-sdk/workflow@1.0.69`):
+ * `WorkflowAgent`/`WorkflowAgentOptions` carry ZERO approval fields — the
+ * string `toolApproval` does not appear anywhere in the package's shipped
+ * `.d.ts`. The veto surface is `needsApproval` (boolean | function) on the
+ * TOOL definition, exactly as the framework's own workflow-agent docs
+ * describe under "Tool Approval". The compiled agent loop confirms the
+ * semantics (dist/index.js): `needsApproval == null` → no approval; a
+ * boolean is used directly; a function is awaited as
+ * `needsApproval(input, { toolCallId, messages, context })`. A call needing
+ * approval pauses DURABLY — the run suspends and a human can approve hours
+ * later — so this framework, uniquely in this package, has a real
+ * human-in-the-loop lane for the gate to route into.
+ *
+ * (`ai@7.0.68` marks tool-level `needsApproval` `@deprecated` in favour of
+ * generateText-level `toolApproval` — but `@ai-sdk/workflow`'s OWN agent loop
+ * reads the tool-level field and exposes no other veto surface, so it is the
+ * correct — indeed the only — integration point here. Noted in the TD entry
+ * this phase filed, so a future @ai-sdk/workflow release moving to the
+ * generateText-shaped surface gets caught rather than silently ungated.)
+ *
+ * ## 2. Denials must not be retried — refusals here are FatalError-compatible
+ *
+ * A durable workflow retries failed steps. Confirmed against real installs
+ * (`workflow@4.8.3` re-exporting `@workflow/errors@4.2.1` via
+ * `@workflow/core`): the runtime's retry/abort decision consults
+ * `FatalError.is(err)` (`@workflow/core`'s `runtime/step-handler.js` — a
+ * fatal error "bubbl[es] up to parent workflow"; anything else is retried
+ * toward `maxAttempts`), and `FatalError.is()` DUCK-TYPES: it checks
+ * `err.name === 'FatalError'` on any Error-shaped object, precisely because
+ * workflows execute in a separate `vm` realm where `instanceof` fails across
+ * the boundary. A plain `IntuticGateRefusal` thrown from `needsApproval` or a
+ * tool body would therefore be RETRIED — a governance denial replayed on a
+ * timer until max attempts, burning the run to reach the same refusal. So
+ * this adapter's refusals are {@link IntuticWorkflowRefusal}: still an
+ * `IntuticGateRefusal` (`instanceof` works in-realm, `.reason`/`.code`/
+ * `.incidentId` intact, message still `[Intutic Governance] BLOCKED: ...`)
+ * but with `name = 'FatalError'` so the real runtime's duck-check aborts
+ * instead of retry-looping. `__tests__/workflow.test.ts` pins this against
+ * the REAL `FatalError.is` from the `workflow` package, not a re-derivation.
+ *
+ * Deliberately asymmetric: a NON-refusal crash inside `Gate.guard()` (a
+ * transient network failure in a remote tier, an unexpected bug) is re-thrown
+ * UNTOUCHED — retryable, which is the durable runtime's correct response to a
+ * transient failure. Only a real governance verdict (and the fail-closed
+ * "no gate configured" case, which is deterministic and would fail every
+ * retry identically) is made fatal.
+ *
+ * @module
+ */
+import { type Gate } from './gate.js';
+import { IntuticGateRefusal } from './errors.js';
+import { type AnyFn, type ExecutableTool } from './wrapTools.js';
+/**
+ * A refused call inside a durable workflow.
+ *
+ * `name` is `'FatalError'` — NOT `'IntuticGateRefusal'` — on purpose: the
+ * workflow runtime's `FatalError.is()` duck-types on that exact string (see
+ * module doc), and it is the only cross-VM-realm-safe way to tell the runtime
+ * "abort, do not retry". Everything else about the refusal contract is
+ * preserved: `instanceof IntuticGateRefusal` still holds (same realm),
+ * `.message` still carries the `[Intutic Governance] BLOCKED:` prefix, and
+ * `.reason`/`.code`/`.incidentId` carry the structured verdict. `fatal: true`
+ * mirrors the property the real `FatalError` class sets, for code that
+ * checks the flag rather than the name.
+ */
+export declare class IntuticWorkflowRefusal extends IntuticGateRefusal {
+    readonly fatal: true;
+    constructor(reason: string, code: string, incidentId?: string);
+    /** Rewrap a core refusal so the durable runtime treats it as fatal. */
+    static from(refusal: IntuticGateRefusal): IntuticWorkflowRefusal;
+    /**
+     * Cross-realm-safe detection (the same trick `FatalError.is` itself uses):
+     * `instanceof` fails across the workflow `vm` boundary, so this checks the
+     * duck-typed name plus this package's own message prefix.
+     */
+    static is(value: unknown): boolean;
+}
+/** Structural copy of the options object `@ai-sdk/workflow`'s agent loop
+ *  passes to a tool's `needsApproval` function (confirmed from the compiled
+ *  loop: `needsApproval(tc.input, { toolCallId, messages, context })`). Only
+ *  the fields this adapter could ever read are named; the index signature
+ *  keeps the function assignable to the real (wider) option type. */
+export interface WorkflowNeedsApprovalOptions {
+    toolCallId: string;
+    [key: string]: unknown;
+}
+/** The `needsApproval` function shape this adapter produces — assignable to
+ *  `ai`'s tool-level `needsApproval` (the surface `@ai-sdk/workflow`'s agent
+ *  loop actually consults). */
+export type WorkflowNeedsApproval = (input: unknown, options: WorkflowNeedsApprovalOptions) => Promise<boolean>;
+export interface IntuticNeedsApprovalOptions {
+    /** Overrides the process-wide installed gate (`install(new Gate(...))`). */
+    gate?: Gate;
+    /**
+     * What an ALLOWED call maps to. `needsApproval` answers "does a human need
+     * to approve this?", which is a different question from "may this run?" —
+     * so an allow has two honest encodings and this option picks one:
+     *
+     *  - `'auto'` (default): resolve `false` — the gate evaluated the call and
+     *    allowed it; no human pause. Denials never reach this mapping at all
+     *    (they THROW — see below), so `false` here never launders a block.
+     *  - `'human'`: resolve `true` — the gate allowed it AND a human still
+     *    approves, using the framework's own durable pause (approvable hours
+     *    later). Belt-and-braces for high-stakes tools.
+     *
+     * A BLOCKED call takes neither value: it throws
+     * {@link IntuticWorkflowRefusal}. Returning `true` for a denial would hand
+     * the decision to a human approver as though the gate had no verdict, and
+     * returning `false` would RUN the tool — the one thing a block must never
+     * do.
+     */
+    onAllow?: 'auto' | 'human';
+}
+/**
+ * Build an async `needsApproval` function for ONE workflow tool:
+ *
+ * ```ts
+ * import { WorkflowAgent } from '@ai-sdk/workflow'
+ * import { Gate, install } from '@intutic/gate'
+ * import { intuticNeedsApproval } from '@intutic/gate/workflow'
+ *
+ * install(new Gate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID }))
+ *
+ * const agent = new WorkflowAgent({
+ *   model,
+ *   tools: {
+ *     deployService: {
+ *       description: '...',
+ *       inputSchema,
+ *       execute: deployStep,
+ *       needsApproval: intuticNeedsApproval('deployService'),
+ *     },
+ *   },
+ * })
+ * ```
+ *
+ * The tool name is a parameter because the framework's `needsApproval`
+ * signature does not carry it — `(input, { toolCallId, messages, context })`
+ * has no `toolName` field (confirmed against the shipped types). Use
+ * {@link withIntuticApproval} to attach this to a whole tools record without
+ * hand-repeating each name.
+ *
+ * Verdict mapping: BLOCK → throws {@link IntuticWorkflowRefusal} (fatal —
+ * aborts instead of retry-looping; see module doc); ALLOW → `false` or `true`
+ * per `onAllow`. A non-refusal crash in the gate is re-thrown untouched
+ * (retryable — correct for transients).
+ */
+export declare function intuticNeedsApproval(toolName: string, opts?: IntuticNeedsApprovalOptions): WorkflowNeedsApproval;
+/** The slice of a workflow tool definition this adapter reads/replaces.
+ *  Structurally compatible with `ai`'s `Tool` (whose `needsApproval` is
+ *  `boolean | ToolNeedsApprovalFunction<...>`). */
+export interface WorkflowToolLike {
+    needsApproval?: boolean | ((input: never, options: never) => unknown);
+    [key: string]: unknown;
+}
+/**
+ * Attach the Intutic gate to every tool in a record, composing with any
+ * `needsApproval` the tool already declares:
+ *
+ * ```ts
+ * const agent = new WorkflowAgent({ model, tools: withIntuticApproval(tools) })
+ * ```
+ *
+ * For each tool (the record KEY is the tool name reported to the gate — the
+ * same identity the framework itself dispatches on):
+ *
+ *   1. `Gate.guard()` runs first. BLOCK throws {@link IntuticWorkflowRefusal}.
+ *   2. On allow, the tool's OWN prior `needsApproval` still applies: a
+ *      boolean is returned as-is; a function is awaited with the original
+ *      arguments; a tool with none falls back to `onAllow` ('auto' → false).
+ *
+ * So a tool that already said "always ask a human" (`needsApproval: true`)
+ * keeps asking a human — this gate only ADDS the ability to refuse outright,
+ * it never removes an approval pause the caller had configured.
+ *
+ * Returns a NEW record of NEW tool objects (shallow copies); the input record
+ * and its tools are not mutated.
+ */
+export declare function withIntuticApproval<T extends Record<string, WorkflowToolLike>>(tools: T, opts?: IntuticNeedsApprovalOptions): T;
+/**
+ * `wrapTools` for durable workflow tool definitions — the same generic
+ * execute-wrapping `wrapTools.ts` provides (gate first, then the real body),
+ * with ONE workflow-specific change: a refusal thrown out of the wrapped
+ * `execute` is rewrapped as {@link IntuticWorkflowRefusal}, because a
+ * workflow tool's `execute` is a durable STEP and a step that throws a
+ * non-fatal error is retried (see module doc). Everything else — including
+ * "no gate configured" handling and the record-key-is-tool-name convention —
+ * is `wrapTools`'s own behaviour, reused rather than reimplemented.
+ *
+ * Prefer {@link withIntuticApproval} as the primary integration: it uses the
+ * framework's own pre-execution veto surface, refuses BEFORE the durable
+ * step ever starts, and keeps the human-approval lane available. This
+ * execute-level wrapper is defense in depth (or the option for callers whose
+ * tools are shared with non-workflow code paths); running both double-guards
+ * the call, which is harmless but emits duplicate gate telemetry.
+ */
+export declare function wrapWorkflowTools<T extends AnyFn | ExecutableTool>(tools: Record<string, T>, gate?: Gate): Record<string, T>;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,OAAO,EAAwB,KAAK,IAAI,EAAkB,MAAM,WAAW,CAAA;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAa,KAAK,KAAK,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE3E;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,SAAQ,kBAAkB;IAC5D,SAAgB,KAAK,EAAG,IAAI,CAAS;gBACzB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;IAK7D,uEAAuE;IACvE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,sBAAsB;IAIhE;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;CASnC;AAED;;;;qEAIqE;AACrE,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;+BAE+B;AAC/B,MAAM,MAAM,qBAAqB,GAAG,CAClC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,4BAA4B,KAClC,OAAO,CAAC,OAAO,CAAC,CAAA;AAErB,MAAM,WAAW,2BAA2B;IAC1C,4EAA4E;IAC5E,IAAI,CAAC,EAAE,IAAI,CAAA;IACX;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAC3B;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,2BAAgC,GACrC,qBAAqB,CAcvB;AAED;;mDAEmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,KAAK,OAAO,CAAC,CAAA;IACrE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC5E,KAAK,EAAE,CAAC,EACR,IAAI,GAAE,2BAAgC,GACrC,CAAC,CAiBH;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,KAAK,GAAG,cAAc,EAChE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EACxB,IAAI,CAAC,EAAE,IAAI,GACV,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAWnB"}