akemon 0.3.1 → 0.3.3

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/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,12 +1,12 @@
 {
   "name": "akemon",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Agent work marketplace — train your agent, let it work for others",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/lhead/akemon"
+    "url": "git+https://github.com/lhead/akemon.git"
   },
   "keywords": [
     "ai",
@@ -18,7 +18,7 @@
     "gemini"
   ],
   "bin": {
-    "akemon": "./dist/cli.js"
+    "akemon": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -26,7 +26,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc && cp src/live.html dist/live.html",
+    "build": "rm -rf dist && tsc && cp src/live.html dist/live.html",
     "dev": "tsc --watch",
     "start": "node dist/cli.js",
     "postinstall": "node scripts/fix-node-pty.cjs",

package/dist/context.test.js

@@ -1,90 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it, before, after } from "node:test";
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-// We import the functions we need to test. appendMessage and loadConversation
-// need a workdir on disk; parseConversation is internal — tested via loadConversation.
-import { appendMessage, loadConversation } from "./context.js";
-const agentName = "test-agent";
-// ---------------------------------------------------------------------------
-// appendMessage + loadConversation round-trip
-// ---------------------------------------------------------------------------
-describe("appendMessage / loadConversation", () => {
-    let workdir = "";
-    before(async () => {
-        workdir = await mkdtemp(join(tmpdir(), "ctx-test-"));
-    });
-    after(async () => {
-        await rm(workdir, { recursive: true, force: true });
-    });
-    it("writes a chat message and reads it back with kind='chat'", async () => {
-        const convId = "test-chat";
-        await appendMessage(workdir, agentName, convId, "User", "hello", "chat");
-        const conv = await loadConversation(workdir, agentName, convId);
-        assert.equal(conv.rounds.length, 1);
-        assert.equal(conv.rounds[0].role, "user");
-        assert.equal(conv.rounds[0].content, "hello");
-        assert.equal(conv.rounds[0].kind, "chat");
-    });
-    it("writes an order message with [order] tag and reads kind='order'", async () => {
-        const convId = "test-order";
-        await appendMessage(workdir, agentName, convId, "User", "order request", "order");
-        await appendMessage(workdir, agentName, convId, "Agent", "order delivered", "order");
-        const conv = await loadConversation(workdir, agentName, convId);
-        assert.equal(conv.rounds.length, 2);
-        assert.equal(conv.rounds[0].kind, "order");
-        assert.equal(conv.rounds[0].role, "user");
-        assert.equal(conv.rounds[1].kind, "order");
-        assert.equal(conv.rounds[1].role, "agent");
-    });
-    it("defaults to kind='chat' when kind arg is omitted", async () => {
-        const convId = "test-default-kind";
-        await appendMessage(workdir, agentName, convId, "Agent", "hi there");
-        const conv = await loadConversation(workdir, agentName, convId);
-        assert.equal(conv.rounds[0].kind, "chat");
-    });
-    it("parses mixed chat + order rounds correctly", async () => {
-        const convId = "test-mixed";
-        await appendMessage(workdir, agentName, convId, "User", "chat message", "chat");
-        await appendMessage(workdir, agentName, convId, "User", "order task", "order");
-        await appendMessage(workdir, agentName, convId, "Agent", "chat reply", "chat");
-        await appendMessage(workdir, agentName, convId, "Agent", "order result", "order");
-        const conv = await loadConversation(workdir, agentName, convId);
-        assert.equal(conv.rounds.length, 4);
-        assert.equal(conv.rounds[0].kind, "chat");
-        assert.equal(conv.rounds[1].kind, "order");
-        assert.equal(conv.rounds[2].kind, "chat");
-        assert.equal(conv.rounds[3].kind, "order");
-    });
-    it("parses legacy file (no [kind] tag) as kind='chat' for backward-compat", async () => {
-        const convId = "test-legacy";
-        // Write a legacy-style file manually (no [order] tag)
-        const { mkdir, writeFile } = await import("node:fs/promises");
-        const dir = join(workdir, ".akemon", "agents", agentName, "conversations");
-        await mkdir(dir, { recursive: true });
-        const legacyContent = "## Summary\n\n\n## Recent\n[2026-04-23 10:00] User: old message\n[2026-04-23 10:01] Agent: old reply\n";
-        await writeFile(join(dir, `${convId}.md`), legacyContent);
-        const conv = await loadConversation(workdir, agentName, convId);
-        assert.equal(conv.rounds.length, 2);
-        assert.equal(conv.rounds[0].kind, "chat");
-        assert.equal(conv.rounds[1].kind, "chat");
-    });
-    it("[order] tag appears in the raw file content", async () => {
-        const convId = "test-tag-on-disk";
-        await appendMessage(workdir, agentName, convId, "User", "buy something", "order");
-        const { readFile: rf } = await import("node:fs/promises");
-        const dir = join(workdir, ".akemon", "agents", agentName, "conversations");
-        const raw = await rf(join(dir, `${convId}.md`), "utf-8");
-        assert.ok(raw.includes("[order] User: buy something"), `raw file should contain [order] tag: ${raw}`);
-    });
-    it("chat message does NOT have [order] tag in raw file", async () => {
-        const convId = "test-no-tag-on-disk";
-        await appendMessage(workdir, agentName, convId, "User", "just chatting", "chat");
-        const { readFile: rf } = await import("node:fs/promises");
-        const dir = join(workdir, ".akemon", "agents", agentName, "conversations");
-        const raw = await rf(join(dir, `${convId}.md`), "utf-8");
-        assert.ok(!raw.includes("[order]"), `chat line should NOT contain [order] tag: ${raw}`);
-        assert.ok(raw.includes("User: just chatting"));
-    });
-});