@xingular/harness 1.3.1-unstable.2 → 1.3.1-unstable.3

package/dist/sdk/terminal/tui/pages/contextPage.d.ts

@@ -0,0 +1,54 @@
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { type TabInfo } from "../chrome.js";
+import type { TerminalPage } from "../page.js";
+export type ContextTab = 'request' | 'growth';
+export type ContextGrouping = 'owner' | 'kind';
+interface ContextPageOptions {
+    theme(): Theme;
+    call(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    changed(): void;
+    initialTab?: ContextTab;
+    /** Opens the variant editor for the row the person wants to shrink. */
+    openVariant?(): void;
+    /** Runs the session's compaction, after the page confirms what it would free. */
+    compact?(): Promise<void>;
+    confirm?(title: string, message: string): Promise<boolean>;
+}
+export declare class ContextPage implements TerminalPage {
+    private readonly options;
+    presentation: "fullscreen";
+    focused: boolean;
+    private tab;
+    private grouping;
+    private data;
+    private detail;
+    private selectedId;
+    private folded;
+    private offset;
+    private detailOffset;
+    private maxOffset;
+    private scrollRows;
+    private busy;
+    private reloadPending;
+    private error;
+    private disposed;
+    constructor(options: ContextPageOptions);
+    tabs(): readonly TabInfo[];
+    activeTab(): string;
+    selectTab(id: string): void;
+    hint(): string;
+    activate(): void;
+    dispose(): void;
+    private load;
+    handleInput(data: string): boolean;
+    private move;
+    private compact;
+    /** The rows in the order the page draws them, with the heading each one introduces. */
+    private entries;
+    render(width: number, rows: number): string[];
+    private requestBody;
+    private rowLine;
+    private growthBody;
+    private detailBody;
+}
+export {};

package/dist/sdk/terminal/tui/pages/contextPage.js

@@ -0,0 +1,393 @@
+import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { CHROME_PAD, headerRow, neutralRule, padded, selectedRow, selectionMuted, selectionText } from "../chrome.js";
+const BARS = '▁▂▃▄▅▆▇█';
+const OWNER_TITLES = {
+    foundation: 'Foundation · harness',
+    variant: 'Variant',
+    application: 'Your application',
+    conversation: 'Conversation',
+    reserved: 'Reserved and free'
+};
+const OWNER_ORDER = ['foundation', 'variant', 'application', 'conversation', 'reserved'];
+const KIND_ORDER = ['System prompt', 'Tools', 'Memory', 'Skills', 'Messages', 'Reserved'];
+function kindOf(row) {
+    if (row.group === 'reserved')
+        return 'Reserved';
+    if (row.id === 'messages' || row.id === 'context-update' || row.id === 'references' || row.id === 'required-skills' || row.id === 'wiki' || row.id === 'session-state')
+        return 'Messages';
+    if (row.id === 'memory')
+        return 'Memory';
+    if (row.id === 'skills')
+        return 'Skills';
+    if (row.id === 'tools' || row.id === 'tools-harness' || row.id === 'tools-application' || row.id === 'tool-guidance')
+        return 'Tools';
+    return 'System prompt';
+}
+function count(value) {
+    if (!Number.isFinite(value) || value <= 0)
+        return '0';
+    if (value >= 1_000_000)
+        return `${(value / 1_000_000).toFixed(value % 1_000_000 === 0 ? 0 : 1)}M`;
+    if (value >= 1_000)
+        return `${(value / 1_000).toFixed(1)}K`;
+    return String(Math.round(value));
+}
+function percent(value) {
+    return value === null ? '?' : `${value.toFixed(1)}%`;
+}
+function tone(share) {
+    if (share === null)
+        return 'dim';
+    if (share >= 90)
+        return 'error';
+    if (share >= 70)
+        return 'warning';
+    return 'success';
+}
+/** A context bar: filled as the window is used, with room left in the track. */
+function usageBar(share, width, theme) {
+    const room = Math.max(1, width - 2);
+    const track = '░'.repeat(room);
+    if (share === null)
+        return `[${theme.fg('dim', track)}]`;
+    const filled = Math.max(0, Math.min(room, Math.round((Math.max(0, Math.min(100, share)) / 100) * room)));
+    return `[${theme.fg(tone(share), '█'.repeat(filled))}${theme.fg('dim', '░'.repeat(room - filled))}]`;
+}
+/** A label on the left and a quiet value at the right edge of the same row. */
+function spread(left, right, width) {
+    if (!right)
+        return truncateToWidth(left, width, '');
+    const room = Math.max(0, width - visibleWidth(left) - 2);
+    const value = truncateToWidth(right, room, '');
+    return left + ' '.repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(value))) + value;
+}
+export class ContextPage {
+    options;
+    presentation = 'fullscreen';
+    focused = false;
+    tab;
+    grouping = 'owner';
+    data = null;
+    detail = null;
+    selectedId = null;
+    folded = new Set();
+    offset = 0;
+    detailOffset = 0;
+    maxOffset = 0;
+    scrollRows = 1;
+    busy = false;
+    reloadPending = false;
+    error = null;
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+        this.tab = options.initialTab ?? 'request';
+    }
+    tabs() {
+        return [{ id: 'request', title: 'Request' }, { id: 'growth', title: 'Growth' }];
+    }
+    activeTab() {
+        return this.tab;
+    }
+    selectTab(id) {
+        if (id !== 'request' && id !== 'growth')
+            return;
+        if (id === this.tab)
+            return;
+        this.tab = id;
+        this.offset = 0;
+        this.detail = null;
+        this.options.changed();
+        if (!this.data)
+            void this.load();
+    }
+    hint() {
+        if (this.detail)
+            return '↑/↓ scroll · esc close · q close page';
+        return this.tab === 'request'
+            ? '↑/↓ move · space fold · enter text · g group · c compact · v variant · r refresh · q close'
+            : '↑/↓ scroll · r refresh · q close';
+    }
+    activate() {
+        if (!this.data)
+            void this.load();
+    }
+    dispose() {
+        this.disposed = true;
+    }
+    async load(section) {
+        if (this.disposed)
+            return;
+        if (this.busy) {
+            this.reloadPending = true;
+            return;
+        }
+        this.busy = true;
+        this.error = null;
+        this.options.changed();
+        try {
+            const answer = await this.options.call('terminal.context', section ? { section } : {});
+            if (this.disposed)
+                return;
+            this.data = answer.attribution ?? null;
+            if (section) {
+                if (answer.text)
+                    this.detail = answer.text;
+                else
+                    this.error = 'That row carries no text: it is measured, not written.';
+                this.detailOffset = 0;
+            }
+        }
+        catch (cause) {
+            this.error = cause instanceof Error ? cause.message : 'The context could not be read.';
+        }
+        finally {
+            this.busy = false;
+            this.options.changed();
+            if (this.reloadPending) {
+                this.reloadPending = false;
+                void this.load();
+            }
+        }
+    }
+    handleInput(data) {
+        if (this.detail) {
+            const page = Math.max(1, this.scrollRows - 2);
+            if (matchesKey(data, 'up'))
+                this.detailOffset = Math.max(0, this.detailOffset - 1);
+            else if (matchesKey(data, 'down'))
+                this.detailOffset += 1;
+            else if (matchesKey(data, 'pageUp'))
+                this.detailOffset = Math.max(0, this.detailOffset - page);
+            else if (matchesKey(data, 'pageDown'))
+                this.detailOffset += page;
+            else if (matchesKey(data, 'escape') || data === 'q') {
+                this.detail = null;
+                this.options.changed();
+            }
+            else
+                return false;
+            this.options.changed();
+            return true;
+        }
+        if (matchesKey(data, 'tab') || matchesKey(data, 'shift+tab')) {
+            const tabs = ['request', 'growth'];
+            const direction = matchesKey(data, 'shift+tab') ? -1 : 1;
+            this.selectTab(tabs[(tabs.indexOf(this.tab) + direction + tabs.length) % tabs.length]);
+            return true;
+        }
+        const entries = this.entries();
+        const current = Math.max(0, entries.findIndex((entry) => entry.row.id === this.selectedId));
+        if (matchesKey(data, 'up'))
+            this.move(entries, current - 1);
+        else if (matchesKey(data, 'down'))
+            this.move(entries, current + 1);
+        else if (matchesKey(data, 'home'))
+            this.offset = 0;
+        else if (matchesKey(data, 'end'))
+            this.offset = this.maxOffset;
+        else if (data === ' ' && entries[current]) {
+            const row = entries[current].row;
+            if (this.folded.has(row.group))
+                this.folded.delete(row.group);
+            else
+                this.folded.add(row.group);
+        }
+        else if (matchesKey(data, 'enter') && entries[current]) {
+            void this.load(entries[current].row.id);
+            return true;
+        }
+        else if (data === 'g') {
+            this.grouping = this.grouping === 'owner' ? 'kind' : 'owner';
+            this.folded.clear();
+            this.offset = 0;
+        }
+        else if (data === 'r') {
+            void this.load();
+            return true;
+        }
+        else if (data === 'c') {
+            void this.compact();
+            return true;
+        }
+        else if (data === 'v') {
+            this.options.openVariant?.();
+            return true;
+        }
+        else
+            return false;
+        this.options.changed();
+        return true;
+    }
+    move(entries, index) {
+        if (!entries.length)
+            return;
+        const next = entries[Math.max(0, Math.min(entries.length - 1, index))];
+        if (next)
+            this.selectedId = next.row.id;
+    }
+    async compact() {
+        if (!this.options.compact)
+            return;
+        const free = this.data?.free === null || this.data?.free === undefined ? null : this.data.free;
+        const question = free === null
+            ? 'Pi will summarize this conversation and start the next request from the summary.'
+            : `Pi will summarize this conversation. About ${count(free)} tokens are free before it does.`;
+        if (this.options.confirm && !(await this.options.confirm('Compact the conversation now?', question)))
+            return;
+        try {
+            await this.options.compact();
+            await this.load();
+        }
+        catch (cause) {
+            this.error = cause instanceof Error ? cause.message : 'Compaction failed.';
+            this.options.changed();
+        }
+    }
+    /** The rows in the order the page draws them, with the heading each one introduces. */
+    entries() {
+        const rows = this.data?.rows ?? [];
+        if (this.grouping === 'owner') {
+            const ordered = [...rows].sort((left, right) => OWNER_ORDER.indexOf(left.group) - OWNER_ORDER.indexOf(right.group));
+            const out = [];
+            for (const row of ordered) {
+                const previous = out.at(-1)?.row.group;
+                out.push({ row, heading: previous === row.group ? null : (OWNER_TITLES[row.group] ?? row.group), folded: this.folded.has(row.group) });
+            }
+            return out;
+        }
+        const ordered = [...rows].sort((left, right) => KIND_ORDER.indexOf(kindOf(left)) - KIND_ORDER.indexOf(kindOf(right)));
+        const out = [];
+        let last = null;
+        for (const row of ordered) {
+            const kind = kindOf(row);
+            const folded = this.folded.has(kind);
+            out.push({ row, heading: last === kind ? null : kind, folded });
+            last = kind;
+        }
+        return out;
+    }
+    render(width, rows) {
+        if (width < 1 || rows < 1)
+            return [];
+        const theme = this.options.theme();
+        const data = this.data;
+        const meta = data ? `${count(data.used)} / ${data.window === null ? '?' : count(data.window)} · ${percent(data.share)}` : undefined;
+        const header = [headerRow('Context', meta, width, theme), neutralRule(width, theme)];
+        const body = this.detail ? this.detailBody(width, theme) : this.tab === 'growth' ? this.growthBody(width, theme) : this.requestBody(width, theme);
+        const list = this.detail ? body : body;
+        const room = Math.max(0, rows - header.length - 2);
+        this.scrollRows = Math.max(1, room);
+        const offset = this.detail ? Math.min(this.detailOffset, Math.max(0, list.length - room)) : Math.min(this.offset, Math.max(0, list.length - room));
+        this.maxOffset = Math.max(0, list.length - room);
+        if (this.detail)
+            this.detailOffset = offset;
+        else
+            this.offset = offset;
+        const footer = [neutralRule(width, theme), padded(theme.fg('dim', this.hint()), width)];
+        return [...header, ...list.slice(offset, offset + room), ...footer].map((line) => truncateToWidth(line, width, ''));
+    }
+    requestBody(width, theme) {
+        const data = this.data;
+        if (!data) {
+            return [padded(theme.fg(this.error ? 'error' : 'dim', this.error ?? (this.busy ? 'Reading the recorded context…' : 'No reply yet: the next request records what it is made of.')), width)];
+        }
+        const inner = Math.max(8, width - CHROME_PAD * 2);
+        const body = [];
+        body.push(padded(spread(theme.fg('text', `${count(data.used)} of ${data.window === null ? 'an unknown window' : count(data.window)}`), theme.fg(tone(data.share), `${percent(data.share)} used · ${data.source}`), inner), width));
+        body.push(padded(usageBar(data.share, inner, theme), width));
+        body.push('');
+        for (const entry of this.entries()) {
+            if (entry.heading) {
+                const total = data.rows.filter((row) => (this.grouping === 'owner' ? OWNER_TITLES[row.group] === entry.heading : kindOf(row) === entry.heading)).reduce((sum, row) => sum + row.tokens, 0);
+                body.push(padded(theme.bold(theme.fg('accent', entry.heading)) + theme.fg('dim', `  ${count(total)}`), width));
+            }
+            if (entry.folded)
+                continue;
+            body.push(this.rowLine(entry.row, inner, width, theme));
+        }
+        body.push('');
+        body.push(padded(theme.fg('dim', `free ${data.free === null ? '?' : count(data.free)}${data.compaction ? ` · reserve ${count(data.compaction.reserveTokens)}` : ''}`), width));
+        if (data.onDemand.length) {
+            body.push('');
+            body.push(padded(theme.fg('accent', 'On demand') + theme.fg('dim', '  not in this request'), width));
+            for (const item of data.onDemand) {
+                const cost = item.tokensEach === null ? (item.note ?? '') : `about ${count(item.tokensEach)} each · ${item.note ?? ''}`;
+                body.push(padded(`  ${theme.fg('text', item.title)}  ${theme.fg('dim', `${item.items} available · ${cost}`)}`, width));
+            }
+        }
+        if (data.note) {
+            body.push('');
+            body.push(...wrapTextWithAnsi(theme.fg('dim', data.note), inner).map((line) => padded(line, width)));
+        }
+        if (this.error)
+            body.push(padded(theme.fg('error', this.error), width));
+        return body;
+    }
+    rowLine(row, inner, width, theme) {
+        const selected = row.id === this.selectedId;
+        const marker = selected ? '❯ ' : row.always ? '  ' : '· ';
+        const budget = row.budget ? `  ${count(row.tokens * 4)} of ${count(row.budget)} chars` : '';
+        const tools = row.tools?.length ? `  ${row.tools.map((tool) => `${tool.group} ${tool.count}`).join(' · ')}` : '';
+        const note = row.note ? `  ${row.note}` : '';
+        const tail = `${count(row.tokens).padStart(7)}${percent(row.share).padStart(7)}`;
+        const label = `${marker}${row.title}`;
+        const fixed = visibleWidth(tail) + 1;
+        const left = truncateToWidth(label, Math.max(4, inner - fixed - visibleWidth(budget) - visibleWidth(tools) - visibleWidth(note)), '…');
+        const line = `${left}${' '.repeat(Math.max(1, inner - visibleWidth(left) - fixed))}${tail}`;
+        if (selected)
+            return selectedRow(padded(line, width), width, theme);
+        const rest = `${budget}${tools}${note}`;
+        if (rest && inner > visibleWidth(line) + visibleWidth(rest)) {
+            const quiet = theme.fg('dim', rest);
+            return padded(selected ? selectionMuted(theme, line) : line + ' '.repeat(Math.max(1, inner - visibleWidth(line) - visibleWidth(rest))) + quiet, width);
+        }
+        return padded(selected ? selectionText(theme, line) : line, width);
+    }
+    growthBody(width, theme) {
+        const data = this.data;
+        if (!data)
+            return [padded(theme.fg('dim', this.busy ? 'Reading the recorded context…' : 'No reply yet.'), width)];
+        const inner = Math.max(8, width - CHROME_PAD * 2);
+        const body = [];
+        const history = data.history.slice(-24);
+        if (history.length) {
+            const peak = Math.max(...history.map((point) => point.used), 1);
+            const spark = history.map((point) => BARS[Math.min(BARS.length - 1, Math.round((point.used / peak) * (BARS.length - 1)))]).join('');
+            body.push(padded(theme.fg('accent', spark), width));
+            body.push(padded(theme.fg('dim', `${history.length} requests · peak ${count(peak)}${data.compactions.length ? ` · ${data.compactions.length} compaction${data.compactions.length === 1 ? '' : 's'}` : ''}`), width));
+        }
+        else {
+            body.push(padded(theme.fg('dim', 'No measured request yet.'), width));
+        }
+        body.push('');
+        body.push(padded(spread(theme.fg('dim', 'REQUEST'), theme.fg('dim', 'USED      SHARE'), inner), width));
+        for (const point of history.slice().reverse().slice(0, 12)) {
+            body.push(padded(spread(`  ${point.request}`, `${count(point.used).padStart(8)}${percent(point.share).padStart(8)}`, inner), width));
+        }
+        for (const compaction of data.compactions.slice(-3)) {
+            const before = compaction.before === null ? '?' : count(compaction.before);
+            const after = compaction.after === null ? '?' : count(compaction.after);
+            body.push(padded(theme.fg('warning', `  compacted ${before} → ${after}`), width));
+        }
+        body.push('');
+        body.push(...wrapTextWithAnsi(theme.fg('dim', data.note ?? ''), inner).filter(Boolean).map((line) => padded(line, width)));
+        return body;
+    }
+    detailBody(width, theme) {
+        const detail = this.detail;
+        const inner = Math.max(8, width - CHROME_PAD * 2);
+        const body = [];
+        body.push(padded(theme.bold(theme.fg('accent', detail.title)), width));
+        body.push('');
+        for (const line of detail.text.split('\n')) {
+            if (!line.trim()) {
+                body.push('');
+                continue;
+            }
+            for (const wrapped of wrapTextWithAnsi(theme.fg('text', line), inner))
+                body.push(padded(wrapped, width));
+        }
+        return body;
+    }
+}

package/dist/sdk/terminal/tui/pages/trajectoryPage.js

@@ -1,11 +1,12 @@
 import { matchesKey, stripTerminalSequences, truncateToWidth, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
 import { FilterList } from "../list.js";
+import { stripMouseReports } from "../mouseReport.js";
 const ACTIVE = new Set(['queued', 'running', 'waiting_for_approval', 'waiting_for_input']);
 const payloadOf = (event) => event.payload && typeof event.payload === 'object' ? event.payload : {};
 const stringOf = (value) => typeof value === 'string' ? value : undefined;
 const numberOf = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 function safe(value) {
-    return stripTerminalSequences(value).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ' ');
+    return stripTerminalSequences(stripMouseReports(value)).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ' ');
 }
 function timeOf(value) {
     const parsed = Date.parse(value);
@@ -220,8 +221,8 @@ export class TrajectoryPage {
         return this.events.map(event => ({
             id: String(event.sequence),
             label: `${timeOf(event.timestamp)}  ${event.type}`,
-            detail: eventDescription(event),
-            searchText: `${event.timestamp} ${event.type} ${eventDescription(event)} ${safe(JSON.stringify(payloadOf(event)))}`,
+            detail: safe(eventDescription(event)),
+            searchText: `${event.timestamp} ${event.type} ${safe(eventDescription(event))} ${safe(JSON.stringify(payloadOf(event)))}`,
             data: event
         }));
     }
@@ -366,7 +367,7 @@ export class TrajectoryPage {
         if (rows >= 4)
             lines.push(theme.fg('muted', usageLine(this.events)));
         if (rows >= 6)
-            lines.push(theme.fg('dim', this.run.goal ? `Prompt: ${this.run.goal.replace(/\s+/g, ' ').slice(0, 140)}` : 'Prompt text unavailable'));
+            lines.push(theme.fg('dim', this.run.goal ? `Prompt: ${safe(this.run.goal).replace(/\s+/g, ' ').slice(0, 140)}` : 'Prompt text unavailable'));
         if (this.error)
             lines.push(theme.fg('error', `Read error: ${this.error}`));
         return lines.slice(0, Math.min(rows, 5)).map(line => truncateToWidth(line, width, ''));

package/dist/sdk/terminal/tui/runtime.js

@@ -145,7 +145,13 @@ export async function createTerminalRuntime(args, host) {
     // A selection is recorded against the mode it was made in; a one-shot plan run is always plan.
     const recordingMode = () => (planRun.active ? 'plan' : currentMode);
     const modelFor = (reference) => resolveCliModel({ cliModel: reference, modelRuntime }).model;
-    const applyMode = () => modeChoices.apply(native.session, currentMode, modelFor);
+    // The level Pi resolves when no mode has saved an effort: the model's own default, then the account's.
+    const defaultEffort = (session) => {
+        const model = session.model;
+        return ((model ? session.settingsManager.getModelThinkingLevel(model.provider, model.id) : undefined)
+            ?? session.settingsManager.getDefaultThinkingLevel() ?? 'medium');
+    };
+    const applyMode = () => modeChoices.apply(native.session, currentMode, modelFor, defaultEffort(native.session));
     const restoreChoice = async (session, previous) => {
         if (previous.model && (session.model?.provider !== previous.model.provider || session.model?.id !== previous.model.id)) {
             await session.setModel(previous.model, { persist: false }).catch(() => undefined);
@@ -325,7 +331,7 @@ export async function createTerminalRuntime(args, host) {
             planRun.active = true;
             try {
                 session.setActiveToolsByName(allowedTools);
-                await modeChoices.apply(session, 'plan', modelFor);
+                await modeChoices.apply(session, 'plan', modelFor, defaultEffort(session));
                 await session.prompt(text, { expandPromptTemplates: false, ...(images?.length ? { images } : {}) });
             }
             finally {

package/dist/sdk/terminal/tui/search.js

@@ -1,4 +1,5 @@
-import { Input, matchesKey, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { matchesKey, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { MouseSafeInput } from "./mouseReport.js";
 export const SEARCH_GLYPH = '⌕';
 export const SEARCH_PLACEHOLDER = 'Type to search';
 export const SEARCH_FIELD_ROWS = 5;
@@ -14,7 +15,7 @@ export class SearchField {
     input;
     constructor(theme, placeholder = SEARCH_PLACEHOLDER) {
         this.theme = theme;
-        this.input = new Input({ prompt: '', placeholder, placeholderStyle: text => this.theme().fg('dim', text) });
+        this.input = new MouseSafeInput({ prompt: '', placeholder, placeholderStyle: text => this.theme().fg('dim', text) });
     }
     get value() { return this.input.getValue(); }
     set focused(value) { this.input.focused = value; }

package/dist/sdk/terminal/tui/skillInvocation.d.ts

@@ -3,7 +3,26 @@ export interface SkillEntry {
     name: string;
     description: string;
 }
-/** Rewrites a leading `$name` of a loaded skill into `/skill:name`. Anything else passes through, so `$5` stays text. */
-export declare function expandSkillInvocation(text: string, skills: ReadonlySet<string>): string;
+export interface SkillToken {
+    /** What has been typed after the `$`. */
+    query: string;
+    /** Where the `$` is. */
+    from: number;
+    /** The caret. */
+    to: number;
+}
+export interface SkillInvocationMatch {
+    name: string;
+    /** Where the `$` is. */
+    from: number;
+    /** Just after the name. */
+    to: number;
+}
+/** The skill token being typed at `caret`, or null when the caret is not in one. */
+export declare function skillTokenAt(text: string, caret: number): SkillToken | null;
+/** Every `$name` token in the message, whether or not the name is a loaded skill. */
+export declare function skillInvocationMatches(text: string): SkillInvocationMatch[];
+/** Every `$name` in the message that names an enabled skill, in message order, once each. */
+export declare function skillInvocations(text: string, skills: ReadonlySet<string>): string[];
 /** Offers the loaded skills at a `$` that starts a word. Every other completion is `base`'s. */
 export declare function skillCompletions(base: AutocompleteProvider, skills: () => readonly SkillEntry[]): AutocompleteProvider;

package/dist/sdk/terminal/tui/skillInvocation.js

@@ -1,24 +1,44 @@
-/** Rewrites a leading `$name` of a loaded skill into `/skill:name`. Anything else passes through, so `$5` stays text. */
-export function expandSkillInvocation(text, skills) {
-    const trimmed = text.trimStart();
-    const match = /^\$(\S+)(?=\s|$)/.exec(trimmed);
-    if (!match || !skills.has(match[1]))
-        return text;
-    return `/skill:${match[1]}${trimmed.slice(match[0].length)}`;
-}
 /** A `$` that starts a word, and the partial name after it, at the cursor. */
-const SKILL_TOKEN = /(?:^|\s)\$([^\s$]*)$/;
+const SKILL_TOKEN = /(?:^|[\s(])\$([^\s$]*)$/;
+/** A `$name` at a word start, ending at whitespace, punctuation or the end of the message. */
+const SKILL_INVOCATION = /(?:^|[\s(])\$([A-Za-z0-9][A-Za-z0-9_-]*)(?=[\s.,;:!?)]|$)/gu;
 /** A line whose first word is a skill invocation. */
 const SKILL_LINE = /^\s*\$\S/;
+/** The skill token being typed at `caret`, or null when the caret is not in one. */
+export function skillTokenAt(text, caret) {
+    const match = SKILL_TOKEN.exec(text.slice(0, caret));
+    if (!match)
+        return null;
+    const query = match[1] ?? '';
+    return { query, from: caret - query.length - 1, to: caret };
+}
+/** Every `$name` token in the message, whether or not the name is a loaded skill. */
+export function skillInvocationMatches(text) {
+    const found = [];
+    for (const match of text.matchAll(SKILL_INVOCATION)) {
+        const from = match.index + match[0].indexOf('$');
+        found.push({ name: match[1], from, to: from + 1 + match[1].length });
+    }
+    return found;
+}
+/** Every `$name` in the message that names an enabled skill, in message order, once each. */
+export function skillInvocations(text, skills) {
+    const found = [];
+    for (const match of skillInvocationMatches(text)) {
+        if (skills.has(match.name) && !found.includes(match.name))
+            found.push(match.name);
+    }
+    return found;
+}
 /** Offers the loaded skills at a `$` that starts a word. Every other completion is `base`'s. */
 export function skillCompletions(base, skills) {
     return {
         triggerCharacters: [...(base.triggerCharacters ?? []), '$'],
         async getSuggestions(lines, cursorLine, cursorCol, options) {
             const line = lines[cursorLine] ?? '';
-            const token = SKILL_TOKEN.exec(line.slice(0, cursorCol));
+            const token = skillTokenAt(line, cursorCol);
             if (token) {
-                const partial = token[1];
+                const partial = token.query;
                 const items = skills()
                     .filter((skill) => skill.name.startsWith(partial))
                     .map((skill) => ({ value: skill.name, label: `$${skill.name}`, description: skill.description }));

package/dist/sdk/tools/defaultSkills.d.ts

@@ -1,4 +1,23 @@
+/** A skill folder name, without `skills/` or backticks. */
+export declare const SKILL_NAME: RegExp;
+/** One skill's file: what `skill_load` reads, and what the prompt compiler includes. */
+export interface SkillFile {
+    name: string;
+    /** The `SKILL.md` file the text came from. */
+    path: string;
+    /** The skill folder that relative references resolve against. */
+    baseDir: string;
+    /** The instructions after the frontmatter. */
+    body: string;
+    /** Files in the skill's `scripts/` folder, empty when it has none. */
+    helpers: string[];
+}
 /** Locate release-owned resources from source, the SDK, or a bundled executable. */
 export declare function defaultSkillPath(): string;
 /** Variant skills win on a name collision, without modifying a pinned variant. */
 export declare function defaultSkillPaths(variantDir: string | null | undefined): string[];
+/**
+ * A skill by folder name: the pinned variant first, then the shipped `plugin-authoring` skill.
+ * The body has its frontmatter removed. Returns null when no skill has that name.
+ */
+export declare function readSkillFile(variantDir: string | null | undefined, name: string): SkillFile | null;

package/dist/sdk/tools/defaultSkills.js

@@ -1,6 +1,9 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { bodyOf } from "../core/frontmatter.js";
+/** A skill folder name, without `skills/` or backticks. */
+export const SKILL_NAME = /^[a-z0-9][a-z0-9_-]*$/;
 /** Locate release-owned resources from source, the SDK, or a bundled executable. */
 export function defaultSkillPath() {
     let dir = dirname(fileURLToPath(import.meta.url));
@@ -18,3 +21,26 @@ export function defaultSkillPath() {
 export function defaultSkillPaths(variantDir) {
     return variantDir && existsSync(join(variantDir, 'skills', 'plugin-authoring', 'SKILL.md')) ? [] : [defaultSkillPath()];
 }
+/**
+ * A skill by folder name: the pinned variant first, then the shipped `plugin-authoring` skill.
+ * The body has its frontmatter removed. Returns null when no skill has that name.
+ */
+export function readSkillFile(variantDir, name) {
+    const wanted = name.trim().replace(/^skills\//, '').replace(/`/g, '');
+    if (!SKILL_NAME.test(wanted))
+        return null;
+    const variant = variantDir ? join(variantDir, 'skills', wanted, 'SKILL.md') : null;
+    const builtin = wanted === 'plugin-authoring' && defaultSkillPaths(variantDir).length ? defaultSkillPath() : null;
+    const path = variant && existsSync(variant) && statSync(variant).isFile() ? variant : builtin;
+    if (!path)
+        return null;
+    const baseDir = dirname(path);
+    const scripts = join(baseDir, 'scripts');
+    return {
+        name: wanted,
+        path,
+        baseDir,
+        body: bodyOf(readFileSync(path, 'utf8')),
+        helpers: existsSync(scripts) ? readdirSync(scripts) : []
+    };
+}