clinkx 0.2.3 → 1.0.0

package/dist/codex/agent-tools.js

@@ -0,0 +1,1270 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { AdapterRegistry } from "../registry.js";
+import { assemblePrompt } from "../prompt.js";
+import { ContinuationCache } from "../continuation.js";
+import { appServerEnabled } from "../config.js";
+import { CancellationError, InvalidParamsError } from "../errors.js";
+import { logger } from "../logger.js";
+import { limitOutput } from "../pipeline.js";
+import { validateExistingDirectory } from "../paths.js";
+import { createActivitySessionLogObserver } from "./activity-session-log.js";
+import { getAppServerRegistry, peekAppServerRegistry, spawnRequestFor, } from "./app-server-registry.js";
+import { sandboxPolicyFromMode } from "./app-server-client.js";
+import { CODEX_APP_SERVER_PROTOCOL_VERSION, SUPPORTED_COMMAND_EXECUTION_APPROVAL_DECISIONS, SupportedCommandExecutionApprovalDecisionSchema, } from "./protocol.js";
+const DEFAULT_MAX_RESPONSE_CHARS = 20_000;
+const PENDING_APPROVAL_FIELD_CHARS = 2_000;
+// Bounds for the model/list passthrough: a configurable/compromisable child
+// app-server could return an oversized payload, so cap both the row count and
+// every surfaced string field before it reaches the caller.
+const MAX_LIST_MODELS = 100;
+const MODEL_DESCRIPTION_CHARS = 500;
+const MODEL_IDENTIFIER_CHARS = 128;
+const MODEL_EFFORT_CHARS = 64;
+const MAX_SUPPORTED_REASONING_EFFORTS = 16;
+// Pagination cursors are opaque tokens that can legitimately be long; cap with a
+// GENEROUS ceiling to bound a compromised child app-server without corrupting a
+// valid cursor (which would break page-two fetches). NOT the tight identifier cap.
+const MAX_CURSOR_CHARS = 4096;
+const SandboxModeSchema = z.enum([
+    "read-only",
+    "workspace-write",
+    "danger-full-access",
+]);
+const ApprovalModeSchema = z.enum([
+    "untrusted",
+    "on-failure",
+    "on-request",
+    "granular",
+    "never",
+]);
+const SessionStatusSchema = z.enum([
+    "running",
+    "completed",
+    "interrupted",
+    "failed",
+    "timeout",
+]);
+const AgentRunInputSchema = z
+    .object({
+    prompt: z.string().min(1).describe("The task or question for the Codex session"),
+    cli_name: z.string().min(1).optional(),
+    role: z.string().default("default"),
+    absolute_file_paths: z.array(z.string()).optional(),
+    images: z.array(z.string()).optional(),
+    context: z.string().optional(),
+    cwd: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Optional working directory for the Codex child. Must be an existing directory inside CLINKX_ALLOWED_ROOTS; when supplied with workspace-write it is the sole explicit writable root."),
+    continuation_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Write/read-symmetric thread alias (process-local; lost on ClinkX restart). This run is tagged under this continuation_id, and passing the SAME continuation_id back on a later run resumes that thread (real model state). Its first use is never an error — it just starts a fresh thread. Alias resume precedence: resume_continuation_id > session_id > continuation_id."),
+    session_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Resume alias for a prior session: looked up to recover that session's thread (errors if unknown). Does NOT set the new session's id (always auto-generated). Mutually exclusive with resume_thread_id and resume_continuation_id. Takes precedence over continuation_id, but is overridden by resume_thread_id and resume_continuation_id."),
+    resume_continuation_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Resume an existing thread by its prior continuation_id — restores real model state (unlike clink's text-append), erroring if unknown. Mutually exclusive with resume_thread_id and session_id. Highest alias resume precedence (over session_id and continuation_id)."),
+    resume_thread_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Resume an existing Codex thread by its RAW thread_id (from a prior snapshot's thread_id). Unlike the process-local continuation_id/session_id aliases, a raw thread_id survives a ClinkX restart (the on-disk rollout persists). Highest resume precedence. Mutually exclusive with session_id and resume_continuation_id."),
+    wait: z
+        .boolean()
+        .default(true)
+        .describe("true: block until the turn reaches a terminal state and return the final text. false: return once the turn is RUNNING, then drive it with clink_agent_manage (poll/wait/steer/respond)."),
+    timeout_seconds: z.number().positive().optional(),
+    max_response_chars: z.number().int().positive().optional(),
+    model: z.string().min(1).optional(),
+    sandbox: SandboxModeSchema.optional().describe('Filesystem sandbox for this turn: "read-only" (safe default), "workspace-write" (write within the workspace), or "danger-full-access" (unrestricted; only when the adapter sets allow_danger_full_access:true). Per-call override of the adapter default.'),
+    approval: ApprovalModeSchema.optional().describe('Approval policy: "never" runs without prompting; "on-request"/"on-failure"/"granular" surface approval requests you answer via clink_agent_manage op:"respond". Use a non-"never" mode whenever the turn can write files or run commands.'),
+    output_schema: z
+        .record(z.unknown())
+        .optional()
+        .describe("JSON Schema object constraining the turn's final assistant message to that shape. When supplied and the turn ends with terminal text, the run response adds a best-effort parsed `final_json` (null if the text is not valid JSON)."),
+    debug: z.boolean().default(false),
+})
+    .strict();
+// Cap on batch poll/wait fan-out. Enforced in the handler (not via a schema
+// .refine, which would turn these discriminatedUnion arms into ZodEffects and
+// break union construction).
+const MAX_BATCH_SESSION_IDS = 50;
+const BatchSessionIdsSchema = z
+    .array(z.string().min(1))
+    .optional()
+    .describe("Batch form: address multiple sessions at once. Provide exactly one of session_id or session_ids (max 50). poll returns { snapshots }; wait races all ids and returns on the first ACTIONABLE session (terminal, or paused on a pending approval).");
+const PollSchema = z.object({
+    op: z.literal("poll"),
+    session_id: z.string().min(1).optional(),
+    session_ids: BatchSessionIdsSchema,
+}).strict();
+const WaitSchema = z.object({
+    op: z.literal("wait"),
+    session_id: z.string().min(1).optional(),
+    session_ids: BatchSessionIdsSchema,
+    timeout_seconds: z.number().positive().optional(),
+}).strict();
+const SteerSchema = z.object({
+    op: z.literal("steer"),
+    session_id: z.string().min(1),
+    prompt: z.string().min(1),
+}).strict();
+const RespondSchema = z.object({
+    op: z.literal("respond"),
+    session_id: z.string().min(1),
+    // Approval (JSON-RPC request) ids are string-or-number per the protocol
+    // RequestId union; live Codex emits numeric ids. Pass through unchanged.
+    approval_id: z.union([z.string().min(1), z.number()]),
+    decision: SupportedCommandExecutionApprovalDecisionSchema,
+}).strict();
+const SessionOnlySchema = (op) => z.object({
+    op: z.literal(op),
+    session_id: z.string().min(1),
+}).strict();
+const CleanupSchema = z.object({
+    op: z.literal("cleanup"),
+    session_id: z.string().min(1),
+    force: z.boolean().default(false),
+}).strict();
+const HealthSchema = z.object({
+    op: z.literal("health"),
+}).strict();
+const ListModelsSchema = z.object({
+    op: z.literal("list_models"),
+    cursor: z.string().min(1).optional(),
+    include_hidden: z.boolean().optional(),
+    limit: z.number().int().nonnegative().optional(),
+}).strict();
+const GetLogSchema = z.object({
+    op: z.literal("get_log"),
+    session_id: z.string().min(1),
+    cursor: z.number().int().nonnegative().optional(),
+    limit: z.number().int().nonnegative().optional(),
+}).strict();
+const ListSchema = z.object({
+    op: z.literal("list"),
+    status: SessionStatusSchema.optional(),
+    offset: z.number().int().nonnegative().default(0),
+    limit: z.number().int().positive().optional(),
+}).strict();
+const AgentManageInputSchema = z.discriminatedUnion("op", [
+    PollSchema,
+    WaitSchema,
+    SteerSchema,
+    RespondSchema,
+    SessionOnlySchema("cancel"),
+    GetLogSchema,
+    ListSchema,
+    CleanupSchema,
+    HealthSchema,
+    ListModelsSchema,
+]);
+export const AGENT_TOOL_NAMES = new Set([
+    "clink_agent_run",
+    "clink_agent_manage",
+]);
+/**
+ * Bounded, insertion-order (oldest-first eviction) map. Keeps the process-global
+ * resume aliases from growing without limit in a long-running STDIO server.
+ */
+class BoundedAliasMap {
+    maxEntries;
+    map = new Map();
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+    }
+    set(key, value) {
+        this.map.delete(key);
+        if (this.map.size >= this.maxEntries) {
+            const oldest = this.map.keys().next();
+            if (!oldest.done)
+                this.map.delete(oldest.value);
+        }
+        this.map.set(key, value);
+    }
+    get(key) {
+        return this.map.get(key);
+    }
+    delete(key) {
+        this.map.delete(key);
+    }
+    get size() {
+        return this.map.size;
+    }
+    clear() {
+        this.map.clear();
+    }
+}
+const MAX_ASYNC_ALIASES = 100;
+/**
+ * Async tool-local resume aliases. They intentionally live only in this MCP
+ * process: restarting ClinkX loses these continuation_id/session aliases even
+ * though the Codex rollout/thread may still exist on disk and can be recovered
+ * by other app-server mechanisms. Bounded (LRU-by-insertion) so the maps cannot
+ * grow without limit; `sessionContinuationKeys` lets cleanup prune the paired
+ * continuation alias rather than leaking a still-resumable thread.
+ */
+const asyncThreadIds = new BoundedAliasMap(MAX_ASYNC_ALIASES);
+const sessionContinuationKeys = new BoundedAliasMap(MAX_ASYNC_ALIASES);
+const emptyContinuationCache = new ContinuationCache(1);
+export function getAgentToolDefinitions(appServerCliNames = []) {
+    const runSchema = zodToJsonSchema(AgentRunInputSchema, {
+        target: "jsonSchema7",
+        $refStrategy: "none",
+    });
+    // ADVERTISED schema for clink_agent_manage. AgentManageInputSchema is a
+    // z.discriminatedUnion("op", ...) which serializes to a root `anyOf` with no
+    // top-level `properties`; stricter MCP clients drop a tool whose root has no
+    // `properties`. We therefore hand-author a FLAT object schema (root
+    // properties, no root anyOf) as a permissive superset for advertisement.
+    // `op` is the only universally-required field; strict per-op validation is
+    // still enforced at runtime by AgentManageInputSchema (see handleAgentManage).
+    const manageSchema = {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        type: "object",
+        additionalProperties: false,
+        required: ["op"],
+        properties: {
+            op: {
+                type: "string",
+                enum: [
+                    "poll",
+                    "wait",
+                    "steer",
+                    "respond",
+                    "cancel",
+                    "get_log",
+                    "list",
+                    "cleanup",
+                    "health",
+                    "list_models",
+                ],
+                description: "Operation. poll: current snapshot; wait: block until terminality; " +
+                    "steer: send a follow-up prompt into the active turn; respond: answer a " +
+                    "pending approval (accept/acceptForSession/decline/cancel); cancel: interrupt the turn; " +
+                    "get_log: event history; list: enumerate live in-process sessions; " +
+                    "cleanup: drop a session; health: inspect app-server backend health; " +
+                    "list_models: list available models via model/list.",
+            },
+            session_id: {
+                type: "string",
+                minLength: 1,
+                description: "Target session (poll/wait/steer/respond/cancel/get_log/cleanup; " +
+                    "provide exactly one of session_id or session_ids for poll/wait).",
+            },
+            session_ids: {
+                type: "array",
+                items: { type: "string", minLength: 1 },
+                maxItems: 50,
+                description: "Batch form for poll/wait (max 50).",
+            },
+            prompt: {
+                type: "string",
+                minLength: 1,
+                description: "steer: the follow-up prompt.",
+            },
+            decision: {
+                type: "string",
+                enum: [...SUPPORTED_COMMAND_EXECUTION_APPROVAL_DECISIONS],
+                description: "respond: approval decision.",
+            },
+            approval_id: {
+                type: ["string", "number"],
+                minLength: 1,
+                description: "respond: JSON-RPC approval request id to answer (string or number; minLength applies only to the string form).",
+            },
+            cursor: {
+                type: ["integer", "string"],
+                minimum: 0,
+                description: "get_log: integer start offset into the event ring; " +
+                    "list_models: opaque string pagination token returned as a prior call's next_cursor " +
+                    "(minimum applies only to the integer get_log form and is ignored for the string form).",
+            },
+            include_hidden: {
+                type: "boolean",
+                description: "list_models: include hidden models in the result.",
+            },
+            limit: {
+                type: "integer",
+                minimum: 0,
+                description: "get_log/list/list_models: max items.",
+            },
+            status: {
+                type: "string",
+                enum: ["running", "completed", "interrupted", "failed", "timeout"],
+                description: "list: optional status filter.",
+            },
+            offset: {
+                type: "integer",
+                minimum: 0,
+                description: "list: pagination offset.",
+            },
+            timeout_seconds: {
+                type: "number",
+                exclusiveMinimum: 0,
+                description: "wait: max seconds to block.",
+            },
+            force: {
+                type: "boolean",
+                default: false,
+                description: "cleanup: when true, interrupt a running turn before eviction. Default false skips active sessions.",
+            },
+        },
+    };
+    const props = runSchema["properties"];
+    if (props?.["cli_name"] != null && appServerCliNames.length > 0) {
+        props["cli_name"]["enum"] = appServerCliNames;
+        props["cli_name"]["description"] =
+            `Codex app-server adapter to use (defaults to the sole configured one when omitted).` +
+                ` Available: ${appServerCliNames.join(", ")}`;
+    }
+    return [
+        {
+            name: "clink_agent_run",
+            description: "Start a Codex app-server agent turn — the stateful, session-based path. " +
+                "Prefer this over clink for Codex whenever the work is multi-turn, needs an approval gate on file/command actions, " +
+                "needs per-call sandbox control, or should be resumable (resume_continuation_id restores real model state, not text re-paste). " +
+                "Set wait:false to start the turn and then drive it with clink_agent_manage; wait:true blocks for the final answer. " +
+                "For a single self-contained, stateless shot, plain clink is simpler.",
+            inputSchema: runSchema,
+            annotations: {
+                readOnlyHint: false,
+            },
+        },
+        {
+            name: "clink_agent_manage",
+            description: "Drive or inspect a running Codex app-server session started by clink_agent_run. Ops: " +
+                'poll (current snapshot), wait (block for terminality), steer (send a follow-up prompt into the active turn), ' +
+                'respond (answer a pending approval: accept/acceptForSession/decline/cancel), cancel (interrupt), get_log (event history), ' +
+                'list (enumerate live in-process sessions — not persisted Codex threads), cleanup (drop a session), ' +
+                'health (backend counters/version envelope), list_models (list available models via model/list). ' +
+                "Use respond when a turn started with a non-\"never\" approval mode pauses for an approval request.",
+            inputSchema: manageSchema,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: true,
+            },
+        },
+    ];
+}
+export async function handleAgentToolCall(name, args, options = {}) {
+    if (!appServerEnabled()) {
+        throw new InvalidParamsError("Codex app-server async tools are disabled. Set CLINKX_APP_SERVER_ENABLED=true to enable them.");
+    }
+    if (name === "clink_agent_run") {
+        return handleAgentRun(args, options);
+    }
+    if (name === "clink_agent_manage") {
+        return handleAgentManage(args, options);
+    }
+    throw new InvalidParamsError(`Unknown Codex agent tool: ${name}`);
+}
+async function handleAgentRun(args, options) {
+    const input = parseWithSchema(AgentRunInputSchema, args, "clink_agent_run");
+    const resumeSelectorCount = (input.resume_thread_id != null ? 1 : 0) +
+        (input.session_id != null ? 1 : 0) +
+        (input.resume_continuation_id != null ? 1 : 0);
+    if (resumeSelectorCount > 1) {
+        throw new InvalidParamsError("clink_agent_run accepts only one of resume_thread_id, session_id, or resume_continuation_id.");
+    }
+    throwIfAborted(options.signal);
+    const adapterRegistry = options.adapterRegistry ?? AdapterRegistry.load();
+    const adapter = resolveAppServerAdapter(adapterRegistry, input.cli_name);
+    // The app-server turn input is text-only. If the caller supplied images but the
+    // resolved adapter cannot carry them, reject rather than silently degrading them
+    // into manifest TEXT inside the prompt (which the model would treat as a path
+    // listing, not an image). Fail loud so the caller can drop them or pick an
+    // image-capable adapter (F5).
+    if (input.images != null &&
+        input.images.length > 0 &&
+        adapter.supports_images !== true) {
+        throw new InvalidParamsError(`Adapter "${adapter.name}" does not support images (supports_images:false); ` +
+            "remove the images field or use an image-capable adapter.");
+    }
+    const policy = resolvePolicies(adapter, input);
+    const registry = options.registry ?? getAppServerRegistry(spawnRequestFor(adapter));
+    const resumeThreadId = resolveResumeThreadId(input, registry);
+    const resumedFrom = effectiveResumeKey(input, resumeThreadId);
+    const sessionId = `clink-agent-${randomUUID()}`;
+    const prompt = buildAsyncPrompt(input, adapter);
+    const cwd = resolveAgentCwd(input.cwd);
+    const sandboxPolicy = sandboxPolicyFromMode(policy.sandbox, cwd != null ? { writableRoots: [cwd] } : undefined);
+    const activityObservation = await beginAgentActivity(options.activityJournal, {
+        activityId: sessionId,
+        kind: "clink_agent_run",
+        adapter: adapter.name,
+        role: input.role,
+        projectFolders: [cwd ?? process.cwd()],
+    });
+    const sessionObserver = options.sessionLogRootDir !== undefined && activityObservation?.identity !== undefined
+        ? createActivitySessionLogObserver({
+            rootDir: options.sessionLogRootDir,
+            activityIdentity: activityObservation.identity,
+        })
+        : undefined;
+    let started;
+    try {
+        started = await registry.startSession({
+            sessionId,
+            input: [{ type: "text", text: prompt }],
+            sandbox: policy.sandbox,
+            approval: policy.approval,
+            approvalPolicy: policy.approval,
+            sandboxPolicy,
+            ...(cwd != null ? { cwd } : {}),
+            ...(policy.model != null ? { model: policy.model } : {}),
+            ...(input.output_schema != null ? { outputSchema: input.output_schema } : {}),
+            ...(resumeThreadId != null ? { resumeThreadId } : {}),
+            ...(activityObservation != null ? { activityObservation } : {}),
+            ...(sessionObserver != null ? { sessionObserver } : {}),
+            // Mirror the async wait timeout into the per-session turn timer so an
+            // explicit timeout_seconds drives both (review fix B). The async path
+            // derives the turn timeout ONLY from input.timeout_seconds — NOT from
+            // adapter.timeout_seconds — so without a per-call timeout an async turn
+            // falls back to the global CLINKX_TURN_TIMEOUT_SECONDS default. This is
+            // intentional: the async API is caller-driven (not a bug).
+            ...(input.timeout_seconds != null
+                ? { turnTimeoutMs: Math.ceil(input.timeout_seconds * 1000) }
+                : {}),
+        });
+    }
+    catch (err) {
+        await completeAgentActivity(activityObservation, "failed");
+        throw err;
+    }
+    rememberThread(input, started);
+    if (!input.wait) {
+        return jsonResult({
+            session_id: started.sessionId,
+            status: "running",
+            resumed_from: resumedFrom,
+        });
+    }
+    const startedAt = Date.now();
+    const waited = await waitForRun(registry, started.sessionId, input, options.signal);
+    rememberThread(input, waited);
+    const response = snapshotResponse(waited, input.max_response_chars);
+    response["resumed_from"] = resumedFrom;
+    addWaitMetadata(response, waited, Date.now() - startedAt);
+    addPendingApprovalNextAction(response, waited);
+    if (input.output_schema != null) {
+        // Best-effort: parse the raw (un-truncated) final text against the requested
+        // schema's intent. Never throw — leave final_json null on parse failure.
+        response["final_json"] = parseFinalJson(waited.finalText);
+    }
+    return jsonResult(response, { isError: snapshotIsError(waited) });
+}
+async function beginAgentActivity(journal, input) {
+    if (journal == null)
+        return undefined;
+    try {
+        return await journal.begin(input);
+    }
+    catch (err) {
+        logger.debug({ err: err instanceof Error ? err.message : String(err) }, "clink_agent_run: dashboard activity admission failed open");
+        return undefined;
+    }
+}
+async function completeAgentActivity(observation, status) {
+    if (observation == null)
+        return;
+    try {
+        if (status === "completed") {
+            await observation.complete({
+                status: "succeeded",
+                outcomeKind: "success",
+            });
+        }
+        else if (status === "interrupted") {
+            await observation.complete({
+                status: "cancelled",
+                outcomeKind: "cancelled",
+            });
+        }
+        else {
+            await observation.complete({
+                status: "failed",
+                outcomeKind: "error",
+            });
+        }
+    }
+    catch (err) {
+        logger.debug({ err: err instanceof Error ? err.message : String(err) }, "clink_agent_run: dashboard activity completion failed open");
+    }
+}
+function resolveAgentCwd(cwd) {
+    if (cwd == null) {
+        logger.debug("clink_agent_run cwd omitted; Codex child will inherit the ClinkX launch directory");
+        return undefined;
+    }
+    return validateExistingDirectory(cwd);
+}
+async function handleAgentManage(args, options) {
+    const input = parseWithSchema(AgentManageInputSchema, args, "clink_agent_manage");
+    if (input.op === "list_models") {
+        return handleListModels(input, options);
+    }
+    // Use a NON-creating accessor: a manage op must never construct the singleton
+    // with the default spawn config, or a later run with a custom app_server
+    // command would spuriously conflict (review fix D). `list` degrades to empty;
+    // session-specific ops behave as "unknown session".
+    const registry = options.registry ?? peekAppServerRegistry();
+    if (registry == null) {
+        if (input.op === "list") {
+            return jsonResult({ sessions: [] });
+        }
+        if (input.op === "health") {
+            return jsonResult(emptyHealthResponse());
+        }
+        const unknown = input.session_id ??
+            input.session_ids?.join(", ");
+        throw new InvalidParamsError(`Unknown session: ${unknown}`);
+    }
+    switch (input.op) {
+        case "poll": {
+            throwIfAborted(options.signal);
+            const target = resolveSessionSelector(input);
+            if (target.kind === "single") {
+                const snapshot = registry.poll(target.id);
+                return jsonResult(snapshotResponse(snapshot), {
+                    isError: snapshotIsError(snapshot),
+                });
+            }
+            return jsonResult({
+                snapshots: target.ids.map((id) => snapshotResponse(registry.poll(id))),
+            });
+        }
+        case "wait": {
+            const target = resolveSessionSelector(input);
+            if (target.kind === "single") {
+                const startedAt = Date.now();
+                const snapshot = await waitForManage(registry, target.id, input.timeout_seconds, options.signal);
+                const response = snapshotResponse(snapshot);
+                addWaitMetadata(response, snapshot, Date.now() - startedAt);
+                addPendingApprovalNextAction(response, snapshot);
+                return jsonResult(response, {
+                    isError: snapshotIsError(snapshot),
+                });
+            }
+            const batch = await waitForManageBatch(registry, target.ids, input.timeout_seconds, options.signal);
+            return jsonResult(batch.value, { isError: batch.isError });
+        }
+        case "steer": {
+            const snapshot = await registry.steer(input.session_id, [
+                { type: "text", text: input.prompt },
+            ]);
+            return jsonResult(snapshotResponse(snapshot), {
+                isError: snapshotIsError(snapshot),
+            });
+        }
+        case "respond": {
+            const snapshot = await registry.respondApproval(input.session_id, input.approval_id, input.decision);
+            return jsonResult(snapshotResponse(snapshot), {
+                isError: snapshotIsError(snapshot),
+            });
+        }
+        case "cancel": {
+            const snapshot = await registry.interrupt(input.session_id);
+            return jsonResult(snapshotResponse(snapshot), {
+                isError: snapshotIsError(snapshot),
+            });
+        }
+        case "get_log": {
+            const page = registry.getLog(input.session_id, input.cursor, input.limit);
+            return jsonResult(logResponse(page));
+        }
+        case "list": {
+            const offset = input.offset ?? 0;
+            const snapshots = registry
+                .list(input.status != null ? { status: input.status } : undefined)
+                .slice(offset, input.limit != null ? offset + input.limit : undefined)
+                .map((snapshot) => snapshotResponse(snapshot));
+            return jsonResult({ sessions: snapshots });
+        }
+        case "health":
+            return jsonResult(healthResponse(registry.health()));
+        case "cleanup": {
+            const cleanup = await registry.cleanup(input.session_id, {
+                force: input.force,
+            });
+            if (cleanup.cleanedUp) {
+                const sKey = sessionKey(input.session_id);
+                const contKey = sessionContinuationKeys.get(sKey);
+                asyncThreadIds.delete(sKey);
+                if (contKey != null) {
+                    asyncThreadIds.delete(contKey);
+                    sessionContinuationKeys.delete(sKey);
+                }
+            }
+            return jsonResult({
+                session_id: cleanup.sessionId,
+                cleaned_up: cleanup.cleanedUp,
+                skipped_active: cleanup.skippedActive,
+            });
+        }
+    }
+}
+async function handleListModels(input, options) {
+    let registry = options.registry ?? peekAppServerRegistry();
+    if (registry == null) {
+        const adapterRegistry = options.adapterRegistry ?? AdapterRegistry.load();
+        const adapter = resolveAppServerAdapter(adapterRegistry, undefined);
+        registry = getAppServerRegistry(spawnRequestFor(adapter));
+    }
+    // Map snake_case tool params → protocol/registry camelCase. Omit absent keys
+    // so the strict ModelListParamsSchema is not handed `undefined` values.
+    const params = {};
+    if (input.cursor !== undefined)
+        params.cursor = input.cursor;
+    if (input.include_hidden !== undefined)
+        params.includeHidden = input.include_hidden;
+    if (input.limit !== undefined)
+        params.limit = input.limit;
+    try {
+        const result = await registry.listModels(params);
+        return jsonResult(modelListResponse(result));
+    }
+    catch (err) {
+        return jsonResult(listModelsErrorResponse(err));
+    }
+}
+function parseWithSchema(schema, value, toolName) {
+    const result = schema.safeParse(value ?? {});
+    if (result.success)
+        return result.data;
+    const detail = result.error.issues
+        .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+        .join("; ");
+    throw new InvalidParamsError(`Invalid ${toolName} input: ${detail}`);
+}
+/**
+ * Enforce the "exactly one of session_id | session_ids" rule (and the batch cap)
+ * for poll/wait. Kept in handler code because a schema-level `.refine` would turn
+ * these discriminatedUnion arms into ZodEffects, which the union rejects.
+ */
+function resolveSessionSelector(input) {
+    const hasSingle = input.session_id != null;
+    const hasBatch = input.session_ids != null;
+    if (hasSingle === hasBatch) {
+        throw new InvalidParamsError("Provide exactly one of session_id or session_ids.");
+    }
+    if (hasBatch) {
+        const ids = input.session_ids;
+        if (ids.length === 0) {
+            throw new InvalidParamsError("session_ids must not be empty.");
+        }
+        if (ids.length > MAX_BATCH_SESSION_IDS) {
+            throw new InvalidParamsError(`session_ids exceeds the maximum of ${MAX_BATCH_SESSION_IDS}.`);
+        }
+        return { kind: "batch", ids };
+    }
+    return { kind: "single", id: input.session_id };
+}
+function parseFinalJson(finalText) {
+    if (finalText == null)
+        return null;
+    try {
+        return JSON.parse(finalText);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveAppServerAdapter(registry, cliName) {
+    if (cliName != null) {
+        const adapter = registry.resolveAdapter(cliName);
+        if (adapter.backend !== "app_server") {
+            throw new InvalidParamsError(`Adapter "${adapter.name}" does not use the Codex app-server backend.`);
+        }
+        return adapter;
+    }
+    const appServerAdapters = registry
+        .getAdapterNames()
+        .map((name) => registry.resolveAdapter(name))
+        .filter((adapter) => adapter.backend === "app_server");
+    if (appServerAdapters.length === 0) {
+        throw new InvalidParamsError("No Codex app-server adapters configured.");
+    }
+    if (appServerAdapters.length > 1) {
+        throw new InvalidParamsError(`cli_name is required when multiple app-server adapters are configured. Available: ${appServerAdapters
+            .map((adapter) => adapter.name)
+            .sort()
+            .join(", ")}`);
+    }
+    return appServerAdapters[0];
+}
+function buildAsyncPrompt(input, adapter) {
+    const { prompt } = assemblePrompt({
+        input: {
+            prompt: input.prompt,
+            cli_name: input.cli_name,
+            role: input.role,
+            absolute_file_paths: input.absolute_file_paths,
+            images: input.images,
+            context: input.context,
+            debug: input.debug,
+            debug_keep_artifacts: false,
+        },
+        adapter,
+        continuationCache: emptyContinuationCache,
+        runDirPath: process.cwd(),
+    });
+    return prompt;
+}
+function resolvePolicies(adapter, input) {
+    const appConfig = adapter.app_server;
+    const defaultSandbox = appConfig?.default_sandbox ?? "read-only";
+    const defaultApproval = appConfig?.default_approval ?? "never";
+    const sandbox = input.sandbox ?? defaultSandbox;
+    const approval = input.approval ?? defaultApproval;
+    enforceSandboxClamp(defaultSandbox, sandbox, appConfig?.allow_danger_full_access === true);
+    enforceApprovalClamp(defaultApproval, approval);
+    return {
+        sandbox,
+        approval,
+        model: input.model ?? appConfig?.default_model,
+    };
+}
+function enforceSandboxClamp(defaultSandbox, requested, allowDangerFullAccess) {
+    const rank = {
+        "read-only": 0,
+        "workspace-write": 1,
+        "danger-full-access": 2,
+    };
+    if (requested === "danger-full-access" && !allowDangerFullAccess) {
+        throw new InvalidParamsError('Per-call sandbox "danger-full-access" requires app_server.allow_danger_full_access: true.');
+    }
+    if (rank[requested] > rank[defaultSandbox]) {
+        throw new InvalidParamsError(`Per-call sandbox "${requested}" is more privileged than adapter default "${defaultSandbox}".`);
+    }
+}
+function enforceApprovalClamp(defaultApproval, requested) {
+    const rank = {
+        untrusted: 0,
+        "on-failure": 1,
+        "on-request": 2,
+        granular: 3,
+        never: 4,
+    };
+    if (rank[requested] > rank[defaultApproval]) {
+        throw new InvalidParamsError(`Per-call approval "${requested}" is more privileged than adapter default "${defaultApproval}".`);
+    }
+}
+/**
+ * Resolve the prior thread to resume, honoring raw thread ids before the alias
+ * precedence resume_continuation_id > session_id > continuation_id.
+ *
+ * resume_continuation_id and session_id are EXPLICIT resume requests: an unknown
+ * alias is an error. continuation_id is a WRITE/READ-symmetric alias (F2): the
+ * SAME continuation_id passed back resumes the thread it tagged, but its FIRST
+ * use (no stored alias yet) is not an error — it simply starts a fresh thread
+ * that {@link rememberThread} then records under that continuation_id.
+ */
+function resolveResumeThreadId(input, registry) {
+    if (input.resume_thread_id != null) {
+        const threadId = input.resume_thread_id;
+        assertThreadNotRunning(registry, threadId);
+        return threadId;
+    }
+    let key;
+    let explicit = false;
+    if (input.resume_continuation_id != null) {
+        key = continuationKey(input.resume_continuation_id);
+        explicit = true;
+    }
+    else if (input.session_id != null) {
+        key = sessionKey(input.session_id);
+        explicit = true;
+    }
+    else if (input.continuation_id != null) {
+        key = continuationKey(input.continuation_id);
+        explicit = false;
+    }
+    if (key == null)
+        return undefined;
+    const threadId = asyncThreadIds.get(key);
+    if (threadId == null) {
+        if (!explicit)
+            return undefined; // first use of this continuation_id → fresh thread
+        throw new InvalidParamsError(input.resume_continuation_id != null
+            ? `Unknown async continuation_id: ${input.resume_continuation_id}`
+            : `Unknown async session_id: ${input.session_id}`);
+    }
+    assertThreadNotRunning(registry, threadId);
+    return threadId;
+}
+function assertThreadNotRunning(registry, threadId) {
+    // Cheap, advisory fast-path for a friendlier early error: refuse to resume a
+    // thread a still-running session visibly holds. This is NOT the authoritative
+    // guard — startSession reserves the resumed thread SYNCHRONOUSLY before any
+    // await (review fix A), closing the deferred-insertion race two concurrent
+    // resumes could otherwise slip through here.
+    if (registry.list({ status: "running" }).some((s) => s.threadId === threadId)) {
+        throw new InvalidParamsError(`Cannot resume thread ${threadId}: a session is still running on it. ` +
+            "Wait for that turn to complete before resuming.");
+    }
+}
+/**
+ * The user-facing identifier that actually drove the resume (or null when the run
+ * started a fresh thread), echoed back as `resumed_from`. Mirrors the precedence
+ * in {@link resolveResumeThreadId}.
+ */
+function effectiveResumeKey(input, resumeThreadId) {
+    if (resumeThreadId == null)
+        return null;
+    if (input.resume_thread_id != null)
+        return input.resume_thread_id;
+    if (input.resume_continuation_id != null)
+        return input.resume_continuation_id;
+    if (input.session_id != null)
+        return input.session_id;
+    if (input.continuation_id != null)
+        return input.continuation_id;
+    return null;
+}
+function rememberThread(input, snapshot) {
+    asyncThreadIds.set(sessionKey(snapshot.sessionId), snapshot.threadId);
+    if (input.continuation_id != null) {
+        const contKey = continuationKey(input.continuation_id);
+        asyncThreadIds.set(contKey, snapshot.threadId);
+        // Track the paired alias so cleanup can prune it (otherwise the thread stays
+        // resumable via continuation_id after the session is cleaned up).
+        sessionContinuationKeys.set(sessionKey(snapshot.sessionId), contKey);
+    }
+}
+async function waitForRun(registry, sessionId, input, signal) {
+    const opts = buildWaitOptions(input.timeout_seconds, signal);
+    if (signal == null) {
+        return registry.waitForTurn(sessionId, opts);
+    }
+    // Run-path cancellation INTERRUPTS the turn (and clears the underlying wait via
+    // the threaded signal), then surfaces CancellationError.
+    const outcome = await raceAbort(registry.waitForTurn(sessionId, opts), signal);
+    if (outcome.aborted) {
+        await registry.interrupt(sessionId).catch(() => undefined);
+        throw new CancellationError();
+    }
+    return outcome.value;
+}
+async function waitForManage(registry, sessionId, timeoutSeconds, signal) {
+    const opts = buildWaitOptions(timeoutSeconds, signal);
+    if (signal == null) {
+        return registry.waitForTurn(sessionId, opts);
+    }
+    // Manage-path cancellation only STOPS WAITING (the threaded signal clears the
+    // registry's race timer/listeners); it never interrupts the turn.
+    const outcome = await raceAbort(registry.waitForTurn(sessionId, opts), signal);
+    if (outcome.aborted) {
+        throw new CancellationError();
+    }
+    return outcome.value;
+}
+/**
+ * Batch wait. Races all ids and returns on the FIRST actionable session rather
+ * than blocking on a barrier. A session is "actionable" when its snapshot is
+ * TERMINAL (completed/failed/timeout/interrupted) or PAUSED (running with a
+ * pending approval). On each wake we re-poll ALL sessions and pick the
+ * lowest-input-index actionable one as winner, preserving determinism when
+ * several settle together. A bare wait-timeout (still running, no approval) is
+ * NOT actionable, so we keep waiting on the rest.
+ *
+ * If the shared timeout elapses with no actionable session, winner is null and
+ * `timed_out` is true. `pending_session_ids` lists ONLY sessions still running
+ * with no pending approval — terminal and paused ids are excluded. `elapsed_ms`
+ * is wall-clock. The abort signal throws {@link CancellationError}.
+ */
+async function waitForManageBatch(registry, sessionIds, timeoutSeconds, signal) {
+    // Validate all ids up-front so an unknown session surfaces a deterministic
+    // InvalidParamsError instead of racing a rejection against valid sessions.
+    for (const id of sessionIds)
+        registry.poll(id);
+    const startedAtMs = Date.now();
+    const isActionable = (id) => {
+        const snapshot = registry.poll(id);
+        return (snapshot.status !== "running" ||
+            (snapshot.status === "running" && snapshot.pendingApprovals.length > 0));
+    };
+    // The first actionable session in INPUT order, or undefined. find() walks in
+    // order, so this is always the lowest input index.
+    const lowestActionable = () => sessionIds.find((id) => isActionable(id));
+    const buildResult = (winnerId) => {
+        const pendingSessionIds = sessionIds.filter((id) => !isActionable(id));
+        const elapsedMs = Date.now() - startedAtMs;
+        if (winnerId == null) {
+            return {
+                value: {
+                    winner_session_id: null,
+                    timed_out: true,
+                    pending_session_ids: pendingSessionIds,
+                    snapshot: null,
+                    elapsed_ms: elapsedMs,
+                },
+                isError: false,
+            };
+        }
+        const winnerSnapshot = registry.poll(winnerId);
+        const response = snapshotResponse(winnerSnapshot);
+        addPendingApprovalNextAction(response, winnerSnapshot);
+        return {
+            value: {
+                winner_session_id: winnerId,
+                timed_out: false,
+                pending_session_ids: pendingSessionIds,
+                snapshot: response,
+                elapsed_ms: elapsedMs,
+            },
+            isError: snapshotIsError(winnerSnapshot),
+        };
+    };
+    // Fast path: if any session is already actionable, return immediately.
+    const alreadyActionable = lowestActionable();
+    if (alreadyActionable != null)
+        return buildResult(alreadyActionable);
+    // Cleanup controller: its signal is threaded into EVERY per-session
+    // waitForTurn so that on any early return (a winner is crowned) or throw
+    // (caller abort) we can abort the still-outstanding losing waits. Each such
+    // wait then hits its abort path inside raceTurnWait → its race timer and
+    // terminal/attention listeners are torn down and it settles, so the residual
+    // .then(done) continuations become guaranteed no-ops. This is distinct from
+    // the caller's signal: only the caller's signal produces CancellationError;
+    // the cleanup abort never does (it is not raced via raceAbort below).
+    const cleanupController = new AbortController();
+    // If the caller cancels, also tear down the per-session waits. (The reverse
+    // is unnecessary: aborting cleanup must not look like a caller cancellation.)
+    let onCallerAbort;
+    if (signal != null) {
+        if (signal.aborted) {
+            cleanupController.abort();
+        }
+        else {
+            onCallerAbort = () => cleanupController.abort();
+            signal.addEventListener("abort", onCallerAbort, { once: true });
+        }
+    }
+    try {
+        const opts = buildWaitOptions(timeoutSeconds, cleanupController.signal);
+        // Race the still-pending sessions' waits. Each wake re-polls ALL sessions; a
+        // wait that merely timed out (still running, no approval) is non-actionable,
+        // so we drop it and keep racing the rest. Map rejections to a resolved void so
+        // a single bad wait cannot reject the batch. Tag each promise with its id so a
+        // settled one is not re-awaited.
+        const outstanding = new Map();
+        for (const id of sessionIds) {
+            outstanding.set(id, registry.waitForTurn(id, opts).then(() => id, () => id));
+        }
+        while (outstanding.size > 0) {
+            const settledId = signal == null
+                ? await Promise.race(outstanding.values())
+                : await (async () => {
+                    const outcome = await raceAbort(Promise.race(outstanding.values()), signal);
+                    if (outcome.aborted)
+                        throw new CancellationError();
+                    return outcome.value;
+                })();
+            outstanding.delete(settledId);
+            const winner = lowestActionable();
+            if (winner != null)
+                return buildResult(winner);
+        }
+        // All waits settled with no actionable session: shared timeout elapsed.
+        return buildResult(undefined);
+    }
+    finally {
+        // Covers normal return (a winner), all-timed-out return, and the
+        // caller-abort throw. Aborting forces every still-outstanding losing
+        // waitForTurn to settle and release its timer/listener.
+        cleanupController.abort();
+        if (onCallerAbort != null) {
+            signal?.removeEventListener("abort", onCallerAbort);
+        }
+    }
+}
+function buildWaitOptions(timeoutSeconds, signal) {
+    const timeoutMs = timeoutSeconds != null ? Math.ceil(timeoutSeconds * 1000) : undefined;
+    if (timeoutMs == null && signal == null)
+        return undefined;
+    return {
+        ...(timeoutMs != null ? { timeoutMs } : {}),
+        ...(signal != null ? { signal } : {}),
+    };
+}
+function raceAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.resolve({ aborted: true });
+    let onAbort;
+    const abortPromise = new Promise((resolve) => {
+        onAbort = () => resolve({ aborted: true });
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    return Promise.race([
+        promise.then((value) => ({ aborted: false, value })),
+        abortPromise,
+    ]).finally(() => {
+        if (onAbort != null) {
+            signal.removeEventListener("abort", onAbort);
+        }
+    });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new CancellationError();
+    }
+}
+function snapshotResponse(snapshot, maxResponseChars) {
+    const finalText = snapshot.finalText != null
+        ? limitOutput(snapshot.finalText, maxResponseChars ?? DEFAULT_MAX_RESPONSE_CHARS)
+        : null;
+    return {
+        session_id: snapshot.sessionId,
+        thread_id: snapshot.threadId,
+        active_turn_id: snapshot.activeTurnId,
+        status: snapshot.status,
+        cwd: snapshot.cwd,
+        model: snapshot.model,
+        sandbox: snapshot.sandbox,
+        approval: snapshot.approval,
+        origin: snapshot.origin,
+        depth: snapshot.depth,
+        pending_approvals: snapshot.pendingApprovals.map((approval) => pendingApprovalResponse(approval, maxResponseChars)),
+        final_text: finalText,
+        final_text_truncated: snapshot.finalTextTruncated,
+        latest_assistant_preview: snapshot.latestAssistantPreview,
+        latest_assistant_preview_truncated: snapshot.latestAssistantPreviewTruncated,
+        latest_diff: snapshot.latestDiff,
+        latest_plan: snapshot.latestPlan != null && snapshot.latestPlan.length > 0
+            ? snapshot.latestPlan.map((s) => ({ step: s.step, status: s.status }))
+            : null,
+        plan_explanation: snapshot.planExplanation,
+        token_usage: tokenUsageResponse(snapshot.tokenUsage),
+        failure_reason: snapshot.failureReason,
+        event_count: snapshot.eventCount,
+        created_at_ms: snapshot.createdAtMs,
+        updated_at_ms: snapshot.updatedAtMs,
+        last_activity_at_ms: snapshot.lastActivityAtMs,
+    };
+}
+function pendingApprovalResponse(approval, maxResponseChars) {
+    const cap = Math.min(maxResponseChars ?? DEFAULT_MAX_RESPONSE_CHARS, PENDING_APPROVAL_FIELD_CHARS);
+    const response = {
+        id: approval.id,
+        type: approval.type,
+        allowed_decisions: allowedDecisionsForType(approval.type),
+        reason: boundedApprovalString(approval.reason, cap),
+        requested_at_ms: approval.requestedAtMs,
+    };
+    if (approval.command !== undefined) {
+        response["command"] = boundedApprovalString(approval.command, cap);
+    }
+    if (approval.cwd !== undefined) {
+        response["cwd"] = boundedApprovalString(approval.cwd, cap);
+    }
+    if (approval.grantRoot !== undefined) {
+        response["grant_root"] = boundedApprovalString(approval.grantRoot, cap);
+    }
+    if (approval.networkApprovalContext !== undefined) {
+        response["network_approval_context"] = boundedUnknown(approval.networkApprovalContext, cap);
+    }
+    return response;
+}
+function allowedDecisionsForType(type) {
+    switch (type) {
+        case "commandExecution":
+        case "fileChange":
+            return [...SUPPORTED_COMMAND_EXECUTION_APPROVAL_DECISIONS];
+        case "permissions":
+            return [];
+    }
+}
+function boundedApprovalString(value, maxChars) {
+    if (value == null)
+        return null;
+    return limitOutput(redactSensitiveText(value), maxChars);
+}
+function boundedUnknown(value, maxChars) {
+    if (value == null)
+        return null;
+    if (typeof value === "string")
+        return boundedApprovalString(value, maxChars);
+    if (typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "bigint")
+        return value.toString();
+    try {
+        const json = JSON.stringify(value);
+        const redactedJson = redactSensitiveText(json);
+        if (redactedJson.length <= maxChars)
+            return JSON.parse(redactedJson);
+        return {
+            summary: limitOutput(redactedJson, maxChars),
+            truncated: true,
+        };
+    }
+    catch {
+        return {
+            summary: limitOutput(redactSensitiveText(String(value)), maxChars),
+            truncated: true,
+        };
+    }
+}
+function redactSensitiveText(value) {
+    return value
+        .replace(/("?[A-Z0-9_]*(?:KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL)[A-Z0-9_]*"?\s*:\s*)"[^"]*"/gi, "$1\"[REDACTED]\"")
+        .replace(/\b([A-Z0-9_]*(?:KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL)[A-Z0-9_]*)=([^\s]+)/gi, "$1=[REDACTED]")
+        .replace(/\b(?:sk|pk|ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_=-]{8,}\b/g, "[REDACTED]");
+}
+function healthResponse(health) {
+    return {
+        active_leases: health.activeLeases,
+        retained_session_count: health.retainedSessionCount,
+        app_server_protocol: {
+            accepted_version: health.appServerProtocol.acceptedVersion,
+            min_version: health.appServerProtocol.minVersion,
+            max_version: health.appServerProtocol.maxVersion,
+            strict_version: health.appServerProtocol.strictVersion,
+        },
+        child_respawn_count: health.childRespawnCount,
+        recent_failures: {
+            count: health.recentFailures.count,
+            samples: health.recentFailures.samples,
+        },
+    };
+}
+function emptyHealthResponse() {
+    const minVersion = process.env["CLINKX_APP_SERVER_MIN_VERSION"] ??
+        CODEX_APP_SERVER_PROTOCOL_VERSION;
+    const maxVersion = process.env["CLINKX_APP_SERVER_MAX_VERSION"] ??
+        CODEX_APP_SERVER_PROTOCOL_VERSION;
+    return {
+        active_leases: 0,
+        retained_session_count: 0,
+        app_server_protocol: {
+            accepted_version: null,
+            min_version: minVersion,
+            max_version: maxVersion,
+            strict_version: ["1", "true", "yes", "on"].includes(String(process.env["CLINKX_APP_SERVER_STRICT_VERSION"] ?? "").toLowerCase()),
+        },
+        child_respawn_count: 0,
+        recent_failures: {
+            count: 0,
+            samples: [],
+        },
+    };
+}
+/** Coerce an arbitrary (untrusted) value to a bounded string, or null. */
+function boundedUnknownString(value, maxChars) {
+    if (value == null)
+        return null;
+    const text = typeof value === "string" ? value : String(value);
+    return limitOutput(text, maxChars);
+}
+function modelListResponse(result) {
+    const models = result.data.slice(0, MAX_LIST_MODELS).map((m) => ({
+        id: limitOutput(m.id, MODEL_IDENTIFIER_CHARS),
+        model: limitOutput(m.model, MODEL_IDENTIFIER_CHARS),
+        display_name: m.displayName != null
+            ? limitOutput(m.displayName, MODEL_IDENTIFIER_CHARS)
+            : null,
+        description: m.description != null
+            ? limitOutput(m.description, MODEL_DESCRIPTION_CHARS)
+            : null,
+        is_default: m.isDefault ?? null,
+        hidden: m.hidden ?? null,
+        default_reasoning_effort: boundedUnknownString(m.defaultReasoningEffort, MODEL_EFFORT_CHARS),
+        supported_reasoning_efforts: m.supportedReasoningEfforts != null
+            ? m.supportedReasoningEfforts
+                .slice(0, MAX_SUPPORTED_REASONING_EFFORTS)
+                .map((e) => boundedUnknownString(e, MODEL_EFFORT_CHARS))
+            : null,
+    }));
+    return {
+        supported: true,
+        models,
+        next_cursor: result.nextCursor != null
+            ? limitOutput(result.nextCursor, MAX_CURSOR_CHARS)
+            : null,
+    };
+}
+function listModelsErrorResponse(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        supported: false,
+        reason: limitOutput(`Codex model/list RPC failed: ${message}`, 500),
+    };
+}
+function tokenUsageResponse(usage) {
+    return {
+        baseline_total: usage.baselineTotal,
+        last_usage: usage.lastUsage,
+        delta_usage: usage.deltaUsage,
+        cumulative_total: usage.cumulativeTotal,
+        incomplete: usage.incomplete,
+    };
+}
+function addPendingApprovalNextAction(response, snapshot) {
+    if (snapshot.status !== "running" || snapshot.pendingApprovals.length === 0) {
+        return;
+    }
+    response["next_action"] =
+        'Use clink_agent_manage op:"respond" with this session_id, an approval_id from pending_approvals, and a decision.';
+}
+function logResponse(page) {
+    return {
+        events: page.events,
+        next_cursor: page.nextCursor,
+        truncated: page.truncated,
+        floor: page.floor,
+        capacity: page.capacity,
+        persisted: false,
+    };
+}
+function addWaitMetadata(response, snapshot, elapsedMs) {
+    const running = snapshot.status === "running";
+    const paused = running && snapshot.pendingApprovals.length > 0;
+    response["wake_reason"] = paused
+        ? "paused_on_approval"
+        : running
+            ? "timeout"
+            : "terminal";
+    response["wait_result"] = running && !paused
+        ? "timed_out"
+        : paused
+            ? "actionable"
+            : "settled";
+    response["elapsed_ms"] = elapsedMs;
+}
+function snapshotIsError(snapshot) {
+    return (snapshot.status === "failed" ||
+        snapshot.status === "timeout" ||
+        snapshot.status === "interrupted");
+}
+function jsonResult(value, opts = {}) {
+    const result = {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    };
+    if (opts.isError === true)
+        result.isError = true;
+    return result;
+}
+function sessionKey(sessionId) {
+    return `session:${sessionId}`;
+}
+function continuationKey(continuationId) {
+    return `continuation:${continuationId}`;
+}
+export function resetAgentToolStateForTest() {
+    asyncThreadIds.clear();
+    sessionContinuationKeys.clear();
+}
+//# sourceMappingURL=agent-tools.js.map