@orcareplay/shell-shim 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './resolve.js';
+export * from './runner.js';
+export * from './install.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './resolve.js';
+export * from './runner.js';
+export * from './install.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/install.d.ts

@@ -0,0 +1,37 @@
+import type { ShellFrame } from './runner.js';
+/** Shells an agent actually reaches for. Shimming more binaries buys detail and costs blast radius. */
+export declare const DEFAULT_SHIMS: readonly ["sh", "bash"];
+export interface InstallOptions {
+    runDir: string;
+    /** Defaults to `<runDir>/shell-frames.jsonl`. */
+    framesPath?: string;
+    shims?: readonly string[];
+}
+export interface InstalledShim {
+    /** Prepend this to PATH. */
+    dir: string;
+    framesPath: string;
+    shimmed: string[];
+    /** Environment overlay the child needs for the shims to work. */
+    env: Record<string, string>;
+}
+/**
+ * Write a directory of shim executables to prepend to PATH.
+ *
+ * On POSIX, each shim is a small shell script whose shebang names an absolute interpreter, so it
+ * never consults PATH to start — and PATH is exactly where our own shims live. Windows cannot
+ * execute an extensionless script from PATH, so it gets a `.cmd` shim with the same argv contract.
+ */
+export declare function installShellShim(options: InstallOptions): Promise<InstalledShim>;
+/** Read back what the shims observed. Tolerates a partial final line, like events.jsonl. */
+export declare function readShellFrames(framesPath: string): Promise<ShellFrame[]>;
+/**
+ * Locate the compiled shim entry point.
+ *
+ * This module is loaded from `dist/` in a real install but from `src/` when the workspace aliases
+ * packages to source, and only the compiled `.js` can actually be exec'd. Resolving by probing
+ * rather than assuming means the shim works in both, and fails with a sentence instead of an
+ * empty stdout when it works in neither.
+ */
+export declare function resolveRunnerBin(): Promise<string>;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,uGAAuG;AACvG,eAAO,MAAM,aAAa,yBAA0B,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAyCtF;AAED,4FAA4F;AAC5F,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAY/E;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAkBxD"}

package/dist/install.js

@@ -0,0 +1,97 @@
+import { access, chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+/** Shells an agent actually reaches for. Shimming more binaries buys detail and costs blast radius. */
+export const DEFAULT_SHIMS = ['sh', 'bash'];
+/**
+ * Write a directory of shim executables to prepend to PATH.
+ *
+ * On POSIX, each shim is a small shell script whose shebang names an absolute interpreter, so it
+ * never consults PATH to start — and PATH is exactly where our own shims live. Windows cannot
+ * execute an extensionless script from PATH, so it gets a `.cmd` shim with the same argv contract.
+ */
+export async function installShellShim(options) {
+    const dir = join(options.runDir, 'shims');
+    const framesPath = options.framesPath ?? join(options.runDir, 'shell-frames.jsonl');
+    const shims = options.shims ?? DEFAULT_SHIMS;
+    await mkdir(dir, { recursive: true });
+    const runner = await resolveRunnerBin();
+    const node = process.execPath;
+    const windows = process.platform === 'win32';
+    for (const name of shims) {
+        const script = windows
+            ? [
+                '@echo off',
+                'rem Written by orca record. Runs the real binary and notes what happened.',
+                `${quoteCmd(node)} ${quoteCmd(runner)} ${quoteCmd(name)} ${quoteCmd(dir)} ${quoteCmd(framesPath)} -- %*`,
+                'exit /b %ERRORLEVEL%',
+                '',
+            ].join('\r\n')
+            : [
+                '#!/bin/sh',
+                '# Written by orca record. Runs the real binary and notes what happened.',
+                `exec ${quotePosix(node)} ${quotePosix(runner)} ${quotePosix(name)} ${quotePosix(dir)} ${quotePosix(framesPath)} -- "$@"`,
+                '',
+            ].join('\n');
+        const path = join(dir, windows ? `${name}.cmd` : name);
+        await writeFile(path, script, { mode: 0o755 });
+        await chmod(path, 0o755);
+    }
+    await writeFile(framesPath, '', { flag: 'a', mode: 0o600 }).catch(() => {
+        // An unwritable frames file must not stop the run; the shim swallows write errors too.
+    });
+    return {
+        dir,
+        framesPath,
+        shimmed: [...shims],
+        env: { ORCA_SHIM_DIR: dir, ORCA_SHIM_FRAMES: framesPath },
+    };
+}
+/** Read back what the shims observed. Tolerates a partial final line, like events.jsonl. */
+export async function readShellFrames(framesPath) {
+    const raw = await readFile(framesPath, 'utf8').catch(() => '');
+    const frames = [];
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            frames.push(JSON.parse(line));
+        }
+        catch {
+            // A process killed mid-write leaves a partial line. That is the run we most want to read.
+        }
+    }
+    return frames;
+}
+/**
+ * Locate the compiled shim entry point.
+ *
+ * This module is loaded from `dist/` in a real install but from `src/` when the workspace aliases
+ * packages to source, and only the compiled `.js` can actually be exec'd. Resolving by probing
+ * rather than assuming means the shim works in both, and fails with a sentence instead of an
+ * empty stdout when it works in neither.
+ */
+export async function resolveRunnerBin() {
+    const candidates = [
+        new URL('./runner-bin.js', import.meta.url),
+        new URL('../dist/runner-bin.js', import.meta.url),
+    ].map((url) => fileURLToPath(url));
+    for (const candidate of candidates) {
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch {
+            // try the next layout
+        }
+    }
+    throw new Error(`orca shell-shim: no compiled runner found (looked in ${candidates.join(', ')})\n` +
+        '  run `npm run build` before recording with shell capture');
+}
+function quotePosix(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function quoteCmd(value) {
+    return `"${value.replace(/"/g, '""')}"`;
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}

package/dist/resolve.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Find the real binary a shim is standing in for.
+ *
+ * The shim directory is prepended to PATH, so the one thing this must never do is return the
+ * shim itself: that is an exec loop, and it would happen inside the user's agent run rather than
+ * anywhere convenient. Comparison is by resolved real path, because PATH routinely contains the
+ * same directory spelled several ways (`/x`, `/x/.`, a symlink) and a string compare misses those.
+ */
+export declare function resolveRealBinary(name: string, pathVar: string, shimDir: string): Promise<string | undefined>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgB7B"}

package/dist/resolve.js

@@ -0,0 +1,62 @@
+import { access, constants, realpath, stat } from 'node:fs/promises';
+import { delimiter, extname, join, resolve } from 'node:path';
+/**
+ * Find the real binary a shim is standing in for.
+ *
+ * The shim directory is prepended to PATH, so the one thing this must never do is return the
+ * shim itself: that is an exec loop, and it would happen inside the user's agent run rather than
+ * anywhere convenient. Comparison is by resolved real path, because PATH routinely contains the
+ * same directory spelled several ways (`/x`, `/x/.`, a symlink) and a string compare misses those.
+ */
+export async function resolveRealBinary(name, pathVar, shimDir) {
+    const shimReal = await safeRealpath(resolve(shimDir));
+    for (const entry of pathVar.split(delimiter)) {
+        if (entry === '')
+            continue;
+        const dirReal = await safeRealpath(resolve(entry));
+        if (dirReal !== undefined && shimReal !== undefined && dirReal === shimReal)
+            continue;
+        for (const candidateName of candidateNames(name)) {
+            const candidate = join(entry, candidateName);
+            if (await isExecutableFile(candidate))
+                return candidate;
+        }
+    }
+    // Deliberately undefined rather than a guess: exec'ing the wrong binary is worse than a clear
+    // error the caller can report.
+    return undefined;
+}
+async function safeRealpath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function isExecutableFile(path) {
+    try {
+        // Windows does not expose POSIX execute bits. The extension/PATHEXT lookup above is the
+        // executable check there; stat keeps a valid .exe/.cmd/.bat discoverable on that platform.
+        if (process.platform === 'win32')
+            return (await stat(path)).isFile();
+        await access(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function candidateNames(name) {
+    if (process.platform !== 'win32' || extname(name) !== '')
+        return [name];
+    const pathext = process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD';
+    return [
+        name,
+        ...pathext
+            .split(';')
+            .filter(Boolean)
+            .map((ext) => `${name}${ext.toLowerCase()}`),
+    ];
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAY,EACZ,OAAe,EACf,OAAe;IAEf,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAEtD,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,IAAI,KAAK,KAAK,EAAE;YAAE,SAAS;QAC3B,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACnD,IAAI,OAAO,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,QAAQ;YAAE,SAAS;QAEtF,KAAK,MAAM,aAAa,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;YACjD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;YAC7C,IAAI,MAAM,gBAAgB,CAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,8FAA8F;IAC9F,+BAA+B;IAC/B,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,IAAY;IACtC,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,IAAY;IAC1C,IAAI,CAAC;QACH,wFAAwF;QACxF,2FAA2F;QAC3F,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACrE,MAAM,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,qBAAqB,CAAC;IAC7D,OAAO;QACL,IAAI;QACJ,GAAG,OAAO;aACP,KAAK,CAAC,GAAG,CAAC;aACV,MAAM,CAAC,OAAO,CAAC;aACf,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;KAC/C,CAAC;AACJ,CAAC"}

package/dist/runner-bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=runner-bin.d.ts.map

package/dist/runner-bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-bin.d.ts","sourceRoot":"","sources":["../src/runner-bin.ts"],"names":[],"mappings":""}

package/dist/runner-bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from './runner.js';
+process.exitCode = await main(process.argv.slice(2));
+//# sourceMappingURL=runner-bin.js.map

package/dist/runner-bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-bin.js","sourceRoot":"","sources":["../src/runner-bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,OAAO,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/runner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * What the shim records about one shell invocation.
+ *
+ * Deliberately not the output itself. The model already sees a rendering of stdout via the tool
+ * result; what it never sees — and what the protocol layer therefore cannot recover — is the exit
+ * code, the wall duration, the real argv, and which stream each byte came out of.
+ */
+export interface ShellFrame {
+    name: string;
+    argv: string[];
+    cwd: string;
+    exitCode: number;
+    signal: string | null;
+    startedAt: string;
+    durationMs: number;
+    stdoutBytes: number;
+    stderrBytes: number;
+}
+export interface RunShimOptions {
+    name: string;
+    argv: string[];
+    shimDir: string;
+    framesPath: string;
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * Stand in for one shell binary: run the real one, forward everything, write down what happened.
+ *
+ * Two rules, both about not being noticed. The passthrough must be byte-faithful, so stdio is
+ * inherited outright rather than piped — piping would let us count bytes but would also strip the
+ * TTY, and a harness that checks `isatty` would change its behaviour because we were watching.
+ * And every capture-side failure is swallowed: losing a frame costs a line in the trace, whereas
+ * throwing here breaks the command the user was actually running.
+ */
+export declare function runShim(options: RunShimOptions): Promise<number>;
+/**
+ * Entry point the generated shim scripts call:
+ * `node runner-bin.js <name> <shimDir> <framesPath> -- [args...]`
+ *
+ * The three shim parameters arrive as argv, not environment. An agent is entitled to sanitise the
+ * environment of the commands it runs, and if it did, an env-carried shim would keep working while
+ * silently capturing nothing — the exact failure mode this whole layer exists to avoid.
+ */
+export declare function main(argv: string[]): Promise<number>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAoEtE;AAYD;;;;;;;GAOG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmB1D"}

package/dist/runner.js

@@ -0,0 +1,105 @@
+import { spawn } from 'node:child_process';
+import { appendFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { resolveRealBinary } from './resolve.js';
+/**
+ * Stand in for one shell binary: run the real one, forward everything, write down what happened.
+ *
+ * Two rules, both about not being noticed. The passthrough must be byte-faithful, so stdio is
+ * inherited outright rather than piped — piping would let us count bytes but would also strip the
+ * TTY, and a harness that checks `isatty` would change its behaviour because we were watching.
+ * And every capture-side failure is swallowed: losing a frame costs a line in the trace, whereas
+ * throwing here breaks the command the user was actually running.
+ */
+export async function runShim(options) {
+    const real = await resolveRealBinary(options.name, options.env.PATH ?? '', options.shimDir);
+    if (real === undefined) {
+        process.stderr.write(`orca shell-shim: cannot find the real "${options.name}" on PATH.\n` +
+            `  the shim directory is ${options.shimDir}\n` +
+            `  re-run without recording, or report this with your PATH\n`);
+        return 127;
+    }
+    const startedAt = new Date();
+    const startedNs = process.hrtime.bigint();
+    // Counting bytes requires piping, which removes the TTY. Only do it when there is no TTY to
+    // remove — under `orca record` the agent has already given us pipes, which is the case we care
+    // about, and an interactive terminal keeps its exact behaviour.
+    const canCount = !process.stdout.isTTY && !process.stderr.isTTY;
+    const child = spawn(real, options.argv, {
+        env: options.env,
+        stdio: canCount ? ['inherit', 'pipe', 'pipe'] : 'inherit',
+    });
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    if (canCount) {
+        child.stdout?.on('data', (chunk) => {
+            stdoutBytes += chunk.length;
+            process.stdout.write(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderrBytes += chunk.length;
+            process.stderr.write(chunk);
+        });
+    }
+    const forward = (signal) => () => child.kill(signal);
+    const onInt = forward('SIGINT');
+    const onTerm = forward('SIGTERM');
+    process.on('SIGINT', onInt);
+    process.on('SIGTERM', onTerm);
+    const { code, signal } = await new Promise((resolve) => {
+        child.on('error', (err) => {
+            process.stderr.write(`orca shell-shim: could not run ${real}: ${String(err)}\n`);
+            resolve({ code: 127, signal: null });
+        });
+        child.on('close', (c, s) => resolve({ code: c ?? 0, signal: s }));
+    });
+    process.off('SIGINT', onInt);
+    process.off('SIGTERM', onTerm);
+    record(options.framesPath, {
+        name: options.name,
+        argv: options.argv,
+        cwd: process.cwd(),
+        exitCode: code,
+        signal,
+        startedAt: startedAt.toISOString(),
+        durationMs: Number((process.hrtime.bigint() - startedNs) / 1000000n),
+        stdoutBytes,
+        stderrBytes,
+    });
+    return code;
+}
+function record(framesPath, frame) {
+    try {
+        // Synchronous and append-only: the process is about to exit, and a lost write here would be
+        // invisible. One line per invocation keeps the file greppable like events.jsonl.
+        appendFileSync(framesPath, `${JSON.stringify(frame)}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Capture is best-effort by design. See the note on runShim.
+    }
+}
+/**
+ * Entry point the generated shim scripts call:
+ * `node runner-bin.js <name> <shimDir> <framesPath> -- [args...]`
+ *
+ * The three shim parameters arrive as argv, not environment. An agent is entitled to sanitise the
+ * environment of the commands it runs, and if it did, an env-carried shim would keep working while
+ * silently capturing nothing — the exact failure mode this whole layer exists to avoid.
+ */
+export async function main(argv) {
+    const separator = argv.indexOf('--');
+    const [name, shimDir, framesPath] = separator === -1 ? [argv[0], argv[1], argv[2]] : argv.slice(0, separator);
+    const rest = separator === -1 ? argv.slice(3) : argv.slice(separator + 1);
+    if (!name || !shimDir || !framesPath) {
+        process.stderr.write('orca shell-shim: invoked without its shim parameters; not launched by orca record\n');
+        return 127;
+    }
+    return runShim({
+        name: basename(name),
+        argv: rest,
+        shimDir,
+        framesPath,
+        env: process.env,
+    });
+}
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@orcareplay/shell-shim",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@orcareplay/schema": "0.1.0"
+  }
+}