@geometra/core 1.59.1 → 1.61.0

package/dist/agent-contracts.d.ts

@@ -0,0 +1,26 @@
+import type { ComputedLayout } from 'textura';
+import type { AgentActionContract, SemanticProps, UIElement } from './types.js';
+export interface AgentActionTarget {
+    id: string;
+    kind: AgentActionContract['kind'];
+    title: string;
+    description?: string;
+    risk: NonNullable<AgentActionContract['risk']>;
+    requiresConfirmation: boolean;
+    enabled: boolean;
+    role: string;
+    name?: string;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    path: number[];
+    contract: AgentActionContract;
+}
+/** Attach an agent action contract to existing semantic metadata. */
+export declare function agentAction(contract: AgentActionContract, semantic?: Omit<SemanticProps, 'agentAction'>): SemanticProps;
+/** Extract all agent-native action contracts from a rendered tree and its computed layout. */
+export declare function collectAgentActions(tree: UIElement, layout: ComputedLayout): AgentActionTarget[];
+//# sourceMappingURL=agent-contracts.d.ts.map

package/dist/agent-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-contracts.d.ts","sourceRoot":"","sources":["../src/agent-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAG/E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAA;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,WAAW,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAA;IAC9C,oBAAoB,EAAE,OAAO,CAAA;IAC7B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/D,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,QAAQ,EAAE,mBAAmB,CAAA;CAC9B;AA0BD,qEAAqE;AACrE,wBAAgB,WAAW,CACzB,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,GAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAM,GAChD,aAAa,CAEf;AAgDD,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,iBAAiB,EAAE,CAIhG"}

package/dist/agent-contracts.js

@@ -0,0 +1,78 @@
+import { layoutBoundsAreFinite, scrollSafeChildOffsets } from './layout-bounds.js';
+function roleFor(element) {
+    if (element.semantic?.role)
+        return element.semantic.role;
+    if (element.kind === 'text')
+        return 'text';
+    if (element.kind === 'image' || element.kind === 'scene3d')
+        return 'img';
+    if (element.kind === 'box' && element.handlers?.onClick)
+        return 'button';
+    return 'group';
+}
+function nameFor(element) {
+    if (element.semantic?.ariaLabel)
+        return element.semantic.ariaLabel;
+    if (element.kind === 'text')
+        return element.props.text;
+    if (element.kind === 'image')
+        return element.semantic?.alt ?? element.props.alt;
+    return element.semantic?.alt;
+}
+function normalizeRisk(contract) {
+    return contract.risk ?? 'write';
+}
+function normalizeConfirmation(contract) {
+    if (contract.requiresConfirmation !== undefined)
+        return contract.requiresConfirmation;
+    return normalizeRisk(contract) === 'destructive' || normalizeRisk(contract) === 'external';
+}
+/** Attach an agent action contract to existing semantic metadata. */
+export function agentAction(contract, semantic = {}) {
+    return { ...semantic, agentAction: contract };
+}
+function walkAgentActions(element, layout, offsetX, offsetY, path, out) {
+    if (!layoutBoundsAreFinite(layout))
+        return;
+    const x = offsetX + layout.x;
+    const y = offsetY + layout.y;
+    if (!Number.isFinite(x) || !Number.isFinite(y))
+        return;
+    const contract = element.semantic?.agentAction;
+    if (contract) {
+        const name = nameFor(element);
+        out.push({
+            id: contract.id,
+            kind: contract.kind,
+            title: contract.title,
+            ...(contract.description !== undefined ? { description: contract.description } : {}),
+            risk: normalizeRisk(contract),
+            requiresConfirmation: normalizeConfirmation(contract),
+            enabled: element.semantic?.ariaDisabled !== true,
+            role: roleFor(element),
+            ...(name !== undefined ? { name } : {}),
+            bounds: { x, y, width: layout.width, height: layout.height },
+            path,
+            contract,
+        });
+    }
+    if (element.kind !== 'box')
+        return;
+    const childOrigin = scrollSafeChildOffsets(x, y, element.props.scrollX, element.props.scrollY);
+    if (!childOrigin)
+        return;
+    for (let i = 0; i < element.children.length; i++) {
+        const child = element.children[i];
+        const childLayout = layout.children[i];
+        if (child && childLayout) {
+            walkAgentActions(child, childLayout, childOrigin.ox, childOrigin.oy, [...path, i], out);
+        }
+    }
+}
+/** Extract all agent-native action contracts from a rendered tree and its computed layout. */
+export function collectAgentActions(tree, layout) {
+    const out = [];
+    walkAgentActions(tree, layout, 0, 0, [], out);
+    return out;
+}
+//# sourceMappingURL=agent-contracts.js.map

package/dist/agent-contracts.js.map

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

package/dist/agent-gateway.d.ts

@@ -0,0 +1,158 @@
+import type { ComputedLayout } from 'textura';
+import type { AgentTrace } from './agent-trace.js';
+import type { AgentActionRisk, UIElement } from './types.js';
+import { type AgentActionTarget } from './agent-contracts.js';
+import { type AgentGeometrySnapshot } from './semantic-geometry.js';
+export type AgentGatewayActionStatus = 'completed' | 'awaiting_approval' | 'denied' | 'disabled' | 'failed' | 'no_frame' | 'not_found' | 'stale_frame' | 'approval_not_found';
+export interface AgentGatewayFrame {
+    id: string;
+    route?: string;
+    createdAt: string;
+    tree: UIElement;
+    layout: ComputedLayout;
+    geometry: AgentGeometrySnapshot;
+    actions: AgentActionTarget[];
+    trace: AgentTrace;
+}
+export interface AgentGatewayFrameSnapshot {
+    id: string;
+    route?: string;
+    createdAt: string;
+    layout: ComputedLayout;
+    geometry: AgentGeometrySnapshot;
+    actions: AgentActionTarget[];
+}
+export interface AgentGatewayFrameOptions {
+    id?: string;
+    route?: string;
+    createdAt?: string;
+}
+export interface AgentGatewayActionRequest {
+    actionId: string;
+    frameId?: string;
+    actor?: string;
+    approvalActor?: string;
+    approved?: boolean;
+    input?: unknown;
+}
+export interface AgentGatewayApprovalRequest {
+    approvalId: string;
+    actor?: string;
+    approved?: boolean;
+}
+export type AgentGatewayPolicyDecision = {
+    allow: true;
+    /** Require approval in addition to any requirement declared by the contract. */
+    requiresApproval?: boolean;
+    reason?: string;
+} | {
+    allow: false;
+    reason: string;
+};
+export interface AgentGatewayPolicyContext {
+    frame: AgentGatewayFrame;
+    target: AgentActionTarget;
+    request: AgentGatewayActionRequest;
+}
+export type AgentGatewayPolicy = (context: AgentGatewayPolicyContext) => AgentGatewayPolicyDecision;
+export interface AgentGatewayExecuteContext extends AgentGatewayPolicyContext {
+    approved: boolean;
+}
+export type AgentGatewayExecutor = (context: AgentGatewayExecuteContext) => unknown | Promise<unknown>;
+export interface AgentGatewayPendingApproval {
+    id: string;
+    actionId: string;
+    frameId: string;
+    requestedAt: string;
+    target: AgentActionTarget;
+    request: AgentGatewayActionRequest;
+    reason: string;
+}
+export type AgentGatewayApprovalHook = (approval: AgentGatewayPendingApproval) => unknown | Promise<unknown>;
+export type AgentGatewayResultHook = (result: AgentGatewayActionResult) => unknown | Promise<unknown>;
+export interface AgentGatewayActionResult {
+    status: AgentGatewayActionStatus;
+    actionId: string;
+    frameId?: string;
+    approvalId?: string;
+    replayId?: string;
+    target?: AgentActionTarget;
+    reason?: string;
+    output?: unknown;
+    trace: AgentTrace;
+}
+export interface AgentGatewayReplayAction {
+    id: string;
+    actionId: string;
+    status: AgentGatewayActionStatus;
+    requestedAt: string;
+    completedAt?: string;
+    frameBefore?: AgentGatewayFrameSnapshot;
+    frameAfter?: AgentGatewayFrameSnapshot;
+    request: {
+        actor: string;
+        input?: unknown;
+    };
+    policy?: AgentGatewayPolicyDecision;
+    approval?: {
+        id?: string;
+        actor?: string;
+        approved: boolean;
+        timestamp: string;
+    };
+    output?: unknown;
+    error?: string;
+}
+export interface AgentGatewayReplay {
+    sessionId: string;
+    startedAt: string;
+    trace: AgentTrace;
+    frames: AgentGatewayFrameSnapshot[];
+    actions: AgentGatewayReplayAction[];
+}
+export type AgentGatewayRedactionField = 'input' | 'output' | 'error';
+export interface AgentGatewayRedactionContext {
+    field: AgentGatewayRedactionField;
+    actionId: string;
+}
+export type AgentGatewayRedactor = (value: unknown, context: AgentGatewayRedactionContext) => unknown;
+export interface AgentGatewayPolicyOptions {
+    /** If supplied, only these action ids may run. */
+    allowedActionIds?: string[];
+    deniedActionIds?: string[];
+    /** If supplied, only these risk classes may run. */
+    allowedRisks?: AgentActionRisk[];
+    /** Risk classes to deny. Defaults to external/destructive unless disabled. */
+    deniedRisks?: AgentActionRisk[];
+    /** Set true to avoid the default external/destructive deny list. */
+    allowExternalDestructiveByDefault?: boolean;
+    /** Extra risk classes that must be explicitly approved. */
+    requireApprovalForRisks?: AgentActionRisk[];
+}
+export interface AgentGatewayOptions {
+    sessionId: string;
+    startedAt?: string;
+    now?: () => string;
+    policy?: AgentGatewayPolicy;
+    execute?: AgentGatewayExecutor;
+    redact?: AgentGatewayRedactor;
+    /** Optional side-effect hook for approval notifications or webhook dispatch. Hook failures are ignored. */
+    onApprovalRequired?: AgentGatewayApprovalHook;
+    /** Optional side-effect hook for audit sinks or workflow notifications. Hook failures are ignored. */
+    onActionResult?: AgentGatewayResultHook;
+}
+export interface AgentGateway {
+    setFrame(tree: UIElement, layout: ComputedLayout, options?: AgentGatewayFrameOptions): AgentGatewayFrame;
+    getFrame(): AgentGatewayFrame | null;
+    listActions(): AgentActionTarget[];
+    getTrace(): AgentTrace;
+    getReplay(): AgentGatewayReplay;
+    getPendingApprovals(): AgentGatewayPendingApproval[];
+    requestAction(request: AgentGatewayActionRequest): Promise<AgentGatewayActionResult>;
+    approveAction(request: AgentGatewayApprovalRequest): Promise<AgentGatewayActionResult>;
+}
+/** Build a simple allowlist/denylist policy for an agent gateway. */
+export declare function createAgentGatewayPolicy(options?: AgentGatewayPolicyOptions): AgentGatewayPolicy;
+/** Create a frame-bound gateway for listing, policy-checking, executing, tracing, and replaying agent actions. */
+export declare function createAgentGateway(options: AgentGatewayOptions): AgentGateway;
+//# sourceMappingURL=agent-gateway.d.ts.map

package/dist/agent-gateway.d.ts.map

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

package/dist/agent-gateway.js

@@ -0,0 +1,380 @@
+import { appendAgentTraceEvent, createAgentTrace } from './agent-trace.js';
+import { collectAgentActions } from './agent-contracts.js';
+import { createAgentGeometrySnapshot } from './semantic-geometry.js';
+function defaultNow() {
+    return new Date().toISOString();
+}
+function idSet(values) {
+    return values ? new Set(values) : null;
+}
+function riskSet(values) {
+    return values ? new Set(values) : null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function defaultRedact(value) {
+    return value;
+}
+function frameSnapshot(frame) {
+    return {
+        id: frame.id,
+        ...(frame.route !== undefined ? { route: frame.route } : {}),
+        createdAt: frame.createdAt,
+        layout: frame.layout,
+        geometry: frame.geometry,
+        actions: frame.actions,
+    };
+}
+/** Build a simple allowlist/denylist policy for an agent gateway. */
+export function createAgentGatewayPolicy(options = {}) {
+    const allowedActionIds = idSet(options.allowedActionIds);
+    const deniedActionIds = idSet(options.deniedActionIds);
+    const allowedRisks = riskSet(options.allowedRisks);
+    const deniedRisks = riskSet(options.deniedRisks ??
+        (options.allowExternalDestructiveByDefault === true ? [] : ['external', 'destructive']));
+    const requireApprovalForRisks = riskSet(options.requireApprovalForRisks);
+    return ({ target }) => {
+        if (deniedActionIds?.has(target.id)) {
+            return { allow: false, reason: `action "${target.id}" is denied by policy` };
+        }
+        if (allowedActionIds && !allowedActionIds.has(target.id)) {
+            return { allow: false, reason: `action "${target.id}" is not allowlisted` };
+        }
+        if (deniedRisks?.has(target.risk)) {
+            return { allow: false, reason: `risk "${target.risk}" is denied by policy` };
+        }
+        if (allowedRisks && !allowedRisks.has(target.risk)) {
+            return { allow: false, reason: `risk "${target.risk}" is not allowed` };
+        }
+        return {
+            allow: true,
+            ...(requireApprovalForRisks?.has(target.risk) ? { requiresApproval: true } : {}),
+        };
+    };
+}
+/** Create a frame-bound gateway for listing, policy-checking, executing, tracing, and replaying agent actions. */
+export function createAgentGateway(options) {
+    const now = options.now ?? defaultNow;
+    const redact = options.redact ?? defaultRedact;
+    let trace = createAgentTrace(options.sessionId, options.startedAt ?? now());
+    let frame = null;
+    let frameIndex = 0;
+    let approvalIndex = 0;
+    let replayIndex = 0;
+    const frames = [];
+    const replayActions = [];
+    const pendingApprovals = new Map();
+    const replayActionsNeedingFrameAfter = new Set();
+    const redactValue = (actionId, field, value) => redact(value, { actionId, field });
+    const runHook = (hook, value) => {
+        try {
+            void Promise.resolve(hook?.(value)).catch(() => undefined);
+        }
+        catch {
+            // Hooks are notification sinks; they must not change gateway execution.
+        }
+    };
+    const resultWithHook = (result) => {
+        runHook(options.onActionResult, result);
+        return result;
+    };
+    const withTrace = () => {
+        if (frame)
+            frame = { ...frame, trace };
+    };
+    const append = (actionId, status, event = {}) => {
+        trace = appendAgentTraceEvent(trace, {
+            actionId,
+            status,
+            timestamp: now(),
+            ...(event.actor !== undefined ? { actor: event.actor } : {}),
+            ...(event.input !== undefined ? { input: redactValue(actionId, 'input', event.input) } : {}),
+            ...(event.output !== undefined ? { output: redactValue(actionId, 'output', event.output) } : {}),
+            ...(event.error !== undefined ? { error: String(redactValue(actionId, 'error', event.error)) } : {}),
+            ...(event.message !== undefined ? { message: event.message } : {}),
+        });
+        withTrace();
+    };
+    const createReplayAction = (request, status, frameBefore) => {
+        replayIndex++;
+        const action = {
+            id: `${options.sessionId}:replay:${replayIndex}`,
+            actionId: request.actionId,
+            status,
+            requestedAt: now(),
+            ...(frameBefore ? { frameBefore } : {}),
+            request: {
+                actor: request.actor ?? 'agent',
+                ...(request.input !== undefined ? { input: redactValue(request.actionId, 'input', request.input) } : {}),
+            },
+        };
+        replayActions.push(action);
+        return action;
+    };
+    const finishReplayAction = (replayId, patch) => {
+        const index = replayActions.findIndex(action => action.id === replayId);
+        if (index === -1)
+            return;
+        replayActions[index] = {
+            ...replayActions[index],
+            ...patch,
+            completedAt: patch.completedAt ?? now(),
+        };
+        replayActionsNeedingFrameAfter.add(replayId);
+    };
+    const reject = (request, status, reason, target) => {
+        const replay = createReplayAction(request, status, frame ? frameSnapshot(frame) : undefined);
+        append(request.actionId, 'requested', {
+            actor: request.actor ?? 'agent',
+            input: request.input,
+            message: reason,
+        });
+        append(request.actionId, 'denied', {
+            actor: 'gateway',
+            error: reason,
+        });
+        finishReplayAction(replay.id, {
+            status,
+            error: String(redactValue(request.actionId, 'error', reason)),
+        });
+        return resultWithHook({
+            status,
+            actionId: request.actionId,
+            replayId: replay.id,
+            ...(frame ? { frameId: frame.id } : {}),
+            ...(target ? { target } : {}),
+            reason,
+            trace,
+        });
+    };
+    const executeApproved = async (sourceFrame, target, request, replayId, approved, approvalActor) => {
+        const approvalTimestamp = now();
+        if (approved) {
+            append(request.actionId, 'approved', {
+                actor: approvalActor ?? request.approvalActor ?? 'human',
+                message: 'approval recorded',
+            });
+        }
+        else {
+            append(request.actionId, 'denied', {
+                actor: approvalActor ?? request.approvalActor ?? 'human',
+                error: 'approval denied',
+            });
+            finishReplayAction(replayId, {
+                status: 'denied',
+                approval: { actor: approvalActor ?? request.approvalActor ?? 'human', approved: false, timestamp: approvalTimestamp },
+                error: 'approval denied',
+            });
+            return resultWithHook({
+                status: 'denied',
+                actionId: request.actionId,
+                frameId: sourceFrame.id,
+                replayId,
+                target,
+                reason: 'approval denied',
+                trace,
+            });
+        }
+        try {
+            const output = await options.execute?.({ frame: sourceFrame, target, request, approved: true });
+            const redactedOutput = output === undefined ? { accepted: true } : redactValue(request.actionId, 'output', output);
+            append(request.actionId, 'completed', {
+                actor: 'gateway',
+                output: redactedOutput,
+            });
+            finishReplayAction(replayId, {
+                status: 'completed',
+                approval: { actor: approvalActor ?? request.approvalActor ?? 'human', approved: true, timestamp: approvalTimestamp },
+                output: redactedOutput,
+            });
+            return resultWithHook({
+                status: 'completed',
+                actionId: request.actionId,
+                frameId: sourceFrame.id,
+                replayId,
+                target,
+                output: redactedOutput,
+                trace,
+            });
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            append(request.actionId, 'failed', {
+                actor: 'gateway',
+                error: message,
+            });
+            finishReplayAction(replayId, {
+                status: 'failed',
+                approval: { actor: approvalActor ?? request.approvalActor ?? 'human', approved: true, timestamp: approvalTimestamp },
+                error: String(redactValue(request.actionId, 'error', message)),
+            });
+            return resultWithHook({
+                status: 'failed',
+                actionId: request.actionId,
+                frameId: sourceFrame.id,
+                replayId,
+                target,
+                reason: message,
+                trace,
+            });
+        }
+    };
+    return {
+        setFrame(tree, layout, frameOptions = {}) {
+            frameIndex++;
+            const createdAt = frameOptions.createdAt ?? now();
+            const frameId = frameOptions.id ?? `${options.sessionId}:frame:${frameIndex}`;
+            const actions = collectAgentActions(tree, layout);
+            frame = {
+                id: frameId,
+                ...(frameOptions.route !== undefined ? { route: frameOptions.route } : {}),
+                createdAt,
+                tree,
+                layout,
+                geometry: createAgentGeometrySnapshot(tree, layout, {
+                    id: frameId,
+                    ...(frameOptions.route !== undefined ? { route: frameOptions.route } : {}),
+                    createdAt,
+                }),
+                actions,
+                trace,
+            };
+            const snapshot = frameSnapshot(frame);
+            frames.push(snapshot);
+            for (const replayId of replayActionsNeedingFrameAfter) {
+                const action = replayActions.find(item => item.id === replayId);
+                if (action && !action.frameAfter) {
+                    action.frameAfter = snapshot;
+                }
+            }
+            replayActionsNeedingFrameAfter.clear();
+            return frame;
+        },
+        getFrame() {
+            return frame;
+        },
+        listActions() {
+            return frame?.actions ?? [];
+        },
+        getTrace() {
+            return trace;
+        },
+        getReplay() {
+            return {
+                sessionId: options.sessionId,
+                startedAt: trace.startedAt,
+                trace,
+                frames,
+                actions: replayActions,
+            };
+        },
+        getPendingApprovals() {
+            return [...pendingApprovals.values()].map(record => ({
+                id: record.id,
+                actionId: record.actionId,
+                frameId: record.frameId,
+                requestedAt: record.requestedAt,
+                target: record.target,
+                request: record.request,
+                reason: record.reason,
+            }));
+        },
+        async requestAction(request) {
+            if (!frame) {
+                return reject(request, 'no_frame', 'no current frame is available');
+            }
+            if (request.frameId && request.frameId !== frame.id) {
+                return reject(request, 'stale_frame', `request frame "${request.frameId}" does not match current frame "${frame.id}"`);
+            }
+            const sourceFrame = frame;
+            const target = sourceFrame.actions.find(action => action.id === request.actionId);
+            if (!target) {
+                return reject(request, 'not_found', `action "${request.actionId}" is not present in the current frame`);
+            }
+            if (!target.enabled) {
+                return reject(request, 'disabled', `action "${request.actionId}" is disabled`, target);
+            }
+            const replay = createReplayAction(request, 'awaiting_approval', frameSnapshot(sourceFrame));
+            append(request.actionId, 'requested', {
+                actor: request.actor ?? 'agent',
+                input: request.input,
+                message: target.title,
+            });
+            const policyDecision = options.policy?.({ frame: sourceFrame, target, request }) ?? { allow: true };
+            replay.policy = policyDecision;
+            if (!policyDecision.allow) {
+                append(request.actionId, 'denied', {
+                    actor: 'gateway',
+                    error: policyDecision.reason,
+                });
+                finishReplayAction(replay.id, {
+                    status: 'denied',
+                    error: String(redactValue(request.actionId, 'error', policyDecision.reason)),
+                });
+                return resultWithHook({
+                    status: 'denied',
+                    actionId: request.actionId,
+                    frameId: sourceFrame.id,
+                    replayId: replay.id,
+                    target,
+                    reason: policyDecision.reason,
+                    trace,
+                });
+            }
+            const approvalRequired = policyDecision.requiresApproval === true || target.requiresConfirmation;
+            if (approvalRequired && request.approved !== true) {
+                approvalIndex++;
+                const approvalId = `${options.sessionId}:approval:${approvalIndex}`;
+                const pendingApproval = {
+                    id: approvalId,
+                    actionId: request.actionId,
+                    frameId: sourceFrame.id,
+                    requestedAt: now(),
+                    target,
+                    request,
+                    reason: policyDecision.reason ?? 'approval required',
+                    replayId: replay.id,
+                    policy: policyDecision,
+                    frame: sourceFrame,
+                };
+                pendingApprovals.set(approvalId, pendingApproval);
+                runHook(options.onApprovalRequired, {
+                    id: pendingApproval.id,
+                    actionId: pendingApproval.actionId,
+                    frameId: pendingApproval.frameId,
+                    requestedAt: pendingApproval.requestedAt,
+                    target: pendingApproval.target,
+                    request: pendingApproval.request,
+                    reason: pendingApproval.reason,
+                });
+                return resultWithHook({
+                    status: 'awaiting_approval',
+                    actionId: request.actionId,
+                    frameId: sourceFrame.id,
+                    approvalId,
+                    replayId: replay.id,
+                    target,
+                    reason: policyDecision.reason ?? 'approval required',
+                    trace,
+                });
+            }
+            return executeApproved(sourceFrame, target, request, replay.id, true, request.approvalActor);
+        },
+        async approveAction(request) {
+            const pending = pendingApprovals.get(request.approvalId);
+            if (!pending) {
+                return resultWithHook({
+                    status: 'approval_not_found',
+                    actionId: '',
+                    approvalId: request.approvalId,
+                    reason: `approval "${request.approvalId}" is not pending`,
+                    trace,
+                });
+            }
+            pendingApprovals.delete(request.approvalId);
+            return executeApproved(pending.frame, pending.target, pending.request, pending.replayId, request.approved !== false, request.actor);
+        },
+    };
+}
+//# sourceMappingURL=agent-gateway.js.map