@naswerks/periscope 1.0.0

package/dist/host/token-cache.js

@@ -0,0 +1,185 @@
+/**
+ * The file-backed token cache: one of the two places this package writes credential material to
+ * disk (the other is the paired-credential store beside it).
+ *
+ * What 0600 is and is not, because the honest version is load-bearing here. The agent runs as the
+ * same OS user as this host. File permissions are not a boundary against a process running as the
+ * same user: an 0600 token file is readable by the agent exactly as it is by the host. What 0600
+ * buys is keeping other OS users out. What keeps the agent out is the gate's credential-path
+ * denial, and that denial covers this file because `credentialPaths` and `tokenCachePath` are
+ * derived from one function in `paths.ts`, not kept equal by hand.
+ *
+ * The exposure is a different kind, not a smaller amount of the same one. Compared with a shared
+ * secret that grants access as every user, what is stored here is one user's own token, expiring
+ * on its own and revocable from the identity provider without touching this machine.
+ *
+ * Enforcement is probed, not assumed. `node` on win32 accepts a mode and ignores it, and reports
+ * the same `0o666` for a deliberately world-readable file as for one written `0o600`, so a
+ * verify-after-write there is either always-refusing or always-vacuous. This measures which world
+ * it is in once, and `identity/mode.ts` turns the answer into a named outcome.
+ */
+import { chmodSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { ok, refuse } from '../core/result.js';
+import { CREDENTIAL_MODE, classifyCredentialMode, classifyProbeReadings } from '../identity/mode.js';
+import { readCachedTokens } from '../identity/store.js';
+/** Directories holding credential material are owner-only too. */
+const CREDENTIAL_DIR_MODE = 0o700;
+/**
+ * Measure what this filesystem does with a mode.
+ *
+ * Measured rather than listed by platform. A `process.platform === 'win32'` test is a guess that
+ * ages: WSL, a POSIX filesystem mounted under Windows, and a future runtime mapping modes onto ACLs
+ * would each make it wrong in the direction that matters. The probe writes a throwaway file BESIDE
+ * the cache — the same filesystem, which is the thing actually in question.
+ *
+ * It asserts its positive control before it reports the negative, and that ordering is the whole
+ * design. Three measurements, in this order:
+ *
+ *   1. Ask for `0600` and for `0666`. If they read back differently AND `0600` came back as `0600`,
+ *      POSIX modes are honoured. Done.
+ *   2. They did not differ — so privacy is unconfirmable. **Before saying so, prove the instrument
+ *      is alive**: clear the write bit with `0444`. Measured on win32, that DOES read back as
+ *      `444`, because the write bit is the one real bit there. If it changes, this is a genuine
+ *      finding about a filesystem that records only writability.
+ *   3. Even `0444` changed nothing. Then the probe cannot distinguish "this filesystem records
+ *      nothing" from "this probe is broken", and it says exactly that.
+ *
+ * Without step 2, "unenforced" and "the probe never worked" are the same answer — an instrument
+ * with no inconclusive state, which is how a dead check gets read as evidence.
+ *
+ * `0444` is the control, never the target. The cache must stay owner-writable; refreshes are
+ * written to it. The probe restores a writable mode on its own throwaway file before removing it,
+ * because a read-only file is one `rmSync` can fail on.
+ */
+export function probeModeEnforcement(directory) {
+    const probe = `${directory}/.mode-probe`;
+    const modeOf = () => statSync(probe).mode & 0o777;
+    try {
+        writeFileSync(probe, '', { mode: CREDENTIAL_MODE });
+        chmodSync(probe, CREDENTIAL_MODE);
+        const narrow = modeOf();
+        writeFileSync(probe, '', { mode: 0o666 });
+        chmodSync(probe, 0o666);
+        const wide = modeOf();
+        // The positive control. Taken before anything is concluded, not after.
+        chmodSync(probe, 0o444);
+        const readOnly = modeOf();
+        chmodSync(probe, 0o666);
+        // Taking the readings is this function's job; what they MEAN is `identity/mode.ts`'s, so the
+        // filesystem shapes this machine cannot produce on demand are still drivable in a test.
+        return classifyProbeReadings(narrow, wide, readOnly);
+    }
+    catch {
+        return 'unobservable';
+    }
+    finally {
+        try {
+            // Restore writability first: a read-only file is one removal can fail on, and a probe that
+            // leaves litter behind on the credential directory is its own small defect.
+            try {
+                chmodSync(probe, 0o666);
+            }
+            catch {
+                // Already gone, or never created.
+            }
+            rmSync(probe, { force: true });
+        }
+        catch {
+            // A probe file that could not be removed is untidy, never a reason to fail a sign-in.
+        }
+    }
+}
+export class FileTokenCache {
+    #path;
+    #directory;
+    #enforcement = null;
+    constructor(path) {
+        this.#path = path;
+        const cut = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+        this.#directory = cut > 0 ? path.slice(0, cut) : path;
+    }
+    get path() {
+        return this.#path;
+    }
+    /** Memoised: the filesystem does not change its mind mid-process. */
+    modeEnforcement() {
+        if (this.#enforcement === null) {
+            try {
+                mkdirSync(this.#directory, { recursive: true, mode: CREDENTIAL_DIR_MODE });
+            }
+            catch {
+                // The write path reports the real failure; a probe must not be the thing that raises it.
+            }
+            this.#enforcement = probeModeEnforcement(this.#directory);
+        }
+        return this.#enforcement;
+    }
+    /**
+     * Read the cache.
+     *
+     * A missing file is `token-unavailable` — nobody has signed in — and that is deliberately NOT the
+     * same reason as a file that exists and cannot be parsed, which is a real problem with a real
+     * fix. Collapsing them would make a corrupted cache look like a fresh install forever.
+     */
+    read() {
+        let raw;
+        try {
+            raw = readFileSync(this.#path, 'utf8');
+        }
+        catch {
+            return refuse('token-unavailable', 'no token cache exists on this host yet — sign in first');
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return refuse('credential-cache-unreadable', `the token cache at ${this.#path} exists and is not valid JSON; remove it and sign in again`);
+        }
+        return readCachedTokens(parsed);
+    }
+    /**
+     * Write the cache, then verify what actually landed.
+     *
+     * A file that came out wider than asked is removed, not left and reported. Leaving a
+     * world-readable token on disk while returning a refusal would mean the caller sees a failure and
+     * the credential is exposed anyway — the worst of both. No cache at all is strictly safer than a
+     * readable one, and the sign-in can simply be repeated.
+     */
+    write(cached) {
+        const enforcement = this.modeEnforcement();
+        try {
+            mkdirSync(this.#directory, { recursive: true, mode: CREDENTIAL_DIR_MODE });
+            writeFileSync(this.#path, `${JSON.stringify(cached, null, 2)}\n`, { mode: CREDENTIAL_MODE });
+            // `writeFileSync`'s mode applies only when it CREATES the file — an existing file keeps the
+            // mode it already had. Re-stating it is what makes an overwrite as private as a first write.
+            chmodSync(this.#path, CREDENTIAL_MODE);
+        }
+        catch (error) {
+            return refuse('credential-cache-write-failed', `the token cache could not be written to ${this.#path}: ${String(error)}`);
+        }
+        let observed;
+        try {
+            observed = statSync(this.#path).mode;
+        }
+        catch (error) {
+            return refuse('credential-cache-write-failed', `the token cache was written and could not be read back from ${this.#path}: ${String(error)}`);
+        }
+        const mode = classifyCredentialMode(observed, enforcement);
+        if (mode.kind === 'too-wide') {
+            this.clear();
+            return refuse(mode.refusal.reason, `${mode.refusal.detail}; the file has been removed rather than left readable`);
+        }
+        return ok({ path: this.#path, mode });
+    }
+    /** Remove the cache. Idempotent — clearing a cache that is not there is success, not an error. */
+    clear() {
+        try {
+            rmSync(this.#path, { force: true });
+        }
+        catch {
+            // Nothing here can act on the failure, and throwing would turn "sign out" into an error path.
+        }
+    }
+}
+//# sourceMappingURL=token-cache.js.map

package/dist/host/transcript-fs.d.ts

@@ -0,0 +1,4 @@
+import type { StoreEffects } from '../persistence/store.js';
+/** File-backed effects rooted at one directory. The root must be absolute. */
+export declare function nodeStoreEffects(root: string): StoreEffects;
+//# sourceMappingURL=transcript-fs.d.ts.map

package/dist/host/transcript-fs.js

@@ -0,0 +1,104 @@
+/**
+ * The local JSONL mirror: the store's effects, on a real disk.
+ *
+ * It lives here for the one reason everything else in this directory does: it names `node:fs`.
+ * The rules worth testing (which key becomes which record, what a missing transcript returns, what
+ * a corrupt line does) are in `persistence/store.ts` and are proven without a disk. This file is
+ * the part that cannot be, so it is small and it is the only place a path is built.
+ *
+ * The root is a jail, and the token is escaped before it gets here. A project key is
+ * caller-supplied and may contain anything, separators included; `transcriptToken` percent-encodes
+ * each segment so a key cannot introduce one. This checks containment anyway, because a jail that
+ * relies on its caller having escaped correctly is a jail with one lock on the outside.
+ */
+import { mkdir, readFile, readdir, rm, stat, appendFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { isContainedBy, normalizePath, requireAbsolute } from '../core/paths.js';
+/** File-backed effects rooted at one directory. The root must be absolute. */
+export function nodeStoreEffects(root) {
+    const absolute = requireAbsolute(root);
+    if (!absolute.ok) {
+        throw new Error(`the transcript root must be absolute: ${absolute.refusal.detail}`);
+    }
+    const rootPath = normalizePath(absolute.value);
+    const pathFor = (token) => {
+        const candidate = normalizePath(resolve(rootPath, `${token}.jsonl`));
+        if (!isContainedBy(candidate, rootPath)) {
+            // Unreachable through `transcriptToken`, which escapes every segment. Kept because the day it
+            // becomes reachable is the day somebody writes a second token function.
+            throw new Error(`refusing a transcript path outside the store root: ${token}`);
+        }
+        return candidate;
+    };
+    return {
+        async appendTo(token, text) {
+            const file = pathFor(token);
+            await mkdir(dirname(file), { recursive: true });
+            // A real append, not a read-modify-write: a transcript reaches megabytes and batches arrive
+            // throughout a turn, so rewriting per batch would cost the square of the session's length.
+            await appendFile(file, text, 'utf8');
+        },
+        async readAll(token) {
+            try {
+                return await readFile(pathFor(token), 'utf8');
+            }
+            catch (error) {
+                // A transcript that was never written is `null`, and that is distinct from a read that
+                // failed — the store contract turns the first into "nothing was ever stored" and must not
+                // be handed it for a permission error.
+                if (isMissing(error))
+                    return null;
+                throw error;
+            }
+        },
+        async list(projectKey) {
+            const scope = pathFor(encodeURIComponent(projectKey)).replace(/\.jsonl$/, '');
+            let names;
+            try {
+                names = await readdir(scope);
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return [];
+                throw error;
+            }
+            const found = [];
+            for (const name of names) {
+                if (!name.endsWith('.jsonl'))
+                    continue;
+                const encodedId = name.slice(0, -'.jsonl'.length);
+                const stats = await stat(join(scope, name));
+                found.push({
+                    token: `${encodeURIComponent(projectKey)}/${encodedId}`,
+                    sessionId: decodeURIComponent(encodedId),
+                    // Floored: the contract asks for integer epoch milliseconds and a fractional source here
+                    // would not compare equal to a summary's own stamp.
+                    mtime: Math.floor(stats.mtimeMs),
+                });
+            }
+            return found;
+        },
+        async remove(token) {
+            await rm(pathFor(token), { force: true });
+        },
+        async subkeys(projectKey, sessionId) {
+            // A session's subagent transcripts live under a directory named for the session, beside its
+            // own file. Absent means it never spawned one, which is not an error.
+            const scope = pathFor(`${encodeURIComponent(projectKey)}/${encodeURIComponent(sessionId)}`).replace(/\.jsonl$/, '');
+            try {
+                return (await readdir(scope))
+                    .filter((name) => name.endsWith('.jsonl'))
+                    .map((name) => decodeURIComponent(name.slice(0, -'.jsonl'.length)));
+            }
+            catch (error) {
+                if (isMissing(error))
+                    return [];
+                throw error;
+            }
+        },
+    };
+}
+function isMissing(error) {
+    return typeof error === 'object' && error !== null && error.code === 'ENOENT';
+}
+//# sourceMappingURL=transcript-fs.js.map

package/dist/host/wire-request.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The one place a controller's `session_new.request` becomes a local `SessionRequest`.
+ *
+ * Why it is a file and not four lines in the dispatcher: everything crossing here arrived from
+ * off-box and was validated only as JSON. The codec's job is to keep malformed bytes out, and it
+ * says so; an empty `cwd`, an empty `text` and a non-ISO `at` all pass it. So a value that is
+ * well-formed JSON and meaningless to the SDK reaches this line, and there are exactly two things to
+ * do with one: refuse it by name before a process exists, or hand it to `query()` and let the
+ * failure arrive later wearing a spawn error's clothes. This file is the first of those.
+ *
+ * What it narrows and what it deliberately does not, because the split is a judgement worth
+ * stating rather than a gap. It narrows every value with a closed set this package can see (the
+ * three setting sources, the plugin type, the thinking discriminator) because an unrecognised value
+ * there silently does nothing, which is the failure mode with no symptom. It does not re-validate
+ * the MCP server configs: that union is large, versioned with the SDK, and re-stating it here would
+ * be a second copy that can disagree with the first. Those are shape-checked and handed on, and the
+ * SDK is their validator.
+ *
+ * Nothing here can produce `sessionStore`, `sessionStoreFlush`, `spawn`, `onStderr` or `hooks`.
+ * They have no JSON form, so the wire type has no member for them and this file has nothing to read.
+ * That is the boundary, and it is structural rather than a check somebody remembered to write.
+ */
+import type { SessionNewRequest } from '../control/frames.js';
+import type { Result } from '../core/result.js';
+import type { SessionRequest } from '../sessions/registry.js';
+import type { McpServerConfig, PermissionMode, SettingSource, ThinkingConfig } from './agent-process.js';
+import type { SessionConfigure } from '../control/frames.js';
+/** What a controller may ask for, minus the two the composer supplies itself. */
+export type ComposableRequest = Omit<SessionRequest, 'cwd' | 'hooks'>;
+/**
+ * The three tiers the SDK understands, as data.
+ *
+ * Restated here rather than derived because the SDK ships them as a bare string union with no
+ * runtime value to read — so this is the one place a copy is unavoidable. `wire-request.test.ts`
+ * asserts each member against the shipped `sdk.d.ts`, the same way the permission pin does, so the
+ * copy cannot quietly drift from what it copies.
+ */
+export declare const SETTING_SOURCES: readonly SettingSource[];
+/** The thinking shapes the SDK declares, by discriminator. Same argument as above. */
+export declare const THINKING_TYPES: readonly string[];
+/** The SDK's effort levels, by name. An unknown level is refused, never dropped. */
+export declare const EFFORT_LEVELS: readonly string[];
+/** The SDK's permission modes, by name (protocol v6, CLI parity). */
+export declare const PERMISSION_MODES: readonly string[];
+/**
+ * The one mode under which a granting gate and loaded operator settings are NOT two authorities: the
+ * mode already allows everything the grant would, and a hook deny survives every mode. Named here, in
+ * the one module that holds the vocabulary, so nothing else has to spell the mode.
+ */
+export declare function isBypassMode(mode: string | null | undefined): boolean;
+/** What a `session_configure` frame asked for, narrowed to the SDK's own types. */
+export interface SessionConfigureChange {
+    readonly model?: string | null;
+    readonly permissionMode?: PermissionMode;
+    readonly thinking?: ThinkingConfig;
+}
+/**
+ * Narrow a `session_configure` payload. Same discipline as `readSessionRequest`: a value the SDK does
+ * not declare is REFUSED by name — a mode nobody recognises must never become "the default" silently.
+ */
+export declare function readSessionConfigure(payload: SessionConfigure): Result<SessionConfigureChange>;
+/**
+ * Turn a controller's request into a local one, or refuse it by name.
+ *
+ * `null` in means "every default", which is byte-for-byte the behaviour before this payload grew —
+ * so a controller that sends nothing new is unaffected by any of this.
+ */
+export declare function readSessionRequest(request: SessionNewRequest | null): Result<ComposableRequest>;
+/**
+ * Merge the controller's servers with the ones this host registers itself.
+ *
+ * A colliding name is refused rather than resolved, and either precedence would have been wrong.
+ * Letting the controller win lets a remote peer replace the host's OWN tool server — the one that
+ * carries the host's identity into every call — with something it supplies. Letting the host win
+ * silently discards a registration the controller believes it made, and its tools then simply do not
+ * exist, with nothing anywhere saying why. So the pair is refused, before any process exists, naming
+ * the server both sides claimed.
+ */
+export declare function mergeMcpServers(fromController: Readonly<Record<string, McpServerConfig>> | undefined, fromHost: Readonly<Record<string, McpServerConfig>> | null): Result<Readonly<Record<string, McpServerConfig>> | null>;
+//# sourceMappingURL=wire-request.d.ts.map

package/dist/host/wire-request.js

@@ -0,0 +1,196 @@
+import { ok, refuse } from '../core/result.js';
+/**
+ * The three tiers the SDK understands, as data.
+ *
+ * Restated here rather than derived because the SDK ships them as a bare string union with no
+ * runtime value to read — so this is the one place a copy is unavoidable. `wire-request.test.ts`
+ * asserts each member against the shipped `sdk.d.ts`, the same way the permission pin does, so the
+ * copy cannot quietly drift from what it copies.
+ */
+export const SETTING_SOURCES = ['user', 'project', 'local'];
+/** The thinking shapes the SDK declares, by discriminator. Same argument as above. */
+export const THINKING_TYPES = ['adaptive', 'enabled', 'disabled'];
+/** The SDK's effort levels, by name. An unknown level is refused, never dropped. */
+export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+/** The SDK's permission modes, by name (protocol v6, CLI parity). */
+export const PERMISSION_MODES = [
+    'default',
+    'acceptEdits',
+    'bypassPermissions',
+    'plan',
+    'dontAsk',
+    'auto',
+];
+/**
+ * The one mode under which a granting gate and loaded operator settings are NOT two authorities: the
+ * mode already allows everything the grant would, and a hook deny survives every mode. Named here, in
+ * the one module that holds the vocabulary, so nothing else has to spell the mode.
+ */
+export function isBypassMode(mode) {
+    return mode === PERMISSION_MODES[2];
+}
+/**
+ * Narrow a `session_configure` payload. Same discipline as `readSessionRequest`: a value the SDK does
+ * not declare is REFUSED by name — a mode nobody recognises must never become "the default" silently.
+ */
+export function readSessionConfigure(payload) {
+    const change = {};
+    if (payload.model !== null)
+        change.model = payload.model;
+    if (payload.permissionMode !== null) {
+        if (!PERMISSION_MODES.includes(payload.permissionMode)) {
+            return refuse('frame-malformed', `permissionMode is ${JSON.stringify(payload.permissionMode)}; the modes this SDK declares are ` +
+                `${PERMISSION_MODES.join(', ')}`);
+        }
+        change.permissionMode = payload.permissionMode;
+    }
+    if (payload.thinking !== null) {
+        const type = payload.thinking['type'];
+        if (typeof type !== 'string' || !THINKING_TYPES.includes(type)) {
+            return refuse('frame-malformed', `thinking.type is ${JSON.stringify(type)}; the shapes this SDK declares are ${THINKING_TYPES.join(', ')}`);
+        }
+        change.thinking = payload.thinking;
+    }
+    return ok(change);
+}
+/**
+ * Turn a controller's request into a local one, or refuse it by name.
+ *
+ * `null` in means "every default", which is byte-for-byte the behaviour before this payload grew —
+ * so a controller that sends nothing new is unaffected by any of this.
+ */
+export function readSessionRequest(request) {
+    if (request === null)
+        return ok({});
+    const composed = {};
+    if (request.resume !== null)
+        composed['resume'] = request.resume;
+    if (request.fork !== null)
+        composed['fork'] = request.fork;
+    if (request.includePartialMessages !== null) {
+        composed['includePartialMessages'] = request.includePartialMessages;
+    }
+    if (request.forwardSubagentText !== null)
+        composed['forwardSubagentText'] = request.forwardSubagentText;
+    if (request.strictMcpConfig !== null)
+        composed['strictMcpConfig'] = request.strictMcpConfig;
+    if (request.model !== null)
+        composed['model'] = request.model;
+    // Handed on as the SDK's own option type. A string, a list of strings and a preset object are all
+    // legal, so there is no closed set to check and inventing one would refuse valid requests.
+    if (request.systemPrompt !== null)
+        composed['systemPrompt'] = request.systemPrompt;
+    if (request.settingSources !== null) {
+        // A tier nobody declared is refused, not dropped. Dropping it would start a session the
+        // controller believes loads its project settings, silently without them — and the permission
+        // rules it expected to be in force would simply not be. Nothing would say so.
+        const unknown = request.settingSources.filter((source) => !SETTING_SOURCES.includes(source));
+        if (unknown.length > 0) {
+            return refuse('frame-malformed', `settingSources names ${unknown.map((source) => `"${source}"`).join(', ')}, which this host ` +
+                `does not know — the tiers are ${SETTING_SOURCES.join(', ')}. Refused rather than ignored: a ` +
+                `session started without a tier its controller asked for runs with permission rules nobody ` +
+                `told it were absent`);
+        }
+        composed['settingSources'] = [...request.settingSources];
+    }
+    if (request.plugins !== null) {
+        const plugins = [];
+        for (const plugin of request.plugins) {
+            // Same argument as the tiers: the SDK supports exactly one plugin type today, and a value it
+            // does not recognise loads nothing while looking like it asked for something.
+            if (plugin.type !== 'local') {
+                return refuse('frame-malformed', `a plugin declares type "${plugin.type}"; this host passes only "local" plugins to the agent`);
+            }
+            plugins.push({
+                type: 'local',
+                path: plugin.path,
+                ...(plugin.skipMcpDiscovery === null ? {} : { skipMcpDiscovery: plugin.skipMcpDiscovery }),
+            });
+        }
+        composed['plugins'] = plugins;
+    }
+    if (request.thinking !== null) {
+        const type = request.thinking['type'];
+        if (typeof type !== 'string' || !THINKING_TYPES.includes(type)) {
+            return refuse('frame-malformed', `thinking.type is ${JSON.stringify(type)}; the shapes this SDK declares are ` +
+                `${THINKING_TYPES.join(', ')}`);
+        }
+        composed['thinking'] = request.thinking;
+    }
+    if (request.effort !== null) {
+        if (!EFFORT_LEVELS.includes(request.effort)) {
+            return refuse('frame-malformed', `effort is ${JSON.stringify(request.effort)}; the levels this SDK declares are ${EFFORT_LEVELS.join(', ')}`);
+        }
+        composed['effort'] = request.effort;
+    }
+    if (request.permissionMode !== null) {
+        // The lane that was closed, opened by name (protocol v6). Narrowed like every other member: an
+        // unknown mode is refused, never dropped and never defaulted.
+        if (!PERMISSION_MODES.includes(request.permissionMode)) {
+            return refuse('frame-malformed', `permissionMode is ${JSON.stringify(request.permissionMode)}; the modes this SDK declares are ` +
+                `${PERMISSION_MODES.join(', ')}`);
+        }
+        composed['permissionMode'] = request.permissionMode;
+    }
+    if (request.env !== null) {
+        const policy = {
+            ...(request.env.extraAllowedKeys === null
+                ? {}
+                : { extraAllowedKeys: [...request.env.extraAllowedKeys] }),
+            ...(request.env.extraDeniedKeys === null ? {} : { extraDeniedKeys: [...request.env.extraDeniedKeys] }),
+            ...(request.env.extraEnv === null ? {} : { extraEnv: { ...request.env.extraEnv } }),
+        };
+        composed['env'] = policy;
+    }
+    if (request.mcpServers !== null) {
+        const servers = readMcpServers(request.mcpServers);
+        if (!servers.ok)
+            return refuse(servers.refusal.reason, servers.refusal.detail);
+        composed['mcpServers'] = servers.value;
+    }
+    return ok(composed);
+}
+/**
+ * Shape-check the server map. Each value must be an object; beyond that the SDK is the validator.
+ *
+ * See this file's header for why the config union is not re-stated here.
+ */
+function readMcpServers(servers) {
+    const read = {};
+    for (const [name, config] of Object.entries(servers)) {
+        if (name === '') {
+            return refuse('mcp-descriptor-invalid', 'an MCP server was declared under an empty name; a tool reaches the model as ' +
+                '`mcp__{server}__{tool}` and an unnamed server has no reachable tools');
+        }
+        if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+            return refuse('mcp-descriptor-invalid', `MCP server "${name}" is declared as ${config === null ? 'null' : typeof config}, not an object`);
+        }
+        read[name] = config;
+    }
+    return ok(read);
+}
+/**
+ * Merge the controller's servers with the ones this host registers itself.
+ *
+ * A colliding name is refused rather than resolved, and either precedence would have been wrong.
+ * Letting the controller win lets a remote peer replace the host's OWN tool server — the one that
+ * carries the host's identity into every call — with something it supplies. Letting the host win
+ * silently discards a registration the controller believes it made, and its tools then simply do not
+ * exist, with nothing anywhere saying why. So the pair is refused, before any process exists, naming
+ * the server both sides claimed.
+ */
+export function mergeMcpServers(fromController, fromHost) {
+    if (fromHost === null)
+        return ok(fromController ?? null);
+    if (fromController === undefined)
+        return ok(fromHost);
+    const collisions = Object.keys(fromHost).filter((name) => Object.prototype.hasOwnProperty.call(fromController, name));
+    if (collisions.length > 0) {
+        return refuse('mcp-descriptor-invalid', `MCP server ${collisions.map((name) => `"${name}"`).join(', ')} is declared by both this host ` +
+            `and the controller. Refused rather than resolved: letting the controller win replaces this ` +
+            `host's own tool server, and letting the host win discards a registration the controller ` +
+            `believes it made. Rename one`);
+    }
+    return ok({ ...fromHost, ...fromController });
+}
+//# sourceMappingURL=wire-request.js.map

package/dist/host/workspace-fs.d.ts

@@ -0,0 +1,14 @@
+import type { CommandEffects, WorkspaceEffects } from '../workspace/provider.js';
+/** The filesystem half, on `node:fs/promises`. */
+export declare const nodeWorkspaceEffects: WorkspaceEffects;
+/**
+ * Running a program with an argv array.
+ *
+ * It rejects on a non-zero exit, and that is load-bearing rather than conventional. The worktree
+ * provider probes for a branch by running `rev-parse --verify` and reading the FAILURE as "this
+ * branch does not exist" — so an implementation that resolved with an empty string on a non-zero
+ * exit would report every branch as existing, and the provider would attach where it should create.
+ * The safe direction, but silently wrong, and it would look like it worked.
+ */
+export declare function nodeCommandEffects(timeoutMs?: number): CommandEffects;
+//# sourceMappingURL=workspace-fs.d.ts.map

package/dist/host/workspace-fs.js

@@ -0,0 +1,84 @@
+/**
+ * The real effects the workspace providers run on: the filesystem, and `git`.
+ *
+ * Why they live here and the providers do not: `src/host/` is the only directory allowed to touch
+ * the machine, pinned by pins/host-boundary.test.ts, and a provider is mostly DECISIONS: which argv
+ * a git call gets, whether a directory is reused or made, what a release does. Splitting them puts
+ * the decisions where they can be tested with no disk and no repository — which is what turns "never
+ * hard-reset an existing branch" into a unit test instead of a rule only a lost branch could prove.
+ *
+ * `execFile`, never `exec`. `exec` runs its argument through a shell, so every branch name and
+ * path in it becomes an injection site — and branch names arrive from a caller this package does not
+ * control. `execFile` takes an argv array and spawns the program directly, with no shell to quote
+ * for and nothing to escape.
+ */
+import { execFile } from 'node:child_process';
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+/** The filesystem half, on `node:fs/promises`. */
+export const nodeWorkspaceEffects = {
+    async makeDirectory(path) {
+        await mkdir(path, { recursive: true });
+    },
+    async exists(path) {
+        try {
+            await stat(path);
+            return true;
+        }
+        catch {
+            // Any failure to stat is treated as absent. The caller's next act either creates it — which
+            // reports its own error — or attaches to it, so a stat that failed for a different reason
+            // surfaces as a named provisioning refusal rather than being swallowed here.
+            return false;
+        }
+    },
+    async removeDirectory(path) {
+        await rm(path, { recursive: true, force: true });
+    },
+    async listDirectories(path) {
+        try {
+            const entries = await readdir(path, { withFileTypes: true });
+            return entries
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => entry.name)
+                .sort();
+        }
+        catch (error) {
+            // A root that does not exist yet has no workspaces in it; anything else is the caller's refusal.
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    },
+};
+/**
+ * 60 seconds. Long enough for a cold worktree creation on a loaded machine; short enough that a git
+ * call which will never return does not hold a session's provisioning open indefinitely.
+ */
+const DEFAULT_COMMAND_TIMEOUT_MS = 60_000;
+/**
+ * Running a program with an argv array.
+ *
+ * It rejects on a non-zero exit, and that is load-bearing rather than conventional. The worktree
+ * provider probes for a branch by running `rev-parse --verify` and reading the FAILURE as "this
+ * branch does not exist" — so an implementation that resolved with an empty string on a non-zero
+ * exit would report every branch as existing, and the provider would attach where it should create.
+ * The safe direction, but silently wrong, and it would look like it worked.
+ */
+export function nodeCommandEffects(timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
+    return {
+        run(program, args, cwd) {
+            return new Promise((resolve, reject) => {
+                execFile(program, [...args], { cwd, timeout: timeoutMs, windowsHide: true }, (error, stdout, stderr) => {
+                    if (error !== null) {
+                        // stderr carries git's own message, which is the only text that says WHY. Dropping it
+                        // leaves a refusal reading "command failed" with nothing to act on.
+                        reject(new Error(`${program} ${args.join(' ')} failed: ${stderr.trim() || error.message}`));
+                        return;
+                    }
+                    resolve(stdout.trim());
+                });
+            });
+        },
+    };
+}
+//# sourceMappingURL=workspace-fs.js.map