termdock 1.3.1 → 1.4.1

package/dist/server/agent/plugins.js

@@ -0,0 +1,271 @@
+/**
+ * Agent plugin system: user-defined agents loaded from
+ * `~/.termdock/agent-plugins/<slug>/manifest.json`.
+ *
+ * Each plugin can define:
+ * 1. Agent identity (display name, aliases, accent color, icon)
+ * 2. Hook installation config (target file + event mappings)
+ * 3. Resume command support
+ *
+ * Plugins are merged into the built-in agent registry and hook installer
+ * list at startup. Slugs that collide with built-in agents are skipped.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const PLUGINS_DIR = path.join(os.homedir(), '.termdock', 'agent-plugins');
+const MANIFEST_FILE = 'manifest.json';
+const ICON_FILE = 'icon.svg';
+// ---------------------------------------------------------------------------
+// Manifest schema
+// ---------------------------------------------------------------------------
+export const PLUGIN_MANIFEST_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Known sentinel event kinds — the set of events our state machine accepts
+// ---------------------------------------------------------------------------
+const VALID_EVENT_KINDS = new Set([
+    'session-start',
+    'prompt-submit',
+    'permission-request',
+    'question-asked',
+    'tool-complete',
+    'notification',
+    'stop',
+    'session-end',
+]);
+// ---------------------------------------------------------------------------
+// Slug validation (alphanumeric + hyphens, non-empty)
+// ---------------------------------------------------------------------------
+const SLUG_RE = /^[a-z][a-z0-9-]*$/;
+function isValidSlug(s) {
+    return SLUG_RE.test(s) && s.length <= 40;
+}
+// ---------------------------------------------------------------------------
+// Hex color validation
+// ---------------------------------------------------------------------------
+const HEX_COLOR_RE = /^#[0-9A-Fa-f]{6}$/;
+// ---------------------------------------------------------------------------
+// Path resolution: ~ → home directory
+// ---------------------------------------------------------------------------
+function resolveHome(p) {
+    if (p.startsWith('~')) {
+        return path.join(os.homedir(), p.slice(1));
+    }
+    return p;
+}
+function validateManifest(raw, dir) {
+    const errors = [];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { error: { slug: path.basename(dir), errors: ['manifest.json is not a JSON object'] } };
+    }
+    const m = raw;
+    const version = m.version;
+    if (typeof version !== 'number' || version !== PLUGIN_MANIFEST_VERSION) {
+        errors.push(`version must be ${PLUGIN_MANIFEST_VERSION}`);
+    }
+    const slug = m.slug;
+    if (typeof slug !== 'string' || !isValidSlug(slug)) {
+        errors.push('slug must be a lowercase alphanumeric string with hyphens (max 40 chars)');
+    }
+    const displayName = m.displayName;
+    if (typeof displayName !== 'string' || displayName.trim().length === 0) {
+        errors.push('displayName is required and must be a non-empty string');
+    }
+    const aliases = m.aliases;
+    if (!Array.isArray(aliases) || aliases.length === 0 || !aliases.every((a) => typeof a === 'string' && a.trim().length > 0)) {
+        errors.push('aliases must be a non-empty array of strings');
+    }
+    const accentColor = m.accentColor;
+    if (typeof accentColor !== 'string' || !HEX_COLOR_RE.test(accentColor)) {
+        errors.push('accentColor must be a 6-digit hex color (e.g. "#4385BE")');
+    }
+    // Optional hooks
+    let hooks;
+    if (m.hooks !== undefined) {
+        if (typeof m.hooks !== 'object' || Array.isArray(m.hooks) || m.hooks === null) {
+            errors.push('hooks must be an object if present');
+        }
+        else {
+            const h = m.hooks;
+            const target = h.target;
+            if (typeof target !== 'string' || target.trim().length === 0) {
+                errors.push('hooks.target is required and must be a file path (~-abbreviated ok)');
+            }
+            const events = h.events;
+            if (!Array.isArray(events) || events.length === 0) {
+                errors.push('hooks.events must be a non-empty array');
+            }
+            else {
+                const validEvents = [];
+                for (let i = 0; i < events.length; i++) {
+                    const e = events[i];
+                    if (!e || typeof e !== 'object') {
+                        errors.push(`hooks.events[${i}] is not an object`);
+                        continue;
+                    }
+                    const evt = e;
+                    const hook = evt.hook;
+                    const event = evt.event;
+                    if (typeof hook !== 'string' || hook.trim().length === 0) {
+                        errors.push(`hooks.events[${i}].hook is required`);
+                    }
+                    if (typeof event !== 'string' || !VALID_EVENT_KINDS.has(event)) {
+                        errors.push(`hooks.events[${i}].event must be one of: ${[...VALID_EVENT_KINDS].join(', ')}`);
+                    }
+                    const matcher = evt.matcher;
+                    if (matcher !== undefined && typeof matcher !== 'string') {
+                        errors.push(`hooks.events[${i}].matcher must be a string if provided`);
+                    }
+                    const timeout = evt.timeout;
+                    if (timeout !== undefined && (typeof timeout !== 'number' || timeout <= 0)) {
+                        errors.push(`hooks.events[${i}].timeout must be a positive number if provided`);
+                    }
+                    validEvents.push({
+                        hook: hook,
+                        event: event,
+                        matcher: typeof matcher === 'string' ? matcher : undefined,
+                        timeout: typeof timeout === 'number' ? timeout : undefined,
+                    });
+                }
+                if (validEvents.length > 0) {
+                    hooks = { target: target, events: validEvents };
+                }
+            }
+        }
+    }
+    // Optional resume
+    let resumeConfig;
+    if (m.resume !== undefined) {
+        if (typeof m.resume !== 'object' || Array.isArray(m.resume) || m.resume === null) {
+            errors.push('resume must be an object if present');
+        }
+        else {
+            const r = m.resume;
+            const command = r.command;
+            if (typeof command !== 'string' || !command.includes('{sessionId}')) {
+                errors.push('resume.command must contain the {sessionId} placeholder');
+            }
+            const staleFlags = r.staleFlags;
+            if (staleFlags !== undefined && (!Array.isArray(staleFlags) || !staleFlags.every((f) => typeof f === 'string'))) {
+                errors.push('resume.staleFlags must be an array of strings if provided');
+            }
+            resumeConfig = {
+                command: command,
+                staleFlags: Array.isArray(staleFlags) ? staleFlags : undefined,
+            };
+        }
+    }
+    if (errors.length > 0) {
+        return { error: { slug: typeof slug === 'string' ? slug : path.basename(dir), errors } };
+    }
+    return {
+        manifest: {
+            version: version,
+            slug: slug,
+            displayName: displayName.trim(),
+            aliases: aliases.map((a) => a.trim().toLowerCase()),
+            accentColor: accentColor,
+            hooks,
+            resume: resumeConfig,
+        },
+    };
+}
+/**
+ * Scan ~/.termdock/agent-plugins/ for plugin directories, validate each
+ * manifest, and return the loaded plugins + any validation errors.
+ */
+export function loadPlugins() {
+    const plugins = [];
+    const errors = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true });
+    }
+    catch {
+        return { plugins, errors };
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(PLUGINS_DIR, entry.name);
+        const manifestPath = path.join(dir, MANIFEST_FILE);
+        let raw;
+        try {
+            raw = fs.readFileSync(manifestPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            errors.push({ slug: entry.name, errors: ['manifest.json is not valid JSON'] });
+            continue;
+        }
+        const result = validateManifest(parsed, dir);
+        if ('error' in result) {
+            errors.push(result.error);
+            continue;
+        }
+        const iconPath = path.join(dir, ICON_FILE);
+        plugins.push({
+            manifest: result.manifest,
+            dir,
+            iconPath: fs.existsSync(iconPath) ? iconPath : null,
+        });
+    }
+    return { plugins, errors };
+}
+/**
+ * Save a plugin manifest to disk, creating the plugin directory.
+ */
+export function savePlugin(manifest) {
+    const dir = path.join(PLUGINS_DIR, manifest.slug);
+    fs.mkdirSync(dir, { recursive: true });
+    const manifestPath = path.join(dir, MANIFEST_FILE);
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+    return dir;
+}
+/**
+ * Remove a plugin directory from disk.
+ */
+export function removePlugin(slug) {
+    const dir = path.join(PLUGINS_DIR, slug);
+    if (!fs.existsSync(dir)) {
+        throw new Error(`Plugin "${slug}" not found`);
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+}
+/**
+ * List all plugin slugs (both currently loaded and directories on disk).
+ */
+export function listPluginDirectories() {
+    try {
+        return fs.readdirSync(PLUGINS_DIR, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve a ~-abbreviated path from a plugin's hooks.target to an absolute path.
+ */
+export function resolveHookTarget(hooksTargetPath) {
+    return resolveHome(hooksTargetPath);
+}
+/**
+ * Read an icon SVG from a plugin directory as a string.
+ */
+export function readPluginIcon(slug) {
+    const iconPath = path.join(PLUGINS_DIR, slug, ICON_FILE);
+    try {
+        return fs.readFileSync(iconPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server/agent/registry.js

@@ -0,0 +1,306 @@
+// Registry order matters only for iteration stability; lookup is by alias.
+// flexoki-allow-file — vendor brand accents are deliberately theme-independent.
+const AGENTS = [
+    { slug: 'claude', displayName: 'Claude Code', aliases: ['claude', 'claude-code'], accentColor: '#D97757', icon: 'claude' },
+    { slug: 'codex', displayName: 'Codex', aliases: ['codex', 'codex-cli'], accentColor: '#000000', icon: 'codex' },
+    { slug: 'gemini', displayName: 'Gemini', aliases: ['gemini', 'gemini-cli'], accentColor: '#4285F4', icon: 'gemini' },
+    { slug: 'aider', displayName: 'Aider', aliases: ['aider', 'aider-chat'], accentColor: '#14B8A6', icon: null },
+    { slug: 'amp', displayName: 'Amp', aliases: ['amp'], accentColor: '#F34E3F', icon: 'amp' },
+    { slug: 'opencode', displayName: 'OpenCode', aliases: ['opencode'], accentColor: '#6E56CF', icon: 'opencode' },
+    { slug: 'copilot', displayName: 'Copilot', aliases: ['copilot'], accentColor: '#8957E5', icon: 'copilot' },
+    { slug: 'cursor', displayName: 'Cursor', aliases: ['cursor-agent'], accentColor: '#9AA0A6', icon: 'cursor' },
+    { slug: 'goose', displayName: 'Goose', aliases: ['goose'], accentColor: '#9A8CFF', icon: 'goose' },
+    { slug: 'droid', displayName: 'Droid', aliases: ['droid'], accentColor: '#F59E0B', icon: 'droid' },
+    { slug: 'pi', displayName: 'Pi', aliases: ['pi'], accentColor: '#0EA5E9', icon: null },
+    { slug: 'auggie', displayName: 'Auggie', aliases: ['auggie'], accentColor: '#16A34A', icon: null },
+    { slug: 'hermes', displayName: 'Hermes', aliases: ['hermes'], accentColor: '#8B5CF6', icon: null },
+    { slug: 'vibe', displayName: 'Vibe', aliases: ['vibe', 'vibe-acp'], accentColor: '#FF7000', icon: null },
+    { slug: 'antigravity', displayName: 'Antigravity', aliases: ['agy', 'antigravity'], accentColor: '#2563EB', icon: null },
+    { slug: 'grok', displayName: 'Grok', aliases: ['grok'], accentColor: '#000000', icon: 'grok' },
+    { slug: 'qwen', displayName: 'Qwen Code', aliases: ['qwen', 'qwen-code'], accentColor: '#7C3AED', icon: null },
+];
+const BY_ALIAS = new Map();
+const BY_SLUG = new Map();
+for (const info of AGENTS) {
+    BY_SLUG.set(info.slug, info);
+    for (const alias of info.aliases)
+        BY_ALIAS.set(alias, info);
+}
+export function agentBySlug(slug) {
+    if (!slug)
+        return null;
+    return BY_SLUG.get(slug.trim().toLowerCase()) ?? null;
+}
+export function listAgents() {
+    return AGENTS.slice();
+}
+function matchToken(token) {
+    return BY_ALIAS.get(token) ?? null;
+}
+/** A `KEY=value` shell environment assignment prefix (`FOO=bar cmd`). */
+function isEnvAssignment(token) {
+    const eq = token.indexOf('=');
+    if (eq <= 0)
+        return false;
+    const key = token.slice(0, eq);
+    if (!/^[A-Za-z_]/.test(key))
+        return false;
+    return /^[A-Za-z0-9_]+$/.test(key);
+}
+/**
+ * The final path component with trailing script extension stripped.
+ * `/usr/bin/claude` → `claude`, `cli.js` → `cli`, `claude.cmd` → `claude`.
+ * Splits on both separators so Windows paths resolve the same on Unix.
+ */
+function baseStem(token) {
+    const trimmed = token.replace(/[/\\]+$/, '');
+    const idx = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
+    const name = idx >= 0 ? trimmed.slice(idx + 1) : trimmed;
+    for (const ext of ['.js', '.mjs', '.cjs', '.ts', '.py', '.rb', '.sh', '.exe', '.cmd', '.bat', '.ps1']) {
+        if (name.endsWith(ext))
+            return name.slice(0, -ext.length);
+    }
+    return name;
+}
+/** Whether a launcher basename is an interpreter whose arguments name the real program. */
+function isInterpreter(stem) {
+    return ['node', 'nodejs', 'bun', 'deno', 'npx', 'pnpm', 'yarn',
+        'python', 'python3', 'ruby', 'uv', 'uvx', 'env'].includes(stem.toLowerCase());
+}
+function tokenNamesAgent(token, agent) {
+    return token.split(/[/\\]/).some((seg) => matchToken(baseStem(seg).toLowerCase()) === agent);
+}
+/**
+ * Identify the coding agent a foreground argv is running, or null.
+ * `customRules` maps a command basename to an agent slug (personal wrappers);
+ * applies to the launcher only and loses to a built-in match on the same name.
+ */
+export function detectAgentFromArgv(argv, customRules = {}) {
+    let i = 0;
+    while (i < argv.length && isEnvAssignment(argv[i]))
+        i++;
+    const launcher = argv[i];
+    if (!launcher)
+        return null;
+    const launcherStem = baseStem(launcher);
+    // Native binary (or built-in match wins over custom rules on the same name)
+    const direct = matchToken(launcherStem.toLowerCase());
+    if (direct)
+        return direct;
+    const custom = customRules[launcherStem.toLowerCase()];
+    if (custom) {
+        const agent = agentBySlug(custom);
+        if (agent)
+            return agent;
+    }
+    // Interpreter wrapper: scan the script path / package args it runs
+    if (isInterpreter(launcherStem)) {
+        for (let j = i + 1; j < argv.length; j++) {
+            const arg = argv[j];
+            if (arg.startsWith('-'))
+                continue;
+            for (const seg of arg.split(/[/\\]/)) {
+                const hit = matchToken(baseStem(seg).toLowerCase());
+                if (hit)
+                    return hit;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Shell-split a raw command line (as captured from ps args) into argv, then
+ * detect. Naive tokenization: whitespace split, quotes trimmed — enough for
+ * the dominant shapes (`claude --model opus`, `node /path/cli.js --flag`).
+ */
+export function detectAgentFromCommand(command, customRules = {}) {
+    const argv = command
+        .split(/\s+/)
+        .map((t) => t.replace(/^["']+|["']+$/g, ''))
+        .filter((t) => t.length > 0);
+    return detectAgentFromArgv(argv, customRules);
+}
+// ---------------------------------------------------------------------------
+// Resume: rebuild the shell command that resumes a previous agent session by
+// its native session id, carrying the user's original launch flags.
+// ---------------------------------------------------------------------------
+/** Per-agent resume command templates; null = no known resume flag. */
+function resumeCommandFor(agent, sessionId, flags) {
+    const f = flags.length > 0 ? ' ' + flags.join(' ') : '';
+    switch (agent.slug) {
+        case 'claude': return `claude${f} --resume ${sessionId}`;
+        // Codex resumes via a subcommand; interactive options follow the positional id
+        case 'codex': return `codex resume ${sessionId}${f}`;
+        case 'gemini': return `gemini${f} --resume ${sessionId}`;
+        case 'opencode': return `opencode${f} --session ${sessionId}`;
+        case 'amp': return `amp threads continue ${sessionId}${f}`;
+        case 'cursor': return `cursor-agent${f} --resume ${sessionId}`;
+        case 'copilot': return `copilot${f} --resume ${sessionId}`;
+        case 'grok': return `grok${f} --resume ${sessionId}`;
+        default: return null;
+    }
+}
+/** Session-targeting flags whose old value must not survive onto a resume. */
+const STALE_SESSION_FLAGS = {
+    claude: ['--resume', '-r', '--continue', '-c', '--session-id', '--from-pr'],
+    gemini: ['--resume', '-r'],
+    cursor: ['--resume', '-r'],
+    copilot: ['--resume', '-r', '--continue', '-c'],
+    opencode: ['--session', '-s', '--continue', '-c'],
+    codex: ['--last'],
+    grok: ['--resume', '-r', '--load', '--continue', '-c', '--session-id', '-s',
+        '--fork-session', '--worktree', '-w', '--worktree-ref', '--ref'],
+};
+/**
+ * The launch-flag tail of argv worth replaying on a resume command, or null
+ * to resume bare. Deliberately conservative: anything ambiguous falls back to
+ * no flags rather than a corrupted command line.
+ * - The tail is everything after the token that names this agent; leading
+ *   `VAR=value` env assignments are skipped first. No naming token → null.
+ * - Stale session-targeting flags are stripped (the new id must win).
+ * - Every surviving token must be shell-safe, the first must be a `-` flag,
+ *   and no two bare words may run consecutively (a bare word is only valid as
+ *   the value directly behind a flag — anything else is a positional prompt
+ *   that must not re-submit itself into the resumed session).
+ */
+function replayFlags(agent, argv) {
+    let start = 0;
+    while (start < argv.length && isEnvAssignment(argv[start]))
+        start++;
+    let named = -1;
+    for (let j = start; j < argv.length; j++) {
+        if (tokenNamesAgent(argv[j], agent)) {
+            named = j;
+            break;
+        }
+    }
+    if (named < 0)
+        return null;
+    const tail = argv.slice(named + 1);
+    // A relaunched `codex resume <old-id>`: drop the subcommand and its id
+    if (agent.slug === 'codex' && tail[0] === 'resume') {
+        tail.shift();
+        if (tail.length > 0 && !tail[0].startsWith('-'))
+            tail.shift();
+    }
+    const stale = STALE_SESSION_FLAGS[agent.slug] ?? [];
+    for (let j = 0; j < tail.length;) {
+        const t = tail[j];
+        const isStale = stale.includes(t)
+            || stale.some((f) => f.length > 2 && t.startsWith(`${f}=`));
+        if (isStale) {
+            tail.splice(j, 1);
+            if (j < tail.length && !tail[j].startsWith('-'))
+                tail.splice(j, 1);
+        }
+        else {
+            j++;
+        }
+    }
+    // Safety gate: plain tokens only, flag-shaped tail
+    const safe = (t) => t.length > 0 && /^[A-Za-z0-9_=./,:@+~-]+$/.test(t);
+    if (!tail.every(safe))
+        return null;
+    let prevWasFlag = false;
+    for (const t of tail) {
+        const isFlag = t.startsWith('-');
+        if (!isFlag && !prevWasFlag)
+            return null;
+        prevWasFlag = isFlag;
+    }
+    return tail;
+}
+/**
+ * The shell command resuming a session, or null when the agent has no known
+ * resume flag or the id/flags aren't shell-safe. Ids come from the agent's own
+ * hook events but still land on a shell command line — refuse anything that
+ * isn't a plain token.
+ */
+export function buildResumeCommand(agent, sessionId, launchArgv) {
+    if (!sessionId || !/^[A-Za-z0-9._-]+$/.test(sessionId))
+        return null;
+    // Plugin-defined resume: use the command template
+    if (agent.isPlugin) {
+        const pluginResume = getPluginResumeConfig(agent.slug);
+        if (pluginResume) {
+            const safe = (t) => /^[A-Za-z0-9._-]+$/.test(t);
+            if (!safe(sessionId))
+                return null;
+            const cmd = pluginResume.command.replace('{sessionId}', sessionId);
+            // Shell-safety: refuse anything non-alphanumeric
+            if (!/^[A-Za-z0-9_[\]{},./:;@+=~'"!?#&()<>*|$ -]+$/.test(cmd))
+                return null;
+            return cmd;
+        }
+        return null;
+    }
+    const flags = launchArgv ? replayFlags(agent, launchArgv) ?? [] : [];
+    return resumeCommandFor(agent, sessionId, flags);
+}
+// ---------------------------------------------------------------------------
+// Plugin agent integration
+// ---------------------------------------------------------------------------
+/** Plugin-defined resume configs, keyed by slug. */
+const pluginResumeConfigs = new Map();
+/**
+ * Register plugin agents into the lookup maps. Plugins whose slug or aliases
+ * collide with built-in agents are skipped. Call `clearPluginAgents()` first
+ * when reloading.
+ */
+export function registerPluginAgents(plugins) {
+    let registered = 0;
+    const skipped = [];
+    for (const p of plugins) {
+        const { manifest } = p;
+        if (BY_SLUG.has(manifest.slug)) {
+            skipped.push(`${manifest.slug} (slug conflicts with built-in)`);
+            continue;
+        }
+        let aliasConflict = false;
+        for (const alias of manifest.aliases) {
+            if (BY_ALIAS.has(alias)) {
+                skipped.push(`${manifest.slug} (alias "${alias}" conflicts with built-in)`);
+                aliasConflict = true;
+                break;
+            }
+        }
+        if (aliasConflict)
+            continue;
+        const info = {
+            slug: manifest.slug,
+            displayName: manifest.displayName,
+            aliases: manifest.aliases,
+            accentColor: manifest.accentColor,
+            icon: manifest.slug, // plugins use slug as icon key; frontend checks /agent-plugin-icon/<slug>
+            isPlugin: true,
+        };
+        BY_SLUG.set(info.slug, info);
+        for (const alias of info.aliases)
+            BY_ALIAS.set(alias, info);
+        if (manifest.resume) {
+            pluginResumeConfigs.set(manifest.slug, {
+                command: manifest.resume.command,
+                staleFlags: manifest.resume.staleFlags ?? [],
+            });
+        }
+        registered++;
+    }
+    return { registered, skipped };
+}
+export function clearPluginAgents() {
+    for (const [slug, info] of BY_SLUG) {
+        if (info.isPlugin)
+            BY_SLUG.delete(slug);
+    }
+    for (const [alias, info] of BY_ALIAS) {
+        if (info.isPlugin)
+            BY_ALIAS.delete(alias);
+    }
+    pluginResumeConfigs.clear();
+}
+export function getPluginResumeConfig(slug) {
+    return pluginResumeConfigs.get(slug);
+}
+export function isPluginAgent(slug) {
+    return BY_SLUG.get(slug)?.isPlugin === true;
+}