akemon 0.3.6 → 0.3.7

package/dist/work-memory.js

@@ -3,13 +3,16 @@ 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_DIR = "work";
 const WORK_INBOX_FILE = "inbox.md";
 const DEFAULT_CONTEXT_FILES = [
     "README.md",
@@ -29,15 +32,26 @@ const INDEX_FILE_EXTENSIONS = new Set([
     ".yml",
 ]);
 export function workMemoryDir(workdir, agentName) {
-    return join(workdir, ".akemon", "agents", cleanAgentName(agentName), WORK_DIR);
+    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 = workMemoryDir(opts.workdir, 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);
@@ -45,6 +59,7 @@ export async function buildWorkMemoryContext(opts) {
         agentName,
         workdir: opts.workdir,
         workMemoryDir: root,
+        workMemoryScope,
         generatedAt,
         purpose,
         budget,
@@ -54,6 +69,7 @@ export async function buildWorkMemoryContext(opts) {
         agentName,
         workdir: opts.workdir,
         workMemoryDir: root,
+        workMemoryScope,
         generatedAt,
         purpose,
         budget,
@@ -80,11 +96,46 @@ export async function appendWorkMemoryNote(input) {
     if (target)
         note.target = target;
     const redacted = redactSecrets(note);
+    const root = resolveWorkMemoryDir(input.workdir, note.agentName, input.global === true);
     const path = target
-        ? join(workMemoryDir(input.workdir, note.agentName), target)
-        : workMemoryInboxPath(input.workdir, note.agentName);
+        ? 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) {
@@ -168,11 +219,13 @@ async function walk(root, relativeDir, depth, files) {
     }
 }
 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}`,
@@ -188,7 +241,7 @@ function renderWorkMemoryContext(packet) {
         "## Suggested Update Command",
         "",
         "```bash",
-        `akemon work-note \"<durable work memory>\" --source codex --kind decision`,
+        `akemon work-note${globalFlag} \"<durable work memory>\" --source codex --kind decision`,
         "```",
     ];
     if (!packet.sections.length) {
@@ -247,15 +300,6 @@ function cleanToken(value, field, maxChars) {
     }
     return cleaned;
 }
-function cleanAgentName(value) {
-    const cleaned = cleanSingleLine(value, 120);
-    if (!cleaned)
-        throw new Error("Missing required agentName");
-    if (cleaned === "." || cleaned === ".." || cleaned.includes("/") || cleaned.includes("\\") || cleaned.includes("\0")) {
-        throw new Error("Invalid agentName: path separators and NUL bytes are not allowed");
-    }
-    return cleaned;
-}
 function cleanOptionalToken(value, field, maxChars) {
     if (value === undefined || value === null || value.trim() === "")
         return undefined;

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");