@phnx-labs/agents-cli 1.20.52 → 1.20.53

package/dist/lib/memory.js

@@ -0,0 +1,274 @@
+/**
+ * Canonical agent memory resource — accumulated facts/preferences/knowledge
+ * distinct from `rules` (instructions / AGENTS.md persona).
+ *
+ * Layout (project > user > system layering):
+ *   ~/.agents/memory/MEMORY.md          always-read index
+ *   ~/.agents/memory/<slug>.md          individual facts
+ *   ~/.agents/.system/memory/           system layer
+ *   <project>/.agents/memory/           project layer
+ *
+ * Sync fans out into each capable agent's version home under an agent-specific
+ * target dir (see memoryTargetDir).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, ensureAgentsDir, } from './state.js';
+import { agentConfigDirName } from './agents.js';
+import { supports } from './capabilities.js';
+/** User-layer memory root (~/.agents/memory/). */
+export function getUserMemoryDir() {
+    return path.join(getUserAgentsDir(), 'memory');
+}
+/** System-layer memory root (~/.agents/.system/memory/). */
+export function getSystemMemoryDir() {
+    return path.join(getSystemAgentsDir(), 'memory');
+}
+/** Project-layer memory root when a project agents dir exists. */
+export function getProjectMemoryDir(cwd = process.cwd()) {
+    const project = getProjectAgentsDir(cwd);
+    return project ? path.join(project, 'memory') : null;
+}
+/** Ensure the user memory dir exists (creates MEMORY.md index if missing). */
+export function ensureUserMemoryDir() {
+    ensureAgentsDir();
+    const dir = getUserMemoryDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const index = path.join(dir, 'MEMORY.md');
+    if (!fs.existsSync(index)) {
+        fs.writeFileSync(index, [
+            '# Memory index',
+            '',
+            'Always-read summary of accumulated agent memory. Individual facts live',
+            'as sibling `*.md` files. Managed by `agents memory`.',
+            '',
+        ].join('\n'), 'utf-8');
+    }
+    return dir;
+}
+function isFactFile(name) {
+    return name.endsWith('.md') && name.toLowerCase() !== 'memory.md';
+}
+function slugify(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64) || 'fact';
+}
+function summarize(content) {
+    for (const line of content.split('\n')) {
+        const t = line.trim();
+        if (!t || t.startsWith('#'))
+            continue;
+        return t.length > 80 ? t.slice(0, 77) + '...' : t;
+    }
+    return '(empty)';
+}
+/** Layer dirs highest-priority first. */
+export function getMemoryLayerDirs(cwd = process.cwd()) {
+    const out = [];
+    const project = getProjectMemoryDir(cwd);
+    if (project && fs.existsSync(project))
+        out.push({ layer: 'project', dir: project });
+    const user = getUserMemoryDir();
+    if (fs.existsSync(user))
+        out.push({ layer: 'user', dir: user });
+    const system = getSystemMemoryDir();
+    if (fs.existsSync(system))
+        out.push({ layer: 'system', dir: system });
+    return out;
+}
+/** List memory facts with project > user > system override on name. */
+export function listMemoryFacts(cwd = process.cwd()) {
+    const seen = new Set();
+    const results = [];
+    for (const { layer, dir } of getMemoryLayerDirs(cwd)) {
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const file of entries) {
+            if (!isFactFile(file))
+                continue;
+            const name = file.replace(/\.md$/i, '');
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            const filePath = path.join(dir, file);
+            let content = '';
+            try {
+                content = fs.readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            results.push({ name, path: filePath, layer, summary: summarize(content) });
+        }
+    }
+    return results.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Read one fact by name (winning layer). */
+export function readMemoryFact(name, cwd = process.cwd()) {
+    const slug = slugify(name);
+    for (const { layer, dir } of getMemoryLayerDirs(cwd)) {
+        const filePath = path.join(dir, `${slug}.md`);
+        if (!fs.existsSync(filePath))
+            continue;
+        let content = '';
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        return { name: slug, path: filePath, layer, summary: summarize(content) };
+    }
+    return null;
+}
+/** Write a fact into the user layer. Returns the absolute path. */
+export function addMemoryFact(name, body) {
+    const dir = ensureUserMemoryDir();
+    const slug = slugify(name);
+    const filePath = path.join(dir, `${slug}.md`);
+    const content = body.trimStart().startsWith('#')
+        ? body.endsWith('\n') ? body : body + '\n'
+        : `# ${slug}\n\n${body.trim()}\n`;
+    fs.writeFileSync(filePath, content, 'utf-8');
+    rebuildMemoryIndex(dir);
+    return filePath;
+}
+/** Remove a fact from the user layer. Returns true if a file was deleted. */
+export function removeMemoryFact(name) {
+    const dir = getUserMemoryDir();
+    const slug = slugify(name);
+    const filePath = path.join(dir, `${slug}.md`);
+    if (!fs.existsSync(filePath))
+        return false;
+    fs.unlinkSync(filePath);
+    if (fs.existsSync(dir))
+        rebuildMemoryIndex(dir);
+    return true;
+}
+/** Rebuild MEMORY.md index from sibling fact files in a single layer dir. */
+export function rebuildMemoryIndex(dir) {
+    let facts = [];
+    try {
+        facts = fs.readdirSync(dir).filter(isFactFile).sort();
+    }
+    catch {
+        return;
+    }
+    const lines = [
+        '# Memory index',
+        '',
+        'Always-read summary of accumulated agent memory. Managed by `agents memory`.',
+        '',
+    ];
+    if (facts.length === 0) {
+        lines.push('_No facts yet. Add one with `agents memory add <name> --body "..."`._', '');
+    }
+    else {
+        for (const file of facts) {
+            const name = file.replace(/\.md$/i, '');
+            let summary = '';
+            try {
+                summary = summarize(fs.readFileSync(path.join(dir, file), 'utf-8'));
+            }
+            catch {
+                summary = '';
+            }
+            lines.push(`- **${name}** — ${summary}`);
+        }
+        lines.push('');
+    }
+    fs.writeFileSync(path.join(dir, 'MEMORY.md'), lines.join('\n'), 'utf-8');
+}
+/**
+ * Per-agent target directory (relative to version home) for synced memory.
+ * Claude/Codex/OpenClaw/Grok get native-ish paths; others get a generic memory/.
+ */
+export function memoryTargetDir(agent) {
+    switch (agent) {
+        case 'claude':
+            return path.join(agentConfigDirName(agent), 'memory');
+        case 'codex':
+            return path.join(agentConfigDirName(agent), 'memories');
+        case 'openclaw':
+        case 'grok':
+            return 'memory';
+        default:
+            return path.join(agentConfigDirName(agent), 'memory');
+    }
+}
+/** Copy canonical layered memory into one version home. Returns fact names written. */
+export function syncMemoryToVersionHome(agent, versionHome, cwd = process.cwd()) {
+    if (!supports(agent, 'memory').ok)
+        return [];
+    const facts = listMemoryFacts(cwd);
+    const targetRel = memoryTargetDir(agent);
+    const targetDir = path.join(versionHome, targetRel);
+    fs.mkdirSync(targetDir, { recursive: true });
+    // Managed manifest tracks which fact files *we* wrote. On sync we only
+    // remove previously-managed names that are no longer in the canonical set —
+    // never wipe every .md (user-authored native memory must survive).
+    const managedManifestPath = path.join(targetDir, '.agents-cli-memory.json');
+    let previouslyManaged = [];
+    try {
+        const raw = JSON.parse(fs.readFileSync(managedManifestPath, 'utf-8'));
+        if (Array.isArray(raw.facts)) {
+            previouslyManaged = raw.facts.filter((f) => typeof f === 'string');
+        }
+    }
+    catch { /* missing or corrupt → treat as first managed sync */ }
+    const desiredNames = new Set(facts.map((f) => f.name));
+    const managedThisSync = new Set(desiredNames);
+    for (const name of previouslyManaged) {
+        if (desiredNames.has(name))
+            continue;
+        if (name === 'MEMORY')
+            continue; // index rewritten below
+        try {
+            fs.unlinkSync(path.join(targetDir, `${name}.md`));
+        }
+        catch { /* ignore */ }
+    }
+    const written = [];
+    for (const fact of facts) {
+        const dest = path.join(targetDir, `${fact.name}.md`);
+        try {
+            fs.copyFileSync(fact.path, dest);
+            written.push(fact.name);
+        }
+        catch { /* skip unreadable */ }
+    }
+    // Always write an index from the winning layers.
+    const indexSrc = (() => {
+        for (const { dir } of getMemoryLayerDirs(cwd)) {
+            const p = path.join(dir, 'MEMORY.md');
+            if (fs.existsSync(p))
+                return p;
+        }
+        return null;
+    })();
+    if (indexSrc) {
+        try {
+            fs.copyFileSync(indexSrc, path.join(targetDir, 'MEMORY.md'));
+            managedThisSync.add('MEMORY');
+        }
+        catch { /* ignore */ }
+    }
+    else {
+        rebuildMemoryIndex(targetDir);
+        managedThisSync.add('MEMORY');
+    }
+    try {
+        fs.writeFileSync(managedManifestPath, JSON.stringify({ facts: [...managedThisSync].sort() }, null, 2) + '\n', 'utf-8');
+    }
+    catch { /* best-effort */ }
+    return written;
+}

package/dist/lib/notify.d.ts

@@ -0,0 +1,16 @@
+import type { OpenBlock } from './feed.js';
+export interface NotifyOptions {
+    channel?: string;
+    account?: string;
+    /** OpenClaw destination (Telegram chat id). Defaults to Muqsit's chat. */
+    target?: string;
+    dryRun?: boolean;
+}
+export interface NotifyResult {
+    ok: boolean;
+    skipped?: boolean;
+    error?: string;
+}
+/** Build openclaw argv for urgent notify (exported for tests). */
+export declare function buildOpenClawNotifyArgs(text: string, options?: Pick<NotifyOptions, 'channel' | 'account' | 'target'>): string[];
+export declare function notifyUrgentBlock(block: OpenBlock, options?: NotifyOptions): Promise<NotifyResult>;

package/dist/lib/notify.js

@@ -0,0 +1,61 @@
+/**
+ * Urgent-block phone notifier.
+ *
+ * Reuses the OpenClaw Telegram gateway on the local mac-mini (Jeff/`default` bot)
+ * instead of raw bot tokens. Notifies once per block (tracked by `notifiedAt`).
+ * Best-effort: any openclaw failure is surfaced as a warning, not a hard error,
+ * so a notification hiccup never blocks the agent.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+function formatBlock(block) {
+    const q = block.questions[0];
+    const header = q?.header ? `[${q.header}] ` : '';
+    const text = q?.text ?? 'Agent needs input';
+    const host = block.host ? ` on ${block.host}` : '';
+    const cls = block.blockClass ?? 'approval';
+    const cost = block.costOfDelay ?? 'low';
+    return `🚨 ${cls.toUpperCase()}${host} — ${header}${text} (cost: ${cost}, id: ${block.blockId})`;
+}
+/** Build openclaw argv for urgent notify (exported for tests). */
+export function buildOpenClawNotifyArgs(text, options = {}) {
+    const channel = options.channel ?? 'telegram';
+    const account = options.account ?? 'default';
+    const target = options.target ?? '6078999250';
+    return [
+        'message',
+        'send',
+        '--channel',
+        channel,
+        '--account',
+        account,
+        '--target',
+        target,
+        '--message',
+        text,
+    ];
+}
+export async function notifyUrgentBlock(block, options = {}) {
+    if (block.notifiedAt) {
+        return { ok: true, skipped: true };
+    }
+    if (options.dryRun) {
+        return { ok: true, skipped: true };
+    }
+    // Check that openclaw is installed.
+    try {
+        await execFileAsync('which', ['openclaw']);
+    }
+    catch {
+        return { ok: false, error: 'openclaw CLI not found on PATH' };
+    }
+    const text = formatBlock(block);
+    try {
+        await execFileAsync('openclaw', buildOpenClawNotifyArgs(text, options));
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}

package/dist/lib/operator.d.ts

@@ -0,0 +1,26 @@
+export interface Operator {
+    id: string;
+    name?: string;
+    admin?: boolean;
+    can?: string[];
+}
+export interface OperatorRegistry {
+    operators: Record<string, Operator>;
+}
+export declare function getOperatorsPath(root?: string): string;
+export declare function loadOperators(root?: string): OperatorRegistry;
+export declare function getOperator(id: string, root?: string): Operator | undefined;
+export declare function isKnownOperator(id: string, root?: string): boolean;
+export declare function isAdmin(id: string, root?: string): boolean;
+export declare function canPerform(id: string, action: string, root?: string): boolean;
+/** High-consequence blocks require a known operator with explicit merge/deploy/admin rights. */
+export declare function isHighConsequenceAllowed(blockConsequence: string | undefined, operatorId: string, root?: string): boolean;
+/**
+ * Prove operator identity for high-consequence answers.
+ *
+ * Knowing an id listed in operators.yaml is not authentication — any same-user
+ * process can pass `--as muqsit`. Require the process environment to claim the
+ * same id via AGENTS_OPERATOR_ID (typically injected by `agents secrets` /
+ * the human's launch context).
+ */
+export declare function verifyOperatorIdentity(claimedId: string | undefined, root?: string): boolean;

package/dist/lib/operator.js

@@ -0,0 +1,107 @@
+/**
+ * Operator identity registry for multi-human feed controls.
+ *
+ * The mailbox `from` label is caller-supplied and unverified (same-user-writable).
+ * For routine answers that's fine; for high-consequence blocks (merge/deploy/admin)
+ * we need a verified operator identity. This module loads a local registry of
+ * operators from ~/.agents/operators.yaml and provides the authz check used by
+ * `recordAnswer` and `agents message --as`.
+ *
+ * Registry format (YAML):
+ *   operators:
+ *     muqsit:
+ *       name: Muqsit
+ *       admin: true
+ *     bisma:
+ *       name: Bisma
+ *       can:
+ *         - merge
+ *         - deploy
+ *
+ * For this release identity is proven by knowing the operator id (local registry
+ * membership). A future release can add public-key/totp challenge without changing
+ * the call sites.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getUserAgentsDir } from './state.js';
+const OPERATORS_FILE = 'operators.yaml';
+export function getOperatorsPath(root) {
+    return path.join(root ?? getUserAgentsDir(), OPERATORS_FILE);
+}
+export function loadOperators(root) {
+    const file = getOperatorsPath(root);
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const parsed = yaml.parse(raw);
+        if (parsed && typeof parsed === 'object' && 'operators' in parsed) {
+            const ops = parsed.operators;
+            const operators = {};
+            for (const [id, v] of Object.entries(ops)) {
+                if (v && typeof v === 'object') {
+                    const entry = v;
+                    operators[id] = {
+                        id,
+                        name: typeof entry.name === 'string' ? entry.name : undefined,
+                        admin: entry.admin === true,
+                        can: Array.isArray(entry.can)
+                            ? entry.can.filter((c) => typeof c === 'string')
+                            : undefined,
+                    };
+                }
+            }
+            return { operators };
+        }
+    }
+    catch {
+        // missing or malformed -> empty registry
+    }
+    return { operators: {} };
+}
+export function getOperator(id, root) {
+    return loadOperators(root).operators[id];
+}
+export function isKnownOperator(id, root) {
+    return getOperator(id, root) !== undefined;
+}
+export function isAdmin(id, root) {
+    const op = getOperator(id, root);
+    return op?.admin === true;
+}
+export function canPerform(id, action, root) {
+    const op = getOperator(id, root);
+    if (!op)
+        return false;
+    if (op.admin)
+        return true;
+    return op.can?.includes(action) ?? false;
+}
+/** High-consequence blocks require a known operator with explicit merge/deploy/admin rights. */
+export function isHighConsequenceAllowed(blockConsequence, operatorId, root) {
+    if (!blockConsequence || blockConsequence === 'normal')
+        return true;
+    if (!isKnownOperator(operatorId, root))
+        return false;
+    if (isAdmin(operatorId, root))
+        return true;
+    return canPerform(operatorId, blockConsequence, root);
+}
+/**
+ * Prove operator identity for high-consequence answers.
+ *
+ * Knowing an id listed in operators.yaml is not authentication — any same-user
+ * process can pass `--as muqsit`. Require the process environment to claim the
+ * same id via AGENTS_OPERATOR_ID (typically injected by `agents secrets` /
+ * the human's launch context).
+ */
+export function verifyOperatorIdentity(claimedId, root) {
+    if (!claimedId)
+        return false;
+    if (!isKnownOperator(claimedId, root))
+        return false;
+    const envId = process.env.AGENTS_OPERATOR_ID?.trim();
+    if (!envId)
+        return false;
+    return envId === claimedId;
+}

package/dist/lib/plugins.d.ts

@@ -79,6 +79,8 @@ export declare function getPlugin(name: string): DiscoveredPlugin | null;
  * Otherwise defaults to all plugin-capable agents.
  */
 export declare function pluginSupportsAgent(plugin: DiscoveredPlugin, agent: AgentId): boolean;
+/** Fact basenames (no .md) from a plugin's memory/ directory. */
+export declare function discoverPluginMemory(pluginRoot: string): string[];
 /**
  * The lifecycle events a plugin hooks into, read from hooks/hooks.json.
  *
@@ -168,6 +170,39 @@ export declare function syncPluginToVersion(plugin: DiscoveredPlugin, agent: Age
     mcp: boolean;
     settings: boolean;
 };
+/**
+ * OpenCode loads JS/TS modules from `$HOME/.config/opencode/plugins/` (global)
+ * and `<project>/.opencode/plugins/` (project). Under agents-cli version
+ * isolation HOME is the version home, so we write:
+ *   {versionHome}/.config/opencode/plugins/
+ *
+ * Claude-style marketplace plugins are NOT auto-converted; we install modules
+ * from (in order):
+ *   1. pluginRoot/opencode/*.{ts,js,mjs,cjs}
+ *   2. pluginRoot/plugins/*.{ts,js,mjs,cjs}
+ *   3. pluginRoot/*.{ts,js,mjs,cjs} (excluding *.test.* / *.spec.*)
+ * If none exist, install still succeeds by writing a marker + copying any
+ * package.json so empty plugins don't break sync; opencode simply has nothing
+ * to load until a real module appears.
+ */
+export declare function openCodePluginsDir(versionHome: string): string;
+/** Resolve source module files for an agents-cli plugin to install into OpenCode. */
+export declare function resolveOpenCodePluginSources(pluginRoot: string): string[];
+export declare function installOpenCodePlugin(plugin: DiscoveredPlugin, versionHome: string): boolean;
+export declare function isOpenCodePluginInstalled(pluginName: string, versionHome: string): boolean;
+export declare function removeOpenCodePlugin(pluginName: string, versionHome: string): boolean;
+/**
+ * Goose auto-discovers Open Plugins at `$HOME/.agents/plugins/<name>/`.
+ * Under agents-cli version isolation HOME is the version home, so we install to:
+ *   {versionHome}/.agents/plugins/<name>/
+ *
+ * Full plugin directory copy (not marketplace) — same layout goose and
+ * agents-cli share for source plugins.
+ */
+export declare function goosePluginsDir(versionHome: string): string;
+export declare function installGoosePlugin(plugin: DiscoveredPlugin, versionHome: string): boolean;
+export declare function isGoosePluginInstalled(pluginName: string, versionHome: string): boolean;
+export declare function removeGoosePlugin(pluginName: string, versionHome: string): boolean;
 /**
  * Check if a plugin is synced to a version. True when the plugin lives at the
  * native marketplace install path. Legacy dual-dash entries are not counted —