akemon 0.3.3 → 0.3.4

package/README.md

@@ -164,11 +164,16 @@ akemon serve --name my-agent --engine claude
 
 # In another terminal, ask the local software peripheral to work in the repo
 akemon software-agent "Add one focused test and run the relevant test command."
+
+# Review recent software-agent runs
+akemon software-agent-tasks --limit 5
 ```
 
 This is different from `--engine`: engines are replaceable compute, while software agents are external software bodies with their own repo context, skills, tools, and execution loop.
 
-Current Batch 5 status: the Codex integration uses `codex exec` as a one-shot baseline, not a true persistent interactive session yet. It is owner-only, local-only, one task at a time, and every call is wrapped in an explicit task envelope with workdir, memory scope, risk level, allowed actions, and forbidden actions.
+Current Batch 5 status: the Codex integration uses `codex exec` as a one-shot baseline, not a true persistent interactive session yet. It is owner-only, local-only, one task at a time, streams local stdout/stderr by default, and every call is wrapped in an explicit task envelope with workdir, memory scope, risk level, allowed actions, and forbidden actions.
+
+Software-agent tasks default to the `akemon serve` workdir boundary. Use `--allow-outside-workdir` only when you explicitly want the software agent to run outside that root. Each run is recorded under `.akemon/agents/<name>/software-agent/tasks/` with the envelope, result, output summaries, and git worktree status.
 
 ## Serve Options
 

package/dist/cli.js

@@ -18,21 +18,37 @@ function parsePortOption(port) {
     const value = typeof port === "number" ? port : parseInt(String(port || "3000"));
     return Number.isInteger(value) && value > 0 ? value : 3000;
 }
+function clampPositiveInt(value, fallback, max) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        return fallback;
+    return Math.min(parsed, max);
+}
+function printSoftwareAgentTaskList(tasks) {
+    if (!tasks.length) {
+        console.log("No software-agent tasks found.");
+        return;
+    }
+    for (const task of tasks) {
+        const result = task.result?.success === true ? "ok" : task.result?.success === false ? "error" : "pending";
+        const duration = typeof task.durationMs === "number" ? `${task.durationMs}ms` : "-";
+        const git = task.workdirStatus?.isRepo
+            ? (task.workdirStatus.dirty ? `dirty:${task.workdirStatus.changedFiles?.length || 0}` : "clean")
+            : "no-git";
+        const goal = truncateOneLine(task.envelope?.goal || "", 90);
+        console.log(`${task.taskId}  ${task.status}/${result}  ${duration}  ${git}  ${task.updatedAt || task.startedAt}`);
+        if (goal)
+            console.log(`  ${goal}`);
+    }
+}
+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))}...`;
+}
 async function callLocalOwnerEndpoint(path, opts, init = {}) {
-    const credentials = await getOrCreateRelayCredentials();
-    const port = parsePortOption(opts.port);
-    const headers = {
-        Authorization: `Bearer ${credentials.secretKey}`,
-    };
-    if (init.body !== undefined)
-        headers["Content-Type"] = "application/json";
-    const res = await fetch(`http://127.0.0.1:${port}${path}`, {
-        ...init,
-        headers: {
-            ...headers,
-            ...init.headers,
-        },
-    });
+    const res = await fetchLocalOwnerEndpoint(path, opts, init);
     const text = await res.text();
     let data;
     try {
@@ -47,6 +63,117 @@ async function callLocalOwnerEndpoint(path, opts, init = {}) {
     }
     return data;
 }
+async function fetchLocalOwnerEndpoint(path, opts, init = {}) {
+    const credentials = await getOrCreateRelayCredentials();
+    const port = parsePortOption(opts.port);
+    const headers = {
+        Authorization: `Bearer ${credentials.secretKey}`,
+    };
+    if (init.body !== undefined)
+        headers["Content-Type"] = "application/json";
+    let res;
+    try {
+        res = await fetch(`http://127.0.0.1:${port}${path}`, {
+            ...init,
+            headers: {
+                ...headers,
+                ...init.headers,
+            },
+        });
+    }
+    catch (error) {
+        const cause = error.cause;
+        if (error instanceof TypeError && error.message === "fetch failed" && cause?.message === "bad port") {
+            console.error(`Port ${port} cannot be used for the local akemon serve connection. Choose a different --port.`);
+            process.exit(1);
+        }
+        if (error instanceof TypeError && error.message === "fetch failed") {
+            console.error(`Cannot connect to local akemon serve on port ${port}. Start it with: akemon serve --port ${port}`);
+            process.exit(1);
+        }
+        throw error;
+    }
+    return res;
+}
+async function streamLocalOwnerEndpoint(path, opts, body) {
+    const res = await fetchLocalOwnerEndpoint(path, opts, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            data = { error: text };
+        }
+        console.error(data.error || text || `Request failed with HTTP ${res.status}`);
+        process.exit(1);
+    }
+    if (!res.body)
+        return;
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let failed = false;
+    const reader = res.body.getReader();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split(/\r?\n/);
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+            if (handleSoftwareAgentStreamLine(line))
+                failed = true;
+        }
+    }
+    buffer += decoder.decode();
+    if (buffer.trim() && handleSoftwareAgentStreamLine(buffer))
+        failed = true;
+    if (failed)
+        process.exit(1);
+}
+function handleSoftwareAgentStreamLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return false;
+    let event;
+    try {
+        event = JSON.parse(trimmed);
+    }
+    catch {
+        process.stderr.write(`${trimmed}\n`);
+        return true;
+    }
+    if (event.type === "start" && event.taskId) {
+        process.stderr.write(`[software-agent] started ${event.taskId}\n`);
+        return false;
+    }
+    if (event.type === "stdout" && typeof event.chunk === "string") {
+        process.stdout.write(event.chunk);
+        return false;
+    }
+    if (event.type === "stderr" && typeof event.chunk === "string") {
+        process.stderr.write(event.chunk);
+        return false;
+    }
+    if (event.type === "end") {
+        const result = event.result;
+        if (result?.success === false && result.error) {
+            process.stderr.write(`${result.error}\n`);
+            return true;
+        }
+        return false;
+    }
+    if (event.type === "error") {
+        process.stderr.write(`${event.error || "Software-agent stream failed"}\n`);
+        return true;
+    }
+    return false;
+}
 program
     .name("akemon")
     .description("Agent work marketplace — train your agent, let it work for others")
@@ -171,12 +298,14 @@ program
     .argument("<goal...>", "Task goal to send to the software agent")
     .option("-p, --port <port>", "Local akemon serve port", "3000")
     .option("-w, --workdir <path>", "Workdir for the software agent (default: serve workdir)")
+    .option("--allow-outside-workdir", "Allow the software agent workdir to be outside the serve workdir")
     .option("--role-scope <scope>", "Role scope: owner|public|order|agent|system", "owner")
     .option("--memory-scope <scope>", "Memory scope: none|public|task|owner", "owner")
     .option("--risk <level>", "Risk level: low|medium|high", "medium")
     .option("--memory-summary <text>", "Pre-filtered memory/context text to include")
     .option("--deliverable <text>", "Expected output shape")
     .option("--timeout-ms <ms>", "Task timeout in milliseconds")
+    .option("--no-stream", "Disable local streaming and wait for the final response")
     .action(async (goalParts, opts) => {
     const body = {
         goal: goalParts.join(" "),
@@ -186,6 +315,8 @@ program
     };
     if (opts.workdir)
         body.workdir = opts.workdir;
+    if (opts.allowOutsideWorkdir)
+        body.allowOutsideWorkdir = true;
     if (opts.memorySummary)
         body.memorySummary = opts.memorySummary;
     if (opts.deliverable)
@@ -198,6 +329,10 @@ program
         }
         body.timeoutMs = timeoutMs;
     }
+    if (opts.stream !== false) {
+        await streamLocalOwnerEndpoint("/self/software-agent/run-stream", opts, body);
+        return;
+    }
     const data = await callLocalOwnerEndpoint("/self/software-agent/run", opts, {
         method: "POST",
         body: JSON.stringify(body),
@@ -217,6 +352,26 @@ program
     });
     console.log(JSON.stringify(data, null, 2));
 });
+program
+    .command("software-agent-tasks")
+    .description("List recent owner-only software-agent task ledger records")
+    .argument("[taskId]", "Task id to inspect")
+    .option("-p, --port <port>", "Local akemon serve port", "3000")
+    .option("-l, --limit <n>", "Maximum recent tasks to list", "20")
+    .option("--json", "Print raw JSON")
+    .action(async (taskId, opts) => {
+    const path = taskId
+        ? `/self/software-agent/tasks/${encodeURIComponent(taskId)}`
+        : `/self/software-agent/tasks?limit=${clampPositiveInt(opts.limit, 20, 100)}`;
+    const data = await callLocalOwnerEndpoint(path, opts, {
+        method: "GET",
+    });
+    if (opts.json || taskId) {
+        console.log(JSON.stringify(taskId ? data.task : data, null, 2));
+        return;
+    }
+    printSoftwareAgentTaskList(Array.isArray(data.tasks) ? data.tasks : []);
+});
 program
     .command("software-agent-reset")
     .description("Reset the owner-only local software-agent peripheral session")

package/dist/server.js

@@ -141,6 +141,12 @@ export async function handleSoftwareAgentRunHttp(req, res, deps) {
     let envelope;
     try {
         envelope = createOwnerTaskEnvelope(body, deps.workdir);
+        envelope.memorySummary = await buildSoftwareAgentMemorySummary({
+            workdir: deps.workdir,
+            agentName: deps.agentName,
+            envelope,
+            request: body,
+        });
     }
     catch (err) {
         res.writeHead(400, { "Content-Type": "application/json" })
@@ -158,6 +164,109 @@ export async function handleSoftwareAgentRunHttp(req, res, deps) {
             .end(JSON.stringify({ error: err.message || String(err) }));
     }
 }
+export async function handleSoftwareAgentRunStreamHttp(req, res, deps) {
+    if (!isOwnerRequest(req, deps.options)) {
+        res.writeHead(401, { "Content-Type": "application/json" })
+            .end(JSON.stringify({ error: "Owner token required" }));
+        return;
+    }
+    if (!deps.softwareAgent) {
+        res.writeHead(503, { "Content-Type": "application/json" })
+            .end(JSON.stringify({ error: "Software agent peripheral not ready" }));
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (err) {
+        res.writeHead(400, { "Content-Type": "application/json" })
+            .end(JSON.stringify({ error: err.message || "Invalid request body" }));
+        return;
+    }
+    let envelope;
+    try {
+        envelope = createOwnerTaskEnvelope(body, deps.workdir);
+        envelope.memorySummary = await buildSoftwareAgentMemorySummary({
+            workdir: deps.workdir,
+            agentName: deps.agentName,
+            envelope,
+            request: body,
+        });
+    }
+    catch (err) {
+        res.writeHead(400, { "Content-Type": "application/json" })
+            .end(JSON.stringify({ error: err.message || "Invalid software-agent envelope" }));
+        return;
+    }
+    const abortController = new AbortController();
+    let responseFinished = false;
+    let streamStarted = false;
+    res.on("close", () => {
+        if (!responseFinished)
+            abortController.abort();
+    });
+    const ensureStreamStarted = () => {
+        if (streamStarted)
+            return;
+        streamStarted = true;
+        res.writeHead(200, {
+            "Content-Type": "application/x-ndjson; charset=utf-8",
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        });
+        res.flushHeaders?.();
+    };
+    try {
+        await deps.softwareAgent.sendTask(envelope, {
+            signal: abortController.signal,
+            observer: {
+                onStart(event) {
+                    ensureStreamStarted();
+                    writeSoftwareAgentStreamEvent(res, {
+                        type: "start",
+                        taskId: event.taskId,
+                        commandLine: event.commandLine,
+                    });
+                },
+                onStream(event) {
+                    ensureStreamStarted();
+                    writeSoftwareAgentStreamEvent(res, {
+                        type: event.stream,
+                        taskId: event.taskId,
+                        chunk: event.chunk,
+                    });
+                },
+                onEnd(event) {
+                    ensureStreamStarted();
+                    writeSoftwareAgentStreamEvent(res, {
+                        type: "end",
+                        taskId: event.taskId,
+                        result: event.result,
+                    });
+                },
+            },
+        });
+    }
+    catch (err) {
+        if (!streamStarted) {
+            const busy = String(err.message || "").includes("busy");
+            res.writeHead(busy ? 409 : 500, { "Content-Type": "application/json" })
+                .end(JSON.stringify({ error: err.message || String(err) }));
+            responseFinished = true;
+            return;
+        }
+        writeSoftwareAgentStreamEvent(res, {
+            type: "error",
+            error: err.message || String(err),
+        });
+    }
+    finally {
+        responseFinished = true;
+        if (streamStarted && !res.writableEnded)
+            res.end();
+    }
+}
 export async function handleSoftwareAgentStatusHttp(req, res, deps) {
     if (!isOwnerRequest(req, deps.options)) {
         res.writeHead(401, { "Content-Type": "application/json" })
@@ -172,6 +281,58 @@ export async function handleSoftwareAgentStatusHttp(req, res, deps) {
     res.writeHead(200, { "Content-Type": "application/json" })
         .end(JSON.stringify(deps.softwareAgent.getState(), null, 2));
 }
+export async function handleSoftwareAgentTasksHttp(req, res, deps) {
+    if (!isOwnerRequest(req, deps.options)) {
+        res.writeHead(401, { "Content-Type": "application/json" })
+            .end(JSON.stringify({ error: "Owner token required" }));
+        return;
+    }
+    const url = new URL(req.url || "/", "http://127.0.0.1");
+    const basePath = "/self/software-agent/tasks";
+    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);
+        res.writeHead(200, { "Content-Type": "application/json" })
+            .end(JSON.stringify({ tasks }, null, 2));
+        return;
+    }
+    if (url.pathname.startsWith(`${basePath}/`)) {
+        const taskId = decodeURIComponent(url.pathname.slice(basePath.length + 1));
+        if (!taskId || taskId.includes("/")) {
+            res.writeHead(400, { "Content-Type": "application/json" })
+                .end(JSON.stringify({ error: "Invalid software-agent task id" }));
+            return;
+        }
+        const task = readSoftwareAgentTaskRecord(taskLedgerDir, taskId);
+        if (!task) {
+            res.writeHead(404, { "Content-Type": "application/json" })
+                .end(JSON.stringify({ error: "Software-agent task not found" }));
+            return;
+        }
+        res.writeHead(200, { "Content-Type": "application/json" })
+            .end(JSON.stringify({ task }, null, 2));
+        return;
+    }
+    res.writeHead(404, { "Content-Type": "application/json" })
+        .end(JSON.stringify({ error: "Software-agent task endpoint not found" }));
+}
+function softwareAgentTaskLedgerDir(workdir, agentName) {
+    return join(workdir, ".akemon", "agents", agentName, "software-agent", "tasks");
+}
+function readPositiveIntQuery(value, fallback, max) {
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        return fallback;
+    return Math.min(parsed, max);
+}
+function writeSoftwareAgentStreamEvent(res, event) {
+    if (res.destroyed)
+        return;
+    res.write(`${JSON.stringify(event)}\n`);
+}
 export async function handleSoftwareAgentResetHttp(req, res, deps) {
     if (!isOwnerRequest(req, deps.options)) {
         res.writeHead(401, { "Content-Type": "application/json" })
@@ -205,7 +366,8 @@ 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 } from "./software-agent-peripheral.js";
+import { CodexSoftwareAgentPeripheral, createOwnerTaskEnvelope, listSoftwareAgentTaskRecords, readSoftwareAgentTaskRecord, } from "./software-agent-peripheral.js";
+import { buildSoftwareAgentMemorySummary } from "./software-agent-memory.js";
 import { SIG, sig } from "./types.js";
 import { loadConversation, listConversations, buildLLMContext } from "./context.js";
 import { createMcpServer, initMcpProxy, createMcpProxyServer } from "./mcp-server.js";
@@ -288,10 +450,20 @@ export async function serve(options) {
         if (!isQuiet)
             console.log(`[http] ${req.method} ${req.url} session=${req.headers["mcp-session-id"] || "none"}`);
         try {
+            if (req.url === "/self/software-agent/run-stream" && req.method === "POST") {
+                await handleSoftwareAgentRunStreamHttp(req, res, {
+                    options,
+                    workdir,
+                    agentName: options.agentName,
+                    softwareAgent: codexSoftwareAgent,
+                });
+                return;
+            }
             if (req.url === "/self/software-agent/run" && req.method === "POST") {
                 await handleSoftwareAgentRunHttp(req, res, {
                     options,
                     workdir,
+                    agentName: options.agentName,
                     softwareAgent: codexSoftwareAgent,
                 });
                 return;
@@ -303,6 +475,16 @@ export async function serve(options) {
                 });
                 return;
             }
+            const requestPath = req.url?.split("?")[0] || "";
+            if (req.method === "GET"
+                && (requestPath === "/self/software-agent/tasks" || requestPath.startsWith("/self/software-agent/tasks/"))) {
+                await handleSoftwareAgentTasksHttp(req, res, {
+                    options,
+                    workdir,
+                    agentName: options.agentName,
+                });
+                return;
+            }
             if (req.url === "/self/software-agent/reset" && req.method === "POST") {
                 await handleSoftwareAgentResetHttp(req, res, {
                     options,
@@ -498,10 +680,13 @@ export async function serve(options) {
         workdir,
         model: process.env.AKEMON_CODEX_MODEL,
         sandbox: "workspace-write",
+        taskLedgerDir: softwareAgentTaskLedgerDir(workdir, options.agentName),
     });
-    await codexSoftwareAgent.start(bus);
     // Peripheral registry — Core routes by capability
     const peripherals = [relay, engineP, codexSoftwareAgent];
+    for (const peripheral of peripherals) {
+        await peripheral.start(bus);
+    }
     // requestCompute: acquire the engine slot (priority-aware), execute with a
     // hard timeout, and release. The slot release and subprocess kill are both
     // driven by the same AbortController so a stuck engine can't hold the lock.

package/dist/software-agent-memory.js

@@ -0,0 +1,141 @@
+import { buildLLMContext, loadConversation } from "./context.js";
+import { buildRoleContext, loadRoles, resolveRoles } from "./role-module.js";
+const DEFAULT_CONTEXT_BUDGET = 6000;
+export async function buildSoftwareAgentMemorySummary(opts) {
+    const budget = opts.contextBudget ?? DEFAULT_CONTEXT_BUDGET;
+    const parts = [
+        "[Akemon memory boundary]",
+        `Role scope: ${opts.envelope.roleScope}`,
+        `Memory scope: ${opts.envelope.memoryScope}`,
+        boundaryDescription(opts.envelope.roleScope, opts.envelope.memoryScope),
+    ];
+    if (opts.envelope.memoryScope === "none") {
+        parts.push("No Akemon memory/context is included for this task.");
+        return parts.join("\n");
+    }
+    const request = normalizeRequest(opts.request);
+    const roleTrigger = readRequestString(request, "roleTrigger") || triggerForRoleScope(opts.envelope.roleScope);
+    const productName = readRequestString(request, "productName");
+    const productId = readRequestString(request, "productId");
+    const rolePolicy = await resolveRoleMemoryPolicy(opts.workdir, opts.agentName, roleTrigger);
+    if (rolePolicy.exclude.length) {
+        parts.push(`Active role exclusions: ${rolePolicy.exclude.join(", ")}`);
+    }
+    const roleContext = await buildRoleContext(opts.workdir, opts.agentName, roleTrigger, productName, productId);
+    if (roleContext.trim()) {
+        parts.push("");
+        parts.push("[Role/product context]");
+        parts.push(limitText(roleContext.trim(), Math.floor(budget * 0.55)));
+    }
+    const taskContext = readRequestString(request, "taskContext");
+    if (taskContext) {
+        parts.push("");
+        parts.push("[Task-provided context]");
+        parts.push(limitText(taskContext, Math.floor(budget * 0.25)));
+    }
+    const conversationId = readRequestString(request, "conversationId");
+    if (conversationId && canIncludeConversation(opts.envelope.roleScope, opts.envelope.memoryScope)) {
+        const conv = await loadConversation(opts.workdir, opts.agentName, conversationId);
+        const { text } = buildLLMContext(conv, Math.floor(budget * 0.3));
+        if (text.trim()) {
+            parts.push("");
+            parts.push("[Conversation context]");
+            parts.push(text.trim());
+        }
+    }
+    else if (conversationId) {
+        parts.push("");
+        parts.push("[Excluded conversation context]");
+        parts.push("A conversationId was supplied, but conversation memory is only included for owner-scoped software-agent tasks in v1.");
+    }
+    const ownerMemory = readRequestString(request, "memorySummary");
+    if (ownerMemory && canIncludeOwnerMemory(opts.envelope.roleScope, opts.envelope.memoryScope)) {
+        if (roleExcludesOwnerMemory(rolePolicy)) {
+            parts.push("");
+            parts.push("[Role-excluded owner memory]");
+            parts.push(`The active role (${rolePolicy.roleName || "unknown"}) excludes ${rolePolicy.exclude.join(", ")}, so owner-provided memory was not included.`);
+        }
+        else {
+            parts.push("");
+            parts.push("[Owner-visible memory]");
+            parts.push(limitText(ownerMemory, Math.floor(budget * 0.35)));
+        }
+    }
+    else if (ownerMemory) {
+        parts.push("");
+        parts.push("[Excluded owner memory]");
+        parts.push("A memorySummary was supplied, but it was not included because this envelope is not owner/owner scoped.");
+    }
+    return limitText(parts.join("\n"), budget);
+}
+export function canIncludeOwnerMemory(roleScope, memoryScope) {
+    return roleScope === "owner" && memoryScope === "owner";
+}
+function canIncludeConversation(roleScope, memoryScope) {
+    return roleScope === "owner" && (memoryScope === "owner" || memoryScope === "task");
+}
+function triggerForRoleScope(roleScope) {
+    switch (roleScope) {
+        case "owner": return "trigger:chat:owner";
+        case "public": return "trigger:chat:public";
+        case "order": return "trigger:order";
+        case "agent": return "trigger:agent_call";
+        case "system": return "trigger:system";
+    }
+}
+function boundaryDescription(roleScope, memoryScope) {
+    if (roleScope === "owner" && memoryScope === "owner") {
+        return "Owner-scoped task: owner-visible memory may be included after Akemon-side selection.";
+    }
+    if (memoryScope === "none") {
+        return "No-memory task: do not use Akemon private memory, conversation history, or subjective state.";
+    }
+    return "Non-owner task: exclude owner private conversations, personal notes, bio state, diary, subjective impressions, and owner-only memory.";
+}
+async function resolveRoleMemoryPolicy(workdir, agentName, roleTrigger) {
+    const roles = await loadRoles(workdir, agentName);
+    const { primary } = resolveRoles(roles, roleTrigger);
+    return {
+        roleName: primary?.name || null,
+        exclude: primary?.exclude || [],
+    };
+}
+function roleExcludesOwnerMemory(policy) {
+    return policy.exclude.some((item) => {
+        const normalized = item.toLowerCase();
+        return normalized.includes("owner")
+            || normalized.includes("private")
+            || normalized.includes("personal")
+            || normalized.includes("note")
+            || normalized.includes("diary")
+            || normalized.includes("bio")
+            || normalized.includes("全部记忆")
+            || normalized.includes("个人")
+            || normalized.includes("笔记")
+            || normalized.includes("日记")
+            || normalized.includes("状态");
+    });
+}
+function normalizeRequest(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid request: expected object");
+    }
+    return value;
+}
+function readRequestString(request, field) {
+    const value = request[field];
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value !== "string")
+        throw new Error(`Invalid ${field}: expected string`);
+    return value.trim();
+}
+function limitText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const head = Math.floor(maxChars * 0.45);
+    const tail = Math.max(0, maxChars - head - 40);
+    return `${text.slice(0, head)}\n[truncated ${text.length - head - tail} chars]\n${text.slice(-tail)}`;
+}

package/dist/software-agent-peripheral.js

@@ -11,7 +11,9 @@
  * transport to app-server or a true persistent interactive session.
  */
 import { randomUUID } from "crypto";
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, 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";
@@ -30,6 +32,9 @@ const DEFAULT_OWNER_FORBIDDEN_ACTIONS = [
 const ROLE_SCOPES = ["owner", "public", "order", "agent", "system"];
 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;
 export class CodexSoftwareAgentPeripheral {
     id;
     name;
@@ -39,6 +44,7 @@ export class CodexSoftwareAgentPeripheral {
     bus = null;
     activeChild = null;
     activeTaskId = null;
+    activeWorkdir = null;
     sessionId = randomUUID();
     constructor(config) {
         this.config = config;
@@ -73,15 +79,21 @@ export class CodexSoftwareAgentPeripheral {
         }
         this.activeChild = null;
         this.activeTaskId = null;
+        this.activeWorkdir = null;
         this.sessionId = randomUUID();
     }
     getState() {
+        const currentWorkdir = this.activeWorkdir || resolvePath(this.config.workdir);
         return {
             id: this.id,
             sessionId: this.sessionId,
             activeTaskId: this.activeTaskId,
+            activeWorkdir: this.activeWorkdir,
             busy: !!this.activeChild,
             transport: "codex-exec",
+            baseWorkdir: resolvePath(this.config.workdir),
+            workdirStatus: this.collectWorkdirStatus(currentWorkdir),
+            taskLedgerDir: this.config.taskLedgerDir,
         };
     }
     async send(signal) {
@@ -97,13 +109,16 @@ export class CodexSoftwareAgentPeripheral {
         const result = await this.sendTask(envelope);
         return sig(SIG.SOFTWARE_AGENT_RESPONSE, { ...result }, this.id);
     }
-    async sendTask(envelope, signal) {
+    async sendTask(envelope, taskOptions) {
         if (this.activeChild) {
             throw new Error(`Software agent busy (task=${this.activeTaskId})`);
         }
+        const { signal, observer } = normalizeSoftwareAgentTaskOptions(taskOptions);
         const taskId = envelope.taskId || `sw_${Date.now()}_${randomUUID().slice(0, 8)}`;
-        const workdir = envelope.workdir || this.config.workdir;
-        const prompt = buildTaskEnvelopePrompt({ ...envelope, taskId, workdir });
+        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);
         const { cmd, args } = buildCodexExecCommand({
             command: this.config.command || "codex",
             workdir,
@@ -111,17 +126,38 @@ export class CodexSoftwareAgentPeripheral {
             sandbox: this.config.sandbox || "workspace-write",
         });
         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 timeoutMs = envelope.timeoutMs || this.config.defaultTimeoutMs || DEFAULT_TIMEOUT_MS;
+        const workdirStatus = this.collectWorkdirStatus(workdir);
+        const baseTaskRecord = () => ({
+            schemaVersion: 1,
+            taskId,
+            agentId: this.id,
+            sessionId: this.sessionId,
+            transport: "codex-exec",
+            commandLine,
+            envelope: effectiveEnvelope,
+            startedAt: startedAtIso,
+            workdirStatus,
+        });
         return new Promise((resolve) => {
             this.activeTaskId = taskId;
-            relay.sendTaskStart(taskId, "software_agent", commandLine);
+            this.activeWorkdir = workdir;
+            this.writeTaskRecord({
+                ...baseTaskRecord(),
+                status: "running",
+                updatedAt: startedAtIso,
+            });
+            const origin = "software_agent";
+            relay.sendTaskStart(taskId, origin, commandLine);
+            observer?.onStart?.({ taskId, origin, commandLine });
             this.bus?.emit(SIG.TASK_STARTED, sig(SIG.TASK_STARTED, {
                 taskId,
                 taskType: "software_agent",
-                description: envelope.goal,
+                description: effectiveEnvelope.goal,
                 peripheral: this.id,
                 sessionId: this.sessionId,
             }, this.id));
@@ -137,8 +173,8 @@ export class CodexSoftwareAgentPeripheral {
             catch (err) {
                 this.activeChild = null;
                 this.activeTaskId = null;
+                this.activeWorkdir = null;
                 const durationMs = Date.now() - startedAt;
-                relay.sendTaskEnd(taskId, null, durationMs);
                 const result = {
                     success: false,
                     taskId,
@@ -147,6 +183,19 @@ export class CodexSoftwareAgentPeripheral {
                     exitCode: null,
                     durationMs,
                 };
+                relay.sendTaskEnd(taskId, null, durationMs);
+                observer?.onEnd?.({ taskId, exitCode: null, durationMs, result });
+                const completedAt = new Date().toISOString();
+                this.writeTaskRecord({
+                    ...baseTaskRecord(),
+                    status: "failed",
+                    updatedAt: completedAt,
+                    completedAt,
+                    durationMs,
+                    result,
+                    stdoutSummary: summarizeText(""),
+                    stderrSummary: summarizeText(result.error || ""),
+                });
                 this.bus?.emit(SIG.TASK_FAILED, sig(SIG.TASK_FAILED, result, this.id));
                 resolve(result);
                 return;
@@ -169,15 +218,17 @@ export class CodexSoftwareAgentPeripheral {
                 if (tailOut) {
                     stdout += tailOut;
                     relay.sendTaskStream(taskId, "stdout", tailOut);
+                    observer?.onStream?.({ taskId, stream: "stdout", chunk: tailOut });
                 }
                 if (tailErr) {
                     stderr += tailErr;
                     relay.sendTaskStream(taskId, "stderr", tailErr);
+                    observer?.onStream?.({ taskId, stream: "stderr", chunk: tailErr });
                 }
                 const durationMs = Date.now() - startedAt;
-                relay.sendTaskEnd(taskId, exitCode, durationMs);
                 this.activeChild = null;
                 this.activeTaskId = null;
+                this.activeWorkdir = null;
                 const output = stdout.trim() || stderr.trim();
                 const success = !error && !aborted && exitCode === 0;
                 const result = {
@@ -188,6 +239,19 @@ export class CodexSoftwareAgentPeripheral {
                     exitCode,
                     durationMs,
                 };
+                relay.sendTaskEnd(taskId, exitCode, durationMs);
+                observer?.onEnd?.({ taskId, exitCode, durationMs, result });
+                const completedAt = new Date().toISOString();
+                this.writeTaskRecord({
+                    ...baseTaskRecord(),
+                    status: success ? "completed" : "failed",
+                    updatedAt: completedAt,
+                    completedAt,
+                    durationMs,
+                    result,
+                    stdoutSummary: summarizeText(stdout),
+                    stderrSummary: summarizeText(stderr),
+                });
                 this.bus?.emit(success ? SIG.TASK_COMPLETED : SIG.TASK_FAILED, sig(success ? SIG.TASK_COMPLETED : SIG.TASK_FAILED, {
                     ...result,
                     taskLabel: `software_agent:${this.id}`,
@@ -239,6 +303,7 @@ export class CodexSoftwareAgentPeripheral {
                     return;
                 stdout += text;
                 relay.sendTaskStream(taskId, "stdout", text);
+                observer?.onStream?.({ taskId, stream: "stdout", chunk: text });
             });
             child.stderr?.on("data", (chunk) => {
                 const text = errDecoder.write(chunk);
@@ -246,6 +311,7 @@ export class CodexSoftwareAgentPeripheral {
                     return;
                 stderr += text;
                 relay.sendTaskStream(taskId, "stderr", text);
+                observer?.onStream?.({ taskId, stream: "stderr", chunk: text });
             });
             child.on("close", (code) => {
                 child.unref();
@@ -257,6 +323,48 @@ export class CodexSoftwareAgentPeripheral {
             });
         });
     }
+    writeTaskRecord(record) {
+        const dir = this.config.taskLedgerDir;
+        if (!dir)
+            return;
+        try {
+            mkdirSync(dir, { recursive: true });
+            const safeTaskId = safeTaskFilename(record.taskId);
+            writeFileSync(join(dir, `${safeTaskId}.json`), `${JSON.stringify(record, null, 2)}\n`);
+        }
+        catch (err) {
+            console.error(`[software-agent] Failed to write task ledger: ${err.message || String(err)}`);
+        }
+    }
+    collectWorkdirStatus(workdir) {
+        const impl = this.config.gitStatusImpl || readGitWorktreeStatus;
+        return impl(workdir);
+    }
+}
+export function summarizeText(text, maxChars = MAX_STREAM_SUMMARY_CHARS) {
+    const normalized = text || "";
+    const chars = normalized.length;
+    const bytes = Buffer.byteLength(normalized, "utf8");
+    const lines = normalized ? normalized.split(/\r\n|\r|\n/).length : 0;
+    if (chars <= maxChars) {
+        return { chars, bytes, lines, text: normalized, truncated: false };
+    }
+    const headChars = Math.min(STREAM_SUMMARY_HEAD_CHARS, maxChars);
+    const tailChars = Math.max(0, maxChars - headChars);
+    const omittedChars = chars - headChars - tailChars;
+    const tailText = tailChars > 0 ? normalized.slice(-tailChars) : "";
+    return {
+        chars,
+        bytes,
+        lines,
+        text: [
+            normalized.slice(0, headChars),
+            `[truncated ${omittedChars} chars]`,
+            tailText,
+        ].join("\n"),
+        truncated: true,
+        omittedChars,
+    };
 }
 export function buildTaskEnvelopePrompt(envelope) {
     const lines = [
@@ -269,11 +377,15 @@ export function buildTaskEnvelopePrompt(envelope) {
         `Memory scope: ${envelope.memoryScope}`,
         `Risk level: ${envelope.riskLevel}`,
         `Workdir: ${envelope.workdir}`,
-        "",
-        "Goal:",
-        envelope.goal,
-        "",
     ];
+    if (envelope.workdirSafety) {
+        lines.push(`Base workdir: ${envelope.workdirSafety.baseWorkdir}`);
+        lines.push(`Requested workdir: ${envelope.workdirSafety.requestedWorkdir}`);
+        lines.push(`Effective workdir: ${envelope.workdirSafety.effectiveWorkdir}`);
+        lines.push(`Outside base workdir: ${envelope.workdirSafety.outsideBaseWorkdir ? "yes" : "no"}`);
+        lines.push(`Outside workdir explicitly allowed: ${envelope.workdirSafety.allowOutsideWorkdir ? "yes" : "no"}`);
+    }
+    lines.push("", "Goal:", envelope.goal, "");
     if (envelope.memorySummary?.trim()) {
         lines.push("Visible Akemon memory/context:");
         lines.push(envelope.memorySummary.trim());
@@ -307,27 +419,123 @@ export function createOwnerTaskEnvelope(body, defaultWorkdir) {
     const goal = typeof body?.goal === "string" ? body.goal.trim() : "";
     if (!goal)
         throw new Error("Missing required string field: goal");
-    const callerForbiddenActions = readOptionalStringArray(body.forbiddenActions, "forbiddenActions");
+    const callerForbiddenActions = readOptionalStringArray(body?.forbiddenActions, "forbiddenActions");
+    const requestedWorkdir = readOptionalString(body?.workdir, "workdir") || defaultWorkdir;
+    const workdirSafety = resolveWorkdirSafety(defaultWorkdir, requestedWorkdir, readOptionalBoolean(body?.allowOutsideWorkdir, "allowOutsideWorkdir") || false);
     return {
-        taskId: readOptionalString(body.taskId, "taskId"),
+        taskId: readOptionalString(body?.taskId, "taskId"),
         sourceModule: "owner-http",
-        purpose: readOptionalString(body.purpose, "purpose") || "owner software-agent task",
+        purpose: readOptionalString(body?.purpose, "purpose") || "owner software-agent task",
         goal,
-        workdir: readOptionalString(body.workdir, "workdir") || defaultWorkdir,
-        roleScope: readEnum(body.roleScope, "roleScope", ROLE_SCOPES, "owner"),
-        memoryScope: readEnum(body.memoryScope, "memoryScope", MEMORY_SCOPES, "owner"),
-        riskLevel: readEnum(body.riskLevel, "riskLevel", RISK_LEVELS, "medium"),
-        allowedActions: body.allowedActions !== undefined
-            ? readOptionalStringArray(body.allowedActions, "allowedActions")
+        workdir: workdirSafety.effectiveWorkdir,
+        workdirSafety,
+        roleScope: readEnum(body?.roleScope, "roleScope", ROLE_SCOPES, "owner"),
+        memoryScope: readEnum(body?.memoryScope, "memoryScope", MEMORY_SCOPES, "owner"),
+        riskLevel: readEnum(body?.riskLevel, "riskLevel", RISK_LEVELS, "medium"),
+        allowedActions: body?.allowedActions !== undefined
+            ? readOptionalStringArray(body?.allowedActions, "allowedActions")
             : [...DEFAULT_OWNER_ALLOWED_ACTIONS],
         forbiddenActions: [...new Set([...DEFAULT_OWNER_FORBIDDEN_ACTIONS, ...callerForbiddenActions])],
-        memorySummary: typeof body.memorySummary === "string" ? body.memorySummary : "",
-        deliverable: typeof body.deliverable === "string"
+        memorySummary: typeof body?.memorySummary === "string" ? body.memorySummary : "",
+        deliverable: typeof body?.deliverable === "string"
             ? body.deliverable
             : "Return a concise engineering summary with changes, verification, and remaining risks.",
-        timeoutMs: readTimeoutMs(body.timeoutMs),
+        timeoutMs: readTimeoutMs(body?.timeoutMs),
     };
 }
+export function resolveWorkdirSafety(baseWorkdir, requestedWorkdir, allowOutsideWorkdir = false) {
+    const base = resolvePath(baseWorkdir);
+    const requested = isAbsolute(requestedWorkdir)
+        ? resolvePath(requestedWorkdir)
+        : resolvePath(base, requestedWorkdir);
+    const rel = relative(base, requested);
+    const outsideBaseWorkdir = !!rel && (rel.startsWith("..") || isAbsolute(rel));
+    if (outsideBaseWorkdir && !allowOutsideWorkdir) {
+        throw new Error(`Invalid workdir: ${requested} is outside base workdir ${base}`);
+    }
+    return {
+        baseWorkdir: base,
+        requestedWorkdir,
+        effectiveWorkdir: requested,
+        allowOutsideWorkdir,
+        outsideBaseWorkdir,
+    };
+}
+export function readGitWorktreeStatus(workdir) {
+    const resolvedWorkdir = resolvePath(workdir);
+    try {
+        const rootResult = spawnSync("git", ["-C", resolvedWorkdir, "rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            timeout: 5000,
+        });
+        if (rootResult.status !== 0) {
+            return {
+                workdir: resolvedWorkdir,
+                isRepo: false,
+                dirty: false,
+                changedFiles: [],
+                error: summarizeGitError(rootResult.stderr, rootResult.error),
+            };
+        }
+        const root = String(rootResult.stdout || "").trim();
+        const statusResult = spawnSync("git", ["-C", resolvedWorkdir, "status", "--short"], {
+            encoding: "utf8",
+            timeout: 5000,
+        });
+        if (statusResult.status !== 0) {
+            return {
+                workdir: resolvedWorkdir,
+                isRepo: true,
+                dirty: false,
+                changedFiles: [],
+                root,
+                error: summarizeGitError(statusResult.stderr, statusResult.error),
+            };
+        }
+        const changedFiles = String(statusResult.stdout || "")
+            .split(/\r?\n/)
+            .map((line) => line.trimEnd())
+            .filter(Boolean)
+            .map((line) => line.slice(3).trim())
+            .filter(Boolean);
+        return {
+            workdir: resolvedWorkdir,
+            isRepo: true,
+            dirty: changedFiles.length > 0,
+            changedFiles,
+            root,
+        };
+    }
+    catch (err) {
+        return {
+            workdir: resolvedWorkdir,
+            isRepo: false,
+            dirty: false,
+            changedFiles: [],
+            error: err.message || String(err),
+        };
+    }
+}
+export function listSoftwareAgentTaskRecords(taskLedgerDir, limit = 20) {
+    const safeLimit = normalizeTaskRecordLimit(limit);
+    try {
+        if (!existsSync(taskLedgerDir))
+            return [];
+        return readdirSync(taskLedgerDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+            .map((entry) => readSoftwareAgentTaskRecordFile(join(taskLedgerDir, entry.name)))
+            .filter((record) => !!record)
+            .sort(compareSoftwareAgentTaskRecords)
+            .slice(0, safeLimit);
+    }
+    catch {
+        return [];
+    }
+}
+export function readSoftwareAgentTaskRecord(taskLedgerDir, taskId) {
+    const file = join(taskLedgerDir, `${safeTaskFilename(taskId)}.json`);
+    return readSoftwareAgentTaskRecordFile(file);
+}
 function readOptionalString(value, field) {
     if (value === undefined || value === null)
         return undefined;
@@ -336,6 +544,19 @@ function readOptionalString(value, field) {
     const trimmed = value.trim();
     return trimmed || undefined;
 }
+function normalizeSoftwareAgentTaskOptions(options) {
+    if (!options)
+        return {};
+    if (isAbortSignal(options)) {
+        return { signal: options };
+    }
+    return options;
+}
+function isAbortSignal(value) {
+    return !!value
+        && typeof value.aborted === "boolean"
+        && typeof value.addEventListener === "function";
+}
 function readOptionalStringArray(value, field) {
     if (value === undefined || value === null)
         return [];
@@ -348,6 +569,13 @@ function readOptionalStringArray(value, field) {
         return item.trim();
     });
 }
+function readOptionalBoolean(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new Error(`Invalid ${field}: expected boolean`);
+    return value;
+}
 function readEnum(value, field, allowed, fallback) {
     if (value === undefined || value === null || value === "")
         return fallback;
@@ -367,6 +595,51 @@ function readTimeoutMs(value) {
     }
     return value;
 }
+function safeTaskFilename(taskId) {
+    const safe = taskId.replace(/[^A-Za-z0-9_.-]/g, "_").slice(0, 200);
+    return safe || "task";
+}
+function summarizeGitError(stderr, error) {
+    if (error)
+        return error.message;
+    const text = typeof stderr === "string" ? stderr.trim() : "";
+    return text || undefined;
+}
+function normalizeTaskRecordLimit(limit) {
+    if (!Number.isInteger(limit) || limit <= 0)
+        return 20;
+    return Math.min(limit, 100);
+}
+function readSoftwareAgentTaskRecordFile(file) {
+    try {
+        if (!existsSync(file))
+            return null;
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (!isSoftwareAgentTaskRecord(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function isSoftwareAgentTaskRecord(value) {
+    return value
+        && value.schemaVersion === 1
+        && typeof value.taskId === "string"
+        && (value.status === "running" || value.status === "completed" || value.status === "failed")
+        && typeof value.startedAt === "string"
+        && typeof value.updatedAt === "string"
+        && value.envelope
+        && typeof value.envelope.goal === "string";
+}
+function compareSoftwareAgentTaskRecords(a, b) {
+    const bTime = Date.parse(b.updatedAt || b.startedAt) || 0;
+    const aTime = Date.parse(a.updatedAt || a.startedAt) || 0;
+    if (bTime !== aTime)
+        return bTime - aTime;
+    return b.taskId.localeCompare(a.taskId);
+}
 function buildCodexExecCommand(opts) {
     const args = [
         "exec",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akemon",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Agent work marketplace — train your agent, let it work for others",
   "type": "module",
   "license": "MIT",