@anureo/adapter-claude 0.0.0-stage → 0.3.0

package/src/store.js

@@ -0,0 +1,223 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, readdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { HarnessSdkError } from "@anureo/sdk";
+/** Persist JSON-safe, opaque Claude transcript entries in a host-owned directory.
+ * Supply this as sessionStore to ClaudeNativeAdapter. With a configured state directory and no
+ * supplied store, the adapter creates one in its ahp-session-store subdirectory and also uses it
+ * to persist turn IDs for boundary lookup. The native SDK invokes the SessionStore methods for
+ * mirroring, resume and history. Transcript keys include the project, session and optional
+ * subpath. The host owns retention and coordinates deletion with writers. Construction opens no
+ * resources and requires no disposal. */
+export class FileSessionStore {
+    directory;
+    /** Use directory for transcripts and turn maps. Writes create missing directories with mode 0700. */
+    constructor(directory) {
+        this.directory = directory;
+    }
+    /** Commit a batch of JSON-safe entries under the lock for this transcript key.
+     * A truthy UUID replaces its existing entry in place. New UUIDs and entries without a truthy
+     * UUID append in batch order. Resolve after file sync, atomic rename and lock cleanup.
+     * An unreclaimable lock that is still contended at the 10-second retry deadline rejects with
+     * SESSION_STORE_BUSY. Transcript read, write and cleanup failures also reject, including
+     * cleanup after publication. ClaudeBackendSession.observedStore awaits successful
+     * main-transcript appends before scheduling a title refresh for the active query. Rejections
+     * return to the native SDK. */
+    async append(key, entries) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const file = this.transcriptPath(key);
+        const lockPath = `${file}.lock`;
+        const lockHandle = await acquireSessionLock(lockPath);
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+            const stored = await this.readTranscript(file) ?? { key: structuredClone(key), entries: [], mtime: 0 };
+            mergeSessionEntries(stored, entries);
+            await publishJson({ file, temporary, value: stored });
+        }
+        finally {
+            await rm(temporary, { force: true });
+            await lockHandle.close();
+            await rm(lockPath, { force: true });
+        }
+    }
+    /** Load a detached full transcript, or null when the requested file is absent.
+     * An envelope without a truthy key or an entries array rejects with SESSION_STORE_INVALID.
+     * Other filesystem and JSON parse failures propagate. ClaudeBackendSession.boundaryPoint and
+     * structuredHistory also read these entries to include opaque records omitted by native history
+     * in fork/revert cutoffs and structured output in history pages, respectively. */
+    async load(key) {
+        const stored = await this.readTranscript(this.transcriptPath(key));
+        return stored ? structuredClone(stored.entries) : null;
+    }
+    /** List transcripts with no truthy subpath for a project in filesystem order.
+     * The stored mtime is in Unix epoch milliseconds and advances on every committed append.
+     * A missing directory yields an empty list. Read and envelope errors anywhere in the
+     * transcript scan reject the listing. */
+    async listSessions(projectKey) {
+        return (await this.scanTranscripts())
+            .filter((entry) => entry.key.projectKey === projectKey && !entry.key.subpath)
+            .map(({ key, mtime }) => ({ sessionId: key.sessionId, mtime }));
+    }
+    /** List nonempty transcript subpaths for a project and session in filesystem order.
+     * A missing directory yields an empty list. Scan failures propagate as in listSessions. */
+    async listSubkeys(key) {
+        return (await this.scanTranscripts()).flatMap((entry) => {
+            if (entry.key.projectKey !== key.projectKey || entry.key.sessionId !== key.sessionId)
+                return [];
+            return entry.key.subpath ? [entry.key.subpath] : [];
+        });
+    }
+    /** Remove the transcript for this exact key, accepting an absent file.
+     * Other subpaths and turn maps remain. The caller must coordinate this unlocked deletion with
+     * writers. Other removal failures reject. */
+    async delete(key) {
+        await rm(this.transcriptPath(key), { force: true });
+    }
+    /** Load adapter boundary metadata mapping native input UUIDs to AHP turn IDs by native session ID.
+     * Return the parsed JSON as stored, or an empty map when the file is absent. Other read and
+     * parse failures reject.
+     * ClaudeBackendSession.open restores the map for the active session or reads it from the fork
+     * source. ClaudeBackendSession.boundaryPoint uses the map to resolve AHP turn IDs to candidates
+     * that it verifies in native history. */
+    async loadTurnMap(sessionId) {
+        try {
+            return JSON.parse(await readFile(this.turnMapPath(sessionId), "utf8"));
+        }
+        catch (cause) {
+            if (cause.code === "ENOENT")
+                return {};
+            throw cause;
+        }
+    }
+    /** Replace the adapter's turn map for a native session ID.
+     * Resolve after file sync, atomic rename and temporary-file cleanup. Callers must order
+     * concurrent replacements if publication order matters. Cleanup can reject after publication.
+     * ClaudeBackendSession.open and restoreConversation await the save before starting a query.
+     * Saves during input association or a native ID change can fail the query pump. */
+    async saveTurnMap(sessionId, turns) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const file = this.turnMapPath(sessionId);
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+            await publishJson({ file, temporary, value: turns });
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    /** Keep each transcript at its stable hashed path. Omitted subpaths use the null slot in the
+     * tuple, preserving the on-disk key format and keeping an explicit empty string distinct. */
+    transcriptPath(key) {
+        return join(this.directory, `${createHash("sha256")
+            .update(JSON.stringify([key.projectKey, key.sessionId, key.subpath ?? null]))
+            .digest("hex")}.json`);
+    }
+    /** Read a transcript envelope for load, append or a scan. Return null on absence and reject
+     * malformed JSON or a missing key/entries array so append cannot overwrite those records. */
+    async readTranscript(file) {
+        try {
+            const value = JSON.parse(await readFile(file, "utf8"));
+            if (!value || !value.key || !Array.isArray(value.entries))
+                throw new HarnessSdkError("SESSION_STORE_INVALID");
+            return value;
+        }
+        catch (cause) {
+            if (cause.code === "ENOENT")
+                return null;
+            throw cause;
+        }
+    }
+    /** Scan the hashed transcript filenames for both listing methods. Preserve directory order and
+     * skip files removed before they can be read. Directory absence also yields an empty result.
+     * Other read or envelope errors reject before the caller filters by project or session. */
+    async scanTranscripts() {
+        const names = await readdir(this.directory).catch((cause) => {
+            if (cause.code === "ENOENT")
+                return [];
+            throw cause;
+        });
+        const transcripts = names.filter((name) => /^[a-f0-9]{64}\.json$/.test(name));
+        const entries = await Promise.all(transcripts.map((name) => this.readTranscript(join(this.directory, name))));
+        return entries.filter((entry) => entry !== null);
+    }
+    /** Keep boundary metadata at its stable session-ID path, outside the transcript filename pattern. */
+    turnMapPath(sessionId) {
+        return join(this.directory, `${createHash("sha256").update(`turns:${sessionId}`).digest("hex")}.turns.json`);
+    }
+}
+/** Acquire append's exclusive lock and record its PID. Once the handle is returned, append owns
+ * close and removal. A rejected PID write can strand the handle and lock file before transfer. */
+async function acquireSessionLock(lockPath) {
+    const deadline = Date.now() + 10_000;
+    let lockHandle;
+    while (!lockHandle) {
+        try {
+            lockHandle = await open(lockPath, "wx", 0o600);
+            await lockHandle.writeFile(String(process.pid));
+        }
+        catch (cause) {
+            if (cause.code !== "EEXIST")
+                throw cause;
+            await waitForSessionLock({ lockPath, deadline });
+        }
+    }
+    return lockHandle;
+}
+/** Resolve contention before acquireSessionLock retries. Reclaim only a lock whose PID is gone,
+ * since an unreadable PID or an old lock can still belong to a live writer. For other owners,
+ * wait 10 ms before retrying or reject with SESSION_STORE_BUSY at the deadline. A failed removal
+ * also rejects append. */
+async function waitForSessionLock({ lockPath, deadline }) {
+    const pid = Number(await readFile(lockPath, "utf8").catch(() => ""));
+    if (isLockOwnerDefinitelyAbsent(pid)) {
+        await rm(lockPath, { force: true });
+        return;
+    }
+    if (Date.now() >= deadline)
+        throw new HarnessSdkError("SESSION_STORE_BUSY");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+}
+/** Treat only ESRCH for a valid positive PID as proof; permission errors leave the lock intact. */
+function isLockOwnerDefinitelyAbsent(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+/** Mutate append's locked snapshot, cloning incoming entries and preserving UUID positions.
+ * Index new UUIDs immediately so repeats in the same batch also replace in place. */
+function mergeSessionEntries(stored, entries) {
+    const entryIndexByUuid = new Map(stored.entries.flatMap((entry, index) => entry.uuid ? [[entry.uuid, index]] : []));
+    for (const entry of entries) {
+        const existingIndex = entry.uuid ? entryIndexByUuid.get(entry.uuid) : undefined;
+        if (existingIndex !== undefined) {
+            stored.entries[existingIndex] = structuredClone(entry);
+        }
+        else {
+            if (entry.uuid)
+                entryIndexByUuid.set(entry.uuid, stored.entries.length);
+            stored.entries.push(structuredClone(entry));
+        }
+    }
+    stored.mtime = Math.max(Date.now(), stored.mtime + 1);
+}
+/** Publish JSON by renaming an exclusive mode-0600 temporary file after sync and close.
+ * append and saveTurnMap supply a unique path in the destination directory for atomic rename
+ * and own path cleanup. File and serialization failures reject, and the temporary handle closes
+ * before the destination can be replaced. */
+async function publishJson({ file, temporary, value }) {
+    const temporaryHandle = await open(temporary, "wx", 0o600);
+    try {
+        await temporaryHandle.writeFile(JSON.stringify(value));
+        await temporaryHandle.sync();
+    }
+    finally {
+        await temporaryHandle.close();
+    }
+    await rename(temporary, file);
+}

package/src/turn-error.d.ts

@@ -0,0 +1,11 @@
+import type { SDKAssistantMessageError, SDKResultMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { HarnessError } from '@anureo/protocol';
+/**
+ * Classify a native terminal result, returning undefined for a successful non-error result.
+ * Execution limits take precedence. For API failures, a recognized assistant category takes
+ * precedence over a valid HTTP status. Returned errors use fixed messages and omit native prose.
+ * ClaudeBackendSession.completeTurn supplies the latest main-assistant category and emits the
+ * returned error with turn/completed unless interrupted. The caller receives it in the failed
+ * result from Turn.result(). Retryability is advice for the consumer.
+ */
+export declare function claudeTurnError(result: SDKResultMessage, assistantError?: SDKAssistantMessageError): HarnessError | undefined;

package/src/turn-error.js

@@ -0,0 +1,74 @@
+/**
+ * Classify a native terminal result, returning undefined for a successful non-error result.
+ * Execution limits take precedence. For API failures, a recognized assistant category takes
+ * precedence over a valid HTTP status. Returned errors use fixed messages and omit native prose.
+ * ClaudeBackendSession.completeTurn supplies the latest main-assistant category and emits the
+ * returned error with turn/completed unless interrupted. The caller receives it in the failed
+ * result from Turn.result(). Retryability is advice for the consumer.
+ */
+export function claudeTurnError(result, assistantError) {
+    if (result.subtype === 'success' && !result.is_error)
+        return undefined;
+    const limitCode = executionLimitCode(result.subtype);
+    if (limitCode)
+        return { code: limitCode, message: 'Claude execution limit reached', retryable: false, outcomeUnknown: false };
+    if (result.subtype !== 'success' && result.terminal_reason !== 'api_error') {
+        return { code: 'CLAUDE_TURN_FAILED', message: 'Claude turn failed', retryable: false, outcomeUnknown: false };
+    }
+    const status = apiErrorStatus(result);
+    const code = apiErrorCode(assistantError, status);
+    return {
+        code,
+        message: 'Claude model request failed',
+        retryable: code === 'RATE_LIMITED' || code === 'NATIVE_SERVICE_UNAVAILABLE',
+        outcomeUnknown: false,
+        ...(status !== undefined ? { details: { httpStatusCode: status } } : {}),
+    };
+}
+/** Recognize execution limits before consulting potentially stale API failure evidence. */
+function executionLimitCode(subtype) {
+    switch (subtype) {
+        case 'error_max_structured_output_retries': return 'CLAUDE_STRUCTURED_OUTPUT_RETRIES_EXCEEDED';
+        case 'error_max_turns': return 'CLAUDE_MAX_TURNS_EXCEEDED';
+        case 'error_max_budget_usd': return 'CLAUDE_MAX_BUDGET_EXCEEDED';
+        default: return undefined;
+    }
+}
+/** Accept HTTP status integers from 100 through 599 on the success variant for classification and public details. */
+function apiErrorStatus(result) {
+    if (result.subtype !== 'success')
+        return undefined;
+    const status = result.api_error_status;
+    if (typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599)
+        return status;
+    return undefined;
+}
+const assistantErrorCodes = {
+    authentication_failed: 'AUTH_REQUIRED',
+    oauth_org_not_allowed: 'AUTH_FORBIDDEN',
+    account_on_hold: 'AUTH_FORBIDDEN',
+    billing_error: 'USAGE_LIMIT_EXCEEDED',
+    rate_limit: 'RATE_LIMITED',
+    overloaded: 'NATIVE_SERVICE_UNAVAILABLE',
+    server_error: 'NATIVE_SERVICE_UNAVAILABLE',
+    invalid_request: 'NATIVE_REQUEST_INVALID',
+    model_not_found: 'MODEL_NOT_FOUND',
+    max_output_tokens: 'CLAUDE_MAX_OUTPUT_TOKENS',
+};
+/** Use a recognized assistant category first, then fall back to HTTP status. */
+function apiErrorCode(assistantError, status) {
+    if (assistantError && Object.hasOwn(assistantErrorCodes, assistantError)) {
+        const code = assistantErrorCodes[assistantError];
+        if (code)
+            return code;
+    }
+    if (status === 401)
+        return 'AUTH_REQUIRED';
+    if (status === 403)
+        return 'AUTH_FORBIDDEN';
+    if (status === 429)
+        return 'RATE_LIMITED';
+    if (status !== undefined && status >= 500)
+        return 'NATIVE_SERVICE_UNAVAILABLE';
+    return 'CLAUDE_TURN_FAILED';
+}