@memberjunction/ai-agent-harness 0.0.0 → 6.1.0-edge.1

package/dist/adapters/StdioJsonAdapter.js

@@ -0,0 +1,109 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { RegisterClass } from '@memberjunction/global';
+import { BaseCliHarnessAdapter } from './BaseCliHarnessAdapter.js';
+import { BaseHarnessAdapter } from './BaseHarnessAdapter.js';
+/**
+ * Drives ANY command that speaks a documented newline-delimited JSON event contract.
+ *
+ * This is the escape hatch that keeps "adding a harness must not require core changes" true in the
+ * strong sense: a harness MJ has never heard of works with zero MJ code, provided its CLI emits
+ * lines matching the vocabulary below.
+ *
+ * ## The contract
+ *
+ * Each stdout line is a JSON object with a `type` field:
+ *
+ * | `type`       | Other fields                          | Meaning                                  |
+ * |--------------|---------------------------------------|------------------------------------------|
+ * | `text`       | `text`                                | Narration; streamed, never persisted     |
+ * | `activity`   | `description`                         | In-sandbox activity, for live view only  |
+ * | `permission` | `id`, `description`, `command?`       | Requests approval; becomes a HITL row    |
+ * | `usage`      | `input_tokens`, `output_tokens`, `cost_usd?` | Turn usage; drives cost guardrails |
+ * | `complete`   | `text`                                | Turn ended; `text` carries the envelope  |
+ * | `error`      | `message`                             | Turn failed                              |
+ *
+ * Unrecognised lines are ignored, so a harness may interleave its own diagnostics freely.
+ *
+ * Capabilities default to the conservative end — an unknown harness is assumed NOT to resume
+ * sessions or honour permission hooks, so the runtime emulates continuity rather than silently
+ * losing context. Override via `AIAgentHarness.CapabilitySettings` when the harness does better.
+ */
+let StdioJsonAdapter = class StdioJsonAdapter extends BaseCliHarnessAdapter {
+    constructor() {
+        super(...arguments);
+        this.executable = 'harness';
+        this.extraArgs = [];
+        this.declaredCapabilities = null;
+    }
+    get ExecutablePath() {
+        return this.executable;
+    }
+    /** @inheritdoc */
+    get Capabilities() {
+        return (this.declaredCapabilities ?? {
+            SessionResume: false,
+            StructuredOutput: false,
+            UsageReporting: true,
+            // FALSE by definition: this is the generic escape hatch for a harness with no
+            // first-class adapter, so there is no known flag vocabulary to translate a policy
+            // into. A subclass that knows its CLI should override ApplyPermissionPolicy and
+            // report true.
+            PermissionPolicy: false,
+            PermissionHooks: false,
+            McpClient: false,
+            WorkspaceScoping: true,
+            ModelSelection: false,
+        });
+    }
+    BuildTurnArgs(input, _isFirstTurn) {
+        return [...this.extraArgs, input];
+    }
+    MapEvent(raw) {
+        switch (this.readString(raw, 'type')) {
+            case 'text':
+                return { Type: 'assistant-text', Text: this.readString(raw, 'text') ?? '' };
+            case 'activity':
+                return { Type: 'sandbox-activity', Description: this.readString(raw, 'description') ?? 'activity' };
+            case 'permission':
+                return {
+                    Type: 'permission-request',
+                    RequestId: this.readString(raw, 'id') ?? '',
+                    Description: this.readString(raw, 'description') ?? 'permission requested',
+                    Command: this.readString(raw, 'command'),
+                };
+            case 'usage':
+                return {
+                    Type: 'usage',
+                    InputTokens: this.readNumber(raw, 'input_tokens') ?? 0,
+                    OutputTokens: this.readNumber(raw, 'output_tokens') ?? 0,
+                    CostUsd: this.readNumber(raw, 'cost_usd'),
+                };
+            case 'complete':
+                return { Type: 'turn-complete', RawText: this.readString(raw, 'text') ?? '' };
+            case 'error':
+                return { Type: 'session-error', Error: this.readString(raw, 'message') ?? 'harness reported an error' };
+            default:
+                return null;
+        }
+    }
+    /** Configures the command, extra argv and declared capabilities from `AIAgentHarness` metadata. */
+    Configure(executable, extraArgs, capabilities) {
+        this.executable = executable;
+        this.extraArgs = extraArgs;
+        this.declaredCapabilities = capabilities;
+    }
+    /** Points the adapter at a specific binary, from `AIAgentHarness.ExecutablePath`. */
+    SetExecutable(path) {
+        this.executable = path;
+    }
+};
+StdioJsonAdapter = __decorate([
+    RegisterClass(BaseHarnessAdapter, 'StdioJsonAdapter')
+], StdioJsonAdapter);
+export { StdioJsonAdapter };
+//# sourceMappingURL=StdioJsonAdapter.js.map

package/dist/adapters/StdioJsonAdapter.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export * from './types.js';
+export * from './HarnessAgentType.js';
+export * from './HarnessAgentBase.js';
+export * from './adapters/BaseHarnessAdapter.js';
+export * from './adapters/BaseCliHarnessAdapter.js';
+export * from './adapters/StdioJsonAdapter.js';
+export * from './adapters/ClaudeCodeCliAdapter.js';
+export * from './adapters/CodexAdapter.js';
+export * from './adapters/OpenCodeAdapter.js';
+export * from './adapters/GeminiCliAdapter.js';
+export * from './adapters/PiAdapter.js';
+export * from './sandbox/SandboxExecutor.js';
+export * from './sandbox/ISandboxProvider.js';
+export * from './sandbox/ChildProcessExecutor.js';
+export * from './sandbox/DockerSandboxProvider.js';
+export * from './sandbox/LocalDirectorySandboxProvider.js';
+/**
+ * Tree-shaking guard.
+ *
+ * The adapters register themselves with ClassFactory via `@RegisterClass` as a side effect of being
+ * loaded. A bundler that sees no direct import of a module is free to drop it, which would leave
+ * `AIAgentHarness.DriverClass` resolving to nothing at runtime — a failure that only appears in a
+ * built artifact, never in dev. Calling this from a consumer's startup path keeps them reachable.
+ */
+export declare function LoadAgentHarnessAdapters(): void;
+//# 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,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAE3D;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/index.js

@@ -0,0 +1,28 @@
+export * from './types.js';
+export * from './HarnessAgentType.js';
+export * from './HarnessAgentBase.js';
+export * from './adapters/BaseHarnessAdapter.js';
+export * from './adapters/BaseCliHarnessAdapter.js';
+export * from './adapters/StdioJsonAdapter.js';
+export * from './adapters/ClaudeCodeCliAdapter.js';
+export * from './adapters/CodexAdapter.js';
+export * from './adapters/OpenCodeAdapter.js';
+export * from './adapters/GeminiCliAdapter.js';
+export * from './adapters/PiAdapter.js';
+export * from './sandbox/SandboxExecutor.js';
+export * from './sandbox/ISandboxProvider.js';
+export * from './sandbox/ChildProcessExecutor.js';
+export * from './sandbox/DockerSandboxProvider.js';
+export * from './sandbox/LocalDirectorySandboxProvider.js';
+/**
+ * Tree-shaking guard.
+ *
+ * The adapters register themselves with ClassFactory via `@RegisterClass` as a side effect of being
+ * loaded. A bundler that sees no direct import of a module is free to drop it, which would leave
+ * `AIAgentHarness.DriverClass` resolving to nothing at runtime — a failure that only appears in a
+ * built artifact, never in dev. Calling this from a consumer's startup path keeps them reachable.
+ */
+export function LoadAgentHarnessAdapters() {
+    // Intentionally empty — the imports above are the point.
+}
+//# 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,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB;IACpC,yDAAyD;AAC7D,CAAC"}

package/dist/sandbox/ChildProcessExecutor.d.ts

@@ -0,0 +1,41 @@
+import { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { HarnessProcess, HarnessProcessSpec, SandboxExecutor } from './SandboxExecutor.js';
+/**
+ * Turns a spawned child process into the backend-neutral {@link HarnessProcess} shape.
+ *
+ * Shared by every executor that ultimately runs a local binary — the local provider spawns the
+ * harness itself, and the Docker provider spawns `docker exec`. Only the argv differs, so the
+ * process plumbing lives here once rather than in each provider.
+ */
+export declare function wrapChildProcess(child: ChildProcessWithoutNullStreams): HarnessProcess;
+/**
+ * Runs harness processes directly on the MJAPI host.
+ *
+ * Provides no isolation whatsoever — see {@link LocalDirectorySandboxProvider} for what that means
+ * and why it is a development-only posture.
+ */
+export declare class ChildProcessExecutor implements SandboxExecutor {
+    private readonly defaultWorkingDirectory;
+    constructor(defaultWorkingDirectory: string);
+    /**
+     * The host variables a locally-spawned harness inherits, before granted credentials are layered
+     * on top.
+     *
+     * Deliberately an ALLOWLIST, not the full process environment: passing everything through would
+     * hand the harness whatever credentials the MJAPI process happens to hold, which is exactly the
+     * over-granting the credential model exists to prevent.
+     *
+     * `HOME` is on the list for a specific reason. Local CLI harnesses keep their own login state
+     * under the user's home directory (Claude Code in `~/.claude`), so a developer who has already
+     * authenticated their CLI can run a harness agent with no credential row and no API key at all —
+     * the "true local" mode. Without HOME the harness cannot find its session and reports "Not
+     * logged in", which reads as a broken integration rather than a stripped variable.
+     *
+     * This applies ONLY to local execution. The Docker executor passes just the granted environment,
+     * because a container has no business inheriting the host developer's identity.
+     */
+    private baseEnvironment;
+    /** @inheritdoc */
+    Run(spec: HarnessProcessSpec): HarnessProcess;
+}
+//# sourceMappingURL=ChildProcessExecutor.d.ts.map

package/dist/sandbox/ChildProcessExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChildProcessExecutor.d.ts","sourceRoot":"","sources":["../../src/sandbox/ChildProcessExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAS,MAAM,oBAAoB,CAAC;AAG3E,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE3F;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,8BAA8B,GAAG,cAAc,CAoBtF;AAUD;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,uBAAuB;gBAAvB,uBAAuB,EAAE,MAAM;IAEnE;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,eAAe;IAYvB,kBAAkB;IACX,GAAG,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc;CAQvD"}

package/dist/sandbox/ChildProcessExecutor.js

@@ -0,0 +1,86 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+/**
+ * Turns a spawned child process into the backend-neutral {@link HarnessProcess} shape.
+ *
+ * Shared by every executor that ultimately runs a local binary — the local provider spawns the
+ * harness itself, and the Docker provider spawns `docker exec`. Only the argv differs, so the
+ * process plumbing lives here once rather than in each provider.
+ */
+export function wrapChildProcess(child) {
+    return {
+        Stdout: readLines(child.stdout),
+        Stderr: readLines(child.stderr),
+        ExitCode: new Promise((resolve) => {
+            if (child.exitCode !== null) {
+                resolve(child.exitCode);
+                return;
+            }
+            child.once('close', (code) => resolve(code));
+            // A spawn failure (ENOENT for a missing binary) emits 'error' and never 'close', so
+            // without this the ExitCode promise would hang forever and take the turn with it.
+            child.once('error', () => resolve(null));
+        }),
+        Kill: () => {
+            if (child.exitCode === null && !child.killed) {
+                child.kill();
+            }
+        },
+    };
+}
+/** Frames a stream into complete lines. */
+async function* readLines(stream) {
+    const lines = createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of lines) {
+        yield line;
+    }
+}
+/**
+ * Runs harness processes directly on the MJAPI host.
+ *
+ * Provides no isolation whatsoever — see {@link LocalDirectorySandboxProvider} for what that means
+ * and why it is a development-only posture.
+ */
+export class ChildProcessExecutor {
+    constructor(defaultWorkingDirectory) {
+        this.defaultWorkingDirectory = defaultWorkingDirectory;
+    }
+    /**
+     * The host variables a locally-spawned harness inherits, before granted credentials are layered
+     * on top.
+     *
+     * Deliberately an ALLOWLIST, not the full process environment: passing everything through would
+     * hand the harness whatever credentials the MJAPI process happens to hold, which is exactly the
+     * over-granting the credential model exists to prevent.
+     *
+     * `HOME` is on the list for a specific reason. Local CLI harnesses keep their own login state
+     * under the user's home directory (Claude Code in `~/.claude`), so a developer who has already
+     * authenticated their CLI can run a harness agent with no credential row and no API key at all —
+     * the "true local" mode. Without HOME the harness cannot find its session and reports "Not
+     * logged in", which reads as a broken integration rather than a stripped variable.
+     *
+     * This applies ONLY to local execution. The Docker executor passes just the granted environment,
+     * because a container has no business inheriting the host developer's identity.
+     */
+    baseEnvironment() {
+        const allowed = ['PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'LANG', 'TERM'];
+        const env = {};
+        for (const key of allowed) {
+            const value = process.env[key];
+            if (value !== undefined) {
+                env[key] = value;
+            }
+        }
+        return env;
+    }
+    /** @inheritdoc */
+    Run(spec) {
+        const child = spawn(spec.Command, spec.Args, {
+            cwd: spec.WorkingDirectory ?? this.defaultWorkingDirectory,
+            env: { ...this.baseEnvironment(), ...spec.Environment },
+            signal: spec.CancellationToken,
+        });
+        return wrapChildProcess(child);
+    }
+}
+//# sourceMappingURL=ChildProcessExecutor.js.map

package/dist/sandbox/ChildProcessExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChildProcessExecutor.js","sourceRoot":"","sources":["../../src/sandbox/ChildProcessExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAqC;IAClE,OAAO;QACH,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC;QAC/B,MAAM,EAAE,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC;QAC/B,QAAQ,EAAE,IAAI,OAAO,CAAgB,CAAC,OAAO,EAAE,EAAE;YAC7C,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;gBAC1B,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBACxB,OAAO;YACX,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YAC7C,oFAAoF;YACpF,kFAAkF;YAClF,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7C,CAAC,CAAC;QACF,IAAI,EAAE,GAAG,EAAE;YACP,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC3C,KAAK,CAAC,IAAI,EAAE,CAAC;YACjB,CAAC;QACL,CAAC;KACJ,CAAC;AACN,CAAC;AAED,2CAA2C;AAC3C,KAAK,SAAS,CAAC,CAAC,SAAS,CAAC,MAAgB;IACtC,MAAM,KAAK,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IACtE,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC7B,MAAM,IAAI,CAAC;IACf,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAC7B,YAAoC,uBAA+B;QAA/B,4BAAuB,GAAvB,uBAAuB,CAAQ;IAAG,CAAC;IAEvE;;;;;;;;;;;;;;;;OAgBG;IACK,eAAe;QACnB,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACvF,MAAM,GAAG,GAA2B,EAAE,CAAC;QACvC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACtB,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACrB,CAAC;QACL,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAED,kBAAkB;IACX,GAAG,CAAC,IAAwB;QAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE;YACzC,GAAG,EAAE,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,uBAAuB;YAC1D,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,eAAe,EAAE,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE;YACvD,MAAM,EAAE,IAAI,CAAC,iBAAiB;SACjC,CAAC,CAAC;QACH,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;CACJ"}

package/dist/sandbox/DockerSandboxProvider.d.ts

@@ -0,0 +1,64 @@
+import { ISandboxProvider, SandboxConfig, SandboxHandle, WorkspaceKey } from './ISandboxProvider.js';
+import { HarnessProcess, HarnessProcessSpec, SandboxExecutor } from './SandboxExecutor.js';
+/**
+ * Runs each harness turn inside a per-run container.
+ *
+ * ## Why this exists
+ *
+ * {@link LocalDirectorySandboxProvider} scopes a directory but does not contain the process: the
+ * harness runs on the MJAPI host with that host's network reach and cloud credentials. For a feature
+ * whose entire purpose is executing an autonomous agent's shell commands, that is the wrong blast
+ * radius anywhere but a developer's laptop.
+ *
+ * Here the harness runs in a container with the workspace bind-mounted, so a file write outside the
+ * workspace hits the container's filesystem and dies with it, and `networkPolicy` is enforced by
+ * Docker rather than merely documented.
+ *
+ * ## Container per RUN, exec per TURN
+ *
+ * The container starts once at {@link Provision} and every turn is a `docker exec` into it. The
+ * alternative — `docker run` per turn — would pay container startup on every turn and, worse, lose
+ * any in-container state the harness accumulated outside the mounted workspace. A run is the natural
+ * lifetime because it is exactly the span over which a harness session is continuous.
+ *
+ * ## Network policy
+ *
+ * `none` maps to `--network none`. `mcp-only` and `allowlist` currently map to a bridge network and
+ * are NOT yet enforced at the packet level — enforcing them properly needs a per-run network with
+ * egress rules, which is the next increment. They are documented here as not-yet-enforced rather
+ * than quietly treated as equivalent to `open`, because an operator who believes `mcp-only` is
+ * enforced has a false sense of containment, which is worse than knowing the boundary is soft.
+ */
+export declare class DockerSandboxProvider implements ISandboxProvider {
+    private readonly hostRootPath;
+    private readonly defaultImage;
+    private readonly containers;
+    constructor(options?: {
+        hostRootPath?: string;
+        defaultImage?: string;
+    });
+    /** @inheritdoc */
+    Provision(key: WorkspaceKey, config: SandboxConfig): Promise<SandboxHandle>;
+    /** @inheritdoc */
+    Finalize(handle: SandboxHandle, _outcome: 'success' | 'failure' | 'cancelled'): Promise<void>;
+    /** Maps the declared network policy onto docker flags, honestly. */
+    private buildNetworkArgs;
+    /** Runs a docker CLI command and resolves with its trimmed stdout. */
+    private runDockerCommand;
+    /** Same shape as the local provider, so a workspace is recognisable across both. */
+    private buildRelativePath;
+}
+/**
+ * Runs harness processes via `docker exec` into an already-running per-run container.
+ *
+ * Environment is passed with repeated `--env` flags rather than baked into the container at start,
+ * so a credential rotated between turns takes effect on the next turn without recreating the
+ * sandbox.
+ */
+export declare class DockerExecExecutor implements SandboxExecutor {
+    private readonly containerName;
+    constructor(containerName: string);
+    /** @inheritdoc */
+    Run(spec: HarnessProcessSpec): HarnessProcess;
+}
+//# sourceMappingURL=DockerSandboxProvider.d.ts.map

package/dist/sandbox/DockerSandboxProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DockerSandboxProvider.d.ts","sourceRoot":"","sources":["../../src/sandbox/DockerSandboxProvider.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrG,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAO3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;gBAErC,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAK7E,kBAAkB;IACL,SAAS,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAsCxF,kBAAkB;IACL,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB1G,oEAAoE;IACpE,OAAO,CAAC,gBAAgB;IAexB,sEAAsE;IACtE,OAAO,CAAC,gBAAgB;IAkBxB,oFAAoF;IACpF,OAAO,CAAC,iBAAiB;CAU5B;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,MAAM;IAEzD,kBAAkB;IACX,GAAG,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc;CAavD"}

package/dist/sandbox/DockerSandboxProvider.js

@@ -0,0 +1,176 @@
+import { spawn } from 'node:child_process';
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { LogError, LogStatus } from '@memberjunction/core';
+import { wrapChildProcess } from './ChildProcessExecutor.js';
+/** Path the host workspace is mounted at inside the container. */
+const CONTAINER_WORKSPACE = '/workspace';
+/**
+ * Runs each harness turn inside a per-run container.
+ *
+ * ## Why this exists
+ *
+ * {@link LocalDirectorySandboxProvider} scopes a directory but does not contain the process: the
+ * harness runs on the MJAPI host with that host's network reach and cloud credentials. For a feature
+ * whose entire purpose is executing an autonomous agent's shell commands, that is the wrong blast
+ * radius anywhere but a developer's laptop.
+ *
+ * Here the harness runs in a container with the workspace bind-mounted, so a file write outside the
+ * workspace hits the container's filesystem and dies with it, and `networkPolicy` is enforced by
+ * Docker rather than merely documented.
+ *
+ * ## Container per RUN, exec per TURN
+ *
+ * The container starts once at {@link Provision} and every turn is a `docker exec` into it. The
+ * alternative — `docker run` per turn — would pay container startup on every turn and, worse, lose
+ * any in-container state the harness accumulated outside the mounted workspace. A run is the natural
+ * lifetime because it is exactly the span over which a harness session is continuous.
+ *
+ * ## Network policy
+ *
+ * `none` maps to `--network none`. `mcp-only` and `allowlist` currently map to a bridge network and
+ * are NOT yet enforced at the packet level — enforcing them properly needs a per-run network with
+ * egress rules, which is the next increment. They are documented here as not-yet-enforced rather
+ * than quietly treated as equivalent to `open`, because an operator who believes `mcp-only` is
+ * enforced has a false sense of containment, which is worse than knowing the boundary is soft.
+ */
+export class DockerSandboxProvider {
+    constructor(options) {
+        this.containers = new Map();
+        this.hostRootPath = options?.hostRootPath ?? join(tmpdir(), 'mj-agent-harness');
+        this.defaultImage = options?.defaultImage ?? 'ghcr.io/memberjunction/harness-sandbox:latest';
+    }
+    /** @inheritdoc */
+    async Provision(key, config) {
+        const hostPath = join(this.hostRootPath, this.buildRelativePath(key));
+        await mkdir(hostPath, { recursive: true });
+        const image = config.Image ?? this.defaultImage;
+        const containerName = `mj-harness-${key.RunId}`;
+        const args = [
+            'run',
+            '--detach',
+            '--rm',
+            '--name',
+            containerName,
+            '--volume',
+            `${hostPath}:${CONTAINER_WORKSPACE}`,
+            '--workdir',
+            CONTAINER_WORKSPACE,
+            ...this.buildNetworkArgs(config.NetworkPolicy),
+            image,
+            // Keep the container alive so turns can exec into it; the harness itself is never this
+            // process, it is whatever `docker exec` runs.
+            'sleep',
+            'infinity',
+        ];
+        const containerId = await this.runDockerCommand(args);
+        this.containers.set(containerName, containerId);
+        LogStatus(`Harness container started: ${containerName} (${image})`);
+        return {
+            // The path AS THE HARNESS SEES IT — inside the container, not on the host. Anything that
+            // tries to open this with `fs` on the MJAPI host is wrong; see SandboxHandle's note.
+            WorkspacePath: CONTAINER_WORKSPACE,
+            Key: key,
+            Ephemeral: key.Scope === 'run',
+            Executor: new DockerExecExecutor(containerName),
+        };
+    }
+    /** @inheritdoc */
+    async Finalize(handle, _outcome) {
+        const containerName = `mj-harness-${handle.Key.RunId}`;
+        try {
+            // --rm on the container means stopping it removes it, so this is both stop and cleanup.
+            await this.runDockerCommand(['stop', '--time', '5', containerName]);
+        }
+        catch (e) {
+            // Never rethrow from finalize: it runs on failure and cancellation paths, where throwing
+            // would replace the real error with a cleanup error and lose the diagnosis.
+            LogError(`Failed to stop harness container ${containerName}: ${describeError(e)}`);
+        }
+        this.containers.delete(containerName);
+        if (handle.Ephemeral) {
+            const hostPath = join(this.hostRootPath, this.buildRelativePath(handle.Key));
+            try {
+                await rm(hostPath, { recursive: true, force: true });
+            }
+            catch (e) {
+                LogError(`Failed to remove harness workspace ${hostPath}: ${describeError(e)}`);
+            }
+        }
+    }
+    /** Maps the declared network policy onto docker flags, honestly. */
+    buildNetworkArgs(policy) {
+        switch (policy) {
+            case 'none':
+                // Fully enforced: no interfaces at all.
+                return ['--network', 'none'];
+            case 'mcp-only':
+            case 'allowlist':
+                // NOT yet enforced at the packet level — see the class doc. Deliberately identical
+                // to 'open' today rather than pretending otherwise.
+                return [];
+            case 'open':
+                return [];
+        }
+    }
+    /** Runs a docker CLI command and resolves with its trimmed stdout. */
+    runDockerCommand(args) {
+        return new Promise((resolve, reject) => {
+            const child = spawn('docker', args);
+            const out = [];
+            const err = [];
+            child.stdout.on('data', (c) => out.push(c.toString()));
+            child.stderr.on('data', (c) => err.push(c.toString()));
+            child.once('error', (e) => reject(e));
+            child.once('close', (code) => {
+                if (code === 0) {
+                    resolve(out.join('').trim());
+                }
+                else {
+                    reject(new Error(`docker ${args[0]} failed (code ${code}): ${err.join('').trim()}`));
+                }
+            });
+        });
+    }
+    /** Same shape as the local provider, so a workspace is recognisable across both. */
+    buildRelativePath(key) {
+        switch (key.Scope) {
+            case 'run':
+                return join('run', key.RunId);
+            case 'agent':
+                return join('agent', key.AgentId);
+            case 'agent-user':
+                return join('agent-user', key.AgentId, key.UserId ?? 'no-user');
+        }
+    }
+}
+/**
+ * Runs harness processes via `docker exec` into an already-running per-run container.
+ *
+ * Environment is passed with repeated `--env` flags rather than baked into the container at start,
+ * so a credential rotated between turns takes effect on the next turn without recreating the
+ * sandbox.
+ */
+export class DockerExecExecutor {
+    constructor(containerName) {
+        this.containerName = containerName;
+    }
+    /** @inheritdoc */
+    Run(spec) {
+        const args = ['exec', '--interactive'];
+        for (const [key, value] of Object.entries(spec.Environment)) {
+            args.push('--env', `${key}=${value}`);
+        }
+        if (spec.WorkingDirectory) {
+            args.push('--workdir', spec.WorkingDirectory);
+        }
+        args.push(this.containerName, spec.Command, ...spec.Args);
+        const child = spawn('docker', args, { signal: spec.CancellationToken });
+        return wrapChildProcess(child);
+    }
+}
+function describeError(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=DockerSandboxProvider.js.map

package/dist/sandbox/DockerSandboxProvider.js.map

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

package/dist/sandbox/ISandboxProvider.d.ts

@@ -0,0 +1,71 @@
+import { HarnessNetworkPolicy, HarnessWorkspaceScope } from '../types.js';
+import { SandboxExecutor } from './SandboxExecutor.js';
+/**
+ * Identifies which workspace a run should get, and therefore how long its files live.
+ *
+ * Scope is the deciding field: `run` means a fresh directory nobody sees again, `agent` a shared
+ * workspace across every run of that agent, `agent-user` one per agent per user — the default,
+ * because it gives an agent continuity without letting one user's working files leak into another's
+ * session.
+ */
+export interface WorkspaceKey {
+    Scope: HarnessWorkspaceScope;
+    AgentId: string;
+    UserId?: string;
+    RunId: string;
+}
+/** Runtime knobs a provider honours when provisioning. */
+export interface SandboxConfig {
+    NetworkPolicy: HarnessNetworkPolicy;
+    /** Container image, for providers that have one. Ignored by the local provider. */
+    Image?: string;
+    /** How to handle two runs wanting the same durable workspace. */
+    Concurrency?: 'queue' | 'fail' | 'fork';
+}
+/** A provisioned workspace, and the means of running commands inside it. */
+export interface SandboxHandle {
+    /**
+     * Workspace path AS THE HARNESS SEES IT.
+     *
+     * For the local provider that is a host path. For a container provider it is the path inside the
+     * container, which is generally NOT the host path the workspace was created at — the two are
+     * connected by a mount the provider set up. Code that passes this to a harness process is
+     * correct; code that opens it with `fs` on the MJAPI host is only correct for the local provider,
+     * and that distinction is why the field is documented rather than just named.
+     */
+    WorkspacePath: string;
+    Key: WorkspaceKey;
+    /** True when the workspace is discarded on finalize rather than retained for the next run. */
+    Ephemeral: boolean;
+    /**
+     * Runs harness processes inside this sandbox.
+     *
+     * The reason process placement lives on the HANDLE rather than in the adapter: an adapter that
+     * called `spawn()` directly would always run on the MJAPI host, which in production means an
+     * autonomous agent executing shell commands inside the API container with its network reach and
+     * cloud credentials. Routing every process through the provider's executor is what makes
+     * `provider: 'docker'` mean something.
+     */
+    Executor: SandboxExecutor;
+}
+/**
+ * Provisions and finalizes the filesystem a harness runs against.
+ *
+ * Kept deliberately small — two methods — because the interesting variation between a local
+ * directory and a container is not the shape of the API, it is what `NetworkPolicy` can actually
+ * enforce. The local provider can only honour it on a best-effort basis; a container provider
+ * enforces it for real, which is why `mcp-only` is the recommended production posture and only
+ * meaningful there.
+ */
+export interface ISandboxProvider {
+    /** Provisions (or reattaches to) the workspace identified by `key`. */
+    Provision(key: WorkspaceKey, config: SandboxConfig): Promise<SandboxHandle>;
+    /**
+     * Releases the workspace.
+     *
+     * Must be safe to call on every exit path including crash and cancellation, and must not throw —
+     * a finalize that throws inside a failure path masks the original error with a cleanup error.
+     */
+    Finalize(handle: SandboxHandle, outcome: 'success' | 'failure' | 'cancelled'): Promise<void>;
+}
+//# sourceMappingURL=ISandboxProvider.d.ts.map

package/dist/sandbox/ISandboxProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISandboxProvider.d.ts","sourceRoot":"","sources":["../../src/sandbox/ISandboxProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,qBAAqB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC1B,aAAa,EAAE,oBAAoB,CAAC;IACpC,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;CAC3C;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC1B;;;;;;;;OAQG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,YAAY,CAAC;IAClB,8FAA8F;IAC9F,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,EAAE,eAAe,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC7B,uEAAuE;IACvE,SAAS,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5E;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChG"}