@ory/codex 0.13.9 → 1.0.0

package/dist/handlers.js

@@ -3,14 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleHookEvent = handleHookEvent;
 exports.shouldEmitOutput = shouldEmitOutput;
 const argus_1 = require("@ory/argus");
-/**
- * Route a Codex hook event to the appropriate Ory integration.
- *
- * Codex events: SessionStart, PreToolUse, PostToolUse, PermissionRequest,
- * UserPromptSubmit, Stop. Hooks are declared by the plugin (`hooks` in
- * plugin.json → hooks.json) and must be trusted by the user before they run.
- */
-async function handleHookEvent(input, client, deps = {}) {
+const session_state_js_1 = require("./session-state.js");
+const HARNESS = "codex";
+const SPAWN_PARENT_FLUSH_TIMEOUT_MS = 500;
+const SPAWN_IDENTITY_TIMEOUT_MS = 10_000;
+function handleHookEvent(input, client, deps = {}) {
     const event = input.hook_event_name;
     client.logger.debug("hook.received", {
         event,
@@ -18,145 +15,54 @@ async function handleHookEvent(input, client, deps = {}) {
         toolName: input.tool_name,
         turnId: input.turn_id,
     });
-    // Set trace context so all spans within this hook invocation correlate
-    client.tracer.setContext({
-        traceId: (0, argus_1.deriveTraceId)(input.session_id),
-        sessionId: input.session_id,
-    });
-    try {
+    return (0, argus_1.withHookContext)(client, { sessionId: input.session_id }, async () => {
         switch (event) {
             case "SessionStart":
-                return await handleSessionStart(input, client, deps);
+                return handleSessionStart(input, client, deps);
             case "PreToolUse":
-                return await handlePreToolUse(input, client);
+                return handlePreToolUse(input, client);
             case "PostToolUse":
-                return await handlePostToolUse(input, client);
+                return handlePostToolUse(input, client, deps);
             case "PermissionRequest":
-                return await handlePermissionRequest(input, client);
+                return handlePermissionRequest(input, client);
             case "UserPromptSubmit":
-                return await handleUserPromptSubmit(input, client);
+                return handleUserPromptSubmit(input, client, deps);
             case "Stop":
-                return await handleStop(input, client);
+                return handleStop(input, client);
             default:
                 client.logger.debug("hook.passthrough", { event });
-                client.tracer.record("hook.passthrough", "skipped", {
-                    attributes: { event },
-                });
+                client.logger.activity("hook.passthrough", "skipped", { attributes: { event } });
                 return {};
         }
-    }
-    finally {
-        client.tracer.clearContext();
-    }
+    });
 }
-// ─── SessionStart ───────────────────────────────────────────────────
 async function handleSessionStart(input, client, deps) {
     client.logger.info("lifecycle.session_start", {
         sessionId: input.session_id,
         model: input.model,
         cwd: input.cwd,
     });
-    client.tracer.record("session.start", "ok", {
-        attributes: { model: input.model },
-    });
-    const userGate = deps.userLogin ?? argus_1.ensureUserAuthenticated;
-    const decision = await userGate(client, {
-        binName: "ory-codex",
-        harness: "codex",
-        allowBlock: true,
-    });
-    // Resolve the agent identity (machine credentials). Never blocks;
-    // attaches the agent's bearer token to outgoing Ory API calls.
-    const agentGate = deps.agentGate ?? argus_1.ensureAgentIdentity;
-    await agentGate(client, { projectUrl: (0, argus_1.resolveConfig)().projectUrl, harness: "codex" });
-    // Record the user→agent delegation so the audit trail captures that
-    // this user authorized this agent for this session. Written at most once
-    // per install. Best-effort: requires both principals to be populated, and
-    // any failure is logged and swallowed (fail-open — delegation tracking is
-    // for audit, not enforcement).
-    await (0, argus_1.writeUserDelegatesAgent)(client);
-    if (!decision.proceed) {
-        return { decision: "block", reason: decision.reason };
-    }
-    if (decision.mode !== "disabled") {
-        return {};
-    }
-    const resolved = (0, argus_1.resolveConfig)();
-    if (resolved.auditOnly) {
-        client.logger.info("config.audit_only", {
-            message: "Audit-only mode enabled. Auth and permission checks are disabled.",
-        });
-        return {};
-    }
-    if (!resolved.projectUrl) {
-        client.logger.warn("config.not_configured", {
-            message: "Ory plugin is not configured. Auth and permission checks are disabled. " +
-                "Run 'npx ory-codex configure' to connect to an Ory project.",
-        });
-        return {};
-    }
-    // Try session token first, then OAuth2 token
-    const sessionToken = process.env.ORY_SESSION_TOKEN;
-    const oauth2Token = process.env.ORY_OAUTH2_TOKEN;
-    if (sessionToken) {
-        await verifySessionToken(sessionToken, client);
-        return {};
-    }
-    if (oauth2Token) {
-        await verifyOAuth2Token(oauth2Token, client);
-        return {};
-    }
-    client.logger.warn("session.no_credentials", {
-        message: "Neither ORY_SESSION_TOKEN nor ORY_OAUTH2_TOKEN is set. " +
-            "Skipping authentication.",
-    });
+    await startSession(input, client, deps);
     return {};
 }
-async function verifySessionToken(token, client) {
-    try {
-        const session = await client.verifySession(token);
-        if (!session.active) {
-            client.logger.warn("session.inactive", {
-                message: "Ory session is not active. Re-authenticate to enable auth checks.",
-            });
-        }
-    }
-    catch (err) {
-        const oryErr = err;
-        client.logger.warn("session.verify_failed", {
-            code: oryErr.code,
-            message: oryErr.message,
-        });
-    }
-}
-async function verifyOAuth2Token(token, client) {
+async function startSession(input, client, deps) {
+    await (0, argus_1.sessionStart)(client, {
+        harness: HARNESS,
+        binName: "ory-codex",
+        userLogin: deps.userLogin,
+        agentGate: deps.agentGate,
+        activityAttributes: { model: input.model },
+    });
     try {
-        const tokenInfo = await client.introspectToken(token);
-        if (!tokenInfo.active) {
-            client.logger.warn("oauth2.token_inactive", {
-                message: "Ory OAuth2 token is not active. Obtain a new token to enable auth checks.",
-            });
-            return;
-        }
-        client.logger.info("oauth2.session_authenticated", {
-            clientId: tokenInfo.clientId,
-            subject: tokenInfo.subject,
-            scope: tokenInfo.scope,
-        });
+        (0, session_state_js_1.markCodexSessionStarted)(input.session_id);
     }
     catch (err) {
-        const oryErr = err;
-        client.logger.warn("oauth2.introspect_failed", {
-            code: oryErr.code,
-            message: oryErr.message,
+        client.logger.warn("session_start.marker_write_failed", {
+            message: err instanceof Error ? err.message : String(err),
         });
     }
 }
-// ─── PreToolUse ─────────────────────────────────────────────────────
 async function handlePreToolUse(input, client) {
-    // No default. Codex always sets `tool_name` to the canonical value
-    // (`Bash`, `apply_patch`, or `mcp__<server>__<tool>`). Defaulting to
-    // `"Bash"` here would silently mislabel apply_patch and MCP calls.
     const toolName = input.tool_name;
     if (!toolName) {
         client.logger.warn("pre_tool_use.missing_tool_name", {
@@ -170,112 +76,21 @@ async function handlePreToolUse(input, client) {
         toolName,
         toolInput: input.tool_input,
     });
-    const inputSummary = (0, argus_1.summarizeToolInput)(toolName, input.tool_input);
-    // In audit-only mode, log the invocation but skip permission checks
-    if ((0, argus_1.resolveConfig)().auditOnly) {
-        client.tracer.record("tool.invoke", "ok", {
-            attributes: { toolName, ...inputSummary },
-        });
-        return {};
-    }
-    const subject = (0, argus_1.resolveUserSubject)(client, `session:${input.session_id}`);
-    const subjectId = (0, argus_1.subjectLabel)(subject);
-    const mcpTool = (0, argus_1.parseMcpToolGeneric)(toolName);
-    try {
-        if (mcpTool) {
-            const mcpResult = await (0, argus_1.checkMcpPermission)(client, mcpTool, {
-                subject,
-                spanAttributes: { toolName },
-            });
-            const mcpAttrs = {
-                toolName,
-                mcpServer: mcpTool.serverName,
-                mcpTool: mcpTool.toolName,
-                ...inputSummary,
-            };
-            const decision = (0, argus_1.applyPermissionMode)(client, mcpResult.allowed, {
-                object: mcpTool.serverName,
-                relation: "use",
-                subjectId,
-                ...("subjectSet" in subject ? { subjectSet: subject.subjectSet } : {}),
-                spanAttributes: mcpAttrs,
-            });
-            const decisionAttrs = decision.spanAttributes;
-            if (decision.kind === "allow") {
-                client.tracer.record("tool.invoke", "ok", {
-                    attributes: { ...mcpAttrs, ...decisionAttrs },
-                });
-                return {};
-            }
-            if (decision.kind === "observe") {
-                client.tracer.record("tool.block", "denied", {
-                    attributes: { ...mcpAttrs, ...decisionAttrs, allowed: false, ...(0, argus_1.alertAttributes)(false) },
-                });
-                client.tracer.record("tool.invoke", "ok", {
-                    attributes: { ...mcpAttrs, ...decisionAttrs, allowed: false, observed: true },
-                });
-                return {};
-            }
-            client.tracer.record("tool.block", "denied", {
-                attributes: { ...mcpAttrs, ...decisionAttrs, allowed: false, ...(0, argus_1.alertAttributes)(true) },
-            });
-            return {
-                decision: "block",
-                reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }),
-            };
-        }
-        const namespace = resolveNamespace();
-        const outcome = await (0, argus_1.gateToolCall)(client, {
-            harness: "codex",
-            toolName,
-            check: { namespace, object: toolName, relation: "use", ...subject },
-            spanAttributes: { toolName },
-        });
-        // Interactive tools (operator-extensible via ORY_INTERACTIVE_TOOLS):
-        // pass through with the user.interaction span already recorded.
-        if (outcome.kind === "interactive") {
-            return {};
-        }
-        const decision = outcome;
-        if (decision.kind === "fail_open") {
-            return handlePermissionError(decision.error, toolName, client);
-        }
-        const attrs = { toolName, ...inputSummary };
-        const decisionAttrs = decision.spanAttributes;
-        if (decision.kind === "allow") {
-            client.tracer.record("tool.invoke", "ok", {
-                attributes: { ...attrs, ...decisionAttrs, allowed: true },
-            });
-            return {};
-        }
-        if (decision.kind === "observe") {
-            client.tracer.record("tool.block", "denied", {
-                attributes: { ...attrs, ...decisionAttrs, allowed: false, ...(0, argus_1.alertAttributes)(false) },
-            });
-            client.tracer.record("tool.invoke", "ok", {
-                attributes: { ...attrs, ...decisionAttrs, allowed: false, observed: true },
-            });
-            return {};
-        }
-        client.tracer.record("tool.block", "denied", {
-            attributes: { ...attrs, ...decisionAttrs, allowed: false, ...(0, argus_1.alertAttributes)(true) },
-        });
-        return {
-            decision: "block",
-            reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }),
-        };
-    }
-    catch (err) {
-        return handlePermissionError(err, toolName, client);
-    }
+    const result = await (0, argus_1.gate)(client, {
+        harness: HARNESS,
+        toolName,
+        toolArgs: input.tool_input,
+        subjectFallback: `session:${input.session_id}`,
+        mcpTool: (0, argus_1.parseMcpToolGeneric)(toolName) ?? undefined,
+    });
+    return result.blocked
+        ? { decision: "block", reason: result.denialMessage }
+        : {};
 }
-// ─── PostToolUse ────────────────────────────────────────────────────
-async function handlePostToolUse(input, client) {
+async function handlePostToolUse(input, client, deps) {
     const toolName = input.tool_name;
     if (!toolName) {
-        client.logger.warn("post_tool_use.missing_tool_name", {
-            sessionId: input.session_id,
-        });
+        client.logger.warn("post_tool_use.missing_tool_name", { sessionId: input.session_id });
         return {};
     }
     client.logger.info("lifecycle.post_tool_use", {
@@ -284,24 +99,85 @@ async function handlePostToolUse(input, client) {
         turnId: input.turn_id,
         toolUseId: input.tool_use_id,
     });
-    client.tracer.record("tool.complete", "ok", {
-        attributes: {
-            toolName,
-            turnId: input.turn_id,
-            toolUseId: input.tool_use_id,
-            ...(0, argus_1.summarizeToolInput)(toolName, input.tool_input),
-            ...(0, argus_1.summarizeToolOutput)(toolName, input.tool_response),
-        },
+    const collaborationSpawn = isCollaborationSpawn(toolName);
+    const spawnSignal = collaborationSpawn
+        ? AbortSignal.timeout(SPAWN_IDENTITY_TIMEOUT_MS)
+        : undefined;
+    if (collaborationSpawn) {
+        await (0, argus_1.ensureReadCredential)(client, {
+            harness: HARNESS,
+            agentGate: deps.agentGate,
+            signal: spawnSignal,
+        });
+    }
+    (0, argus_1.complete)(client, {
+        toolName,
+        input: input.tool_input,
+        output: input.tool_response,
+        extraActivityAttributes: { turnId: input.turn_id, toolUseId: input.tool_use_id },
     });
+    if (collaborationSpawn) {
+        // Keep the spawn tool's events attributed to the parent before switching
+        // the reporter to the newly authenticated Sub-Agent.
+        await client.flushEvents(SPAWN_PARENT_FLUSH_TIMEOUT_MS);
+        const subAgentType = "collaboration";
+        let subAgentKind;
+        let subAgentReason;
+        let subAgentSubject;
+        let subAgentToken;
+        const subAgentGate = deps.subAgentGate ?? argus_1.ensureSubAgentIdentity;
+        await (0, argus_1.registerSubagent)(client, {
+            harness: HARNESS,
+            subAgentType,
+            perSpawnId: input.tool_use_id,
+            signal: spawnSignal,
+            subAgentGate: async (gateClient, options) => {
+                const identity = await subAgentGate(gateClient, {
+                    ...options,
+                    emitActivity: false,
+                });
+                subAgentKind = identity.kind;
+                subAgentReason = identity.reason;
+                subAgentSubject = identity.subject;
+                subAgentToken = identity.token;
+                return identity;
+            },
+        });
+        if (subAgentKind === "runtime" || (subAgentSubject && subAgentToken)) {
+            if (subAgentSubject && subAgentToken) {
+                client.setAgentPrincipal({ subject: subAgentSubject, token: subAgentToken });
+            }
+            client.logger.activity("agent.auth", "ok", {
+                attributes: {
+                    kind: subAgentKind === "runtime" ? "subagent_runtime" : "subagent_dynamic",
+                    subAgentType,
+                    ...(subAgentSubject ? { subject: subAgentSubject } : {}),
+                },
+            });
+            client.logger.activity("subagent.start", "ok", {
+                attributes: { subAgentType, agentId: input.tool_use_id },
+            });
+        }
+        else {
+            client.logger.activity("agent.auth", "skipped", {
+                attributes: {
+                    kind: subAgentKind === "dynamic" ? "subagent_dynamic" : "subagent_none",
+                    subAgentType,
+                    reason: subAgentReason,
+                },
+            });
+        }
+    }
     return {};
 }
-// ─── PermissionRequest ──────────────────────────────────────────────
+function isCollaborationSpawn(toolName) {
+    const normalized = toolName.toLowerCase().replace(/[^a-z0-9]/g, "");
+    return normalized === "collaborationspawnagent" || normalized === "spawnagent";
+}
 async function handlePermissionRequest(input, client) {
     const toolName = input.tool_name;
     if (!toolName) {
-        client.logger.warn("permission_request.missing_tool_name", {
-            sessionId: input.session_id,
-        });
+        client.logger.warn("permission_request.missing_tool_name", { sessionId: input.session_id });
         return {};
     }
     client.logger.info("lifecycle.permission_request", {
@@ -309,71 +185,31 @@ async function handlePermissionRequest(input, client) {
         toolName,
         turnId: input.turn_id,
     });
-    if ((0, argus_1.resolveConfig)().auditOnly) {
-        return permissionRequestFallback("Audit-only mode — deferring to user");
+    const mcpTool = (0, argus_1.parseMcpToolGeneric)(toolName);
+    const result = await (0, argus_1.decideTool)(client, {
+        harness: HARNESS,
+        toolName,
+        toolArgs: input.tool_input,
+        subjectFallback: `session:${input.session_id}`,
+        mcpTool: mcpTool ?? undefined,
+    });
+    if (result.kind === "not_connected") {
+        return permissionRequestFallback("Ory Agent Security not connected — deferring to user");
     }
-    // Interactive tools: defer to the user instead of pre-answering.
-    if ((0, argus_1.isInteractiveTool)("codex", toolName)) {
-        client.tracer.record("user.interaction", "ok", {
-            attributes: { harness: "codex", toolName, kind: "permission-request" },
-        });
+    if (result.kind === "interactive") {
         return permissionRequestFallback("Interactive tool — deferring to user");
     }
-    const subject = (0, argus_1.resolveUserSubject)(client, `session:${input.session_id}`);
-    const subjectId = (0, argus_1.subjectLabel)(subject);
-    const mcpTool = (0, argus_1.parseMcpToolGeneric)(toolName);
-    try {
-        if (mcpTool) {
-            const mcpResult = await (0, argus_1.checkMcpPermission)(client, mcpTool, {
-                subject,
-                spanAttributes: { toolName },
-            });
-            const decision = (0, argus_1.applyPermissionMode)(client, mcpResult.allowed, {
-                object: mcpTool.serverName,
-                relation: "use",
-                subjectId,
-                ...("subjectSet" in subject ? { subjectSet: subject.subjectSet } : {}),
-                spanAttributes: { toolName, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName },
-            });
-            if (decision.kind === "deny") {
-                return permissionRequestDecision("deny", (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }));
-            }
-            return permissionRequestDecision("allow", decision.kind === "observe"
-                ? "Ory observe mode — denied by policy but allowed through"
-                : "Ory MCP server permission granted");
-        }
-        const namespace = resolveNamespace();
-        const outcome = await (0, argus_1.gateToolCall)(client, {
-            harness: "codex",
-            toolName,
-            check: { namespace, object: toolName, relation: "use", ...subject },
-            spanAttributes: { toolName },
-        });
-        if (outcome.kind === "interactive") {
-            return permissionRequestFallback("Interactive tool — deferring to user");
-        }
-        const decision = outcome;
-        if (decision.kind === "fail_open") {
-            const code = decision.error.code;
-            const reason = code === "network_error" || code === "rate_limited"
-                ? `Ory unavailable (${code}), falling back to user prompt`
-                : `Ory permission check failed: ${decision.error.message}`;
-            return permissionRequestFallback(reason);
-        }
-        if (decision.kind === "deny") {
-            return permissionRequestDecision("deny", (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }));
-        }
-        return permissionRequestDecision("allow", decision.kind === "observe"
-            ? "Ory observe mode — denied by policy but allowed through"
-            : "Ory permission granted");
+    if (result.kind === "fail_open") {
+        return permissionRequestFallback(permissionFailureReason(result.decision));
     }
-    catch (err) {
-        const oryErr = err;
-        const reason = oryErr.code === "network_error" || oryErr.code === "rate_limited"
-            ? `Ory unavailable (${oryErr.code}), falling back to user prompt`
-            : `Ory permission check failed: ${oryErr.message}`;
-        return permissionRequestFallback(reason);
+    if (result.kind === "deny") {
+        return permissionRequestDecision("deny", result.denialMessage ?? "Ory permission denied");
     }
+    return permissionRequestDecision("allow", result.kind === "observe"
+        ? "Ory observe mode — denied by policy but allowed through"
+        : mcpTool
+            ? "Ory MCP server permission granted"
+            : "Ory permission granted");
 }
 function permissionRequestDecision(behavior, message) {
     return {
@@ -384,36 +220,48 @@ function permissionRequestDecision(behavior, message) {
     };
 }
 function permissionRequestFallback(message) {
-    return {
-        hookSpecificOutput: {
-            hookEventName: "PermissionRequest",
-            message,
-        },
-    };
+    return { hookSpecificOutput: { hookEventName: "PermissionRequest", message } };
+}
+function permissionFailureReason(decision) {
+    if (decision.kind !== "fail_open")
+        return "Ory permission check failed";
+    const { code, message } = decision.error;
+    return code === "network_error" || code === "rate_limited"
+        ? `Ory unavailable (${code}), falling back to user prompt`
+        : `Ory permission check failed: ${message}`;
 }
-// ─── UserPromptSubmit ───────────────────────────────────────────────
-async function handleUserPromptSubmit(input, client) {
+async function handleUserPromptSubmit(input, client, deps) {
+    let sessionStarted = false;
+    try {
+        sessionStarted = (0, session_state_js_1.hasCodexSessionStarted)(input.session_id);
+    }
+    catch (err) {
+        client.logger.warn("session_start.marker_read_failed", {
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+    if (!sessionStarted) {
+        // Codex consumes SessionStart only once. If the plugin was installed or
+        // trusted afterward, recover before processing the next prompt.
+        await startSession(input, client, deps);
+    }
     client.logger.info("lifecycle.user_prompt_submit", {
         sessionId: input.session_id,
         turnId: input.turn_id,
         promptLen: input.prompt?.length,
     });
-    client.tracer.record("user.prompt", "ok", {
-        attributes: {
-            turnId: input.turn_id,
-            promptLen: input.prompt?.length,
-        },
+    client.logger.activity("user.prompt", "ok", {
+        attributes: { turnId: input.turn_id, promptLen: input.prompt?.length },
     });
     return {};
 }
-// ─── Stop ───────────────────────────────────────────────────────────
 async function handleStop(input, client) {
     client.logger.info("lifecycle.stop", {
         sessionId: input.session_id,
         turnId: input.turn_id,
         stopHookActive: input.stop_hook_active,
     });
-    client.tracer.record("turn.stop", "ok", {
+    client.logger.activity("turn.stop", "ok", {
         attributes: {
             turnId: input.turn_id,
             stopHookActive: input.stop_hook_active,
@@ -422,42 +270,6 @@ async function handleStop(input, client) {
     });
     return {};
 }
-// ─── Helpers ────────────────────────────────────────────────────────
-/**
- * Whether a hook output carries anything Codex needs to see on stdout.
- *
- * The hook entry point handles `decision === "block"` (exit code 2 + stdout)
- * before consulting this. Everything else with at least one populated field
- * must be written to stdout — most importantly `hookSpecificOutput`, which
- * carries the PermissionRequest allow/deny decision. Empty outputs stay
- * silent to keep stdout clean for the harness.
- */
 function shouldEmitOutput(output) {
     return Object.values(output).some((value) => value !== undefined);
 }
-function resolveNamespace() {
-    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
-}
-function handlePermissionError(oryErr, toolName, client) {
-    if (oryErr.code === "network_error") {
-        client.logger.warn("permission.network_error", {
-            toolName,
-            message: "Ory unreachable, failing open",
-        });
-        return {};
-    }
-    if (oryErr.code === "rate_limited") {
-        client.logger.warn("permission.rate_limited", {
-            toolName,
-            message: "Ory rate limited, failing open",
-        });
-        return {};
-    }
-    // For other errors, also fail open but log prominently
-    client.logger.error("permission.check.error", {
-        toolName,
-        code: oryErr.code,
-        message: oryErr.message,
-    });
-    return {};
-}