akemon 0.3.5 → 0.3.7

package/dist/software-agent-peripheral.js

@@ -11,13 +11,17 @@
  * transport to app-server or a true persistent interactive session.
  */
 import { randomUUID } from "crypto";
-import { spawn, spawnSync } from "child_process";
+import { spawnSync } from "child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { isAbsolute, join, relative, resolve as resolvePath } from "path";
-import { StringDecoder } from "string_decoder";
 import { SIG, sig } from "./types.js";
 import { sendTaskEnd, sendTaskStart, sendTaskStream } from "./relay-client.js";
-import { redactSecrets, StreamingRedactor } from "./redaction.js";
+import { redactSecrets } from "./redaction.js";
+import { terminateProcessTree } from "./runtime-platform.js";
+import { actorRef } from "./akemon-message.js";
+import { appendPermissionAuditRecordSync } from "./permission-audit.js";
+import { logBestEffortError } from "./best-effort.js";
+import { CodexExecTransport, } from "./software-agent-transport.js";
 const defaultTaskRelay = {
     sendTaskStart,
     sendTaskStream,
@@ -78,12 +82,19 @@ export class CodexSoftwareAgentPeripheral {
     activeTaskId = null;
     activeWorkdir = null;
     sessionId = randomUUID();
+    transport;
     constructor(config) {
         this.config = {
             ...config,
             envPolicy: normalizeSoftwareAgentEnvPolicy(config.envPolicy),
             envAllowlist: normalizeSoftwareAgentEnvAllowlist(config.envAllowlist),
         };
+        this.transport = config.transport || new CodexExecTransport({
+            command: config.command || "codex",
+            model: config.model,
+            sandbox: config.sandbox || "workspace-write",
+            spawnImpl: config.spawnImpl,
+        });
         this.id = config.id || "software-agent:codex";
         this.name = config.name || "Codex CLI Software Agent";
     }
@@ -103,18 +114,9 @@ export class CodexSoftwareAgentPeripheral {
     async resetSession() {
         const activePid = this.activeChild?.pid;
         if (activePid) {
-            const processGroupId = -activePid;
-            try {
-                process.kill(processGroupId, "SIGTERM");
-            }
-            catch { }
-            setTimeout(() => {
-                try {
-                    process.kill(processGroupId, "SIGKILL");
-                }
-                catch { }
-            }, 3000).unref();
+            terminateProcessTree(activePid, { signal: "SIGTERM", forceAfterMs: 3000 });
         }
+        await this.transport.reset?.();
         this.activeChild = null;
         this.activeTaskId = null;
         this.activeWorkdir = null;
@@ -127,12 +129,14 @@ export class CodexSoftwareAgentPeripheral {
             sessionId: this.sessionId,
             activeTaskId: this.activeTaskId,
             activeWorkdir: this.activeWorkdir,
-            busy: !!this.activeChild,
-            transport: "codex-exec",
+            busy: !!this.activeTaskId || !!this.activeChild,
+            transport: this.transport.kind,
+            transportContract: this.transport.describe(currentWorkdir),
             baseWorkdir: resolvePath(this.config.workdir),
             workdirStatus: this.collectWorkdirStatus(currentWorkdir),
             taskLedgerDir: this.config.taskLedgerDir,
             contextSessionDir: this.config.contextSessionDir,
+            workMemoryDir: this.config.workMemoryDir,
             environment: buildSoftwareAgentChildEnvironment({
                 policy: this.config.envPolicy,
                 allowlist: this.config.envAllowlist,
@@ -154,7 +158,17 @@ export class CodexSoftwareAgentPeripheral {
         return sig(SIG.SOFTWARE_AGENT_RESPONSE, { ...result }, this.id);
     }
     async sendTask(envelope, taskOptions) {
-        if (this.activeChild) {
+        if (this.activeTaskId || this.activeChild) {
+            this.writePermissionAudit({
+                envelope,
+                taskId: envelope.taskId,
+                workdir: envelope.workdir || this.config.workdir,
+                decision: {
+                    result: "denied",
+                    mode: "automatic",
+                    reason: `Software agent busy (task=${this.activeTaskId})`,
+                },
+            });
             throw new Error(`Software agent busy (task=${this.activeTaskId})`);
         }
         const { signal, observer } = normalizeSoftwareAgentTaskOptions(taskOptions);
@@ -162,7 +176,14 @@ export class CodexSoftwareAgentPeripheral {
         const contextSessionId = normalizeContextSessionId(envelope.contextSessionId) || taskId;
         const workdirSafety = resolveWorkdirSafety(this.config.workdir, envelope.workdir || this.config.workdir, envelope.workdirSafety?.allowOutsideWorkdir || false);
         const workdir = workdirSafety.effectiveWorkdir;
-        let effectiveEnvelope = { ...envelope, taskId, contextSessionId, workdir, workdirSafety };
+        let effectiveEnvelope = {
+            ...envelope,
+            taskId,
+            contextSessionId,
+            workdir,
+            workdirSafety,
+            workMemoryDir: envelope.workMemoryDir || this.config.workMemoryDir,
+        };
         const contextSession = this.config.contextSessionDir
             ? writeSoftwareAgentContextPacket(this.config.contextSessionDir, effectiveEnvelope)
             : undefined;
@@ -171,30 +192,42 @@ export class CodexSoftwareAgentPeripheral {
         const prompt = contextSession
             ? buildContextPacketLaunchPrompt(effectiveEnvelope, contextSession.audit.packetPath)
             : buildTaskEnvelopePrompt(effectiveEnvelope);
-        const { cmd, args } = buildCodexExecCommand({
-            command: this.config.command || "codex",
-            workdir,
-            model: this.config.model,
-            sandbox: this.config.sandbox || "workspace-write",
-        });
+        const transportDescriptor = this.transport.describe(workdir);
         const startedAt = Date.now();
         const startedAtIso = new Date(startedAt).toISOString();
         const relay = this.config.taskRelay || defaultTaskRelay;
-        const commandLine = [cmd, ...args].join(" ");
-        const spawnImpl = this.config.spawnImpl || spawn;
+        const commandLine = transportDescriptor.commandLine;
         const timeoutMs = envelope.timeoutMs || this.config.defaultTimeoutMs || DEFAULT_TIMEOUT_MS;
         const workdirStatus = this.collectWorkdirStatus(workdir);
+        const taskMetadata = {
+            contextSessionId: effectiveEnvelope.contextSessionId,
+            contextPacketPath: effectiveEnvelope.contextPacketPath,
+            workMemoryDir: effectiveEnvelope.workMemoryDir,
+        };
         const childEnvironment = buildSoftwareAgentChildEnvironment({
             policy: this.config.envPolicy,
             allowlist: this.config.envAllowlist,
             sourceEnv: this.config.sourceEnv,
         });
+        this.writePermissionAudit({
+            envelope: effectiveEnvelope,
+            taskId,
+            workdir,
+            workdirSafety,
+            commandLine,
+            environment: childEnvironment.audit,
+            decision: {
+                result: "allowed",
+                mode: "owner-approved",
+                reason: "Owner local endpoint accepted the software-agent task envelope.",
+            },
+        });
         const baseTaskRecord = () => ({
             schemaVersion: 1,
             taskId,
             agentId: this.id,
             sessionId: this.sessionId,
-            transport: "codex-exec",
+            transport: this.transport.kind,
             commandLine,
             envelope: effectiveEnvelope,
             startedAt: startedAtIso,
@@ -202,197 +235,103 @@ export class CodexSoftwareAgentPeripheral {
             contextSession: contextSession?.audit,
             workdirStatus,
         });
-        return new Promise((resolve) => {
-            this.activeTaskId = taskId;
-            this.activeWorkdir = workdir;
-            this.writeTaskRecord({
-                ...baseTaskRecord(),
-                status: "running",
-                updatedAt: startedAtIso,
+        this.activeTaskId = taskId;
+        this.activeWorkdir = workdir;
+        this.writeTaskRecord({
+            ...baseTaskRecord(),
+            status: "running",
+            updatedAt: startedAtIso,
+        });
+        const origin = "software_agent";
+        relay.sendTaskStart(taskId, origin, commandLine);
+        observer?.onStart?.({ taskId, origin, commandLine, ...taskMetadata });
+        this.bus?.emit(SIG.TASK_STARTED, sig(SIG.TASK_STARTED, {
+            taskId,
+            taskType: "software_agent",
+            description: effectiveEnvelope.goal,
+            peripheral: this.id,
+            sessionId: this.sessionId,
+        }, this.id));
+        let transportResult;
+        try {
+            transportResult = await this.transport.run({
+                taskId,
+                prompt,
+                workdir,
+                env: childEnvironment.env,
+                timeoutMs,
+                signal,
+                startedAt,
+                onStream: (event) => {
+                    relay.sendTaskStream(event.taskId, event.stream, event.chunk);
+                    observer?.onStream?.(event);
+                },
+                onProcessStart: (child) => {
+                    this.activeChild = child;
+                },
+                onProcessEnd: (child) => {
+                    if (this.activeChild === child)
+                        this.activeChild = null;
+                },
             });
-            const origin = "software_agent";
-            relay.sendTaskStart(taskId, origin, commandLine);
-            observer?.onStart?.({ taskId, origin, commandLine });
-            this.bus?.emit(SIG.TASK_STARTED, sig(SIG.TASK_STARTED, {
+        }
+        catch (err) {
+            transportResult = {
                 taskId,
-                taskType: "software_agent",
-                description: effectiveEnvelope.goal,
-                peripheral: this.id,
-                sessionId: this.sessionId,
-            }, this.id));
-            let child;
-            try {
-                child = spawnImpl(cmd, args, {
-                    cwd: workdir,
-                    env: childEnvironment.env,
-                    stdio: ["pipe", "pipe", "pipe"],
-                    detached: true,
-                });
-            }
-            catch (err) {
-                this.activeChild = null;
-                this.activeTaskId = null;
-                this.activeWorkdir = null;
-                const durationMs = Date.now() - startedAt;
-                const result = {
-                    success: false,
-                    taskId,
-                    output: "",
-                    error: err.message || String(err),
-                    exitCode: null,
-                    durationMs,
-                };
-                relay.sendTaskEnd(taskId, null, durationMs);
-                observer?.onEnd?.({ taskId, exitCode: null, durationMs, result: redactSecrets(result) });
-                const completedAt = new Date().toISOString();
-                this.writeTaskRecord({
-                    ...baseTaskRecord(),
-                    status: "failed",
-                    updatedAt: completedAt,
-                    completedAt,
-                    durationMs,
-                    result,
-                    stdoutSummary: summarizeText(""),
-                    stderrSummary: summarizeText(result.error || ""),
-                });
-                if (contextSession) {
-                    writeSoftwareAgentContextSessionState(contextSession.audit.statePath, effectiveEnvelope, result, completedAt);
-                }
-                this.bus?.emit(SIG.TASK_FAILED, sig(SIG.TASK_FAILED, result, this.id));
-                resolve(result);
-                return;
-            }
-            this.activeChild = child;
-            let stdout = "";
-            let stderr = "";
-            let finished = false;
-            let aborted = false;
-            const outDecoder = new StringDecoder("utf8");
-            const errDecoder = new StringDecoder("utf8");
-            const outRedactor = new StreamingRedactor();
-            const errRedactor = new StreamingRedactor();
-            const emitSafeStream = (stream, text) => {
-                if (!text)
-                    return;
-                relay.sendTaskStream(taskId, stream, text);
-                observer?.onStream?.({ taskId, stream, chunk: text });
-            };
-            const finish = (exitCode, error) => {
-                if (finished)
-                    return;
-                finished = true;
-                signal?.removeEventListener("abort", onAbort);
-                clearTimeout(timer);
-                const tailOut = outDecoder.end();
-                const tailErr = errDecoder.end();
-                if (tailOut) {
-                    stdout += tailOut;
-                    emitSafeStream("stdout", outRedactor.push(tailOut));
-                }
-                if (tailErr) {
-                    stderr += tailErr;
-                    emitSafeStream("stderr", errRedactor.push(tailErr));
-                }
-                emitSafeStream("stdout", outRedactor.flush());
-                emitSafeStream("stderr", errRedactor.flush());
-                const durationMs = Date.now() - startedAt;
-                this.activeChild = null;
-                this.activeTaskId = null;
-                this.activeWorkdir = null;
-                const output = stdout.trim() || stderr.trim();
-                const success = !error && !aborted && exitCode === 0;
-                const result = {
-                    success,
-                    taskId,
-                    output,
-                    error: success ? undefined : error || stderr.trim() || `codex exited with code ${exitCode}`,
-                    exitCode,
-                    durationMs,
-                };
-                relay.sendTaskEnd(taskId, exitCode, durationMs);
-                observer?.onEnd?.({ taskId, exitCode, durationMs, result: redactSecrets(result) });
-                const completedAt = new Date().toISOString();
-                this.writeTaskRecord({
-                    ...baseTaskRecord(),
-                    status: success ? "completed" : "failed",
-                    updatedAt: completedAt,
-                    completedAt,
-                    durationMs,
-                    result,
-                    stdoutSummary: summarizeText(stdout),
-                    stderrSummary: summarizeText(stderr),
-                });
-                if (contextSession) {
-                    writeSoftwareAgentContextSessionState(contextSession.audit.statePath, effectiveEnvelope, result, completedAt);
-                }
-                this.bus?.emit(success ? SIG.TASK_COMPLETED : SIG.TASK_FAILED, sig(success ? SIG.TASK_COMPLETED : SIG.TASK_FAILED, {
-                    ...result,
-                    taskLabel: `software_agent:${this.id}`,
-                }, this.id));
-                resolve(result);
-            };
-            const onAbort = () => {
-                if (aborted || !child.pid)
-                    return;
-                aborted = true;
-                try {
-                    process.kill(-child.pid, "SIGTERM");
-                }
-                catch { }
-                setTimeout(() => {
-                    try {
-                        process.kill(-child.pid, "SIGKILL");
-                    }
-                    catch { }
-                }, 3000).unref();
+                stdout: "",
+                stderr: "",
+                error: err.message || String(err),
+                exitCode: null,
+                durationMs: Date.now() - startedAt,
+                aborted: false,
+                success: false,
             };
-            const timer = setTimeout(() => {
-                if (!child.pid)
-                    return;
-                aborted = true;
-                try {
-                    process.kill(-child.pid, "SIGTERM");
-                }
-                catch { }
-                setTimeout(() => {
-                    try {
-                        process.kill(-child.pid, "SIGKILL");
-                    }
-                    catch { }
-                }, 3000).unref();
-            }, timeoutMs);
-            if (signal) {
-                if (signal.aborted)
-                    onAbort();
-                else
-                    signal.addEventListener("abort", onAbort, { once: true });
-            }
-            child.stdin?.on("error", () => { });
-            child.stdin?.write(prompt);
-            child.stdin?.end();
-            child.stdout?.on("data", (chunk) => {
-                const text = outDecoder.write(chunk);
-                if (!text)
-                    return;
-                stdout += text;
-                emitSafeStream("stdout", outRedactor.push(text));
-            });
-            child.stderr?.on("data", (chunk) => {
-                const text = errDecoder.write(chunk);
-                if (!text)
-                    return;
-                stderr += text;
-                emitSafeStream("stderr", errRedactor.push(text));
-            });
-            child.on("close", (code) => {
-                child.unref();
-                finish(code);
-            });
-            child.on("error", (err) => {
-                child.unref();
-                finish(null, err.message);
-            });
+        }
+        finally {
+            this.activeChild = null;
+            this.activeTaskId = null;
+            this.activeWorkdir = null;
+        }
+        const output = transportResult.stdout.trim() || transportResult.stderr.trim();
+        const transportLabel = this.transport.kind === "codex-exec" ? "codex" : this.transport.kind;
+        const result = {
+            success: transportResult.success,
+            taskId,
+            output,
+            error: transportResult.success
+                ? undefined
+                : transportResult.error || transportResult.stderr.trim() || `${transportLabel} exited with code ${transportResult.exitCode}`,
+            exitCode: transportResult.exitCode,
+            durationMs: transportResult.durationMs,
+            ...taskMetadata,
+        };
+        relay.sendTaskEnd(taskId, transportResult.exitCode, transportResult.durationMs);
+        observer?.onEnd?.({
+            taskId,
+            exitCode: transportResult.exitCode,
+            durationMs: transportResult.durationMs,
+            result: redactSecrets(result),
+            ...taskMetadata,
+        });
+        const completedAt = new Date().toISOString();
+        this.writeTaskRecord({
+            ...baseTaskRecord(),
+            status: result.success ? "completed" : "failed",
+            updatedAt: completedAt,
+            completedAt,
+            durationMs: transportResult.durationMs,
+            result,
+            stdoutSummary: summarizeText(transportResult.stdout),
+            stderrSummary: summarizeText(transportResult.stderr || result.error || ""),
         });
+        if (contextSession) {
+            writeSoftwareAgentContextSessionState(contextSession.audit.statePath, effectiveEnvelope, result, completedAt);
+        }
+        this.bus?.emit(result.success ? SIG.TASK_COMPLETED : SIG.TASK_FAILED, sig(result.success ? SIG.TASK_COMPLETED : SIG.TASK_FAILED, {
+            ...result,
+            taskLabel: `software_agent:${this.id}`,
+        }, this.id));
+        return result;
     }
     writeTaskRecord(record) {
         const dir = this.config.taskLedgerDir;
@@ -400,14 +339,54 @@ export class CodexSoftwareAgentPeripheral {
             return;
         try {
             mkdirSync(dir, { recursive: true });
-            const safeTaskId = safeTaskFilename(record.taskId);
-            writeFileSync(join(dir, `${safeTaskId}.json`), `${JSON.stringify(redactSecrets(record), null, 2)}\n`);
+            writeFileSync(softwareAgentTaskRecordPath(dir, record.taskId), `${JSON.stringify(redactSecrets(record), null, 2)}\n`);
             pruneSoftwareAgentTaskRecords(dir, this.config.taskLedgerMaxRecords, record.taskId);
         }
         catch (err) {
             console.error(`[software-agent] Failed to write task ledger: ${err.message || String(err)}`);
         }
     }
+    writePermissionAudit(input) {
+        if (!this.config.agentName)
+            return;
+        try {
+            const requesterKind = input.envelope.sourceModule === "owner-http" ? "owner" : "system";
+            appendPermissionAuditRecordSync(this.config.agentName, {
+                actionKind: "software-agent-task",
+                action: "software-agent.run",
+                requestedBy: actorRef(requesterKind, input.envelope.sourceModule || "owner", "local"),
+                performedBy: actorRef("agent", this.config.agentName, "software-agent"),
+                target: actorRef("external", this.id, "software-agent"),
+                sourceModule: input.envelope.sourceModule,
+                peripheralId: this.id,
+                riskLevel: input.envelope.riskLevel,
+                roleScope: input.envelope.roleScope,
+                memoryScope: input.envelope.memoryScope,
+                workdir: input.workdir || input.envelope.workdir,
+                projectScope: input.workdirSafety
+                    ? (input.workdirSafety.outsideBaseWorkdir ? "outside-workdir" : "inside-workdir")
+                    : "unknown",
+                transport: "software-agent",
+                decision: input.decision,
+                allowedActions: input.envelope.allowedActions,
+                forbiddenActions: input.envelope.forbiddenActions,
+                references: {
+                    taskId: input.taskId || input.envelope.taskId,
+                    contextSessionId: input.envelope.contextSessionId,
+                    contextPacketPath: input.envelope.contextPacketPath,
+                },
+                metadata: {
+                    purpose: input.envelope.purpose,
+                    commandLine: input.commandLine,
+                    environment: input.environment,
+                    workMemoryDir: input.envelope.workMemoryDir,
+                },
+            });
+        }
+        catch (error) {
+            logBestEffortError("software-agent audit append", error);
+        }
+    }
     collectWorkdirStatus(workdir) {
         const impl = this.config.gitStatusImpl || readGitWorktreeStatus;
         return impl(workdir);
@@ -451,6 +430,9 @@ export function buildTaskEnvelopePrompt(envelope) {
         `Risk level: ${envelope.riskLevel}`,
         `Workdir: ${envelope.workdir}`,
     ];
+    if (envelope.workMemoryDir) {
+        lines.push(`Work memory directory: ${envelope.workMemoryDir}`);
+    }
     if (envelope.contextPacketPath) {
         lines.push(`Context packet path: ${envelope.contextPacketPath}`);
     }
@@ -472,6 +454,20 @@ export function buildTaskEnvelopePrompt(envelope) {
         lines.push(envelope.memorySummary.trim());
         lines.push("");
     }
+    if (envelope.workMemoryDir) {
+        lines.push("Work memory:");
+        lines.push("- This is user-owned working context for engineering/task continuity.");
+        lines.push("- You may read it with grep, direct file browsing, or semantic review as appropriate.");
+        lines.push("- You may update files under this directory when the task or user asks you to maintain work memory.");
+        lines.push("- Do not read or edit Akemon self memory as part of this software-agent task.");
+        lines.push("- For a quick append, use `akemon work-note \"<durable work memory>\" --source codex --kind note`.");
+        lines.push("");
+    }
+    if (envelope.workMemoryContext?.trim()) {
+        lines.push("Included work-memory context:");
+        lines.push(envelope.workMemoryContext.trim());
+        lines.push("");
+    }
     if (envelope.allowedActions?.length) {
         lines.push("Allowed actions:");
         for (const item of envelope.allowedActions)
@@ -492,7 +488,9 @@ export function buildTaskEnvelopePrompt(envelope) {
     lines.push("Instructions:");
     lines.push("- Treat this envelope as the complete Akemon-provided context for this task.");
     lines.push("- Do not attempt to read Akemon private memory outside the visible context above.");
+    lines.push("- Do not read or edit Akemon self memory unless the user explicitly names a normal file to inspect.");
     lines.push("- Work only in the stated workdir unless the envelope explicitly allows otherwise.");
+    lines.push("- If you learn durable work memory, update the work memory directory or use `akemon work-note`.");
     lines.push("- Report what changed, what you verified, and any remaining risk.");
     return lines.join("\n");
 }
@@ -504,6 +502,7 @@ export function buildContextPacketLaunchPrompt(envelope, contextPacketPath) {
         `Akemon context session: ${envelope.contextSessionId || "(one-shot)"}`,
         `Context packet: ${contextPacketPath}`,
         `Workdir: ${envelope.workdir}`,
+        `Work memory directory: ${envelope.workMemoryDir || "(not configured)"}`,
         "",
         "Goal:",
         envelope.goal,
@@ -512,7 +511,9 @@ export function buildContextPacketLaunchPrompt(envelope, contextPacketPath) {
         "- Read the context packet first before doing repository work.",
         "- Treat that file as the complete Akemon-provided context for this task.",
         "- Do not read Akemon private memory outside the context packet.",
+        "- Do not read or edit Akemon self memory unless the user explicitly names a normal file to inspect.",
         "- Work only in the stated workdir unless the packet explicitly allows otherwise.",
+        "- If you learn durable work memory, update the work memory directory or use `akemon work-note`.",
         "- Report what changed, what you verified, and any remaining risk.",
     ].join("\n");
 }
@@ -618,8 +619,9 @@ export function readGitWorktreeStatus(workdir) {
         };
     }
 }
-export function listSoftwareAgentTaskRecords(taskLedgerDir, limit = 20) {
+export function listSoftwareAgentTaskRecords(taskLedgerDir, limit = 20, opts = {}) {
     const safeLimit = normalizeTaskRecordLimit(limit);
+    const contextSessionId = opts.contextSessionId?.trim();
     try {
         if (!existsSync(taskLedgerDir))
             return [];
@@ -627,6 +629,7 @@ export function listSoftwareAgentTaskRecords(taskLedgerDir, limit = 20) {
             .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
             .map((entry) => readSoftwareAgentTaskRecordFile(join(taskLedgerDir, entry.name)))
             .filter((record) => !!record)
+            .filter((record) => !contextSessionId || record.contextSession?.sessionId === contextSessionId || record.envelope.contextSessionId === contextSessionId)
             .sort(compareSoftwareAgentTaskRecords)
             .slice(0, safeLimit);
     }
@@ -635,8 +638,66 @@ export function listSoftwareAgentTaskRecords(taskLedgerDir, limit = 20) {
     }
 }
 export function readSoftwareAgentTaskRecord(taskLedgerDir, taskId) {
-    const file = join(taskLedgerDir, `${safeTaskFilename(taskId)}.json`);
-    return readSoftwareAgentTaskRecordFile(file);
+    return readSoftwareAgentTaskRecordFile(softwareAgentTaskRecordPath(taskLedgerDir, taskId));
+}
+export function softwareAgentTaskRecordPath(taskLedgerDir, taskId) {
+    return join(taskLedgerDir, `${safeTaskFilename(taskId)}.json`);
+}
+export function listSoftwareAgentContextSessions(contextSessionDir, limit = 20) {
+    const safeLimit = normalizeTaskRecordLimit(limit);
+    try {
+        if (!existsSync(contextSessionDir))
+            return [];
+        return readdirSync(contextSessionDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => {
+            try {
+                return readSoftwareAgentContextSession(contextSessionDir, entry.name);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((record) => !!record)
+            .sort(compareSoftwareAgentContextSessions)
+            .slice(0, safeLimit);
+    }
+    catch {
+        return [];
+    }
+}
+export function readSoftwareAgentContextSession(contextSessionDir, sessionId, opts = {}) {
+    const safeSessionId = normalizeContextSessionId(sessionId, "sessionId");
+    if (!safeSessionId)
+        return null;
+    const sessionDir = join(contextSessionDir, safeSessionId);
+    if (!existsSync(sessionDir))
+        return null;
+    const packetPath = join(sessionDir, CONTEXT_PACKET_FILENAME);
+    const statePath = join(sessionDir, CONTEXT_SESSION_STATE_FILENAME);
+    const state = readSoftwareAgentContextSessionState(statePath);
+    const record = {
+        sessionId: safeSessionId,
+        packetPath,
+        statePath,
+        hasContextPacket: existsSync(packetPath),
+    };
+    if (state) {
+        record.updatedAt = state.updatedAt;
+        record.workMemoryDir = state.workMemoryDir;
+        record.lastTaskId = state.lastTaskId;
+        record.lastGoal = state.lastGoal;
+        record.lastResult = state.lastResult;
+    }
+    if (opts.includeContextPacket && record.hasContextPacket) {
+        try {
+            record.contextPacket = readFileSync(packetPath, "utf8");
+        }
+        catch {
+            record.contextPacket = "";
+        }
+    }
+    return record;
 }
 export function pruneSoftwareAgentTaskRecords(taskLedgerDir, maxRecords = DEFAULT_TASK_LEDGER_MAX_RECORDS, preserveTaskId) {
     const safeMaxRecords = normalizeTaskLedgerMaxRecords(maxRecords);
@@ -728,6 +789,7 @@ function writeSoftwareAgentContextSessionState(statePath, envelope, result, upda
             schemaVersion: 1,
             sessionId: envelope.contextSessionId,
             updatedAt,
+            workMemoryDir: envelope.workMemoryDir,
             lastTaskId: result.taskId,
             lastGoal: envelope.goal,
             lastResult: {
@@ -746,10 +808,8 @@ function writeSoftwareAgentContextSessionState(statePath, envelope, result, upda
 }
 function readSoftwareAgentContextSessionSummary(statePath) {
     try {
-        if (!existsSync(statePath))
-            return undefined;
-        const parsed = JSON.parse(readFileSync(statePath, "utf8"));
-        if (!parsed || parsed.schemaVersion !== 1 || !parsed.lastTaskId || !parsed.lastResult)
+        const parsed = readSoftwareAgentContextSessionState(statePath);
+        if (!parsed?.lastTaskId || !parsed.lastResult)
             return undefined;
         const result = parsed.lastResult;
         const status = result.success === true ? "completed" : "failed";
@@ -771,6 +831,31 @@ function readSoftwareAgentContextSessionSummary(statePath) {
         return undefined;
     }
 }
+function readSoftwareAgentContextSessionState(statePath) {
+    try {
+        if (!existsSync(statePath))
+            return null;
+        const parsed = JSON.parse(readFileSync(statePath, "utf8"));
+        if (!isSoftwareAgentContextSessionState(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function isSoftwareAgentContextSessionState(value) {
+    return value
+        && value.schemaVersion === 1
+        && typeof value.sessionId === "string"
+        && typeof value.updatedAt === "string"
+        && (value.workMemoryDir === undefined || typeof value.workMemoryDir === "string")
+        && typeof value.lastTaskId === "string"
+        && value.lastResult
+        && typeof value.lastResult.success === "boolean"
+        && (typeof value.lastResult.exitCode === "number" || value.lastResult.exitCode === null)
+        && typeof value.lastResult.durationMs === "number";
+}
 function readOptionalString(value, field) {
     if (value === undefined || value === null)
         return undefined;
@@ -933,16 +1018,10 @@ function compareSoftwareAgentTaskRecords(a, b) {
         return bTime - aTime;
     return b.taskId.localeCompare(a.taskId);
 }
-function buildCodexExecCommand(opts) {
-    const args = [
-        "exec",
-        "--skip-git-repo-check",
-        "--color", "never",
-        "-s", opts.sandbox,
-        "-C", opts.workdir,
-    ];
-    if (opts.model)
-        args.push("-m", opts.model);
-    args.push("-");
-    return { cmd: opts.command, args };
+function compareSoftwareAgentContextSessions(a, b) {
+    const bTime = Date.parse(b.updatedAt || "") || 0;
+    const aTime = Date.parse(a.updatedAt || "") || 0;
+    if (bTime !== aTime)
+        return bTime - aTime;
+    return b.sessionId.localeCompare(a.sessionId);
 }