@intutic/gate 1.10.1

package/dist/soprules.js

@@ -0,0 +1,176 @@
+/**
+ * SOP rules authored in the product, enforced before execution.
+ *
+ * Port of `packages/intutic-clawde/intutic_clawde/gate/soprules.py`.
+ *
+ * `SopRule` has carried an optional `argPattern` since mcp-proxy shipped, and
+ * `packages/mcp-proxy/src/policy.ts` matches it against the serialised tool
+ * input. `intutic/intutic-enterprise#14` added a ` WHERE ` clause to the SOP
+ * title grammar, so a rule can finally say "kubectl apply without a digest"
+ * instead of only "any shell call":
+ *
+ *     BLOCK:^shell$ WHERE kubectl\s+apply(?!.*@sha256:):deploy must be pinned
+ *
+ * Now the *policy* lives in the SOP register — versioned, lifecycle-gated,
+ * visible on the dashboard, editable without touching agent code — and this
+ * module is only the part that applies it.
+ *
+ * Matching mirrors `matchSopRule` in
+ * `services/control-plane/src/lib/sopRuleTitle.ts` (itself a deliberate
+ * line-for-line mirror of `PolicyClient.matchRule` in
+ * `packages/mcp-proxy/src/policy.ts`), deliberately:
+ *
+ *   * rules are tried in the order the control plane returned them
+ *   * first match wins
+ *   * `toolPattern` is tested against the tool name, `argPattern` against the
+ *     serialised tool input
+ *   * the serialisation is the `JSON.stringify(tool_input ?? {})` shape every
+ *     mirror matches against — compact separators, insertion order, non-ASCII
+ *     left intact
+ *   * a rule whose regex does not compile is SKIPPED, not fatal
+ *
+ * Fetch failure is non-fatal for the same reason it is in `policy.ts`: the
+ * gate's image-integrity tier independently covers the deploy case and fails
+ * CLOSED. This tier changes where the policy is *authored*, not whether the
+ * run is safe.
+ */
+export const FETCH_TIMEOUT_MS = 3_000;
+// Actions the control plane can return. Anything else is ignored rather than
+// guessed at — an unrecognised action must not silently become "allow".
+export const ACTION_BLOCK = 'block';
+export const ACTION_WARN = 'warn';
+export const ACTION_APPROVAL = 'require_approval';
+const KNOWN_ACTIONS = new Set([ACTION_BLOCK, ACTION_WARN, ACTION_APPROVAL]);
+/** Mirror of `matchSopRule`, including its silent-skip on bad regex. */
+export function ruleMatches(rule, toolName, toolInputJson) {
+    try {
+        if (!new RegExp(rule.toolPattern).test(toolName))
+            return false;
+        if (rule.argPattern !== null) {
+            return new RegExp(rule.argPattern).test(toolInputJson);
+        }
+        return true;
+    }
+    catch {
+        // Malformed regex in rule — skip silently, exactly as the control plane
+        // and mcp-proxy mirrors do.
+        return false;
+    }
+}
+/**
+ * The `JSON.stringify(tool_input ?? {})` shape every mirror matches against.
+ *
+ * `JSON.stringify` already produces compact separators and preserves
+ * insertion order and non-ASCII by default — this function exists mainly so
+ * every call site names the contract explicitly rather than calling
+ * `JSON.stringify` inline and drifting on a future edit.
+ */
+export function serialiseToolInput(toolInput) {
+    return JSON.stringify(toolInput ?? {});
+}
+/**
+ * Accept the rule list in whichever envelope the control plane used.
+ *
+ * `/api/v1/sop/rules` returns `{rules:[...]}`, while sibling list endpoints
+ * variously return `{items:[...]}` and `{data:[...]}`. Reading the wrong key
+ * yields zero rules and a tier that enforces nothing while looking healthy —
+ * the worst failure a gate can have — so all three are accepted rather than
+ * assumed.
+ */
+export function parseRules(payload) {
+    let rows;
+    if (Array.isArray(payload)) {
+        rows = payload;
+    }
+    else if (payload !== null && typeof payload === 'object') {
+        const obj = payload;
+        const candidate = obj.rules ?? obj.items ?? obj.data ?? [];
+        rows = Array.isArray(candidate) ? candidate : [];
+    }
+    else {
+        return [];
+    }
+    const out = [];
+    for (const row of rows) {
+        if (row === null || typeof row !== 'object')
+            continue;
+        const r = row;
+        const toolPattern = r.toolPattern ?? r.tool_pattern;
+        const action = String(r.action ?? '').toLowerCase();
+        if (typeof toolPattern !== 'string' || !toolPattern)
+            continue;
+        if (!KNOWN_ACTIONS.has(action))
+            continue;
+        const arg = r.argPattern ?? r.arg_pattern;
+        out.push({
+            id: String(r.id ?? r.sopId ?? 'sop'),
+            toolPattern,
+            action,
+            reason: String(r.reason ?? `SOP rule ${toolPattern}`),
+            argPattern: typeof arg === 'string' && arg ? arg : null,
+        });
+    }
+    return out;
+}
+/**
+ * Fetch active VALIDATED rules, or `null` if they could not be fetched.
+ *
+ * `null` and `[]` mean different things and the caller must not conflate
+ * them: `null` is "the register did not answer", `[]` is "the register
+ * answered and this workspace has no rules". Only the second is a statement
+ * about policy.
+ */
+export async function fetchRules(baseUrl, apiKey, workspaceId, timeoutMs = FETCH_TIMEOUT_MS) {
+    const qs = new URLSearchParams({ workspaceId, active: 'true' });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`${baseUrl.replace(/\/$/, '')}/api/v1/sop/rules?${qs.toString()}`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'X-Workspace-Id': workspaceId,
+            },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const raw = await res.text();
+        return parseRules(raw ? JSON.parse(raw) : {});
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * True when the control plane emitted at least one usable `argPattern`.
+ *
+ * A control plane predating `intutic-enterprise#14` cannot produce one, so
+ * this doubles as a deployment probe — surface it rather than letting the
+ * tier be silently inert.
+ */
+export function supportsArgPatterns(rules) {
+    return rules.some((r) => r.argPattern !== null && compiles(r.argPattern));
+}
+function compiles(pattern) {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** First rule matching this call, in control-plane order. */
+export function firstMatch(rules, toolName, toolInput) {
+    const payload = serialiseToolInput(toolInput);
+    for (const rule of rules) {
+        if (ruleMatches(rule, toolName, payload))
+            return rule;
+    }
+    return null;
+}
+//# sourceMappingURL=soprules.js.map

package/dist/soprules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"soprules.js","sourceRoot":"","sources":["../src/soprules.ts"],"names":[],"mappings":"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"}

package/dist/trueforge.d.ts

@@ -0,0 +1,191 @@
+/**
+ * TrueForge (embedded) adapter: `intuticApprovalResponder()`.
+ *
+ * `@intutic/gate/trueforge` — Phase 1 of TrueForge support: another team's
+ * Node process that imports `@truefoundry/trueforge-core` directly
+ * (github.com/truefoundry/trueforge, MIT) and drives its own
+ * `SessionHandle`/`TurnHandle` API in-process. Same family idea as
+ * `mastra.ts`/`vercel.ts` (wrap the framework's own veto point around this
+ * package's `Gate.guard()`), but TrueForge's veto point is shaped
+ * differently from either of those, so this module follows `harness.ts`'s
+ * `intuticApprovalResponder()` precedent instead — a batch function
+ * answering pending approvals — not a single-call `beforeToolCall`/
+ * `toolApproval` option.
+ *
+ * Phase 2 (`HarnessType.TRUEFORGE_SERVER` — TrueForge run as its own
+ * standalone/hosted server, e.g. `npx @truefoundry/trueforge`, Docker
+ * Compose, or the Helm chart) is explicitly OUT OF SCOPE here. Nobody embeds
+ * an Intutic gate into a third-party OSS server process; that deployment
+ * mode needs governance running in an external Intutic-operated bridge
+ * service — separate, larger work, not attempted in this module.
+ *
+ * ## Confirmed against the real published package, not assumed
+ *
+ * `@truefoundry/trueforge-core@0.1.4` (`latest` on npm at the time this was
+ * written) was downloaded from the npm registry and its shipped `.d.ts`
+ * files read directly — not inferred from docs alone:
+ *
+ *   - There is NO synchronous, in-process "approval resolver" callback
+ *     anywhere in the package. Every shipped `.d.ts` file was grepped for
+ *     `approvalResolver`/`onApproval`/`approvalHandler`/`resolveApproval`:
+ *     zero matches. `ITurnResourceResolver`
+ *     (`dist/agent-session/ITurnResourceResolver.d.ts`) resolves sandboxes,
+ *     agent definitions, and tracing per run — it carries no tool-call veto
+ *     hook of any kind.
+ *   - The ONLY approval mechanism, embedded or not, is the same turn/event
+ *     contract TrueForge's standalone server exposes over HTTP: a turn
+ *     pauses with a `required_actions` entry of type `tool.approval_required`
+ *     (`EventType.TOOL_APPROVAL_REQUIRED`, `dist/agent-session/schemas/
+ *     events.d.ts`), naming each pending call only as `{id, source_event_id}`
+ *     — no tool name or arguments travel on the event itself. Answering it
+ *     means constructing a NEW turn (`SessionHandle.createTurn()`) whose
+ *     `input` carries a `user.tool_approval` item:
+ *     `{type:'user.tool_approval', thread_id, tool_call_id, approval}`,
+ *     where `approval` is `{status:'allow'} | {status:'deny', reason?:
+ *     string}` (`ApprovalDecisionSchema`, `dist/core/events/schema.d.ts`) —
+ *     confirmed field-for-field, and pinned by this module's own test file
+ *     via a structural assignability check against the real exported
+ *     `TurnInputItem` (`@truefoundry/trueforge-core/agent-session`) and
+ *     `ApprovalDecision` (`@truefoundry/trueforge-core/core`) types.
+ *
+ * So unlike `mastra.ts`/`vercel.ts`, this adapter cannot BE "the function you
+ * pass as a framework option" — embedded TrueForge has no such option. What
+ * it can be, and is, is the `harness.ts`-shaped piece: a function that
+ * evaluates a batch of pending approval requests through `Gate.guard()` and
+ * returns the `user.tool_approval` `TurnInputItem[]` ready to hand to your
+ * next `session.createTurn({ input, previous_turn_id })` call.
+ *
+ * ## What the embedding host still has to do itself
+ *
+ * Resolving a `{id, source_event_id}` tool-call reference back to the real
+ * tool NAME and ARGUMENTS is the host's job, not this adapter's: the host
+ * already owns the `TurnHandle`/event stream (`turn.stream()`/
+ * `listEvents()`) this package has no reason to depend on, and
+ * `source_event_id` points at a `model.message` event whose tool-call wire
+ * shape this package deliberately does not import — matching
+ * `mastra.ts`/`vercel.ts`'s existing convention of zero runtime dependency
+ * on the framework being gated. Build the `TrueforgeApprovalRequest[]` this
+ * responder consumes from whatever your own event-resolution loop already
+ * extracts, then feed the returned items straight into your next
+ * `createTurn()` call.
+ *
+ * ## GUESSED, clearly marked as such: the exact orchestration wiring
+ *
+ * The plan that authored this phase asked to pin the exact registration API
+ * against `TurnHandle`/`ITurnResourceResolver`; having read both real files,
+ * NEITHER carries a registration point for this at all — the orchestration
+ * loop (drive `turn.stream()`, detect a `tool.approval_required` required
+ * action, resolve each `source_event_id`, call this responder, call
+ * `createTurn()` again with the answers) is necessarily HAND-WRITTEN
+ * application code in the embedding host, not something a config option
+ * turns on. That loop's exact shape — how you persist the paused turn id,
+ * how you resolve `source_event_id`, whether you drain `stream()` to
+ * completion before or after answering — is a genuine judgment call for the
+ * embedding host's own architecture and is NOT prescribed here. See
+ * `apps/docs/integrations/trueforge.md` for a worked (illustrative, not
+ * load-bearing) example of one way to wire this loop.
+ *
+ * @module
+ */
+import { type Gate } from './gate.js';
+/**
+ * One pending `tool.approval_required` request, already resolved to a real
+ * tool name and arguments by the embedding host — see the module doc's
+ * "What the embedding host still has to do itself".
+ */
+export interface TrueforgeApprovalRequest {
+    /** TrueForge's own thread id for this call — carried through unchanged
+     *  onto the `user.tool_approval` item this responder produces. */
+    readonly threadId: string;
+    /** The pending tool call's id (`ToolCallRef.id`) — becomes `tool_call_id`
+     *  on the produced item. */
+    readonly toolCallId: string;
+    /** The tool name `Gate.guard()` evaluates. */
+    readonly toolName: string;
+    /** The tool's arguments, resolved from the `model.message` event the
+     *  pending call's `source_event_id` points at. */
+    readonly input: unknown;
+}
+/**
+ * Structural copy of `@truefoundry/trueforge-core`'s `ApprovalDecision`
+ * (`ApprovalDecisionSchema`, `core/events/schema.ts`) — this package does
+ * not depend on `@truefoundry/trueforge-core` at runtime, so the shape is
+ * declared here rather than imported. Confirmed field-for-field against
+ * `@truefoundry/trueforge-core@0.1.4`'s shipped `dist/core/events/schema.d.ts`
+ * (see module doc).
+ */
+export type TrueforgeApprovalDecision = {
+    status: 'allow';
+} | {
+    status: 'deny';
+    reason?: string;
+};
+/**
+ * Structural copy of the `user.tool_approval` member of
+ * `@truefoundry/trueforge-core`'s `TurnInputItem` union
+ * (`UserToolApprovalMessageSchema`, `agent-session/schemas/events.ts`) — the
+ * shape `SessionHandle.createTurn({ input })` expects for answering a
+ * pending approval. Confirmed field-for-field against the same install.
+ */
+export interface TrueforgeUserToolApprovalItem {
+    type: 'user.tool_approval';
+    thread_id: string;
+    tool_call_id: string;
+    approval: TrueforgeApprovalDecision;
+}
+export interface IntuticApprovalResponderOptions {
+    /** Overrides the process-wide installed gate (`install(new Gate(...))`). */
+    gate?: Gate;
+}
+/**
+ * Render a pending request's `input` as the `tool_input` object
+ * {@link Gate.guard} evaluates. Mirrors `harness.ts`'s/`workflow.ts`'s own
+ * coercion: a non-object input (a bare string/number/array — TrueForge's own
+ * `model.message` tool-call arguments are typically already an object, but
+ * this adapter does not import that wire format to assume so) falls back to
+ * `{ args: [...] }` so the gate always has something to evaluate.
+ */
+export declare function renderTrueforgeToolInput(input: unknown): Record<string, unknown>;
+/**
+ * Build an approval responder: a function that evaluates each pending
+ * TrueForge tool-approval request via `Gate.guard()` and produces the
+ * `user.tool_approval` input items for your next `createTurn()` call:
+ *
+ * ```ts
+ * import { Gate, install } from '@intutic/gate'
+ * import { intuticApprovalResponder } from '@intutic/gate/trueforge'
+ *
+ * install(new Gate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID }))
+ *
+ * const respond = intuticApprovalResponder()
+ *
+ * // ...drive turn.stream() until it pauses on a tool.approval_required
+ * // required_action; resolve each {id, source_event_id} back to a real
+ * // tool name + arguments (see the module doc), then:
+ * const input = await respond(pendingRequests)
+ * const nextTurn = await session.createTurn({
+ *   turn_id: newTurnId(),
+ *   input,
+ *   previous_turn_id: pausedTurn.id,
+ *   signal,
+ *   resolver,
+ * })
+ * ```
+ *
+ * Decision mapping, per request:
+ *
+ *   - gate allows              -> `{ status: 'allow' }`
+ *   - `IntuticGateRefusal`     -> `{ status: 'deny', reason }` — the
+ *     `[Intutic Governance] BLOCKED: ...` message
+ *   - any OTHER throw          -> `{ status: 'deny', reason: '... gate
+ *     crashed ...' }` — fail CLOSED, same posture as `harness.ts`'s
+ *     responder: this function's output is a decision list fed into a
+ *     resumed turn, and a deliverable, auditable deny is better than an
+ *     escaped throw that leaves the caller with nothing to resume with.
+ *
+ * Requires a `Gate` — either passed via `{ gate }`, or installed process-wide
+ * with `install(new Gate(...))`. A call with neither throws before
+ * evaluating anything, refusing to answer approvals unguarded.
+ */
+export declare function intuticApprovalResponder(opts?: IntuticApprovalResponderOptions): (requests: readonly TrueforgeApprovalRequest[]) => Promise<TrueforgeUserToolApprovalItem[]>;
+//# sourceMappingURL=trueforge.d.ts.map

package/dist/trueforge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trueforge.d.ts","sourceRoot":"","sources":["../src/trueforge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AAEH,OAAO,EAAwB,KAAK,IAAI,EAAE,MAAM,WAAW,CAAA;AAG3D;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;sEACkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;gCAC4B;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;sDACkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,yBAAyB,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEjG;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,oBAAoB,CAAA;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,yBAAyB,CAAA;CACpC;AAED,MAAM,WAAW,+BAA+B;IAC9C,4EAA4E;IAC5E,IAAI,CAAC,EAAE,IAAI,CAAA;CACZ;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,GAAE,+BAAoC,GACzC,CAAC,QAAQ,EAAE,SAAS,wBAAwB,EAAE,KAAK,OAAO,CAAC,6BAA6B,EAAE,CAAC,CAsC7F"}

package/dist/trueforge.js

@@ -0,0 +1,184 @@
+/**
+ * TrueForge (embedded) adapter: `intuticApprovalResponder()`.
+ *
+ * `@intutic/gate/trueforge` — Phase 1 of TrueForge support: another team's
+ * Node process that imports `@truefoundry/trueforge-core` directly
+ * (github.com/truefoundry/trueforge, MIT) and drives its own
+ * `SessionHandle`/`TurnHandle` API in-process. Same family idea as
+ * `mastra.ts`/`vercel.ts` (wrap the framework's own veto point around this
+ * package's `Gate.guard()`), but TrueForge's veto point is shaped
+ * differently from either of those, so this module follows `harness.ts`'s
+ * `intuticApprovalResponder()` precedent instead — a batch function
+ * answering pending approvals — not a single-call `beforeToolCall`/
+ * `toolApproval` option.
+ *
+ * Phase 2 (`HarnessType.TRUEFORGE_SERVER` — TrueForge run as its own
+ * standalone/hosted server, e.g. `npx @truefoundry/trueforge`, Docker
+ * Compose, or the Helm chart) is explicitly OUT OF SCOPE here. Nobody embeds
+ * an Intutic gate into a third-party OSS server process; that deployment
+ * mode needs governance running in an external Intutic-operated bridge
+ * service — separate, larger work, not attempted in this module.
+ *
+ * ## Confirmed against the real published package, not assumed
+ *
+ * `@truefoundry/trueforge-core@0.1.4` (`latest` on npm at the time this was
+ * written) was downloaded from the npm registry and its shipped `.d.ts`
+ * files read directly — not inferred from docs alone:
+ *
+ *   - There is NO synchronous, in-process "approval resolver" callback
+ *     anywhere in the package. Every shipped `.d.ts` file was grepped for
+ *     `approvalResolver`/`onApproval`/`approvalHandler`/`resolveApproval`:
+ *     zero matches. `ITurnResourceResolver`
+ *     (`dist/agent-session/ITurnResourceResolver.d.ts`) resolves sandboxes,
+ *     agent definitions, and tracing per run — it carries no tool-call veto
+ *     hook of any kind.
+ *   - The ONLY approval mechanism, embedded or not, is the same turn/event
+ *     contract TrueForge's standalone server exposes over HTTP: a turn
+ *     pauses with a `required_actions` entry of type `tool.approval_required`
+ *     (`EventType.TOOL_APPROVAL_REQUIRED`, `dist/agent-session/schemas/
+ *     events.d.ts`), naming each pending call only as `{id, source_event_id}`
+ *     — no tool name or arguments travel on the event itself. Answering it
+ *     means constructing a NEW turn (`SessionHandle.createTurn()`) whose
+ *     `input` carries a `user.tool_approval` item:
+ *     `{type:'user.tool_approval', thread_id, tool_call_id, approval}`,
+ *     where `approval` is `{status:'allow'} | {status:'deny', reason?:
+ *     string}` (`ApprovalDecisionSchema`, `dist/core/events/schema.d.ts`) —
+ *     confirmed field-for-field, and pinned by this module's own test file
+ *     via a structural assignability check against the real exported
+ *     `TurnInputItem` (`@truefoundry/trueforge-core/agent-session`) and
+ *     `ApprovalDecision` (`@truefoundry/trueforge-core/core`) types.
+ *
+ * So unlike `mastra.ts`/`vercel.ts`, this adapter cannot BE "the function you
+ * pass as a framework option" — embedded TrueForge has no such option. What
+ * it can be, and is, is the `harness.ts`-shaped piece: a function that
+ * evaluates a batch of pending approval requests through `Gate.guard()` and
+ * returns the `user.tool_approval` `TurnInputItem[]` ready to hand to your
+ * next `session.createTurn({ input, previous_turn_id })` call.
+ *
+ * ## What the embedding host still has to do itself
+ *
+ * Resolving a `{id, source_event_id}` tool-call reference back to the real
+ * tool NAME and ARGUMENTS is the host's job, not this adapter's: the host
+ * already owns the `TurnHandle`/event stream (`turn.stream()`/
+ * `listEvents()`) this package has no reason to depend on, and
+ * `source_event_id` points at a `model.message` event whose tool-call wire
+ * shape this package deliberately does not import — matching
+ * `mastra.ts`/`vercel.ts`'s existing convention of zero runtime dependency
+ * on the framework being gated. Build the `TrueforgeApprovalRequest[]` this
+ * responder consumes from whatever your own event-resolution loop already
+ * extracts, then feed the returned items straight into your next
+ * `createTurn()` call.
+ *
+ * ## GUESSED, clearly marked as such: the exact orchestration wiring
+ *
+ * The plan that authored this phase asked to pin the exact registration API
+ * against `TurnHandle`/`ITurnResourceResolver`; having read both real files,
+ * NEITHER carries a registration point for this at all — the orchestration
+ * loop (drive `turn.stream()`, detect a `tool.approval_required` required
+ * action, resolve each `source_event_id`, call this responder, call
+ * `createTurn()` again with the answers) is necessarily HAND-WRITTEN
+ * application code in the embedding host, not something a config option
+ * turns on. That loop's exact shape — how you persist the paused turn id,
+ * how you resolve `source_event_id`, whether you drain `stream()` to
+ * completion before or after answering — is a genuine judgment call for the
+ * embedding host's own architecture and is NOT prescribed here. See
+ * `apps/docs/integrations/trueforge.md` for a worked (illustrative, not
+ * load-bearing) example of one way to wire this loop.
+ *
+ * @module
+ */
+import { active as activeGate } from './gate.js';
+import { IntuticGateRefusal } from './errors.js';
+/**
+ * Render a pending request's `input` as the `tool_input` object
+ * {@link Gate.guard} evaluates. Mirrors `harness.ts`'s/`workflow.ts`'s own
+ * coercion: a non-object input (a bare string/number/array — TrueForge's own
+ * `model.message` tool-call arguments are typically already an object, but
+ * this adapter does not import that wire format to assume so) falls back to
+ * `{ args: [...] }` so the gate always has something to evaluate.
+ */
+export function renderTrueforgeToolInput(input) {
+    if (input !== null && typeof input === 'object' && !Array.isArray(input)) {
+        return input;
+    }
+    return { args: [input] };
+}
+/**
+ * Build an approval responder: a function that evaluates each pending
+ * TrueForge tool-approval request via `Gate.guard()` and produces the
+ * `user.tool_approval` input items for your next `createTurn()` call:
+ *
+ * ```ts
+ * import { Gate, install } from '@intutic/gate'
+ * import { intuticApprovalResponder } from '@intutic/gate/trueforge'
+ *
+ * install(new Gate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID }))
+ *
+ * const respond = intuticApprovalResponder()
+ *
+ * // ...drive turn.stream() until it pauses on a tool.approval_required
+ * // required_action; resolve each {id, source_event_id} back to a real
+ * // tool name + arguments (see the module doc), then:
+ * const input = await respond(pendingRequests)
+ * const nextTurn = await session.createTurn({
+ *   turn_id: newTurnId(),
+ *   input,
+ *   previous_turn_id: pausedTurn.id,
+ *   signal,
+ *   resolver,
+ * })
+ * ```
+ *
+ * Decision mapping, per request:
+ *
+ *   - gate allows              -> `{ status: 'allow' }`
+ *   - `IntuticGateRefusal`     -> `{ status: 'deny', reason }` — the
+ *     `[Intutic Governance] BLOCKED: ...` message
+ *   - any OTHER throw          -> `{ status: 'deny', reason: '... gate
+ *     crashed ...' }` — fail CLOSED, same posture as `harness.ts`'s
+ *     responder: this function's output is a decision list fed into a
+ *     resumed turn, and a deliverable, auditable deny is better than an
+ *     escaped throw that leaves the caller with nothing to resume with.
+ *
+ * Requires a `Gate` — either passed via `{ gate }`, or installed process-wide
+ * with `install(new Gate(...))`. A call with neither throws before
+ * evaluating anything, refusing to answer approvals unguarded.
+ */
+export function intuticApprovalResponder(opts = {}) {
+    return async (requests) => {
+        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 intuticApprovalResponder(). Refusing to answer tool approvals unguarded.');
+        }
+        const items = [];
+        for (const req of requests) {
+            let approval;
+            try {
+                await g.guard(req.toolName, renderTrueforgeToolInput(req.input));
+                approval = { status: 'allow' };
+            }
+            catch (exc) {
+                if (exc instanceof IntuticGateRefusal) {
+                    approval = { status: 'deny', reason: exc.message };
+                }
+                else {
+                    const detail = exc instanceof Error ? exc.message : String(exc);
+                    approval = {
+                        status: 'deny',
+                        reason: `[Intutic Governance] BLOCKED: gate crashed (${detail}) — failing closed rather ` +
+                            'than approving an unevaluated call.',
+                    };
+                }
+            }
+            items.push({
+                type: 'user.tool_approval',
+                thread_id: req.threadId,
+                tool_call_id: req.toolCallId,
+                approval,
+            });
+        }
+        return items;
+    };
+}
+//# sourceMappingURL=trueforge.js.map

package/dist/trueforge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trueforge.js","sourceRoot":"","sources":["../src/trueforge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AAEH,OAAO,EAAE,MAAM,IAAI,UAAU,EAAa,MAAM,WAAW,CAAA;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAkDhD;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,OAAO,KAAgC,CAAA;IACzC,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,CAAA;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAwC,EAAE;IAE1C,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE;QACxB,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,UAAU,EAAE,CAAA;QACnC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,8EAA8E;gBAC5E,sFAAsF,CACzF,CAAA;QACH,CAAC;QAED,MAAM,KAAK,GAAoC,EAAE,CAAA;QACjD,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,IAAI,QAAmC,CAAA;YACvC,IAAI,CAAC;gBACH,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,wBAAwB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAA;gBAChE,QAAQ,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;YAChC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;oBACtC,QAAQ,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAA;gBACpD,CAAC;qBAAM,CAAC;oBACN,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;oBAC/D,QAAQ,GAAG;wBACT,MAAM,EAAE,MAAM;wBACd,MAAM,EACJ,+CAA+C,MAAM,4BAA4B;4BACjF,qCAAqC;qBACxC,CAAA;gBACH,CAAC;YACH,CAAC;YACD,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,oBAAoB;gBAC1B,SAAS,EAAE,GAAG,CAAC,QAAQ;gBACvB,YAAY,EAAE,GAAG,CAAC,UAAU;gBAC5B,QAAQ;aACT,CAAC,CAAA;QACJ,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;AACH,CAAC"}