akemon 0.3.5 → 0.3.6

package/dist/server.js

@@ -163,6 +163,16 @@ async function readOwnerSoftwareAgentEnvelope(req, res, deps) {
             envelope,
             request: body,
         });
+        if (readOptionalBooleanBody(body?.includeWorkMemoryContext, "includeWorkMemoryContext")) {
+            const workContext = await buildWorkMemoryContext({
+                workdir: deps.workdir,
+                agentName: deps.agentName,
+                purpose: `software-agent task: ${envelope.goal}`,
+                budget: readOptionalPositiveIntBody(body?.workMemoryContextBudget, "workMemoryContextBudget"),
+            });
+            envelope.workMemoryDir = workContext.workMemoryDir;
+            envelope.workMemoryContext = workContext.text;
+        }
         return envelope;
     }
     catch (err) {
@@ -225,6 +235,9 @@ export async function handleSoftwareAgentRunStreamHttp(req, res, deps) {
                         type: "start",
                         taskId: event.taskId,
                         commandLine: event.commandLine,
+                        contextSessionId: event.contextSessionId,
+                        contextPacketPath: event.contextPacketPath,
+                        workMemoryDir: event.workMemoryDir,
                     });
                 },
                 onStream(event) {
@@ -243,6 +256,9 @@ export async function handleSoftwareAgentRunStreamHttp(req, res, deps) {
                         exitCode: event.exitCode,
                         durationMs: event.durationMs,
                         result: event.result,
+                        contextSessionId: event.contextSessionId,
+                        contextPacketPath: event.contextPacketPath,
+                        workMemoryDir: event.workMemoryDir,
                     });
                 },
             },
@@ -282,7 +298,9 @@ export async function handleSoftwareAgentTasksHttp(req, res, deps) {
     const taskLedgerDir = softwareAgentTaskLedgerDir(deps.workdir, deps.agentName);
     if (url.pathname === basePath) {
         const limit = readPositiveIntQuery(url.searchParams.get("limit"), 20, 100);
-        const tasks = listSoftwareAgentTaskRecords(taskLedgerDir, limit);
+        const tasks = listSoftwareAgentTaskRecords(taskLedgerDir, limit, {
+            contextSessionId: url.searchParams.get("session") || undefined,
+        });
         writeJsonResponse(res, 200, { tasks }, true);
         return;
     }
@@ -297,11 +315,57 @@ export async function handleSoftwareAgentTasksHttp(req, res, deps) {
             writeJsonResponse(res, 404, { error: "Software-agent task not found" });
             return;
         }
-        writeJsonResponse(res, 200, { task }, true);
+        let contextSession;
+        if (readBooleanQuery(url.searchParams.get("includeContext")) && task.contextSession?.sessionId) {
+            try {
+                contextSession = readSoftwareAgentContextSession(softwareAgentContextSessionDir(deps.workdir, deps.agentName), task.contextSession.sessionId, { includeContextPacket: true });
+            }
+            catch {
+                contextSession = null;
+            }
+        }
+        writeJsonResponse(res, 200, { task, ...(contextSession ? { contextSession } : {}) }, true);
         return;
     }
     writeJsonResponse(res, 404, { error: "Software-agent task endpoint not found" });
 }
+export async function handleSoftwareAgentContextSessionsHttp(req, res, deps) {
+    if (!requireOwnerRequest(req, res, deps.options))
+        return;
+    const url = new URL(req.url || "/", "http://127.0.0.1");
+    const basePath = "/self/software-agent/sessions";
+    const contextSessionDir = softwareAgentContextSessionDir(deps.workdir, deps.agentName);
+    if (url.pathname === basePath) {
+        const limit = readPositiveIntQuery(url.searchParams.get("limit"), 20, 100);
+        const sessions = listSoftwareAgentContextSessions(contextSessionDir, limit);
+        writeJsonResponse(res, 200, { sessions }, true);
+        return;
+    }
+    if (url.pathname.startsWith(`${basePath}/`)) {
+        const sessionId = decodeURIComponent(url.pathname.slice(basePath.length + 1));
+        if (!sessionId || sessionId.includes("/")) {
+            writeJsonResponse(res, 400, { error: "Invalid software-agent context session id" });
+            return;
+        }
+        let session;
+        try {
+            session = readSoftwareAgentContextSession(contextSessionDir, sessionId, {
+                includeContextPacket: readBooleanQuery(url.searchParams.get("includeContext")),
+            });
+        }
+        catch (err) {
+            writeJsonResponse(res, 400, { error: err.message || "Invalid software-agent context session id" });
+            return;
+        }
+        if (!session) {
+            writeJsonResponse(res, 404, { error: "Software-agent context session not found" });
+            return;
+        }
+        writeJsonResponse(res, 200, { session }, true);
+        return;
+    }
+    writeJsonResponse(res, 404, { error: "Software-agent context session endpoint not found" });
+}
 function softwareAgentTaskLedgerDir(workdir, agentName) {
     return join(workdir, ".akemon", "agents", agentName, "software-agent", "tasks");
 }
@@ -316,6 +380,24 @@ function readPositiveIntQuery(value, fallback, max) {
         return fallback;
     return Math.min(parsed, max);
 }
+function readBooleanQuery(value) {
+    return value === "1" || value === "true" || value === "yes";
+}
+function readOptionalBooleanBody(value, field) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value !== "boolean")
+        throw new Error(`Invalid ${field}: expected boolean`);
+    return value;
+}
+function readOptionalPositiveIntBody(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`Invalid ${field}: expected positive integer`);
+    }
+    return value;
+}
 function writeSoftwareAgentStreamEvent(res, event) {
     if (res.destroyed)
         return;
@@ -347,8 +429,9 @@ import { LongTermModule } from "./longterm-module.js";
 import { ReflectionModule } from "./reflection-module.js";
 import { ScriptModule } from "./script-module.js";
 import { FileEventLog, PersistentEventBus } from "./event-bus.js";
-import { CodexSoftwareAgentPeripheral, createOwnerTaskEnvelope, listSoftwareAgentTaskRecords, readSoftwareAgentTaskRecord, } from "./software-agent-peripheral.js";
+import { CodexSoftwareAgentPeripheral, createOwnerTaskEnvelope, listSoftwareAgentContextSessions, listSoftwareAgentTaskRecords, readSoftwareAgentContextSession, readSoftwareAgentTaskRecord, } from "./software-agent-peripheral.js";
 import { buildSoftwareAgentMemorySummary } from "./software-agent-memory.js";
+import { buildWorkMemoryContext, workMemoryDir } from "./work-memory.js";
 import { SIG, sig } from "./types.js";
 import { loadConversation, listConversations, buildLLMContext } from "./context.js";
 import { redactSecrets } from "./redaction.js";
@@ -458,6 +541,15 @@ export async function serve(options) {
                 return;
             }
             const requestPath = req.url?.split("?")[0] || "";
+            if (req.method === "GET"
+                && (requestPath === "/self/software-agent/sessions" || requestPath.startsWith("/self/software-agent/sessions/"))) {
+                await handleSoftwareAgentContextSessionsHttp(req, res, {
+                    options,
+                    workdir,
+                    agentName: options.agentName,
+                });
+                return;
+            }
             if (req.method === "GET"
                 && (requestPath === "/self/software-agent/tasks" || requestPath.startsWith("/self/software-agent/tasks/"))) {
                 await handleSoftwareAgentTasksHttp(req, res, {
@@ -664,6 +756,7 @@ export async function serve(options) {
         sandbox: "workspace-write",
         taskLedgerDir: softwareAgentTaskLedgerDir(workdir, options.agentName),
         contextSessionDir: softwareAgentContextSessionDir(workdir, options.agentName),
+        workMemoryDir: workMemoryDir(workdir, options.agentName),
         envPolicy: options.softwareAgentEnvPolicy,
         envAllowlist: options.softwareAgentEnvAllowlist,
     });

package/dist/software-agent-peripheral.js

@@ -133,6 +133,7 @@ export class CodexSoftwareAgentPeripheral {
             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,
@@ -162,7 +163,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;
@@ -184,6 +192,11 @@ 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,
@@ -212,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",
@@ -241,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: redactSecrets(result) });
+                observer?.onEnd?.({
+                    taskId,
+                    exitCode: null,
+                    durationMs,
+                    result: redactSecrets(result),
+                    ...taskMetadata,
+                });
                 const completedAt = new Date().toISOString();
                 this.writeTaskRecord({
                     ...baseTaskRecord(),
@@ -308,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: redactSecrets(result) });
+                observer?.onEnd?.({
+                    taskId,
+                    exitCode,
+                    durationMs,
+                    result: redactSecrets(result),
+                    ...taskMetadata,
+                });
                 const completedAt = new Date().toISOString();
                 this.writeTaskRecord({
                     ...baseTaskRecord(),
@@ -451,6 +478,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 +502,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 +536,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 +550,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 +559,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 +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 [];
@@ -627,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);
     }
@@ -638,6 +689,62 @@ 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 {
@@ -728,6 +835,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 +854,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 +877,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,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",

package/dist/software-agent-result-cli.js

@@ -0,0 +1,69 @@
+export function renderSoftwareAgentRunResult(result, writers = {
+    stdout: (chunk) => process.stdout.write(chunk),
+    stderr: (chunk) => process.stderr.write(chunk),
+}) {
+    const output = readString(result?.output);
+    if (output) {
+        writers.stdout(output);
+        if (!output.endsWith("\n"))
+            writers.stdout("\n");
+    }
+    else {
+        writers.stdout(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    const taskId = readString(result?.taskId) || "unknown";
+    const success = result?.success === false ? false : true;
+    const exitCode = readExitCode(result?.exitCode);
+    const durationMs = readDurationMs(result?.durationMs);
+    const parts = [`[software-agent] task ${taskId} ${success ? "finished" : "failed"}`];
+    if (exitCode !== undefined)
+        parts.push(`exit=${exitCode}`);
+    if (durationMs !== undefined)
+        parts.push(`duration=${durationMs}ms`);
+    stderrLine(writers, parts.join(" "));
+    const error = readString(result?.error);
+    if (!success && error)
+        stderrLine(writers, `[software-agent] error: ${truncateOneLine(error, 240)}`);
+    printMetadata(result, writers);
+    printNextSteps(result, taskId, writers);
+    return !success;
+}
+function printMetadata(result, writers) {
+    const contextSessionId = readString(result?.contextSessionId);
+    const contextPacketPath = readString(result?.contextPacketPath);
+    const workMemoryDir = readString(result?.workMemoryDir);
+    if (contextSessionId)
+        stderrLine(writers, `[software-agent] session: ${truncateOneLine(contextSessionId, 120)}`);
+    if (contextPacketPath)
+        stderrLine(writers, `[software-agent] context: ${truncateOneLine(contextPacketPath, 240)}`);
+    if (workMemoryDir)
+        stderrLine(writers, `[software-agent] work memory: ${truncateOneLine(workMemoryDir, 240)}`);
+}
+function printNextSteps(result, taskId, writers) {
+    const contextSessionId = readString(result?.contextSessionId);
+    const workMemoryDir = readString(result?.workMemoryDir);
+    const hints = [`akemon software-agent-tasks ${taskId}`];
+    if (contextSessionId)
+        hints.push(`akemon software-agent-sessions ${contextSessionId} --context`);
+    if (workMemoryDir)
+        hints.push("akemon work-note \"<durable work memory>\" --source codex");
+    stderrLine(writers, `[software-agent] next: ${hints.join(" | ")}`);
+}
+function stderrLine(writers, line) {
+    writers.stderr(`${line}\n`);
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function readExitCode(value) {
+    return typeof value === "number" && Number.isInteger(value) ? value : undefined;
+}
+function readDurationMs(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+function truncateOneLine(value, max) {
+    const oneLine = value.replace(/\s+/g, " ").trim();
+    if (oneLine.length <= max)
+        return oneLine;
+    return `${oneLine.slice(0, Math.max(0, max - 3))}...`;
+}

package/dist/software-agent-stream-cli.js

@@ -31,6 +31,7 @@ export class SoftwareAgentStreamCliRenderer {
             const commandLine = readString(event.commandLine);
             if (commandLine)
                 this.stderrLine(`[software-agent] command: ${truncateOneLine(commandLine, 160)}`);
+            this.printMetadata(event);
             return false;
         }
         if (type === "stdout" && typeof event.chunk === "string") {
@@ -72,8 +73,30 @@ export class SoftwareAgentStreamCliRenderer {
         if (output) {
             this.stderrLine(`[software-agent] summary: ${truncateOneLine(output, 240)}`);
         }
+        this.printNextSteps(event, taskId);
         return !success;
     }
+    printMetadata(event) {
+        const contextSessionId = readString(event.contextSessionId);
+        const contextPacketPath = readString(event.contextPacketPath);
+        const workMemoryDir = readString(event.workMemoryDir);
+        if (contextSessionId)
+            this.stderrLine(`[software-agent] session: ${truncateOneLine(contextSessionId, 120)}`);
+        if (contextPacketPath)
+            this.stderrLine(`[software-agent] context: ${truncateOneLine(contextPacketPath, 240)}`);
+        if (workMemoryDir)
+            this.stderrLine(`[software-agent] work memory: ${truncateOneLine(workMemoryDir, 240)}`);
+    }
+    printNextSteps(event, taskId) {
+        const contextSessionId = readString(event.contextSessionId);
+        const workMemoryDir = readString(event.workMemoryDir);
+        const hints = [`akemon software-agent-tasks ${taskId}`];
+        if (contextSessionId)
+            hints.push(`akemon software-agent-sessions ${contextSessionId} --context`);
+        if (workMemoryDir)
+            hints.push("akemon work-note \"<durable work memory>\" --source codex");
+        this.stderrLine(`[software-agent] next: ${hints.join(" | ")}`);
+    }
     stderrLine(line) {
         if (!this.stderrEndsWithNewline)
             this.writers.stderr("\n");