@cleocode/cleo-os 2026.4.99 → 2026.4.101

package/dist/harnesses/pi-coding-agent/docker-mode.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Docker sandbox mode for the Pi coding agent harness.
+ *
+ * When `CLEO_PI_SANDBOXED=1` is set (or `sandboxed: true` is passed to
+ * {@link PiCodingAgentAdapter.spawn}), the adapter routes the Pi process
+ * through a Docker container instead of running Pi host-native.
+ *
+ * @remarks
+ * The sandbox container image mirrors the pattern established by the
+ * `cleo-sandbox` project (`/mnt/projects/cleo-sandbox/harnesses/pi/`):
+ *
+ *   - Base: `cleo-sandbox/pi:local` (or the image named in
+ *     `CLEO_PI_SANDBOX_IMAGE`). This image has `@mariozechner/pi-coding-agent`
+ *     installed globally and a non-root `cleo` user.
+ *   - The cleocode source tree is bind-mounted read-only at `/sandbox-src`.
+ *   - An artifacts volume is bind-mounted at `/sandbox`.
+ *   - API keys are passed via `-e` at container creation time — NEVER baked
+ *     into the image.
+ *
+ * When Docker is not available or the image is not present, the adapter
+ * falls back to host-native mode with a warning logged to stderr.
+ *
+ * Environment variable overrides (all optional):
+ *   - `CLEO_PI_SANDBOXED`         — set to `1` to enable docker mode globally
+ *   - `CLEO_PI_SANDBOX_IMAGE`     — Docker image name (default: `cleo-sandbox/pi:local`)
+ *   - `CLEO_PI_SANDBOX_NETWORK`   — Docker network name (default: none)
+ *   - `CLEO_PI_SANDBOX_WORKDIR`   — Container working directory (default: `/sandbox`)
+ *   - `CLEO_PI_SANDBOX_SOURCE`    — Host path bind-mounted at `/sandbox-src`
+ *   - `CLEO_PI_SANDBOX_ARTIFACTS` — Host path bind-mounted at `/sandbox`
+ *
+ * @see `/mnt/projects/cleo-sandbox/harnesses/pi/Dockerfile` — reference image
+ * @see `/mnt/projects/openclaw/Dockerfile.sandbox-common` — OpenClaw sandbox pattern
+ * @packageDocumentation
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Return `true` when docker sandbox mode is globally enabled via env var.
+ *
+ * @public
+ */
+export declare function isSandboxedGlobally(): boolean;
+/**
+ * Return the Docker image name to use for the Pi sandbox container.
+ *
+ * Reads `CLEO_PI_SANDBOX_IMAGE` from the environment; falls back to
+ * {@link DEFAULT_SANDBOX_IMAGE}.
+ *
+ * @public
+ */
+export declare function getSandboxImage(): string;
+/**
+ * Return the working directory path to use inside the container.
+ *
+ * Reads `CLEO_PI_SANDBOX_WORKDIR`; falls back to {@link DEFAULT_CONTAINER_WORKDIR}.
+ *
+ * @public
+ */
+export declare function getContainerWorkdir(): string;
+/**
+ * Check whether the Docker CLI is available and the daemon is reachable.
+ *
+ * Runs `docker info` with a short timeout. Returns `false` when Docker is
+ * not installed or the daemon is not running so the adapter can fall back
+ * gracefully to host-native mode.
+ *
+ * @returns `true` when Docker is usable, `false` otherwise.
+ *
+ * @public
+ */
+export declare function isDockerAvailable(): Promise<boolean>;
+/**
+ * Check whether the Pi sandbox Docker image exists locally.
+ *
+ * @param image - Image name to probe (defaults to {@link getSandboxImage}).
+ * @returns `true` when the image is present, `false` otherwise.
+ *
+ * @public
+ */
+export declare function isSandboxImagePresent(image?: string): Promise<boolean>;
+/**
+ * Options for constructing a `docker run` invocation.
+ *
+ * @public
+ */
+export interface DockerRunOptions {
+    /** Prompt text to pass to Pi inside the container. */
+    prompt: string;
+    /**
+     * Host working directory.
+     *
+     * When set, mounted read-write at {@link getContainerWorkdir} inside the
+     * container so Pi can write output artifacts.
+     *
+     * @defaultValue undefined
+     */
+    cwd?: string;
+    /**
+     * Extra environment variable overrides injected via `-e` flags.
+     *
+     * @defaultValue undefined
+     */
+    env?: Record<string, string>;
+    /**
+     * Path to the temporary prompt file already written by the caller.
+     *
+     * The adapter writes the prompt to a host-side temp file and bind-mounts it
+     * into the container at `/tmp/pi-prompt.txt`. Pi reads this file as its
+     * prompt argument (`pi /tmp/pi-prompt.txt`).
+     *
+     * @defaultValue undefined
+     */
+    promptFilePath?: string;
+    /**
+     * Docker image override for this invocation.
+     *
+     * @defaultValue `getSandboxImage()`
+     */
+    image?: string;
+}
+/**
+ * Build the `docker run` argument array for a sandboxed Pi invocation.
+ *
+ * The resulting array is suitable as the second argument to Node's
+ * `child_process.spawn('docker', args)` call.
+ *
+ * @remarks
+ * Key design choices (mirroring OpenClaw's sandbox pattern):
+ * - `--rm` — container is removed on exit; no persistent container state.
+ * - Read-only source mount (`/sandbox-src:ro`) — prevents agent from
+ *   modifying the cleocode source tree.
+ * - Read-write artifacts mount (`/sandbox`) — agent output lands here.
+ * - API keys forwarded from the host environment when present.
+ * - `PI_TELEMETRY=0` always injected to suppress telemetry.
+ * - No ports exposed — sandbox containers are ephemeral CLI workers.
+ *
+ * @param opts - Options controlling the container configuration.
+ * @returns Array of arguments for `docker run`.
+ *
+ * @public
+ */
+export declare function buildDockerRunArgs(opts: DockerRunOptions): string[];
+/**
+ * Supplemental adapter that wraps Pi runs inside a Docker sandbox container.
+ *
+ * Used by {@link PiCodingAgentAdapter} when sandbox mode is enabled.
+ * Callers should first call {@link checkDockerReadiness} to verify that
+ * Docker is available and the sandbox image is present.
+ *
+ * @public
+ */
+export declare class DockerModeAdapter {
+    /**
+     * Verify that Docker is available and the sandbox image is present.
+     *
+     * @param image - Image to check (defaults to {@link getSandboxImage}).
+     * @returns Object describing readiness and any issue encountered.
+     *
+     * @public
+     */
+    checkReadiness(image?: string): Promise<{
+        ready: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Spawn Pi inside a Docker sandbox container.
+     *
+     * Builds the `docker run` argument list via {@link buildDockerRunArgs} and
+     * delegates to Node's `child_process.spawn`. The returned `ChildProcess` is
+     * wired identically to the host-native path in {@link PiWrapper.start} so
+     * the adapter can use the same output buffering and cleanup logic.
+     *
+     * @param opts - Docker run options.
+     * @returns A spawned `ChildProcess` handle.
+     *
+     * @public
+     */
+    spawnInDocker(opts: DockerRunOptions): ReturnType<typeof spawn>;
+}
+//# sourceMappingURL=docker-mode.d.ts.map

package/dist/harnesses/pi-coding-agent/docker-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-mode.d.ts","sourceRoot":"","sources":["../../../src/harnesses/pi-coding-agent/docker-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAQ,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAejD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO1D;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAU5E;AAMD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,EAAE,CA2DnE;AAMD;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;OAOG;IACG,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAclF;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC;CAMhE"}

package/dist/harnesses/pi-coding-agent/docker-mode.js

@@ -0,0 +1,241 @@
+/**
+ * Docker sandbox mode for the Pi coding agent harness.
+ *
+ * When `CLEO_PI_SANDBOXED=1` is set (or `sandboxed: true` is passed to
+ * {@link PiCodingAgentAdapter.spawn}), the adapter routes the Pi process
+ * through a Docker container instead of running Pi host-native.
+ *
+ * @remarks
+ * The sandbox container image mirrors the pattern established by the
+ * `cleo-sandbox` project (`/mnt/projects/cleo-sandbox/harnesses/pi/`):
+ *
+ *   - Base: `cleo-sandbox/pi:local` (or the image named in
+ *     `CLEO_PI_SANDBOX_IMAGE`). This image has `@mariozechner/pi-coding-agent`
+ *     installed globally and a non-root `cleo` user.
+ *   - The cleocode source tree is bind-mounted read-only at `/sandbox-src`.
+ *   - An artifacts volume is bind-mounted at `/sandbox`.
+ *   - API keys are passed via `-e` at container creation time — NEVER baked
+ *     into the image.
+ *
+ * When Docker is not available or the image is not present, the adapter
+ * falls back to host-native mode with a warning logged to stderr.
+ *
+ * Environment variable overrides (all optional):
+ *   - `CLEO_PI_SANDBOXED`         — set to `1` to enable docker mode globally
+ *   - `CLEO_PI_SANDBOX_IMAGE`     — Docker image name (default: `cleo-sandbox/pi:local`)
+ *   - `CLEO_PI_SANDBOX_NETWORK`   — Docker network name (default: none)
+ *   - `CLEO_PI_SANDBOX_WORKDIR`   — Container working directory (default: `/sandbox`)
+ *   - `CLEO_PI_SANDBOX_SOURCE`    — Host path bind-mounted at `/sandbox-src`
+ *   - `CLEO_PI_SANDBOX_ARTIFACTS` — Host path bind-mounted at `/sandbox`
+ *
+ * @see `/mnt/projects/cleo-sandbox/harnesses/pi/Dockerfile` — reference image
+ * @see `/mnt/projects/openclaw/Dockerfile.sandbox-common` — OpenClaw sandbox pattern
+ * @packageDocumentation
+ */
+import { exec, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+/** Default Docker image for the Pi sandbox container. */
+const DEFAULT_SANDBOX_IMAGE = 'cleo-sandbox/pi:local';
+/** Default working directory inside the sandbox container. */
+const DEFAULT_CONTAINER_WORKDIR = '/sandbox';
+// ---------------------------------------------------------------------------
+// Configuration helpers
+// ---------------------------------------------------------------------------
+/**
+ * Return `true` when docker sandbox mode is globally enabled via env var.
+ *
+ * @public
+ */
+export function isSandboxedGlobally() {
+    return process.env['CLEO_PI_SANDBOXED'] === '1';
+}
+/**
+ * Return the Docker image name to use for the Pi sandbox container.
+ *
+ * Reads `CLEO_PI_SANDBOX_IMAGE` from the environment; falls back to
+ * {@link DEFAULT_SANDBOX_IMAGE}.
+ *
+ * @public
+ */
+export function getSandboxImage() {
+    return process.env['CLEO_PI_SANDBOX_IMAGE'] ?? DEFAULT_SANDBOX_IMAGE;
+}
+/**
+ * Return the working directory path to use inside the container.
+ *
+ * Reads `CLEO_PI_SANDBOX_WORKDIR`; falls back to {@link DEFAULT_CONTAINER_WORKDIR}.
+ *
+ * @public
+ */
+export function getContainerWorkdir() {
+    return process.env['CLEO_PI_SANDBOX_WORKDIR'] ?? DEFAULT_CONTAINER_WORKDIR;
+}
+// ---------------------------------------------------------------------------
+// Docker availability probe
+// ---------------------------------------------------------------------------
+/**
+ * Check whether the Docker CLI is available and the daemon is reachable.
+ *
+ * Runs `docker info` with a short timeout. Returns `false` when Docker is
+ * not installed or the daemon is not running so the adapter can fall back
+ * gracefully to host-native mode.
+ *
+ * @returns `true` when Docker is usable, `false` otherwise.
+ *
+ * @public
+ */
+export async function isDockerAvailable() {
+    try {
+        await execAsync('docker info --format "{{.ServerVersion}}"', { timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check whether the Pi sandbox Docker image exists locally.
+ *
+ * @param image - Image name to probe (defaults to {@link getSandboxImage}).
+ * @returns `true` when the image is present, `false` otherwise.
+ *
+ * @public
+ */
+export async function isSandboxImagePresent(image) {
+    const tag = image ?? getSandboxImage();
+    try {
+        const { stdout } = await execAsync(`docker image inspect "${tag}" --format "{{.Id}}"`, {
+            timeout: 5000,
+        });
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the `docker run` argument array for a sandboxed Pi invocation.
+ *
+ * The resulting array is suitable as the second argument to Node's
+ * `child_process.spawn('docker', args)` call.
+ *
+ * @remarks
+ * Key design choices (mirroring OpenClaw's sandbox pattern):
+ * - `--rm` — container is removed on exit; no persistent container state.
+ * - Read-only source mount (`/sandbox-src:ro`) — prevents agent from
+ *   modifying the cleocode source tree.
+ * - Read-write artifacts mount (`/sandbox`) — agent output lands here.
+ * - API keys forwarded from the host environment when present.
+ * - `PI_TELEMETRY=0` always injected to suppress telemetry.
+ * - No ports exposed — sandbox containers are ephemeral CLI workers.
+ *
+ * @param opts - Options controlling the container configuration.
+ * @returns Array of arguments for `docker run`.
+ *
+ * @public
+ */
+export function buildDockerRunArgs(opts) {
+    const image = opts.image ?? getSandboxImage();
+    const containerWorkdir = getContainerWorkdir();
+    const network = process.env['CLEO_PI_SANDBOX_NETWORK'];
+    const sourceMount = process.env['CLEO_PI_SANDBOX_SOURCE'];
+    const artifactsMount = opts.cwd ?? process.env['CLEO_PI_SANDBOX_ARTIFACTS'];
+    const args = ['run', '--rm', '--init'];
+    // Network isolation (optional).
+    if (network !== undefined && network.length > 0) {
+        args.push('--network', network);
+    }
+    // Working directory inside the container.
+    args.push('-w', containerWorkdir);
+    // Read-only source mount (cleocode source tree).
+    if (sourceMount !== undefined && sourceMount.length > 0) {
+        args.push('-v', `${sourceMount}:/sandbox-src:ro`);
+    }
+    // Read-write artifacts mount.
+    if (artifactsMount !== undefined && artifactsMount.length > 0) {
+        args.push('-v', `${artifactsMount}:${containerWorkdir}`);
+    }
+    // Bind-mount the prompt file into the container.
+    if (opts.promptFilePath !== undefined) {
+        args.push('-v', `${opts.promptFilePath}:/tmp/pi-prompt.txt:ro`);
+    }
+    // Core environment variables.
+    args.push('-e', 'PI_TELEMETRY=0');
+    // Forward API keys from the host environment.
+    for (const key of [
+        'ANTHROPIC_API_KEY',
+        'OPENAI_API_KEY',
+        'GOOGLE_API_KEY',
+        'OPENROUTER_API_KEY',
+    ]) {
+        const val = process.env[key];
+        if (val !== undefined && val.length > 0) {
+            args.push('-e', `${key}=${val}`);
+        }
+    }
+    // Caller-supplied environment overrides.
+    if (opts.env !== undefined) {
+        for (const [k, v] of Object.entries(opts.env)) {
+            args.push('-e', `${k}=${v}`);
+        }
+    }
+    // Image and command: `pi /tmp/pi-prompt.txt`
+    args.push(image, 'pi', '/tmp/pi-prompt.txt');
+    return args;
+}
+// ---------------------------------------------------------------------------
+// DockerModeAdapter
+// ---------------------------------------------------------------------------
+/**
+ * Supplemental adapter that wraps Pi runs inside a Docker sandbox container.
+ *
+ * Used by {@link PiCodingAgentAdapter} when sandbox mode is enabled.
+ * Callers should first call {@link checkDockerReadiness} to verify that
+ * Docker is available and the sandbox image is present.
+ *
+ * @public
+ */
+export class DockerModeAdapter {
+    /**
+     * Verify that Docker is available and the sandbox image is present.
+     *
+     * @param image - Image to check (defaults to {@link getSandboxImage}).
+     * @returns Object describing readiness and any issue encountered.
+     *
+     * @public
+     */
+    async checkReadiness(image) {
+        if (!(await isDockerAvailable())) {
+            return { ready: false, reason: 'Docker daemon not available' };
+        }
+        const tag = image ?? getSandboxImage();
+        if (!(await isSandboxImagePresent(tag))) {
+            return {
+                ready: false,
+                reason: `Sandbox image "${tag}" not found. Build it with: cd /mnt/projects/cleo-sandbox && docker build -f harnesses/pi/Dockerfile -t ${tag} .`,
+            };
+        }
+        return { ready: true };
+    }
+    /**
+     * Spawn Pi inside a Docker sandbox container.
+     *
+     * Builds the `docker run` argument list via {@link buildDockerRunArgs} and
+     * delegates to Node's `child_process.spawn`. The returned `ChildProcess` is
+     * wired identically to the host-native path in {@link PiWrapper.start} so
+     * the adapter can use the same output buffering and cleanup logic.
+     *
+     * @param opts - Docker run options.
+     * @returns A spawned `ChildProcess` handle.
+     *
+     * @public
+     */
+    spawnInDocker(opts) {
+        const args = buildDockerRunArgs(opts);
+        return spawn('docker', args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+}
+//# sourceMappingURL=docker-mode.js.map

package/dist/harnesses/pi-coding-agent/docker-mode.js.map

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

package/dist/harnesses/pi-coding-agent/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pi Coding Agent harness adapter — public barrel export.
+ *
+ * Re-exports the adapter class, type contract, and supporting utilities
+ * for the Pi coding agent harness in cleo-os.
+ *
+ * @packageDocumentation
+ */
+export { PiCodingAgentAdapter } from './adapter.js';
+export { DockerModeAdapter, getSandboxImage, isSandboxedGlobally } from './docker-mode.js';
+export { getPiBinaryPath, getTerminateGraceMs, PiWrapper, resolveExtensionPaths, } from './pi-wrapper.js';
+export type { HarnessAdapter, HarnessOutputLine, HarnessProcessState, HarnessProcessStatus, HarnessSpawnOptions, HarnessSpawnResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/harnesses/pi-coding-agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/harnesses/pi-coding-agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,SAAS,EACT,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/harnesses/pi-coding-agent/index.js

@@ -0,0 +1,12 @@
+/**
+ * Pi Coding Agent harness adapter — public barrel export.
+ *
+ * Re-exports the adapter class, type contract, and supporting utilities
+ * for the Pi coding agent harness in cleo-os.
+ *
+ * @packageDocumentation
+ */
+export { PiCodingAgentAdapter } from './adapter.js';
+export { DockerModeAdapter, getSandboxImage, isSandboxedGlobally } from './docker-mode.js';
+export { getPiBinaryPath, getTerminateGraceMs, PiWrapper, resolveExtensionPaths, } from './pi-wrapper.js';
+//# sourceMappingURL=index.js.map

package/dist/harnesses/pi-coding-agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/harnesses/pi-coding-agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,SAAS,EACT,qBAAqB,GACtB,MAAM,iBAAiB,CAAC"}

package/dist/harnesses/pi-coding-agent/pi-wrapper.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Pi binary wrapper — low-level launcher for the Pi coding agent CLI.
+ *
+ * Handles prompt delivery, process spawning, stdin/stdout/stderr wiring,
+ * and SIGTERM-then-SIGKILL cleanup. This module is the only place in
+ * cleo-os that touches `child_process.spawn` directly for Pi.
+ *
+ * @remarks
+ * Pi receives its prompt via **file mode**: the prompt text is written to a
+ * temporary file under `/tmp/` and passed as a positional CLI argument
+ * (`pi <file>`). This mirrors the pattern used by `PiSpawnProvider` in
+ * `packages/adapters/` and avoids stdin complexity for non-interactive runs.
+ *
+ * CleoOS extension injection follows the same mechanism as `cli.ts`: each
+ * discovered extension is prepended as `--extension <path>` so Pi loads
+ * bridges (CANT bridge, hooks bridge, etc.) even in non-interactive mode.
+ *
+ * Environment variable overrides (all optional):
+ *   - `CLEO_PI_BINARY`              — path to the `pi` binary (default: `pi` from PATH)
+ *   - `CLEO_TERMINATE_GRACE_MS`     — SIGTERM grace window in ms (default: `5000`)
+ *   - `CLEO_HARNESS_OUTPUT_BUFFER`  — ring buffer capacity per process (default: `500`)
+ *
+ * OpenClaw patterns adopted:
+ *   - Extension injection via `--extension <path>` flags.
+ *   - Prompt written to `/tmp/` with a unique suffix; cleaned up on exit.
+ *   - `PI_TELEMETRY=0` injected by default to suppress telemetry in CI.
+ *
+ * @packageDocumentation
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { HarnessOutputLine, HarnessProcessState, HarnessProcessStatus } from './types.js';
+/**
+ * Resolve the `pi` binary path.
+ *
+ * Honours `CLEO_PI_BINARY` env var when set (absolute path or bare name),
+ * otherwise defaults to `pi` (expects the binary on PATH).
+ *
+ * @returns Resolved binary path string.
+ *
+ * @public
+ */
+export declare function getPiBinaryPath(): string;
+/**
+ * Return the SIGTERM grace window in milliseconds.
+ *
+ * Reads `CLEO_TERMINATE_GRACE_MS` from the environment; falls back to
+ * {@link DEFAULT_TERMINATE_GRACE_MS} when absent or non-positive.
+ *
+ * @public
+ */
+export declare function getTerminateGraceMs(): number;
+/**
+ * Return the output ring buffer capacity.
+ *
+ * Reads `CLEO_HARNESS_OUTPUT_BUFFER` from the environment; falls back to
+ * {@link DEFAULT_OUTPUT_BUFFER_SIZE} when absent or non-positive.
+ *
+ * @public
+ */
+export declare function getOutputBufferSize(): number;
+/**
+ * Collect CleoOS extension paths that exist on disk.
+ *
+ * Resolves the standard extension list relative to the compiled package root
+ * (`extensions/` directory adjacent to `dist/`). Only paths that exist on
+ * disk are returned — missing extensions are skipped silently so the adapter
+ * degrades gracefully when extensions are not installed.
+ *
+ * Mirrors `collectExtensionPaths()` in `cli.ts` but does not depend on
+ * `@cleocode/core` to keep this module free of external package imports.
+ *
+ * @returns Array of absolute `.js` extension paths.
+ *
+ * @public
+ */
+export declare function resolveExtensionPaths(): string[];
+/**
+ * Internal state tracked for each spawned Pi process.
+ */
+export interface PiProcessEntry {
+    /** OS process ID (or null if spawn failed before assigning one). */
+    pid: number | null;
+    /** Live child process handle (null after the process exits). */
+    child: ChildProcess | null;
+    /** Task ID from the caller. */
+    taskId: string;
+    /** Stable instance ID. */
+    instanceId: string;
+    /** ISO-8601 spawn timestamp. */
+    startedAt: string;
+    /** Current lifecycle state. */
+    state: HarnessProcessState;
+    /** Exit code (populated on exit). */
+    exitCode: number | null;
+    /** Signal used to terminate (populated on kill). */
+    terminatingSignal: NodeJS.Signals | null;
+    /** ISO-8601 end timestamp. */
+    endedAt: string | null;
+    /** Error message for 'failed' state. */
+    error: string | null;
+    /** Bounded output ring buffer. */
+    outputBuffer: HarnessOutputLine[];
+    /** Resolve callback for the exitPromise. */
+    resolveExit: (status: HarnessProcessStatus) => void;
+    /** Path of the temporary prompt file (cleaned up on exit). */
+    tmpFile: string | null;
+    /** SIGKILL timer handle (set during the grace window). */
+    killTimer: ReturnType<typeof setTimeout> | null;
+}
+/**
+ * Snapshot the current state of a process entry as a {@link HarnessProcessStatus}.
+ *
+ * @param entry - The process tracking entry.
+ * @returns Immutable status snapshot.
+ *
+ * @public
+ */
+export declare function buildStatus(entry: PiProcessEntry): HarnessProcessStatus;
+/**
+ * Create a new process tracking entry for a given instance and task.
+ *
+ * The entry starts in a transitional `'failed'` state that will be
+ * immediately overwritten by {@link PiWrapper.start} on success.
+ *
+ * @param instanceId - Stable instance identifier.
+ * @param taskId - CLEO task ID.
+ * @param resolveExit - Promise resolve callback wired to the exit promise.
+ * @returns Initialised (pre-spawn) tracking entry.
+ *
+ * @public
+ */
+export declare function createProcessEntry(instanceId: string, taskId: string, resolveExit: (status: HarnessProcessStatus) => void): PiProcessEntry;
+/**
+ * Low-level Pi process launcher.
+ *
+ * Manages the full lifecycle of Pi CLI processes: spawning via
+ * {@link start}, output buffering into a ring buffer, and
+ * SIGTERM-then-SIGKILL termination via {@link terminate}. Process state
+ * is tracked in a {@link PiProcessEntry} held by the caller
+ * ({@link PiCodingAgentAdapter}).
+ *
+ * @public
+ */
+export declare class PiWrapper {
+    /**
+     * Spawn a Pi CLI process for the given task.
+     *
+     * Writes the prompt to a temporary file in `/tmp/`, builds the argument
+     * list (prepending `--extension <path>` for each available CleoOS
+     * extension), and spawns Pi as a child process. Stdout and stderr are
+     * line-buffered into `entry.outputBuffer`.
+     *
+     * When spawn fails (e.g. binary not found), `entry.state` is set to
+     * `'failed'` and `entry.resolveExit` is called before returning.
+     *
+     * @param entry - Pre-allocated process tracking entry. Mutated in place.
+     * @param prompt - Prompt text to deliver to Pi.
+     * @param cwd - Working directory for the child process.
+     * @param env - Environment variable overrides merged atop the current env.
+     * @returns The mutated `entry` (for chaining convenience).
+     *
+     * @public
+     */
+    start(entry: PiProcessEntry, prompt: string, cwd: string, env: Record<string, string>): Promise<PiProcessEntry>;
+    /**
+     * Terminate a Pi process via SIGTERM-then-SIGKILL.
+     *
+     * Sends SIGTERM immediately. If the process has not exited within the
+     * configured grace window ({@link getTerminateGraceMs}), sends SIGKILL.
+     * Idempotent — subsequent calls when the process is already dead are no-ops.
+     *
+     * @param entry - The process tracking entry to terminate.
+     *
+     * @public
+     */
+    terminate(entry: PiProcessEntry): void;
+}
+//# sourceMappingURL=pi-wrapper.d.ts.map

package/dist/harnesses/pi-coding-agent/pi-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-wrapper.d.ts","sourceRoot":"","sources":["../../../src/harnesses/pi-coding-agent/pi-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAc/F;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAO5C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAO5C;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAYhD;AAMD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,gEAAgE;IAChE,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3B,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oDAAoD;IACpD,iBAAiB,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACzC,8BAA8B;IAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wCAAwC;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kCAAkC;IAClC,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,4CAA4C;IAC5C,WAAW,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACpD,8DAA8D;IAC9D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0DAA0D;IAC1D,SAAS,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAC;CACjD;AAuCD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,oBAAoB,CAWvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAClD,cAAc,CAiBhB;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,CACT,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,OAAO,CAAC,cAAc,CAAC;IAsG1B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;CAoBvC"}