akemon 0.3.5 → 0.3.7

package/dist/work-memory.js

@@ -0,0 +1,339 @@
+import { randomUUID } from "crypto";
+import { appendFile, mkdir, readdir, readFile } from "fs/promises";
+import { basename, dirname, join } from "path";
+import { localNow } from "./self.js";
+import { redactSecrets, redactText } from "./redaction.js";
+import { actorRef } from "./akemon-message.js";
+import { appendPermissionAuditRecord } from "./permission-audit.js";
+import { logBestEffortError } from "./best-effort.js";
+import { cleanAgentName, globalWorkMemoryDir, projectWorkMemoryDir, } from "./akemon-home.js";
+const DEFAULT_CONTEXT_BUDGET = 12_000;
+const MIN_CONTEXT_BUDGET = 1_000;
+const MAX_CONTEXT_BUDGET = 80_000;
+const MAX_SECTION_CHARS = 4_000;
+const MAX_INDEX_FILES = 200;
+const MAX_INDEX_DEPTH = 4;
+const WORK_INBOX_FILE = "inbox.md";
+const DEFAULT_CONTEXT_FILES = [
+    "README.md",
+    "current.md",
+    "handoff.md",
+    "decisions.md",
+    "commands.md",
+    "notes.md",
+    WORK_INBOX_FILE,
+];
+const INDEX_FILE_EXTENSIONS = new Set([
+    ".md",
+    ".txt",
+    ".json",
+    ".jsonl",
+    ".yaml",
+    ".yml",
+]);
+export function workMemoryDir(workdir, agentName) {
+    cleanAgentName(agentName);
+    return projectWorkMemoryDir(workdir);
+}
+export function globalAgentWorkMemoryDir(agentName) {
+    return globalWorkMemoryDir(agentName);
+}
+export function resolveWorkMemoryDir(workdir, agentName, global = false) {
+    return global ? globalAgentWorkMemoryDir(agentName) : workMemoryDir(workdir, agentName);
+}
+export function workMemoryInboxPath(workdir, agentName) {
+    return join(workMemoryDir(workdir, agentName), WORK_INBOX_FILE);
+}
+export function globalWorkMemoryInboxPath(agentName) {
+    return join(globalAgentWorkMemoryDir(agentName), WORK_INBOX_FILE);
+}
+export async function buildWorkMemoryContext(opts) {
+    const budget = normalizeBudget(opts.budget);
+    const agentName = cleanAgentName(opts.agentName);
+    const root = resolveWorkMemoryDir(opts.workdir, agentName, opts.global === true);
+    const workMemoryScope = opts.global === true ? "global" : "project";
+    const generatedAt = localNow();
+    const purpose = cleanSingleLine(opts.purpose || "external software-agent work context", 180);
+    const sections = await collectWorkContextSections(root);
+    const text = renderWorkMemoryContext({
+        agentName,
+        workdir: opts.workdir,
+        workMemoryDir: root,
+        workMemoryScope,
+        generatedAt,
+        purpose,
+        budget,
+        sections,
+    });
+    return {
+        agentName,
+        workdir: opts.workdir,
+        workMemoryDir: root,
+        workMemoryScope,
+        generatedAt,
+        purpose,
+        budget,
+        sections,
+        text: fitText(text, budget),
+    };
+}
+export async function appendWorkMemoryNote(input) {
+    const text = cleanMultiline(input.text, 8_000);
+    if (!text)
+        throw new Error("Missing required work memory note text");
+    const note = {
+        id: `work_${Date.now()}_${randomUUID().slice(0, 8)}`,
+        ts: localNow(),
+        agentName: cleanAgentName(input.agentName),
+        source: cleanToken(input.source || "user", "source", 80),
+        kind: cleanToken(input.kind || "note", "kind", 80),
+        text,
+    };
+    const sessionId = cleanOptionalToken(input.sessionId, "sessionId", 120);
+    if (sessionId)
+        note.sessionId = sessionId;
+    const target = cleanOptionalPathHint(input.target);
+    if (target)
+        note.target = target;
+    const redacted = redactSecrets(note);
+    const root = resolveWorkMemoryDir(input.workdir, note.agentName, input.global === true);
+    const path = target
+        ? join(root, target)
+        : join(root, WORK_INBOX_FILE);
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, renderWorkMemoryNote(redacted), "utf-8");
+    try {
+        await appendPermissionAuditRecord(note.agentName, {
+            actionKind: "memory-write",
+            action: "work-memory.note.append",
+            requestedBy: note.source === "user"
+                ? actorRef("owner", "owner", "local")
+                : actorRef("external", note.source, "unknown"),
+            performedBy: actorRef("agent", note.agentName, "local"),
+            target: actorRef("system", input.global === true ? "global-work-memory" : "project-work-memory", "local"),
+            riskLevel: "low",
+            memoryScope: "task",
+            workdir: input.workdir,
+            projectScope: input.global === true ? "global" : "inside-workdir",
+            transport: "local",
+            decision: {
+                result: "allowed",
+                mode: note.source === "user" ? "owner-approved" : "automatic",
+                reason: "Work memory note target was validated under the configured work memory directory.",
+            },
+            references: {
+                noteId: note.id,
+                path,
+                sessionId: note.sessionId,
+            },
+            metadata: {
+                kind: note.kind,
+                target: note.target,
+                global: input.global === true,
+            },
+        });
+    }
+    catch (error) {
+        logBestEffortError("work-memory audit append", error);
+    }
+    return { note: redacted, path };
+}
+async function collectWorkContextSections(root) {
+    const sections = [];
+    for (const file of DEFAULT_CONTEXT_FILES) {
+        const section = await readWorkContextFile(root, file);
+        if (section)
+            sections.push(section);
+    }
+    const index = await buildWorkFileIndex(root);
+    if (index)
+        sections.push(index);
+    return sections;
+}
+async function readWorkContextFile(root, relativePath) {
+    const path = join(root, relativePath);
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const redacted = redactText(selectUsefulFileContent(relativePath, raw));
+    const trimmed = redacted.trim();
+    const content = fitText(trimmed, MAX_SECTION_CHARS);
+    return {
+        title: relativePath,
+        path,
+        relativePath,
+        chars: trimmed.length,
+        truncated: content.length < trimmed.length,
+        content,
+    };
+}
+async function buildWorkFileIndex(root) {
+    const files = await listWorkMemoryFiles(root);
+    if (!files.length)
+        return null;
+    const content = files.map((file) => `- ${file}`).join("\n");
+    return {
+        title: "work memory file index",
+        path: root,
+        relativePath: ".",
+        chars: content.length,
+        truncated: files.length >= MAX_INDEX_FILES,
+        content,
+    };
+}
+async function listWorkMemoryFiles(root) {
+    const files = [];
+    await walk(root, "", 0, files);
+    return files.sort((a, b) => a.localeCompare(b)).slice(0, MAX_INDEX_FILES);
+}
+async function walk(root, relativeDir, depth, files) {
+    if (depth > MAX_INDEX_DEPTH || files.length >= MAX_INDEX_FILES)
+        return;
+    const dir = relativeDir ? join(root, relativeDir) : root;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (files.length >= MAX_INDEX_FILES)
+            return;
+        if (entry.name.startsWith("."))
+            continue;
+        const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            await walk(root, relativePath, depth + 1, files);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (!INDEX_FILE_EXTENSIONS.has(extensionOf(entry.name)))
+            continue;
+        files.push(relativePath);
+    }
+}
+function renderWorkMemoryContext(packet) {
+    const globalFlag = packet.workMemoryScope === "global" ? " --global" : "";
+    const lines = [
+        "# Akemon Work Memory Context",
+        "",
+        `Generated at: ${packet.generatedAt}`,
+        `Agent: ${packet.agentName}`,
+        `Scope: ${packet.workMemoryScope}`,
+        `Purpose: ${packet.purpose}`,
+        `Workdir: ${packet.workdir}`,
+        `Work memory directory: ${packet.workMemoryDir}`,
+        "",
+        "## Boundary",
+        "",
+        "- This is user-owned work memory for engineering and task continuity.",
+        "- External tools such as Codex or Claude Code may read this work directory as task context.",
+        "- External tools may update this work directory when the user or task asks them to maintain work memory.",
+        "- Do not read or edit Akemon self memory through this work-memory interface.",
+        "- Use grep, direct file reading, semantic review, or your own tool workflow as appropriate for the task.",
+        "",
+        "## Suggested Update Command",
+        "",
+        "```bash",
+        `akemon work-note${globalFlag} \"<durable work memory>\" --source codex --kind decision`,
+        "```",
+    ];
+    if (!packet.sections.length) {
+        lines.push("", "## Included Work Memory", "", "No work memory files were found yet.");
+        lines.push("", "Create files under the work memory directory or use `akemon work-note` to append a quick note.");
+        return lines.join("\n");
+    }
+    lines.push("", "## Included Work Memory");
+    for (const section of packet.sections) {
+        lines.push("");
+        lines.push(`### ${section.title}`);
+        if (section.relativePath)
+            lines.push(`Path: ${section.relativePath}`);
+        if (section.truncated)
+            lines.push(`Truncated from ${section.chars} chars.`);
+        lines.push("");
+        lines.push("```");
+        lines.push(section.content || "(empty)");
+        lines.push("```");
+    }
+    return lines.join("\n");
+}
+function renderWorkMemoryNote(note) {
+    const lines = [
+        "",
+        `## ${note.ts} ${note.kind}`,
+        "",
+        `Source: ${note.source}`,
+    ];
+    if (note.sessionId)
+        lines.push(`Session: ${note.sessionId}`);
+    if (note.target)
+        lines.push(`Target: ${note.target}`);
+    lines.push("", note.text.trim(), "");
+    return lines.join("\n");
+}
+function selectUsefulFileContent(relativePath, raw) {
+    if (!relativePath.endsWith(".jsonl"))
+        return raw;
+    const lines = raw.trim().split(/\r?\n/).filter(Boolean);
+    return lines.slice(-20).join("\n");
+}
+function normalizeBudget(value) {
+    if (value === undefined || value === null)
+        return DEFAULT_CONTEXT_BUDGET;
+    if (!Number.isInteger(value) || value <= 0)
+        throw new Error("Context budget must be a positive integer");
+    return Math.max(MIN_CONTEXT_BUDGET, Math.min(MAX_CONTEXT_BUDGET, value));
+}
+function cleanToken(value, field, maxChars) {
+    const cleaned = cleanSingleLine(value, maxChars);
+    if (!cleaned)
+        throw new Error(`Missing required ${field}`);
+    if (!/^[A-Za-z0-9_.:@-]+$/.test(cleaned)) {
+        throw new Error(`Invalid ${field}: expected letters, numbers, dot, underscore, colon, at, or hyphen`);
+    }
+    return cleaned;
+}
+function cleanOptionalToken(value, field, maxChars) {
+    if (value === undefined || value === null || value.trim() === "")
+        return undefined;
+    return cleanToken(value, field, maxChars);
+}
+function cleanOptionalPathHint(value) {
+    if (value === undefined || value === null || value.trim() === "")
+        return undefined;
+    const cleaned = cleanSingleLine(value, 240);
+    if (cleaned.includes("\0") || cleaned.startsWith("/") || cleaned.includes("\\") || cleaned.split("/").includes("..")) {
+        throw new Error("Invalid target path");
+    }
+    const base = basename(cleaned);
+    if (base === "." || base === "..")
+        throw new Error("Invalid target path");
+    return cleaned;
+}
+function cleanSingleLine(value, maxChars) {
+    return fitText(String(value || "").replace(/\s+/g, " ").trim(), maxChars);
+}
+function cleanMultiline(value, maxChars) {
+    return fitText(String(value || "").replace(/\0/g, "").trim(), maxChars);
+}
+function fitText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    if (maxChars <= 20)
+        return text.slice(0, maxChars);
+    const omitted = text.length - maxChars;
+    const head = Math.floor(maxChars * 0.65);
+    const tail = Math.max(0, maxChars - head - 40);
+    return `${text.slice(0, head)}\n[truncated ${omitted} chars]\n${text.slice(-tail)}`;
+}
+function extensionOf(file) {
+    const index = file.lastIndexOf(".");
+    return index >= 0 ? file.slice(index).toLowerCase() : "";
+}

package/dist/workbench-peripheral-guide.js

@@ -0,0 +1,79 @@
+export const WORKBENCH_PERIPHERAL_GUIDE = [
+    "[Interactive Session Peripheral Usage Guide]",
+    "Workbench is the current local surface for the interactive-session peripheral.",
+    "The interactive session capability owns local Claude, Codex, shell, cursor, and custom PTY sessions; Workbench displays and controls it.",
+    "",
+    "Use interactive-session when:",
+    "- the owner asks to start or observe a local Claude, Codex, shell, or custom PTY session",
+    "- the owner asks what interactive sessions are running",
+    "- the owner asks to send text to an existing session",
+    "- the owner wants to take over, stop, or resize a local interactive session",
+    "",
+    "Do not use Workbench when:",
+    "- a direct Core CM answer is enough",
+    "- the task is primarily a durable memory update",
+    "- the requested action is outside the adapter's exposed capabilities",
+    "",
+    "Current exposed capabilities:",
+    "- list_sessions: inspect tracked Workbench sessions",
+    "- inspect_session: inspect one tracked Workbench session's status and recent output",
+    "- start_session: start a codex, claude, cursor, shell, or custom session",
+    "- send_input: send text or an Enter key to an existing session",
+    "- set_input_mode: switch a session between line input and TUI input",
+    "- resize_session: resize an existing interactive session",
+    "- stop_session: stop an existing session",
+    "- capture_output: capture recent output from an existing session",
+    "",
+    "Important behavior rules:",
+    "- Do not claim that a session action happened until Akemon receives an adapter observation.",
+    "- If a session action is needed but has not happened yet, say what action should be taken next.",
+    "- Explain interactive session actions to the owner in natural language.",
+    "- Do not present slash commands as the normal user interface unless the owner explicitly asks for manual/debug commands.",
+    "- Slash commands remain available only as a debug/manual control path.",
+].join("\n");
+export const WORKBENCH_ACTION_PROPOSAL_GUIDE = [
+    "[Interactive Session Action Proposal Contract]",
+    "When the owner's request requires an interactive session action, output only JSON in this exact shape:",
+    "{",
+    "  \"kind\": \"use_peripheral\",",
+    "  \"peripheral\": \"interactive-session\",",
+    "  \"capability\": \"list_sessions\" | \"inspect_session\" | \"start_session\" | \"send_input\" | \"set_input_mode\" | \"stop_session\" | \"resize_session\" | \"capture_output\",",
+    "  \"args\": { ... },",
+    "  \"reason\": \"short machine-readable reason\",",
+    "  \"processNote\": \"one concise owner-facing sentence explaining why Core CM is taking this step\"",
+    "}",
+    "",
+    "When no interactive session action is needed, output only JSON in this exact shape:",
+    "{",
+    "  \"kind\": \"answer\",",
+    "  \"answer\": \"natural-language answer to the owner\",",
+    "  \"processNote\": \"one concise owner-facing sentence explaining how Core CM handled this request\"",
+    "}",
+    "",
+    "Allowed args:",
+    "- list_sessions: {}",
+    "- inspect_session: { \"sessionId\": string }",
+    "- start_session: { \"tool\": \"codex\" | \"claude\" | \"cursor\" | \"shell\" | \"custom\", \"args\"?: string[], \"command\"?: string, \"workdir\"?: string, \"label\"?: string, \"inputMode\"?: \"line\" | \"tui\" }",
+    "- send_input: { \"sessionId\": string, \"input\": string, \"waitMs\"?: number }",
+    "- set_input_mode: { \"sessionId\": string, \"inputMode\": \"line\" | \"tui\" }",
+    "- stop_session: { \"sessionId\": string }",
+    "- resize_session: { \"sessionId\": string, \"cols\": number, \"rows\": number }",
+    "- capture_output: { \"sessionId\": string }",
+    "",
+    "Rules:",
+    "- Output JSON only. No markdown fences.",
+    "- Always use peripheral \"interactive-session\". Legacy \"workbench\" proposals are accepted only for compatibility, not as new output.",
+    "- Always write processNote in the configured owner-facing language. It is for the CM area, not a debug log.",
+    "- Do not put JSON keys, taskKind, capability names, adapter names, token counts, or event ids in processNote unless the owner explicitly asks for debug details.",
+    "- Use inspect_session when the owner asks what a specific session returned, what it is doing, or whether it has new output.",
+    "- Use capture_output when the owner specifically asks for raw recent output instead of a natural-language inspection.",
+    "- Use start_session only when the owner asks to start a local interactive session.",
+    "- Use send_input only when the owner asks to send text to an existing session.",
+    "- Use resize_session when the owner asks Akemon to resize a terminal session.",
+    "- Use set_input_mode when the owner says a shell/custom session is now running Codex, Cursor, or another interactive TUI and input is not submitting.",
+    "- For send_input, include the text exactly as the owner wants it sent; Akemon will append Enter if needed.",
+    "- Input modes: line is normal terminal input. tui uses bracketed paste plus delayed Enter for interactive TUIs. Do not guess TUI mode from output unless the owner gives a clear clue.",
+    "- For send_input, set waitMs when the owner expects Akemon to observe the immediate result. Use 3000-8000 for typical CLI commands, and omit it for fire-and-forget interactive input. Maximum is 10000.",
+    "- Do not invent session ids. Use ids from the current interactive session context, or use sessionId \"latest\" when the owner clearly means the most recent session.",
+    "- Session aliases: \"active\" and \"current\" mean the browser-selected Workbench session when available; \"latest\" and \"last\" mean the most recently started matching session; \"recent\" means the most recently updated matching session.",
+].join("\n");