@jini-ai/platform 0.1.0

package/dist/sandbox-env.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Names the environment variables and on-disk naming this port reads/writes.
+ * A consumer supplies its own env-var names and config-directory name — see
+ * `source-map.md` for the values a real adapter (e.g. the OD adapter) uses.
+ */
+export interface SandboxEnvConfig {
+    /** Env var gating whether sandboxing is on (truthy/falsy string). */
+    modeEnvVar: string;
+    /** Env var carrying a PATH-delimiter-separated list of allowed import roots. */
+    importAllowedRootsEnvVar: string;
+    /** Env var carrying the sandbox data directory (required when sandboxing is on). */
+    dataDirEnvVar: string;
+    /** Env var the spawned process reads back for its agent-home directory. */
+    agentHomeEnvVar: string;
+    /** Env var the spawned process reads back for its local agent-profiles config path. */
+    agentProfilesConfigEnvVar: string;
+    /** Sub-directory name (under the agent home) local agent-profile config lives in. */
+    agentProfilesDirName: string;
+}
+export interface SandboxRuntimeRoots {
+    agentHomeDir: string;
+    cacheDir: string;
+    configDir: string;
+    generatedFilesDir: string;
+    logsDir: string;
+    mcpConfigDir: string;
+    pluginStateDir: string;
+    previewStateDir: string;
+    skillsCacheDir: string;
+    tempDir: string;
+    toolConfigDir: string;
+}
+export interface SandboxRuntimeConfig {
+    enabled: boolean;
+    dataDir: string;
+    roots: SandboxRuntimeRoots;
+}
+/**
+ * Reads {@link SandboxEnvConfig.modeEnvVar} and interprets it as a boolean
+ * flag. Throws if the value is set but neither a recognized truthy nor
+ * falsy spelling.
+ */
+export declare function isSandboxModeEnabled(config: SandboxEnvConfig, env?: Record<string, string | undefined>): boolean;
+/**
+ * The configured, canonicalized set of directories an imported project root
+ * is allowed to live under while sandboxing is on.
+ */
+export declare function sandboxImportAllowedRoots(config: SandboxEnvConfig, env?: Record<string, string | undefined>): string[];
+/**
+ * Whether `projectRoot` may be used as an imported-folder project while
+ * sandboxing is enabled. Always `true` when sandboxing is off.
+ */
+export declare function isSandboxImportedProjectRootAllowed(config: SandboxEnvConfig, projectRoot: string, env?: Record<string, string | undefined>): boolean;
+/**
+ * A human-readable reason `projectRoot` is unavailable under sandboxing, or
+ * `null` when it's allowed (including when sandboxing is off).
+ */
+export declare function sandboxImportedProjectRootUnavailableReason(config: SandboxEnvConfig, projectRoot: string, env?: Record<string, string | undefined>): string | null;
+/**
+ * Derives the full sandbox directory tree from a data directory. Pure —
+ * does not touch the filesystem (see {@link ensureSandboxRuntimeDirs}).
+ */
+export declare function resolveSandboxRuntimeConfig(enabled: boolean, dataDir: string): SandboxRuntimeConfig;
+/**
+ * Resolves the sandbox runtime config from environment variables, or `null`
+ * when sandboxing is off. Throws when sandboxing is on but the data-dir env
+ * var is unset.
+ */
+export declare function resolveSandboxRuntimeConfigFromEnv(config: SandboxEnvConfig, env: Record<string, string | undefined>, projectRoot: string): SandboxRuntimeConfig | null;
+/**
+ * The path a spawned agent process's local agent-profiles config lives at,
+ * under its sandboxed agent-home directory.
+ */
+export declare function sandboxAgentProfilesConfigPath(config: SandboxEnvConfig, runtime: SandboxRuntimeConfig): string;
+/**
+ * Creates every directory in the sandbox tree (idempotent). No-op when
+ * sandboxing is disabled.
+ */
+export declare function ensureSandboxRuntimeDirs(runtime: SandboxRuntimeConfig): void;
+/**
+ * Overlays sandboxed HOME/XDG/TMPDIR/tool-config env vars onto `baseEnv` for
+ * a spawned agent process. Returns `baseEnv` unchanged when sandboxing is
+ * disabled.
+ */
+export declare function applySandboxRuntimeEnv(config: SandboxEnvConfig, baseEnv: NodeJS.ProcessEnv, runtime: SandboxRuntimeConfig): NodeJS.ProcessEnv;
+//# sourceMappingURL=sandbox-env.d.ts.map

package/dist/sandbox-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-env.d.ts","sourceRoot":"","sources":["../src/sandbox-env.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,wBAAwB,EAAE,MAAM,CAAC;IACjC,oFAAoF;IACpF,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,eAAe,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,yBAAyB,EAAE,MAAM,CAAC;IAClC,qFAAqF;IACrF,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,mBAAmB,CAAC;CAC5B;AAKD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,OAAO,CAUT;AAkED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,gBAAgB,EACxB,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,EAAE,CAEV;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,MAAM,EACnB,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,OAAO,CAIT;AAED;;;GAGG;AACH,wBAAgB,2CAA2C,CACzD,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,MAAM,EACnB,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,GAAG,IAAI,CAMf;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,oBAAoB,CAmBnG;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,WAAW,EAAE,MAAM,GAClB,oBAAoB,GAAG,IAAI,CAO7B;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,oBAAoB,GAC5B,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAK5E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,CAAC,UAAU,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,MAAM,CAAC,UAAU,CA8BnB"}

package/dist/sandbox-env.js

@@ -0,0 +1,215 @@
+/**
+ * @module sandbox-env
+ *
+ * Sandboxed agent-execution environment: an isolated directory tree (agent
+ * home, cache, config, temp, …) plus the environment-variable overrides that
+ * redirect a spawned agent process's HOME/XDG/TMPDIR into it, and a policy
+ * gate for whether an imported (non-managed) project root may be used while
+ * sandboxing is on.
+ *
+ * Generalized from an upstream flat daemon module: the origin hardcoded its
+ * host product's env-var names and a product-branded config sub-directory.
+ * Every one of those is now a field on {@link SandboxEnvConfig} so a
+ * consumer isn't branded — see `source-map.md` for the exact mapping.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveProjectRelativePath } from './home-expansion.js';
+const TRUTHY_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSY_VALUES = new Set(['0', 'false', 'no', 'off', '']);
+/**
+ * Reads {@link SandboxEnvConfig.modeEnvVar} and interprets it as a boolean
+ * flag. Throws if the value is set but neither a recognized truthy nor
+ * falsy spelling.
+ */
+export function isSandboxModeEnabled(config, env = process.env) {
+    const raw = env[config.modeEnvVar];
+    if (typeof raw !== 'string')
+        return false;
+    const value = raw.trim().toLowerCase();
+    if (TRUTHY_VALUES.has(value))
+        return true;
+    if (FALSY_VALUES.has(value))
+        return false;
+    throw new Error(`${config.modeEnvVar} must be one of ${Array.from(TRUTHY_VALUES).join(', ')} ` +
+        `or ${Array.from(FALSY_VALUES).join(', ')}`);
+}
+function configuredSandboxImportRoots(config, env) {
+    const raw = env[config.importAllowedRootsEnvVar];
+    if (typeof raw !== 'string' || !raw.trim())
+        return [];
+    const roots = raw
+        .split(path.delimiter)
+        .map((part) => part.trim())
+        .filter(Boolean);
+    const relativeRoot = roots.find((root) => !path.isAbsolute(path.normalize(root)));
+    if (relativeRoot) {
+        throw new Error(`${config.importAllowedRootsEnvVar} entries must be absolute paths. Got: ${relativeRoot}`);
+    }
+    return roots;
+}
+function canonicalizePathForContainment(value) {
+    const resolved = path.normalize(value);
+    try {
+        return fs.realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+// A containment *candidate* (e.g. a project root that hasn't been imported/
+// created yet) may not fully exist on disk, so a bare realpath attempt
+// throws. Unlike `canonicalizePathForContainment` above — used only for the
+// *configured allowed roots*, which are expected to already exist when they
+// matter — this walks up to the nearest existing ancestor, realpaths that,
+// and rejoins the not-yet-existing suffix. Without this, comparing a raw
+// candidate against a realpath'd allowed root misfires whenever the roots
+// sit under a symlinked prefix (macOS's /tmp -> /private/tmp, /var ->
+// /private/var): the candidate would keep the raw prefix while the allowed
+// root was resolved through the symlink, so a legitimately-nested path
+// would look like it climbs above the root.
+function canonicalizeContainmentCandidate(value) {
+    const resolved = path.normalize(value);
+    let existing = resolved;
+    const trailingSegments = [];
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync.native(existing), ...trailingSegments);
+        }
+        catch {
+            // `path.dirname(x) === x` is the fixed point for both an absolute
+            // filesystem root ('/') and a relative reference ('.') — walking
+            // further would just retry the same path forever, so bail out to the
+            // raw normalized value instead of looping.
+            const parent = path.dirname(existing);
+            if (parent === existing)
+                return resolved;
+            trailingSegments.unshift(path.basename(existing));
+            existing = parent;
+        }
+    }
+}
+function isPathInsideDir(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+/**
+ * The configured, canonicalized set of directories an imported project root
+ * is allowed to live under while sandboxing is on.
+ */
+export function sandboxImportAllowedRoots(config, env = process.env) {
+    return configuredSandboxImportRoots(config, env).map(canonicalizePathForContainment);
+}
+/**
+ * Whether `projectRoot` may be used as an imported-folder project while
+ * sandboxing is enabled. Always `true` when sandboxing is off.
+ */
+export function isSandboxImportedProjectRootAllowed(config, projectRoot, env = process.env) {
+    if (!isSandboxModeEnabled(config, env))
+        return true;
+    const candidate = canonicalizeContainmentCandidate(projectRoot);
+    return sandboxImportAllowedRoots(config, env).some((root) => isPathInsideDir(root, candidate));
+}
+/**
+ * A human-readable reason `projectRoot` is unavailable under sandboxing, or
+ * `null` when it's allowed (including when sandboxing is off).
+ */
+export function sandboxImportedProjectRootUnavailableReason(config, projectRoot, env = process.env) {
+    if (!isSandboxModeEnabled(config, env))
+        return null;
+    return isSandboxImportedProjectRootAllowed(config, projectRoot, env)
+        ? null
+        : `Imported-folder projects are not available in ${config.modeEnvVar} unless their root is ` +
+            `under ${config.importAllowedRootsEnvVar}.`;
+}
+/**
+ * Derives the full sandbox directory tree from a data directory. Pure —
+ * does not touch the filesystem (see {@link ensureSandboxRuntimeDirs}).
+ */
+export function resolveSandboxRuntimeConfig(enabled, dataDir) {
+    const sandboxRoot = path.join(dataDir, 'sandbox');
+    return {
+        enabled,
+        dataDir,
+        roots: {
+            agentHomeDir: path.join(sandboxRoot, 'agent-home'),
+            cacheDir: path.join(sandboxRoot, 'cache'),
+            configDir: path.join(sandboxRoot, 'config'),
+            generatedFilesDir: path.join(dataDir, 'generated-files'),
+            logsDir: path.join(dataDir, 'logs'),
+            mcpConfigDir: dataDir,
+            pluginStateDir: path.join(dataDir, 'plugins'),
+            previewStateDir: path.join(dataDir, 'previews'),
+            skillsCacheDir: path.join(dataDir, 'skills'),
+            tempDir: path.join(sandboxRoot, 'tmp'),
+            toolConfigDir: path.join(sandboxRoot, 'tools'),
+        },
+    };
+}
+/**
+ * Resolves the sandbox runtime config from environment variables, or `null`
+ * when sandboxing is off. Throws when sandboxing is on but the data-dir env
+ * var is unset.
+ */
+export function resolveSandboxRuntimeConfigFromEnv(config, env, projectRoot) {
+    if (!isSandboxModeEnabled(config, env))
+        return null;
+    const rawDataDir = env[config.dataDirEnvVar]?.trim();
+    if (!rawDataDir) {
+        throw new Error(`${config.dataDirEnvVar} is required when ${config.modeEnvVar} is enabled`);
+    }
+    return resolveSandboxRuntimeConfig(true, resolveProjectRelativePath(rawDataDir, projectRoot));
+}
+/**
+ * The path a spawned agent process's local agent-profiles config lives at,
+ * under its sandboxed agent-home directory.
+ */
+export function sandboxAgentProfilesConfigPath(config, runtime) {
+    return path.join(runtime.roots.agentHomeDir, config.agentProfilesDirName, 'agents.local.json');
+}
+/**
+ * Creates every directory in the sandbox tree (idempotent). No-op when
+ * sandboxing is disabled.
+ */
+export function ensureSandboxRuntimeDirs(runtime) {
+    if (!runtime.enabled)
+        return;
+    for (const dir of new Set(Object.values(runtime.roots))) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Overlays sandboxed HOME/XDG/TMPDIR/tool-config env vars onto `baseEnv` for
+ * a spawned agent process. Returns `baseEnv` unchanged when sandboxing is
+ * disabled.
+ */
+export function applySandboxRuntimeEnv(config, baseEnv, runtime) {
+    if (!runtime.enabled)
+        return baseEnv;
+    const env = { ...baseEnv };
+    const { roots } = runtime;
+    const codexHome = path.join(roots.agentHomeDir, '.codex');
+    const claudeConfigDir = path.join(roots.configDir, 'claude');
+    const opencodeHome = path.join(roots.agentHomeDir, '.opencode');
+    const npmUserConfig = path.join(roots.toolConfigDir, 'npmrc');
+    env[config.modeEnvVar] = '1';
+    env[config.dataDirEnvVar] = runtime.dataDir;
+    env[config.agentHomeEnvVar] = roots.agentHomeDir;
+    env.HOME = roots.agentHomeDir;
+    env.USERPROFILE = roots.agentHomeDir;
+    env.XDG_CONFIG_HOME = roots.configDir;
+    env.XDG_CACHE_HOME = roots.cacheDir;
+    env.XDG_DATA_HOME = path.join(roots.configDir, 'data');
+    env.XDG_STATE_HOME = path.join(roots.configDir, 'state');
+    env.TMPDIR = roots.tempDir;
+    env.TEMP = roots.tempDir;
+    env.TMP = roots.tempDir;
+    env.CODEX_HOME = codexHome;
+    env.CLAUDE_CONFIG_DIR = claudeConfigDir;
+    env.OPENCODE_TEST_HOME = opencodeHome;
+    env[config.agentProfilesConfigEnvVar] = sandboxAgentProfilesConfigPath(config, runtime);
+    env.NPM_CONFIG_USERCONFIG = npmUserConfig;
+    env.npm_config_userconfig = npmUserConfig;
+    return env;
+}
+//# sourceMappingURL=sandbox-env.js.map

package/dist/sandbox-env.js.map

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

package/dist/shell.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module shell
+ *
+ * Buffered command execution that re-enters the user's login shell. A daemon
+ * process's own `PATH` frequently lacks entries a shell profile adds (a
+ * version manager's shims, a package-manager-installed CLI, a Homebrew
+ * prefix), so a plain `execFile` against a bare command name can fail even
+ * though the same command works fine in the user's terminal. Routing through
+ * `$SHELL -c "..."` re-sources that PATH before running the command.
+ *
+ * Depends on nothing else in this package; owns no process lifecycle beyond
+ * the single buffered child it spawns per call.
+ */
+import { type ExecFileOptions } from "node:child_process";
+export type BufferedCommandResult = {
+    code: string | number | null | undefined;
+    error: Error | null;
+    ok: boolean;
+    stderr: string;
+    stdout: string;
+};
+/**
+ * Run a command directly via `execFile`, buffering stdout/stderr and never
+ * rejecting — failures are reported through the returned `ok`/`error` fields.
+ *
+ * @param command - The executable to run.
+ * @param args - Arguments to pass to the executable.
+ * @param opts - `child_process.execFile` options (a 120s timeout and 1MiB
+ *   buffer apply unless overridden).
+ * @returns The buffered result.
+ */
+export declare function execFileBuffered(command: string, args: readonly string[], opts?: ExecFileOptions): Promise<BufferedCommandResult>;
+/**
+ * Run an arbitrary command re-entering the user's login shell (via
+ * `$SHELL -c`) so shell-profile-only `PATH` entries are visible, then buffer
+ * its output. Falls back to a direct `execFile` on Windows, where there is no
+ * equivalent login-shell PATH gap.
+ *
+ * @param command - The executable to run.
+ * @param args - Arguments to pass to the executable.
+ * @param opts - `child_process.execFile` options; `env` defaults to
+ *   `process.env` so the re-exported `PATH` above has a base to restore from.
+ * @returns The buffered result.
+ */
+export declare function execCommandViaLoginShell(command: string, args: readonly string[], opts?: ExecFileOptions): Promise<BufferedCommandResult>;
+//# sourceMappingURL=shell.d.ts.map

package/dist/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEpE,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACzC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,qBAAqB,CAAC,CAYhC;AAqBD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,qBAAqB,CAAC,CAUhC"}

package/dist/shell.js

@@ -0,0 +1,78 @@
+/**
+ * @module shell
+ *
+ * Buffered command execution that re-enters the user's login shell. A daemon
+ * process's own `PATH` frequently lacks entries a shell profile adds (a
+ * version manager's shims, a package-manager-installed CLI, a Homebrew
+ * prefix), so a plain `execFile` against a bare command name can fail even
+ * though the same command works fine in the user's terminal. Routing through
+ * `$SHELL -c "..."` re-sources that PATH before running the command.
+ *
+ * Depends on nothing else in this package; owns no process lifecycle beyond
+ * the single buffered child it spawns per call.
+ */
+import { execFile } from "node:child_process";
+/**
+ * Run a command directly via `execFile`, buffering stdout/stderr and never
+ * rejecting — failures are reported through the returned `ok`/`error` fields.
+ *
+ * @param command - The executable to run.
+ * @param args - Arguments to pass to the executable.
+ * @param opts - `child_process.execFile` options (a 120s timeout and 1MiB
+ *   buffer apply unless overridden).
+ * @returns The buffered result.
+ */
+export function execFileBuffered(command, args, opts = {}) {
+    return new Promise((resolve) => {
+        execFile(command, [...args], { timeout: 120_000, maxBuffer: 1024 * 1024, ...opts }, (error, stdout, stderr) => {
+            resolve({
+                code: error && "code" in error ? error.code : undefined,
+                error,
+                ok: !error,
+                stderr: String(stderr).trim(),
+                stdout: String(stdout).trim(),
+            });
+        });
+    });
+}
+/** @internal Single-quote a POSIX shell argument, escaping embedded single quotes. */
+function quotePosixShellArg(value) {
+    const text = String(value ?? "");
+    return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+/** @internal Join a command and its arguments into one quoted POSIX shell command line. */
+function buildShellCommandLine(command, args) {
+    return [command, ...args].map(quotePosixShellArg).join(" ");
+}
+/** @internal Wrap a shell command line so a non-login shell still sees the current `PATH`. */
+function buildLoginShellCommand(innerCommand) {
+    // Use a non-login shell and re-export PATH so test fakes and wrapped
+    // command shims remain visible; login shells often reset PATH from
+    // profile scripts.
+    return `export PATH=${quotePosixShellArg(process.env.PATH)}; ${innerCommand}`;
+}
+/**
+ * Run an arbitrary command re-entering the user's login shell (via
+ * `$SHELL -c`) so shell-profile-only `PATH` entries are visible, then buffer
+ * its output. Falls back to a direct `execFile` on Windows, where there is no
+ * equivalent login-shell PATH gap.
+ *
+ * @param command - The executable to run.
+ * @param args - Arguments to pass to the executable.
+ * @param opts - `child_process.execFile` options; `env` defaults to
+ *   `process.env` so the re-exported `PATH` above has a base to restore from.
+ * @returns The buffered result.
+ */
+export function execCommandViaLoginShell(command, args, opts = {}) {
+    if (process.platform === "win32")
+        return execFileBuffered(command, args, opts);
+    // `/bin/sh` is POSIX-guaranteed to exist; unlike a specific shell (zsh,
+    // bash), it is never absent on a POSIX host, so it is the only safe
+    // default for a product-neutral engine that can't assume its host's shell.
+    const shell = process.env.SHELL?.trim() || "/bin/sh";
+    return execFileBuffered(shell, ["-c", buildLoginShellCommand(buildShellCommandLine(command, args))], {
+        env: process.env,
+        ...opts,
+    });
+}
+//# sourceMappingURL=shell.js.map

package/dist/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,QAAQ,EAAwB,MAAM,oBAAoB,CAAC;AAUpE;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,IAAuB,EACvB,OAAwB,EAAE;IAE1B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YAC5G,OAAO,CAAC;gBACN,IAAI,EAAE,KAAK,IAAI,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;gBACvD,KAAK;gBACL,EAAE,EAAE,CAAC,KAAK;gBACV,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;gBAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;aAC9B,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,sFAAsF;AACtF,SAAS,kBAAkB,CAAC,KAAgC;IAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IACjC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AAC5C,CAAC;AAED,2FAA2F;AAC3F,SAAS,qBAAqB,CAAC,OAAe,EAAE,IAAuB;IACrE,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED,8FAA8F;AAC9F,SAAS,sBAAsB,CAAC,YAAoB;IAClD,qEAAqE;IACrE,mEAAmE;IACnE,mBAAmB;IACnB,OAAO,eAAe,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,YAAY,EAAE,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAe,EACf,IAAuB,EACvB,OAAwB,EAAE;IAE1B,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/E,wEAAwE;IACxE,oEAAoE;IACpE,2EAA2E;IAC3E,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IACrD,OAAO,gBAAgB,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,sBAAsB,CAAC,qBAAqB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE;QACnG,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,IAAI;KACR,CAAC,CAAC;AACL,CAAC"}

package/dist/terminal.d.ts

@@ -0,0 +1,137 @@
+/** A single running PTY child process, however the caller's backend spawns it. */
+export interface PtyProcess {
+    onData(cb: (chunk: string) => void): void;
+    onExit(cb: (event: {
+        exitCode: number;
+        signal?: number;
+    }) => void): void;
+    write(input: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+}
+export interface PtySpawnOptions {
+    name: string;
+    cols: number;
+    rows: number;
+    cwd: string;
+    env: Record<string, string>;
+}
+/** Spawns a PTY. The caller supplies this — e.g. a thin wrapper around `node-pty`'s `spawn`. */
+export type PtySpawn = (shell: string, args: string[], options: PtySpawnOptions) => PtyProcess;
+/**
+ * Resolves the candidate paths to node-pty's `spawn-helper` binary. On
+ * macOS/Linux, `pty.fork` shells out to this helper via `posix_spawn`;
+ * node-pty looks for the native artifacts under `build/Release` first and a
+ * platform-tagged `prebuilds/<platform>-<arch>` dir second. Returns both so
+ * {@link ensureSpawnHelperExecutable} covers whichever one a given install
+ * produced. Empty on win32 (ConPTY has no helper) or when node-pty can't be
+ * resolved at all (not installed, or a workspace that doesn't use it).
+ *
+ * @param options.platform - Defaults to `process.platform`; injectable for tests.
+ * @param options.resolve - Defaults to a `require.resolve`-shaped resolver for
+ *   `'node-pty'`; injectable so this stays testable without the native module.
+ */
+export declare function spawnHelperCandidatePaths(options?: {
+    platform?: NodeJS.Platform;
+    resolve?: (specifier: string) => string;
+}): string[];
+/**
+ * Restores the executable bit on node-pty's `spawn-helper`. pnpm unpacks
+ * node-pty's prebuilt binaries with mode 0644 — and node-pty's own
+ * post-install hook only chmods `build/Release`, which a prebuild-based
+ * install never creates. Re-adding +x before the first fork makes the
+ * terminal self-heal across reinstalls without depending on an install hook.
+ * Best-effort and idempotent: a missing file or a read-only filesystem is
+ * swallowed, and the subsequent spawn surfaces the real error instead.
+ *
+ * @param candidatePaths - Defaults to {@link spawnHelperCandidatePaths}'s result.
+ */
+export declare function ensureSpawnHelperExecutable(candidatePaths?: string[]): void;
+/**
+ * Resolves the shell binary for a new PTY. Honors an explicit request
+ * override, then the user's environment (`SHELL` on posix, `ComSpec` on
+ * win32), and finally a per-platform default.
+ */
+export declare function resolveShell(requested?: string | null, options?: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+}): string;
+export type TerminalEventData = {
+    data: string;
+} | {
+    code: number | null;
+    signal: string | null;
+};
+export interface TerminalEventRecord {
+    id: number;
+    event: 'data' | 'exit';
+    data: TerminalEventData;
+    timestamp: number;
+    byteLength: number;
+}
+/** A minimal push sink a transport adapts its live connection to (e.g. SSE). */
+export interface TerminalSseSink {
+    send(event: string, data: TerminalEventData, id: number): void;
+    end(): void;
+}
+export interface TerminalSession {
+    readonly id: string;
+    readonly projectId: string | null;
+    readonly cwd: string;
+    readonly shell: string;
+    readonly cols: number;
+    readonly rows: number;
+    readonly status: 'running' | 'exited';
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+}
+export interface CreateTerminalOptions {
+    projectId?: string | null;
+    cwd: string;
+    cols?: number;
+    rows?: number;
+    shell?: string | null;
+}
+export interface CreateTerminalServiceOptions {
+    /** Lazily loads the PTY spawner. Called at most once, on the first `create()`. */
+    loadSpawnPty: () => Promise<PtySpawn>;
+    /** Count backstop for the per-session output ring-buffer; `maxBufferBytes` is the real ceiling. */
+    maxEvents?: number;
+    /** Byte ceiling for retained reattach scrollback per running session (evicted oldest-first). */
+    maxBufferBytes?: number;
+    /** Trailing scrollback kept once a shell exits, so an unreaped session doesn't pin memory. */
+    exitTailBytes?: number;
+    /** Coalesces PTY output for roughly one animation frame before fanning out one `data` event. */
+    flushIntervalMs?: number;
+    /** Flushes immediately once buffered output crosses this size, bypassing the frame timer. */
+    flushThresholdBytes?: number;
+    /** Drops an exited session from the registry after this idle window. */
+    ttlMs?: number;
+    /** Grace window given to children to exit during {@link TerminalService.shutdownActive}. */
+    shutdownGraceMs?: number;
+}
+export interface TerminalService {
+    create(options: CreateTerminalOptions): Promise<TerminalSession>;
+    get(id: string): TerminalSession | null;
+    list(filter?: {
+        projectId?: string | null;
+    }): TerminalSession[];
+    write(id: string, input: string): boolean;
+    resize(id: string, cols: number, rows: number): boolean;
+    kill(id: string, signal?: string): boolean;
+    /** Replays scrollback after `lastEventId`, then attaches `sink` for live output if still running. */
+    attach(id: string, lastEventId: number, sink: TerminalSseSink): 'attached' | 'ended' | 'not-found';
+    detach(id: string, sink: TerminalSseSink): void;
+    shutdownActive(options?: {
+        graceMs?: number;
+    }): Promise<void>;
+    isTerminal(status: string): boolean;
+}
+/**
+ * Builds an in-memory terminal session manager. See the module docblock for
+ * the design rationale; see {@link CreateTerminalServiceOptions} for tuning.
+ */
+export declare function createTerminalService(options: CreateTerminalServiceOptions): TerminalService;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/terminal.d.ts.map

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