@crouter/api 0.3.386 → 0.3.388

package/dist/core/locked-file.js

@@ -0,0 +1,118 @@
+// locked-file.ts — crouter's cross-process locked read/modify/write primitive for the
+// small JSON state files the runtime co-owns with pi: pi's own `auth.json` (api keys and
+// non-managed OAuth credentials) and crouter's per-provider subscription pool files, which
+// hold every managed account's own credential.
+//
+// The lock is `proper-lockfile` on the target path, so a crouter process and a pi process
+// contending for `auth.json` still exclude each other: same library, same lock path, and
+// same `realpath: false` option. Every callback runs asynchronously and returns
+// `{ result, next }`; `next === undefined` means "no write". Every write lands by atomic
+// tmp+rename (pool callers do their own, inside the callback), so a whole snapshot is the
+// only thing on disk and READS need no lock at all -- `readUnlocked` serves them. That
+// matters: pi asks its CredentialStore for every registered provider (~75) whenever it
+// builds a model runtime, and routing those through the lock made each boot serialize
+// behind seconds of lock acquisition backoff.
+import { chmodSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, closeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import lockfile from 'proper-lockfile';
+const WRITE_OPTIONS = { encoding: 'utf-8', mode: 0o600 };
+// proper-lockfile decides a held lock is abandoned when its lockdir mtime is older than
+// the acquirer's `stale`, and refreshes the mtime on the holder's `update` timer. The holder
+// refreshes well inside the staleness threshold so long-running callbacks remain protected.
+const LOCK_STALE_MS = 30_000;
+const LOCK_UPDATE_MS = 5_000;
+/** A 0600 JSON file guarded by a cross-process `proper-lockfile` lock on its own path. */
+export class LockedJsonFile {
+    path;
+    durable;
+    initialContent;
+    constructor(path, durable = false, initialContent = '{}') {
+        this.path = path;
+        this.durable = durable;
+        this.initialContent = initialContent;
+    }
+    readUnlocked() {
+        return existsSync(this.path) ? readFileSync(this.path, 'utf-8') : undefined;
+    }
+    ensureFile() {
+        const dir = dirname(this.path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (!existsSync(this.path)) {
+            writeFileSync(this.path, this.initialContent, WRITE_OPTIONS);
+            chmodSync(this.path, 0o600);
+        }
+    }
+    /** Acquire the lock without blocking the event loop, keeping every read-modify-write
+     *  callback on the same asynchronous path. */
+    async withLockAsync(fn) {
+        this.ensureFile();
+        let release;
+        let compromised;
+        const throwIfCompromised = () => {
+            if (compromised)
+                throw compromised;
+        };
+        try {
+            release = await lockfile.lock(this.path, {
+                // A different realpath setting would derive a DIFFERENT lock path for a symlinked
+                // auth.json and silently stop excluding other writers.
+                realpath: false,
+                retries: { retries: 10, factor: 2, minTimeout: 100, maxTimeout: 10_000, randomize: true },
+                stale: LOCK_STALE_MS,
+                // Refresh the lockdir mtime well inside `stale` so long-running callbacks remain protected.
+                update: LOCK_UPDATE_MS,
+                onCompromised: (err) => {
+                    compromised = err;
+                },
+            });
+            throwIfCompromised();
+            const current = existsSync(this.path) ? readFileSync(this.path, 'utf-8') : undefined;
+            let published = false;
+            const publish = (next) => {
+                if (published)
+                    throw new Error(`locked file was published twice: ${this.path}`);
+                throwIfCompromised();
+                const tmp = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+                writeFileSync(tmp, next, WRITE_OPTIONS);
+                chmodSync(tmp, 0o600);
+                if (this.durable) {
+                    const fd = openSync(tmp, 'r');
+                    try {
+                        fsyncSync(fd);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                }
+                renameSync(tmp, this.path);
+                if (this.durable) {
+                    const fd = openSync(dirname(this.path), 'r');
+                    try {
+                        fsyncSync(fd);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                }
+                published = true;
+            };
+            const { result, next } = await fn(current, throwIfCompromised, publish);
+            throwIfCompromised();
+            if (next !== undefined)
+                publish(next);
+            throwIfCompromised();
+            return result;
+        }
+        finally {
+            if (release) {
+                try {
+                    await release();
+                }
+                catch {
+                    // A compromised lock's release throws; the compromise itself already surfaced.
+                }
+            }
+        }
+    }
+}

package/dist/core/log.d.ts

@@ -0,0 +1,9 @@
+export declare const MAX_ROTATING_RECORD_BYTES = 65536;
+/** Synchronously appends one complete NDJSON record, retaining active + .1 + .2. */
+export declare function appendRotatingRecord(path: string, recordWithoutLf: string): boolean;
+/** One timed/bounded daemon batch instead of a mkdir/stat/open/write per event.
+ *  Process 'exit' drains synchronously even after an uncaught exception; SIGKILL
+ *  and a host power loss cannot run an exit handler. */
+export declare function appendBufferedDaemonRecord(path: string, recordWithoutLf: string): boolean;
+/** Flush the daemon batch; also invoked synchronously on process exit. */
+export declare function flushDaemonLog(): void;

package/dist/core/log.js

@@ -0,0 +1,89 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const MAX_ROTATING_RECORD_BYTES = 65_536;
+const MAX_ACTIVE_BYTES = 5 * 1024 * 1024;
+const MAX_PENDING_BYTES = 128 * 1024;
+const FLUSH_INTERVAL_MS = 200;
+/** Append complete records in batches, rotating at record boundaries. */
+function appendRotatingRecords(path, records) {
+    let pending = '';
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        let currentBytes = existsSync(path) ? statSync(path).size : 0;
+        for (const record of records) {
+            const line = `${record}\n`;
+            const lineBytes = Buffer.byteLength(line, 'utf8');
+            if (currentBytes + lineBytes > MAX_ACTIVE_BYTES && currentBytes > 0) {
+                if (pending !== '') {
+                    appendFileSync(path, pending, 'utf8');
+                    pending = '';
+                }
+                rmSync(`${path}.2`, { force: true });
+                if (existsSync(`${path}.1`))
+                    renameSync(`${path}.1`, `${path}.2`);
+                renameSync(path, `${path}.1`);
+                currentBytes = 0;
+            }
+            pending += line;
+            currentBytes += lineBytes;
+        }
+        if (pending !== '')
+            appendFileSync(path, pending, 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Synchronously appends one complete NDJSON record, retaining active + .1 + .2. */
+export function appendRotatingRecord(path, recordWithoutLf) {
+    if (recordWithoutLf.includes('\n') || recordWithoutLf.includes('\r'))
+        return false;
+    if (Buffer.byteLength(recordWithoutLf, 'utf8') + 1 > MAX_ROTATING_RECORD_BYTES)
+        return false;
+    return appendRotatingRecords(path, [recordWithoutLf]);
+}
+let daemonBuffer;
+let exitDrainInstalled = false;
+/** One timed/bounded daemon batch instead of a mkdir/stat/open/write per event.
+ *  Process 'exit' drains synchronously even after an uncaught exception; SIGKILL
+ *  and a host power loss cannot run an exit handler. */
+export function appendBufferedDaemonRecord(path, recordWithoutLf) {
+    if (recordWithoutLf.includes('\n') || recordWithoutLf.includes('\r'))
+        return false;
+    const bytes = Buffer.byteLength(recordWithoutLf, 'utf8') + 1;
+    if (bytes > MAX_ROTATING_RECORD_BYTES)
+        return false;
+    if (daemonBuffer !== undefined && daemonBuffer.path !== path)
+        flushDaemonLog();
+    if (daemonBuffer === undefined) {
+        daemonBuffer = { path, records: [], bytes: 0 };
+        if (!exitDrainInstalled) {
+            process.on('exit', flushDaemonLog);
+            exitDrainInstalled = true;
+        }
+    }
+    daemonBuffer.path = path;
+    daemonBuffer.records.push(recordWithoutLf);
+    daemonBuffer.bytes += bytes;
+    if (daemonBuffer.bytes >= MAX_PENDING_BYTES)
+        flushDaemonLog();
+    else if (daemonBuffer.timer === undefined) {
+        daemonBuffer.timer = setTimeout(flushDaemonLog, FLUSH_INTERVAL_MS);
+        daemonBuffer.timer.unref();
+    }
+    return true;
+}
+/** Flush the daemon batch; also invoked synchronously on process exit. */
+export function flushDaemonLog() {
+    const buffer = daemonBuffer;
+    if (buffer === undefined || buffer.records.length === 0)
+        return;
+    if (buffer.timer !== undefined)
+        clearTimeout(buffer.timer);
+    daemonBuffer = undefined;
+    if (!appendRotatingRecords(buffer.path, buffer.records)) {
+        for (const record of buffer.records)
+            process.stderr.write(`[crtrd] event log append failed: ${record}\n`);
+    }
+}

package/dist/core/manifest.d.ts

@@ -0,0 +1,5 @@
+import type { MarketplaceManifest, PluginManifest } from '../types.js';
+export declare function pluginManifestPath(pluginRoot: string): string;
+export declare function marketplaceManifestPath(mktRoot: string): string;
+export declare function readPluginManifest(pluginRoot: string): PluginManifest | null;
+export declare function readMarketplaceManifest(mktRoot: string): MarketplaceManifest | null;

package/dist/core/manifest.js

@@ -0,0 +1,15 @@
+import { join } from 'node:path';
+import { MARKETPLACE_MANIFEST_DIR, MARKETPLACE_MANIFEST_FILE, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE, } from '../types.js';
+import { readJsonIfExists } from './fs-utils.js';
+export function pluginManifestPath(pluginRoot) {
+    return join(pluginRoot, PLUGIN_MANIFEST_DIR, PLUGIN_MANIFEST_FILE);
+}
+export function marketplaceManifestPath(mktRoot) {
+    return join(mktRoot, MARKETPLACE_MANIFEST_DIR, MARKETPLACE_MANIFEST_FILE);
+}
+export function readPluginManifest(pluginRoot) {
+    return readJsonIfExists(pluginManifestPath(pluginRoot));
+}
+export function readMarketplaceManifest(mktRoot) {
+    return readJsonIfExists(marketplaceManifestPath(mktRoot));
+}

package/dist/core/plugin-env.d.ts

@@ -0,0 +1,8 @@
+export interface PluginEnvDeclaration {
+    description: string;
+    required?: boolean;
+    secret?: boolean;
+    url?: string;
+}
+export declare function invalidPluginEnvReasons(raw: unknown): string[];
+export declare function requiredPluginEnv(raw: Record<string, PluginEnvDeclaration> | undefined): string[];

package/dist/core/plugin-env.js

@@ -0,0 +1,31 @@
+import { validateEnvVarName } from './env-name.js';
+import { isReservedEnvName } from './profiles/env-store.js';
+export function invalidPluginEnvReasons(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return ['env must be an object mapping variable names to declarations'];
+    const reasons = [];
+    for (const [name, declaration] of Object.entries(raw)) {
+        if (!validateEnvVarName(name).isValid || isReservedEnvName(name))
+            reasons.push(`env.${name} has an invalid or reserved name`);
+        if (!declaration || typeof declaration !== 'object' || Array.isArray(declaration)) {
+            reasons.push(`env.${name} must be an object`);
+            continue;
+        }
+        const entry = declaration;
+        if (typeof entry['description'] !== 'string' || !entry['description'].trim())
+            reasons.push(`env.${name}.description must be a non-empty string`);
+        if (entry['required'] !== undefined && typeof entry['required'] !== 'boolean')
+            reasons.push(`env.${name}.required must be boolean`);
+        if (entry['secret'] !== undefined && typeof entry['secret'] !== 'boolean')
+            reasons.push(`env.${name}.secret must be boolean`);
+        if (entry['url'] !== undefined && (typeof entry['url'] !== 'string' || !/^https:\/\/[^\s]+$/.test(entry['url'])))
+            reasons.push(`env.${name}.url must be an https URL`);
+        for (const key of Object.keys(entry))
+            if (!['description', 'required', 'secret', 'url'].includes(key))
+                reasons.push(`env.${name}.${key} is unknown`);
+    }
+    return reasons;
+}
+export function requiredPluginEnv(raw) {
+    return Object.entries(raw ?? {}).filter(([, entry]) => entry.required !== false).map(([name]) => name);
+}

package/dist/core/plugin-extensions.d.ts

@@ -0,0 +1,29 @@
+import type { MemoryExtensionDeclarations, MemoryExtensionScalar, PluginManifest, Scope } from '../types.js';
+export type MemoryExtensionCatalog = Record<string, MemoryExtensionDeclarations>;
+export interface MemoryExtensionValidationIssue {
+    path: string;
+    message: string;
+}
+export interface MemoryExtensionCatalogOptions {
+    /** The manifest currently being staged. Its namespace shadows an installed copy only for that candidate validation. */
+    candidate?: Pick<PluginManifest, 'name' | 'memory_extensions'>;
+}
+export declare function isMemoryExtensionScalar(value: unknown): value is MemoryExtensionScalar;
+/** Parse the closed declaration addendum. Callers that accept a plugin manifest
+ * invoke this at their install/preflight boundary; normal runtime catalogs only
+ * admit declarations which have already cleared that boundary. */
+export declare function validateMemoryExtensionDeclarations(raw: unknown): MemoryExtensionDeclarations;
+/** Throw when a manifest carries an invalid addendum; absent is valid. */
+export declare function validatePluginMemoryExtensions(manifest: Pick<PluginManifest, 'memory_extensions'>): void;
+/** Declarations for a native document. Project documents use their owning
+ * project scope only, then user scope; profile/node/user docs use user scope. */
+/** Installed declarations a package candidate's documents validate against:
+ * a project-scope candidate sees its project's plugins, then user scope; any
+ * other scope sees user scope. Disabled plugins remain present so existing
+ * values can still be checked. The candidate's namespace shadows an installed
+ * copy of the same name. */
+export declare function pluginExtensionCatalog(scope: Scope, scopeRootPath: string, options?: MemoryExtensionCatalogOptions): MemoryExtensionCatalog;
+/** Validate the raw `extensions` frontmatter value. Unresolved namespaces are
+ * intentionally reported rather than discarded: removal leaves raw metadata
+ * intact but lint-invalid until its plugin returns. */
+export declare function validateMemoryExtensionValues(raw: unknown, catalog: MemoryExtensionCatalog): MemoryExtensionValidationIssue[];

package/dist/core/plugin-extensions.js

@@ -0,0 +1,191 @@
+// plugin-extensions.ts — a plugin manifest's `memory_extensions` declarations and
+// the `extensions` frontmatter values its package documents carry.
+import { listInstalledPlugins, listInstalledPluginsInRoot } from './resolver.js';
+const LOCAL_FIELD_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const DECLARATION_KEYS = new Set(['type', 'values', 'default', 'write_help', 'edit_help']);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function isMemoryExtensionScalar(value) {
+    return typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
+}
+function declarationError(path, message) {
+    return new Error(`invalid memory_extensions declaration at ${path}: ${message}`);
+}
+function validHelp(value) {
+    return typeof value === 'string' && value.trim() !== '' && !/[\r\n]/.test(value);
+}
+function validDefault(declaration, value) {
+    if (!isMemoryExtensionScalar(value))
+        return false;
+    if (declaration.type === 'enum')
+        return typeof value === 'string' && declaration.values.includes(value);
+    return typeof value === declaration.type;
+}
+/** Parse the closed declaration addendum. Callers that accept a plugin manifest
+ * invoke this at their install/preflight boundary; normal runtime catalogs only
+ * admit declarations which have already cleared that boundary. */
+export function validateMemoryExtensionDeclarations(raw) {
+    if (!isRecord(raw))
+        throw declarationError('memory_extensions', 'expected a non-empty object');
+    const declarations = {};
+    const fields = Object.entries(raw);
+    if (fields.length === 0)
+        throw declarationError('memory_extensions', 'must not be empty');
+    for (const [field, value] of fields) {
+        const path = `memory_extensions.${field}`;
+        if (!LOCAL_FIELD_NAME.test(field)) {
+            throw declarationError(path, 'field names must be lowercase kebab-case');
+        }
+        if (!isRecord(value))
+            throw declarationError(path, 'expected a declaration object');
+        for (const key of Object.keys(value)) {
+            if (!DECLARATION_KEYS.has(key))
+                throw declarationError(path, `unknown key \`${key}\``);
+        }
+        const type = value['type'];
+        if (type !== 'boolean' && type !== 'string' && type !== 'number' && type !== 'enum') {
+            throw declarationError(`${path}.type`, 'expected boolean, string, number, or enum');
+        }
+        if (!validHelp(value['write_help']))
+            throw declarationError(`${path}.write_help`, 'expected a nonblank single-line string');
+        if (!validHelp(value['edit_help']))
+            throw declarationError(`${path}.edit_help`, 'expected a nonblank single-line string');
+        if (type === 'enum') {
+            const values = value['values'];
+            if (!Array.isArray(values) || values.length === 0 || !values.every((entry) => typeof entry === 'string' && entry !== '')) {
+                throw declarationError(`${path}.values`, 'expected a non-empty string list');
+            }
+            if (new Set(values).size !== values.length)
+                throw declarationError(`${path}.values`, 'values must be unique');
+            const declaration = {
+                type,
+                values: [...values],
+                write_help: value['write_help'],
+                edit_help: value['edit_help'],
+            };
+            if ('default' in value) {
+                if (!validDefault(declaration, value['default'])) {
+                    throw declarationError(`${path}.default`, 'must be one of the declared enum values');
+                }
+                declaration.default = value['default'];
+            }
+            declarations[field] = declaration;
+            continue;
+        }
+        if ('values' in value)
+            throw declarationError(`${path}.values`, 'is allowed only for enum declarations');
+        const declaration = {
+            type,
+            write_help: value['write_help'],
+            edit_help: value['edit_help'],
+        };
+        if ('default' in value) {
+            if (!validDefault(declaration, value['default'])) {
+                throw declarationError(`${path}.default`, `must be a ${type}`);
+            }
+            declaration.default = value['default'];
+        }
+        declarations[field] = declaration;
+    }
+    return declarations;
+}
+/** Throw when a manifest carries an invalid addendum; absent is valid. */
+export function validatePluginMemoryExtensions(manifest) {
+    if (manifest.memory_extensions !== undefined)
+        validateMemoryExtensionDeclarations(manifest.memory_extensions);
+}
+function declarationsFromManifest(manifest, strict) {
+    if (manifest.memory_extensions === undefined)
+        return undefined;
+    try {
+        return validateMemoryExtensionDeclarations(manifest.memory_extensions);
+    }
+    catch (error) {
+        if (strict)
+            throw error;
+        return undefined;
+    }
+}
+function catalogForPlugins(groups, enabledOnly, candidate) {
+    const catalog = {};
+    const shadowed = new Set();
+    if (candidate !== undefined) {
+        // A candidate that removes its addendum must still hide an installed copy
+        // while that package's own documents are being validated.
+        shadowed.add(candidate.name);
+        const declarations = declarationsFromManifest(candidate, true);
+        if (declarations !== undefined)
+            catalog[candidate.name] = declarations;
+    }
+    for (const plugins of groups) {
+        for (const plugin of plugins) {
+            if (enabledOnly && !plugin.enabled)
+                continue;
+            const namespace = plugin.manifest.name;
+            if (shadowed.has(namespace) || catalog[namespace] !== undefined)
+                continue;
+            const declarations = declarationsFromManifest(plugin.manifest, false);
+            if (declarations !== undefined)
+                catalog[namespace] = declarations;
+        }
+    }
+    return catalog;
+}
+/** Declarations for a native document. Project documents use their owning
+ * project scope only, then user scope; profile/node/user docs use user scope. */
+/** Installed declarations a package candidate's documents validate against:
+ * a project-scope candidate sees its project's plugins, then user scope; any
+ * other scope sees user scope. Disabled plugins remain present so existing
+ * values can still be checked. The candidate's namespace shadows an installed
+ * copy of the same name. */
+export function pluginExtensionCatalog(scope, scopeRootPath, options = {}) {
+    const groups = scope === 'project'
+        ? [listInstalledPluginsInRoot('project', scopeRootPath), listInstalledPlugins('user')]
+        : scope === 'builtin' ? [] : [listInstalledPlugins('user')];
+    return catalogForPlugins(groups, false, options.candidate);
+}
+/** Validate the raw `extensions` frontmatter value. Unresolved namespaces are
+ * intentionally reported rather than discarded: removal leaves raw metadata
+ * intact but lint-invalid until its plugin returns. */
+export function validateMemoryExtensionValues(raw, catalog) {
+    if (raw === undefined)
+        return [];
+    if (!isRecord(raw))
+        return [{ path: 'extensions', message: 'expected a mapping' }];
+    const issues = [];
+    for (const [namespace, fields] of Object.entries(raw)) {
+        const namespacePath = `extensions.${namespace}`;
+        if (!isRecord(fields)) {
+            issues.push({ path: namespacePath, message: 'expected a mapping' });
+            continue;
+        }
+        const declarations = catalog[namespace];
+        if (declarations === undefined) {
+            issues.push({ path: namespacePath, message: 'unresolved extension namespace' });
+            for (const [field, value] of Object.entries(fields)) {
+                if (!isMemoryExtensionScalar(value)) {
+                    issues.push({ path: `${namespacePath}.${field}`, message: 'expected a string, boolean, or finite number' });
+                }
+            }
+            continue;
+        }
+        for (const [field, value] of Object.entries(fields)) {
+            const path = `${namespacePath}.${field}`;
+            if (!isMemoryExtensionScalar(value)) {
+                issues.push({ path, message: 'expected a string, boolean, or finite number' });
+                continue;
+            }
+            const declaration = declarations[field];
+            if (declaration === undefined) {
+                issues.push({ path, message: 'undeclared extension field' });
+                continue;
+            }
+            if (!validDefault(declaration, value)) {
+                const expected = declaration.type === 'enum' ? `one of ${declaration.values.join('|')}` : declaration.type;
+                issues.push({ path, message: `expected ${expected}` });
+            }
+        }
+    }
+    return issues;
+}

package/dist/core/plugin-swap-lock.d.ts

@@ -0,0 +1,9 @@
+/** Under the scope root's `tmp/`, alongside the staging and `.prev` dirs the
+ *  swap itself uses, so one directory holds the whole transition. */
+export declare function bundleSwapLockPath(scopeRootPath: string, name: string): string;
+/** Whether ANOTHER live process currently holds this plugin's swap lock. Our
+ *  own lock does not count: the swapper reads the plugin list from inside its
+ *  own critical section. */
+export declare function bundleSwapInFlightElsewhere(scopeRootPath: string, name: string): boolean;
+/** Wait out another process's swap of this plugin, bounded. */
+export declare function awaitBundleSwap(scopeRootPath: string, name: string): void;

package/dist/core/plugin-swap-lock.js

@@ -0,0 +1,31 @@
+// The one name for the lock a bundle-plugin package swap is held under, and the
+// two questions a reader asks about it.
+//
+// Two modules need it and neither may own it: the swapper lives in
+// `commands/pkg/plugin-manage.ts` (the whole command graph), the reader in
+// `core/installed-plugins.ts` (deliberately leaf-safe: types, fs-utils,
+// manifest). This module keeps both dependency-light — `node:path` plus the
+// generic lock primitive, which itself imports only `node:fs` and
+// `node:crypto`.
+import { join } from 'node:path';
+import { awaitExclusiveLockRelease, exclusiveLockOwnerPid } from './exclusive-lock.js';
+/** How long a reader waits for another process's swap to finish before it
+ *  reports what it can see. A swap is one rename of an already-staged, already-
+ *  validated tree, so a wait this long means the holder is wedged, not slow. */
+const READER_WAIT_MS = 2_000;
+/** Under the scope root's `tmp/`, alongside the staging and `.prev` dirs the
+ *  swap itself uses, so one directory holds the whole transition. */
+export function bundleSwapLockPath(scopeRootPath, name) {
+    return join(scopeRootPath, 'tmp', `${name}.swap.lock`);
+}
+/** Whether ANOTHER live process currently holds this plugin's swap lock. Our
+ *  own lock does not count: the swapper reads the plugin list from inside its
+ *  own critical section. */
+export function bundleSwapInFlightElsewhere(scopeRootPath, name) {
+    const pid = exclusiveLockOwnerPid(bundleSwapLockPath(scopeRootPath, name));
+    return pid !== null && pid !== process.pid;
+}
+/** Wait out another process's swap of this plugin, bounded. */
+export function awaitBundleSwap(scopeRootPath, name) {
+    awaitExclusiveLockRelease(bundleSwapLockPath(scopeRootPath, name), READER_WAIT_MS);
+}

package/dist/core/preview-result-path.d.ts

@@ -0,0 +1,4 @@
+export declare const PREVIEW_RESULT_PATH_ENV = "CRTR_PREVIEW_RESULT_PATH";
+/** Deterministic from the tool call id, so the spawning side and the result
+ *  side derive the same path without sharing state. */
+export declare function previewResultPath(toolCallId: string): string;

package/dist/core/preview-result-path.js

@@ -0,0 +1,26 @@
+// The private structured-result side channel between a crtr CLI invocation and
+// the canvas broker that spawned it: the broker names one file per bash tool
+// call, the leaf mirrors its record there, and the broker attaches the record
+// to Pi's ToolResult.details.
+//
+// The path travels in the child process environment. It must never be spliced
+// into the command text — the executed script has to stay exactly what the
+// agent wrote, because `cmd.sh`, job inspection, and the doc substrate's
+// `command` surfaces all read that text as the agent's own words.
+import { envNodeId } from '../shared/env.js';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const PREVIEW_RESULT_PATH_ENV = 'CRTR_PREVIEW_RESULT_PATH';
+/** A tool call id is unique only within one broker: some provider adapters
+ *  synthesize a missing id from a process-local counter and a millisecond
+ *  clock, so two brokers can mint the same one and collide on a shared file.
+ *  Node id and pid are equal across both sides of the transport (they run in
+ *  the same broker process) without either side sharing state. */
+function brokerToken() {
+    return `${encodeURIComponent(envNodeId() ?? 'no-node')}-${process.pid}`;
+}
+/** Deterministic from the tool call id, so the spawning side and the result
+ *  side derive the same path without sharing state. */
+export function previewResultPath(toolCallId) {
+    return join(tmpdir(), 'crouter-preview-results', `${brokerToken()}-${encodeURIComponent(toolCallId)}.json`);
+}

package/dist/core/profiles/env-store.d.ts

@@ -0,0 +1,22 @@
+export declare function isReservedEnvName(name: string): boolean;
+/** Every stored variable NAME for a profile, sorted. Never returns values. */
+export declare function listProfileEnvNames(profileId: string): string[];
+/** Set one variable, replacing any prior value under the same name. Holds the
+ *  same per-profile lock manifest mutations use (`withProfileManifestLock`),
+ *  so a concurrent `profile delete` can never race a write into an
+ *  about-to-vanish profile dir — whichever runs first wins the lock, and the
+ *  loser either sees `not_found` (delete-then-set) or removes the file right
+ *  back out from under a just-written value (set-then-delete, via
+ *  `deleteProfile`'s recursive rm of the whole profile root). Returns whether
+ *  the name was newly added (`true`) or replaced an existing value (`false`). */
+export declare function setProfileEnvVar(profileId: string, name: string, value: string): boolean;
+/** Remove one variable. Returns whether it was present. */
+export declare function removeProfileEnvVar(profileId: string, name: string): boolean;
+/** Every stored `{name: value}` for a profile — the ONLY function that
+ *  returns raw values, called exclusively by `buildBrokerEnv`
+ *  (`core/runtime/spawn-env.ts`) to inject them directly into a launched
+ *  broker's env. Never throws: a stale/invalid/deleted profile id is a
+ *  hot-path no-op (mirrors `readRawProfileConfig` in `core/config.ts`),
+ *  because broker-env resolution must never fail a launch over a bad profile
+ *  id. */
+export declare function readProfileEnvVars(profileId: string | null): Record<string, string>;