@xingular/harness 1.1.1 → 1.3.1-unstable.0

package/dist/sdk/core/interactiveProfile.js

@@ -0,0 +1,143 @@
+import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileSecretStore } from "../accounts/secrets.js";
+const fail = () => { throw new Error('Invalid interactive profile configuration.'); };
+const object = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return fail();
+    return value;
+};
+const keys = (value, expected) => {
+    if (Object.keys(value).length !== expected.length || expected.some(key => !Object.hasOwn(value, key)))
+        fail();
+};
+const absolute = (value) => {
+    if (typeof value !== 'string' || value.length > 4096 || value.includes('\0') || !isAbsolute(value))
+        return fail();
+    return value;
+};
+const identifier = (value) => {
+    if (typeof value !== 'string' || value.length > 128 || !/^[A-Za-z0-9_-]+$/.test(value))
+        return fail();
+    return value;
+};
+/** Strict, bounded, credential-free configuration. Unknown fields are errors, not ignored secrets. */
+export function validateInteractiveProfile(value) {
+    const record = object(value);
+    keys(record, ['version', 'dataRoot', 'stateDir', 'defaultVariantScope', 'secretBackend']);
+    if (record.version !== 1)
+        return fail();
+    const backend = object(record.secretBackend);
+    let secretBackend;
+    if (backend.kind === 'file') {
+        keys(backend, ['kind', 'path']);
+        secretBackend = { kind: 'file', path: absolute(backend.path) };
+    }
+    else if (backend.kind === 'host') {
+        keys(backend, ['kind', 'id']);
+        secretBackend = { kind: 'host', id: identifier(backend.id) };
+    }
+    else
+        return fail();
+    return {
+        version: 1,
+        dataRoot: absolute(record.dataRoot),
+        stateDir: absolute(record.stateDir),
+        defaultVariantScope: identifier(record.defaultVariantScope),
+        secretBackend
+    };
+}
+export function interactiveProfilePath(home = homedir()) {
+    return join(absolute(home), '.xingular-harness', 'profile.json');
+}
+function selectedConfigPath(location = {}) {
+    return location.configPath === undefined ? interactiveProfilePath(location.home) : absolute(location.configPath);
+}
+/** Read only. Missing is legacy mode; malformed or inaccessible is never silently ignored. */
+export function readInteractiveProfile(location = {}) {
+    const path = selectedConfigPath(location);
+    try {
+        const info = statSync(path);
+        if (!info.isFile() || info.size > 16_384)
+            return fail();
+        return validateInteractiveProfile(JSON.parse(readFileSync(path, 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        // Do not include JSON contents, paths, or backend details in diagnostics.
+        throw new Error('Interactive profile could not be read or validated.');
+    }
+}
+function overrides(value) {
+    if (value === undefined)
+        return {};
+    const record = object(value);
+    if (Object.keys(record).some(key => !['dataRoot', 'stateDir', 'defaultVariantScope', 'secretBackend'].includes(key)))
+        return fail();
+    return record;
+}
+/** Explicit roots > selected profile > caller's legacy defaults. Never creates roots or merges data. */
+export function resolveInteractiveProfile(options = {}) {
+    const home = absolute(options.home ?? homedir());
+    const root = join(home, '.xingular-harness');
+    const selected = readInteractiveProfile(options);
+    const legacy = overrides(options.legacyDefaults);
+    const explicit = overrides(options.overrides);
+    const dataRoot = explicit.dataRoot ?? selected?.dataRoot ?? legacy.dataRoot ?? join(root, 'data');
+    const stateDir = explicit.stateDir ?? selected?.stateDir ?? legacy.stateDir ?? join(root, 'state');
+    const defaultVariantScope = explicit.defaultVariantScope ?? selected?.defaultVariantScope ?? legacy.defaultVariantScope ?? 'default';
+    const secretBackend = explicit.secretBackend ?? selected?.secretBackend ?? legacy.secretBackend ?? {
+        kind: 'file',
+        path: join(stateDir, 'secrets.json')
+    };
+    return validateInteractiveProfile({ version: 1, dataRoot, stateDir, defaultVariantScope, secretBackend });
+}
+/**
+ * Explicit adoption only. Creates the profile file, never roots or credentials; it never replaces
+ * an existing profile or merges data. A pre-profile host must supply its selected backend in
+ * `legacyDefaults` so an absent profile cannot silently downgrade it to the file store.
+ */
+export function adoptInteractiveProfile(profile, location = {}) {
+    const validated = validateInteractiveProfile(profile);
+    const path = selectedConfigPath(location);
+    const folder = dirname(path);
+    mkdirSync(folder, { recursive: true, mode: 0o700 });
+    const temporary = join(folder, `.profile-${randomUUID()}.tmp`);
+    try {
+        const fd = openSync(temporary, 'wx', 0o600);
+        try {
+            writeFileSync(fd, `${JSON.stringify(validated, null, 2)}\n`);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        linkSync(temporary, path);
+    }
+    catch {
+        throw new Error('Interactive profile adoption failed; existing configuration was not replaced.');
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/**
+ * Every participating process must map this host id to the same credential store. The account
+ * lock serializes access but cannot unify distinct native Keychain identities; no file fallback is
+ * allowed when a selected host adapter is unavailable.
+ */
+export async function interactiveProfileSecretStore(profile, host) {
+    const { secretBackend } = validateInteractiveProfile(profile);
+    if (secretBackend.kind === 'file')
+        return fileSecretStore(secretBackend.path);
+    if (!host)
+        throw new Error('The selected credential backend is unavailable; supply its host SecretStore adapter.');
+    const store = await host(secretBackend);
+    if (!store || !['get', 'set', 'delete'].every(key => typeof store[key] === 'function')) {
+        throw new Error('The selected credential backend did not provide a SecretStore.');
+    }
+    return store;
+}

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/workspace.d.ts

@@ -0,0 +1,13 @@
+/** The nearest Git repository containing `cwd`, or its canonical directory when there is none. */
+export declare function resolveWorkspaceRoot(cwd: string): string;
+/**
+ * Resolves a write target relative to `cwd` (the workspace root by default), and returns its
+ * canonical path only when the target stays inside the canonical workspace root.
+ */
+export declare function resolveWorkspaceWritePath(workspaceRoot: string, candidate: string, cwd?: string): string;
+/** Canonicalizes an absolute, relative, or home-relative write target without imposing a root. */
+export declare function resolveWritePath(candidate: string, cwd?: string): string;
+/** Whether a canonical target is within the workspace's canonical filesystem root. */
+export declare function isWithinWorkspace(workspaceRoot: string, canonicalCandidate: string): boolean;
+/** Revalidates a root pinned by an active run; a replaced or redirected root fails closed. */
+export declare function verifyWorkspaceRoot(workspaceRoot: string): string;

package/dist/sdk/core/workspace.js

@@ -0,0 +1,88 @@
+import { lstatSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { invalid } from "./errors.js";
+/** The nearest Git repository containing `cwd`, or its canonical directory when there is none. */
+export function resolveWorkspaceRoot(cwd) {
+    const canonicalCwd = realpathSync(cwd);
+    if (!statSync(canonicalCwd).isDirectory())
+        throw invalid('The working directory must be a directory.');
+    if (dirname(canonicalCwd) === canonicalCwd)
+        throw invalid('The filesystem root cannot be used as an active project workspace.');
+    let directory = canonicalCwd;
+    while (true) {
+        try {
+            const marker = lstatSync(resolve(directory, '.git'));
+            if (marker.isDirectory() || marker.isFile())
+                return directory;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return canonicalCwd;
+        directory = parent;
+    }
+}
+/**
+ * Resolves a write target relative to `cwd` (the workspace root by default), and returns its
+ * canonical path only when the target stays inside the canonical workspace root.
+ */
+export function resolveWorkspaceWritePath(workspaceRoot, candidate, cwd = workspaceRoot) {
+    const canonicalCandidate = resolveWritePath(candidate, cwd);
+    if (!isWithinWorkspace(workspaceRoot, canonicalCandidate))
+        throw invalid('Write target is outside the active project workspace.');
+    return canonicalCandidate;
+}
+/** Canonicalizes an absolute, relative, or home-relative write target without imposing a root. */
+export function resolveWritePath(candidate, cwd = process.cwd()) {
+    const expanded = candidate === '~'
+        ? homedir()
+        : candidate.startsWith('~/') || candidate.startsWith('~\\')
+            ? join(homedir(), candidate.slice(2))
+            : candidate;
+    const absoluteCandidate = isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
+    return canonicalizeTarget(absoluteCandidate);
+}
+/** Whether a canonical target is within the workspace's canonical filesystem root. */
+export function isWithinWorkspace(workspaceRoot, canonicalCandidate) {
+    const canonicalRoot = realpathSync(workspaceRoot);
+    if (!statSync(canonicalRoot).isDirectory())
+        throw invalid('The workspace root must be a directory.');
+    const fromRoot = relative(canonicalRoot, canonicalCandidate);
+    return fromRoot === '' || (fromRoot !== '..' && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot));
+}
+/** Revalidates a root pinned by an active run; a replaced or redirected root fails closed. */
+export function verifyWorkspaceRoot(workspaceRoot) {
+    const canonicalRoot = realpathSync(workspaceRoot);
+    if (dirname(canonicalRoot) === canonicalRoot)
+        throw invalid('The filesystem root cannot be used as an active project workspace.');
+    if (canonicalRoot !== resolve(workspaceRoot) || !statSync(canonicalRoot).isDirectory()) {
+        throw invalid('The active project workspace changed after this run began.');
+    }
+    return canonicalRoot;
+}
+function canonicalizeTarget(path) {
+    const missing = [];
+    let current = path;
+    while (true) {
+        let exists = false;
+        try {
+            lstatSync(current);
+            exists = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (exists)
+            return resolve(realpathSync(current), ...missing.reverse());
+        const parent = dirname(current);
+        if (parent === current)
+            throw invalid('Write target could not be resolved.');
+        missing.push(basename(current));
+        current = parent;
+    }
+}

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

@@ -0,0 +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, note?: string): T;
+export {};

package/dist/sdk/core/workspaceBashTool.js

@@ -0,0 +1,50 @@
+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, note = '') {
+    const native = tool;
+    const execute = native.execute.bind(tool);
+    return {
+        ...tool,
+        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})` })),
+            reason: Type.Optional(Type.String({ description: `Why a command needs more than ${COMMAND_TIMEOUT_CEILING_SECONDS} seconds` })),
+            workspaceWriteScope: Type.Optional(Type.Union([
+                Type.Literal('workspace'),
+                Type.Literal('outside')
+            ], { description: 'Write scope for this command. Defaults to workspace; outside requests approval before running.' }))
+        }),
+        execute: (...args) => {
+            const input = args[1];
+            const scope = input?.workspaceWriteScope === 'outside' ? 'outside' : 'workspace';
+            const budget = resolveCommandTimeout(input?.timeout, input?.reason);
+            if (!budget.ok)
+                return { content: [{ type: 'text', text: budget.message }], details: { refused: true } };
+            // The native tool reads the timeout from its own arguments; give it the effective one.
+            const callArgs = [...args];
+            callArgs[1] = { ...(input ?? {}), timeout: budget.timeout };
+            return runWithWorkspaceWriteScope(scope, () => execute(...callArgs));
+        }
+    };
+}

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

@@ -0,0 +1,41 @@
+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;
+export interface WorkspaceWriteScopeRequest {
+    command: string;
+    cwd: string;
+    workspaceRoot: string;
+    reason: string;
+}
+export interface WorkspaceBoundaryBypassRequest {
+    command: string;
+    cwd: string;
+    workspaceRoot: string;
+}
+export interface WorkspaceBashOptions {
+    /** The explicit Full Permission switch can bypass the workspace boundary before the command runs. */
+    bypassWorkspaceBoundary?: (request: WorkspaceBoundaryBypassRequest) => Promise<boolean>;
+    requestWorkspaceWriteScope?: (request: WorkspaceWriteScopeRequest) => Promise<boolean>;
+    /** Overrides the per-call scope; `undefined` falls back to it. */
+    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;