@xingular/harness 1.2.0 → 1.3.1-unstable.1

package/dist/sdk/annotations/store.js

@@ -160,6 +160,23 @@ function validNote(note, id) {
     if (!note || note.id !== id || note.author !== 'user' || !Number.isSafeInteger(note.version) || note.version < 1 || !Array.isArray(note.grants) || !Array.isArray(note.history)) {
         throw new HarnessError('invalid_data', `Note ${id} is not a valid note.`);
     }
+    return upgradeDelivery(note);
+}
+/** Notes written before PROP-0048 had a queue and a "fixed" claim: read them as pending or sent. */
+function upgradeDelivery(note) {
+    const delivery = note.delivery;
+    if (!delivery)
+        return note;
+    if (delivery.state === 'queued')
+        delivery.state = 'pending';
+    else if (delivery.state === 'fixed') {
+        delivery.state = 'sent';
+        delivery.sentAt ??= delivery.fixedAt;
+    }
+    delete delivery.fixedAt;
+    delete delivery.summary;
+    if (delivery.state !== 'pending' && delivery.state !== 'sent')
+        note.delivery = null;
     return note;
 }
 export function read(root, id) {
@@ -240,7 +257,7 @@ export function update(root, id, expectedVersion, patch) {
         if (patch.status !== 'open' && patch.status !== 'resolved')
             throw invalid('A note is open or resolved.');
         note.status = patch.status;
-        if (patch.status === 'resolved' && note.delivery?.state === 'queued')
+        if (patch.status === 'resolved' && note.delivery?.state === 'pending')
             note.delivery = null;
     }
     if (patch.target !== undefined)
@@ -263,6 +280,9 @@ export function unshare(root, id, principal) {
     const who = validatePrincipal(principal);
     const note = current(root, id, undefined);
     note.grants = note.grants.filter((grant) => !samePrincipal(grant.principal, who));
+    // A session that may no longer read the note is not sent it either.
+    if (note.delivery?.state === 'pending' && who.sessionId && note.delivery.sessionId === who.sessionId)
+        note.delivery = null;
     return save(root, note, 'unshare');
 }
 /** The host withdrew what a binding stood for (a tab closed or was shared again): every grant made with it ends. */
@@ -320,45 +340,48 @@ export function importNotes(root, notes) {
     }
     return { imported, skipped };
 }
-// ---- Delivery to an agent (PROP-0018) ----------------------------------------------------------
+// ---- Delivery to a session (PROP-0048) ----------------------------------------------------------
 /**
- * A person asks a session to act on the note: it is shared with that session (if it was not) and
- * waits in the session's queue until it is sent.
+ * The note is shared with the session and waits there, unsent, until the person sends it. Calling it
+ * again keeps the original time, so the send order stays the order the notes were made.
  */
-export function queue(root, id, expectedVersion, sessionId, options = {}) {
+export function markPending(root, id, expectedVersion, sessionId, options = {}) {
     const session = safeId(sessionId);
     const note = current(root, id, expectedVersion);
     if (note.status === 'resolved')
-        throw invalid('Reopen this note before queueing it.');
+        throw invalid('Reopen this note before sending it.');
     if (!note.grants.some((grant) => grant.principal.sessionId === session))
         note.grants.push({ principal: { sessionId: session }, grantedAt: now() });
-    const confirmationRequired = options.confirm === true || (note.delivery?.confirm === true && options.confirmed !== true);
+    const previous = note.delivery?.state === 'pending' && note.delivery.sessionId === session ? note.delivery : null;
+    const confirmationRequired = options.confirm === true || (previous?.confirm === true && options.confirmed !== true);
     note.delivery = {
-        state: 'queued',
+        state: 'pending',
         sessionId: session,
-        queuedAt: now(),
-        ...(options.autoSend ? { autoSend: true } : {}),
+        queuedAt: previous?.queuedAt ?? now(),
+        ...(options.autoSend || previous?.autoSend ? { autoSend: true } : {}),
         ...(confirmationRequired ? { confirm: true } : {})
     };
-    return save(root, note, 'queue');
-}
-/** Takes the note out of the queue. It stays shared; unshare withdraws that. */
-export function dequeue(root, id, expectedVersion) {
-    const note = current(root, id, expectedVersion);
-    if (note.delivery?.state !== 'queued')
-        throw invalid('This note is not waiting to be sent.');
-    note.delivery = null;
-    return save(root, note, 'dequeue');
+    return save(root, note, 'pending');
 }
-/** The notes waiting for one session, oldest first. `auto` keeps only those to send when it is idle. */
-export function queued(root, sessionId, filter = {}) {
+/** The unsent notes of one session, oldest first. `auto` keeps only those to send when it is idle. */
+export function pending(root, sessionId, filter = {}) {
     const ids = filter.ids ? new Set(filter.ids) : null;
     return all(root)
-        .filter((note) => note.status === 'open' && note.delivery?.state === 'queued' && note.delivery.sessionId === sessionId)
+        .filter((note) => note.status === 'open' && note.delivery?.state === 'pending' && note.delivery.sessionId === sessionId)
         .filter((note) => !filter.auto || (note.delivery?.autoSend === true && note.delivery.confirm !== true))
         .filter((note) => !ids || ids.has(note.id))
         .sort((left, right) => (left.delivery.queuedAt).localeCompare(right.delivery.queuedAt) || left.id.localeCompare(right.id));
 }
+/** `/annotate:clear`: the session's unsent notes are resolved and no longer shared with it. They can be reopened. */
+export function clearPending(root, sessionId) {
+    const session = safeId(sessionId);
+    return pending(root, session).map((note) => {
+        note.status = 'resolved';
+        note.delivery = null;
+        note.grants = note.grants.filter((grant) => grant.principal.sessionId !== session);
+        return save(root, note, 'clear');
+    });
+}
 /** The notes went to the session as part of `runId`. */
 export function markSent(root, ids, sessionId, runId) {
     const session = safeId(sessionId);
@@ -367,8 +390,8 @@ export function markSent(root, ids, sessionId, runId) {
     for (const note of notes) {
         if (note.status !== 'open')
             throw invalid('Resolved notes cannot be sent.');
-        if (note.delivery?.state !== 'queued' || note.delivery.sessionId !== session)
-            throw invalid('This note is not queued for this session.');
+        if (note.delivery?.state !== 'pending' || note.delivery.sessionId !== session)
+            throw invalid('This note is not waiting to be sent to this session.');
         if (note.delivery.confirm)
             throw invalid('Confirm this note before sending it.');
     }
@@ -379,16 +402,3 @@ export function markSent(root, ids, sessionId, runId) {
         return save(root, note, 'deliver');
     });
 }
-/** The agent says it acted on a note shared with it. The note stays open until a person resolves it. */
-export function markFixed(root, id, caller, summary) {
-    const note = current(root, id, undefined);
-    if (!visibleTo(note, caller))
-        throw notFound('Note');
-    const sessionId = note.delivery?.sessionId ?? caller.sessionId ?? note.grants.find((grant) => grant.principal.sessionId)?.principal.sessionId;
-    if (!sessionId)
-        throw invalid('This note was never sent to a session.');
-    note.delivery = { ...(note.delivery ?? { queuedAt: now() }), state: 'fixed', sessionId, fixedAt: now(), summary: bounded(summary.trim(), 2000, true, 'summary') };
-    delete note.delivery.autoSend;
-    delete note.delivery.confirm;
-    return save(root, note, 'mark_fixed');
-}

package/dist/sdk/capabilities/runSnapshot.js

@@ -6,11 +6,16 @@ const path = (root, runId) => join(root, 'runs', safeId(runId), 'capabilities.js
 function strings(value) {
     return Array.isArray(value) ? [...new Set(value.filter((item) => typeof item === 'string' && item.length > 0))] : [];
 }
+/** Tool names that were renamed; a pinned run keeps the current name so a continuation can use it. */
+const RENAMED_TOOLS = { checklist_write: 'todo_write' };
+function tools(value) {
+    return [...new Set(strings(value).map((name) => RENAMED_TOOLS[name] ?? name))];
+}
 export function capabilitySet(value) {
     if (!value || typeof value !== 'object' || value.version !== 1)
         throw invalid('A capability set must use version 1.');
     const record = value;
-    return { version: 1, tools: strings(record.tools), connectors: strings(record.connectors), contributions: strings(record.contributions) };
+    return { version: 1, tools: tools(record.tools), connectors: strings(record.connectors), contributions: strings(record.contributions) };
 }
 /** Writes a run's capability set once. A resumed or duplicate launch cannot replace it. */
 export function freezeRun(root, runId, caller, set) {
@@ -18,11 +23,12 @@ export function freezeRun(root, runId, caller, set) {
     const snapshot = {
         version: 1,
         caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null },
-        tools: strings(set.tools),
+        tools: tools(set.tools),
         connectors: strings(set.connectors),
         contributions: strings(set.contributions)
     };
-    const existing = existsSync(target) ? readJson(target) : null;
+    const stored = existsSync(target) ? readJson(target) : null;
+    const existing = stored ? { ...stored, tools: tools(stored.tools) } : null;
     if (existing) {
         if (JSON.stringify(existing) !== JSON.stringify(snapshot))
             throw new HarnessError('capabilities_frozen', 'This run already has a different frozen capability set.');
@@ -40,7 +46,7 @@ export function loadRun(root, runId) {
     return {
         version: 1,
         caller: { agentId: typeof caller.agentId === 'string' ? caller.agentId : null, projectId: typeof caller.projectId === 'string' ? caller.projectId : null },
-        tools: strings(record.tools),
+        tools: tools(record.tools),
         connectors: strings(record.connectors),
         contributions: strings(record.contributions)
     };

package/dist/sdk/commands/list.js

@@ -22,6 +22,8 @@ export function listCommands(plugins) {
         aliases.forEach((alias) => taken.add(alias));
     }
     for (const command of BUILTIN_PLUGIN_REGISTRY.commands()) {
+        if (command.rootOnly)
+            continue;
         const name = `${command.prefix}:${command.name}`;
         out.set(name, { name, description: command.description, group: 'Plugins', source: 'plugin', owner: command.pluginId });
     }

package/dist/sdk/commands/registry.d.ts

@@ -121,6 +121,13 @@ export declare const CORE_COMMANDS: readonly [{
     readonly group: "Inspect";
     readonly kind: "session";
     readonly methods: readonly ["sessions.export", "sessions.run"];
+}, {
+    readonly name: "todo";
+    readonly aliases: readonly ["checklist"];
+    readonly description: "Show the current todo list";
+    readonly group: "Inspect";
+    readonly kind: "session";
+    readonly methods: readonly ["runs.todo"];
 }, {
     readonly name: "trajectory";
     readonly args: "[run-id]";
@@ -173,15 +180,16 @@ export declare const CORE_COMMANDS: readonly [{
     readonly kind: "page";
 }, {
     readonly name: "plugins";
-    readonly description: "Switch plugins on or off and trust their code";
+    readonly description: "Manage local plugins, packages, trust and settings";
     readonly group: "Harness";
     readonly kind: "page";
-    readonly methods: readonly ["plugins.inventory"];
+    readonly methods: readonly ["plugins.list", "plugins.attach", "plugins.detach", "plugins.trust", "plugins.untrust", "plugins.configure", "plugins.install", "plugins.update", "plugins.remove", "hub.list"];
 }, {
     readonly name: "hub";
-    readonly description: "Browse and install reviewed skills, plugins and documents";
+    readonly description: "Browse the Community catalog and manage Hub installs";
     readonly group: "Harness";
     readonly kind: "page";
+    readonly methods: readonly ["hub.list", "hub.install", "hub.uninstall"];
 }, {
     readonly name: "components";
     readonly description: "Browse skills, prompts and rules for this Harness scope";

package/dist/sdk/commands/registry.js

@@ -18,6 +18,7 @@ export const CORE_COMMANDS = [
     { name: 'compact', args: '[instructions]', description: 'Compact the context', group: 'Session', kind: 'session', methods: ['sessions.run'] },
     { name: 'copy', description: 'Copy the last reply', group: 'Inspect', kind: 'local', methods: ['sessions.lastReply'] },
     { name: 'export', args: '[path.html|path.jsonl]', description: 'Export this branch to HTML or JSONL', group: 'Inspect', kind: 'session', methods: ['sessions.export', 'sessions.run'] },
+    { name: 'todo', aliases: ['checklist'], description: 'Show the current todo list', group: 'Inspect', kind: 'session', methods: ['runs.todo'] },
     { name: 'trajectory', args: '[run-id]', description: 'Inspect recorded runs for this session', group: 'Inspect', kind: 'page', methods: ['runs.list', 'runs.events'] },
     { name: 'reload', description: 'Reload trusted resources and keybindings', group: 'Harness', kind: 'session', methods: ['sessions.reload'] },
     { name: 'accounts', description: 'Sign in, switch, check and remove Pi accounts', group: 'Harness', kind: 'page', methods: ['accounts.list'] },
@@ -27,8 +28,8 @@ export const CORE_COMMANDS = [
     { name: 'connections', description: 'Manage local and remote MCP connections', group: 'Harness', kind: 'page' },
     { name: 'mcp', description: 'Open Connections in the Harness browser', group: 'Harness', kind: 'page' },
     { name: 'tools', description: 'Inspect available tools, owners and approvals', group: 'Harness', kind: 'page' },
-    { name: 'plugins', description: 'Switch plugins on or off and trust their code', group: 'Harness', kind: 'page', methods: ['plugins.inventory'] },
-    { name: 'hub', description: 'Browse and install reviewed skills, plugins and documents', group: 'Harness', kind: 'page' },
+    { name: 'plugins', description: 'Manage local plugins, packages, trust and settings', group: 'Harness', kind: 'page', methods: ['plugins.list', 'plugins.attach', 'plugins.detach', 'plugins.trust', 'plugins.untrust', 'plugins.configure', 'plugins.install', 'plugins.update', 'plugins.remove', 'hub.list'] },
+    { name: 'hub', description: 'Browse the Community catalog and manage Hub installs', group: 'Harness', kind: 'page', methods: ['hub.list', 'hub.install', 'hub.uninstall'] },
     { name: 'components', description: 'Browse skills, prompts and rules for this Harness scope', group: 'Harness', kind: 'page' },
     { name: 'settings', description: 'Session, terminal and browser settings', group: 'Harness', kind: 'page' },
     { name: 'doctor', description: 'Check account, model, tools and runtime readiness', group: 'Harness', kind: 'page', methods: ['doctor.start', 'doctor.read'] },

package/dist/sdk/core/links.d.ts

@@ -0,0 +1,51 @@
+/** What a link names, before anything touches the filesystem. */
+export type LinkTarget = {
+    kind: 'web';
+    url: string;
+} | {
+    kind: 'mail';
+    address: string;
+} | {
+    kind: 'path';
+    path: string;
+};
+/** What the operating system is asked to open, after the file it names was checked. */
+export type OpenedTarget = {
+    kind: 'web';
+    url: string;
+} | {
+    kind: 'mail';
+    address: string;
+} | {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'directory';
+    path: string;
+};
+/** Hands an opened target to the operating system. Replaced in tests, and by a host that has its own opener. */
+export type LinkOpener = (target: OpenedTarget) => Promise<void>;
+export interface LinkOpenCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * What a link names, or null when it names nothing a surface may open. Pure: a path is not
+ * checked against the filesystem here, so hover and rendering can classify without I/O.
+ */
+export declare function linkTarget(raw: string | null | undefined, options?: {
+    base?: string | null;
+}): LinkTarget | null;
+/** The target with its path checked, or the reason the operating system must not be asked. */
+export declare function openableTarget(target: LinkTarget): OpenedTarget;
+/** The address the operating system is given, and the argv that carries it without a shell. */
+export declare function linkOpenCommand(target: OpenedTarget, platform?: NodeJS.Platform): LinkOpenCommand;
+/** The default opener: the operating system's own handler for this kind of target. */
+export declare function openWithSystem(target: OpenedTarget): Promise<void>;
+/** Checks the target and opens it. Returns what was opened, for a caller that reports it. */
+export declare function openLink(target: LinkTarget, opener?: LinkOpener): Promise<OpenedTarget>;
+/** Classifies and opens in one step: the door a host calls for a link a person clicked. */
+export declare function openLinkTarget(raw: string, options?: {
+    base?: string | null;
+    opener?: LinkOpener;
+}): Promise<OpenedTarget>;

package/dist/sdk/core/links.js

@@ -0,0 +1,155 @@
+// What a link points at, and the one door that hands it to the operating system. Both front ends
+// classify with `linkTarget` and open through `openLink`, so a destination one surface accepts is
+// the destination the other accepts.
+import { spawn } from 'node:child_process';
+import { lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { HarnessError } from "./errors.js";
+const MAX_LENGTH = 4096;
+const CONTROL_CHARACTERS = /[\x00-\x1f\x7f-\x9f]/u;
+const WEB_ADDRESS = /^https?:/iu;
+const MAIL_ADDRESS = /^mailto:/iu;
+const FILE_ADDRESS = /^file:/iu;
+const SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
+const LINE_SUFFIX = /:\d+(?::\d+)?$/u;
+/** A folder the system would launch or install rather than show. */
+const BUNDLE = /\.(?:app|appex|bundle|framework|kext|plugin|prefpane|workflow|xpc)$/iu;
+/** A document whose default application runs it, so a click would execute rather than open. */
+const LAUNCHABLE = /\.(?:action|appimage|bat|cmd|command|desktop|dmg|exe|jar|lnk|mpkg|osax|pkg|ps1|scpt|sh|terminal|tool|url|vb|vbs|webloc|workflow)$/iu;
+const unopenable = (message) => new HarnessError('link_not_openable', message, 'Open the file from the project instead.');
+/**
+ * What a link names, or null when it names nothing a surface may open. Pure: a path is not
+ * checked against the filesystem here, so hover and rendering can classify without I/O.
+ */
+export function linkTarget(raw, options = {}) {
+    const value = raw?.trim();
+    if (!value || value.length > MAX_LENGTH || CONTROL_CHARACTERS.test(value) || value.startsWith('#'))
+        return null;
+    if (WEB_ADDRESS.test(value)) {
+        try {
+            const url = new URL(value);
+            if ((url.protocol !== 'http:' && url.protocol !== 'https:') || !url.hostname || url.username || url.password)
+                return null;
+            return { kind: 'web', url: url.href };
+        }
+        catch {
+            return null;
+        }
+    }
+    if (MAIL_ADDRESS.test(value)) {
+        const address = value.slice('mailto:'.length).split('?')[0].trim();
+        return address && address.includes('@') && !/\s/u.test(address) ? { kind: 'mail', address } : null;
+    }
+    const path = filePath(value, options.base);
+    return path ? { kind: 'path', path } : null;
+}
+function filePath(value, base) {
+    let raw = value;
+    if (FILE_ADDRESS.test(raw)) {
+        try {
+            const url = new URL(raw);
+            if (url.hostname && url.hostname !== 'localhost')
+                return null;
+            raw = url.pathname;
+        }
+        catch {
+            return null;
+        }
+    }
+    const address = raw.split('#')[0].split('?')[0].replace(LINE_SUFFIX, '');
+    let decoded;
+    try {
+        decoded = decodeURIComponent(address);
+    }
+    catch {
+        return null;
+    }
+    if (!decoded || decoded.includes('\0') || decoded.startsWith('~') || decoded.startsWith('//'))
+        return null;
+    if (isAbsolute(decoded))
+        return decoded;
+    if (SCHEME.test(decoded))
+        return null;
+    if (!base || !isAbsolute(base))
+        return null;
+    return resolve(base, decoded);
+}
+/** The target with its path checked, or the reason the operating system must not be asked. */
+export function openableTarget(target) {
+    if (target.kind !== 'path')
+        return target;
+    let stats = statsOf(target.path);
+    let path = target.path;
+    if (stats.isSymbolicLink()) {
+        try {
+            path = realpathSync(target.path);
+        }
+        catch {
+            throw unopenable('That link points at a file that is not there.');
+        }
+        stats = statsOf(path);
+    }
+    if (stats.isDirectory()) {
+        if (BUNDLE.test(path))
+            throw unopenable('That link points at an application, not a document.');
+        return { kind: 'directory', path };
+    }
+    if (!stats.isFile())
+        throw unopenable('That link does not point at a file or a folder.');
+    if (LAUNCHABLE.test(path))
+        throw unopenable('That kind of file runs when it is opened, so a link cannot open it.');
+    if ((stats.mode & 0o111) !== 0)
+        throw unopenable('That file is executable, so a link cannot open it.');
+    return { kind: 'file', path };
+}
+function statsOf(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        throw unopenable('That link points at a file that is not there.');
+    }
+}
+/** The address the operating system is given, and the argv that carries it without a shell. */
+export function linkOpenCommand(target, platform = process.platform) {
+    const address = target.kind === 'web' ? target.url : target.kind === 'mail' ? `mailto:${target.address}` : target.path;
+    if (platform === 'darwin')
+        return { command: 'open', args: [address] };
+    if (platform === 'win32')
+        return { command: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', address] };
+    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd')
+        return { command: 'xdg-open', args: [address] };
+    throw unopenable(`Opening links is not supported on ${platform}.`);
+}
+/** The default opener: the operating system's own handler for this kind of target. */
+export async function openWithSystem(target) {
+    const { command, args } = linkOpenCommand(target);
+    await new Promise((done, fail) => {
+        let child;
+        try {
+            child = spawn(command, args, { detached: process.platform !== 'win32', stdio: 'ignore', windowsHide: true });
+        }
+        catch (error) {
+            fail(error);
+            return;
+        }
+        child.once('error', fail);
+        child.once('spawn', () => {
+            child.unref();
+            done();
+        });
+    });
+}
+/** Checks the target and opens it. Returns what was opened, for a caller that reports it. */
+export async function openLink(target, opener = openWithSystem) {
+    const opened = openableTarget(target);
+    await opener(opened);
+    return opened;
+}
+/** Classifies and opens in one step: the door a host calls for a link a person clicked. */
+export async function openLinkTarget(raw, options = {}) {
+    const target = linkTarget(raw, { base: options.base });
+    if (!target)
+        throw unopenable('This link cannot be opened here.');
+    return openLink(target, options.opener);
+}

package/dist/sdk/core/shell.d.ts

@@ -0,0 +1,20 @@
+export type ShellKind = 'bash' | 'powershell';
+export interface Shell {
+    kind: ShellKind;
+    executable: string;
+    /** Arguments placed before the command text. */
+    args: readonly string[];
+}
+export interface ShellLookup {
+    env?: NodeJS.ProcessEnv;
+    /** Whether a file exists at an absolute path. */
+    exists?: (path: string) => boolean;
+    /** The first match for an executable name on the search path. */
+    onPath?: (name: string) => string | null;
+}
+/** The shell for this machine, resolved once. Null when none was found. */
+export declare function hostShell(): Shell | null;
+export declare function resolveShell(platform: NodeJS.Platform, lookup?: ShellLookup): Shell | null;
+/** The full argument list that runs `command` in `shell`. */
+export declare function shellArguments(shell: Shell, command: string): string[];
+export declare function shellLabel(shell: Shell): string;

package/dist/sdk/core/shell.js

@@ -0,0 +1,73 @@
+// The shell the Bash tool runs commands in. POSIX systems use Bash. Windows uses Git Bash when it
+// is installed and PowerShell otherwise, so a fresh machine can run commands with nothing extra.
+import { accessSync, constants, statSync } from 'node:fs';
+import { win32 } from 'node:path';
+import { findBinary } from "./path.js";
+const POWERSHELL_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command'];
+// Windows PowerShell writes the console code page by default; ask for UTF-8 like Pi does.
+const POWERSHELL_UTF8 = 'try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\n';
+let cached;
+/** The shell for this machine, resolved once. Null when none was found. */
+export function hostShell() {
+    if (cached === undefined)
+        cached = resolveShell(process.platform);
+    return cached;
+}
+export function resolveShell(platform, lookup = {}) {
+    const env = lookup.env ?? process.env;
+    const exists = lookup.exists ?? isFile;
+    const onPath = lookup.onPath ?? findBinary;
+    if (platform !== 'win32') {
+        const executable = ['/bin/bash', '/usr/bin/bash'].find((candidate) => exists(candidate));
+        return executable ? { kind: 'bash', executable, args: ['-c'] } : null;
+    }
+    const gitBash = [env.ProgramFiles, env['ProgramFiles(x86)']]
+        .filter((folder) => Boolean(folder))
+        .map((folder) => win32.join(folder, 'Git', 'bin', 'bash.exe'))
+        .find((candidate) => exists(candidate));
+    if (gitBash)
+        return { kind: 'bash', executable: gitBash, args: ['-c'] };
+    const bashOnPath = onPath('bash.exe');
+    if (bashOnPath && !isWslLauncher(bashOnPath, env))
+        return { kind: 'bash', executable: bashOnPath, args: ['-c'] };
+    const existing = (folder, ...parts) => {
+        if (!folder)
+            return null;
+        const candidate = win32.join(folder, ...parts);
+        return exists(candidate) ? candidate : null;
+    };
+    // PowerShell 7 first; Windows PowerShell ships with every supported Windows version.
+    const powershell = onPath('pwsh.exe')
+        ?? existing(env.ProgramFiles, 'PowerShell', '7', 'pwsh.exe')
+        ?? onPath('powershell.exe')
+        ?? existing(env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    return powershell ? { kind: 'powershell', executable: powershell, args: POWERSHELL_ARGS } : null;
+}
+/** The full argument list that runs `command` in `shell`. */
+export function shellArguments(shell, command) {
+    return [...shell.args, shell.kind === 'powershell' ? `${POWERSHELL_UTF8}${command}` : command];
+}
+export function shellLabel(shell) {
+    if (shell.kind === 'powershell')
+        return 'PowerShell';
+    return /\\git\\/iu.test(shell.executable) ? 'Git Bash' : 'Bash';
+}
+// System32\bash.exe starts WSL, a separate Linux system that does not see Windows paths the same
+// way and needs its command on stdin. It is not a usable Bash for this tool.
+function isWslLauncher(path, env) {
+    const normalized = win32.normalize(path).toLowerCase();
+    const systemRoot = env.SystemRoot;
+    if (systemRoot) {
+        return ['System32', 'Sysnative'].some((folder) => normalized === win32.join(systemRoot, folder, 'bash.exe').toLowerCase());
+    }
+    return /^[a-z]:\\windows\\(?:system32|sysnative)\\bash\.exe$/u.test(normalized);
+}
+function isFile(path) {
+    try {
+        accessSync(path, constants.F_OK);
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/sdk/core/workspaceBashTool.d.ts

@@ -1,4 +1,20 @@
+import type { BashOperations } from '@earendil-works/pi-coding-agent';
+import { type Shell } from "./shell.js";
 /** Quotes command text and escapes terminal control/format characters for approval details. */
 export declare function formatBashCommandForApproval(command: string): string;
+interface ShellToolFactories<T> {
+    createBashTool: (cwd: string, options: {
+        operations: BashOperations;
+    }) => T;
+    createPowerShellTool: (cwd: string, options: {
+        operations: BashOperations;
+    }) => T;
+}
+/**
+ * The `bash` tool for this machine. The capability keeps the name `bash` on every platform; on a
+ * Windows machine without Git Bash it runs PowerShell and carries PowerShell's description.
+ */
+export declare function createWorkspaceShellTool<T>(pi: ShellToolFactories<T>, cwd: string, operations: BashOperations, shell?: Shell | null, platform?: NodeJS.Platform): T;
 /** Adds the explicit pre-execution escape request to Pi's native Bash tool. */
-export declare function withWorkspaceWriteScope<T>(tool: T): T;
+export declare function withWorkspaceWriteScope<T>(tool: T, note?: string): T;
+export {};

package/dist/sdk/core/workspaceBashTool.js

@@ -1,17 +1,31 @@
 import { Type } from 'typebox';
 import { COMMAND_TIMEOUT_CEILING_SECONDS, COMMAND_TIMEOUT_MAX_SECONDS, DEFAULT_COMMAND_TIMEOUT_SECONDS, resolveCommandTimeout } from "./commandBudget.js";
+import { hostShell, shellLabel } from "./shell.js";
 import { runWithWorkspaceWriteScope } from "./workspaceSandbox.js";
 /** Quotes command text and escapes terminal control/format characters for approval details. */
 export function formatBashCommandForApproval(command) {
     return JSON.stringify(command).replace(/[\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff]/gu, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
 }
+/**
+ * The `bash` tool for this machine. The capability keeps the name `bash` on every platform; on a
+ * Windows machine without Git Bash it runs PowerShell and carries PowerShell's description.
+ */
+export function createWorkspaceShellTool(pi, cwd, operations, shell = hostShell(), platform = process.platform) {
+    const native = shell?.kind === 'powershell'
+        ? { ...pi.createPowerShellTool(cwd, { operations }), name: 'bash' }
+        : pi.createBashTool(cwd, { operations });
+    const note = platform === 'win32' && shell
+        ? ` On this machine commands run in ${shellLabel(shell)}. Windows has no workspace sandbox, so each command asks for approval unless Full Permission is on, and plan mode cannot run commands.`
+        : '';
+    return withWorkspaceWriteScope(native, note);
+}
 /** Adds the explicit pre-execution escape request to Pi's native Bash tool. */
-export function withWorkspaceWriteScope(tool) {
+export function withWorkspaceWriteScope(tool, note = '') {
     const native = tool;
     const execute = native.execute.bind(tool);
     return {
         ...tool,
-        description: `${native.description} Workspace writes are the default. Set workspaceWriteScope to "outside" to request approval before broader writes. Commands run for ${DEFAULT_COMMAND_TIMEOUT_SECONDS} seconds unless timeout says otherwise; above ${COMMAND_TIMEOUT_CEILING_SECONDS} seconds a reason is required, and ${COMMAND_TIMEOUT_MAX_SECONDS} seconds is the maximum.`,
+        description: `${native.description}${note} Workspace writes are the default. Set workspaceWriteScope to "outside" to request approval before broader writes. Commands run for ${DEFAULT_COMMAND_TIMEOUT_SECONDS} seconds unless timeout says otherwise; above ${COMMAND_TIMEOUT_CEILING_SECONDS} seconds a reason is required, and ${COMMAND_TIMEOUT_MAX_SECONDS} seconds is the maximum.`,
         parameters: Type.Object({
             command: Type.String({ description: 'Shell command to execute' }),
             timeout: Type.Optional(Type.Number({ description: `Timeout in seconds (default ${DEFAULT_COMMAND_TIMEOUT_SECONDS})` })),

package/dist/sdk/core/workspaceSandbox.d.ts

@@ -1,4 +1,5 @@
 import type { BashOperations } from '@earendil-works/pi-coding-agent';
+import { type Shell } from "./shell.js";
 /** `read-only` (plan mode) permits no workspace writes, no network and no outside processes. */
 export type WorkspaceWriteScope = 'workspace' | 'outside' | 'read-only';
 export declare function runWithWorkspaceWriteScope<T>(scope: WorkspaceWriteScope, action: () => T): T;
@@ -21,11 +22,20 @@ export interface WorkspaceBashOptions {
     workspaceWriteScope?: () => WorkspaceWriteScope | undefined;
     /** Exposed for platform-specific tests; production uses the current operating system. */
     platform?: NodeJS.Platform;
+    /** Exposed for tests; production uses the machine's shell (`hostShell`). */
+    shell?: () => Shell | null;
 }
+/** Why a Windows command asks first: Windows has no write-boundary sandbox the harness can use. */
+export declare const WINDOWS_UNSANDBOXED_REASON = "Windows has no workspace write-boundary sandbox, so this command would run without one. It will not run until this one-call request is approved.";
 export interface WorkspaceSandboxCommand {
     executable: string;
     args: string[];
     marker: string;
 }
+/**
+ * The operating system's write-boundary sandbox for this platform, or null when it is not
+ * installed. Bash cannot run without it, so readiness diagnostics report it before a command runs.
+ */
+export declare function workspaceSandboxBackend(platform?: NodeJS.Platform): string | null;
 export declare function workspaceSandboxCommand(platform: NodeJS.Platform, workspaceRoot: string, cwd: string, command: string, additionalWriteRoots?: readonly string[], readOnlyTempRoot?: string | null): WorkspaceSandboxCommand;
 export declare function createWorkspaceBashOperations(workspaceRoot: string | (() => string | null), options?: WorkspaceBashOptions): BashOperations;