akemon 0.3.4 → 0.3.6

package/dist/software-agent-peripheral.js

@@ -12,11 +12,12 @@
  */
 import { randomUUID } from "crypto";
 import { spawn, spawnSync } from "child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
+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";
 const defaultTaskRelay = {
     sendTaskStart,
     sendTaskStream,
@@ -34,7 +35,38 @@ const MEMORY_SCOPES = ["none", "public", "task", "owner"];
 const RISK_LEVELS = ["low", "medium", "high"];
 const MAX_STREAM_SUMMARY_CHARS = 12_000;
 const STREAM_SUMMARY_HEAD_CHARS = 4_000;
-const STREAM_SUMMARY_TAIL_CHARS = 8_000;
+const DEFAULT_TASK_LEDGER_MAX_RECORDS = 200;
+const CONTEXT_PACKET_FILENAME = "TASK_CONTEXT.md";
+const CONTEXT_SESSION_STATE_FILENAME = "SESSION.json";
+const MAX_CONTEXT_SESSION_ID_LENGTH = 120;
+const MAX_CONTEXT_SESSION_SUMMARY_CHARS = 4_000;
+const DEFAULT_SOFTWARE_AGENT_ENV_POLICY = "inherit";
+const DEFAULT_SOFTWARE_AGENT_ENV_ALLOWLIST = [
+    "PATH",
+    "HOME",
+    "SHELL",
+    "USER",
+    "LOGNAME",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TERM",
+    "COLORTERM",
+    "NO_COLOR",
+    "FORCE_COLOR",
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+    "OPENAI_ORG_ID",
+    "OPENAI_ORGANIZATION",
+    "OPENAI_PROJECT",
+    "OPENAI_MODEL",
+    "CODEX_HOME",
+    "CODEX_MODEL",
+    "CODEX_PROFILE",
+];
 export class CodexSoftwareAgentPeripheral {
     id;
     name;
@@ -47,7 +79,11 @@ export class CodexSoftwareAgentPeripheral {
     activeWorkdir = null;
     sessionId = randomUUID();
     constructor(config) {
-        this.config = config;
+        this.config = {
+            ...config,
+            envPolicy: normalizeSoftwareAgentEnvPolicy(config.envPolicy),
+            envAllowlist: normalizeSoftwareAgentEnvAllowlist(config.envAllowlist),
+        };
         this.id = config.id || "software-agent:codex";
         this.name = config.name || "Codex CLI Software Agent";
     }
@@ -65,14 +101,16 @@ export class CodexSoftwareAgentPeripheral {
             this.sessionId = randomUUID();
     }
     async resetSession() {
-        if (this.activeChild?.pid) {
+        const activePid = this.activeChild?.pid;
+        if (activePid) {
+            const processGroupId = -activePid;
             try {
-                process.kill(-this.activeChild.pid, "SIGTERM");
+                process.kill(processGroupId, "SIGTERM");
             }
             catch { }
             setTimeout(() => {
                 try {
-                    process.kill(-this.activeChild.pid, "SIGKILL");
+                    process.kill(processGroupId, "SIGKILL");
                 }
                 catch { }
             }, 3000).unref();
@@ -94,6 +132,13 @@ export class CodexSoftwareAgentPeripheral {
             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,
+                sourceEnv: this.config.sourceEnv,
+            }).audit,
         };
     }
     async send(signal) {
@@ -115,10 +160,25 @@ export class CodexSoftwareAgentPeripheral {
         }
         const { signal, observer } = normalizeSoftwareAgentTaskOptions(taskOptions);
         const taskId = envelope.taskId || `sw_${Date.now()}_${randomUUID().slice(0, 8)}`;
+        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;
-        const effectiveEnvelope = { ...envelope, taskId, workdir, workdirSafety };
-        const prompt = buildTaskEnvelopePrompt(effectiveEnvelope);
+        let effectiveEnvelope = {
+            ...envelope,
+            taskId,
+            contextSessionId,
+            workdir,
+            workdirSafety,
+            workMemoryDir: envelope.workMemoryDir || this.config.workMemoryDir,
+        };
+        const contextSession = this.config.contextSessionDir
+            ? writeSoftwareAgentContextPacket(this.config.contextSessionDir, effectiveEnvelope)
+            : undefined;
+        if (contextSession)
+            effectiveEnvelope = contextSession.envelope;
+        const prompt = contextSession
+            ? buildContextPacketLaunchPrompt(effectiveEnvelope, contextSession.audit.packetPath)
+            : buildTaskEnvelopePrompt(effectiveEnvelope);
         const { cmd, args } = buildCodexExecCommand({
             command: this.config.command || "codex",
             workdir,
@@ -132,6 +192,16 @@ export class CodexSoftwareAgentPeripheral {
         const spawnImpl = this.config.spawnImpl || spawn;
         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,
+        });
         const baseTaskRecord = () => ({
             schemaVersion: 1,
             taskId,
@@ -141,6 +211,8 @@ export class CodexSoftwareAgentPeripheral {
             commandLine,
             envelope: effectiveEnvelope,
             startedAt: startedAtIso,
+            environment: childEnvironment.audit,
+            contextSession: contextSession?.audit,
             workdirStatus,
         });
         return new Promise((resolve) => {
@@ -153,7 +225,7 @@ export class CodexSoftwareAgentPeripheral {
             });
             const origin = "software_agent";
             relay.sendTaskStart(taskId, origin, commandLine);
-            observer?.onStart?.({ taskId, origin, commandLine });
+            observer?.onStart?.({ taskId, origin, commandLine, ...taskMetadata });
             this.bus?.emit(SIG.TASK_STARTED, sig(SIG.TASK_STARTED, {
                 taskId,
                 taskType: "software_agent",
@@ -165,7 +237,7 @@ export class CodexSoftwareAgentPeripheral {
             try {
                 child = spawnImpl(cmd, args, {
                     cwd: workdir,
-                    env: process.env,
+                    env: childEnvironment.env,
                     stdio: ["pipe", "pipe", "pipe"],
                     detached: true,
                 });
@@ -182,9 +254,16 @@ export class CodexSoftwareAgentPeripheral {
                     error: err.message || String(err),
                     exitCode: null,
                     durationMs,
+                    ...taskMetadata,
                 };
                 relay.sendTaskEnd(taskId, null, durationMs);
-                observer?.onEnd?.({ taskId, exitCode: null, durationMs, result });
+                observer?.onEnd?.({
+                    taskId,
+                    exitCode: null,
+                    durationMs,
+                    result: redactSecrets(result),
+                    ...taskMetadata,
+                });
                 const completedAt = new Date().toISOString();
                 this.writeTaskRecord({
                     ...baseTaskRecord(),
@@ -196,6 +275,9 @@ export class CodexSoftwareAgentPeripheral {
                     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;
@@ -207,6 +289,14 @@ export class CodexSoftwareAgentPeripheral {
             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;
@@ -217,14 +307,14 @@ export class CodexSoftwareAgentPeripheral {
                 const tailErr = errDecoder.end();
                 if (tailOut) {
                     stdout += tailOut;
-                    relay.sendTaskStream(taskId, "stdout", tailOut);
-                    observer?.onStream?.({ taskId, stream: "stdout", chunk: tailOut });
+                    emitSafeStream("stdout", outRedactor.push(tailOut));
                 }
                 if (tailErr) {
                     stderr += tailErr;
-                    relay.sendTaskStream(taskId, "stderr", tailErr);
-                    observer?.onStream?.({ taskId, stream: "stderr", chunk: 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;
@@ -238,9 +328,16 @@ export class CodexSoftwareAgentPeripheral {
                     error: success ? undefined : error || stderr.trim() || `codex exited with code ${exitCode}`,
                     exitCode,
                     durationMs,
+                    ...taskMetadata,
                 };
                 relay.sendTaskEnd(taskId, exitCode, durationMs);
-                observer?.onEnd?.({ taskId, exitCode, durationMs, result });
+                observer?.onEnd?.({
+                    taskId,
+                    exitCode,
+                    durationMs,
+                    result: redactSecrets(result),
+                    ...taskMetadata,
+                });
                 const completedAt = new Date().toISOString();
                 this.writeTaskRecord({
                     ...baseTaskRecord(),
@@ -252,6 +349,9 @@ export class CodexSoftwareAgentPeripheral {
                     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}`,
@@ -302,16 +402,14 @@ export class CodexSoftwareAgentPeripheral {
                 if (!text)
                     return;
                 stdout += text;
-                relay.sendTaskStream(taskId, "stdout", text);
-                observer?.onStream?.({ taskId, stream: "stdout", chunk: text });
+                emitSafeStream("stdout", outRedactor.push(text));
             });
             child.stderr?.on("data", (chunk) => {
                 const text = errDecoder.write(chunk);
                 if (!text)
                     return;
                 stderr += text;
-                relay.sendTaskStream(taskId, "stderr", text);
-                observer?.onStream?.({ taskId, stream: "stderr", chunk: text });
+                emitSafeStream("stderr", errRedactor.push(text));
             });
             child.on("close", (code) => {
                 child.unref();
@@ -330,7 +428,8 @@ export class CodexSoftwareAgentPeripheral {
         try {
             mkdirSync(dir, { recursive: true });
             const safeTaskId = safeTaskFilename(record.taskId);
-            writeFileSync(join(dir, `${safeTaskId}.json`), `${JSON.stringify(record, null, 2)}\n`);
+            writeFileSync(join(dir, `${safeTaskId}.json`), `${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)}`);
@@ -371,6 +470,7 @@ export function buildTaskEnvelopePrompt(envelope) {
         "[Akemon Software Peripheral Task Envelope]",
         "",
         `Task ID: ${envelope.taskId || "(unspecified)"}`,
+        `Akemon context session: ${envelope.contextSessionId || "(one-shot)"}`,
         `Source module: ${envelope.sourceModule}`,
         `Purpose: ${envelope.purpose}`,
         `Role scope: ${envelope.roleScope}`,
@@ -378,6 +478,12 @@ 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}`);
+    }
     if (envelope.workdirSafety) {
         lines.push(`Base workdir: ${envelope.workdirSafety.baseWorkdir}`);
         lines.push(`Requested workdir: ${envelope.workdirSafety.requestedWorkdir}`);
@@ -386,11 +492,30 @@ export function buildTaskEnvelopePrompt(envelope) {
         lines.push(`Outside workdir explicitly allowed: ${envelope.workdirSafety.allowOutsideWorkdir ? "yes" : "no"}`);
     }
     lines.push("", "Goal:", envelope.goal, "");
+    if (envelope.previousTaskSummary?.trim()) {
+        lines.push("Previous task summary for this Akemon context session:");
+        lines.push(envelope.previousTaskSummary.trim());
+        lines.push("");
+    }
     if (envelope.memorySummary?.trim()) {
         lines.push("Visible Akemon memory/context:");
         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)
@@ -411,10 +536,35 @@ 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");
 }
+export function buildContextPacketLaunchPrompt(envelope, contextPacketPath) {
+    return [
+        "[Akemon Software Peripheral Task]",
+        "",
+        `Task ID: ${envelope.taskId || "(unspecified)"}`,
+        `Akemon context session: ${envelope.contextSessionId || "(one-shot)"}`,
+        `Context packet: ${contextPacketPath}`,
+        `Workdir: ${envelope.workdir}`,
+        `Work memory directory: ${envelope.workMemoryDir || "(not configured)"}`,
+        "",
+        "Goal:",
+        envelope.goal,
+        "",
+        "Instructions:",
+        "- 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");
+}
 export function createOwnerTaskEnvelope(body, defaultWorkdir) {
     const goal = typeof body?.goal === "string" ? body.goal.trim() : "";
     if (!goal)
@@ -437,6 +587,7 @@ export function createOwnerTaskEnvelope(body, defaultWorkdir) {
             : [...DEFAULT_OWNER_ALLOWED_ACTIONS],
         forbiddenActions: [...new Set([...DEFAULT_OWNER_FORBIDDEN_ACTIONS, ...callerForbiddenActions])],
         memorySummary: typeof body?.memorySummary === "string" ? body.memorySummary : "",
+        contextSessionId: readOptionalContextSessionId(body?.contextSessionId ?? body?.sessionId, "contextSessionId"),
         deliverable: typeof body?.deliverable === "string"
             ? body.deliverable
             : "Return a concise engineering summary with changes, verification, and remaining risks.",
@@ -516,8 +667,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 [];
@@ -525,6 +677,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);
     }
@@ -536,6 +689,219 @@ export function readSoftwareAgentTaskRecord(taskLedgerDir, taskId) {
     const file = join(taskLedgerDir, `${safeTaskFilename(taskId)}.json`);
     return readSoftwareAgentTaskRecordFile(file);
 }
+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);
+    try {
+        if (!existsSync(taskLedgerDir))
+            return 0;
+        const records = readdirSync(taskLedgerDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+            .map((entry) => {
+            const file = join(taskLedgerDir, entry.name);
+            const record = readSoftwareAgentTaskRecordFile(file);
+            return record ? { file, record } : null;
+        })
+            .filter((entry) => !!entry)
+            .sort((a, b) => compareSoftwareAgentTaskRecords(a.record, b.record));
+        const keepTaskIds = new Set(records.slice(0, safeMaxRecords).map((entry) => entry.record.taskId));
+        if (preserveTaskId)
+            keepTaskIds.add(preserveTaskId);
+        let deleted = 0;
+        for (const entry of records) {
+            if (keepTaskIds.has(entry.record.taskId))
+                continue;
+            try {
+                unlinkSync(entry.file);
+                deleted++;
+            }
+            catch {
+                // Best effort: retention should not break task completion.
+            }
+        }
+        return deleted;
+    }
+    catch {
+        return 0;
+    }
+}
+export function buildSoftwareAgentChildEnvironment(opts = {}) {
+    const policy = normalizeSoftwareAgentEnvPolicy(opts.policy);
+    const sourceEnv = opts.sourceEnv || process.env;
+    if (policy === "inherit") {
+        return {
+            env: sourceEnv,
+            audit: { policy },
+        };
+    }
+    const allowlist = normalizeSoftwareAgentEnvAllowlist([
+        ...DEFAULT_SOFTWARE_AGENT_ENV_ALLOWLIST,
+        ...(opts.allowlist || []),
+    ]);
+    const env = {};
+    for (const key of allowlist) {
+        if (isForbiddenSoftwareAgentEnvKey(key))
+            continue;
+        const value = sourceEnv[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return {
+        env,
+        audit: {
+            policy,
+            allowedKeys: Object.keys(env).sort(),
+        },
+    };
+}
+function writeSoftwareAgentContextPacket(contextSessionDir, envelope) {
+    const sessionId = normalizeContextSessionId(envelope.contextSessionId) || envelope.taskId || randomUUID();
+    const sessionDir = join(contextSessionDir, sessionId);
+    const packetPath = join(sessionDir, CONTEXT_PACKET_FILENAME);
+    const statePath = join(sessionDir, CONTEXT_SESSION_STATE_FILENAME);
+    const previousTaskSummary = readSoftwareAgentContextSessionSummary(statePath);
+    const packetEnvelope = {
+        ...envelope,
+        contextSessionId: sessionId,
+        contextPacketPath: packetPath,
+        previousTaskSummary,
+    };
+    mkdirSync(sessionDir, { recursive: true });
+    const content = buildTaskEnvelopePrompt(packetEnvelope);
+    writeFileSync(packetPath, `${redactSecrets(content)}\n`);
+    return {
+        envelope: packetEnvelope,
+        audit: { sessionId, packetPath, statePath },
+    };
+}
+function writeSoftwareAgentContextSessionState(statePath, envelope, result, updatedAt) {
+    try {
+        const state = {
+            schemaVersion: 1,
+            sessionId: envelope.contextSessionId,
+            updatedAt,
+            workMemoryDir: envelope.workMemoryDir,
+            lastTaskId: result.taskId,
+            lastGoal: envelope.goal,
+            lastResult: {
+                success: result.success,
+                exitCode: result.exitCode,
+                durationMs: result.durationMs,
+                outputSummary: summarizeText(result.output || "", MAX_CONTEXT_SESSION_SUMMARY_CHARS),
+                errorSummary: result.error ? summarizeText(result.error, MAX_CONTEXT_SESSION_SUMMARY_CHARS) : undefined,
+            },
+        };
+        writeFileSync(statePath, `${JSON.stringify(redactSecrets(state), null, 2)}\n`);
+    }
+    catch (err) {
+        console.error(`[software-agent] Failed to write context session state: ${err.message || String(err)}`);
+    }
+}
+function readSoftwareAgentContextSessionSummary(statePath) {
+    try {
+        const parsed = readSoftwareAgentContextSessionState(statePath);
+        if (!parsed?.lastTaskId || !parsed.lastResult)
+            return undefined;
+        const result = parsed.lastResult;
+        const status = result.success === true ? "completed" : "failed";
+        const lines = [
+            `Previous task: ${parsed.lastTaskId}`,
+            parsed.lastGoal ? `Previous goal: ${parsed.lastGoal}` : "",
+            `Status: ${status}`,
+            Number.isInteger(result.exitCode) ? `Exit code: ${result.exitCode}` : "Exit code: null",
+            Number.isInteger(result.durationMs) ? `Duration: ${result.durationMs}ms` : "",
+            result.outputSummary?.text ? "Previous output summary:" : "",
+            result.outputSummary?.text || "",
+            result.errorSummary?.text ? "Previous error summary:" : "",
+            result.errorSummary?.text || "",
+        ].filter(Boolean);
+        const summary = lines.join("\n").trim();
+        return summary ? summarizeText(summary, MAX_CONTEXT_SESSION_SUMMARY_CHARS).text : undefined;
+    }
+    catch {
+        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;
@@ -544,6 +910,27 @@ function readOptionalString(value, field) {
     const trimmed = value.trim();
     return trimmed || undefined;
 }
+function readOptionalContextSessionId(value, field) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error(`Invalid ${field}: expected string`);
+    return normalizeContextSessionId(value, field);
+}
+function normalizeContextSessionId(value, field = "contextSessionId") {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.length > MAX_CONTEXT_SESSION_ID_LENGTH) {
+        throw new Error(`Invalid ${field}: expected at most ${MAX_CONTEXT_SESSION_ID_LENGTH} characters`);
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(trimmed)) {
+        throw new Error(`Invalid ${field}: expected letters, numbers, dot, underscore, or hyphen`);
+    }
+    return trimmed;
+}
 function normalizeSoftwareAgentTaskOptions(options) {
     if (!options)
         return {};
@@ -552,6 +939,38 @@ function normalizeSoftwareAgentTaskOptions(options) {
     }
     return options;
 }
+function normalizeSoftwareAgentEnvPolicy(value) {
+    if (value === undefined || value === null || value === "")
+        return DEFAULT_SOFTWARE_AGENT_ENV_POLICY;
+    if (value === "inherit" || value === "allowlist")
+        return value;
+    throw new Error("Invalid software-agent env policy: expected inherit or allowlist");
+}
+function normalizeSoftwareAgentEnvAllowlist(values) {
+    if (!values)
+        return [];
+    const seen = new Set();
+    for (const value of values) {
+        if (typeof value !== "string") {
+            throw new Error("Invalid software-agent env allowlist entry: expected string");
+        }
+        const key = value.trim();
+        if (!key)
+            continue;
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            throw new Error(`Invalid software-agent env allowlist entry: ${key}`);
+        }
+        seen.add(key);
+    }
+    return [...seen];
+}
+function isForbiddenSoftwareAgentEnvKey(key) {
+    const upper = key.toUpperCase();
+    if (upper.startsWith("AKEMON_"))
+        return true;
+    const looksLikeCredential = /(?:SECRET|TOKEN|ACCESS|KEY|CREDENTIAL)/.test(upper);
+    return looksLikeCredential && (upper.includes("RELAY") || upper.includes("OWNER"));
+}
 function isAbortSignal(value) {
     return !!value
         && typeof value.aborted === "boolean"
@@ -610,6 +1029,11 @@ function normalizeTaskRecordLimit(limit) {
         return 20;
     return Math.min(limit, 100);
 }
+function normalizeTaskLedgerMaxRecords(limit) {
+    if (!Number.isInteger(limit) || limit <= 0)
+        return DEFAULT_TASK_LEDGER_MAX_RECORDS;
+    return Math.min(limit, 10_000);
+}
 function readSoftwareAgentTaskRecordFile(file) {
     try {
         if (!existsSync(file))
@@ -640,6 +1064,13 @@ function compareSoftwareAgentTaskRecords(a, b) {
         return bTime - aTime;
     return b.taskId.localeCompare(a.taskId);
 }
+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);
+}
 function buildCodexExecCommand(opts) {
     const args = [
         "exec",