apex-code 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/core/session-lease.js

@@ -0,0 +1,138 @@
+/**
+ * Liveness records for sessions sharing one working directory.
+ *
+ * Two Apex Code sessions in the same working tree overwrite each other's edits and
+ * commits, and neither one can tell. Each process publishes its own lease file rather
+ * than sharing one, so nothing here takes a lock and the startup path stays free of
+ * `proper-lockfile`.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const LEASE_DIR_NAME = "leases";
+function leaseDir(sessionDir) {
+    return join(sessionDir, LEASE_DIR_NAME);
+}
+function leasePath(sessionDir, pid) {
+    return join(leaseDir(sessionDir), `${pid}.json`);
+}
+/**
+ * Only ESRCH proves the process is gone. EPERM means it exists under another user, and
+ * anything else means the probe itself failed, so treat both as alive: a session we
+ * cannot rule out is worth warning about, and `--allow-concurrent` clears a false one.
+ */
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+/** Reclaiming a lease is best effort. A read-only or hostile directory must not break startup. */
+function discard(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch { }
+}
+function parseLease(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const { pid, sessionId, startedAt, cwd } = value;
+    if (typeof pid !== "number" || typeof sessionId !== "string") {
+        return undefined;
+    }
+    if (typeof startedAt !== "string" || typeof cwd !== "string") {
+        return undefined;
+    }
+    return { pid, sessionId, startedAt, cwd };
+}
+/**
+ * Live leases for `cwd`, excluding this process. Dead and unreadable leases are deleted
+ * as they are found, so a crashed session never locks anyone out and repeated scans
+ * converge on the same answer.
+ */
+export function readLiveSessionLeases(sessionDir, cwd) {
+    const dir = leaseDir(sessionDir);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const live = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".json")) {
+            continue;
+        }
+        const path = join(dir, entry);
+        let lease;
+        try {
+            lease = parseLease(readFileSync(path, "utf-8"));
+        }
+        catch {
+            lease = undefined;
+        }
+        if (!lease || !isProcessAlive(lease.pid)) {
+            discard(path);
+            continue;
+        }
+        if (lease.pid === process.pid || lease.cwd !== cwd) {
+            continue;
+        }
+        live.push(lease);
+    }
+    return live.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+}
+/**
+ * Publish this process's lease. Failing to write one is never fatal: the lease is an
+ * advisory signal to the next session, not something this session depends on.
+ */
+export function acquireSessionLease(sessionDir, cwd, sessionId) {
+    const path = leasePath(sessionDir, process.pid);
+    const lease = {
+        pid: process.pid,
+        sessionId,
+        startedAt: new Date().toISOString(),
+        cwd,
+    };
+    try {
+        mkdirSync(leaseDir(sessionDir), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(lease, null, 2)}\n`, "utf-8");
+    }
+    catch {
+        return { release: () => { } };
+    }
+    let released = false;
+    return {
+        release: () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            discard(path);
+        },
+    };
+}
+export function describeSessionLease(lease) {
+    const started = new Date(lease.startedAt);
+    const when = Number.isNaN(started.getTime()) ? lease.startedAt : started.toLocaleTimeString();
+    return `pid ${lease.pid}, started ${when}, session ${lease.sessionId.slice(0, 8)}`;
+}
+//# sourceMappingURL=session-lease.js.map

package/dist/core/session-lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lease.js","sourceRoot":"","sources":["../../src/core/session-lease.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Liveness records for sessions sharing one working directory.\n *\n * Two Apex Code sessions in the same working tree overwrite each other's edits and\n * commits, and neither one can tell. Each process publishes its own lease file rather\n * than sharing one, so nothing here takes a lock and the startup path stays free of\n * `proper-lockfile`.\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\nexport interface SessionLease {\n\tpid: number;\n\tsessionId: string;\n\t/** ISO 8601. */\n\tstartedAt: string;\n\tcwd: string;\n}\n\nexport interface SessionLeaseHandle {\n\trelease(): void;\n}\n\nconst LEASE_DIR_NAME = \"leases\";\n\nfunction leaseDir(sessionDir: string): string {\n\treturn join(sessionDir, LEASE_DIR_NAME);\n}\n\nfunction leasePath(sessionDir: string, pid: number): string {\n\treturn join(leaseDir(sessionDir), `${pid}.json`);\n}\n\n/**\n * Only ESRCH proves the process is gone. EPERM means it exists under another user, and\n * anything else means the probe itself failed, so treat both as alive: a session we\n * cannot rule out is worth warning about, and `--allow-concurrent` clears a false one.\n */\nfunction isProcessAlive(pid: number): boolean {\n\tif (!Number.isInteger(pid) || pid <= 0) {\n\t\treturn false;\n\t}\n\ttry {\n\t\tprocess.kill(pid, 0);\n\t\treturn true;\n\t} catch (error) {\n\t\treturn (error as NodeJS.ErrnoException).code !== \"ESRCH\";\n\t}\n}\n\n/** Reclaiming a lease is best effort. A read-only or hostile directory must not break startup. */\nfunction discard(path: string): void {\n\ttry {\n\t\trmSync(path, { force: true });\n\t} catch {}\n}\n\nfunction parseLease(raw: string): SessionLease | undefined {\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(raw);\n\t} catch {\n\t\treturn undefined;\n\t}\n\tif (typeof value !== \"object\" || value === null) {\n\t\treturn undefined;\n\t}\n\tconst { pid, sessionId, startedAt, cwd } = value as Record<string, unknown>;\n\tif (typeof pid !== \"number\" || typeof sessionId !== \"string\") {\n\t\treturn undefined;\n\t}\n\tif (typeof startedAt !== \"string\" || typeof cwd !== \"string\") {\n\t\treturn undefined;\n\t}\n\treturn { pid, sessionId, startedAt, cwd };\n}\n\n/**\n * Live leases for `cwd`, excluding this process. Dead and unreadable leases are deleted\n * as they are found, so a crashed session never locks anyone out and repeated scans\n * converge on the same answer.\n */\nexport function readLiveSessionLeases(sessionDir: string, cwd: string): SessionLease[] {\n\tconst dir = leaseDir(sessionDir);\n\tif (!existsSync(dir)) {\n\t\treturn [];\n\t}\n\n\tlet entries: string[];\n\ttry {\n\t\tentries = readdirSync(dir);\n\t} catch {\n\t\treturn [];\n\t}\n\n\tconst live: SessionLease[] = [];\n\tfor (const entry of entries) {\n\t\tif (!entry.endsWith(\".json\")) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst path = join(dir, entry);\n\t\tlet lease: SessionLease | undefined;\n\t\ttry {\n\t\t\tlease = parseLease(readFileSync(path, \"utf-8\"));\n\t\t} catch {\n\t\t\tlease = undefined;\n\t\t}\n\n\t\tif (!lease || !isProcessAlive(lease.pid)) {\n\t\t\tdiscard(path);\n\t\t\tcontinue;\n\t\t}\n\t\tif (lease.pid === process.pid || lease.cwd !== cwd) {\n\t\t\tcontinue;\n\t\t}\n\t\tlive.push(lease);\n\t}\n\n\treturn live.sort((a, b) => a.startedAt.localeCompare(b.startedAt));\n}\n\n/**\n * Publish this process's lease. Failing to write one is never fatal: the lease is an\n * advisory signal to the next session, not something this session depends on.\n */\nexport function acquireSessionLease(sessionDir: string, cwd: string, sessionId: string): SessionLeaseHandle {\n\tconst path = leasePath(sessionDir, process.pid);\n\tconst lease: SessionLease = {\n\t\tpid: process.pid,\n\t\tsessionId,\n\t\tstartedAt: new Date().toISOString(),\n\t\tcwd,\n\t};\n\n\ttry {\n\t\tmkdirSync(leaseDir(sessionDir), { recursive: true });\n\t\twriteFileSync(path, `${JSON.stringify(lease, null, 2)}\\n`, \"utf-8\");\n\t} catch {\n\t\treturn { release: () => {} };\n\t}\n\n\tlet released = false;\n\treturn {\n\t\trelease: () => {\n\t\t\tif (released) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\treleased = true;\n\t\t\tdiscard(path);\n\t\t},\n\t};\n}\n\nexport function describeSessionLease(lease: SessionLease): string {\n\tconst started = new Date(lease.startedAt);\n\tconst when = Number.isNaN(started.getTime()) ? lease.startedAt : started.toLocaleTimeString();\n\treturn `pid ${lease.pid}, started ${when}, session ${lease.sessionId.slice(0, 8)}`;\n}\n"]}

package/dist/core/session-manager.d.ts

@@ -1,6 +1,8 @@
 import { type ImageContent, type Message, type TextContent, type Usage } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "apex-code-agent-core";
 import { type BashExecutionMessage, type CustomMessage } from "./messages.ts";
+import type { EvidenceCaptureDiagnostic, EvidenceRecord } from "./tools/contract.ts";
+import type { TodoItem } from "./tools/todo-write.ts";
 export declare const CURRENT_SESSION_VERSION = 3;
 export interface SessionHeader {
     type: "session";
@@ -9,10 +11,13 @@ export interface SessionHeader {
     timestamp: string;
     cwd: string;
     parentSession?: string;
+    /** Recursion depth for delegation (roadmap Phase 5, task 5.3). Absent means 0 -- every session written before this field existed reads as a non-delegated root, additive per contracts.md §3. */
+    delegationDepth?: number;
 }
 export interface NewSessionOptions {
     id?: string;
     parentSession?: string;
+    delegationDepth?: number;
 }
 export interface SessionEntryBase {
     type: string;
@@ -82,6 +87,24 @@ export interface SessionInfoEntry extends SessionEntryBase {
     type: "session_info";
     name?: string;
 }
+/** Additive, bounded source-level evidence. See ADR 0007. */
+export interface DurableEvidenceRecord {
+    id: string;
+    sessionId: string;
+    toolName: string;
+    timestamp: string;
+    facts: EvidenceRecord;
+}
+export interface EvidenceEntry extends SessionEntryBase {
+    type: "evidence";
+    toolName: string;
+    records: DurableEvidenceRecord[];
+}
+/** Additive diagnostic for an evidence-capture failure; it is not a verification verdict. */
+export interface EvidenceDiagnosticEntry extends SessionEntryBase {
+    type: "evidence_diagnostic";
+    diagnostic: EvidenceCaptureDiagnostic;
+}
 /**
  * Custom message entry for extensions to inject messages into LLM context.
  * Use customType to identify your extension's entries.
@@ -102,7 +125,7 @@ export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
     display: boolean;
 }
 /** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
-export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry;
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry | EvidenceEntry | EvidenceDiagnosticEntry;
 /** Raw file entry (includes header) */
 export type FileEntry = SessionHeader | SessionEntry;
 /** Tree node for getTree() - defensive copy of session structure */
@@ -137,13 +160,21 @@ export interface SessionInfo {
     firstMessage: string;
     allMessagesText: string;
 }
-export type ReadonlySessionManager = Pick<SessionManager, "getCwd" | "getSessionDir" | "getSessionId" | "getSessionFile" | "getLeafId" | "getLeafEntry" | "getEntry" | "getLabel" | "getBranch" | "buildContextEntries" | "getHeader" | "getEntries" | "getTree" | "getSessionName">;
+export type ReadonlySessionManager = Pick<SessionManager, "getCwd" | "getSessionDir" | "getSessionId" | "getSessionFile" | "getLeafId" | "getLeafEntry" | "getEntry" | "getLabel" | "getBranch" | "buildContextEntries" | "getHeader" | "getEntries" | "getEntriesVersion" | "getTree" | "getSessionName" | "getEvidenceRecords">;
 export declare function assertValidSessionId(id: string): void;
 /** Exported for testing */
 export declare function migrateSessionEntries(entries: FileEntry[]): void;
 /** Exported for compaction.test.ts */
 export declare function parseSessionEntries(content: string): FileEntry[];
 export declare function getLatestCompactionEntry(entries: SessionEntry[]): CompactionEntry | null;
+/** customType used for `todo_write`'s session-facing state (task 4.3). */
+export declare const TODO_CUSTOM_ENTRY_TYPE = "todo";
+/**
+ * The task list is a full-replace snapshot, not a delta log: the latest `todo`
+ * custom entry is the entire current list, so reading it back is just finding that
+ * one entry, mirroring `getSessionName`'s "walk backward for the latest marker".
+ */
+export declare function getLatestTodos(entries: SessionEntry[]): TodoItem[];
 /**
  * Project one selected session entry into LLM/runtime messages.
  * Plain custom entries are display/state entries and do not participate in context.
@@ -164,6 +195,11 @@ export declare function buildContextEntries(entries: SessionEntry[], leafId?: st
  * Handles compaction and branch summaries along the path.
  */
 export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>): SessionContext;
+/**
+ * Compute the default session directory for a cwd.
+ * Encodes cwd into a safe directory name under ~/.apex-code/agent/sessions/.
+ */
+export declare function getDefaultSessionDirPath(cwd: string, agentDir?: string): string;
 export declare function getDefaultSessionDir(cwd: string, agentDir?: string): string;
 /** Exported for testing */
 export declare function loadEntriesFromFile(filePath: string): FileEntry[];
@@ -189,6 +225,12 @@ export declare class SessionManager {
     private persist;
     private flushed;
     private fileEntries;
+    /**
+     * Bumped on every change to fileEntries. O(1) staleness check for callers
+     * that walk all entries per frame (the footer's usage totals) and would
+     * otherwise re-copy the whole list on every render.
+     */
+    private entriesVersion;
     private byId;
     private labelsById;
     private labelTimestampsById;
@@ -223,6 +265,10 @@ export declare class SessionManager {
     appendCompaction<T = unknown>(summary: string, firstKeptEntryId: string, tokensBefore: number, details?: T, fromHook?: boolean, usage?: Usage): string;
     /** Append a custom entry (for extensions) as child of current leaf, then advance leaf. Returns entry id. */
     appendCustomEntry(customType: string, data?: unknown): string;
+    /** Append source-level evidence as an additive entry. See ADR 0007. */
+    appendEvidence(toolName: string, records: EvidenceRecord[]): string;
+    /** Record a non-fatal evidence-capture diagnostic without claiming tool success or failure. */
+    appendEvidenceDiagnostic(diagnostic: EvidenceCaptureDiagnostic): string;
     /** Append a session info entry (e.g., display name). Returns entry id. */
     appendSessionInfo(name: string): string;
     /** Get the current session name from the latest session_info entry, if any. */
@@ -239,6 +285,8 @@ export declare class SessionManager {
     getLeafId(): string | null;
     getLeafEntry(): SessionEntry | undefined;
     getEntry(id: string): SessionEntry | undefined;
+    /** Read durable evidence without exposing a mutation path to policy consumers. */
+    getEvidenceRecords(): readonly DurableEvidenceRecord[];
     /**
      * Get all direct children of an entry.
      */
@@ -273,12 +321,20 @@ export declare class SessionManager {
      * Get session header.
      */
     getHeader(): SessionHeader | null;
+    /** This session's delegation recursion depth (roadmap Phase 5, task 5.3). Absent field reads as 0 -- a non-delegated root, including every session written before this field existed. */
+    getDelegationDepth(): number;
     /**
      * Get all session entries (excludes header). Returns a shallow copy.
      * The session is append-only: use appendXXX() to add entries, branch() to
      * change the leaf pointer. Entries cannot be modified or deleted.
      */
     getEntries(): SessionEntry[];
+    /**
+     * Monotonic counter bumped on every change to the entry list. Compare
+     * across frames to detect new/removed entries without calling
+     * getEntries() (which copies the whole list).
+     */
+    getEntriesVersion(): number;
     /**
      * Get the session as a tree structure. Returns a shallow defensive copy of all entries.
      * A well-formed session has exactly one root (first entry with parentId === null).