akemon 0.3.5 → 0.3.7

package/dist/peripheral-registry.js

@@ -0,0 +1,235 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname } from "path";
+import { agentPeripheralRegistryPath } from "./akemon-home.js";
+import { redactText } from "./redaction.js";
+const VALID_TYPES = ["engine", "relay", "software-agent", "interactive-session", "mcp", "service", "hardware", "custom"];
+const VALID_RISK_LEVELS = ["low", "medium", "high"];
+const VALID_EXPLORE_MODES = ["none", "plain-text"];
+const VALID_SOURCES = ["runtime", "owner", "imported"];
+const VALID_STATUSES = ["configured", "available", "unavailable"];
+export function peripheralRegistryPath(agentName) {
+    return agentPeripheralRegistryPath(agentName);
+}
+export async function loadPeripheralRecords(agentName) {
+    let raw;
+    try {
+        raw = await readFile(peripheralRegistryPath(agentName), "utf-8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const parsed = JSON.parse(raw);
+    const records = Array.isArray(parsed.records) ? parsed.records : [];
+    return records.map((record) => normalizePeripheralRecord(record));
+}
+export async function savePeripheralRecords(agentName, records) {
+    const path = peripheralRegistryPath(agentName);
+    const normalized = records.map((record) => normalizePeripheralRecord(record));
+    const file = {
+        schemaVersion: 1,
+        records: normalized.sort((a, b) => a.id.localeCompare(b.id)),
+    };
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(file, null, 2)}\n`, "utf-8");
+}
+export async function upsertPeripheralRecord(agentName, record) {
+    const normalized = normalizePeripheralRecord(record);
+    const records = await loadPeripheralRecords(agentName);
+    const next = upsertRecords(records, [normalized]);
+    await savePeripheralRecords(agentName, next);
+    return normalized;
+}
+export async function upsertPeripheralRecords(agentName, records) {
+    const normalized = records.map((record) => normalizePeripheralRecord(record));
+    const existing = await loadPeripheralRecords(agentName);
+    const next = upsertRecords(existing, normalized);
+    await savePeripheralRecords(agentName, next);
+    return normalized;
+}
+export function createRuntimePeripheralRecord(peripheral, options = {}) {
+    return normalizePeripheralRecord({
+        schemaVersion: 1,
+        id: peripheral.id,
+        name: peripheral.name,
+        type: options.type || inferPeripheralType(peripheral),
+        capabilities: peripheral.capabilities,
+        tags: peripheral.tags,
+        riskLevel: options.riskLevel || inferRiskLevel(peripheral),
+        allowedActions: options.allowedActions || [],
+        explore: {
+            mode: peripheral.explore ? "plain-text" : "none",
+            description: options.exploreDescription,
+        },
+        source: "runtime",
+        status: options.status || "available",
+        updatedAt: options.updatedAt || new Date().toISOString(),
+        startCommand: options.startCommand,
+        url: options.url,
+    });
+}
+export function mergePeripheralRecords(configured, runtime) {
+    const byId = new Map();
+    for (const record of configured)
+        byId.set(record.id, normalizePeripheralRecord(record));
+    for (const record of runtime)
+        byId.set(record.id, normalizePeripheralRecord(record));
+    return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+export async function buildPeripheralExploreBriefing(input) {
+    const generatedAt = new Date().toISOString();
+    const runtimeById = new Map((input.runtimePeripherals || []).map((peripheral) => [peripheral.id, peripheral]));
+    const selected = input.id
+        ? input.records.filter((record) => record.id === input.id)
+        : [...input.records];
+    const sections = [];
+    for (const record of selected) {
+        const lines = renderRegistryBriefingLines(record);
+        const runtime = runtimeById.get(record.id);
+        if (runtime?.explore) {
+            try {
+                const live = (await runtime.explore()).trim();
+                if (live) {
+                    lines.push("live briefing:");
+                    for (const line of redactText(live).split(/\r?\n/)) {
+                        lines.push(`  ${line}`);
+                    }
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                lines.push(`live briefing error: ${redactText(message)}`);
+            }
+        }
+        sections.push({
+            id: record.id,
+            name: record.name,
+            type: record.type,
+            text: lines.join("\n"),
+        });
+    }
+    const text = sections.map((section) => section.text).join("\n\n") || "(no peripherals registered)";
+    return { generatedAt, sections, text };
+}
+export function normalizePeripheralRecord(input) {
+    const now = new Date().toISOString();
+    const type = cleanEnum(input.type, VALID_TYPES, "type", "custom");
+    const riskLevel = cleanEnum(input.riskLevel, VALID_RISK_LEVELS, "riskLevel", "medium");
+    const exploreMode = cleanEnum(input.explore?.mode, VALID_EXPLORE_MODES, "explore.mode", "none");
+    return {
+        schemaVersion: 1,
+        id: cleanPeripheralId(input.id),
+        name: cleanText(input.name || input.id, "name", 160),
+        type,
+        capabilities: cleanTokenList(input.capabilities || [], "capabilities"),
+        tags: cleanTokenList(input.tags || [], "tags"),
+        riskLevel,
+        allowedActions: cleanTokenList(input.allowedActions || [], "allowedActions"),
+        explore: {
+            mode: exploreMode,
+            ...(input.explore?.description ? { description: cleanText(input.explore.description, "explore.description", 500) } : {}),
+        },
+        source: cleanEnum(input.source, VALID_SOURCES, "source", "owner"),
+        status: cleanEnum(input.status, VALID_STATUSES, "status", "configured"),
+        updatedAt: cleanText(input.updatedAt || now, "updatedAt", 80),
+        ...(input.startCommand ? { startCommand: cleanCommand(input.startCommand) } : {}),
+        ...(input.url ? { url: cleanUrl(input.url) } : {}),
+    };
+}
+function upsertRecords(existing, records) {
+    const byId = new Map();
+    for (const record of existing)
+        byId.set(record.id, normalizePeripheralRecord(record));
+    for (const record of records)
+        byId.set(record.id, normalizePeripheralRecord(record));
+    return [...byId.values()];
+}
+function renderRegistryBriefingLines(record) {
+    const lines = [
+        `[${record.id}] ${record.name}`,
+        `type=${record.type} risk=${record.riskLevel} status=${record.status} source=${record.source}`,
+        `capabilities: ${record.capabilities.length ? record.capabilities.join(", ") : "(none declared)"}`,
+    ];
+    if (record.tags.length)
+        lines.push(`tags: ${record.tags.join(", ")}`);
+    if (record.allowedActions.length)
+        lines.push(`allowed actions: ${record.allowedActions.join(", ")}`);
+    if (record.startCommand)
+        lines.push(`start command: ${redactText(record.startCommand)}`);
+    if (record.url)
+        lines.push(`url: ${redactText(record.url)}`);
+    lines.push(`explore: ${record.explore.mode}${record.explore.description ? ` - ${record.explore.description}` : ""}`);
+    return lines;
+}
+function inferPeripheralType(peripheral) {
+    if (peripheral.tags.includes("engine") || peripheral.id.startsWith("engine:"))
+        return "engine";
+    if (peripheral.tags.includes("relay") || peripheral.id === "relay")
+        return "relay";
+    if (peripheral.tags.includes("software-agent") || peripheral.id.startsWith("software-agent:"))
+        return "software-agent";
+    return "custom";
+}
+function inferRiskLevel(peripheral) {
+    if (peripheral.capabilities.includes("repo-edit") || peripheral.capabilities.includes("action-out"))
+        return "high";
+    if (peripheral.capabilities.includes("sync") || peripheral.capabilities.includes("tool-use"))
+        return "medium";
+    return "low";
+}
+function cleanPeripheralId(value) {
+    const cleaned = cleanText(value, "id", 120);
+    if (/[/\\\x00-\x1f\x7f]/.test(cleaned))
+        throw new Error("Invalid peripheral id: must not contain path separators or control characters");
+    if (!/^[A-Za-z0-9_.:-]+$/.test(cleaned)) {
+        throw new Error("Invalid peripheral id: use only letters, numbers, '.', '_', ':', and '-'");
+    }
+    return cleaned;
+}
+function cleanTokenList(values, label) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const cleaned = cleanText(value, label, 100);
+        if (/[/\\\x00-\x1f\x7f]/.test(cleaned))
+            throw new Error(`Invalid ${label}: contains path separators or control characters`);
+        if (!seen.has(cleaned)) {
+            seen.add(cleaned);
+            result.push(cleaned);
+        }
+    }
+    return result;
+}
+function cleanText(value, label, max) {
+    const cleaned = String(value || "").trim();
+    if (!cleaned)
+        throw new Error(`Invalid peripheral ${label}: must not be empty`);
+    if (cleaned.length > max)
+        throw new Error(`Invalid peripheral ${label}: too long`);
+    if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(cleaned))
+        throw new Error(`Invalid peripheral ${label}: contains control characters`);
+    return cleaned;
+}
+function cleanCommand(value) {
+    const cleaned = cleanText(value, "startCommand", 1000);
+    if (/[\r\n]/.test(cleaned))
+        throw new Error("Invalid peripheral startCommand: must be a single line");
+    return cleaned;
+}
+function cleanUrl(value) {
+    const cleaned = cleanText(value, "url", 1000);
+    const url = new URL(cleaned);
+    if (!["http:", "https:", "ws:", "wss:", "file:"].includes(url.protocol)) {
+        throw new Error("Invalid peripheral url: unsupported protocol");
+    }
+    return url.toString();
+}
+function cleanEnum(value, allowed, label, fallback) {
+    if (value === undefined || value === null || value === "")
+        return fallback;
+    const normalized = String(value).trim().toLowerCase();
+    if (allowed.includes(normalized))
+        return normalized;
+    throw new Error(`Invalid peripheral ${label}: must be one of ${allowed.join(", ")}`);
+}

package/dist/permission-audit.js

@@ -0,0 +1,132 @@
+import { randomUUID } from "crypto";
+import { appendFileSync, mkdirSync } from "fs";
+import { appendFile, mkdir, readFile } from "fs/promises";
+import { join } from "path";
+import { agentAuditDir, cleanAgentName } from "./akemon-home.js";
+import { redactSecrets } from "./redaction.js";
+const DEFAULT_AUDIT_LIMIT = 50;
+const MAX_AUDIT_LIMIT = 500;
+export function permissionAuditLogPath(agentName) {
+    return join(agentAuditDir(agentName), "actions.jsonl");
+}
+export function createPermissionAuditRecord(agentName, input) {
+    return {
+        schemaVersion: 1,
+        id: input.id || randomUUID(),
+        ts: input.ts || new Date().toISOString(),
+        agentName: cleanAgentName(agentName),
+        actionKind: input.actionKind,
+        action: cleanAuditToken(input.action, "action"),
+        requestedBy: normalizeActor(input.requestedBy),
+        performedBy: normalizeActor(input.performedBy),
+        ...(input.target ? { target: normalizeActor(input.target) } : {}),
+        ...(input.sourceModule ? { sourceModule: cleanAuditToken(input.sourceModule, "sourceModule") } : {}),
+        ...(input.peripheralId ? { peripheralId: cleanAuditToken(input.peripheralId, "peripheralId") } : {}),
+        ...(input.riskLevel ? { riskLevel: input.riskLevel } : {}),
+        ...(input.roleScope ? { roleScope: cleanAuditToken(input.roleScope, "roleScope") } : {}),
+        ...(input.memoryScope ? { memoryScope: input.memoryScope } : {}),
+        ...(input.workdir ? { workdir: input.workdir } : {}),
+        ...(input.projectScope ? { projectScope: input.projectScope } : {}),
+        ...(input.transport ? { transport: input.transport } : {}),
+        decision: {
+            result: input.decision.result,
+            mode: input.decision.mode,
+            ...(input.decision.reason ? { reason: truncate(input.decision.reason, 500) } : {}),
+        },
+        ...(input.allowedActions?.length ? { allowedActions: input.allowedActions.map((item) => truncate(item, 300)) } : {}),
+        ...(input.forbiddenActions?.length ? { forbiddenActions: input.forbiddenActions.map((item) => truncate(item, 300)) } : {}),
+        ...(input.references ? { references: compactStringRecord(input.references) } : {}),
+        ...(input.metadata ? { metadata: redactSecrets(input.metadata) } : {}),
+    };
+}
+export async function appendPermissionAuditRecord(agentName, input) {
+    const record = isPermissionAuditRecord(input) ? input : createPermissionAuditRecord(agentName, input);
+    const file = permissionAuditLogPath(record.agentName);
+    await mkdir(agentAuditDir(record.agentName), { recursive: true });
+    await appendFile(file, `${renderAuditRecord(record)}\n`, "utf-8");
+    return file;
+}
+export function appendPermissionAuditRecordSync(agentName, input) {
+    const record = isPermissionAuditRecord(input) ? input : createPermissionAuditRecord(agentName, input);
+    const file = permissionAuditLogPath(record.agentName);
+    mkdirSync(agentAuditDir(record.agentName), { recursive: true });
+    appendFileSync(file, `${renderAuditRecord(record)}\n`, "utf-8");
+    return file;
+}
+export async function listPermissionAuditRecords(agentName, options = {}) {
+    let raw = "";
+    try {
+        raw = await readFile(permissionAuditLogPath(agentName), "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const limit = clampLimit(options.limit);
+    const records = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        try {
+            const record = JSON.parse(line);
+            if (!isPermissionAuditRecord(record))
+                continue;
+            if (options.actionKind && record.actionKind !== options.actionKind)
+                continue;
+            if (options.decision && record.decision.result !== options.decision)
+                continue;
+            records.push(record);
+        }
+        catch {
+            // Ignore malformed audit lines; the log is append-only and best-effort.
+        }
+    }
+    return records.sort((a, b) => b.ts.localeCompare(a.ts)).slice(0, limit);
+}
+function renderAuditRecord(record) {
+    return redactSecrets(JSON.stringify(record));
+}
+function isPermissionAuditRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return record.schemaVersion === 1
+        && typeof record.id === "string"
+        && typeof record.ts === "string"
+        && typeof record.agentName === "string"
+        && typeof record.actionKind === "string"
+        && typeof record.action === "string"
+        && !!record.requestedBy
+        && !!record.performedBy
+        && !!record.decision;
+}
+function normalizeActor(actor) {
+    return {
+        kind: actor.kind,
+        id: truncate(String(actor.id || "unknown").trim() || "unknown", 160),
+        ...(actor.transport ? { transport: actor.transport } : {}),
+        ...(actor.displayName ? { displayName: truncate(actor.displayName, 160) } : {}),
+    };
+}
+function compactStringRecord(record) {
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (typeof value !== "string" || !value)
+            continue;
+        out[cleanAuditToken(key, "referenceKey")] = truncate(value, 500);
+    }
+    return out;
+}
+function cleanAuditToken(value, field) {
+    const cleaned = value.trim().replace(/\s+/g, "-").slice(0, 120);
+    if (!cleaned)
+        throw new Error(`Invalid ${field}: empty`);
+    return cleaned;
+}
+function truncate(value, max) {
+    return value.length <= max ? value : value.slice(0, max);
+}
+function clampLimit(value) {
+    if (!Number.isInteger(value) || !value || value <= 0)
+        return DEFAULT_AUDIT_LIMIT;
+    return Math.min(value, MAX_AUDIT_LIMIT);
+}

package/dist/relay-client.js

@@ -2,6 +2,8 @@ import WebSocket from "ws";
 import http from "http";
 import { getMetrics, updateMetrics } from "./metrics.js";
 import { redactText, StreamingRedactor } from "./redaction.js";
+import { getRuntimePlatform } from "./runtime-platform.js";
+import { createRelayAgentCallMessage, createRelayAgentCallResultMessage, isAkemonMessageEnvelope, textFromAkemonMessage, } from "./akemon-message.js";
 const DEFAULT_RELAY_URL = "wss://relay.akemon.dev";
 // Pending agent_call results (callId → resolve function)
 const pendingAgentCalls = new Map();
@@ -26,9 +28,16 @@ function startPTY(ws, cols, rows) {
         console.log("[terminal] PTY already running, ignoring duplicate start");
         return;
     }
+    const runtime = getRuntimePlatform();
+    if (!runtime.capabilities.canStartPty) {
+        const error = `Terminal PTY is not supported on this platform: ${runtime.platform}`;
+        console.error(`[terminal] ${error}`);
+        ws.send(JSON.stringify({ type: "terminal_exit", error }));
+        return;
+    }
     // Dynamic import so node-pty is only loaded when needed
     import("node-pty").then((pty) => {
-        const shell = process.env.SHELL || "/bin/bash";
+        const shell = runtime.defaultShell;
         ptyProcess = pty.spawn(shell, [], {
             name: "xterm-256color",
             cols: cols || 80,
@@ -65,19 +74,33 @@ function stopPTY() {
     }
 }
 /** Call another agent through the relay. Available to any engine. */
-export function callAgent(target, task) {
+export function callAgent(target, task, options = {}) {
     return new Promise((resolve, reject) => {
         if (!relayWsRef || relayWsRef.readyState !== WebSocket.OPEN) {
             reject(new Error("Not connected to relay"));
             return;
         }
         const callId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+        const akemonMessage = createRelayAgentCallMessage({
+            callId,
+            caller: options.sourceAgent || "unknown",
+            target,
+            task,
+            conversationId: options.conversationId,
+            memoryScope: options.memoryScope,
+            requiresOwnerApproval: options.requiresOwnerApproval,
+        });
         pendingAgentCalls.set(callId, resolve);
         relayWsRef.send(JSON.stringify({
             type: "agent_call",
             call_id: callId,
+            ...(options.sourceAgent ? { caller: options.sourceAgent } : {}),
             target,
             task,
+            conversation_id: options.conversationId,
+            memory_scope: akemonMessage.memoryScope,
+            require_owner_approval: akemonMessage.permissions.requiresOwnerApproval === true,
+            akemon_message: akemonMessage,
         }));
         // Timeout after 5 minutes
         setTimeout(() => {
@@ -254,7 +277,7 @@ export function connectRelay(options) {
                     handleControl(ws, msg);
                     break;
                 case "agent_call":
-                    handleIncomingAgentCall(ws, msg, options.localPort);
+                    handleIncomingAgentCall(ws, msg, options.localPort, options.agentName);
                     break;
                 case "agent_call_result":
                     handleAgentCallResult(msg);
@@ -310,11 +333,22 @@ export function connectRelay(options) {
     }
     connect();
 }
-function handleIncomingAgentCall(ws, msg, localPort) {
+function handleIncomingAgentCall(ws, msg, localPort, agentName) {
     const callId = msg.call_id || "";
-    const caller = msg.caller || "unknown";
-    const task = msg.task || "";
-    console.log(`[agent_call] Incoming from ${caller}: ${task.slice(0, 80)}`);
+    const incomingMessage = isAkemonMessageEnvelope(msg.akemon_message)
+        ? msg.akemon_message
+        : createRelayAgentCallMessage({
+            callId,
+            caller: msg.caller || "unknown",
+            target: agentName,
+            task: msg.task || "",
+            conversationId: msg.conversation_id,
+            memoryScope: msg.memory_scope,
+            requiresOwnerApproval: msg.require_owner_approval === true,
+        });
+    const caller = incomingMessage.source.id || msg.caller || "unknown";
+    const task = textFromAkemonMessage(incomingMessage);
+    console.log(`[agent_call] Incoming ${incomingMessage.type} from ${caller}: ${task.slice(0, 80)}`);
     // Forward to local MCP as a submit_task call
     const initBody = JSON.stringify({
         jsonrpc: "2.0", id: 1,
@@ -348,7 +382,13 @@ function handleIncomingAgentCall(ws, msg, localPort) {
         const callBody = JSON.stringify({
             jsonrpc: "2.0", id: 2,
             method: "tools/call",
-            params: { name: "submit_task", arguments: { task } },
+            params: {
+                name: "submit_task",
+                arguments: {
+                    task,
+                    require_human: incomingMessage.permissions.requiresOwnerApproval === true,
+                },
+            },
         });
         return doRequest(callBody, sid);
     })
@@ -377,20 +417,39 @@ function handleIncomingAgentCall(ws, msg, localPort) {
             }
         }
         catch { /* use raw */ }
+        const responseMessage = createRelayAgentCallResultMessage({
+            callId,
+            responder: agentName,
+            requester: incomingMessage.source,
+            result,
+            conversationId: incomingMessage.conversationId,
+            inReplyTo: incomingMessage.id,
+        });
         ws.send(JSON.stringify({
             type: "agent_call_result",
             call_id: callId,
             caller,
             result,
+            akemon_message: responseMessage,
         }));
         console.log(`[agent_call] Replied to ${caller} (${result.length} bytes)`);
     })
         .catch((err) => {
+        const errorResult = `[error] ${err.message}`;
+        const responseMessage = createRelayAgentCallResultMessage({
+            callId,
+            responder: agentName,
+            requester: incomingMessage.source,
+            result: errorResult,
+            conversationId: incomingMessage.conversationId,
+            inReplyTo: incomingMessage.id,
+        });
         ws.send(JSON.stringify({
             type: "agent_call_result",
             call_id: callId,
             caller,
-            result: `[error] ${err.message}`,
+            result: errorResult,
+            akemon_message: responseMessage,
         }));
     });
 }

package/dist/relay-mode.js

@@ -0,0 +1,34 @@
+export const DEFAULT_RELAY_WS = "wss://relay.akemon.dev";
+export const DEFAULT_RELAY_HTTP = "https://relay.akemon.dev";
+export function relayHttpFromWs(relayWs) {
+    return relayWs.replace(/^wss:/, "https:").replace(/^ws:/, "http:");
+}
+export function resolveServeRelayMode(input) {
+    const relay = input.relay?.trim();
+    if (input.localOnly) {
+        if (input.public) {
+            throw new Error("--local-only cannot be combined with --public");
+        }
+        if (relay) {
+            throw new Error("--local-only cannot be combined with --relay");
+        }
+        return { enabled: false, reason: "local-only" };
+    }
+    if (relay) {
+        return {
+            enabled: true,
+            relayWs: relay,
+            relayHttp: relayHttpFromWs(relay),
+            reason: "explicit-relay",
+        };
+    }
+    if (input.public) {
+        return {
+            enabled: true,
+            relayWs: DEFAULT_RELAY_WS,
+            relayHttp: DEFAULT_RELAY_HTTP,
+            reason: "public-default-relay",
+        };
+    }
+    return { enabled: false, reason: "local-only" };
+}