@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/sessions/workSlice.d.ts

@@ -0,0 +1,103 @@
+import type { Checkpoint } from "./contracts.js";
+export declare const WORK_SLICE_EXTENSION = "work-slice";
+export interface WorkSliceInput {
+    /** False turns the guard off for this run: no budget, no stall notes, no continuation. */
+    enabled?: boolean;
+    /** Tool calls in one reply; 0 disables this limit. */
+    maxToolCalls?: number;
+    /** Minutes in one reply; 0 disables this limit. */
+    maxMinutes?: number;
+    /** New tokens in one reply (input + cache read + output); 0 disables this limit. */
+    maxNewTokens?: number;
+    /** Slices one task may use before it is handed back to the person; 0 disables the cap. */
+    maxSlices?: number;
+    /** Start the next slice from the checkpoint without asking. */
+    continue?: boolean;
+}
+export interface SlicePolicy {
+    enabled: boolean;
+    maxToolCalls: number;
+    maxMinutes: number;
+    maxNewTokens: number;
+    maxSlices: number;
+    continue: boolean;
+}
+/** The foundation defaults: enough for one meaningful step of work, short enough to report. */
+export declare const DEFAULT_SLICE_POLICY: SlicePolicy;
+export declare class WorkSliceError extends Error {
+}
+/**
+ * The policy a run asked for, or the defaults. `XINGULAR_WORK_SLICE=off` at launch turns the guard
+ * off for every run in this process; nothing is persisted, so restarting without it restores the
+ * defaults.
+ */
+export declare function parseWorkSlice(input: unknown): SlicePolicy;
+export type SliceEnd = 'budget' | 'stuck' | 'compaction-thrash';
+/** What a live reply tracks for its slice; the runner reads it after the reply. */
+export interface SliceState {
+    slice: number;
+    steps: number;
+    tokens: number;
+    startedAt: number;
+    lastTool: string | null;
+    compactions: number;
+    checkpointWritten: boolean;
+    /** Set when the guard ended the reply instead of the model finishing it. */
+    endedBy: SliceEnd | null;
+    /** The limit that ended it, for the record. */
+    endedByLimit: string | null;
+    /** Steps past which every non-exempt tool call is refused, once one was refused. */
+    refusedAt: number | null;
+}
+export declare function createSliceState(_policy: SlicePolicy, slice?: number, now?: number): SliceState;
+/** Counters start again for each reply; a terminal session keeps one guard across replies. */
+export declare function resetSliceState(state: SliceState, now?: number): void;
+/** The first limit this reply has passed, named as a person would say it. */
+export declare function sliceLimitReached(policy: SlicePolicy, state: SliceState, now?: number): string | null;
+/** Commands that read as a check, for "no progress" and "still failing" rules. */
+export declare function looksLikeCheck(command: string): boolean;
+interface ToolCall {
+    toolName: string;
+    input?: unknown;
+}
+interface ToolResult {
+    toolName: string;
+    isError?: boolean;
+    input?: unknown;
+}
+/** The part of Pi's extension API this guard uses. Structural, so the module needs no Pi import. */
+interface GuardApi {
+    on(event: 'agent_start', handler: () => unknown): void;
+    on(event: 'tool_call', handler: (event: ToolCall) => unknown): void;
+    on(event: 'tool_result', handler: (event: ToolResult) => unknown): void;
+    on(event: 'message_end', handler: (event: {
+        message: {
+            role: string;
+            usage?: {
+                input?: number;
+                output?: number;
+                cacheRead?: number;
+                cacheWrite?: number;
+            };
+        };
+    }) => unknown): void;
+}
+export interface WorkSliceGuardOptions {
+    policy: SlicePolicy;
+    state: SliceState;
+    /** Called once the guard has decided the reply must stop; the runner ends it. */
+    onEnd?: (end: SliceEnd, limit: string) => void;
+}
+/**
+ * Bounds one reply and names repeated work. The first refusal asks for a checkpoint; a tool call
+ * after that refusal ends the reply. A repeated call or failing command is named once, then ends it.
+ */
+export declare function workSliceGuard(options: WorkSliceGuardOptions): (pi: GuardApi) => void;
+/**
+ * Which slice of its session a run is, from 1. Counts the recorded continuation chain, so it
+ * survives a restart and needs no extra field on the run record.
+ */
+export declare function sliceOf(root: string, runId: string, limit?: number): number;
+/** The reason a checkpoint the harness derives (no model handoff) records. */
+export declare function derivedReason(end: SliceEnd | null): Checkpoint['reason'];
+export {};

package/dist/sdk/sessions/workSlice.js

@@ -0,0 +1,297 @@
+// A reply's work slice (PROP-0041): a bounded amount of work, then a handoff checkpoint, then a
+// continuation. The guard here refuses the call that would run past the budget, once with a
+// request for the checkpoint, and ends the reply if the model keeps calling tools. It also names
+// repeated work before it becomes a loop. All decisions are deterministic; no model is consulted.
+import { createHash } from 'node:crypto';
+import { findRun } from "./runStore.js";
+export const WORK_SLICE_EXTENSION = 'work-slice';
+/** The foundation defaults: enough for one meaningful step of work, short enough to report. */
+export const DEFAULT_SLICE_POLICY = {
+    enabled: true,
+    // Roughly 40 minutes of ordinary work (about 15 s a call), so a checkpoint is a chapter of a
+    // task, not an interruption every few edits. A task still gets eight of them before the cap.
+    maxToolCalls: 160,
+    maxMinutes: 40,
+    // A generous cost ceiling, counted on new input, cache writes and output only: heavy reading at
+    // a large context can add tens of thousands of tokens a request, so a small cap stopped useful
+    // work (see the "Confirm plan model support" thread). 320k is a safety net, not the bound.
+    maxNewTokens: 320_000,
+    maxSlices: 8,
+    continue: true
+};
+const LIMITS = {
+    maxToolCalls: { min: 1, max: 2_000 },
+    maxMinutes: { min: 1, max: 480 },
+    maxNewTokens: { min: 1_000, max: 5_000_000 },
+    maxSlices: { min: 1, max: 100 }
+};
+export class WorkSliceError extends Error {
+}
+/**
+ * The policy a run asked for, or the defaults. `XINGULAR_WORK_SLICE=off` at launch turns the guard
+ * off for every run in this process; nothing is persisted, so restarting without it restores the
+ * defaults.
+ */
+export function parseWorkSlice(input) {
+    if (input === undefined || input === null) {
+        const launch = process.env.XINGULAR_WORK_SLICE?.trim().toLowerCase();
+        return { ...DEFAULT_SLICE_POLICY, ...(launch === 'off' || launch === '0' || launch === 'false' ? { enabled: false } : {}) };
+    }
+    if (typeof input !== 'object' || Array.isArray(input))
+        throw new WorkSliceError('workSlice must be an object.');
+    const record = input;
+    const policy = { ...DEFAULT_SLICE_POLICY };
+    for (const key of Object.keys(record)) {
+        if (key === 'enabled') {
+            if (typeof record.enabled !== 'boolean')
+                throw new WorkSliceError('workSlice.enabled must be true or false.');
+            policy.enabled = record.enabled;
+            continue;
+        }
+        if (key === 'continue') {
+            if (typeof record.continue !== 'boolean')
+                throw new WorkSliceError('workSlice.continue must be true or false.');
+            policy.continue = record.continue;
+            continue;
+        }
+        const limits = LIMITS[key];
+        if (!limits)
+            throw new WorkSliceError(`workSlice has no field ${key}.`);
+        const value = record[key];
+        if (typeof value !== 'number' || !Number.isInteger(value))
+            throw new WorkSliceError(`workSlice.${key} must be a whole number.`);
+        // 0 switches one limit off, as the settings page says.
+        if (value === 0) {
+            policy[key] = 0;
+            continue;
+        }
+        if (value < limits.min || value > limits.max)
+            throw new WorkSliceError(`workSlice.${key} must be between ${limits.min} and ${limits.max}, or 0 for no limit.`);
+        policy[key] = value;
+    }
+    return policy;
+}
+export function createSliceState(_policy, slice = 1, now = Date.now()) {
+    return { slice, steps: 0, tokens: 0, startedAt: now, lastTool: null, compactions: 0, checkpointWritten: false, endedBy: null, endedByLimit: null, refusedAt: null };
+}
+/** Counters start again for each reply; a terminal session keeps one guard across replies. */
+export function resetSliceState(state, now = Date.now()) {
+    state.steps = 0;
+    state.tokens = 0;
+    state.startedAt = now;
+    state.lastTool = null;
+    state.compactions = 0;
+    state.checkpointWritten = false;
+    state.endedBy = null;
+    state.endedByLimit = null;
+    state.refusedAt = null;
+}
+/** The first limit this reply has passed, named as a person would say it. */
+export function sliceLimitReached(policy, state, now = Date.now()) {
+    if (policy.maxToolCalls > 0 && state.steps >= policy.maxToolCalls)
+        return `${policy.maxToolCalls} tool calls`;
+    if (policy.maxMinutes > 0 && now - state.startedAt >= policy.maxMinutes * 60_000)
+        return `${policy.maxMinutes} minutes`;
+    if (policy.maxNewTokens > 0 && state.tokens >= policy.maxNewTokens)
+        return `${Math.round(policy.maxNewTokens / 1000)}k new tokens`;
+    return null;
+}
+/** Tools a reply may still call while it writes its handoff. A plan update waits for the next slice. */
+const HANDOFF_TOOLS = new Set(['checkpoint_write', 'session_name']);
+/** Tools whose repetition is how waiting works, not a loop. */
+const POLLING_TOOLS = new Set(['wait_subagents', 'subagents.list', 'subagents.status']);
+/** Commands that read as a check, for "no progress" and "still failing" rules. */
+export function looksLikeCheck(command) {
+    return /\b(test|tests|typecheck|tsc|vitest|jest|cargo|check:|prove|lint|ci|build)\b/u.test(command);
+}
+/**
+ * A stable rendering of a value: object keys sorted, so argument order never changes the result.
+ * Depth is bounded so a cyclic or absurdly nested input cannot recurse forever.
+ */
+function canonical(value, depth = 0) {
+    if (depth > 8)
+        return '…';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonical(item, depth + 1)).join(',')}]`;
+    const entries = Object.entries(value).filter(([, item]) => item !== undefined);
+    entries.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonical(item, depth + 1)}`).join(',')}}`;
+}
+/**
+ * A call's identity: its name and every argument, hashed so the key stays small even when an
+ * argument is a whole file. A changed argument is a different call; only an identical one repeats.
+ * Reading a fixed handful of fields made every `checklist_write` look identical, so a reply that
+ * reported its progress was told it was repeating work.
+ */
+const signature = (name, input) => `${name}\u0000${createHash('sha256').update(canonical(input ?? null)).digest('hex')}`;
+const clip = (value, limit) => (value.length <= limit ? value : `${value.slice(0, limit - 1)}…`);
+function handoffRequest(limit, state) {
+    return clip(`This reply reached its work-slice limit (${limit}; step ${state.steps}). Call checkpoint_write now with what is done, the single next step, anything blocking, the files you touched and the checks that matter. Then tell the user in a few lines where you stopped. Do not call other tools.`, 600);
+}
+function stalledNote(reason) {
+    return clip(`You are repeating work: ${reason}. Do not repeat it. Choose a different approach, read what the earlier attempt returned, or call checkpoint_write with the blocker so the next slice can decide.`, 600);
+}
+/**
+ * Bounds one reply and names repeated work. The first refusal asks for a checkpoint; a tool call
+ * after that refusal ends the reply. A repeated call or failing command is named once, then ends it.
+ */
+export function workSliceGuard(options) {
+    const { policy, state } = options;
+    const calls = new Map();
+    const edits = new Map();
+    const failures = new Map();
+    let stepsSinceProgress = 0;
+    let nudged = false;
+    /** Repetition is judged inside one reply; the next reply starts from a clean count. */
+    const resetRepetition = () => {
+        calls.clear();
+        edits.clear();
+        failures.clear();
+        stepsSinceProgress = 0;
+        nudged = false;
+    };
+    const end = (kind, limit) => {
+        state.endedBy = kind;
+        state.endedByLimit = limit;
+        options.onEnd?.(kind, limit);
+        const reason = kind === 'stuck'
+            ? stalledNote(limit)
+            : kind === 'compaction-thrash'
+                ? handoffRequest('three context compactions in one reply', state)
+                : handoffRequest(limit, state);
+        return { block: true, terminate: true, reason };
+    };
+    const repeated = (name, input) => {
+        if (POLLING_TOOLS.has(name))
+            return null;
+        const key = signature(name, input);
+        const count = (calls.get(key) ?? 0) + 1;
+        calls.set(key, count);
+        if (count < 3)
+            return null;
+        return name === 'bash' ? `the same Bash command ${count} times (steps ending at ${state.steps})` : `the same ${name} call ${count} times (steps ending at ${state.steps})`;
+    };
+    const failing = (name, input) => {
+        if (name !== 'bash')
+            return null;
+        const command = input && typeof input === 'object' ? String(input.command ?? '') : '';
+        if (!command || !looksLikeCheck(command))
+            return null;
+        const count = failures.get(command) ?? 0;
+        return count >= 2 ? `the check ${command} failed ${count} times` : null;
+    };
+    return (pi) => {
+        pi.on('agent_start', () => {
+            resetSliceState(state);
+            resetRepetition();
+        });
+        pi.on('message_end', (event) => {
+            const usage = event.message.usage;
+            if (event.message.role !== 'assistant' || !usage)
+                return;
+            // New tokens only: the cached prefix was sent before and is not new context or new cost.
+            state.tokens += (usage.input ?? 0) + (usage.cacheWrite ?? 0) + (usage.output ?? 0);
+        });
+        pi.on('tool_result', (event) => {
+            if (event.toolName === 'checkpoint_write' && !event.isError) {
+                state.checkpointWritten = true;
+                stepsSinceProgress = 0;
+                nudged = false;
+            }
+            if (event.toolName !== 'bash')
+                return;
+            const command = event.input && typeof event.input === 'object' ? String(event.input.command ?? '') : '';
+            if (!command || !looksLikeCheck(command))
+                return;
+            if (event.isError) {
+                failures.set(command, (failures.get(command) ?? 0) + 1);
+                return;
+            }
+            // A passing check is progress: the repetition rules start over.
+            failures.delete(command);
+            edits.clear();
+            calls.clear();
+            stepsSinceProgress = 0;
+            nudged = false;
+        });
+        pi.on('tool_call', (event) => {
+            const name = event.toolName;
+            state.steps += 1;
+            state.lastTool = name;
+            const handoff = HANDOFF_TOOLS.has(name);
+            // A handoff is always callable; after the slice ended it is the only thing that is.
+            if (state.endedBy) {
+                return handoff ? undefined : { block: true, terminate: true, reason: 'This reply is over. Its checkpoint is recorded; nothing else runs.' };
+            }
+            if (state.compactions >= 3) {
+                if (handoff) {
+                    state.endedBy = 'compaction-thrash';
+                    state.endedByLimit = 'three compactions';
+                    return undefined;
+                }
+                return end('compaction-thrash', 'three compactions');
+            }
+            const limit = sliceLimitReached(policy, state);
+            if (limit) {
+                // The slice ends here; the model gets one wrap-up request to write the handoff. A handoff
+                // call is never refused, including when it is the very first call past the budget.
+                state.endedBy = 'budget';
+                state.endedByLimit = limit;
+                state.refusedAt ??= state.steps;
+                stepsSinceProgress = 0;
+                return handoff ? undefined : { block: true, reason: handoffRequest(limit, state) };
+            }
+            if (handoff)
+                return undefined;
+            const edit = name === 'edit' || name === 'write';
+            const path = edit && event.input && typeof event.input === 'object' ? String(event.input.path ?? '') : '';
+            if (edit && path) {
+                const count = (edits.get(path) ?? 0) + 1;
+                edits.set(path, count);
+                stepsSinceProgress = 0;
+                if (count >= 4) {
+                    const reason = `${path} was edited ${count} times with no passing check between`;
+                    if (nudged)
+                        return end('stuck', reason);
+                    nudged = true;
+                    return { block: true, reason: stalledNote(reason) };
+                }
+            }
+            else {
+                stepsSinceProgress += 1;
+            }
+            const repeat = repeated(name, event.input);
+            const failure = failing(name, event.input);
+            const noProgress = stepsSinceProgress >= 25 ? `${stepsSinceProgress} steps with no file change and no passing check` : null;
+            const reason = repeat ?? failure ?? noProgress;
+            if (!reason)
+                return undefined;
+            if (nudged)
+                return end('stuck', reason);
+            nudged = true;
+            stepsSinceProgress = 0;
+            return { block: true, reason: stalledNote(reason) };
+        });
+    };
+}
+/**
+ * Which slice of its session a run is, from 1. Counts the recorded continuation chain, so it
+ * survives a restart and needs no extra field on the run record.
+ */
+export function sliceOf(root, runId, limit = 100) {
+    let current = runId;
+    let count = 0;
+    const seen = new Set();
+    while (current && count < limit && !seen.has(current)) {
+        seen.add(current);
+        count += 1;
+        current = findRun(root, current)?.resumedFromRunId ?? null;
+    }
+    return Math.max(1, count);
+}
+/** The reason a checkpoint the harness derives (no model handoff) records. */
+export function derivedReason(end) {
+    return end ?? 'requested';
+}

package/dist/sdk/sessions/workspaceBoundary.d.ts

@@ -0,0 +1,15 @@
+import type { RunRecord } from "./contracts.js";
+import type { ScopeDecision } from "./policy.js";
+export declare const WORKSPACE_FILE_WRITE_TOOLS: Set<string>;
+export interface WorkspaceWriteInspection {
+    input: unknown;
+    path: string | null;
+    outside: boolean;
+    reason: string | null;
+}
+/** Canonicalize native file-write arguments and identify an explicit workspace escape. */
+export declare function inspectWorkspaceWrite(workspaceRoot: string, cwd: string, tool: string, input: unknown): WorkspaceWriteInspection;
+/** Adds the mandatory per-operation boundary without allowing it to waive host hard denials. */
+export declare function combineWorkspaceScope(scope: ScopeDecision, inspection: WorkspaceWriteInspection): ScopeDecision;
+/** Resolve a root for pre-boundary run records, then inspect the write using the pinned directory. */
+export declare function inspectRunWorkspaceWrite(run: RunRecord, tool: string, input: unknown): WorkspaceWriteInspection;

package/dist/sdk/sessions/workspaceBoundary.js

@@ -0,0 +1,46 @@
+import { isWithinWorkspace, resolveWorkspaceRoot, resolveWritePath, verifyWorkspaceRoot } from "../core/workspace.js";
+export const WORKSPACE_FILE_WRITE_TOOLS = new Set(['edit', 'write']);
+/** Canonicalize native file-write arguments and identify an explicit workspace escape. */
+export function inspectWorkspaceWrite(workspaceRoot, cwd, tool, input) {
+    if (!WORKSPACE_FILE_WRITE_TOOLS.has(tool.toLowerCase()) || !input || typeof input !== 'object' || Array.isArray(input)) {
+        return { input, path: null, outside: false, reason: null };
+    }
+    const args = input;
+    if (typeof args.path !== 'string')
+        return { input, path: null, outside: false, reason: null };
+    const root = verifyWorkspaceRoot(workspaceRoot);
+    const path = resolveWritePath(args.path, cwd);
+    const outside = !isWithinWorkspace(root, path);
+    return {
+        input: { ...args, path },
+        path,
+        outside,
+        reason: outside ? `Write target ${path} is outside the active project workspace ${root}.` : null
+    };
+}
+/** Adds the mandatory per-operation boundary without allowing it to waive host hard denials. */
+export function combineWorkspaceScope(scope, inspection) {
+    if (!inspection.outside)
+        return scope;
+    if (!scope.allowed && (scope.automatic || !scope.requiresApproval))
+        return scope;
+    return {
+        ...scope,
+        allowed: false,
+        requiresApproval: true,
+        humanOnly: true,
+        allowGlobalApproval: scope.humanOnly ? scope.allowGlobalApproval : true,
+        reason: inspection.reason
+    };
+}
+/** Resolve a root for pre-boundary run records, then inspect the write using the pinned directory. */
+export function inspectRunWorkspaceWrite(run, tool, input) {
+    const cwd = run.workingDirectory;
+    const root = run.workspaceRoot ?? (cwd ? resolveWorkspaceRoot(cwd) : null);
+    if (!root || !cwd) {
+        if (WORKSPACE_FILE_WRITE_TOOLS.has(tool.toLowerCase()))
+            throw new Error('The active project workspace could not be resolved; file writes are blocked.');
+        return { input, path: null, outside: false, reason: null };
+    }
+    return inspectWorkspaceWrite(root, cwd, tool, input);
+}

package/dist/sdk/terminal/browser.d.ts

@@ -0,0 +1,62 @@
+import type { HubOverview } from "../hub/schema.js";
+import type { Connection } from "../mcp/types.js";
+import type { Plugin } from "../plugins/types.js";
+export declare const BROWSER_SECTIONS: readonly ["overview", "foundation", "variant", "skills", "plugins", "connections", "tools", "library"];
+export type BrowserSection = typeof BROWSER_SECTIONS[number];
+export type BrowserSource = 'installed' | 'discover';
+export type BrowserChannel = 'all' | 'community' | 'official';
+export declare const BROWSER_COMMANDS: Set<string>;
+export interface BrowserItem {
+    id: string;
+    section: BrowserSection;
+    name: string;
+    description: string;
+    owner: string;
+    origin: string;
+    status: string;
+    path?: string;
+    scope?: string | null;
+    pluginId?: string;
+    contributionId?: string;
+    componentId?: string;
+    connectionId?: string;
+    skillName?: string;
+    available?: boolean;
+    read?: boolean;
+    added?: boolean;
+    required?: string | null;
+    parameters?: unknown;
+}
+export interface BrowserSnapshot {
+    items: BrowserItem[];
+    plugins: Plugin[];
+    connections: Connection[];
+    variant: {
+        scope: string | null;
+        pinned: string | null;
+        latest: string | null;
+        writable: boolean;
+    };
+    hub: HubOverview | null;
+}
+export interface BrowserRuntime {
+    skills: {
+        name: string;
+        description: string;
+        filePath: string;
+    }[];
+    tools: {
+        name: string;
+        description: string;
+        parameters?: unknown;
+        sourceInfo?: {
+            path: string;
+            source: string;
+        };
+    }[];
+    activeTools: string[];
+    skillCommands: boolean;
+}
+/** Saved configuration never establishes what the current runtime has loaded. */
+export declare function browserItems(snapshot: BrowserSnapshot, runtime: BrowserRuntime): BrowserItem[];
+export declare function catalogSection(entry: NonNullable<BrowserSnapshot['hub']>['entries'][number]): BrowserSection;

package/dist/sdk/terminal/browser.js

@@ -0,0 +1,41 @@
+export const BROWSER_SECTIONS = ['overview', 'foundation', 'variant', 'skills', 'plugins', 'connections', 'tools', 'library'];
+export const BROWSER_COMMANDS = new Set(['harness', 'skills', 'plugins', 'connections', 'mcp', 'tools', 'hub', 'components']);
+/** Saved configuration never establishes what the current runtime has loaded. */
+export function browserItems(snapshot, runtime) {
+    const items = snapshot.items.map(item => ({ ...item }));
+    for (const skill of runtime.skills) {
+        const existing = items.find(item => item.section === 'skills' && item.path === skill.filePath);
+        if (existing)
+            Object.assign(existing, { available: true, skillName: skill.name, status: 'Available now' });
+        else
+            items.push({ id: `runtime:skill:${skill.filePath}`, section: 'skills', name: skill.name, description: skill.description,
+                owner: 'Session resource loader', origin: 'Loaded resource', status: 'Available now', available: true, skillName: skill.name, path: skill.filePath });
+    }
+    const active = new Set(runtime.activeTools);
+    for (const tool of runtime.tools) {
+        const candidates = items.filter(item => item.section === 'tools' && item.name === tool.name);
+        const sourcePath = tool.sourceInfo?.path.replaceAll('\\', '/');
+        const owner = sourcePath ? snapshot.plugins.filter(plugin => {
+            const path = plugin.path?.replaceAll('\\', '/');
+            return path && (sourcePath === path || sourcePath.startsWith(path + '/'));
+        }).sort((a, b) => (b.path?.length ?? 0) - (a.path?.length ?? 0))[0] : undefined;
+        const builtin = sourcePath?.startsWith('builtin:') ? candidates.filter(item => item.origin === 'builtin' || item.origin === 'pi') : [];
+        const existing = owner ? candidates.find(item => item.pluginId === owner.id) : builtin.length === 1 ? builtin[0] : candidates.length === 1 ? candidates[0] : undefined;
+        const state = { available: active.has(tool.name), status: active.has(tool.name) ? 'Available now' : 'Not active here', parameters: tool.parameters };
+        if (existing)
+            Object.assign(existing, state, { description: tool.description || existing.description });
+        else
+            items.push({ id: `runtime:tool:${tool.name}`, section: 'tools', name: tool.name, description: tool.description,
+                owner: 'Runtime (unattributed)', origin: tool.sourceInfo?.source ?? 'Session', path: tool.sourceInfo?.path, ...state });
+    }
+    return items.sort((a, b) => Number(Boolean(b.available)) - Number(Boolean(a.available)) || a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+}
+export function catalogSection(entry) {
+    if (entry.delivery.kind === 'registry')
+        return entry.delivery.registryKind === 'skills' ? 'skills' : 'library';
+    if (entry.category === 'connector')
+        return 'connections';
+    if (entry.delivery.kind === 'pi-package')
+        return 'plugins';
+    return 'library';
+}

package/dist/sdk/terminal/browserControl.d.ts

@@ -0,0 +1,29 @@
+import * as path from 'node:path';
+import type { Hub } from "../hub/hub.js";
+import type { ConnectedApps } from "../mcp/service.js";
+import type { Plugin } from "../plugins/types.js";
+import type { Materialised } from "../variant/materialise.js";
+import type { BrowserSnapshot } from "./browser.js";
+type PathApi = Pick<typeof path, 'relative' | 'sep' | 'isAbsolute'>;
+export declare function isWithinBoundary(boundary: string, file: string, pathApi?: PathApi): boolean;
+export interface BrowserControlOptions {
+    root: string;
+    cwd: string;
+    pinned: Materialised | null;
+    writable: boolean;
+    plugins(): Promise<Plugin[]>;
+    hub?: Hub;
+    apps: ConnectedApps;
+}
+/** Only the protected terminal control route calls this adapter. It never loads discovered code. */
+export declare class BrowserControl {
+    private readonly options;
+    constructor(options: BrowserControlOptions);
+    snapshot(refresh?: boolean): Promise<BrowserSnapshot>;
+    read(id: string, latestVersion?: boolean): Promise<{
+        content: string;
+    }>;
+    importSkill(input: string): void;
+    connection(action: string, params: Record<string, unknown>): Promise<unknown>;
+}
+export {};