@north-light/crouter 0.3.174 → 0.3.176

package/dist/core/exclusive-lock.js

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readdirSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+const MARKER_PREFIX = 'owner.';
+const POLL_MS = 10;
+const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_TIMEOUT_MS = 5_000;
+function pause(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+function markerPath(path, token) { return `${path}/${MARKER_PREFIX}${token}`; }
+function observedMarkerToken(path) {
+    try {
+        return readdirSync(path).find((entry) => entry.startsWith(MARKER_PREFIX))?.slice(MARKER_PREFIX.length) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The token opens with the owner's pid, so liveness reads off the name. */
+function ownerIsAlive(token) {
+    const pid = Number(token.split('.', 1)[0]);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function isEmptyDirectory(path) {
+    try {
+        return readdirSync(path).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function ageMs(path) {
+    try {
+        return Date.now() - statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+// Reclamation is bound to the exact instance it observed: it unlinks ONLY that
+// token's marker, then removes the now-empty directory with an empty-guarded
+// rmdir. A successor holds a different random token — a different marker name —
+// so a lagging reclaimer that saw the old dead lock can never strip a live
+// successor: its unlink targets a name that no longer exists.
+function reclaimIfOwnerGone(path, staleMs) {
+    const token = observedMarkerToken(path);
+    if (token !== null) {
+        if (ownerIsAlive(token))
+            return;
+        try {
+            unlinkSync(markerPath(path, token));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    else {
+        // Nothing names an owner. A live holder always has its marker, so this is a
+        // crash between mkdir and the marker write, or a lock left in some older
+        // shape; age is the only evidence, and an empty-guarded rmdir still cannot
+        // take a successor that has since claimed the name.
+        if (ageMs(path) <= staleMs)
+            return;
+        if (!isEmptyDirectory(path)) {
+            rmSync(path, { recursive: true, force: true });
+            return;
+        }
+    }
+    try {
+        rmdirSync(path);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ENOTEMPTY' && code !== 'EEXIST')
+            throw error;
+    }
+}
+function tryAcquire(path, staleMs) {
+    const token = `${process.pid}.${randomUUID()}`;
+    try {
+        mkdirSync(path, { mode: 0o700 });
+        writeFileSync(markerPath(path, token), '', { flag: 'wx', mode: 0o600 });
+        return { path, token };
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        reclaimIfOwnerGone(path, staleMs);
+        return null;
+    }
+}
+/**
+ * Run a short filesystem transition under a token-checked, crash-reclaimable
+ * directory lock. A holder that dies releases immediately — the next contender
+ * sees a dead pid in the marker name — while a live holder is never stolen from,
+ * however long its operation runs.
+ */
+export function withExclusiveDirectoryLock(path, operation, options = {}) {
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let lock = tryAcquire(path, staleMs);
+    while (lock === null) {
+        if (Date.now() >= deadline) {
+            throw options.timeoutError?.() ?? new Error(`timed out waiting for the exclusive lock: ${path}`);
+        }
+        pause(POLL_MS);
+        lock = tryAcquire(path, staleMs);
+    }
+    try {
+        return operation();
+    }
+    finally {
+        if (existsSync(markerPath(lock.path, lock.token)))
+            rmSync(lock.path, { recursive: true, force: true });
+    }
+}

package/dist/core/human/claim.js

@@ -1,7 +1,8 @@
 import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
-import { claimPath, deckPath, readJson, responsePath, reviewPath, withExclusiveDirectoryLock } from './convention.js';
+import { claimPath, deckPath, readJson, responsePath, reviewPath } from './convention.js';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 const REMOTE_STALE_MS = 30_000;
 function parseClaim(raw) {
     if (typeof raw !== 'object' || raw === null)

package/dist/core/human/convention.d.ts

@@ -15,16 +15,6 @@ export declare function atomicWriteJson(path: string, value: unknown): void;
 /** Publish one immutable JSON record without replacing an existing winner. */
 export declare function publishJsonExclusive(path: string, value: unknown): boolean;
 export declare function readJson<T>(path: string): T | null;
-/** Runs a short filesystem transition under a token-checked, crash-reclaimable directory lock. */
-export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: {
-    staleMs?: number;
-    timeoutMs?: number;
-}): T;
-/** Async counterpart heartbeats while its operation runs, so a valid long handler is never stolen. */
-export declare function withExclusiveDirectoryLockAsync<T>(path: string, operation: () => Promise<T>, options?: {
-    staleMs?: number;
-    timeoutMs?: number;
-}): Promise<T>;
 export declare function writeResponse(dir: string, responses: InteractionResponse[], completedAt: string, deck?: Deck): string;
 export declare function writeProgress(dir: string, responses: InteractionResponse[]): void;
 export declare function clearProgress(dir: string): void;

package/dist/core/human/convention.js

@@ -1,6 +1,5 @@
-import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { randomUUID } from 'node:crypto';
 import { buildSummary } from './summary.js';
 export function deckPath(dir) { return `${dir}/deck.json`; }
 export function reviewPath(dir) { return `${dir}/review.json`; }
@@ -62,127 +61,6 @@ export function readJson(path) {
         return null;
     }
 }
-function pause(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
-// The holder's identity lives in the NAME of its single marker file. The marker's
-// mtime is the heartbeat and its presence is ownership, so the observed token, the
-// staleness clock, and the reclaim gate are one atomic fact.
-const MARKER_PREFIX = 'owner.';
-function markerPath(path, token) { return `${path}/${MARKER_PREFIX}${token}`; }
-function observedMarkerToken(path) {
-    try {
-        return readdirSync(path).find((entry) => entry.startsWith(MARKER_PREFIX))?.slice(MARKER_PREFIX.length) ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-function ownsLock(lock) { return existsSync(markerPath(lock.path, lock.token)); }
-function releaseDirectoryLock(lock) { if (ownsLock(lock))
-    rmSync(lock.path, { recursive: true, force: true }); }
-function lockAge(path, token) {
-    const target = token !== null ? markerPath(path, token) : path;
-    try {
-        return Date.now() - statSync(existsSync(target) ? target : path).mtimeMs;
-    }
-    catch {
-        return 0;
-    }
-}
-// Reclamation is bound to the exact instance it observed: it unlinks ONLY that
-// token's marker, then removes the now-empty directory with an empty-guarded
-// rmdir. A successor lock holds a different random token (a different marker
-// name), so a lagging reclaimer that saw the old stale lock can never strip a
-// live successor — its unlink targets a name that no longer exists.
-function reclaimIfStale(path, staleMs) {
-    const token = observedMarkerToken(path);
-    if (lockAge(path, token) <= staleMs)
-        return;
-    if (token !== null) {
-        try {
-            unlinkSync(markerPath(path, token));
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                return;
-            throw error;
-        }
-    }
-    try {
-        rmdirSync(path);
-    }
-    catch (error) {
-        const code = error.code;
-        if (code !== 'ENOENT' && code !== 'ENOTEMPTY' && code !== 'EEXIST')
-            throw error;
-    }
-}
-function tryAcquireDirectoryLock(path, staleMs) {
-    const token = randomUUID();
-    try {
-        mkdirSync(path, { mode: 0o700 });
-        writeFileSync(markerPath(path, token), '', { flag: 'wx', mode: 0o600 });
-        return { path, token };
-    }
-    catch (error) {
-        if (error.code !== 'EEXIST')
-            throw error;
-        reclaimIfStale(path, staleMs);
-        return null;
-    }
-}
-function acquireDirectoryLock(path, staleMs, timeoutMs) {
-    const startedAt = Date.now();
-    while (true) {
-        const lock = tryAcquireDirectoryLock(path, staleMs);
-        if (lock !== null)
-            return lock;
-        if (Date.now() - startedAt >= timeoutMs)
-            throw new Error('exclusive operation lock acquisition timed out');
-        pause(5);
-    }
-}
-async function acquireDirectoryLockAsync(path, staleMs, timeoutMs) {
-    const startedAt = Date.now();
-    while (true) {
-        const lock = tryAcquireDirectoryLock(path, staleMs);
-        if (lock !== null)
-            return lock;
-        if (Date.now() - startedAt >= timeoutMs)
-            throw new Error('exclusive operation lock acquisition timed out');
-        await new Promise((resolvePromise) => setTimeout(resolvePromise, 10));
-    }
-}
-/** Runs a short filesystem transition under a token-checked, crash-reclaimable directory lock. */
-export function withExclusiveDirectoryLock(path, operation, options = {}) {
-    const lock = acquireDirectoryLock(path, options.staleMs ?? 30_000, options.timeoutMs ?? 5_000);
-    try {
-        return operation();
-    }
-    finally {
-        releaseDirectoryLock(lock);
-    }
-}
-/** Async counterpart heartbeats while its operation runs, so a valid long handler is never stolen. */
-export async function withExclusiveDirectoryLockAsync(path, operation, options = {}) {
-    const staleMs = options.staleMs ?? 35_000;
-    const lock = await acquireDirectoryLockAsync(path, staleMs, options.timeoutMs ?? staleMs + 5_000);
-    const heartbeat = setInterval(() => {
-        if (ownsLock(lock)) {
-            try {
-                utimesSync(markerPath(lock.path, lock.token), new Date(), new Date());
-            }
-            catch { /* a reclaimed lock is no longer ours */ }
-        }
-    }, 1_000);
-    try {
-        return await operation();
-    }
-    finally {
-        clearInterval(heartbeat);
-        releaseDirectoryLock(lock);
-    }
-}
-// Kept for the existing panel until H2 routes all finalization through tickets.ts.
 export function writeResponse(dir, responses, completedAt, deck) {
     const summary = deck === undefined ? '' : buildSummary(deck, responses);
     atomicWriteJson(responsePath(dir), { schema: 'humanloop.response/v2', kind: 'deck', responses, summary, completedAt });

package/dist/core/io.d.ts

@@ -1,6 +1,29 @@
 import { CrtrError } from './errors.js';
 import { type ExitCodeValue } from '../types.js';
 import { ApiError } from '../api/index.js';
+/** The private result mirror for one crtr CLI invocation launched by the
+ * canvas bash-preview extension. This deliberately never enters stdout: bash
+ * text is model context, while Pi tool-result details are viewer-only. */
+export interface CrtrPreviewRecord {
+    path: string;
+    result?: Record<string, unknown>;
+    jsonl?: Record<string, unknown>[];
+    error?: ErrorPayload;
+}
+/** Begin collecting the current leaf's structured response, if its caller
+ * supplied the private per-tool-call result path. */
+export declare function beginPreview(path: string): void;
+/** Publish the single-object or collected JSONL result after leaf dispatch. */
+export declare function publishPreviewResult(result: Record<string, unknown> | void): void;
+/** Mirror a structured record whose caller renders it itself instead of using
+ * the generic dispatcher (JSONL and event-stream leaves). */
+export declare function recordPreviewLine(obj: Record<string, unknown>): void;
+/** Preserve a verbatim JSONL stream's structured frames without changing the
+ * bytes written to stdout. Invalid third-party lines remain raw-only. */
+export declare function recordPreviewJsonLine(line: string): void;
+/** Record a terminal streaming failure that correctly remains off stdout
+ * because prior frames have already been delivered. */
+export declare function recordPreviewError(payload: ErrorPayload): void;
 /** Set by the dispatcher when `--json` is present anywhere in argv. */
 export declare function setJsonOutput(v: boolean): void;
 /** True when the caller asked for raw JSON instead of rendered prose. */

package/dist/core/io.js

@@ -3,6 +3,7 @@
 // the model, not data it parses); structured errors; stderr is diagnostics only
 // and never carries the result. The raw JSON object is available behind the
 // `--json` global for tooling. See the cli-design reference.
+import { renameSync, writeFileSync } from 'node:fs';
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
 import { renderError } from './render.js';
@@ -11,6 +12,62 @@ import { ApiError } from '../api/index.js';
 // output mode — prose (default) vs raw JSON (--json global, for tooling)
 // ---------------------------------------------------------------------------
 let jsonOutput = false;
+let preview;
+/** Begin collecting the current leaf's structured response, if its caller
+ * supplied the private per-tool-call result path. */
+export function beginPreview(path) {
+    const resultPath = process.env['CRTR_PREVIEW_RESULT_PATH'];
+    preview = resultPath === undefined || resultPath === '' ? undefined : { path, jsonl: [] };
+}
+function publishPreview(record) {
+    const resultPath = process.env['CRTR_PREVIEW_RESULT_PATH'];
+    if (resultPath === undefined || resultPath === '')
+        return;
+    const tempPath = `${resultPath}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tempPath, `${JSON.stringify({ path: preview?.path ?? '', ...record })}\n`, 'utf8');
+        renameSync(tempPath, resultPath);
+    }
+    catch {
+        // Preview transport is optional UI metadata. Its failure must never alter
+        // the CLI's stdout/error contract.
+        try {
+            writeFileSync(tempPath, '', 'utf8');
+        }
+        catch { /* nothing to clean */ }
+    }
+}
+/** Publish the single-object or collected JSONL result after leaf dispatch. */
+export function publishPreviewResult(result) {
+    if (preview === undefined)
+        return;
+    if (result !== undefined && result !== null)
+        publishPreview({ result });
+    else if (preview.jsonl.length > 0 || preview.error !== undefined) {
+        publishPreview({ ...(preview.jsonl.length > 0 ? { jsonl: preview.jsonl } : {}), ...(preview.error === undefined ? {} : { error: preview.error }) });
+    }
+}
+/** Mirror a structured record whose caller renders it itself instead of using
+ * the generic dispatcher (JSONL and event-stream leaves). */
+export function recordPreviewLine(obj) {
+    preview?.jsonl.push(obj);
+}
+/** Preserve a verbatim JSONL stream's structured frames without changing the
+ * bytes written to stdout. Invalid third-party lines remain raw-only. */
+export function recordPreviewJsonLine(line) {
+    try {
+        const value = JSON.parse(line);
+        if (value !== null && typeof value === 'object' && !Array.isArray(value))
+            recordPreviewLine(value);
+    }
+    catch { /* a malformed remote frame remains the command's raw truth */ }
+}
+/** Record a terminal streaming failure that correctly remains off stdout
+ * because prior frames have already been delivered. */
+export function recordPreviewError(payload) {
+    if (preview !== undefined)
+        preview.error = payload;
+}
 /** Set by the dispatcher when `--json` is present anywhere in argv. */
 export function setJsonOutput(v) {
     jsonOutput = v;
@@ -88,6 +145,7 @@ export function emit(obj) {
 }
 /** One JSONL record. Call per event in a stream; partial reads stay parseable. */
 export function emitLine(obj) {
+    recordPreviewLine(obj);
     process.stdout.write(JSON.stringify(obj) + '\n');
 }
 /**
@@ -234,6 +292,8 @@ export function handle(e) {
     }
     if (e instanceof CrtrError) {
         const payload = payloadOf(e);
+        if (preview !== undefined)
+            publishPreview({ error: payload });
         const out = jsonOutput
             ? JSON.stringify(payload, null, 2)
             : renderError(payload);

package/dist/core/preview-registry.d.ts

@@ -23,8 +23,13 @@ export interface SummaryLine {
     text: string;
     tone?: SummaryTone;
 }
-/** Dispatch a command's argv tokens + its raw result text to the summarizer
- *  that owns that leaf path (longest-registered-prefix match, same shape as
- *  suppressOutputForPath), or null when no command owns a summary — the
- *  caller falls through to generic truncation in that case. */
-export declare function summarizePath(tokens: readonly string[], rawText: string): SummaryLine[] | null;
+export interface CrtrPreview {
+    path: string;
+    result?: Record<string, unknown>;
+    jsonl?: Record<string, unknown>[];
+    error?: Record<string, unknown>;
+}
+/** Summarize an exact CLI result record. The recorded path is authoritative:
+ * shell tokenization is used only for an invocation's static icon/help chrome,
+ * never to identify or decode the returned leaf data. */
+export declare function summarizePath(preview: CrtrPreview, tokens?: readonly string[]): SummaryLine[] | null;