@astrasyncai/verification-gateway 3.10.0 → 3.11.0

package/dist/codex/index.d.ts

@@ -0,0 +1,230 @@
+import { PlatformAdapter, AdapterConfig } from '../adapter-interface/interface.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-C23_uaY8.js';
+import { AstraSyncGateway } from '../gateway/gateway.js';
+import '../types-9tns4wyl.js';
+import '../metadata-capture.js';
+
+/**
+ * @astrasyncai/adapter-codex
+ *
+ * Layer 4 adapter for OpenAI Codex CLI. Intercepts tool calls via Codex's
+ * native PreToolUse hooks (stable since Codex v0.124.0): the hook binary
+ * receives {tool_name, tool_input, permission_mode, ...} on stdin and may
+ * answer with a permissionDecision on stdout.
+ *
+ * Decision mapping is strictly tightening, with two Codex-specific twists
+ * versus the Claude Code adapter (§7.7):
+ *
+ * - Codex has NO "ask" decision. MANUAL_REVIEW therefore emits nothing —
+ *   "no matching hook decides" makes Codex fall through to its own native
+ *   approval prompt, which is the HITL. EXCEPT when the session runs in
+ *   `dontAsk` / `bypassPermissions` permission mode: no native prompt will
+ *   catch the fall-through there, so MANUAL_REVIEW escalates to deny.
+ * - Codex FAILS OPEN on hook errors/timeouts (it "reports the error and
+ *   continues the tool call"). The hook binary therefore fails closed
+ *   internally — every internal failure becomes an explicit deny (unless
+ *   failOpen is configured). A hard kill/timeout still fails open on
+ *   Codex's side; that residual gap is documented, and the mitigation is
+ *   the hook's ~200ms cost against a 10s timeout.
+ *
+ * ALLOW never emits "allow" (and never `updatedInput`) — a hook allow would
+ * suppress Codex's own approval prompt rather than defer to it.
+ */
+
+/** The PreToolUse payload Codex CLI writes to the hook's stdin. */
+interface CodexPreToolUsePayload {
+    hook_event_name?: string;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+    session_id?: string;
+    turn_id?: string;
+    tool_use_id?: string;
+    cwd?: string;
+    model?: string;
+    transcript_path?: string | null;
+    /** default | acceptEdits | plan | dontAsk | bypassPermissions */
+    permission_mode?: string;
+}
+/**
+ * The JSON the hook prints to stdout when it wants to tighten a decision.
+ * Deny-only by design: Codex has no "ask", and the guard never emits
+ * "allow". Any unsupported field would make Codex mark the hook run failed
+ * and continue the call — keep this shape strictly to documented fields.
+ */
+interface CodexHookOutput {
+    hookSpecificOutput: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'deny';
+        permissionDecisionReason: string;
+    };
+}
+/** Permission modes with no native approval prompt to catch a fall-through. */
+declare const UNPROMPTED_PERMISSION_MODES: Set<string>;
+/** Session bookkeeping tools that are never governed. */
+declare const DEFAULT_SKIP_TOOLS: string[];
+interface CodexAdapterOptions {
+    /** Tool names to never intercept (replaces DEFAULT_SKIP_TOOLS if given) */
+    skipTools?: string[];
+    /**
+     * When true, unmapped non-MCP tools are still intercepted (purpose
+     * `tool.<name>`, denied by default policy). When false (default),
+     * unmapped tools are skipped — Codex's own approval flow remains their
+     * only gate.
+     */
+    strictUnmapped?: boolean;
+    /**
+     * Govern MCP tools (mcp__{server}__{tool} → purpose {server}.{tool}).
+     * Defaults to true; installers default it off until the policy lists
+     * {server}.{tool} rules (the evaluator denies unknown purposes).
+     */
+    governMcp?: boolean;
+}
+declare class CodexAdapter implements PlatformAdapter {
+    readonly interfaceVersion = 1;
+    private gateway;
+    private skipTools;
+    private strictUnmapped;
+    private governMcp;
+    private _isRunning;
+    constructor(options?: CodexAdapterOptions);
+    get isRunning(): boolean;
+    initialize(config: AdapterConfig): Promise<void>;
+    shutdown(): Promise<void>;
+    interceptAction(action: AgentAction): Promise<InterceptResult>;
+    extractContext(action: AgentAction): PDLSSContext;
+    private buildContext;
+    /**
+     * Translate a gateway decision into hook stdout JSON.
+     *
+     * Returns null on ALLOW (silent — Codex's own approval flow stays in
+     * charge) and on MANUAL_REVIEW in prompted permission modes (the
+     * fall-through IS Codex's native prompt). MANUAL_REVIEW in dontAsk /
+     * bypassPermissions escalates to deny — no prompt exists to catch it.
+     */
+    decisionToHookOutput(decision: VerificationDecision, permissionMode?: string): CodexHookOutput | null;
+    /**
+     * Convenience for the hook entry: full payload → hook output (or null).
+     *
+     * apply_patch envelopes are evaluated per touched file (one context per
+     * `*** Add/Update/Delete File:` header) and tightened to the worst
+     * decision, so file.write blockedPatterns (including guard
+     * self-protection) apply to every path in the patch.
+     */
+    evaluatePayload(payload: CodexPreToolUsePayload): Promise<CodexHookOutput | null>;
+    private evaluateInterceptedPayload;
+    /**
+     * Enforcement happens via the stdout JSON the hook prints; there is no
+     * in-process side to enforce on.
+     */
+    enforceDecision(_decision: VerificationDecision): Promise<void>;
+}
+
+/**
+ * Parse an MCP tool name (mcp__{server}__{tool}) into an app-connector
+ * style purpose `{server}.{tool}`. Returns null for non-MCP tool names.
+ */
+declare function mapMcpTool(toolName: string): string | null;
+
+/**
+ * @astrasyncai/adapter-codex — tool → purpose mapping
+ *
+ * Maps OpenAI Codex CLI's built-in tool names (as delivered in PreToolUse
+ * hook payloads) to PDLSS purpose categories. MCP tool names use the same
+ * mcp__{server}__{tool} convention as Claude Code, so the parser is shared.
+ */
+
+/**
+ * Codex CLI built-in tool name → PDLSS purpose.
+ * Documented canonical names: `Bash`, `apply_patch` (aliases `Edit`/`Write`
+ * appear in matcher examples), `web_search`. Undocumented tools stay
+ * unmapped and are skipped unless strictUnmapped is on.
+ */
+declare const CODEX_TOOL_MAP: Record<string, string>;
+/**
+ * Register the Codex mappings into the shared adapter purpose map.
+ * Idempotent; safe to call from both the adapter and the hook entry.
+ */
+declare function registerCodexMappings(): void;
+/**
+ * Extract the file paths an apply_patch envelope touches. Codex's patch
+ * format marks each file with `*** Add File:` / `*** Update File:` /
+ * `*** Delete File:` headers. Returns [] when nothing parseable is found —
+ * callers should then fall back to a raw-text target.
+ */
+declare function extractApplyPatchPaths(patchText: string): string[];
+
+/**
+ * AstraSync Local Guard for OpenAI Codex CLI — PreToolUse hook entry.
+ *
+ * Codex invokes this binary for each governed tool call, writing the
+ * PreToolUse payload to stdin. The hook evaluates the call against the
+ * local PDLSS policy (shared with the Claude Code adapter: same
+ * ~/.astrasync/policy.yaml + guard.json) and prints a permissionDecision
+ * JSON to stdout only when it wants to tighten the outcome (deny). On
+ * ALLOW — and on MANUAL_REVIEW in prompted permission modes — it prints
+ * nothing, so Codex's own approval flow stays in charge.
+ *
+ * Fail posture: Codex itself FAILS OPEN on hook errors ("reports the error
+ * and continues the tool call"), so unlike the Claude Code hook we cannot
+ * lean on exit codes alone — every internal failure is converted into an
+ * explicit deny decision (opt-outs: ASTRASYNC_GUARD_FAIL_OPEN=1 or
+ * guard.json {"failOpen": true}). A missing policy file everywhere means
+ * the guard simply isn't configured — silent no-op, never a block.
+ */
+
+interface ProcessCodexHookOptions {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    /** Injectable for tests */
+    gatewayFactory?: (config: ConstructorParameters<typeof AstraSyncGateway>[0]) => AstraSyncGateway;
+}
+interface ProcessCodexHookResult {
+    output: CodexHookOutput | null;
+    exitCode: number;
+}
+declare function processCodexHookPayload(payloadJson: string, options?: ProcessCodexHookOptions): Promise<ProcessCodexHookResult>;
+
+/**
+ * AstraSync Local Guard for Claude Code — settings.json installer.
+ *
+ * Merges the guard's PreToolUse hook entry into a Claude Code settings
+ * file (~/.claude/settings.json or <project>/.claude/settings.json)
+ * without clobbering anything else in it, and builds the default policy
+ * for a coding agent.
+ */
+
+interface InstallResult {
+    installed: boolean;
+    alreadyPresent: boolean;
+    updated: boolean;
+}
+
+/**
+ * AstraSync Local Guard for Codex CLI — hooks.json installer.
+ *
+ * Codex reads hooks from ~/.codex/hooks.json (user scope) or
+ * <repo>/.codex/hooks.json (project scope) with the SAME JSON shape as
+ * Claude Code's settings.json (`hooks.PreToolUse[].hooks[]`), so the merge
+ * and uninstall machinery is shared with the Claude Code installer — only
+ * the marker, matcher, and file location differ.
+ *
+ * The policy itself is shared with every other Local Guard adapter on the
+ * machine: ~/.astrasync/policy.yaml + guard.json. One policy per user.
+ */
+
+/** Substring that identifies the guard's hook entry inside hooks.json */
+declare const ASTRASYNC_CODEX_HOOK_MARKER = "astrasync-codex-hook";
+/**
+ * Tools worth spawning the hook for. Codex matchers are regexes over
+ * tool_name; bookkeeping tools (update_plan) never pay node startup cost.
+ */
+declare const CODEX_HOOK_MATCHER = "Bash|apply_patch|Edit|Write|web_search|mcp__.*";
+/**
+ * Merge the guard's PreToolUse entry into a Codex hooks.json file.
+ * Same never-clobber/idempotent semantics as the Claude Code installer.
+ */
+declare function installCodexHooks(hooksPath: string, hookCommand: string): InstallResult;
+/** Remove the guard's PreToolUse entry from a Codex hooks.json file. */
+declare function uninstallCodexHooks(hooksPath: string): boolean;
+
+export { ASTRASYNC_CODEX_HOOK_MARKER, CODEX_HOOK_MATCHER, CODEX_TOOL_MAP, CodexAdapter, type CodexAdapterOptions, type CodexHookOutput, type CodexPreToolUsePayload, DEFAULT_SKIP_TOOLS, type ProcessCodexHookOptions, type ProcessCodexHookResult, UNPROMPTED_PERMISSION_MODES, extractApplyPatchPaths, installCodexHooks, mapMcpTool, processCodexHookPayload, registerCodexMappings, uninstallCodexHooks };