clinkx 0.2.3 → 1.0.0

package/dist/elaris/tools.js

@@ -0,0 +1,1065 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { CancellationError, ExecutionError, InvalidParamsError } from "../errors.js";
+import { ElarisClient, isElarisHttpError, waitForNextElarisPoll } from "./client.js";
+import { loadElarisConfig, resolveElarisApiKey, validateElarisBaseUrl } from "./config.js";
+import { buildElarisFailureBody, classifyElarisHttpError, elarisResult, errorEnvelopeDetail, errorEnvelopeRequestId, errorEnvelopeRunId, inferFollowUpConflictReason, } from "./errors.js";
+import { generateElarisRunId } from "./run-id.js";
+import { mapCreateResponseToSnapshot, mapStatusResponseToSnapshot, mergeCreateProvenance, isTerminalElarisStatus, normalizeElarisStatus, rawStatusIsError, snapshotIsError, withKnownKeepAlive, } from "./status.js";
+import { ElarisRunInputSchema, parseElarisManageInput, parseElarisRunInput, } from "./tool-schemas.js";
+export const ELARIS_TOOL_NAMES = new Set([
+    "clink_elaris_run",
+    "clink_elaris_manage",
+]);
+export function getElarisToolDefinitions() {
+    const runSchema = zodToJsonSchema(ElarisRunInputSchema, {
+        target: "jsonSchema7",
+        $refStrategy: "none",
+    });
+    const manageSchema = {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        type: "object",
+        additionalProperties: false,
+        required: ["op"],
+        properties: {
+            op: {
+                type: "string",
+                enum: [
+                    "poll",
+                    "wait",
+                    "result",
+                    "content",
+                    "logs",
+                    "artifacts",
+                    "artifact_raw",
+                    "message",
+                    "cancel",
+                    "cleanup",
+                    "health",
+                ],
+                description: "Operation for an Elaris remote agent-session. Deferred remote analogs return unsupported_v1 explicitly.",
+            },
+            session_id: { type: "string", minLength: 1 },
+            status_url: { type: "string", minLength: 1 },
+            cursor: { type: "string" },
+            limit: { type: "integer", minimum: 1, maximum: 200 },
+            fetch_all: { type: "boolean" },
+            file_path: { type: "string", minLength: 1 },
+            range: {
+                type: "object",
+                additionalProperties: false,
+                required: ["start"],
+                properties: {
+                    start: { type: "integer", minimum: 0 },
+                    end: { type: "integer", minimum: 0 },
+                },
+            },
+            prompt: { type: "string", minLength: 1 },
+            model_id: { type: "string", minLength: 1 },
+            permission_mode: {
+                type: "string",
+                enum: ["plan", "acceptEdits", "auto", "fullAccess"],
+            },
+            effort_level: {
+                type: "string",
+                enum: ["low", "medium", "high", "xhigh", "max"],
+            },
+            metadata: { type: "object", additionalProperties: true },
+            idempotency_key: {
+                type: "string",
+                minLength: 1,
+                maxLength: 128,
+                pattern: "^[A-Za-z0-9_.:-]+$",
+            },
+            wait: { type: "boolean" },
+            timeout_seconds: { type: "number", exclusiveMinimum: 0 },
+            poll_interval_ms: { type: "integer", minimum: 1 },
+            max_response_chars: { type: "integer", minimum: 1 },
+        },
+    };
+    return [
+        {
+            name: "clink_elaris_run",
+            description: "Start an Elaris remote agent-session over HTTP. This scaffold freezes the advertised v1 input contract; runtime execution lands in Phase 3.",
+            inputSchema: runSchema,
+            annotations: {
+                readOnlyHint: false,
+            },
+        },
+        {
+            name: "clink_elaris_manage",
+            description: "Inspect or drive an Elaris remote agent-session: poll, wait, result/content, logs, artifacts, follow-up message, cancel, cleanup, and health.",
+            inputSchema: manageSchema,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: true,
+            },
+        },
+    ];
+}
+export async function handleElarisToolCall(name, args, signal, options = {}) {
+    if (name === "clink_elaris_run") {
+        return handleElarisRun(args, signal, options);
+    }
+    if (name === "clink_elaris_manage") {
+        return handleElarisManage(args, signal, options);
+    }
+    return elarisResult({
+        ok: false,
+        error_kind: "unsupported_v1",
+        operation: name,
+        detail: "Unknown Elaris tool.",
+    }, { isError: true });
+}
+async function handleElarisRun(args, signal, options) {
+    throwIfCancelled(signal);
+    const input = parseElarisRunInput(args);
+    const config = options.config ?? loadElarisConfig();
+    const modelId = input.model_id ?? config.DEFAULT_MODEL_ID ?? process.env.CLINKX_ELARIS_DEFAULT_MODEL_ID;
+    if (modelId === undefined || modelId.trim().length === 0) {
+        throw new InvalidParamsError("model_id is required. Provide model_id or set CLINKX_ELARIS_DEFAULT_MODEL_ID.");
+    }
+    const runId = input.run_id ?? (options.generateRunId ?? generateElarisRunId)();
+    const client = options.client ?? createDefaultClient(config);
+    const nowMs = options.nowMs ?? Date.now;
+    const waitForNextPoll = options.waitForNextPoll ?? waitForNextElarisPoll;
+    const maxResponseChars = input.max_response_chars ?? 20000;
+    const timeoutSeconds = input.timeout_seconds
+        ?? (input.wait ? config.WAIT_TIMEOUT_SECONDS : config.REQUEST_TIMEOUT_SECONDS)
+        ?? 60;
+    const deadlineMs = nowMs() + Math.max(1, timeoutSeconds) * 1000;
+    const request = buildCreateRequest(input, modelId.trim(), runId);
+    try {
+        return await executeElarisRun({
+            client,
+            input,
+            request,
+            runId,
+            signal,
+            deadlineMs,
+            waitForNextPoll,
+            nowMs,
+            maxResponseChars,
+        });
+    }
+    catch (err) {
+        // MCP cancellation must yield no response: an external-signal abort landing in
+        // the full request RTT of a wait/duplicate status fetch can surface as a raw
+        // AbortError (not CancellationError). Surface it as CancellationError before any
+        // structured-failure handling so it can never be masked as an isError result.
+        rethrowIfCancelled(err, signal);
+        if (err instanceof ElarisStructuredFailure) {
+            return elarisResult(err.body, { isError: true, maxChars: maxResponseChars });
+        }
+        throw err;
+    }
+}
+async function handleElarisManage(args, signal, options) {
+    throwIfCancelled(signal);
+    const input = parseElarisManageInput(args);
+    const maxResponseChars = input.max_response_chars ?? 20000;
+    if (isUnsupportedManageOp(input.op)) {
+        return unsupportedManageResult(input.op, maxResponseChars);
+    }
+    if (input.op === "health") {
+        return handleElarisHealth(signal, options, maxResponseChars);
+    }
+    const config = options.config ?? loadElarisConfig();
+    const client = options.client ?? createDefaultClient(config);
+    const nowMs = options.nowMs ?? Date.now;
+    const waitForNextPoll = options.waitForNextPoll ?? waitForNextElarisPoll;
+    const timeoutSeconds = input.timeout_seconds
+        ?? (input.op === "wait" || input.wait ? config.WAIT_TIMEOUT_SECONDS : config.REQUEST_TIMEOUT_SECONDS)
+        ?? 60;
+    const deadlineMs = nowMs() + Math.max(1, timeoutSeconds) * 1000;
+    try {
+        switch (input.op) {
+            case "poll":
+                return await handleManagePoll({ client, input, signal, maxResponseChars, operation: "poll" });
+            case "wait":
+                return await handleManageWait({ client, input, signal, maxResponseChars, deadlineMs, waitForNextPoll, nowMs });
+            case "result":
+                return await handleManageResult({ client, input, signal, maxResponseChars });
+            case "content":
+                return await handleReadOperation("content", () => client.getResultContent(input.session_id, { signal }), maxResponseChars);
+            case "logs":
+                return await handleReadOperation("logs", () => (input.fetch_all
+                    ? client.getAllLogs(input.session_id, { signal, limit: input.limit })
+                    : client.getLogsPage(input.session_id, { signal, cursor: input.cursor, limit: input.limit })), maxResponseChars);
+            case "artifacts":
+                return await handleReadOperation("artifacts", () => (input.fetch_all
+                    ? client.getAllArtifacts(input.session_id, { signal, limit: input.limit })
+                    : client.getArtifactsPage(input.session_id, { signal, cursor: input.cursor, limit: input.limit })), maxResponseChars);
+            case "artifact_raw":
+                return await handleReadOperation("artifact_raw", () => client.getArtifactRaw(input.session_id, input.file_path, { signal, range: input.range }), maxResponseChars);
+            case "message":
+                return await handleManageMessage({ client, input, signal, maxResponseChars, deadlineMs, waitForNextPoll, nowMs });
+            case "cancel":
+                return await handleStatusMutation("cancel", () => client.cancel(input.session_id, { signal }), input.session_id, maxResponseChars);
+            case "cleanup":
+                return await handleStatusMutation("cleanup", () => client.cleanup(input.session_id, { signal }), input.session_id, maxResponseChars);
+        }
+    }
+    catch (err) {
+        // MCP cancellation must yield no response: surface CancellationError before
+        // any transport classification so an external abort can never be masked as a
+        // backend_unavailable/isError result.
+        rethrowIfCancelled(err, signal);
+        if (err instanceof ElarisStructuredFailure) {
+            return elarisResult(err.body, {
+                isError: manageFailureIsError(input.op, err.body.error_kind),
+                maxChars: maxResponseChars,
+            });
+        }
+        const remote = remoteFailureFromUnknown(err);
+        if (remote !== undefined) {
+            const errorKind = classifyManageRemote(input.op, remote);
+            return elarisResult(buildFailureForRemote(errorKind, remote, input.op, undefined), {
+                isError: manageFailureIsError(input.op, errorKind),
+                maxChars: maxResponseChars,
+            });
+        }
+        throw err;
+    }
+}
+async function executeElarisRun(args) {
+    const { client, input, request, runId, signal, deadlineMs, waitForNextPoll, nowMs, maxResponseChars } = args;
+    const createResult = await createWithBoundedRetry({
+        client,
+        request,
+        input,
+        signal,
+        deadlineMs,
+        waitForNextPoll,
+        nowMs,
+    });
+    if (createResult.kind === "tool_result") {
+        return elarisResult(createResult.body, {
+            isError: createResult.isError,
+            maxChars: maxResponseChars,
+        });
+    }
+    if (createResult.kind === "duplicate") {
+        return recoverDuplicate({
+            client,
+            input,
+            signal,
+            runId,
+            locator: createResult.locator,
+            maxResponseChars,
+            deadlineMs,
+            waitForNextPoll,
+            nowMs,
+        });
+    }
+    const createSnapshot = withKnownKeepAlive(mapCreateResponseToSnapshot(createResult.response), input.keep_alive);
+    if (!input.wait) {
+        return elarisResult({
+            ok: true,
+            operation: "clink_elaris_run",
+            ...createSnapshot,
+            wait_result: "not_requested",
+            next_action: nextAction(createSnapshot),
+        }, {
+            isError: snapshotIsError(createSnapshot),
+            maxChars: maxResponseChars,
+        });
+    }
+    const waited = await waitForTerminal({
+        client,
+        createSnapshot,
+        signal,
+        deadlineMs,
+        pollIntervalMs: input.poll_interval_ms,
+        waitForNextPoll,
+        nowMs,
+        runId,
+    });
+    return elarisResult({
+        ok: true,
+        operation: "clink_elaris_run",
+        ...waited.snapshot,
+        wait_result: waited.waitResult,
+        next_action: waited.waitResult === "timed_out" ? nextAction(waited.snapshot) : undefined,
+    }, {
+        isError: snapshotIsError(waited.snapshot),
+        maxChars: maxResponseChars,
+    });
+}
+async function handleManagePoll(input) {
+    const status = await fetchManageStatus(input.client, input.input, input.signal, input.operation);
+    const snapshot = echoStatusLocator(mapStatusResponseToSnapshot(status), input.input);
+    return elarisResult({
+        ok: true,
+        operation: input.operation,
+        ...snapshot,
+        next_action: nextAction(snapshot),
+    }, {
+        isError: snapshotIsError(snapshot),
+        maxChars: input.maxResponseChars,
+    });
+}
+async function handleManageWait(input) {
+    const first = await fetchManageStatus(input.client, input.input, input.signal, "wait");
+    const firstSnapshot = echoStatusLocator(mapStatusResponseToSnapshot(first), input.input);
+    const waited = await waitForTerminal({
+        client: input.client,
+        createSnapshot: firstSnapshot,
+        signal: input.signal,
+        deadlineMs: input.deadlineMs,
+        pollIntervalMs: input.input.poll_interval_ms,
+        waitForNextPoll: input.waitForNextPoll,
+        nowMs: input.nowMs,
+        runId: firstSnapshot.run_id,
+    });
+    const snapshot = waited.snapshot;
+    return elarisResult({
+        ok: true,
+        operation: "wait",
+        ...snapshot,
+        wait_result: waited.waitResult,
+        next_action: waited.waitResult === "timed_out" ? nextAction(snapshot) : undefined,
+    }, {
+        isError: snapshotIsError(snapshot),
+        maxChars: input.maxResponseChars,
+    });
+}
+async function handleManageResult(input) {
+    try {
+        const result = await input.client.getResult(input.input.session_id, { signal: input.signal });
+        const redactionCount = readRedactionCount(objectOrValue(result));
+        return elarisResult({
+            ok: true,
+            operation: "result",
+            ready: true,
+            ...result,
+            content_url: result.content_url,
+            redaction_count: redactionCount,
+            redacted: redactionCount > 0,
+        }, { maxChars: input.maxResponseChars });
+    }
+    catch (err) {
+        const remote = remoteFailureFromUnknown(err);
+        if (remote !== undefined) {
+            const errorKind = classifyElarisHttpError(remote.status, remote.rawEnvelope);
+            if (errorKind === "not_terminal") {
+                return elarisResult({
+                    ok: true,
+                    operation: "result",
+                    ready: false,
+                    next_action: pollAction(input.input.session_id),
+                }, { maxChars: input.maxResponseChars });
+            }
+            throw new ElarisStructuredFailure(buildFailureForRemote(errorKind, remote, "result", undefined));
+        }
+        throw err;
+    }
+}
+async function handleReadOperation(operation, read, maxResponseChars) {
+    const body = objectOrValue(await read());
+    const redactionCount = readRedactionCount(body);
+    return elarisResult({
+        ok: true,
+        operation,
+        ...body,
+        redaction_count: redactionCount,
+        redacted: redactionCount > 0,
+    }, { maxChars: maxResponseChars });
+}
+// The client attaches a first-class `redaction_count` on read responses only
+// when at least one redaction fired (omitted at zero). Normalize it to a
+// non-negative number so the read-path envelope always carries a definite
+// redaction_count plus the derived `redacted` boolean.
+function readRedactionCount(body) {
+    const value = body["redaction_count"];
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+async function handleManageMessage(input) {
+    const idempotencyKey = input.input.idempotency_key ?? generateMessageIdempotencyKey();
+    const request = buildMessageRequest(input.input, idempotencyKey);
+    const message = await postMessageWithBoundedRetry({
+        client: input.client,
+        sessionId: input.input.session_id,
+        request,
+        signal: input.signal,
+        deadlineMs: input.deadlineMs,
+        waitForNextPoll: input.waitForNextPoll,
+        pollIntervalMs: input.input.poll_interval_ms,
+    });
+    const observed = messageFields(message);
+    if (input.input.wait) {
+        // Short-circuit: if the initial message response is already terminal (e.g. an
+        // idempotent replay of a completed turn), settle immediately instead of
+        // sleeping/polling — which would otherwise report a spurious timed_out.
+        if (isTerminalElarisStatus(observed.status)) {
+            return elarisResult({
+                ok: true,
+                operation: "message",
+                turn_id: observed.turn_id,
+                idempotency_key: idempotencyKey,
+                idempotent_replay: observed.idempotent_replay,
+                ...messageSnapshot(message),
+                wait_result: "settled",
+            }, {
+                isError: rawStatusIsError(observed.status),
+                maxChars: input.maxResponseChars,
+            });
+        }
+        const waited = await waitForMessageTerminal({
+            client: input.client,
+            message,
+            signal: input.signal,
+            deadlineMs: input.deadlineMs,
+            pollIntervalMs: input.input.poll_interval_ms,
+            waitForNextPoll: input.waitForNextPoll,
+            nowMs: input.nowMs,
+        });
+        const waitedBody = "snapshot" in waited ? waited.snapshot : messageSnapshot(waited.message);
+        const waitedIsError = "snapshot" in waited ? snapshotIsError(waited.snapshot) : false;
+        const waitedNextAction = "snapshot" in waited
+            ? (waited.waitResult === "timed_out" ? nextAction(waited.snapshot) : undefined)
+            : pollAction(observed.session_id, observed.status_url);
+        return elarisResult({
+            ok: true,
+            operation: "message",
+            turn_id: observed.turn_id,
+            idempotency_key: idempotencyKey,
+            idempotent_replay: observed.idempotent_replay,
+            ...waitedBody,
+            wait_result: waited.waitResult,
+            next_action: waitedNextAction,
+        }, {
+            isError: waitedIsError,
+            maxChars: input.maxResponseChars,
+        });
+    }
+    return elarisResult({
+        ok: true,
+        operation: "message",
+        turn_id: observed.turn_id,
+        idempotency_key: idempotencyKey,
+        idempotent_replay: observed.idempotent_replay,
+        ...messageSnapshot(message),
+        wait_result: "not_requested",
+        next_action: pollAction(observed.session_id, observed.status_url),
+    }, { maxChars: input.maxResponseChars });
+}
+async function handleStatusMutation(operation, mutate, sessionId, maxResponseChars) {
+    try {
+        const response = await mutate();
+        const snapshot = {
+            ...mapStatusResponseToSnapshot(response),
+            session_id: sessionId,
+        };
+        return elarisResult({
+            ok: true,
+            operation,
+            ...snapshot,
+            next_action: operation === "cancel" ? pollAction(sessionId) : nextAction(snapshot),
+        }, {
+            isError: snapshotIsError(snapshot),
+            maxChars: maxResponseChars,
+        });
+    }
+    catch (err) {
+        const remote = remoteFailureFromUnknown(err);
+        if (remote !== undefined) {
+            const errorKind = classifyElarisHttpError(remote.status, remote.rawEnvelope);
+            if (operation === "cleanup" && errorKind === "not_terminal") {
+                return elarisResult({
+                    ok: true,
+                    operation,
+                    ready: false,
+                    next_action: pollAction(sessionId),
+                }, { maxChars: maxResponseChars });
+            }
+            throw new ElarisStructuredFailure(buildFailureForRemote(errorKind, remote, operation, undefined));
+        }
+        throw err;
+    }
+}
+async function handleElarisHealth(signal, options, maxResponseChars) {
+    throwIfCancelled(signal);
+    let config;
+    try {
+        config = options.config ?? loadElarisConfig();
+    }
+    catch (err) {
+        return elarisResult({
+            ok: false,
+            operation: "health",
+            error_kind: "invalid_config",
+            config_ok: false,
+            key_present: false,
+            router: "not_checked",
+            supported_ops: SUPPORTED_MANAGE_OPS,
+            ...scopeHealthFields(),
+            detail: err instanceof Error ? err.message : "Invalid Elaris config.",
+        }, { maxChars: maxResponseChars });
+    }
+    const apiKeyEnv = config.API_KEY_ENV ?? "CLINKX_ELARIS_API_KEY";
+    const apiKey = process.env[apiKeyEnv]?.trim() ?? "";
+    let baseUrl;
+    try {
+        if (config.BASE_URL === undefined)
+            throw new InvalidParamsError("CLINKX_ELARIS_BASE_URL is required when Elaris is enabled");
+        baseUrl = validateElarisBaseUrl(config.BASE_URL);
+    }
+    catch (err) {
+        return elarisResult({
+            ok: false,
+            operation: "health",
+            error_kind: "invalid_config",
+            config_ok: false,
+            key_env: apiKeyEnv,
+            key_present: apiKey.length > 0,
+            router: "not_checked",
+            supported_ops: SUPPORTED_MANAGE_OPS,
+            ...scopeHealthFields(),
+            detail: err instanceof Error ? err.message : "Invalid Elaris base URL.",
+        }, { maxChars: maxResponseChars });
+    }
+    const client = options.client ?? new ElarisClient({
+        fetch: globalThis.fetch,
+        baseUrl,
+        apiKey,
+        requestTimeoutMs: (config.REQUEST_TIMEOUT_SECONDS ?? 30) * 1000,
+    });
+    const probe = await client.healthProbe({ signal });
+    // healthProbe swallows fetch failures (including the external abort) into a normal
+    // diagnostics body, so re-check the external signal here: a swallowed abort must
+    // become CancellationError (no MCP response), not a successful health body.
+    throwIfCancelled(signal);
+    return elarisResult({
+        ok: true,
+        operation: "health",
+        config_ok: true,
+        key_env: apiKeyEnv,
+        key_present: apiKey.length > 0,
+        router: "indeterminate",
+        supported_ops: SUPPORTED_MANAGE_OPS,
+        ...scopeHealthFields(),
+        probe,
+    }, { maxChars: maxResponseChars });
+}
+function unsupportedManageResult(op, maxResponseChars = 20000) {
+    return elarisResult({
+        ok: false,
+        error_kind: "unsupported_v1",
+        operation: op,
+        detail: "This Elaris manage operation has no v1 remote endpoint or is deferred.",
+    }, { isError: true, maxChars: maxResponseChars });
+}
+const SUPPORTED_MANAGE_OPS = [
+    "poll",
+    "wait",
+    "result",
+    "content",
+    "logs",
+    "artifacts",
+    "artifact_raw",
+    "message",
+    "cancel",
+    "cleanup",
+    "health",
+];
+// tool-schemas.ts owns the schema-side source of truth (`unsupportedManageOps`).
+// This map is keyed by the `ElarisUnsupportedManageOp` union, so any change to that
+// union there fails compilation here — keeping the two definitions from drifting.
+const UNSUPPORTED_MANAGE_OP_FLAGS = {
+    list: true,
+    list_models: true,
+    events: true,
+    steer: true,
+    approvals: true,
+};
+const UNSUPPORTED_MANAGE_OPS = new Set(Object.keys(UNSUPPORTED_MANAGE_OP_FLAGS));
+const REQUIRED_SCOPES_BY_OPERATION = {
+    clink_elaris_run: ["agent_sessions:create"],
+    clink_elaris_run_wait: ["agent_sessions:create", "agent_sessions:read"],
+    duplicate_recovery: ["agent_sessions:read"],
+    poll: ["agent_sessions:read"],
+    wait: ["agent_sessions:read"],
+    result: ["agent_sessions:read"],
+    content: ["agent_sessions:read"],
+    logs: ["agent_sessions:logs"],
+    artifacts: ["agent_sessions:artifacts"],
+    artifact_raw: ["agent_sessions:artifacts"],
+    message: ["agent_sessions:message"],
+    message_wait: ["agent_sessions:message", "agent_sessions:read"],
+    cancel: ["agent_sessions:cancel"],
+    cleanup: ["agent_sessions:cleanup"],
+    health: ["agent_sessions:read"],
+};
+const REQUIRED_SCOPES = Array.from(new Set(Object.values(REQUIRED_SCOPES_BY_OPERATION).flat())).sort();
+const SCOPES_BY_OPERATION = Object.fromEntries(Object.entries(REQUIRED_SCOPES_BY_OPERATION).map(([op, scopes]) => [op, [...scopes]]));
+function scopeHealthFields() {
+    return {
+        required_scopes: [...REQUIRED_SCOPES],
+        scopes_by_operation: Object.fromEntries(Object.entries(SCOPES_BY_OPERATION).map(([op, scopes]) => [op, [...scopes]])),
+    };
+}
+function messageFields(message) {
+    return message;
+}
+function isUnsupportedManageOp(op) {
+    return UNSUPPORTED_MANAGE_OPS.has(op);
+}
+async function fetchManageStatus(client, input, signal, operation) {
+    try {
+        return input.status_url !== undefined
+            ? await client.getStatusByHandle(input.status_url, { signal })
+            : await client.getStatusBySessionId(input.session_id, { signal });
+    }
+    catch (err) {
+        rethrowIfCancelled(err, signal);
+        const remote = remoteFailureFromUnknown(err);
+        if (remote !== undefined) {
+            const errorKind = classifyElarisHttpError(remote.status, remote.rawEnvelope);
+            throw new ElarisStructuredFailure(buildFailureForRemote(errorKind, remote, operation, undefined));
+        }
+        throw err;
+    }
+}
+function echoStatusLocator(snapshot, input) {
+    return {
+        ...snapshot,
+        session_id: input.session_id,
+        status_url: input.status_url,
+        keep_alive_known: false,
+    };
+}
+function manageFailureIsError(op, errorKind) {
+    if (errorKind === "unknown_session" && (op === "poll" || op === "wait")) {
+        return false;
+    }
+    return true;
+}
+function pollAction(sessionId, statusUrl) {
+    return {
+        tool: "clink_elaris_manage",
+        op: "poll",
+        session_id: sessionId,
+        status_url: statusUrl,
+    };
+}
+function objectOrValue(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return { value };
+}
+function buildMessageRequest(input, idempotencyKey) {
+    const request = {
+        prompt: input.prompt,
+        permission_mode: input.permission_mode,
+        idempotency_key: idempotencyKey,
+    };
+    if (input.model_id !== undefined)
+        request.model_id = input.model_id;
+    if (input.effort_level !== undefined)
+        request.effort_level = input.effort_level;
+    if (input.metadata !== undefined)
+        request.metadata = input.metadata;
+    return request;
+}
+async function postMessageWithBoundedRetry(input) {
+    const maxAttempts = 2;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        throwIfCancelled(input.signal);
+        try {
+            return await input.client.postMessage(input.sessionId, input.request, { signal: input.signal });
+        }
+        catch (err) {
+            rethrowIfCancelled(err, input.signal);
+            const remote = remoteFailureFromUnknown(err);
+            if (remote !== undefined) {
+                const errorKind = classifyElarisHttpError(remote.status, remote.rawEnvelope);
+                throw new ElarisStructuredFailure(buildFailureForRemote(errorKind, remote, "message", undefined));
+            }
+            if (!isAmbiguousTransportError(err))
+                throw err;
+            lastError = err;
+            if (attempt >= maxAttempts)
+                break;
+            const slept = await input.waitForNextPoll({
+                deadlineMs: input.deadlineMs,
+                pollIntervalMs: input.pollIntervalMs,
+                signal: input.signal,
+            });
+            if (!slept)
+                break;
+        }
+    }
+    throw new ElarisStructuredFailure(buildElarisFailureBody({
+        error_kind: "backend_unavailable",
+        operation: "message",
+        idempotency_key: input.request.idempotency_key,
+        detail: `Message dispatch outcome is ambiguous after retry budget; retry with the returned idempotency_key to recover if the MCP response was lost. Last error: ${lastError instanceof Error ? lastError.message : "unknown transport failure"}`,
+    }));
+}
+async function waitForMessageTerminal(input) {
+    while (true) {
+        if (input.nowMs() >= input.deadlineMs) {
+            return { message: input.message, waitResult: "timed_out" };
+        }
+        const slept = await input.waitForNextPoll({
+            deadlineMs: input.deadlineMs,
+            pollIntervalMs: input.pollIntervalMs,
+            signal: input.signal,
+        });
+        if (!slept) {
+            return { message: input.message, waitResult: "timed_out" };
+        }
+        throwIfCancelled(input.signal);
+        const observed = messageFields(input.message);
+        const status = await fetchStatusOrStructured(() => input.client.getStatusByHandle(observed.status_url, { signal: input.signal }), undefined, "message");
+        const snapshot = {
+            ...mapStatusResponseToSnapshot(status),
+            session_id: observed.session_id,
+            status_url: observed.status_url,
+            result_url: observed.result_url,
+        };
+        if (snapshot.terminal)
+            return { snapshot, waitResult: "settled" };
+    }
+}
+function messageSnapshot(message) {
+    const observed = messageFields(message);
+    return {
+        session_id: observed.session_id,
+        raw_status: observed.status,
+        normalized_status: normalizeElarisStatus(observed.status),
+        terminal: isTerminalElarisStatus(observed.status),
+        status_url: observed.status_url,
+        result_url: observed.result_url,
+    };
+}
+function generateMessageIdempotencyKey() {
+    const timestamp = new Date().toISOString().replace(/\D/g, "").slice(0, 14);
+    const random = Math.random().toString(36).slice(2, 12);
+    return `cxmsg_${timestamp}_${random}`;
+}
+async function createWithBoundedRetry(input) {
+    const maxAttempts = 3;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        throwIfCancelled(input.signal);
+        try {
+            const response = await input.client.createSession(input.request, { signal: input.signal });
+            return { kind: "created", response };
+        }
+        catch (err) {
+            throwIfCancelled(input.signal);
+            if (err instanceof InvalidParamsError || err instanceof ExecutionError || err instanceof CancellationError) {
+                throw err;
+            }
+            const remote = remoteFailureFromUnknown(err);
+            if (remote !== undefined) {
+                const errorKind = classifyElarisHttpError(remote.status, remote.rawEnvelope);
+                if (errorKind === "duplicate_run_id") {
+                    return { kind: "duplicate", locator: duplicateLocator(remote.rawEnvelope) };
+                }
+                if (shouldRetryCreate(errorKind) && attempt < maxAttempts) {
+                    const slept = await maybeWaitForCreateRetry({
+                        retryAfterMs: remote.retry_after_ms,
+                        pollIntervalMs: input.input.poll_interval_ms,
+                        deadlineMs: input.deadlineMs,
+                        signal: input.signal,
+                        waitForNextPoll: input.waitForNextPoll,
+                        nowMs: input.nowMs,
+                    });
+                    if (slept)
+                        continue;
+                }
+                return {
+                    kind: "tool_result",
+                    body: buildFailureForRemote(errorKind, remote, "clink_elaris_run", input.request.run_id),
+                    isError: true,
+                };
+            }
+            if (!isAmbiguousTransportError(err)) {
+                throw new ExecutionError(err instanceof Error ? err.message : "Unexpected Elaris create failure");
+            }
+            if (attempt < maxAttempts) {
+                const slept = await maybeWaitForCreateRetry({
+                    retryAfterMs: undefined,
+                    pollIntervalMs: input.input.poll_interval_ms,
+                    deadlineMs: input.deadlineMs,
+                    signal: input.signal,
+                    waitForNextPoll: input.waitForNextPoll,
+                    nowMs: input.nowMs,
+                });
+                if (slept)
+                    continue;
+            }
+            return {
+                kind: "tool_result",
+                body: buildElarisFailureBody({
+                    error_kind: "backend_unavailable",
+                    operation: "clink_elaris_run",
+                    detail: ambiguousCreateDetail(err),
+                    run_id: input.request.run_id,
+                }),
+                isError: true,
+            };
+        }
+    }
+    throw new ExecutionError("unreachable Elaris create retry state");
+}
+async function recoverDuplicate(input) {
+    if (input.locator.status_url === undefined && input.locator.session_id === undefined) {
+        return elarisResult(buildElarisFailureBody({
+            error_kind: "duplicate_run_id",
+            operation: "clink_elaris_run",
+            detail: "Duplicate run_id was reported without a poll locator.",
+            run_id: input.runId,
+        }), { isError: true, maxChars: input.maxResponseChars });
+    }
+    const status = await fetchStatusOrStructured(() => input.locator.status_url !== undefined
+        ? input.client.getStatusByHandle(input.locator.status_url, { signal: input.signal })
+        : input.client.getStatusBySessionId(input.locator.session_id, { signal: input.signal }), input.runId);
+    let snapshot = mapStatusResponseToSnapshot(status);
+    snapshot = {
+        ...snapshot,
+        session_id: input.locator.session_id,
+        status_url: input.locator.status_url,
+    };
+    let waitResult = "not_requested";
+    if (input.input.wait) {
+        const waited = await waitForTerminal({
+            client: input.client,
+            createSnapshot: snapshot,
+            signal: input.signal,
+            deadlineMs: input.deadlineMs,
+            pollIntervalMs: input.input.poll_interval_ms,
+            waitForNextPoll: input.waitForNextPoll,
+            nowMs: input.nowMs,
+            runId: input.runId,
+        });
+        snapshot = waited.snapshot;
+        waitResult = waited.waitResult;
+    }
+    const body = {
+        ok: true,
+        operation: "clink_elaris_run",
+        recovered_duplicate: true,
+        duplicate_recovery_note: "Recovered duplicate run_id for polling/read-only status. Multi-turn message continuation requires the same Elaris API key.",
+        session_id: input.locator.session_id,
+        status_url: input.locator.status_url,
+        ...snapshot,
+        wait_result: waitResult,
+        next_action: snapshot.terminal ? undefined : nextAction({ ...snapshot, session_id: input.locator.session_id, status_url: input.locator.status_url }),
+    };
+    return elarisResult(body, {
+        isError: snapshotIsError(snapshot),
+        maxChars: input.maxResponseChars,
+    });
+}
+async function waitForTerminal(input) {
+    let latest = input.createSnapshot;
+    while (!latest.terminal) {
+        if (input.nowMs() >= input.deadlineMs) {
+            return { snapshot: latest, waitResult: "timed_out" };
+        }
+        const slept = await input.waitForNextPoll({
+            deadlineMs: input.deadlineMs,
+            pollIntervalMs: input.pollIntervalMs,
+            signal: input.signal,
+        });
+        if (!slept) {
+            return { snapshot: latest, waitResult: "timed_out" };
+        }
+        throwIfCancelled(input.signal);
+        const status = await fetchStatusOrStructured(() => latest.status_url !== undefined
+            ? input.client.getStatusByHandle(latest.status_url, { signal: input.signal })
+            : input.client.getStatusBySessionId(requiredSessionId(latest), { signal: input.signal }), input.runId);
+        latest = mergeCreateProvenance(mapStatusResponseToSnapshot(status), input.createSnapshot);
+    }
+    return { snapshot: latest, waitResult: "settled" };
+}
+function buildCreateRequest(input, modelId, runId) {
+    const request = {
+        prompt: input.prompt,
+        model_id: modelId,
+        permission_mode: input.permission_mode,
+        run_id: runId,
+        keep_alive: input.keep_alive,
+    };
+    if (input.effort_level !== undefined)
+        request.effort_level = input.effort_level;
+    if (input.metadata !== undefined)
+        request.metadata = input.metadata;
+    if (input.github_repo !== undefined)
+        request.github_repo = input.github_repo;
+    return request;
+}
+function createDefaultClient(config) {
+    if (config.BASE_URL === undefined || config.API_KEY_ENV === undefined || config.REQUEST_TIMEOUT_SECONDS === undefined) {
+        throw new InvalidParamsError("Elaris config is incomplete.");
+    }
+    return new ElarisClient({
+        fetch: globalThis.fetch,
+        baseUrl: validateElarisBaseUrl(config.BASE_URL),
+        apiKey: resolveElarisApiKey(config.API_KEY_ENV),
+        requestTimeoutMs: config.REQUEST_TIMEOUT_SECONDS * 1000,
+    });
+}
+function nextAction(snapshot) {
+    if (snapshot.terminal)
+        return undefined;
+    return {
+        tool: "clink_elaris_manage",
+        op: "poll",
+        session_id: snapshot.session_id,
+        status_url: snapshot.status_url,
+    };
+}
+function shouldRetryCreate(errorKind) {
+    return errorKind === "rate_limited" || errorKind === "backend_unavailable";
+}
+async function maybeWaitForCreateRetry(input) {
+    const slept = await input.waitForNextPoll({
+        deadlineMs: input.deadlineMs,
+        retryAfterMs: input.retryAfterMs,
+        pollIntervalMs: input.pollIntervalMs,
+        signal: input.signal,
+    });
+    if (!slept)
+        return false;
+    throwIfCancelled(input.signal);
+    return true;
+}
+function remoteFailureFromUnknown(err) {
+    if (isElarisHttpError(err)) {
+        const envelope = err.payload ?? {};
+        return {
+            status: err.status,
+            envelope,
+            rawEnvelope: err.rawPayload ?? envelope,
+            retry_after_ms: err.retryAfterMs,
+        };
+    }
+    if (typeof err !== "object" || err === null)
+        return undefined;
+    const record = err;
+    const status = firstNumber(record.status, record.statusCode, record.http_status, record.httpStatus);
+    if (status === undefined)
+        return undefined;
+    const envelope = record.envelope ?? record.payload ?? record.body ?? record.responseBody ?? record.data ?? {};
+    return {
+        status,
+        envelope,
+        rawEnvelope: record.rawPayload ?? envelope,
+        retry_after_ms: firstNumber(record.retry_after_ms, record.retryAfterMs),
+    };
+}
+class ElarisStructuredFailure extends Error {
+    body;
+    constructor(body) {
+        super("elaris structured failure");
+        this.body = body;
+        this.name = "ElarisStructuredFailure";
+    }
+}
+async function fetchStatusOrStructured(fetchStatus, runId, operation = "clink_elaris_run") {
+    try {
+        return await fetchStatus();
+    }
+    catch (err) {
+        if (err instanceof CancellationError)
+            throw err;
+        const remote = remoteFailureFromUnknown(err);
+        if (remote !== undefined) {
+            const errorKind = classifyElarisHttpError(remote.status, remote.rawEnvelope);
+            throw new ElarisStructuredFailure(buildFailureForRemote(errorKind, remote, operation, runId));
+        }
+        throw err;
+    }
+}
+function buildFailureForRemote(errorKind, remote, operation, runId) {
+    const inferredReason = errorKind === "follow_up_conflict"
+        ? inferFollowUpConflictReason(remote.rawEnvelope)
+        : undefined;
+    return buildElarisFailureBody({
+        error_kind: errorKind,
+        operation,
+        http_status: remote.status,
+        retry_after_ms: remote.retry_after_ms,
+        request_id: errorEnvelopeRequestId(remote.envelope),
+        detail: errorEnvelopeDetail(remote.envelope) ?? errorKind,
+        run_id: errorEnvelopeRunId(remote.envelope) ?? runId,
+        inferred_reason: inferredReason,
+    });
+}
+function duplicateLocator(envelope) {
+    if (typeof envelope !== "object" || envelope === null)
+        return {};
+    const record = envelope;
+    const details = typeof record.details === "object" && record.details !== null
+        ? record.details
+        : {};
+    return {
+        session_id: firstString(record.session_id, details.session_id),
+        status_url: firstString(record.status_url, details.status_url),
+    };
+}
+function ambiguousCreateDetail(err) {
+    const message = err instanceof Error ? err.message : "unknown transport failure";
+    return `Create outcome is ambiguous after retry budget; retry with the same caller-supplied run_id to recover if the MCP response was lost. Last error: ${message}`;
+}
+function isAmbiguousTransportError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.name === "AbortError" || err.name === "TimeoutError" || err.name === "TypeError") {
+        return true;
+    }
+    return /fetch|network|timeout|timed out|econn|socket|terminated/i.test(err.message);
+}
+function requiredSessionId(snapshot) {
+    if (snapshot.session_id === undefined) {
+        throw new ExecutionError("Elaris status polling requires session_id or status_url.");
+    }
+    return snapshot.session_id;
+}
+function throwIfCancelled(signal) {
+    if (signal?.aborted === true) {
+        throw new CancellationError();
+    }
+}
+// Normalizes an observed failure into MCP cancellation when warranted: rethrows a
+// CancellationError verbatim, and converts a fetch/transport rejection into a
+// CancellationError when the EXTERNAL request signal is aborted. It does NOT
+// translate the client's internal request-timeout abort — only `signal.aborted`.
+function rethrowIfCancelled(err, signal) {
+    if (err instanceof CancellationError)
+        throw err;
+    throwIfCancelled(signal);
+}
+// artifact_raw has file-level taxonomy in addition to session-level taxonomy.
+// Provider session-not-found includes error_code AGENT_SESSION_NOT_FOUND; a bare
+// 404 means the artifact file/sandbox was not found.
+function classifyManageRemote(op, remote) {
+    const errorKind = classifyElarisHttpError(remote.status, remote.rawEnvelope);
+    if (op === "artifact_raw" &&
+        remote.status === 404 &&
+        errorEnvelopeCode(remote.rawEnvelope) !== "AGENT_SESSION_NOT_FOUND") {
+        return "artifact_not_found";
+    }
+    if (op === "artifact_raw" && (remote.status === 400 || remote.status === 422)) {
+        return "artifact_request_error";
+    }
+    return errorKind;
+}
+function errorEnvelopeCode(envelope) {
+    if (typeof envelope !== "object" || envelope === null)
+        return undefined;
+    const record = envelope;
+    return typeof record.error_code === "string" ? record.error_code : undefined;
+}
+function firstNumber(...values) {
+    return values.find((value) => typeof value === "number" && Number.isFinite(value));
+}
+function firstString(...values) {
+    return values.find((value) => typeof value === "string" && value.length > 0);
+}
+//# sourceMappingURL=tools.js.map