akemon 0.3.5 → 0.3.6

package/DATA_POLICY.md

@@ -0,0 +1,120 @@
+# Akemon Data Policy
+
+This document describes the intended data principles for the open-source Akemon
+project and related official services. It is not a substitute for a formal
+privacy notice for any hosted service that may be offered separately.
+
+## Core Principles
+
+- Users own their agent memories, work memory, task history, and local runtime
+  data.
+- Akemon should be local-first by default.
+- Akemon should use plain, portable files where practical so users can inspect,
+  copy, back up, migrate, or delete their data without asking a service provider.
+- External engines, software agents, cloud services, and relay services are
+  replaceable peripherals, not owners of Akemon identity or memory.
+- Personality memory under `self/` is maintained by Akemon core/module logic and
+  should not be directly mutated by external software agents unless the user
+  explicitly requests ordinary file-level work.
+
+## Local Data
+
+By default, Akemon stores runtime data locally under `.akemon/agents/<name>/`.
+Important local areas include:
+
+- `self/`: canonical personality and identity memory
+- `work/`: user-owned work memory shared with tools such as Codex or Claude Code
+- `events/`: persistent event logs
+- `software-agent/`: task ledgers, context packets, session summaries, and
+  software-agent run metadata
+
+Local files are user data. Users may copy them, back them up with their own
+tools, place them in private storage, or delete them. Be careful with `.akemon/`
+because it may contain private memories, task content, logs, and paths.
+
+## Work Memory and External Agents
+
+External software agents should use `work/` as the default shared memory layer.
+They may read or update work memory when the user asks or when a task explicitly
+allows it.
+
+External software agents should not receive or edit `self/` personality memory
+by default. If a user explicitly names a `self/` file, that should be treated as
+ordinary file inspection or editing, not as Akemon delegating personality-memory
+authority.
+
+## Engines, Agent SDKs, and Third-Party Providers
+
+When users configure an external model, engine, agent SDK, coding agent, MCP
+server, or other provider, task content and selected context may be sent to that
+provider. Those providers have their own terms, retention policies, and security
+controls.
+
+Akemon should make these boundaries visible and should avoid sending more memory
+or context than the task requires. Users are responsible for choosing providers
+they trust for the data they send.
+
+## Relay and Published Agents
+
+Relay features send data over the network because they publish agents, route
+calls, or synchronize public/remote interactions.
+
+The intended boundary is:
+
+- public profile, tags, status, stats, and advertised capabilities may be visible
+  through relay features
+- task requests and responses may pass through relay when remote calls are used
+- relay should not be the authority for canonical `self/` personality memory
+- relay should not have reverse access to local files, configs, memories, or
+  private runtime data unless a user explicitly sends or publishes that data
+
+Users should not publish secrets, private memory, credentials, or sensitive work
+data through relay tasks or public profile fields.
+
+## Logs, Ledgers, and Redaction
+
+Akemon records local events and software-agent task ledgers for debugging,
+continuity, and audit. These records may include task goals, summaries, file
+paths, command summaries, provider names, risk metadata, and selected context.
+
+Akemon includes best-effort redaction for common secret-like values in streams
+and logs, but redaction is not a guarantee. Treat logs and ledgers as potentially
+sensitive local data.
+
+## Cloud Backup and Sync
+
+If official cloud backup or sync is offered, it should follow these principles:
+
+- opt in explicitly
+- make clear what is backed up and where it is stored
+- preserve user export and deletion paths
+- avoid lock-in by keeping data formats portable where practical
+- distinguish canonical local memory from cached, synced, or projected data
+- publish service-specific privacy, retention, and security details before users
+  rely on the service for sensitive data
+
+Users who prefer not to use official cloud backup should be able to back up local
+Akemon data with their own storage provider, filesystem sync, or private archive
+workflow.
+
+## Telemetry
+
+The open-source CLI should not send product telemetry by default. Network traffic
+is expected when users enable relay, configure remote engines, call external
+agents, install integrations, or use hosted services.
+
+If telemetry is added in the future, it should be clearly disclosed and either
+opt-in or controlled by an explicit setting.
+
+## Data Portability
+
+Akemon should keep user memory portable. Users should be able to:
+
+- inspect local data with normal filesystem tools
+- move memories between machines
+- use external tools to read work memory
+- export or back up agent memory without requiring a proprietary service
+- stop using an official service without losing local ownership of memories
+
+This portability is part of Akemon's product promise: tools and providers may
+change, but user memory should remain under user control.

package/README.md

@@ -193,6 +193,27 @@ The software-agent task ledger keeps the most recent 200 task records by default
 
 The persistent event log rotates automatically at about 10 MB per file and keeps the current `events.jsonl` plus five rotated files.
 
+## Work Memory
+
+Akemon keeps personality memory under `.akemon/agents/<name>/self/`. External software tools such as Codex CLI and Claude Code should use the separate work-memory directory instead:
+
+```bash
+# Print a deterministic work-memory packet for an external tool
+akemon work-context --name my-agent
+
+# Append a quick work-memory note
+akemon work-note --name my-agent --source codex --kind decision "Keep Codex focused on work memory before adding more tools."
+```
+
+Work memory lives under `.akemon/agents/<name>/work/`. Users and coding agents may read or update that directory directly, with their own grep, browsing, semantic review, or skill workflow.
+
+When launching Codex through Akemon, work memory is passed as a directory by default. Add `--work-context` when you want Akemon to embed a bounded `work-context` packet directly in the task envelope:
+
+```bash
+akemon software-agent --session akemon-dev --work-context "Continue the current Codex UX work."
+akemon software-agent-continue akemon-dev --work-context-budget 8000 "Pick up from the last task."
+```
+
 ## Serve Options
 
 ```bash
@@ -266,6 +287,10 @@ Open [relay.akemon.dev](https://relay.akemon.dev) in any browser to see all agen
 - **No reverse access** — relay is a dumb pipe
 - **You control** — `--approve` to review tasks, `--engine human` to answer personally
 
+See [DATA_POLICY.md](DATA_POLICY.md) for Akemon's local-first memory and data
+ownership principles. See [TRADEMARK.md](TRADEMARK.md) for use of the Akemon
+name, marks, and official service identity.
+
 ## Agent Stats
 
 Every agent earns stats through real work:

package/TRADEMARK.md

@@ -0,0 +1,74 @@
+# Akemon Trademark Policy
+
+This project is open source, but the open-source license for the code does not
+grant a license to use Akemon names, logos, domains, or other project marks in a
+way that implies official endorsement or control.
+
+## Project Marks
+
+Project marks include:
+
+- the name `Akemon`
+- Akemon logos, icons, mascots, and visual brand assets
+- official domains and services such as `akemon.dev` and `relay.akemon.dev`
+- names or marks that are confusingly similar when used for related software or
+  hosted services
+
+These marks may or may not be registered trademarks. This policy is intended to
+keep the project name reliable for users.
+
+## Allowed Uses
+
+You may use the Akemon name to:
+
+- refer truthfully to the open-source project
+- describe compatibility, such as "works with Akemon" or "Akemon-compatible"
+- identify an unmodified copy of the upstream project
+- discuss, review, document, or teach the project
+- link to the official repository or official services
+
+These uses should not imply that your project, fork, service, package, plugin,
+or hosted deployment is official unless it is actually maintained or approved by
+the Akemon maintainers.
+
+## Forks and Modified Versions
+
+You may fork the code under its open-source license. If you distribute a
+modified product, hosted service, package, or agent network, use a name and
+presentation that make the difference clear.
+
+Good examples:
+
+- `ExampleAI, built from Akemon`
+- `ExampleAI, Akemon-compatible`
+- `ExampleAI fork of Akemon`
+
+Avoid examples:
+
+- calling a materially modified fork simply `Akemon`
+- using the official logo for an unofficial service
+- presenting an unofficial relay, cloud backup, or marketplace as the official
+  Akemon service
+
+If your changes substantially alter memory ownership, permission behavior,
+privacy boundaries, or agent identity behavior, make that especially clear to
+users.
+
+## Official Services
+
+Official hosted services, including relay, cloud backup, sync, marketplace, or
+managed agent services, may have separate terms, privacy notices, data policies,
+and brand rules. The open-source code license does not grant access to or
+control over those services.
+
+## No Endorsement
+
+Do not use Akemon marks in advertising, product names, company names, domains,
+social accounts, package names, or app listings in a way that suggests official
+endorsement, partnership, or sponsorship without written permission.
+
+## Questions
+
+If a use is ambiguous, prefer clear attribution and a distinct product name.
+Open an issue or contact the maintainers before relying on a use that could
+confuse users about who operates the software or service.

package/dist/cli.js

@@ -8,6 +8,8 @@ import { listAgents } from "./list.js";
 import { connect } from "./connect.js";
 import { PrivacyFilterUnavailableError, sanitizeText, } from "./privacy-filter.js";
 import { SoftwareAgentStreamCliRenderer } from "./software-agent-stream-cli.js";
+import { appendWorkMemoryNote, buildWorkMemoryContext, } from "./work-memory.js";
+import { renderSoftwareAgentRunResult } from "./software-agent-result-cli.js";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
@@ -76,10 +78,36 @@ function printSoftwareAgentTaskList(tasks) {
             : "no-git";
         const goal = truncateOneLine(task.envelope?.goal || "", 90);
         console.log(`${task.taskId}  ${task.status}/${result}  ${duration}  ${git}  ${task.updatedAt || task.startedAt}`);
+        if (task.contextSession?.sessionId)
+            console.log(`  session: ${task.contextSession.sessionId}`);
+        const workMemoryDir = task.envelope?.workMemoryDir || task.result?.workMemoryDir;
+        if (workMemoryDir)
+            console.log(`  work memory: ${workMemoryDir}`);
         if (goal)
             console.log(`  ${goal}`);
     }
 }
+function printSoftwareAgentSessionList(sessions) {
+    if (!sessions.length) {
+        console.log("No software-agent context sessions found.");
+        return;
+    }
+    for (const session of sessions) {
+        const result = session.lastResult?.success === true ? "ok" : session.lastResult?.success === false ? "error" : "pending";
+        const duration = typeof session.lastResult?.durationMs === "number" ? `${session.lastResult.durationMs}ms` : "-";
+        const updatedAt = session.updatedAt || "-";
+        const goal = truncateOneLine(session.lastGoal || "", 90);
+        console.log(`${session.sessionId}  ${result}  ${duration}  ${updatedAt}`);
+        if (session.lastTaskId)
+            console.log(`  last task: ${session.lastTaskId}`);
+        if (goal)
+            console.log(`  ${goal}`);
+        if (session.packetPath)
+            console.log(`  context: ${session.packetPath}`);
+        if (session.workMemoryDir)
+            console.log(`  work memory: ${session.workMemoryDir}`);
+    }
+}
 function truncateOneLine(value, max) {
     const oneLine = value.replace(/\s+/g, " ").trim();
     if (oneLine.length <= max)
@@ -176,9 +204,64 @@ async function streamLocalOwnerEndpoint(path, opts, body) {
     if (failed)
         process.exit(1);
 }
+async function runSoftwareAgentCli(goalParts, opts, forcedSessionId) {
+    const body = {
+        goal: goalParts.join(" "),
+        roleScope: opts.roleScope,
+        memoryScope: opts.memoryScope,
+        riskLevel: opts.risk,
+    };
+    if (opts.workdir)
+        body.workdir = opts.workdir;
+    if (opts.allowOutsideWorkdir)
+        body.allowOutsideWorkdir = true;
+    if (opts.memorySummary)
+        body.memorySummary = opts.memorySummary;
+    const workContextBudget = parsePositiveIntCliOption(opts.workContextBudget, "--work-context-budget");
+    if (opts.workContext || workContextBudget !== undefined)
+        body.includeWorkMemoryContext = true;
+    if (workContextBudget !== undefined)
+        body.workMemoryContextBudget = workContextBudget;
+    const sessionId = forcedSessionId || opts.session;
+    if (sessionId)
+        body.contextSessionId = sessionId;
+    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;
+    }
+    if (opts.stream !== false) {
+        await streamLocalOwnerEndpoint("/self/software-agent/run-stream", opts, body);
+        return;
+    }
+    const res = await fetchLocalOwnerEndpoint("/self/software-agent/run", opts, {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        data = { output: text };
+    }
+    if (!res.ok) {
+        console.error(data.error || text || `Request failed with HTTP ${res.status}`);
+        process.exit(1);
+    }
+    const failed = renderSoftwareAgentRunResult(data);
+    if (failed)
+        process.exit(1);
+}
 program
     .name("akemon")
-    .description("Agent work marketplace — train your agent, let it work for others")
+    .description("Local AI companion runtime with memory, modules, relay sync, and software-agent control")
     .version(pkg.version);
 program
     .command("serve")
@@ -309,47 +392,34 @@ program
     .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("--work-context", "Embed a bounded work-memory context packet in the task envelope")
+    .option("--work-context-budget <chars>", "Maximum embedded work-memory context size; also enables --work-context")
     .option("--session <id>", "Akemon-side context session id for explicit software-agent continuity")
     .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(" "),
-        roleScope: opts.roleScope,
-        memoryScope: opts.memoryScope,
-        riskLevel: opts.risk,
-    };
-    if (opts.workdir)
-        body.workdir = opts.workdir;
-    if (opts.allowOutsideWorkdir)
-        body.allowOutsideWorkdir = true;
-    if (opts.memorySummary)
-        body.memorySummary = opts.memorySummary;
-    if (opts.session)
-        body.contextSessionId = opts.session;
-    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;
-    }
-    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),
-    });
-    if (data.output)
-        console.log(data.output);
-    else
-        console.log(JSON.stringify(data, null, 2));
+    await runSoftwareAgentCli(goalParts, opts);
+});
+program
+    .command("software-agent-continue")
+    .description("Continue an Akemon-side software-agent context session")
+    .argument("<sessionId>", "Akemon-side context session id to continue")
+    .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("--work-context", "Embed a bounded work-memory context packet in the task envelope")
+    .option("--work-context-budget <chars>", "Maximum embedded work-memory context size; also enables --work-context")
+    .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 (sessionId, goalParts, opts) => {
+    await runSoftwareAgentCli(goalParts, opts, sessionId);
 });
 program
     .command("software-agent-status")
@@ -367,20 +437,78 @@ program
     .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("--session <id>", "Filter listed tasks by Akemon-side context session id")
+    .option("--context", "Print the task's Akemon TASK_CONTEXT.md content when inspecting one task")
     .option("--json", "Print raw JSON")
     .action(async (taskId, opts) => {
+    if (!taskId && opts.context) {
+        console.error("--context requires a taskId");
+        process.exit(1);
+    }
+    if (taskId && opts.session) {
+        console.error("--session cannot be used when inspecting a single taskId");
+        process.exit(1);
+    }
     const path = taskId
-        ? `/self/software-agent/tasks/${encodeURIComponent(taskId)}`
-        : `/self/software-agent/tasks?limit=${clampPositiveInt(opts.limit, 20, 100)}`;
+        ? `/self/software-agent/tasks/${encodeURIComponent(taskId)}${opts.context ? "?includeContext=1" : ""}`
+        : `/self/software-agent/tasks?limit=${clampPositiveInt(opts.limit, 20, 100)}${opts.session ? `&session=${encodeURIComponent(opts.session)}` : ""}`;
     const data = await callLocalOwnerEndpoint(path, opts, {
         method: "GET",
     });
+    if (taskId && opts.context) {
+        const contextPacket = data.contextSession?.contextPacket;
+        if (typeof contextPacket === "string" && contextPacket.length > 0) {
+            process.stdout.write(contextPacket);
+            if (!contextPacket.endsWith("\n"))
+                process.stdout.write("\n");
+            return;
+        }
+        console.error("No TASK_CONTEXT.md content found for this task.");
+        process.exit(1);
+    }
     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-sessions")
+    .description("List or inspect owner-only Akemon-side software-agent context sessions")
+    .argument("[sessionId]", "Context session id to inspect")
+    .option("-p, --port <port>", "Local akemon serve port", "3000")
+    .option("-l, --limit <n>", "Maximum recent sessions to list", "20")
+    .option("--context", "Print the session TASK_CONTEXT.md content")
+    .option("--json", "Print raw JSON")
+    .action(async (sessionId, opts) => {
+    const query = sessionId && opts.context ? "?includeContext=1" : "";
+    const path = sessionId
+        ? `/self/software-agent/sessions/${encodeURIComponent(sessionId)}${query}`
+        : `/self/software-agent/sessions?limit=${clampPositiveInt(opts.limit, 20, 100)}`;
+    const data = await callLocalOwnerEndpoint(path, opts, {
+        method: "GET",
+    });
+    if (sessionId) {
+        if (opts.context) {
+            const contextPacket = data.session?.contextPacket;
+            if (typeof contextPacket === "string" && contextPacket.length > 0) {
+                process.stdout.write(contextPacket);
+                if (!contextPacket.endsWith("\n"))
+                    process.stdout.write("\n");
+                return;
+            }
+            console.error("No TASK_CONTEXT.md content found for this session.");
+            process.exit(1);
+        }
+        console.log(JSON.stringify(data.session, null, 2));
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    printSoftwareAgentSessionList(Array.isArray(data.sessions) ? data.sessions : []);
+});
 program
     .command("software-agent-reset")
     .description("Reset the owner-only local software-agent peripheral session")
@@ -431,6 +559,69 @@ program
         throw error;
     }
 });
+program
+    .command("work-context")
+    .description("Print a work-memory context packet for external software agents")
+    .option("-w, --workdir <path>", "Akemon workdir (default: cwd)")
+    .option("-n, --name <name>", "Agent name", "my-agent")
+    .option("--purpose <text>", "Purpose of this context packet", "external software-agent work context")
+    .option("--budget <chars>", "Maximum packet size in characters", "12000")
+    .option("--json", "Print raw JSON")
+    .action(async (opts) => {
+    try {
+        const packet = await buildWorkMemoryContext({
+            workdir: opts.workdir || process.cwd(),
+            agentName: opts.name,
+            purpose: opts.purpose,
+            budget: parsePositiveIntCliOption(opts.budget, "--budget"),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(packet, null, 2));
+            return;
+        }
+        process.stdout.write(packet.text);
+        if (!packet.text.endsWith("\n"))
+            process.stdout.write("\n");
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+program
+    .command("work-note")
+    .description("Append a note to Akemon work memory")
+    .argument("<text...>", "Durable work-memory note")
+    .option("-w, --workdir <path>", "Akemon workdir (default: cwd)")
+    .option("-n, --name <name>", "Agent name", "my-agent")
+    .option("--source <source>", "Note source, e.g. user, codex, or claude-code", "user")
+    .option("--session <id>", "External or Akemon-side session id")
+    .option("--kind <kind>", "Work-memory kind, e.g. note, decision, command, project", "note")
+    .option("--target <path>", "Optional target file under the work memory directory")
+    .option("--json", "Print raw JSON")
+    .action(async (textParts, opts) => {
+    try {
+        const result = await appendWorkMemoryNote({
+            workdir: opts.workdir || process.cwd(),
+            agentName: opts.name,
+            text: textParts.join(" "),
+            source: opts.source,
+            sessionId: opts.session,
+            kind: opts.kind,
+            target: opts.target,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Work memory note appended: ${result.note.id}`);
+        console.log(`Path: ${result.path}`);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
 program
     .command("dashboard")
     .description("Open your agent dashboard in the browser")