@ikarmic/forge-core 5.3.0 → 5.4.0

package/dist/orchestrator/specialists.js

@@ -49,7 +49,7 @@ Stop when: you have read enough to name every file and function in the plan. Do
 
 Never: write or edit files, run commands, or plan around code you have not read. If the request is unclear and the answer would change the plan, put it under Questions instead of guessing.`,
         allowedTools: ['read_file', 'list_files', 'search_files', 'find_symbol', 'find_references', 'list_symbols', 'git_diff', 'memory_read', 'todo_write'],
-        forbiddenTools: ['write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'run_command', 'sub_agent'],
+        forbiddenTools: ['write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'run_command', 'bg_start', 'repo_clone', 'suggest_plan', 'sub_agent'],
         maxIterations: 25,
         auto: false,
     },
@@ -129,7 +129,7 @@ Output:
 
 Never: change files, run commands, or state something about this code that you did not read.`,
         allowedTools: ['read_file', 'list_files', 'search_files', 'find_symbol', 'find_references', 'list_symbols', 'fetch_url', 'memory_read'],
-        forbiddenTools: ['write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'run_command', 'sub_agent'],
+        forbiddenTools: ['write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'run_command', 'bg_start', 'repo_clone', 'suggest_plan', 'sub_agent'],
         maxIterations: 15,
         auto: false,
     },
@@ -156,7 +156,7 @@ Report at most ten findings. End with one line: how many hunks you reviewed and
 
 Never: change files, run commands, or report something you did not confirm in the code.`,
         allowedTools: ['read_file', 'list_files', 'search_files', 'find_symbol', 'find_references', 'list_symbols', 'git_diff', 'memory_read'],
-        forbiddenTools: ['write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'run_command', 'sub_agent'],
+        forbiddenTools: ['write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'run_command', 'bg_start', 'repo_clone', 'suggest_plan', 'sub_agent'],
         maxIterations: 20,
         auto: false,
     },

package/dist/semantic/embedder.d.ts

@@ -12,7 +12,18 @@ export interface Embedder {
     /** Stable identity. Vectors from different ids are never compared; a change rebuilds the index. */
     id: string;
     embed(texts: string[]): Promise<number[][]>;
+    /** Where the text goes, when it leaves this process: absent for the offline embedder. */
+    remote?: {
+        host: string;
+        model: string;
+        local: boolean;
+    };
 }
+/** The host and model that would receive chunks of code, or undefined when nothing leaves this machine (F12). */
+export declare function embedderDestination(e: Embedder): {
+    host: string;
+    model: string;
+} | undefined;
 export declare function cosine(a: number[], b: number[]): number;
 /** Lowercased sub-tokens: splits camelCase, snake_case, digits and punctuation. */
 export declare function tokenize(text: string): string[];

package/dist/semantic/embedder.js

@@ -8,6 +8,21 @@
  *   `/v1`, LM Studio, vLLM...). Opt-in via `embedderFromEnv`; chunk text is sent
  *   to that endpoint (after secret redaction).
  */
+/** The host and model that would receive chunks of code, or undefined when nothing leaves this machine (F12). */
+export function embedderDestination(e) {
+    return e.remote && !e.remote.local ? { host: e.remote.host, model: e.remote.model } : undefined;
+}
+function remoteOf(baseUrl, model) {
+    let host = baseUrl;
+    try {
+        host = new URL(baseUrl).hostname.replace(/^\[|\]$/g, '');
+    }
+    catch {
+        // an address that is not a URL: report it as written, and treat it as remote
+    }
+    const local = host === 'localhost' || host === '::1' || /^127\./.test(host);
+    return { host, model, local };
+}
 export function cosine(a, b) {
     let dot = 0;
     let na = 0;
@@ -62,6 +77,7 @@ export function openAiCompatibleEmbedder(options) {
     const batch = options.batchSize ?? 64;
     return {
         id: `openai-compat:${base}:${options.model}`,
+        remote: remoteOf(base, options.model),
         async embed(texts) {
             const out = [];
             for (let i = 0; i < texts.length; i += batch) {

package/dist/semantic/semantic-index.d.ts

@@ -1,10 +1,48 @@
 import { type Embedder } from './embedder.js';
-import { type SemanticManifest } from './vector-store.js';
+import { deleteSemanticIndex, type SemanticManifest } from './vector-store.js';
+export { deleteSemanticIndex };
 export interface SemanticOptions {
     /** File extensions to index, with the dot. Default: the common source and Markdown ones. */
     extensions?: readonly string[];
     /** Hits scoring below this (cosine similarity) are left out. Default: none cut. */
     minScore?: number;
+    /**
+     * Asked before anything is sent to a remote embedder (not for the offline one, nor for a server on this machine). A no
+     * stops the index before a byte leaves. Absent: no question (the terminal app, where the person set the variable).
+     */
+    consent?: (destination: {
+        host: string;
+        model: string;
+    }) => boolean | Promise<boolean>;
+    /** Progress and outcome of an index run, for a status item. */
+    onStatus?: (status: SemanticStatus) => void;
+}
+export type SemanticStatus = {
+    phase: 'indexing';
+    done: number;
+    total: number;
+} | {
+    phase: 'ready';
+    files: number;
+    chunks: number;
+} | {
+    phase: 'error';
+    message: string;
+}
+/** The person did not allow a remote embedder: search by meaning is off. */
+ | {
+    phase: 'off';
+};
+/** The person did not allow sending code to a remote embedder; the message tells the model what to do instead. */
+export declare class SemanticConsentError extends Error {
+    readonly destination: {
+        host: string;
+        model: string;
+    };
+    constructor(destination: {
+        host: string;
+        model: string;
+    });
 }
 /** `"ts, .py,md"` as `['.ts', '.py', '.md']`; undefined (use the defaults) when nothing usable is left. */
 export declare function parseExtensions(text: string | undefined): string[] | undefined;

package/dist/semantic/semantic-index.js

@@ -4,9 +4,19 @@ import { redact } from '../tools/redact.js';
 import { IgnoreRules } from '../tools/ignore-rules.js';
 import { DEFAULT_IGNORED_DIRS } from '../tools/shared.js';
 import { chunkSource } from './chunker.js';
-import { cosine } from './embedder.js';
-import { decodeVector, encodeVector, loadSemanticManifest, saveSemanticManifest } from './vector-store.js';
+import { cosine, embedderDestination } from './embedder.js';
+import { decodeVector, deleteSemanticIndex, encodeVector, loadSemanticManifest, saveSemanticManifest } from './vector-store.js';
+export { deleteSemanticIndex };
 const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.java', '.md']);
+/** The person did not allow sending code to a remote embedder; the message tells the model what to do instead. */
+export class SemanticConsentError extends Error {
+    destination;
+    constructor(destination) {
+        super(`Search by meaning is off: the person did not allow sending code to ${destination.host} (${destination.model}). Use search_files instead.`);
+        this.destination = destination;
+        this.name = 'SemanticConsentError';
+    }
+}
 /** `"ts, .py,md"` as `['.ts', '.py', '.md']`; undefined (use the defaults) when nothing usable is left. */
 export function parseExtensions(text) {
     const list = (text ?? '')
@@ -50,21 +60,36 @@ async function collect(cwd, extensions) {
 }
 /** Bring `.forge/index/embeddings.json` up to date: re-embed only changed files, drop deleted ones. */
 export async function ensureSemanticFresh(cwd, embedder, options = {}) {
+    // Nothing is read, chunked or sent before the person has agreed to where it would go (F12).
+    const destination = embedderDestination(embedder);
+    if (destination && options.consent && !(await options.consent(destination))) {
+        options.onStatus?.({ phase: 'off' });
+        throw new SemanticConsentError(destination);
+    }
     const manifest = await loadSemanticManifest(cwd, embedder.id);
     const files = await collect(cwd, options.extensions ? new Set(options.extensions) : EXTENSIONS);
     const seen = new Set(files.map((f) => f.rel));
     let changed = false;
-    for (const f of files) {
-        if (manifest.files[f.rel]?.mtimeMs === f.mtimeMs)
-            continue;
-        const chunks = await chunkSource(await readFile(f.abs, 'utf8'), f.ext);
-        // Secrets never reach an embedding endpoint or the on-disk index.
-        const vectors = chunks.length ? await embedder.embed(chunks.map((c) => redact(c.text).text)) : [];
-        manifest.files[f.rel] = {
-            mtimeMs: f.mtimeMs,
-            chunks: chunks.map((c, i) => ({ s: c.startLine, e: c.endLine, v: encodeVector(vectors[i]) })),
-        };
-        changed = true;
+    const pending = files.filter((f) => manifest.files[f.rel]?.mtimeMs !== f.mtimeMs);
+    let done = 0;
+    if (pending.length > 0)
+        options.onStatus?.({ phase: 'indexing', done, total: pending.length });
+    try {
+        for (const f of pending) {
+            const chunks = await chunkSource(await readFile(f.abs, 'utf8'), f.ext);
+            // Secrets never reach an embedding endpoint or the on-disk index.
+            const vectors = chunks.length ? await embedder.embed(chunks.map((c) => redact(c.text).text)) : [];
+            manifest.files[f.rel] = {
+                mtimeMs: f.mtimeMs,
+                chunks: chunks.map((c, i) => ({ s: c.startLine, e: c.endLine, v: encodeVector(vectors[i]) })),
+            };
+            changed = true;
+            options.onStatus?.({ phase: 'indexing', done: ++done, total: pending.length });
+        }
+    }
+    catch (err) {
+        options.onStatus?.({ phase: 'error', message: `Indexing stopped${destination ? ` while talking to ${destination.host}` : ''}: ${err.message}` });
+        throw err;
     }
     for (const rel of Object.keys(manifest.files)) {
         if (!seen.has(rel)) {
@@ -74,6 +99,11 @@ export async function ensureSemanticFresh(cwd, embedder, options = {}) {
     }
     if (changed)
         await saveSemanticManifest(cwd, manifest);
+    options.onStatus?.({
+        phase: 'ready',
+        files: Object.keys(manifest.files).length,
+        chunks: Object.values(manifest.files).reduce((n, f) => n + f.chunks.length, 0),
+    });
     return manifest;
 }
 export async function searchSemantic(cwd, embedder, query, k = 8, options = {}) {

package/dist/semantic/vector-store.d.ts

@@ -16,4 +16,6 @@ export interface SemanticManifest {
 export declare function encodeVector(v: number[]): string;
 export declare function decodeVector(s: string): number[];
 export declare function loadSemanticManifest(cwd: string, embedderId: string): Promise<SemanticManifest>;
+/** Delete the index file. True when there was one. */
+export declare function deleteSemanticIndex(cwd: string): Promise<boolean>;
 export declare function saveSemanticManifest(cwd: string, manifest: SemanticManifest): Promise<void>;

package/dist/semantic/vector-store.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 export const EMBEDDINGS_FILE = '.forge/index/embeddings.json';
 export function encodeVector(v) {
@@ -20,6 +20,18 @@ export async function loadSemanticManifest(cwd, embedderId) {
     }
     return { version: 1, embedderId, files: {} };
 }
+/** Delete the index file. True when there was one. */
+export async function deleteSemanticIndex(cwd) {
+    const file = path.join(cwd, EMBEDDINGS_FILE);
+    try {
+        await readFile(file);
+    }
+    catch {
+        return false;
+    }
+    await rm(file, { force: true });
+    return true;
+}
 export async function saveSemanticManifest(cwd, manifest) {
     const file = path.join(cwd, EMBEDDINGS_FILE);
     await mkdir(path.dirname(file), { recursive: true });

package/dist/sessions/index.d.ts

@@ -1,5 +1,5 @@
-export { defaultSessionDir, generateSessionId, saveSession, loadSession, deleteSession, listSessions, findLatestSession, } from './session-store.js';
-export type { Session, ListEntry } from './session-store.js';
+export { defaultSessionDir, generateSessionId, saveSession, loadSession, deleteSession, displayMessages, listSessions, findLatestSession, } from './session-store.js';
+export type { Session, ListEntry, MessageFeedback } from './session-store.js';
 export { pruneByRetention, pruneSessions, type SessionPruneOptions, type SessionPruneResult } from './prune.js';
 export { formatSessionMarkdown, formatSessionJson, type FormatOptions } from './session-export.js';
 export { appendedSince, summarizeMessage, watchSession } from './watch.js';

package/dist/sessions/index.js

@@ -1,4 +1,4 @@
-export { defaultSessionDir, generateSessionId, saveSession, loadSession, deleteSession, listSessions, findLatestSession, } from './session-store.js';
+export { defaultSessionDir, generateSessionId, saveSession, loadSession, deleteSession, displayMessages, listSessions, findLatestSession, } from './session-store.js';
 export { pruneByRetention, pruneSessions } from './prune.js';
 export { formatSessionMarkdown, formatSessionJson } from './session-export.js';
 export { appendedSince, summarizeMessage, watchSession } from './watch.js';

package/dist/sessions/search.js

@@ -3,7 +3,7 @@
  * assistant message (tool calls, tool results and attachment bytes are skipped).
  * Every word of the query must appear; results rank by how often they do, then by recency.
  */
-import { listSessions, loadSession } from './session-store.js';
+import { displayMessages, listSessions, loadSession } from './session-store.js';
 /** The searchable text of a message list: user and assistant text parts. */
 export function sessionText(messages) {
     const out = [];
@@ -49,7 +49,7 @@ export async function searchSessions(dir, query, options = {}) {
         let text;
         try {
             const session = await loadSession(entry.id, dir);
-            text = `${entry.label ?? ''}\n${sessionText(session.messages)}`;
+            text = `${entry.label ?? ''}\n${sessionText(displayMessages(session))}`;
         }
         catch {
             continue;

package/dist/sessions/session-export.d.ts

@@ -16,7 +16,7 @@
  *   - Long strings (tool results, file contents) are truncated with
  *     a "(truncated)" footer so the export stays readable.
  */
-import type { Session } from './session-store.js';
+import { type Session } from './session-store.js';
 export interface FormatOptions {
     /** Max characters per field (tool result, message content). Default 4000. */
     maxField?: number;

package/dist/sessions/session-export.js

@@ -17,6 +17,7 @@
  *     a "(truncated)" footer so the export stays readable.
  */
 import { stripSteering } from '../steering/select.js';
+import { displayMessages } from './session-store.js';
 /** Maximum length of any single string field in the output before truncation. */
 const DEFAULT_MAX_FIELD = 4000;
 /** Hard cap on total output length: anything longer gets a final "(truncated)". */
@@ -54,7 +55,8 @@ export function formatSessionMarkdown(session, options = {}) {
     out.push('');
     // Body: walk messages, grouping tool results under their parent assistant turn.
     let pendingToolResults = [];
-    for (const msg of session.messages) {
+    // Deep redaction first: a secret-named field (`{ "api_key": ... }`) is invisible to the text patterns below (RB-59).
+    for (const msg of displayMessages(redact ? redactSession(session) : session)) {
         if (msg.role === 'user') {
             // Injected steering is agent context, not something the user typed.
             const content = withoutSteering(msg.content);
@@ -281,41 +283,47 @@ function redactSession(session) {
     // content field is a discriminated union of string/array shapes and
     // TS won't let us reassign across variants when we spread the
     // original message.
-    const messages = session.messages.map((msg) => {
+    const redactAll = (list) => list.map((msg) => {
         const m = msg;
-        const next = redactContent(m.content);
-        return { ...m, content: next };
+        return { ...m, content: redactContent(m.content) };
     });
-    return { ...session, messages: messages };
+    // The transcript holds everything said before compaction too: it is redacted the same way (RB-58).
+    // A note on a rating is text the person typed: it can hold a secret too (F3).
+    const feedback = session.feedback
+        ? Object.fromEntries(Object.entries(session.feedback).map(([turn, f]) => [turn, f.note ? { ...f, note: redactString(f.note, true) } : f]))
+        : undefined;
+    return {
+        ...session,
+        messages: redactAll(session.messages),
+        ...(session.transcript ? { transcript: redactAll(session.transcript) } : {}),
+        ...(feedback ? { feedback } : {}),
+    };
 }
 function redactContent(content) {
-    if (typeof content === 'string')
-        return redactString(content, true);
-    if (!Array.isArray(content))
-        return content;
-    return content.map((part) => {
-        if (!part || typeof part !== 'object')
-            return part;
-        const p = part;
-        const out = { ...p };
-        if (typeof out.text === 'string')
-            out.text = redactString(out.text, true);
-        if (typeof out.output === 'string')
-            out.output = redactString(out.output, true);
-        if (typeof out.result === 'string')
-            out.result = redactString(out.result, true);
-        if (typeof out.args === 'string')
-            out.args = redactString(out.args, true);
-        if (out.args && typeof out.args === 'object') {
-            try {
-                out.args = JSON.parse(redactString(JSON.stringify(out.args), true));
-            }
-            catch {
-                // leave as-is on parse failure
-            }
-        }
-        if (typeof out.input === 'string')
-            out.input = redactString(out.input, true);
+    return redactDeep(content);
+}
+/** Field names whose string value is a secret whatever it looks like (`{ "password": "hunter2" }`). */
+const SECRET_KEY = /^(password|passwd|pwd|api[_-]?key|secret|token|access[_-]?token|auth(orization)?)$/i;
+/** Fields that name things rather than carry text; never rewritten. */
+const STRUCTURAL_KEYS = new Set(['type', 'role', 'toolCallId', 'toolName', 'mediaType']);
+/**
+ * Redact every string inside a message's content, at any depth (RB-59): tool call `input` and tool result
+ * `output.value` are objects in the AI SDK shape, and a field list missed them. Walking values, not a JSON string,
+ * keeps the shape intact.
+ */
+function redactDeep(value, key) {
+    if (typeof value === 'string') {
+        if (key && SECRET_KEY.test(key))
+            return '***REDACTED***';
+        return key && STRUCTURAL_KEYS.has(key) ? value : redactString(value, true);
+    }
+    if (Array.isArray(value))
+        return value.map((v) => redactDeep(v));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = redactDeep(v, k);
         return out;
-    });
+    }
+    return value;
 }

package/dist/sessions/session-store.d.ts

@@ -20,8 +20,18 @@ export interface Session {
     cwd: string;
     /** Model used for the most recent turn (informational). */
     model: ModelConfig;
-    /** Conversation history at the time of the last save. */
+    /** Conversation history at the time of the last save: what the next turn sends, compacted. */
     messages: ModelMessage[];
+    /**
+     * Every message shown in the chat, never compacted (RB-58). Absent in sessions saved before it: use
+     * {@link displayMessages}, which falls back to `messages`.
+     */
+    transcript?: ModelMessage[];
+    /**
+     * Ratings the person gave replies, keyed by turn number (1 = the first message). Kept here only: nothing sends it anywhere.
+     * Must be listed in `sessionSchema` below, or every load drops it (RB-58).
+     */
+    feedback?: Record<string, MessageFeedback>;
     /** Token usage accrued across the session, if known. */
     totalInputTokens?: number;
     totalOutputTokens?: number;
@@ -30,6 +40,13 @@ export interface Session {
     /** Whether pricing was resolved for the session's model. */
     costKnown?: boolean;
 }
+/** A thumbs up or down on one turn's reply, with an optional note on a down. */
+export interface MessageFeedback {
+    rating: 'up' | 'down';
+    note?: string;
+    /** ISO-8601 time of the rating. */
+    at: string;
+}
 /** Default session directory: `~/.forge/sessions/`. */
 export declare function defaultSessionDir(env?: NodeJS.ProcessEnv): string;
 /** Generate a fresh session id like `2026-09-24T18-04-01Z-3f9c2a`. */
@@ -62,3 +79,5 @@ export declare function deleteSession(id: string, dir: string): Promise<void>;
 export declare function listSessions(dir: string): Promise<ListEntry[]>;
 /** Most-recent session, or null if there are none. */
 export declare function findLatestSession(dir: string): Promise<ListEntry | null>;
+/** The messages to show for a session: the full transcript, or `messages` for a file saved before RB-58. */
+export declare function displayMessages(session: Pick<Session, 'messages' | 'transcript'>): ModelMessage[];

package/dist/sessions/session-store.js

@@ -15,6 +15,9 @@ const sessionSchema = z.object({
         model: z.string(),
     }),
     messages: z.array(z.unknown()),
+    // zod drops keys it does not list: without this line every load lost the transcript (RB-58).
+    transcript: z.array(z.unknown()).optional(),
+    feedback: z.record(z.string(), z.object({ rating: z.enum(['up', 'down']), note: z.string().optional(), at: z.string() })).optional(),
     totalInputTokens: z.number().optional(),
     totalOutputTokens: z.number().optional(),
     totalCostUsd: z.number().optional(),
@@ -181,3 +184,7 @@ async function rename(from, to) {
 // Suppress unused-import warning on rare Node versions.
 void mkdtemp;
 void rm;
+/** The messages to show for a session: the full transcript, or `messages` for a file saved before RB-58. */
+export function displayMessages(session) {
+    return session.transcript ?? session.messages;
+}

package/dist/sessions/watch.js

@@ -5,7 +5,7 @@
  */
 import { stat } from 'node:fs/promises';
 import path from 'node:path';
-import { loadSession } from './session-store.js';
+import { displayMessages, loadSession } from './session-store.js';
 /** Starts following session `id`; returns a function that stops it. */
 export function watchSession(id, dir, onUpdate, opts = {}) {
     const file = path.join(dir, `${id}.json`);
@@ -28,11 +28,11 @@ export function watchSession(id, dir, onUpdate, opts = {}) {
             if (stopped)
                 return;
             if (known === undefined) {
-                known = session.messages;
+                known = displayMessages(session);
                 return;
             }
-            const appended = appendedSince(known, session.messages);
-            known = session.messages;
+            const appended = appendedSince(known, displayMessages(session));
+            known = displayMessages(session);
             if (appended === null || appended.length > 0)
                 onUpdate({ session, appended });
         }

package/dist/skills/activator.d.ts

@@ -43,6 +43,12 @@ export declare function selectSkills(skills: Skill[], task: string, maxSkills?:
  * The output is plain text: it's appended to the system prompt verbatim.
  */
 export declare function buildSkillsBlock(skills: Skill[]): string;
+/**
+ * Every skill by name and one line, sorted by name so the block does not change between turns (the prompt cache
+ * depends on it) and does not depend on the task. The keyword pick above still carries full bodies. Text from a
+ * skill file can come from a cloned repository, so angle brackets are dropped and the closing tag cannot be forged.
+ */
+export declare function buildSkillIndex(skills: Skill[]): string;
 /**
  * Compose the full skills section that gets prepended to the system
  * prompt. Includes a short preamble explaining how to interpret skills.

package/dist/skills/activator.js

@@ -101,6 +101,23 @@ export function buildSkillsBlock(skills) {
     }
     return `<skills>\n${sections.join('\n\n---\n\n')}\n</skills>`;
 }
+const INDEX_MAX_ENTRIES = 60;
+const INDEX_DESCRIPTION_CHARS = 140;
+/**
+ * Every skill by name and one line, sorted by name so the block does not change between turns (the prompt cache
+ * depends on it) and does not depend on the task. The keyword pick above still carries full bodies. Text from a
+ * skill file can come from a cloned repository, so angle brackets are dropped and the closing tag cannot be forged.
+ */
+export function buildSkillIndex(skills) {
+    if (skills.length === 0)
+        return '';
+    const clean = (text, max) => text.split('\n')[0].replace(/[<>]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+    const sorted = [...skills].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const lines = sorted.slice(0, INDEX_MAX_ENTRIES).map((s) => `- ${clean(s.name, 60)}${s.description ? `: ${clean(s.description, INDEX_DESCRIPTION_CHARS)}` : ''}`);
+    if (sorted.length > INDEX_MAX_ENTRIES)
+        lines.push(`- ... and ${sorted.length - INDEX_MAX_ENTRIES} more`);
+    return ['These skills are installed. Load one with the `skill` tool when it fits the task.', '<available-skills>', ...lines, '</available-skills>'].join('\n');
+}
 /**
  * Compose the full skills section that gets prepended to the system
  * prompt. Includes a short preamble explaining how to interpret skills.

package/dist/skills/skill-tool.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+import type { SkillRegistry } from './types.js';
+declare const params: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `skill`: load one skill's instructions. The prompt lists every skill by name, but only the ones that matched the
+ * task by keyword carry their body; this loads any other. It reads what is already loaded, so it asks nothing.
+ */
+export declare function createSkillTool(registry: SkillRegistry): ToolDefinition<z.infer<typeof params>, string>;
+export {};

package/dist/skills/skill-tool.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+const params = z.object({ name: z.string().describe('The name of a skill from the available skills list.') });
+/**
+ * `skill`: load one skill's instructions. The prompt lists every skill by name, but only the ones that matched the
+ * task by keyword carry their body; this loads any other. It reads what is already loaded, so it asks nothing.
+ */
+export function createSkillTool(registry) {
+    return {
+        name: 'skill',
+        description: 'Load the instructions of one of the available skills by name, then follow them. Use it when a skill in the list fits the task.',
+        parameters: params,
+        execute: async (args) => {
+            const wanted = args.name.trim();
+            const all = registry.list();
+            const found = registry.get(wanted) ?? all.find((s) => s.name.toLowerCase() === wanted.toLowerCase());
+            if (!found) {
+                const names = all.map((s) => s.name).sort();
+                throw new Error(`No skill named "${wanted}". Available: ${names.slice(0, 40).join(', ') || '(none)'}.`);
+            }
+            return [
+                `## Skill: ${found.name}`,
+                ...(found.allowedTools?.length ? [`Allowed tools: ${found.allowedTools.join(', ')}`] : []),
+                '',
+                found.body,
+            ].join('\n');
+        },
+    };
+}

package/dist/tools/background-process.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import type { ToolContext, ToolDefinition } from '../types.js';
+export interface BackgroundRead {
+    id: string;
+    command: string;
+    running: boolean;
+    exitCode: number | null;
+    /** Output since the cursor, secrets removed. */
+    output: string;
+    /** Pass this as `since` to get only what comes after. */
+    nextSince: number;
+    /** Characters between the cursor and the start of `output` that were lost (buffer or read limit). */
+    droppedChars: number;
+}
+export declare class BackgroundProcesses {
+    private readonly entries;
+    private nextId;
+    private readonly maxBufferChars;
+    constructor(options?: {
+        maxBufferChars?: number;
+    });
+    /** How many are running now. */
+    get liveCount(): number;
+    start(command: string, cwd: string, ctx: ToolContext, cwdOverride?: string): {
+        id: string;
+        pid: number | undefined;
+    };
+    private get;
+    read(id: string, since?: number): BackgroundRead;
+    stop(id: string): {
+        id: string;
+        wasRunning: boolean;
+    };
+    /** Stop everything still running; returns what was running. */
+    stopAll(): {
+        id: string;
+        command: string;
+    }[];
+}
+declare const startParams: z.ZodObject<{
+    command: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const bgStartTool: ToolDefinition<z.infer<typeof startParams>, {
+    id: string;
+    pid: number | undefined;
+    note: string;
+}>;
+declare const readParams: z.ZodObject<{
+    id: z.ZodString;
+    since: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const bgReadTool: ToolDefinition<z.infer<typeof readParams>, BackgroundRead & {
+    note?: string;
+}>;
+declare const stopParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const bgStopTool: ToolDefinition<z.infer<typeof stopParams>, {
+    id: string;
+    wasRunning: boolean;
+}>;
+export {};