atom-agent 1.2.0 → 1.4.0

package/dist/extension-commands.js

@@ -0,0 +1,196 @@
+// Extension slash commands (ticket 04): the runtime store behind
+// ExtensionAPI.registerCommand. Dependency-free (no imports) like
+// tools/custom.ts and tools/intercept.ts, so the extension host and the App
+// slash dispatch share it with no cycle: extensions register here, the App
+// lists/parses/runs here, nobody imports the other.
+//
+// A command is a real slash command (`/name args...`): it appears in the
+// command palette and the "/" menu, takes typed free-text arguments, and
+// runs extension code OUTSIDE the model turn loop with a generation-bound
+// context (prompt the user, read a session snapshot, post messages).
+//
+// Semantics:
+// - Names are bare in the definition ("deploy") and slash-prefixed at the
+//   seam ("/deploy"). Lowercase [a-z0-9_-] only, mirroring builtin style so
+//   menu/palette matching stays exact and case-free.
+// - Collision decision: builtins always win. The host rejects a colliding
+//   name at activation (loud error, nothing commits) and App dispatch
+//   routes builtins first as backstop — a builtin is never shadowed, and
+//   there is no renamed form to discover. Duplicate extension names throw
+//   the same way (first registration wins, deterministically by load order).
+// - Handlers never touch model history: say() stages messages and the
+//   runner commits them only on success. A throwing handler drops the
+//   stage and surfaces a clean `Error:` string — the session is untouched.
+// - The context is generation-bound: every ctx call runs checkStale first,
+//   so use after a session replacement throws loudly instead of acting on
+//   the wrong session (same rule as the event API).
+const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const store = new Map();
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e ?? "unknown error");
+}
+/**
+ * Validate a registration shape. Throws Error on any problem (bad name,
+ * empty description, non-function handler). Duplicate and builtin-
+ * collision checks live with the callers that own those names (the store
+ * owns extension names; the host owns the builtin set).
+ */
+export function validateExtensionCommandDef(def) {
+    if (!isRecord(def))
+        throw new Error("extension command definition must be an object");
+    if (typeof def.name !== "string" || !NAME_RE.test(def.name)) {
+        throw new Error(`extension command has an invalid name ${JSON.stringify(def.name)} (want a bare 1-64 char a-z0-9_- name, no leading slash)`);
+    }
+    if (typeof def.description !== "string" || def.description.trim().length === 0) {
+        throw new Error(`extension command "/${def.name}" needs a non-empty description`);
+    }
+    if (typeof def.handler !== "function") {
+        throw new Error(`extension command "/${def.name}" needs a handler function`);
+    }
+}
+/** Register a validated command. Throws on duplicate names. Returns an unregister function. */
+export function registerExtensionCommand(def, owner = "(unknown)") {
+    validateExtensionCommandDef(def);
+    if (store.has(def.name)) {
+        throw new Error(`extension command "/${def.name}" is already registered`);
+    }
+    const rec = {
+        name: def.name,
+        description: def.description,
+        handler: def.handler,
+        owner,
+    };
+    store.set(def.name, rec);
+    let live = true;
+    return () => {
+        if (!live)
+            return;
+        live = false;
+        if (store.get(def.name) === rec)
+            store.delete(def.name);
+    };
+}
+export function unregisterExtensionCommand(name) {
+    return store.delete(name);
+}
+export function getExtensionCommand(name) {
+    return store.get(name);
+}
+/** Live commands in registration order (deterministic menu/palette order). */
+export function listExtensionCommands() {
+    return [...store.values()];
+}
+/** Test seam: drop every extension command. */
+export function clearExtensionCommands() {
+    store.clear();
+}
+// Split "/name args..." into its bare name and raw args. Returns null for
+// anything that is not a single-line slash invocation (plain text, a bare
+// "/", multiline, namespaced skill forms like "/skill:dep" — the name must
+// be followed by whitespace or end, so skill routing is never disturbed).
+export function parseExtensionCommandInput(text) {
+    if (!text.startsWith("/") || text.length < 2)
+        return null;
+    if (/[\r\n]/.test(text))
+        return null;
+    const match = /^\/([A-Za-z0-9_-]+)(?:[ \t]+([\s\S]*))?$/.exec(text);
+    if (!match)
+        return null;
+    return { name: match[1], args: (match[2] ?? "").trim() };
+}
+// Whitespace tokenizer for ctx.argv: double/single quotes group words, the
+// quotes are stripped, no escape processing (documented, not shell).
+export function splitCommandArgs(args) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    let has = false;
+    for (let i = 0; i < args.length; i++) {
+        const ch = args[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                cur += ch;
+            }
+            has = true;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            has = true;
+            continue;
+        }
+        if (ch === " " || ch === "\t") {
+            if (has) {
+                out.push(cur);
+                cur = "";
+                has = false;
+            }
+            continue;
+        }
+        cur += ch;
+        has = true;
+    }
+    if (has)
+        out.push(cur);
+    return out;
+}
+// Run a registered command outside the model turn loop. Never throws for
+// handler failures: unknown names and throwing handlers return a clean
+// `Error:` result. say() output stages in a buffer and commits through
+// deps.say only on success, so a throwing handler leaves the session
+// untouched. Every context call runs checkStale first — stale use throws
+// into the same clean-error path instead of acting on the wrong session.
+export async function runExtensionCommand(name, rawArgs, deps) {
+    const rec = store.get(name);
+    if (!rec) {
+        return { ok: false, error: `Error: unknown extension command "/${name}" (not registered)` };
+    }
+    const stale = deps.checkStale ?? (() => undefined);
+    const staged = [];
+    const ctx = {
+        name,
+        args: rawArgs,
+        argv: splitCommandArgs(rawArgs),
+        cwd: deps.cwd ?? process.cwd(),
+        askUser: async (question, options, allowCustom) => {
+            stale();
+            return deps.askUser(question, options, allowCustom);
+        },
+        getSession: () => {
+            stale();
+            return deps.getSession();
+        },
+        say: (message) => {
+            stale();
+            if (typeof message !== "string") {
+                throw new Error(`extension command "/${name}" say() needs a string`);
+            }
+            if (message.length === 0)
+                return;
+            staged.push(message);
+        },
+    };
+    let returned;
+    try {
+        returned = await rec.handler(ctx);
+    }
+    catch (e) {
+        return { ok: false, error: `Error: extension command "/${name}" failed: ${errorText(e)}` };
+    }
+    if (typeof returned === "string" && returned.length > 0)
+        staged.push(returned);
+    try {
+        for (const message of staged)
+            deps.say(message);
+    }
+    catch (e) {
+        return { ok: false, error: `Error: extension command "/${name}" failed: ${errorText(e)}` };
+    }
+    return { ok: true, posted: staged.length };
+}

package/dist/extension-ui.js

@@ -0,0 +1,153 @@
+// Extension UI surface (ticket 10): the dependency-free render model behind
+// ExtensionAPI.setStatusSegment/setWidget/notify/promptUser. No imports, no
+// React — like extension-commands.ts and tools/intercept.ts — so the host,
+// the App, and pure unit tests share it with no cycle: the host validates
+// and stages here, the App renders from here, nobody imports the other.
+//
+// Shapes:
+// - Status: one text slot per extension (upsert by owner name). The bar
+//   budget lives with the render (status-bar.tsx states the fixed-width
+//   rule); this module only validates shape so a bad segment fails
+//   activation loudly instead of corrupting the bar.
+// - Widget: titled text blocks keyed by owner + id (default "main"),
+//   rendered by the App in the configured placement. "panel" is the only
+//   placement in v1 (the bordered panel above the input zone, beside the
+//   todo panel) — unknown placements throw fail-closed so a typo surfaces
+//   at activation instead of rendering nowhere.
+// - Notices: transient fire-and-forget strings the App drains into the
+//   transcript (one `(owner) message` info line each). Sync and bounded
+//   by flow — notify() never blocks, headless or not; the host caps the
+//   staged queue drop-oldest (EXT_NOTICE_CAP in extensions.ts).
+// - Dialogs: validated { question, options, allowCustom } specs mirroring
+//   the QuestionBox the App fulfills them with (same option caps the modal
+//   already assumes). The pending-promise mechanics live in extensions.ts
+//   (runtime-local, generation-bound); this module only validates shape.
+export const EXT_STATUS_SEGMENT_MAX = 24;
+export const EXT_STATUS_TOTAL_MAX = 40;
+export const EXT_WIDGET_TITLE_MAX = 48;
+export const EXT_WIDGET_TEXT_MAX = 500;
+export const EXT_NOTIFY_MAX = 200;
+export const EXT_DIALOG_QUESTION_MAX = 200;
+export const EXT_DIALOG_OPTIONS_MAX = 8;
+export const EXT_DIALOG_OPTION_MAX = 80;
+// v1 widget placements. The App renders "panel" above the input zone;
+// anything else is a loud validation error (never a silent nowhere).
+export const EXT_WIDGET_PLACEMENTS = ["panel"];
+const WIDGET_ID_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorFor(owner, what) {
+    return `extension "${owner}" ${what}`;
+}
+/** Validate a status segment. Throws Error on any problem. Returns the trimmed text. */
+export function validateStatusSegment(owner, text) {
+    if (typeof text !== "string" || text.trim().length === 0) {
+        throw new Error(errorFor(owner, "status segment needs a non-empty string"));
+    }
+    if (text.length > EXT_STATUS_SEGMENT_MAX * 4) {
+        throw new Error(errorFor(owner, `status segment is too long (${text.length} chars, max ${EXT_STATUS_SEGMENT_MAX * 4})`));
+    }
+    return text;
+}
+/** Validate a widget definition. Throws Error on any problem. */
+export function validateWidgetDef(owner, def) {
+    if (!isRecord(def))
+        throw new Error(errorFor(owner, "widget definition must be an object"));
+    const id = def.id === undefined ? "main" : def.id;
+    if (typeof id !== "string" || !WIDGET_ID_RE.test(id)) {
+        throw new Error(errorFor(owner, `widget has an invalid id ${JSON.stringify(def.id)} (want 1-32 char a-z0-9_-, default "main")`));
+    }
+    if (!EXT_WIDGET_PLACEMENTS.includes(def.placement)) {
+        throw new Error(errorFor(owner, `widget "${id}" has an unknown placement ${JSON.stringify(def.placement)} (want one of: ${EXT_WIDGET_PLACEMENTS.join(", ")})`));
+    }
+    if (typeof def.title !== "string" || def.title.trim().length === 0) {
+        throw new Error(errorFor(owner, `widget "${id}" needs a non-empty title`));
+    }
+    if (def.title.length > EXT_WIDGET_TITLE_MAX) {
+        throw new Error(errorFor(owner, `widget "${id}" title is too long (${def.title.length} chars, max ${EXT_WIDGET_TITLE_MAX})`));
+    }
+    if (typeof def.text !== "string" || def.text.trim().length === 0) {
+        throw new Error(errorFor(owner, `widget "${id}" needs a non-empty text body`));
+    }
+    if (def.text.length > EXT_WIDGET_TEXT_MAX) {
+        throw new Error(errorFor(owner, `widget "${id}" text is too long (${def.text.length} chars, max ${EXT_WIDGET_TEXT_MAX})`));
+    }
+    return { id, placement: def.placement, title: def.title, text: def.text };
+}
+/** Validate a notification message. Throws Error on any problem. Returns the message. */
+export function validateNotifyMessage(owner, message) {
+    if (typeof message !== "string" || message.trim().length === 0) {
+        throw new Error(errorFor(owner, "notification needs a non-empty string"));
+    }
+    if (message.length > EXT_NOTIFY_MAX * 4) {
+        throw new Error(errorFor(owner, `notification is too long (${message.length} chars, max ${EXT_NOTIFY_MAX * 4})`));
+    }
+    return message;
+}
+/** Validate a dialog spec. Throws Error on any problem. */
+export function validateDialogDef(owner, def) {
+    if (!isRecord(def))
+        throw new Error(errorFor(owner, "dialog definition must be an object"));
+    if (typeof def.question !== "string" || def.question.trim().length === 0) {
+        throw new Error(errorFor(owner, "dialog needs a non-empty question"));
+    }
+    if (def.question.length > EXT_DIALOG_QUESTION_MAX) {
+        throw new Error(errorFor(owner, `dialog question is too long (${def.question.length} chars, max ${EXT_DIALOG_QUESTION_MAX})`));
+    }
+    const options = def.options === undefined ? [] : def.options;
+    if (!Array.isArray(options)) {
+        throw new Error(errorFor(owner, "dialog options must be an array of strings"));
+    }
+    if (options.length > EXT_DIALOG_OPTIONS_MAX) {
+        throw new Error(errorFor(owner, `dialog has too many options (${options.length}, max ${EXT_DIALOG_OPTIONS_MAX})`));
+    }
+    for (const o of options) {
+        if (typeof o !== "string" || o.trim().length === 0) {
+            throw new Error(errorFor(owner, "dialog options must be non-empty strings"));
+        }
+        if (o.length > EXT_DIALOG_OPTION_MAX) {
+            throw new Error(errorFor(owner, `dialog option is too long (${o.length} chars, max ${EXT_DIALOG_OPTION_MAX})`));
+        }
+    }
+    if (!options.length && def.allowCustom !== true) {
+        throw new Error(errorFor(owner, "dialog needs options or allowCustom: true (nothing to answer with)"));
+    }
+    return { question: def.question, options: [...options], allowCustom: def.allowCustom === true };
+}
+// Truncate text to n chars max for tight widths (`…/tail` keeps the
+// meaningful end, the status-bar convention). n < 4 yields "" (the caller
+// drops the segment instead of rendering a stub).
+export function truncateSegment(s, n) {
+    if (s.length <= n)
+        return s;
+    if (n < 4)
+        return "";
+    return `…/${s.slice(-(n - 3))}`;
+}
+// Pure status-bar text for extension segments (unit-tested; the bar itself
+// only decides fit-or-drop against the terminal width, never the content).
+// Each segment truncates to EXT_STATUS_SEGMENT_MAX, joined with " · "; the
+// total caps at EXT_STATUS_TOTAL_MAX with trailing segments dropped whole
+// (never a mid-segment cut past the per-segment truncation). Null when
+// nothing renderable remains.
+export function formatExtensionStatusText(segments) {
+    const parts = [];
+    let len = 0;
+    for (const raw of segments) {
+        if (typeof raw !== "string")
+            continue;
+        const text = raw.trim();
+        if (!text)
+            continue;
+        const seg = truncateSegment(text, EXT_STATUS_SEGMENT_MAX);
+        if (!seg)
+            continue;
+        const add = (parts.length > 0 ? 3 : 0) + seg.length;
+        if (len + add > EXT_STATUS_TOTAL_MAX)
+            continue;
+        parts.push(seg);
+        len += add;
+    }
+    return parts.length > 0 ? parts.join(" · ") : null;
+}