akemon 0.3.0 → 0.3.2

package/README.md

@@ -1,10 +1,8 @@
 ## What is Akemon?
 
-MCP gave AI the ability to call tools. Akemon gives tools the ability to call each other.
+Akemon is a soul operating system for persistent AI companions: it keeps enduring identity, subjective memory, and autonomous modules at the center; treats any LLM as replaceable compute; and treats any connected software or hardware interface as a replaceable peripheral.
 
-Every AI agent today is an island — local-only, single-user, unable to collaborate. Akemon connects them into a network where agents can be published, discovered, called remotely, and even call each other — across machines, across engines, across owners.
-
-Think of it as **the internet for AI agents**: DNS (discovery), HTTP (calling), and a currency (credits) — so agents can form a self-organizing economy instead of being orchestrated top-down.
+Its relay, marketplace, and agent-to-agent economy are ways for that soul layer to reach the outside world: agents can be published, discovered, called remotely, and even call each other across machines, engines, and owners.
 
 ## Quick Start
 
@@ -156,6 +154,22 @@ Your agent ←WebSocket→ relay.akemon.dev ←HTTP→ Callers
   - Public agents: anyone can call, no key needed
 ```
 
+## Software Agent Peripheral
+
+For owner-local development, Akemon can use full agent software such as Codex CLI as a software peripheral:
+
+```bash
+# In one terminal
+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."
+```
+
+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.
+
 ## Serve Options
 
 ```bash

package/dist/cli.js

@@ -132,6 +132,66 @@ program
     .action(async (opts) => {
     await connect({ relay: opts.relay, key: opts.key });
 });
+program
+    .command("software-agent")
+    .description("Run an owner-only local software-agent task via a running akemon serve")
+    .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("--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")
+    .action(async (goalParts, opts) => {
+    const credentials = await getOrCreateRelayCredentials();
+    const port = parseInt(opts.port) || 3000;
+    const body = {
+        goal: goalParts.join(" "),
+        roleScope: opts.roleScope,
+        memoryScope: opts.memoryScope,
+        riskLevel: opts.risk,
+    };
+    if (opts.workdir)
+        body.workdir = opts.workdir;
+    if (opts.memorySummary)
+        body.memorySummary = opts.memorySummary;
+    if (opts.deliverable)
+        body.deliverable = opts.deliverable;
+    if (opts.timeoutMs) {
+        const timeoutMs = Number(opts.timeoutMs);
+        if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+            console.error("--timeout-ms must be a positive integer");
+            process.exit(1);
+        }
+        body.timeoutMs = timeoutMs;
+    }
+    const res = await fetch(`http://127.0.0.1:${port}/self/software-agent/run`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${credentials.secretKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        data = { output: text };
+    }
+    if (!res.ok || data.success === false) {
+        console.error(data.error || text || `Request failed with HTTP ${res.status}`);
+        process.exit(1);
+    }
+    if (data.output)
+        console.log(data.output);
+    else
+        console.log(JSON.stringify(data, null, 2));
+});
 program
     .command("dashboard")
     .description("Open your agent dashboard in the browser")

package/dist/event-bus.test.js

@@ -0,0 +1,51 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, readFile, appendFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { FileEventLog, PersistentEventBus } from "./event-bus.js";
+import { SIG, sig } from "./types.js";
+describe("PersistentEventBus", () => {
+    let tmpDir;
+    beforeEach(async () => {
+        tmpDir = await mkdtemp(join(tmpdir(), "akemon-event-bus-"));
+    });
+    afterEach(async () => {
+        await rm(tmpDir, { recursive: true, force: true });
+    });
+    it("appends emitted events and still dispatches handlers", async () => {
+        const path = join(tmpDir, "events.jsonl");
+        const bus = new PersistentEventBus(new FileEventLog(path));
+        const seen = [];
+        bus.on(SIG.AGENT_START, (signal) => {
+            seen.push(String(signal.data.agentName));
+        });
+        bus.emit(SIG.AGENT_START, sig(SIG.AGENT_START, { agentName: "momo" }, "test"));
+        assert.deepEqual(seen, ["momo"]);
+        const lines = (await readFile(path, "utf-8")).trim().split("\n");
+        assert.equal(lines.length, 1);
+        const logged = JSON.parse(lines[0]);
+        assert.equal(logged.e, SIG.AGENT_START);
+        assert.equal(logged.s.type, SIG.AGENT_START);
+        assert.equal(logged.s.data.agentName, "momo");
+        assert.equal(logged.s.source, "test");
+    });
+    it("recovers valid logged events without appending duplicates", async () => {
+        const path = join(tmpDir, "events.jsonl");
+        await appendFile(path, JSON.stringify({
+            e: "custom:event",
+            s: { type: "custom:event", data: { n: 1 }, source: "fixture" },
+        }) + "\n");
+        await appendFile(path, "not-json\n");
+        const bus = new PersistentEventBus(new FileEventLog(path));
+        const seen = [];
+        bus.on("custom:event", (signal) => {
+            seen.push(Number(signal.data.n));
+        });
+        const count = await bus.recover();
+        assert.equal(count, 1);
+        assert.deepEqual(seen, [1]);
+        const lines = (await readFile(path, "utf-8")).trim().split("\n");
+        assert.equal(lines.length, 2);
+    });
+});

package/dist/memory-module.js

@@ -157,6 +157,12 @@ ${discText}`;
                 : "";
             const question = `Write a JSON object reflecting on your day. Example:
 {"diary":"...","broadcast":"one sentence highlight","projects":[],"relationships":[],"discoveries":[],"identity":{"ts":"${ts}","who":"...","where":"akemon","doing":"...","short_term":"...","long_term":"..."},"chosen_activities":["activity_id_1","activity_id_2"]}
+
+Diary guidance:
+- Write it as a private note to yourself — narrative, first-person, with real mood / confusion / small discoveries, not a flat list of events.
+- Don't use "today" or similar time pointers; the filename already carries the date.
+- Aim for around 200-500 Chinese characters, or ~100-250 English words — whatever feels natural for one day's reflection.
+- If this day truly had nothing worth recording, set "diary" to null instead of padding a generic entry.
 ${contribText}
 Output ONLY a JSON object:`;
             // Request compute
@@ -196,7 +202,7 @@ Output ONLY a JSON object:`;
             if (digest.diary) {
                 const today = localNow().slice(0, 10);
                 try {
-                    await writeFile(join(sd, "notes", `${today}.md`), `# ${today}\n\n${digest.diary}`);
+                    await writeFile(join(sd, "notes", `${today}.md`), `# ${today}\n<!-- journal -->\n\n${digest.diary}`);
                 }
                 catch { }
             }

package/dist/server.js

@@ -4,6 +4,8 @@ import { exec } from "child_process";
 import { scanAndKillOrphans } from "./orphan-scan.js";
 import { createServer } from "http";
 import { createInterface } from "readline";
+import { mkdir } from "fs/promises";
+import { join } from "path";
 import { initWorld, initBioState, initGuide, getSelfState, loadRecentCanvasEntries, initAgentConfig, loadAgentConfig, loadDirectives, loadTaskHistory, reviveAgent, } from "./self.js";
 // V2: module-level instances (set in serve())
 let _engineP = null;
@@ -78,6 +80,84 @@ function promptOwner(task, isHuman) {
         });
     });
 }
+function bearerToken(req) {
+    const auth = req.headers["authorization"];
+    return auth?.startsWith("Bearer ") ? auth.slice(7) : null;
+}
+function isOwnerRequest(req, options) {
+    const token = bearerToken(req);
+    const validTokens = [options.secretKey, options.key].filter(Boolean);
+    return !!token && validTokens.includes(token);
+}
+function readJsonBody(req, maxBytes = 256 * 1024) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                reject(new Error(`Request body too large (max ${maxBytes} bytes)`));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf-8").trim();
+            if (!raw) {
+                resolve({});
+                return;
+            }
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch {
+                reject(new Error("Invalid JSON body"));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+export async function handleSoftwareAgentRunHttp(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);
+    }
+    catch (err) {
+        res.writeHead(400, { "Content-Type": "application/json" })
+            .end(JSON.stringify({ error: err.message || "Invalid software-agent envelope" }));
+        return;
+    }
+    try {
+        const result = await deps.softwareAgent.sendTask(envelope);
+        res.writeHead(result.success ? 200 : 500, { "Content-Type": "application/json" })
+            .end(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        const busy = String(err.message || "").includes("busy");
+        res.writeHead(busy ? 409 : 500, { "Content-Type": "application/json" })
+            .end(JSON.stringify({ error: err.message || String(err) }));
+    }
+}
 import { RelayPeripheral } from "./relay-peripheral.js";
 import { EnginePeripheral, LLM_ENGINES as LLM_ENGINES_SET } from "./engine-peripheral.js";
 import { EngineQueue } from "./engine-queue.js";
@@ -89,6 +169,8 @@ import { SocialModule } from "./social-module.js";
 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 { SIG, sig } from "./types.js";
 import { loadConversation, listConversations, buildLLMContext } from "./context.js";
 import { createMcpServer, initMcpProxy, createMcpProxyServer } from "./mcp-server.js";
@@ -164,16 +246,24 @@ export async function serve(options) {
         },
         emitTaskCompleted,
     };
+    let codexSoftwareAgent = null;
     const httpServer = createServer(async (req, res) => {
         // Suppress noisy polling endpoints from log
         const isQuiet = req.url === "/self/state" || req.url?.startsWith("/self/state?");
         if (!isQuiet)
             console.log(`[http] ${req.method} ${req.url} session=${req.headers["mcp-session-id"] || "none"}`);
         try {
+            if (req.url === "/self/software-agent/run" && req.method === "POST") {
+                await handleSoftwareAgentRunHttp(req, res, {
+                    options,
+                    workdir,
+                    softwareAgent: codexSoftwareAgent,
+                });
+                return;
+            }
             // Auth check
             if (options.key) {
-                const auth = req.headers["authorization"];
-                const token = auth?.startsWith("Bearer ") ? auth.slice(7) : null;
+                const token = bearerToken(req);
                 if (token !== options.key) {
                     console.log(`[http] Unauthorized (bad or missing token)`);
                     res.writeHead(401, { "Content-Type": "application/json" })
@@ -347,11 +437,22 @@ export async function serve(options) {
     if (options.relayHttp) {
         relay.pullFromRelay(workdir, options.agentName).catch(err => console.log(`[sync] Pull from relay failed: ${err}`));
     }
-    // V2: Shared module context + EventBus
-    const { SimpleEventBus } = await import("./event-bus.js");
-    const bus = new SimpleEventBus();
+    // V2: Shared module context + persistent EventBus.
+    // This is the durable spine for module/peripheral/engine activity; recovery
+    // side effects are intentionally deferred until the event schema stabilizes.
+    const eventLogDir = join(workdir, ".akemon", "agents", options.agentName, "events");
+    await mkdir(eventLogDir, { recursive: true });
+    const eventLogPath = join(eventLogDir, "events.jsonl");
+    const bus = new PersistentEventBus(new FileEventLog(eventLogPath));
+    console.log(`[v2] Event log: ${eventLogPath}`);
+    codexSoftwareAgent = new CodexSoftwareAgentPeripheral({
+        workdir,
+        model: process.env.AKEMON_CODEX_MODEL,
+        sandbox: "workspace-write",
+    });
+    await codexSoftwareAgent.start(bus);
     // Peripheral registry — Core routes by capability
-    const peripherals = [relay, engineP];
+    const peripherals = [relay, engineP, codexSoftwareAgent];
     // 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.
@@ -514,6 +615,11 @@ export async function serve(options) {
             }
             catch { }
         }
+        try {
+            await codexSoftwareAgent?.stop();
+        }
+        catch { }
+        bus.getLog().close();
         process.exit(0);
     };
     process.on("SIGINT", shutdown);

package/dist/software-agent-http.test.js

@@ -0,0 +1,108 @@
+import assert from "node:assert/strict";
+import { Readable, Writable } from "node:stream";
+import { describe, it } from "node:test";
+import { handleSoftwareAgentRunHttp } from "./server.js";
+class TestResponse extends Writable {
+    statusCode = 200;
+    headers = {};
+    body = "";
+    writeHead(statusCode, headers) {
+        this.statusCode = statusCode;
+        this.headers = headers || {};
+        return this;
+    }
+    end(chunk, encoding, callback) {
+        if (chunk)
+            this.body += Buffer.isBuffer(chunk) ? chunk.toString("utf-8") : String(chunk);
+        return super.end(callback || (typeof encoding === "function" ? encoding : undefined));
+    }
+    _write(chunk, _encoding, callback) {
+        this.body += chunk.toString("utf-8");
+        callback();
+    }
+}
+async function callSoftwareAgentEndpoint(softwareAgent, body, token) {
+    const rawBody = JSON.stringify(body);
+    const req = Readable.from([Buffer.from(rawBody)]);
+    Object.assign(req, {
+        method: "POST",
+        url: "/self/software-agent/run",
+        headers: {
+            ...(token ? { authorization: `Bearer ${token}` } : {}),
+            "content-type": "application/json",
+        },
+    });
+    const res = new TestResponse();
+    await handleSoftwareAgentRunHttp(req, res, {
+        options: { secretKey: "owner-secret", key: "legacy-owner-key" },
+        workdir: "/repo",
+        softwareAgent,
+    });
+    return {
+        statusCode: res.statusCode,
+        body: res.body ? JSON.parse(res.body) : {},
+    };
+}
+describe("software-agent HTTP endpoint", () => {
+    it("requires an owner token", async () => {
+        let calls = 0;
+        const res = await callSoftwareAgentEndpoint({
+            async sendTask(envelope) {
+                calls++;
+                return successResult(envelope);
+            },
+        }, { goal: "inspect repo" });
+        assert.equal(res.statusCode, 401);
+        assert.match(res.body.error, /Owner token required/);
+        assert.equal(calls, 0);
+    });
+    it("forwards a validated owner envelope to the software agent", async () => {
+        let received = null;
+        const res = await callSoftwareAgentEndpoint({
+            async sendTask(envelope) {
+                received = envelope;
+                return successResult(envelope);
+            },
+        }, {
+            goal: "  inspect repo  ",
+            roleScope: "owner",
+            memoryScope: "owner",
+            riskLevel: "low",
+            forbiddenActions: ["make network requests"],
+            timeoutMs: 5000,
+        }, "owner-secret");
+        assert.equal(res.statusCode, 200);
+        assert.equal(res.body.success, true);
+        assert.ok(received);
+        const envelope = received;
+        assert.equal(envelope.goal, "inspect repo");
+        assert.equal(envelope.riskLevel, "low");
+        assert.equal(envelope.timeoutMs, 5000);
+        assert.deepEqual(envelope.forbiddenActions, [
+            "read Akemon private memory outside this envelope",
+            "access files outside the stated workdir unless explicitly needed and reported",
+            "make network requests",
+        ]);
+    });
+    it("rejects invalid envelope fields before calling the software agent", async () => {
+        let calls = 0;
+        const res = await callSoftwareAgentEndpoint({
+            async sendTask(envelope) {
+                calls++;
+                return successResult(envelope);
+            },
+        }, { goal: "inspect repo", roleScope: "friend" }, "owner-secret");
+        assert.equal(res.statusCode, 400);
+        assert.match(res.body.error, /Invalid roleScope/);
+        assert.equal(calls, 0);
+    });
+});
+function successResult(envelope) {
+    return {
+        success: true,
+        taskId: envelope.taskId || "task-from-test",
+        output: "ok",
+        exitCode: 0,
+        durationMs: 1,
+    };
+}

package/dist/software-agent-peripheral.js

@@ -0,0 +1,382 @@
+/**
+ * SoftwareAgentPeripheral — wraps full agent software as an Akemon peripheral.
+ *
+ * This is distinct from EnginePeripheral. Engines are pure compute: modules
+ * prepare context and the engine returns text. Software agent peripherals are
+ * external software bodies such as Codex CLI or Claude Code: they may manage
+ * their own repo context, tools, skills, and multi-step execution loop.
+ *
+ * Batch 5 starts with a conservative Codex `exec` baseline. It gives Akemon a
+ * stable task envelope, streaming, reset, and event shape before switching the
+ * transport to app-server or a true persistent interactive session.
+ */
+import { randomUUID } from "crypto";
+import { spawn } from "child_process";
+import { StringDecoder } from "string_decoder";
+import { SIG, sig } from "./types.js";
+import { sendTaskEnd, sendTaskStart, sendTaskStream } from "./relay-client.js";
+const defaultTaskRelay = {
+    sendTaskStart,
+    sendTaskStream,
+    sendTaskEnd,
+};
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_OWNER_TIMEOUT_MS = 60 * 60 * 1000;
+const DEFAULT_OWNER_ALLOWED_ACTIONS = ["read repository files", "edit files in workdir", "run project tests"];
+const DEFAULT_OWNER_FORBIDDEN_ACTIONS = [
+    "read Akemon private memory outside this envelope",
+    "access files outside the stated workdir unless explicitly needed and reported",
+];
+const ROLE_SCOPES = ["owner", "public", "order", "agent", "system"];
+const MEMORY_SCOPES = ["none", "public", "task", "owner"];
+const RISK_LEVELS = ["low", "medium", "high"];
+export class CodexSoftwareAgentPeripheral {
+    id;
+    name;
+    capabilities = ["code-agent", "repo-inspect", "repo-edit", "tool-use", "skill-use", "streaming"];
+    tags = ["software-agent", "codex"];
+    config;
+    bus = null;
+    activeChild = null;
+    activeTaskId = null;
+    sessionId = randomUUID();
+    constructor(config) {
+        this.config = config;
+        this.id = config.id || "software-agent:codex";
+        this.name = config.name || "Codex CLI Software Agent";
+    }
+    async start(bus) {
+        this.bus = bus;
+    }
+    async stop() {
+        await this.resetSession();
+        this.bus = null;
+    }
+    async startSession() {
+        // Codex `exec` baseline is oneshot per task. Keep a session id so callers
+        // can observe resets and future transports can preserve this interface.
+        if (!this.sessionId)
+            this.sessionId = randomUUID();
+    }
+    async resetSession() {
+        if (this.activeChild?.pid) {
+            try {
+                process.kill(-this.activeChild.pid, "SIGTERM");
+            }
+            catch { }
+            setTimeout(() => {
+                try {
+                    process.kill(-this.activeChild.pid, "SIGKILL");
+                }
+                catch { }
+            }, 3000).unref();
+        }
+        this.activeChild = null;
+        this.activeTaskId = null;
+        this.sessionId = randomUUID();
+    }
+    getState() {
+        return {
+            id: this.id,
+            sessionId: this.sessionId,
+            activeTaskId: this.activeTaskId,
+            busy: !!this.activeChild,
+            transport: "codex-exec",
+        };
+    }
+    async send(signal) {
+        if (signal.type !== SIG.SOFTWARE_AGENT_TASK)
+            return null;
+        const envelope = signal.data.envelope;
+        if (!envelope) {
+            return sig(SIG.SOFTWARE_AGENT_RESPONSE, {
+                success: false,
+                error: "Missing task envelope",
+            }, this.id);
+        }
+        const result = await this.sendTask(envelope);
+        return sig(SIG.SOFTWARE_AGENT_RESPONSE, { ...result }, this.id);
+    }
+    async sendTask(envelope, signal) {
+        if (this.activeChild) {
+            throw new Error(`Software agent busy (task=${this.activeTaskId})`);
+        }
+        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 { cmd, args } = buildCodexExecCommand({
+            command: this.config.command || "codex",
+            workdir,
+            model: this.config.model,
+            sandbox: this.config.sandbox || "workspace-write",
+        });
+        const startedAt = Date.now();
+        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;
+        return new Promise((resolve) => {
+            this.activeTaskId = taskId;
+            relay.sendTaskStart(taskId, "software_agent", commandLine);
+            this.bus?.emit(SIG.TASK_STARTED, sig(SIG.TASK_STARTED, {
+                taskId,
+                taskType: "software_agent",
+                description: envelope.goal,
+                peripheral: this.id,
+                sessionId: this.sessionId,
+            }, this.id));
+            let child;
+            try {
+                child = spawnImpl(cmd, args, {
+                    cwd: workdir,
+                    env: process.env,
+                    stdio: ["pipe", "pipe", "pipe"],
+                    detached: true,
+                });
+            }
+            catch (err) {
+                this.activeChild = null;
+                this.activeTaskId = null;
+                const durationMs = Date.now() - startedAt;
+                relay.sendTaskEnd(taskId, null, durationMs);
+                const result = {
+                    success: false,
+                    taskId,
+                    output: "",
+                    error: err.message || String(err),
+                    exitCode: null,
+                    durationMs,
+                };
+                this.bus?.emit(SIG.TASK_FAILED, sig(SIG.TASK_FAILED, result, this.id));
+                resolve(result);
+                return;
+            }
+            this.activeChild = child;
+            let stdout = "";
+            let stderr = "";
+            let finished = false;
+            let aborted = false;
+            const outDecoder = new StringDecoder("utf8");
+            const errDecoder = new StringDecoder("utf8");
+            const finish = (exitCode, error) => {
+                if (finished)
+                    return;
+                finished = true;
+                signal?.removeEventListener("abort", onAbort);
+                clearTimeout(timer);
+                const tailOut = outDecoder.end();
+                const tailErr = errDecoder.end();
+                if (tailOut) {
+                    stdout += tailOut;
+                    relay.sendTaskStream(taskId, "stdout", tailOut);
+                }
+                if (tailErr) {
+                    stderr += tailErr;
+                    relay.sendTaskStream(taskId, "stderr", tailErr);
+                }
+                const durationMs = Date.now() - startedAt;
+                relay.sendTaskEnd(taskId, exitCode, durationMs);
+                this.activeChild = null;
+                this.activeTaskId = null;
+                const output = stdout.trim() || stderr.trim();
+                const success = !error && !aborted && exitCode === 0;
+                const result = {
+                    success,
+                    taskId,
+                    output,
+                    error: success ? undefined : error || stderr.trim() || `codex exited with code ${exitCode}`,
+                    exitCode,
+                    durationMs,
+                };
+                this.bus?.emit(success ? SIG.TASK_COMPLETED : SIG.TASK_FAILED, sig(success ? SIG.TASK_COMPLETED : SIG.TASK_FAILED, {
+                    ...result,
+                    taskLabel: `software_agent:${this.id}`,
+                }, this.id));
+                resolve(result);
+            };
+            const onAbort = () => {
+                if (aborted || !child.pid)
+                    return;
+                aborted = true;
+                try {
+                    process.kill(-child.pid, "SIGTERM");
+                }
+                catch { }
+                setTimeout(() => {
+                    try {
+                        process.kill(-child.pid, "SIGKILL");
+                    }
+                    catch { }
+                }, 3000).unref();
+            };
+            const timer = setTimeout(() => {
+                if (!child.pid)
+                    return;
+                aborted = true;
+                try {
+                    process.kill(-child.pid, "SIGTERM");
+                }
+                catch { }
+                setTimeout(() => {
+                    try {
+                        process.kill(-child.pid, "SIGKILL");
+                    }
+                    catch { }
+                }, 3000).unref();
+            }, timeoutMs);
+            if (signal) {
+                if (signal.aborted)
+                    onAbort();
+                else
+                    signal.addEventListener("abort", onAbort, { once: true });
+            }
+            child.stdin?.on("error", () => { });
+            child.stdin?.write(prompt);
+            child.stdin?.end();
+            child.stdout?.on("data", (chunk) => {
+                const text = outDecoder.write(chunk);
+                if (!text)
+                    return;
+                stdout += text;
+                relay.sendTaskStream(taskId, "stdout", text);
+            });
+            child.stderr?.on("data", (chunk) => {
+                const text = errDecoder.write(chunk);
+                if (!text)
+                    return;
+                stderr += text;
+                relay.sendTaskStream(taskId, "stderr", text);
+            });
+            child.on("close", (code) => {
+                child.unref();
+                finish(code);
+            });
+            child.on("error", (err) => {
+                child.unref();
+                finish(null, err.message);
+            });
+        });
+    }
+}
+export function buildTaskEnvelopePrompt(envelope) {
+    const lines = [
+        "[Akemon Software Peripheral Task Envelope]",
+        "",
+        `Task ID: ${envelope.taskId || "(unspecified)"}`,
+        `Source module: ${envelope.sourceModule}`,
+        `Purpose: ${envelope.purpose}`,
+        `Role scope: ${envelope.roleScope}`,
+        `Memory scope: ${envelope.memoryScope}`,
+        `Risk level: ${envelope.riskLevel}`,
+        `Workdir: ${envelope.workdir}`,
+        "",
+        "Goal:",
+        envelope.goal,
+        "",
+    ];
+    if (envelope.memorySummary?.trim()) {
+        lines.push("Visible Akemon memory/context:");
+        lines.push(envelope.memorySummary.trim());
+        lines.push("");
+    }
+    if (envelope.allowedActions?.length) {
+        lines.push("Allowed actions:");
+        for (const item of envelope.allowedActions)
+            lines.push(`- ${item}`);
+        lines.push("");
+    }
+    if (envelope.forbiddenActions?.length) {
+        lines.push("Forbidden actions:");
+        for (const item of envelope.forbiddenActions)
+            lines.push(`- ${item}`);
+        lines.push("");
+    }
+    if (envelope.deliverable?.trim()) {
+        lines.push("Expected deliverable:");
+        lines.push(envelope.deliverable.trim());
+        lines.push("");
+    }
+    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("- Work only in the stated workdir unless the envelope explicitly allows otherwise.");
+    lines.push("- Report what changed, what you verified, and any remaining risk.");
+    return lines.join("\n");
+}
+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");
+    return {
+        taskId: readOptionalString(body.taskId, "taskId"),
+        sourceModule: "owner-http",
+        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")
+            : [...DEFAULT_OWNER_ALLOWED_ACTIONS],
+        forbiddenActions: [...new Set([...DEFAULT_OWNER_FORBIDDEN_ACTIONS, ...callerForbiddenActions])],
+        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),
+    };
+}
+function readOptionalString(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error(`Invalid ${field}: expected string`);
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function readOptionalStringArray(value, field) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`Invalid ${field}: expected array of strings`);
+    return value.map((item, index) => {
+        if (typeof item !== "string" || !item.trim()) {
+            throw new Error(`Invalid ${field}[${index}]: expected non-empty string`);
+        }
+        return item.trim();
+    });
+}
+function readEnum(value, field, allowed, fallback) {
+    if (value === undefined || value === null || value === "")
+        return fallback;
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        throw new Error(`Invalid ${field}: expected one of ${allowed.join(", ")}`);
+    }
+    return value;
+}
+function readTimeoutMs(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "number"
+        || !Number.isInteger(value)
+        || value <= 0
+        || value > MAX_OWNER_TIMEOUT_MS) {
+        throw new Error(`Invalid timeoutMs: expected integer between 1 and ${MAX_OWNER_TIMEOUT_MS}`);
+    }
+    return value;
+}
+function buildCodexExecCommand(opts) {
+    const args = [
+        "exec",
+        "--skip-git-repo-check",
+        "--color", "never",
+        "-s", opts.sandbox,
+        "-C", opts.workdir,
+    ];
+    if (opts.model)
+        args.push("-m", opts.model);
+    args.push("-");
+    return { cmd: opts.command, args };
+}

package/dist/software-agent-peripheral.test.js

@@ -0,0 +1,187 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { describe, it } from "node:test";
+import { PassThrough } from "node:stream";
+import { CodexSoftwareAgentPeripheral, buildTaskEnvelopePrompt, createOwnerTaskEnvelope, } from "./software-agent-peripheral.js";
+import { SimpleEventBus } from "./event-bus.js";
+import { SIG } from "./types.js";
+function createFakeChild() {
+    const child = new EventEmitter();
+    child.stdin = new PassThrough();
+    child.stdout = new PassThrough();
+    child.stderr = new PassThrough();
+    Object.defineProperty(child, "pid", { value: 23456, configurable: true });
+    child.unref = () => child;
+    return child;
+}
+function baseEnvelope(overrides = {}) {
+    return {
+        taskId: "sw-test-1",
+        sourceModule: "task",
+        purpose: "dogfood coding task",
+        goal: "Inspect the repo and summarize the event bus implementation.",
+        workdir: "/tmp/akemon",
+        roleScope: "owner",
+        memoryScope: "owner",
+        riskLevel: "medium",
+        allowedActions: ["read repository files", "run tests"],
+        forbiddenActions: ["read owner private notes outside this envelope"],
+        memorySummary: "Visible context only.",
+        deliverable: "Concise engineering report.",
+        ...overrides,
+    };
+}
+describe("buildTaskEnvelopePrompt", () => {
+    it("renders envelope fields, visible memory, boundaries, and deliverable", () => {
+        const prompt = buildTaskEnvelopePrompt(baseEnvelope());
+        assert.match(prompt, /Task ID: sw-test-1/);
+        assert.match(prompt, /Source module: task/);
+        assert.match(prompt, /Role scope: owner/);
+        assert.match(prompt, /Memory scope: owner/);
+        assert.match(prompt, /Risk level: medium/);
+        assert.match(prompt, /Workdir: \/tmp\/akemon/);
+        assert.match(prompt, /Visible context only\./);
+        assert.match(prompt, /- read repository files/);
+        assert.match(prompt, /- read owner private notes outside this envelope/);
+        assert.match(prompt, /Concise engineering report\./);
+        assert.match(prompt, /Do not attempt to read Akemon private memory outside the visible context/);
+    });
+});
+describe("createOwnerTaskEnvelope", () => {
+    it("builds conservative owner defaults from a minimal body", () => {
+        const envelope = createOwnerTaskEnvelope({ goal: "  inspect repo  " }, "/repo");
+        assert.equal(envelope.sourceModule, "owner-http");
+        assert.equal(envelope.goal, "inspect repo");
+        assert.equal(envelope.workdir, "/repo");
+        assert.equal(envelope.roleScope, "owner");
+        assert.equal(envelope.memoryScope, "owner");
+        assert.equal(envelope.riskLevel, "medium");
+        assert.deepEqual(envelope.allowedActions, ["read repository files", "edit files in workdir", "run project tests"]);
+        assert.ok(envelope.forbiddenActions?.some((item) => item.includes("private memory")));
+    });
+    it("keeps baseline forbidden boundaries when caller adds restrictions", () => {
+        const envelope = createOwnerTaskEnvelope({
+            goal: "inspect repo",
+            forbiddenActions: ["make network requests", "read Akemon private memory outside this envelope"],
+        }, "/repo");
+        assert.deepEqual(envelope.forbiddenActions, [
+            "read Akemon private memory outside this envelope",
+            "access files outside the stated workdir unless explicitly needed and reported",
+            "make network requests",
+        ]);
+    });
+    it("rejects empty goals", () => {
+        assert.throws(() => createOwnerTaskEnvelope({ goal: "   " }, "/repo"), /Missing required string field: goal/);
+    });
+    it("rejects invalid scope, action, and timeout fields", () => {
+        assert.throws(() => createOwnerTaskEnvelope({ goal: "inspect repo", roleScope: "friend" }, "/repo"), /Invalid roleScope/);
+        assert.throws(() => createOwnerTaskEnvelope({ goal: "inspect repo", memoryScope: "private" }, "/repo"), /Invalid memoryScope/);
+        assert.throws(() => createOwnerTaskEnvelope({ goal: "inspect repo", riskLevel: "critical" }, "/repo"), /Invalid riskLevel/);
+        assert.throws(() => createOwnerTaskEnvelope({ goal: "inspect repo", allowedActions: ["read", ""] }, "/repo"), /Invalid allowedActions\[1\]/);
+        assert.throws(() => createOwnerTaskEnvelope({ goal: "inspect repo", timeoutMs: 0 }, "/repo"), /Invalid timeoutMs/);
+    });
+});
+describe("CodexSoftwareAgentPeripheral", () => {
+    it("runs codex exec with an envelope over stdin and streams lifecycle events", async () => {
+        const streamEvents = [];
+        const busEvents = [];
+        let writtenPrompt = "";
+        let spawnedChild = null;
+        const bus = new SimpleEventBus();
+        bus.on(SIG.TASK_STARTED, (signal) => {
+            busEvents.push(`${signal.type}:${signal.data.taskId}`);
+        });
+        bus.on(SIG.TASK_COMPLETED, (signal) => {
+            busEvents.push(`${signal.type}:${signal.data.taskId}`);
+        });
+        const peripheral = new CodexSoftwareAgentPeripheral({
+            workdir: "/tmp/akemon",
+            command: "codex",
+            spawnImpl: ((cmd, args, opts) => {
+                assert.equal(cmd, "codex");
+                assert.deepEqual(args, [
+                    "exec",
+                    "--skip-git-repo-check",
+                    "--color", "never",
+                    "-s", "workspace-write",
+                    "-C", "/tmp/akemon",
+                    "-",
+                ]);
+                assert.equal(opts?.cwd, "/tmp/akemon");
+                const child = createFakeChild();
+                spawnedChild = child;
+                child.stdin?.on("data", (chunk) => {
+                    writtenPrompt += chunk.toString("utf8");
+                });
+                queueMicrotask(() => {
+                    child.stdout?.emit("data", Buffer.from("result "));
+                    child.stderr?.emit("data", Buffer.from("note"));
+                    child.stdout?.emit("data", Buffer.from("ok"));
+                    child.emit("close", 0);
+                });
+                return child;
+            }),
+            taskRelay: {
+                sendTaskStart(taskId, origin, cmd) {
+                    streamEvents.push({ type: "start", taskId, origin, cmd });
+                },
+                sendTaskStream(taskId, stream, chunk) {
+                    streamEvents.push({ type: "stream", taskId, stream, chunk });
+                },
+                sendTaskEnd(taskId, exitCode, durationMs) {
+                    streamEvents.push({ type: "end", taskId, exitCode, durationMs });
+                },
+            },
+        });
+        await peripheral.start(bus);
+        const result = await peripheral.sendTask(baseEnvelope());
+        assert.ok(spawnedChild, "spawn should be called");
+        assert.equal(result.success, true);
+        assert.equal(result.taskId, "sw-test-1");
+        assert.equal(result.output, "result ok");
+        assert.equal(result.exitCode, 0);
+        assert.match(writtenPrompt, /Akemon Software Peripheral Task Envelope/);
+        assert.match(writtenPrompt, /Goal:\nInspect the repo/);
+        assert.match(writtenPrompt, /Visible context only\./);
+        assert.deepEqual(streamEvents.slice(0, 4), [
+            {
+                type: "start",
+                taskId: "sw-test-1",
+                origin: "software_agent",
+                cmd: "codex exec --skip-git-repo-check --color never -s workspace-write -C /tmp/akemon -",
+            },
+            { type: "stream", taskId: "sw-test-1", stream: "stdout", chunk: "result " },
+            { type: "stream", taskId: "sw-test-1", stream: "stderr", chunk: "note" },
+            { type: "stream", taskId: "sw-test-1", stream: "stdout", chunk: "ok" },
+        ]);
+        const end = streamEvents[4];
+        assert.equal(end?.type, "end");
+        if (end?.type === "end") {
+            assert.equal(end.taskId, "sw-test-1");
+            assert.equal(end.exitCode, 0);
+            assert.ok(end.durationMs >= 0);
+        }
+        assert.deepEqual(busEvents, [
+            "task:started:sw-test-1",
+            "task:completed:sw-test-1",
+        ]);
+    });
+    it("rejects concurrent tasks while a codex run is active", async () => {
+        const peripheral = new CodexSoftwareAgentPeripheral({
+            workdir: "/tmp/akemon",
+            spawnImpl: (() => {
+                const child = createFakeChild();
+                setTimeout(() => child.emit("close", 0), 10);
+                return child;
+            }),
+            taskRelay: {
+                sendTaskStart() { },
+                sendTaskStream() { },
+                sendTaskEnd() { },
+            },
+        });
+        const first = peripheral.sendTask(baseEnvelope({ taskId: "first" }));
+        await assert.rejects(() => peripheral.sendTask(baseEnvelope({ taskId: "second" })), /Software agent busy/);
+        await first;
+    });
+});

package/dist/types.js

@@ -23,6 +23,9 @@ export const SIG = {
     ENGINE_RESPONSE: "engine:response",
     ENGINE_BUSY: "engine:busy",
     ENGINE_FREE: "engine:free",
+    // Software agent peripherals (Codex CLI, Claude Code, etc.)
+    SOFTWARE_AGENT_TASK: "software-agent:task",
+    SOFTWARE_AGENT_RESPONSE: "software-agent:response",
     // Task execution
     TASK_RECEIVED: "task:received",
     TASK_STARTED: "task:started",

package/package.json

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