@cleocode/cleo-os 2026.4.99 → 2026.4.101

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

@@ -0,0 +1,359 @@
+/**
+ * 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 { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Maximum number of output lines retained in the ring buffer per process. */
+const DEFAULT_OUTPUT_BUFFER_SIZE = 500;
+/** Default SIGTERM → SIGKILL grace window in milliseconds. */
+const DEFAULT_TERMINATE_GRACE_MS = 5000;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// ---------------------------------------------------------------------------
+// Environment helpers
+// ---------------------------------------------------------------------------
+/**
+ * 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 function getPiBinaryPath() {
+    return process.env['CLEO_PI_BINARY'] ?? 'pi';
+}
+/**
+ * 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 function getTerminateGraceMs() {
+    const raw = process.env['CLEO_TERMINATE_GRACE_MS'];
+    if (raw !== undefined) {
+        const n = Number.parseInt(raw, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_TERMINATE_GRACE_MS;
+}
+/**
+ * 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 function getOutputBufferSize() {
+    const raw = process.env['CLEO_HARNESS_OUTPUT_BUFFER'];
+    if (raw !== undefined) {
+        const n = Number.parseInt(raw, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return DEFAULT_OUTPUT_BUFFER_SIZE;
+}
+// ---------------------------------------------------------------------------
+// Extension path resolution
+// ---------------------------------------------------------------------------
+/**
+ * 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 function resolveExtensionPaths() {
+    // Compiled path: dist/harnesses/pi-coding-agent/ → walk up to dist/ → package root
+    const packageRoot = join(__dirname, '..', '..', '..');
+    const extensionsDir = join(packageRoot, 'extensions');
+    const candidates = [
+        'cleo-startup.js',
+        'cleo-cant-bridge.js',
+        'cleo-hooks-bridge.js',
+        'cleo-chatroom.js',
+        'cleo-agent-monitor.js',
+    ];
+    return candidates.map((name) => join(extensionsDir, name)).filter((p) => existsSync(p));
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Append a line to a bounded ring buffer, evicting the oldest entry when the
+ * buffer is full.
+ *
+ * @param buffer - The mutable ring buffer.
+ * @param line - Line to append.
+ * @param bufferSize - Maximum buffer capacity.
+ */
+function appendOutputLine(buffer, line, bufferSize) {
+    buffer.push(line);
+    if (buffer.length > bufferSize) {
+        buffer.shift();
+    }
+}
+/**
+ * Delete a temporary prompt file, swallowing any errors.
+ *
+ * @param path - Absolute path to the temp file, or `null` to skip.
+ */
+async function cleanupTmpFile(path) {
+    if (path === null)
+        return;
+    try {
+        await unlink(path);
+    }
+    catch {
+        // Best-effort cleanup — ignore ENOENT and other errors.
+    }
+}
+/**
+ * Snapshot the current state of a process entry as a {@link HarnessProcessStatus}.
+ *
+ * @param entry - The process tracking entry.
+ * @returns Immutable status snapshot.
+ *
+ * @public
+ */
+export function buildStatus(entry) {
+    return {
+        instanceId: entry.instanceId,
+        taskId: entry.taskId,
+        state: entry.state,
+        pid: entry.pid,
+        startedAt: entry.startedAt,
+        ...(entry.endedAt !== null ? { endedAt: entry.endedAt } : {}),
+        ...(entry.state === 'exited' && entry.exitCode !== null ? { exitCode: entry.exitCode } : {}),
+        ...(entry.error !== null ? { error: entry.error } : {}),
+    };
+}
+/**
+ * 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 function createProcessEntry(instanceId, taskId, resolveExit) {
+    return {
+        pid: null,
+        child: null,
+        taskId,
+        instanceId,
+        startedAt: new Date().toISOString(),
+        state: 'failed', // overwritten by start() on success
+        exitCode: null,
+        terminatingSignal: null,
+        endedAt: null,
+        error: null,
+        outputBuffer: [],
+        resolveExit,
+        tmpFile: null,
+        killTimer: null,
+    };
+}
+// ---------------------------------------------------------------------------
+// PiWrapper
+// ---------------------------------------------------------------------------
+/**
+ * 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 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
+     */
+    async start(entry, prompt, cwd, env) {
+        const bufferSize = getOutputBufferSize();
+        const binaryPath = getPiBinaryPath();
+        // Write prompt to a temporary file (file-mode delivery).
+        const tmpFile = `/tmp/cleo-pi-${entry.instanceId}.txt`;
+        entry.tmpFile = tmpFile;
+        try {
+            await writeFile(tmpFile, prompt, 'utf-8');
+        }
+        catch (err) {
+            entry.state = 'failed';
+            entry.error = err instanceof Error ? err.message : String(err);
+            entry.endedAt = new Date().toISOString();
+            entry.resolveExit(buildStatus(entry));
+            return entry;
+        }
+        // Build argument list: [--extension <path>...] <promptFile>
+        const extensionPaths = resolveExtensionPaths();
+        const extensionFlags = extensionPaths.flatMap((p) => ['--extension', p]);
+        const args = [...extensionFlags, tmpFile];
+        // Merge environment: parent env → telemetry disable → caller overrides.
+        const parentEnv = Object.fromEntries(Object.entries(process.env).filter((pair) => pair[1] !== undefined));
+        const mergedEnv = {
+            ...parentEnv,
+            PI_TELEMETRY: '0', // suppress telemetry in CI/sandbox runs
+            ...env,
+        };
+        let child;
+        try {
+            child = spawn(binaryPath, args, {
+                cwd,
+                env: mergedEnv,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            entry.state = 'failed';
+            entry.error = err instanceof Error ? err.message : String(err);
+            entry.endedAt = new Date().toISOString();
+            await cleanupTmpFile(tmpFile);
+            entry.tmpFile = null;
+            entry.resolveExit(buildStatus(entry));
+            return entry;
+        }
+        entry.child = child;
+        entry.pid = child.pid ?? null;
+        entry.state = 'running';
+        // Buffer stdout lines into the ring buffer.
+        child.stdout?.setEncoding('utf-8');
+        child.stdout?.on('data', (chunk) => {
+            for (const rawLine of chunk.split('\n')) {
+                const line = rawLine.trimEnd();
+                if (line.length === 0)
+                    continue;
+                appendOutputLine(entry.outputBuffer, { source: 'stdout', line, timestamp: new Date().toISOString() }, bufferSize);
+            }
+        });
+        // Buffer stderr lines into the ring buffer.
+        child.stderr?.setEncoding('utf-8');
+        child.stderr?.on('data', (chunk) => {
+            for (const rawLine of chunk.split('\n')) {
+                const line = rawLine.trimEnd();
+                if (line.length === 0)
+                    continue;
+                appendOutputLine(entry.outputBuffer, { source: 'stderr', line, timestamp: new Date().toISOString() }, bufferSize);
+            }
+        });
+        // Handle process exit.
+        child.on('close', async (code, signal) => {
+            if (entry.killTimer !== null) {
+                clearTimeout(entry.killTimer);
+                entry.killTimer = null;
+            }
+            entry.child = null;
+            entry.endedAt = new Date().toISOString();
+            if (entry.state === 'running') {
+                entry.state = signal !== null ? 'killed' : 'exited';
+                entry.exitCode = code;
+                entry.terminatingSignal = signal;
+            }
+            await cleanupTmpFile(entry.tmpFile);
+            entry.tmpFile = null;
+            entry.resolveExit(buildStatus(entry));
+        });
+        return entry;
+    }
+    /**
+     * 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) {
+        if (entry.child === null || entry.state !== 'running')
+            return;
+        const graceMs = getTerminateGraceMs();
+        entry.state = 'killed';
+        try {
+            entry.child.kill('SIGTERM');
+        }
+        catch {
+            // Process may have already exited between the state check and the signal.
+        }
+        entry.killTimer = setTimeout(() => {
+            entry.killTimer = null;
+            if (entry.child !== null) {
+                try {
+                    entry.child.kill('SIGKILL');
+                }
+                catch {
+                    // Already dead — ignore.
+                }
+            }
+        }, graceMs);
+    }
+}
+//# sourceMappingURL=pi-wrapper.js.map

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

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

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

@@ -0,0 +1,185 @@
+/**
+ * HarnessAdapter type contract for cleo-os sandbox harnesses.
+ *
+ * Defines the minimal surface a cleo-os harness adapter must expose for
+ * controlling a process lifecycle: spawn, status, kill, and output streaming.
+ * This interface is intentionally simpler than the full CAAMP
+ * {@link packages/caamp | Harness} contract — cleo-os adapters wrap an
+ * external agent binary rather than a first-class CAAMP provider.
+ *
+ * @remarks
+ * cleo-os harness adapters follow the OpenClaw sandbox pattern: a thin
+ * TypeScript wrapper that controls an external binary (Pi, Claude Code, etc.)
+ * inside either a host-native or Docker sandbox environment.
+ *
+ * @see ADR-049 — CleoOS Sovereignty Invariants
+ * @see ADR-050 — CleoOS Sovereign Harness: Distribution Binding Charter
+ * @packageDocumentation
+ */
+/**
+ * Lifecycle state of a spawned harness process.
+ *
+ * - `'running'` — process was started and has not yet exited.
+ * - `'exited'` — process exited normally (exit code may be non-zero).
+ * - `'killed'` — process was terminated via {@link HarnessAdapter.kill}.
+ * - `'failed'` — process could not be started (pre-spawn error).
+ *
+ * @public
+ */
+export type HarnessProcessState = 'running' | 'exited' | 'killed' | 'failed';
+/**
+ * Describes a running or completed harness process.
+ *
+ * @public
+ */
+export interface HarnessProcessStatus {
+    /** Stable identifier for this process instance. */
+    instanceId: string;
+    /** Task ID associated with this process. */
+    taskId: string;
+    /** Current lifecycle state. */
+    state: HarnessProcessState;
+    /** OS process ID, or `null` when the process could not be started. */
+    pid: number | null;
+    /** ISO-8601 timestamp when the process was spawned. */
+    startedAt: string;
+    /**
+     * ISO-8601 timestamp when the process ended.
+     * Only populated when `state` is `'exited'` or `'killed'`.
+     * @defaultValue undefined
+     */
+    endedAt?: string;
+    /**
+     * Exit code from the process.
+     * Only populated when `state` is `'exited'`.
+     * @defaultValue undefined
+     */
+    exitCode?: number | null;
+    /**
+     * Error message when `state` is `'failed'`.
+     * @defaultValue undefined
+     */
+    error?: string;
+}
+/**
+ * A single line of output emitted from a harness process.
+ *
+ * @public
+ */
+export interface HarnessOutputLine {
+    /** Source stream: stdout or stderr. */
+    source: 'stdout' | 'stderr';
+    /** The text content of this line (without trailing newline). */
+    line: string;
+    /** ISO-8601 timestamp when this line was captured. */
+    timestamp: string;
+}
+/**
+ * Options passed to {@link HarnessAdapter.spawn}.
+ *
+ * @public
+ */
+export interface HarnessSpawnOptions {
+    /**
+     * Working directory for the spawned process.
+     * @defaultValue `process.cwd()`
+     */
+    cwd?: string;
+    /**
+     * Environment variable overrides merged atop the current process environment.
+     * @defaultValue undefined
+     */
+    env?: Record<string, string>;
+    /**
+     * When `true`, run the process inside a Docker sandbox container instead of
+     * host-native. Requires `CLEO_PI_SANDBOXED=1` or explicit `sandboxed: true`.
+     * @defaultValue false
+     */
+    sandboxed?: boolean;
+    /**
+     * Abort signal. When it fires, the adapter terminates the process via
+     * SIGTERM-then-SIGKILL with the configured grace window.
+     * @defaultValue undefined
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Result returned synchronously from {@link HarnessAdapter.spawn}.
+ *
+ * @public
+ */
+export interface HarnessSpawnResult {
+    /** Stable instance identifier (can be passed to status/kill/output). */
+    instanceId: string;
+    /** OS process ID, or `null` on failure. */
+    pid: number | null;
+    /** Promise resolving once the process exits or is killed. */
+    exitPromise: Promise<HarnessProcessStatus>;
+}
+/**
+ * Contract every cleo-os harness adapter MUST implement.
+ *
+ * @remarks
+ * A harness adapter wraps one external agent binary and exposes a uniform
+ * lifecycle surface. The adapter is responsible for:
+ *
+ * - Writing the prompt to the correct location (temp file or stdin).
+ * - Launching the external binary with the right flags and environment.
+ * - Optionally routing the launch through a Docker sandbox container
+ *   (see {@link HarnessSpawnOptions.sandboxed}).
+ * - Buffering recent output lines for post-mortem diagnostics.
+ * - Terminating processes cleanly via SIGTERM-then-SIGKILL.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new PiCodingAgentAdapter();
+ * const { instanceId, exitPromise } = await adapter.spawn('T123', 'Implement the feature', { cwd: '/project' });
+ * const status = await exitPromise;
+ * console.log(status.exitCode);
+ * ```
+ *
+ * @public
+ */
+export interface HarnessAdapter {
+    /** Short adapter identifier (e.g. `"pi-coding-agent"`). */
+    readonly id: string;
+    /**
+     * Spawn the agent binary with the given task prompt.
+     *
+     * @param taskId - Stable CLEO task identifier associated with this run.
+     * @param prompt - Prompt / instruction text to pass to the agent.
+     * @param opts - Spawn options (cwd, env, sandboxed, signal).
+     * @returns Spawn result containing the instance ID and exit promise.
+     */
+    spawn(taskId: string, prompt: string, opts?: HarnessSpawnOptions): Promise<HarnessSpawnResult>;
+    /**
+     * Query the current status of a spawned process.
+     *
+     * @param instanceId - Instance ID returned from {@link spawn}.
+     * @returns Current status, or `null` when the ID is not tracked.
+     */
+    status(instanceId: string): HarnessProcessStatus | null;
+    /**
+     * Terminate a running process.
+     *
+     * Sends SIGTERM, waits for the configured grace window (`CLEO_TERMINATE_GRACE_MS`
+     * or 5000 ms), then sends SIGKILL when the process has not yet exited.
+     * Idempotent — subsequent calls after the first are no-ops.
+     *
+     * @param instanceId - Instance ID returned from {@link spawn}.
+     */
+    kill(instanceId: string): Promise<void>;
+    /**
+     * Return recently captured output lines for a process.
+     *
+     * The adapter keeps a bounded ring buffer of the last
+     * `CLEO_HARNESS_OUTPUT_BUFFER` (default: 500) lines. Useful for
+     * post-mortem diagnostics without injecting output into the parent
+     * LLM context.
+     *
+     * @param instanceId - Instance ID returned from {@link spawn}.
+     * @returns Array of recent output lines, oldest first.
+     */
+    output(instanceId: string): HarnessOutputLine[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/harnesses/pi-coding-agent/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7E;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,sEAAsE;IACtE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,6DAA6D;IAC7D,WAAW,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/F;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAAC;IAExD;;;;;;;;OAQG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAAC;CACjD"}

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

@@ -0,0 +1,20 @@
+/**
+ * HarnessAdapter type contract for cleo-os sandbox harnesses.
+ *
+ * Defines the minimal surface a cleo-os harness adapter must expose for
+ * controlling a process lifecycle: spawn, status, kill, and output streaming.
+ * This interface is intentionally simpler than the full CAAMP
+ * {@link packages/caamp | Harness} contract — cleo-os adapters wrap an
+ * external agent binary rather than a first-class CAAMP provider.
+ *
+ * @remarks
+ * cleo-os harness adapters follow the OpenClaw sandbox pattern: a thin
+ * TypeScript wrapper that controls an external binary (Pi, Claude Code, etc.)
+ * inside either a host-native or Docker sandbox environment.
+ *
+ * @see ADR-049 — CleoOS Sovereignty Invariants
+ * @see ADR-050 — CleoOS Sovereign Harness: Distribution Binding Charter
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/harnesses/pi-coding-agent/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo-os",
-  "version": "2026.4.99",
+  "version": "2026.4.101",
   "description": "CleoOS — the batteries-included agentic development environment wrapping Pi",
   "type": "module",
   "main": "./dist/cli.js",
@@ -13,9 +13,9 @@
     "@mariozechner/pi-coding-agent": ">=0.60.0",
     "@sinclair/typebox": "^0.34.49",
     "env-paths": "^4.0.0",
-    "@cleocode/cant": "2026.4.99",
-    "@cleocode/cleo": "2026.4.99",
-    "@cleocode/core": "2026.4.99"
+    "@cleocode/cant": "2026.4.101",
+    "@cleocode/cleo": "2026.4.101",
+    "@cleocode/core": "2026.4.101"
   },
   "devDependencies": {
     "typescript": "^6.0.2",