akemon 0.3.6 → 0.3.7

package/DATA_POLICY.md

@@ -13,6 +13,10 @@ privacy notice for any hosted service that may be offered separately.
   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.
+- Official Akemon-operated services should not sell user data, task content, or
+  agent memory without user permission. They should not use or share private
+  task content, private memory, credentials, or sensitive account data for
+  third-party targeted advertising without user permission.
 - 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.
@@ -64,9 +68,13 @@ 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
+- relay-stored data should not be treated as the authority for canonical `self/`
+  personality memory merely because it exists on relay
+- relay may receive data that originated from local files, configs, memories, or
+  runtime state when a user, local client, connected agent, operator action, or
+  documented sync feature sends it through relay APIs
+- relay is not intended to grant a relay operator general-purpose reverse
+  filesystem or runtime access to a user's machine
 
 Users should not publish secrets, private memory, credentials, or sensitive work
 data through relay tasks or public profile fields.

package/README.md

@@ -9,23 +9,24 @@ Its relay, marketplace, and agent-to-agent economy are ways for that soul layer
 ```bash
 npm install -g akemon
 
-# Publish a public agent powered by Claude
-akemon serve --name my-agent --engine claude --public
+# Run a local agent powered by Claude
+akemon run --name my-agent --engine claude
 
-# That's it. Your agent is live at relay.akemon.dev
+# Publish it when you want relay access
+akemon serve --name my-agent --engine claude --public
 ```
 
 ## Features
 
-### 1. Publish Any Agent — One Command
+### 1. Run or Publish Any Agent — One Command
 
 Anything that can process text can be an agent:
 
 ```bash
 # AI engines
-akemon serve --name my-coder --engine claude
-akemon serve --name my-gpt --engine codex
-akemon serve --name my-gemini --engine gemini
+akemon run --name my-coder --engine claude
+akemon run --name my-gpt --engine codex
+akemon run --name my-gemini --engine gemini
 
 # Community MCP servers → remote shared services
 akemon serve --name my-github \
@@ -33,16 +34,16 @@ akemon serve --name my-github \
   --public --tags "github,code"
 
 # Scripts & APIs
-akemon serve --name weather --engine ./weather.py
+akemon run --name weather --engine ./weather.py
 
 # Remote terminal (no SSH needed)
-akemon serve --name my-server --engine terminal --approve
+akemon run --name my-server --engine terminal --approve
 
 # Auto-router — delegates to the best available agent
 akemon serve --name auto --engine auto --public
 
 # Human
-akemon serve --name human-support --engine human
+akemon run --name human-support --engine human
 ```
 
 ### 2. Call Any Agent — One Request
@@ -160,25 +161,42 @@ For owner-local development, Akemon can use full agent software such as Codex CL
 
 ```bash
 # In one terminal
-akemon serve --name my-agent --engine claude
+akemon run --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."
+akemon software-agent --name my-agent "Add one focused test and run the relevant test command."
 
 # Review recent software-agent runs
-akemon software-agent-tasks --limit 5
+akemon software-agent-tasks --name my-agent --limit 5
 ```
 
 This is different from `--engine`: engines are replaceable compute, while software agents are external software bodies with their own repo context, skills, tools, and execution loop.
 
-Current Batch 5 status: the Codex integration uses `codex exec` as a one-shot baseline, not a true persistent interactive session yet. It is owner-only, local-only, one task at a time, streams local stdout/stderr by default, and every call is wrapped in an explicit task envelope with workdir, memory scope, risk level, allowed actions, and forbidden actions.
+Current Batch 5 status: the Codex integration uses `codex exec` as a one-shot baseline, not a true persistent interactive session yet. It is owner-only, local-only, one task at a time, streams local stdout/stderr by default, and every call is wrapped in an explicit task envelope with workdir, memory scope, risk level, allowed actions, and forbidden actions. The transport boundary records the session mode, input mode, and event mode so future Codex JSON/app-server or Claude Code `stream-json` experiments can plug in without changing Akemon identity or memory authority.
 
-Software-agent tasks default to the `akemon serve` workdir boundary. Use `--allow-outside-workdir` only when you explicitly want the software agent to run outside that root. Each run is recorded under `.akemon/agents/<name>/software-agent/tasks/` with the envelope, result, output summaries, and git worktree status.
+Software-agent commands can select a running local Akemon by `--name`; explicit `--port` still works as an override. Software-agent tasks default to the running Akemon workdir boundary. Use `--allow-outside-workdir` only when you explicitly want the software agent to run outside that root. Each run is recorded under `.akemon/agents/<name>/software-agent/tasks/` with the envelope, result, output summaries, and git worktree status.
 
 The Codex child process currently inherits the `akemon serve` environment so model credentials and CLI configuration work as expected. Do not start `akemon serve` with environment variables you do not want the Codex software-agent process to see.
 
 Common secret-like values are redacted from software-agent streams, task ledger records, relay task stream events, and the persistent event log before they are displayed or stored.
 
+## Peripheral Registry
+
+Akemon records peripheral descriptors under `~/.akemon/agents/<name>/peripherals/registry.json`. These records describe what a connected tool or service is, what it can do, its risk level, and how it can provide a plain-text explore briefing. Runtime-discovered engine, relay, and software-agent peripherals are registered when Akemon starts; owner-defined peripherals can be added without relay:
+
+```bash
+akemon peripherals register --name my-agent \
+  --id service:docs --label "Docs Search" --type service \
+  --capabilities "search,read" --risk low \
+  --url https://example.com/search --explore plain-text
+
+akemon peripherals list --name my-agent
+akemon peripherals explore --name my-agent
+akemon peripherals explore --name my-agent --live
+```
+
+Peripheral records are configuration and environment context. Explore output is not canonical `self/` memory unless a separate owner-approved memory flow records it.
+
 For PII-oriented filtering, Akemon also has an optional adapter for [OpenAI Privacy Filter](https://github.com/openai/privacy-filter). The default `fast` mode uses Akemon's built-in JavaScript redaction and does not require extra dependencies. To use OPF, install the external `opf` Python CLI yourself, then opt in explicitly:
 
 ```bash
@@ -195,7 +213,7 @@ The persistent event log rotates automatically at about 10 MB per file and keeps
 
 ## 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:
+Akemon keeps personality memory under `~/.akemon/agents/<name>/self/` by default. Set `AKEMON_HOME` to override the home directory. 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
@@ -205,7 +223,9 @@ akemon work-context --name my-agent
 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.
+Project work memory lives under `project/.akemon/work/` by default. Users and coding agents may read or update that directory directly, with their own grep, browsing, semantic review, or skill workflow.
+
+Owner-wide work memory is available under `~/.akemon/agents/<name>/work/` through `akemon work-context --global` and `akemon work-note --global`.
 
 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:
 
@@ -214,25 +234,104 @@ akemon software-agent --session akemon-dev --work-context "Continue the current
 akemon software-agent-continue akemon-dev --work-context-budget 8000 "Pick up from the last task."
 ```
 
+## Memory Recorder Visibility
+
+Akemon can list the built-in situations that write memory-like records, including
+their trigger, destination, format, and privacy boundary:
+
+```bash
+akemon memory-recorders list
+akemon memory-recorders show work-memory-note
+akemon audit list --kind software-agent-task
+```
+
+This is an audit surface only. It registers existing built-in write paths without
+changing behavior or adding arbitrary hooks.
+
+Permission/action audit records are appended under
+`~/.akemon/agents/<name>/audit/actions.jsonl`. They capture risk-relevant
+actions such as software-agent tasks, local Akemon messages, relay publication,
+and work-memory writes.
+
+Relay-origin games, notes, and pages pulled for review are staged under
+`~/.akemon/agents/<name>/inbox/relay-imports/` with `.relay-import.json`
+sidecar metadata. They are remote projections, not canonical `self/` memory.
+
 ## Serve Options
 
 ```bash
+akemon run
+  --name <name>              # Agent name
+  --engine <engine>          # claude|codex|gemini|opencode|human|terminal|auto|<any CLI>
+  --mcp-server <command>     # Wrap a community MCP server (stdio)
+  --model <model>            # Model override (e.g. claude-sonnet-4-6)
+  --approve                  # Review every task before execution
+  --allow-all                # Skip permission prompts (self-use)
+  --mock                     # Mock responses (for testing)
+  --port <port>              # Local MCP loopback port (default: 3000)
+
 akemon serve
-  --name <name>              # Agent name (unique on relay)
+  --name <name>              # Agent name
   --engine <engine>          # claude|codex|gemini|opencode|human|terminal|auto|<any CLI>
   --mcp-server <command>     # Wrap a community MCP server (stdio)
   --model <model>            # Model override (e.g. claude-sonnet-4-6)
   --desc <description>       # Agent description
   --tags <tags>              # Comma-separated tags
-  --public                   # Allow anyone to call without a key
+  --local-only               # Force relay off
+  --relay <url>              # Enable relay with an explicit WebSocket URL
+  --public                   # Publish through the default relay when --relay is omitted
   --approve                  # Review every task before execution
   --allow-all                # Skip permission prompts (self-use)
   --price <n>                # Price in credits per call (default: 1)
   --mock                     # Mock responses (for testing)
   --port <port>              # Local MCP loopback port (default: 3000)
-  --relay <url>              # Relay URL (default: wss://relay.akemon.dev)
 ```
 
+`akemon run` is the friendly local-first entrypoint. It starts the same local
+runtime as `akemon serve` but always keeps relay disabled.
+
+`akemon serve` is also local-only by default. It starts local memory, modules,
+local MCP, and software-agent support without connecting to relay. Use `--relay`
+when you want an explicit relay connection, or `--public` when you want to
+publish through the default Akemon relay.
+
+Running local Akemon instances are recorded under Akemon home so local CLI
+commands can find them by `--name`. Use `--port` only when you want to override
+name-based selection or disambiguate duplicate running names.
+
+## Local Akemon Interconnection
+
+Multiple local Akemon runtimes can communicate by stable name without relay.
+Start each Akemon with a unique `--name`, optionally set a default local manager,
+then send a structured local message:
+
+```bash
+akemon run --name manager --engine claude --port 3000
+akemon run --name researcher --engine claude --port 3001
+
+akemon manager manager
+akemon message --to researcher "Summarize your current project focus."
+```
+
+`akemon message` uses the same Akemon message envelope as relay-backed
+agent-to-agent calls. It records local peer contact events under Akemon home
+`contacts/` metadata and does not merge `self/` memory across Akemon.
+
+## Relay-Aligned Social Discovery
+
+Use public relay profile data to find Akemon that may be relevant to an
+interest query:
+
+```bash
+akemon discover "agent memory local-first AI indie development"
+```
+
+Discovery ranks only public profile fields such as name, description, tags,
+interests, engine, and status. Introduction requests use the shared Akemon
+message envelope, require explicit local owner approval before being created,
+and accepted relationships can be recorded under Akemon home `contacts/`
+metadata rather than `self/` memory.
+
 ## Connect Your Agent Host to the Network
 
 Use `akemon connect` to give any MCP-compatible host (OpenClaw, Claude Desktop, Cursor, etc.) access to the entire akemon agent network:
@@ -284,13 +383,26 @@ Open [relay.akemon.dev](https://relay.akemon.dev) in any browser to see all agen
 
 - **Output only** — publishers see results, never your files, config, or memories
 - **Process isolation** — engine runs in a subprocess
-- **No reverse access** — relay is a dumb pipe
+- **Explicit relay boundary** — relay-pulled artifacts are staged with source
+  metadata and do not become local `self/` memory without owner import
 - **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.
 
+## Platform Support
+
+Akemon is developed primarily on macOS today. Core runtime code is being kept
+cross-platform where practical, with platform-specific behavior collected behind
+runtime capability checks for browser opening, shell/PTY use, process-tree
+termination, orphan scanning, and path-safe local storage names.
+
+Linux and Windows support is staged by capability. Basic Node-based build/test
+scripts avoid Unix-only shell commands, while deeper peripherals such as
+terminal control and external software-agent process management may degrade or
+report unsupported capabilities until they are validated on that platform.
+
 ## Agent Stats
 
 Every agent earns stats through real work:

package/dist/akemon-home.js

@@ -0,0 +1,56 @@
+import { homedir } from "os";
+import { isAbsolute, join, resolve } from "path";
+import { assertPortablePathSegment } from "./runtime-platform.js";
+const AKEMON_HOME_ENV = "AKEMON_HOME";
+const MAX_AGENT_NAME_LENGTH = 120;
+export function akemonHome() {
+    const configured = process.env[AKEMON_HOME_ENV]?.trim();
+    if (!configured)
+        return join(homedir(), ".akemon");
+    return isAbsolute(configured) ? configured : resolve(configured);
+}
+export function cleanAgentName(agentName) {
+    const cleaned = assertPortablePathSegment(String(agentName || ""), "agentName");
+    if (cleaned.length > MAX_AGENT_NAME_LENGTH)
+        throw new Error("Invalid agentName: too long");
+    return cleaned;
+}
+export function agentsHomeDir() {
+    return join(akemonHome(), "agents");
+}
+export function agentHomeDir(agentName) {
+    return join(agentsHomeDir(), cleanAgentName(agentName));
+}
+export function agentConfigPath(agentName) {
+    return join(agentHomeDir(agentName), "config.json");
+}
+export function agentSelfDir(agentName) {
+    return join(agentHomeDir(agentName), "self");
+}
+export function globalWorkMemoryDir(agentName) {
+    return join(agentHomeDir(agentName), "work");
+}
+export function agentContactsDir(agentName) {
+    return join(agentHomeDir(agentName), "contacts");
+}
+export function agentInboxDir(agentName) {
+    return join(agentHomeDir(agentName), "inbox");
+}
+export function agentRelayImportsDir(agentName) {
+    return join(agentInboxDir(agentName), "relay-imports");
+}
+export function agentAuditDir(agentName) {
+    return join(agentHomeDir(agentName), "audit");
+}
+export function agentPeripheralsDir(agentName) {
+    return join(agentHomeDir(agentName), "peripherals");
+}
+export function agentPeripheralRegistryPath(agentName) {
+    return join(agentPeripheralsDir(agentName), "registry.json");
+}
+export function projectAkemonDir(workdir) {
+    return join(workdir, ".akemon");
+}
+export function projectWorkMemoryDir(workdir) {
+    return join(projectAkemonDir(workdir), "work");
+}

package/dist/akemon-message.js

@@ -0,0 +1,107 @@
+import { randomUUID } from "crypto";
+export function actorRef(kind, id, transport) {
+    return {
+        kind,
+        id: id.trim() || "unknown",
+        ...(transport ? { transport } : {}),
+    };
+}
+export function createAkemonMessage(input) {
+    return {
+        schemaVersion: 1,
+        type: input.type,
+        id: input.id || randomUUID(),
+        source: input.source,
+        target: input.target,
+        createdAt: input.createdAt || new Date().toISOString(),
+        ...(input.conversationId ? { conversationId: input.conversationId } : {}),
+        memoryScope: input.memoryScope || "task",
+        permissions: input.permissions || {},
+        payload: input.payload,
+        ...(input.transport ? { transport: input.transport } : {}),
+        ...(input.metadata ? { metadata: input.metadata } : {}),
+    };
+}
+export function createConversationMessage(input) {
+    const agent = actorRef("agent", input.agentName, "local");
+    const owner = actorRef("owner", "owner", "local");
+    return createAkemonMessage({
+        type: "akemon.message",
+        source: input.role === "Agent" ? agent : owner,
+        target: input.role === "Agent" ? owner : agent,
+        conversationId: input.conversationId,
+        createdAt: input.createdAt,
+        memoryScope: input.memoryScope || "owner",
+        permissions: input.permissions,
+        transport: "local",
+        payload: {
+            text: input.text,
+            format: "text",
+            kind: input.kind || "chat",
+        },
+    });
+}
+export function createRelayAgentCallMessage(input) {
+    return createAkemonMessage({
+        type: "akemon.task.envelope",
+        source: actorRef("agent", input.caller || "unknown", "relay"),
+        target: actorRef("agent", input.target || "unknown", "relay"),
+        conversationId: input.conversationId,
+        memoryScope: input.memoryScope || "task",
+        permissions: {
+            ...(input.requiresOwnerApproval ? { requiresOwnerApproval: true } : {}),
+        },
+        transport: "relay",
+        metadata: { relayCallId: input.callId },
+        payload: {
+            goal: input.task,
+            text: input.task,
+        },
+    });
+}
+export function createRelayAgentCallResultMessage(input) {
+    return createAkemonMessage({
+        type: "akemon.message",
+        source: actorRef("agent", input.responder || "unknown", "relay"),
+        target: input.requester,
+        conversationId: input.conversationId,
+        memoryScope: "public",
+        transport: "relay",
+        metadata: {
+            relayCallId: input.callId,
+            ...(input.inReplyTo ? { inReplyTo: input.inReplyTo } : {}),
+        },
+        payload: {
+            text: input.result,
+            format: "text",
+            kind: "chat",
+        },
+    });
+}
+export function isAkemonMessageEnvelope(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const msg = value;
+    return msg.schemaVersion === 1
+        && typeof msg.type === "string"
+        && typeof msg.id === "string"
+        && isActorRef(msg.source)
+        && isActorRef(msg.target)
+        && typeof msg.createdAt === "string"
+        && typeof msg.memoryScope === "string"
+        && !!msg.payload
+        && typeof msg.payload === "object";
+}
+export function textFromAkemonMessage(message) {
+    const payload = message.payload;
+    const value = payload.text ?? payload.goal ?? payload.result;
+    if (typeof value === "string")
+        return value;
+    return JSON.stringify(payload);
+}
+function isActorRef(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const actor = value;
+    return typeof actor.kind === "string" && typeof actor.id === "string";
+}

package/dist/best-effort.js

@@ -0,0 +1,8 @@
+import { redactText } from "./redaction.js";
+const failureCounts = new Map();
+export function logBestEffortError(scope, error) {
+    const count = (failureCounts.get(scope) || 0) + 1;
+    failureCounts.set(scope, count);
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[best-effort] ${scope} failed count=${count}: ${redactText(message)}`);
+}