@cogineai/dearharness 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cogine AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# DearHarness
+
+DearHarness is an OpenClaw Harness operator CLI and instance-side daemon prototype.
+
+It is derived from `cogine-ai/cliq-agent`, but it is not a generic coding agent. Cliq provides useful runtime substrate ideas; DearHarness focuses on Harness inspection, validation, installation, maintenance, packing, publishing, and platform-callable daemon tasks.
+
+## Current Status
+
+This repository is a standalone prototype. The main DearClaw platform repository may later consume or import stable pieces from it.
+
+V0 scope:
+
+- local CLI identity
+- OpenClaw workspace inspection
+- install-lock status reading
+- local Harness manifest validation
+- minimal private daemon task API
+
+V1 work has started with remote `.zip` and `.tar.gz` bundle source staging, dry-run install planning, conflict reporting, guarded file apply, and post-apply verification. DearHarness still does not claim full OpenClaw config mutation, publication, package signing, dependency solving, or OpenClaw plugin installation.
+
+## Quick Start
+
+Requirements: Node.js 20 or newer.
+
+```bash
+npm install
+npm run build
+node dist/index.js help
+```
+
+Inspect an OpenClaw-like workspace:
+
+```bash
+node dist/index.js inspect --target-workspace ~/.openclaw/workspace
+```
+
+Read local install status:
+
+```bash
+node dist/index.js status --target-workspace ~/.openclaw/workspace
+```
+
+Validate a Harness source directory:
+
+```bash
+node dist/index.js validate ./my-harness
+```
+
+Download and validate a remote Harness bundle without applying changes. The install runner accepts either a `.zip` or `.tar.gz` archive URL:
+
+```bash
+node dist/index.js install https://example.com/my-harness.zip --target-workspace ~/.openclaw/workspace --dry-run
+node dist/index.js install https://example.com/my-harness.tar.gz --target-workspace ~/.openclaw/workspace --dry-run
+```
+
+Apply a conflict-free plan explicitly:
+
+```bash
+node dist/index.js install https://example.com/my-harness.zip --target-workspace ~/.openclaw/workspace --apply
+node dist/index.js install https://example.com/my-harness.tar.gz --target-workspace ~/.openclaw/workspace --apply
+```
+
+Run the V0 daemon:
+
+```bash
+DEARHARNESS_DAEMON_TOKEN=dev-token node dist/index.js daemon --host 127.0.0.1 --port 18790
+```
+
+Submit a V0 daemon task:
+
+```bash
+curl -sS \
+  -H 'authorization: Bearer dev-token' \
+  -H 'content-type: application/json' \
+  -d '{"type":"inspect_workspace","targetWorkspace":"/workspace/openclaw"}' \
+  http://127.0.0.1:18790/tasks
+```
+
+Submit a guarded install task to the daemon. The `source` field accepts either a `.zip` or `.tar.gz` archive URL:
+
+```bash
+curl -sS \
+  -H 'authorization: Bearer dev-token' \
+  -H 'content-type: application/json' \
+  -d '{"type":"install_harness","source":"https://example.com/my-harness.zip","targetWorkspace":"/workspace/openclaw","mode":"dry_run"}' \
+  http://127.0.0.1:18790/tasks
+
+curl -sS \
+  -H 'authorization: Bearer dev-token' \
+  -H 'content-type: application/json' \
+  -d '{"type":"install_harness","source":"https://example.com/my-harness.tar.gz","targetWorkspace":"/workspace/openclaw","mode":"dry_run"}' \
+  http://127.0.0.1:18790/tasks
+```
+
+## Repository Guide
+
+Read these first:
+
+- `AGENTS.md`
+- `docs/project.md`
+- `docs/architecture.md`
+- `docs/roadmap.md`
+- `docs/superpowers/plans/2026-04-30-dearharness-v0.md`
+
+## Relationship To DearClaw
+
+DearClaw owns platform policy, auth, catalog, publish review, audit, billing, and user-facing status.
+
+DearHarness owns local execution near OpenClaw:
+
+- inspect workspace/config
+- validate packages
+- apply deterministic install and maintenance tools
+- expose a private daemon for platform task execution
+
+## Relationship To Cliq
+
+The `cliq-upstream` git remote may remain pointed at `https://github.com/cogine-ai/cliq-agent.git` for reference and selective runtime reuse. It should not be used as the DearHarness publishing remote.
+
+If DearHarness needs a generally useful runtime capability, prefer opening an upstream Cliq issue instead of permanently hiding the change in this fork.
+
+Extensions are intentionally limited to hooks and instruction contributions. They do not register new model-callable top-level actions.
+
+## V0 Task Types
+
+The daemon currently accepts synchronous task requests:
+
+- `inspect_workspace`: `{ "type": "inspect_workspace", "targetWorkspace": "/path" }`
+- `read_status`: `{ "type": "read_status", "targetWorkspace": "/path" }`
+- `validate_harness`: `{ "type": "validate_harness", "sourcePath": "/path" }`
+- `install_harness`: `{ "type": "install_harness", "source": "https://example.com/my-harness.zip", "targetWorkspace": "/path", "mode": "dry_run" }`. The `source` field accepts an http(s) `.zip` or `.tar.gz` URL, and `mode` is either `dry_run` or `apply`.
+
+These are deliberately narrow. Future agentic maintenance should choose from deterministic tools instead of relying on unrestricted shell execution.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,259 @@
+import { startDaemon } from './daemon/server.js';
+import { executeHarnessInstall } from './harness/install-runner.js';
+import { readInstallLockfile } from './harness/lockfile.js';
+import { validateHarnessSource } from './harness/manifest.js';
+import { inspectOpenClawWorkspace } from './harness/workspace.js';
+export class ReportedCliError extends Error {
+    constructor(error) {
+        super(error instanceof Error ? error.message : String(error), { cause: error });
+        this.name = 'ReportedCliError';
+    }
+}
+export function isReportedCliError(error) {
+    return error instanceof ReportedCliError;
+}
+export function renderUnhandledError(error) {
+    if (isReportedCliError(error)) {
+        return null;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function readFlagValue(raw, index, flag) {
+    const value = raw[index + 1];
+    if (value === undefined || value === '' || value.startsWith('-')) {
+        throw new Error(`Missing value for ${flag}`);
+    }
+    return value;
+}
+function takeStringOption(raw, index, flag) {
+    const token = raw[index];
+    if (token.startsWith(`${flag}=`)) {
+        const value = token.slice(flag.length + 1);
+        if (!value)
+            throw new Error(`Missing value for ${flag}`);
+        return { value, nextIndex: index };
+    }
+    if (token === flag) {
+        return { value: readFlagValue(raw, index, flag), nextIndex: index + 1 };
+    }
+    return null;
+}
+function readTargetWorkspace(raw) {
+    let targetWorkspace = null;
+    const passthrough = [];
+    for (let i = 0; i < raw.length; i += 1) {
+        const target = takeStringOption(raw, i, '--target-workspace') ?? takeStringOption(raw, i, '--workspace');
+        if (target) {
+            targetWorkspace = target.value;
+            i = target.nextIndex;
+            continue;
+        }
+        passthrough.push(raw[i]);
+    }
+    if (!targetWorkspace) {
+        throw new Error('Missing value for --target-workspace');
+    }
+    if (passthrough.length > 0) {
+        throw new Error(`Unexpected argument for workspace command: ${passthrough[0]}`);
+    }
+    return targetWorkspace;
+}
+function readValidateSource(raw) {
+    let sourcePath = null;
+    const passthrough = [];
+    for (let i = 0; i < raw.length; i += 1) {
+        const source = takeStringOption(raw, i, '--source');
+        if (source) {
+            sourcePath = source.value;
+            i = source.nextIndex;
+            continue;
+        }
+        passthrough.push(raw[i]);
+    }
+    if (!sourcePath) {
+        sourcePath = passthrough.shift() ?? null;
+    }
+    if (!sourcePath) {
+        throw new Error('Missing harness source path');
+    }
+    if (passthrough.length > 0) {
+        throw new Error(`Unexpected argument for validate command: ${passthrough[0]}`);
+    }
+    return sourcePath;
+}
+function readInstallOptions(raw) {
+    let source = null;
+    let targetWorkspace = null;
+    let dryRun = false;
+    let apply = false;
+    let expectedSha256;
+    const passthrough = [];
+    for (let i = 0; i < raw.length; i += 1) {
+        const target = takeStringOption(raw, i, '--target-workspace') ?? takeStringOption(raw, i, '--workspace');
+        if (target) {
+            targetWorkspace = target.value;
+            i = target.nextIndex;
+            continue;
+        }
+        const sha256 = takeStringOption(raw, i, '--sha256');
+        if (sha256) {
+            expectedSha256 = sha256.value;
+            i = sha256.nextIndex;
+            continue;
+        }
+        if (raw[i] === '--dry-run') {
+            dryRun = true;
+            continue;
+        }
+        if (raw[i] === '--apply') {
+            apply = true;
+            continue;
+        }
+        passthrough.push(raw[i]);
+    }
+    source = passthrough.shift() ?? null;
+    if (!source) {
+        throw new Error('Missing harness source URL');
+    }
+    if (!targetWorkspace) {
+        throw new Error('Missing value for --target-workspace');
+    }
+    if (passthrough.length > 0) {
+        throw new Error(`Unexpected argument for install command: ${passthrough[0]}`);
+    }
+    if (dryRun && apply) {
+        throw new Error('install accepts either --dry-run or --apply, not both');
+    }
+    return {
+        source,
+        targetWorkspace,
+        dryRun,
+        ...(apply ? { apply: true } : {}),
+        ...(expectedSha256 ? { expectedSha256 } : {}),
+    };
+}
+function readDaemonOptions(raw) {
+    let host = '127.0.0.1';
+    let port = 18790;
+    let token = process.env.DEARHARNESS_DAEMON_TOKEN ?? null;
+    const passthrough = [];
+    for (let i = 0; i < raw.length; i += 1) {
+        const hostOption = takeStringOption(raw, i, '--host');
+        if (hostOption) {
+            host = hostOption.value;
+            i = hostOption.nextIndex;
+            continue;
+        }
+        const portOption = takeStringOption(raw, i, '--port');
+        if (portOption) {
+            const parsed = Number(portOption.value);
+            if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+                throw new Error('--port must be an integer between 0 and 65535');
+            }
+            port = parsed;
+            i = portOption.nextIndex;
+            continue;
+        }
+        const tokenOption = takeStringOption(raw, i, '--token');
+        if (tokenOption) {
+            token = tokenOption.value;
+            i = tokenOption.nextIndex;
+            continue;
+        }
+        passthrough.push(raw[i]);
+    }
+    if (passthrough.length > 0) {
+        throw new Error(`Unexpected argument for daemon command: ${passthrough[0]}`);
+    }
+    return { host, port, token };
+}
+export function parseArgs(argv) {
+    const raw = argv.slice(2);
+    const command = raw.shift();
+    if (!command || command === 'help' || command === '--help' || command === '-h') {
+        return { command: 'help' };
+    }
+    if (command === 'inspect') {
+        return { command, targetWorkspace: readTargetWorkspace(raw) };
+    }
+    if (command === 'status') {
+        return { command, targetWorkspace: readTargetWorkspace(raw) };
+    }
+    if (command === 'validate') {
+        return { command, sourcePath: readValidateSource(raw) };
+    }
+    if (command === 'install') {
+        return { command, ...readInstallOptions(raw) };
+    }
+    if (command === 'daemon') {
+        return { command, ...readDaemonOptions(raw) };
+    }
+    throw new Error(`Unknown dearharness command: ${command}`);
+}
+export function formatHelp() {
+    return `dearharness - OpenClaw Harness operator
+
+Usage:
+  dearharness inspect --target-workspace PATH
+  dearharness status --target-workspace PATH
+  dearharness validate PATH
+  dearharness install URL --target-workspace PATH --dry-run
+  dearharness install URL --target-workspace PATH --apply
+  dearharness daemon [--host HOST] [--port PORT] [--token TOKEN]
+  dearharness help
+
+Commands:
+  inspect    Describe an OpenClaw workspace without modifying it
+  status     Read the DearHarness install lockfile
+  validate   Validate a harness source directory and manifest
+  install    Plan or apply a remote harness bundle through guarded staging
+  daemon     Serve private-network task requests for a DearClaw instance
+
+Environment:
+  DEARHARNESS_DAEMON_TOKEN   Default bearer token for daemon mode
+`;
+}
+export function printHelp(io = {}) {
+    const write = io.stdout ?? ((value) => process.stdout.write(value));
+    write(formatHelp());
+}
+function writeJson(io, value) {
+    const write = io.stdout ?? ((chunk) => process.stdout.write(chunk));
+    write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export async function runCli(argv, io = {}, dependencies = {}) {
+    const args = parseArgs(argv);
+    if (args.command === 'help') {
+        printHelp(io);
+        return;
+    }
+    if (args.command === 'inspect') {
+        writeJson(io, await inspectOpenClawWorkspace(args.targetWorkspace));
+        return;
+    }
+    if (args.command === 'status') {
+        writeJson(io, await readInstallLockfile(args.targetWorkspace));
+        return;
+    }
+    if (args.command === 'validate') {
+        writeJson(io, await validateHarnessSource(args.sourcePath));
+        return;
+    }
+    if (args.command === 'install') {
+        if (!args.dryRun && !args.apply) {
+            throw new Error('install requires either --dry-run or --apply');
+        }
+        writeJson(io, await executeHarnessInstall({
+            source: args.source,
+            targetWorkspace: args.targetWorkspace,
+            mode: args.apply ? 'apply' : 'dry_run',
+            ...(args.expectedSha256 ? { expectedSha256: args.expectedSha256 } : {}),
+            ...(dependencies.materializeHarnessSource ? { materializeHarnessSource: dependencies.materializeHarnessSource } : {}),
+        }));
+        return;
+    }
+    if (args.command === 'daemon') {
+        const daemon = await startDaemon({ host: args.host, port: args.port, token: args.token });
+        writeJson(io, { ok: true, service: 'dearharness-daemon', host: daemon.host, port: daemon.port });
+    }
+}

package/dist/config.js

@@ -0,0 +1,21 @@
+export const MODEL = 'anthropic/claude-sonnet-4.6';
+export const DEFAULT_MODEL_PROVIDER = 'openrouter';
+export const DEFAULT_MODEL_BASE_URL = 'https://openrouter.ai/api/v1';
+export const OLLAMA_DEFAULT_BASE_URL = 'http://localhost:11434';
+export const OLLAMA_DEFAULT_MODEL_HINT = 'qwen3:4b';
+export const OLLAMA_DISCOVERY_TIMEOUT_MS = 2_000;
+export const APP_DIR = '.cliq';
+export const SESSION_FILE = 'session.json';
+export const MAX_LOOPS = 24;
+export const MAX_OUTPUT = 12_000;
+export const BASH_TIMEOUT_MS = 60_000;
+export const MODEL_TIMEOUT_MS = 20_000;
+export const OPENROUTER_TIMEOUT_MS = MODEL_TIMEOUT_MS;
+export const SESSION_VERSION = 4;
+export const DEFAULT_POLICY_MODE = 'auto';
+export const READ_MAX_BYTES = 8_000;
+export const LIST_MAX_ENTRIES = 200;
+export const FIND_MAX_RESULTS = 200;
+export const FIND_MAX_DEPTH = 12;
+export const GREP_MAX_MATCHES = 200;
+export const GREP_MAX_FILE_BYTES = 64_000;

package/dist/daemon/server.js

@@ -0,0 +1,225 @@
+import { randomUUID } from 'node:crypto';
+import http from 'node:http';
+import { executeHarnessInstall } from '../harness/install-runner.js';
+import { readInstallLockfile } from '../harness/lockfile.js';
+import { validateHarnessSource } from '../harness/manifest.js';
+import { inspectOpenClawWorkspace } from '../harness/workspace.js';
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function jsonResponse(value, status = 200) {
+    return new Response(JSON.stringify(value), {
+        status,
+        headers: { 'content-type': 'application/json; charset=utf-8' },
+    });
+}
+function requireBearerToken(request, token) {
+    if (!token)
+        return null;
+    if (request.headers.get('authorization') === `Bearer ${token}`)
+        return null;
+    return jsonResponse({ error: 'unauthorized' }, 401);
+}
+function readNonEmptyString(record, field) {
+    const value = record[field];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function parseTaskRequest(value) {
+    if (!isRecord(value))
+        return { task: null, error: 'task request must be a JSON object' };
+    if (value.type === 'inspect_workspace') {
+        const targetWorkspace = readNonEmptyString(value, 'targetWorkspace');
+        if (!targetWorkspace) {
+            return { task: null, error: 'inspect_workspace targetWorkspace must be a non-empty string' };
+        }
+        return { task: { type: 'inspect_workspace', targetWorkspace }, error: null };
+    }
+    if (value.type === 'read_status') {
+        const targetWorkspace = readNonEmptyString(value, 'targetWorkspace');
+        if (!targetWorkspace) {
+            return { task: null, error: 'read_status targetWorkspace must be a non-empty string' };
+        }
+        return { task: { type: 'read_status', targetWorkspace }, error: null };
+    }
+    if (value.type === 'validate_harness') {
+        const sourcePath = readNonEmptyString(value, 'sourcePath');
+        if (!sourcePath) {
+            return { task: null, error: 'validate_harness sourcePath must be a non-empty string' };
+        }
+        return { task: { type: 'validate_harness', sourcePath }, error: null };
+    }
+    if (value.type === 'install_harness') {
+        const source = readNonEmptyString(value, 'source');
+        if (!source) {
+            return { task: null, error: 'install_harness source must be a non-empty string' };
+        }
+        const targetWorkspace = readNonEmptyString(value, 'targetWorkspace');
+        if (!targetWorkspace) {
+            return { task: null, error: 'install_harness targetWorkspace must be a non-empty string' };
+        }
+        if (value.mode !== 'dry_run' && value.mode !== 'apply') {
+            return { task: null, error: 'install_harness mode must be dry_run or apply' };
+        }
+        if (value.expectedSha256 !== undefined && (typeof value.expectedSha256 !== 'string' || value.expectedSha256.length === 0)) {
+            return { task: null, error: 'install_harness expectedSha256 must be a non-empty string when present' };
+        }
+        return {
+            task: {
+                type: 'install_harness',
+                source,
+                targetWorkspace,
+                mode: value.mode,
+                ...(value.expectedSha256 ? { expectedSha256: value.expectedSha256 } : {}),
+            },
+            error: null,
+        };
+    }
+    return { task: null, error: 'unknown task type' };
+}
+async function runTask(task) {
+    if (task.type === 'inspect_workspace') {
+        return inspectOpenClawWorkspace(task.targetWorkspace);
+    }
+    if (task.type === 'read_status') {
+        return readInstallLockfile(task.targetWorkspace);
+    }
+    if (task.type === 'install_harness') {
+        return executeHarnessInstall({
+            source: task.source,
+            targetWorkspace: task.targetWorkspace,
+            mode: task.mode,
+            ...(task.expectedSha256 ? { expectedSha256: task.expectedSha256 } : {}),
+        });
+    }
+    return validateHarnessSource(task.sourcePath);
+}
+async function parseJsonBody(request) {
+    try {
+        return { value: await request.json(), error: null };
+    }
+    catch (error) {
+        return {
+            value: null,
+            error: `invalid JSON body: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function nodeHeadersToHeaders(request) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                headers.append(name, item);
+            continue;
+        }
+        headers.set(name, value);
+    }
+    return headers;
+}
+async function nodeRequestToWebRequest(request) {
+    const chunks = [];
+    for await (const chunk of request) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const method = request.method ?? 'GET';
+    const headers = nodeHeadersToHeaders(request);
+    const host = headers.get('host') ?? '127.0.0.1';
+    const body = method === 'GET' || method === 'HEAD' || chunks.length === 0 ? undefined : Buffer.concat(chunks);
+    return new Request(`http://${host}${request.url ?? '/'}`, { method, headers, body });
+}
+async function writeWebResponse(response, target) {
+    target.statusCode = response.status;
+    response.headers.forEach((value, name) => target.setHeader(name, value));
+    target.end(Buffer.from(await response.arrayBuffer()));
+}
+export function createDaemonServer(options = {}) {
+    const tasks = new Map();
+    return {
+        async handleRequest(request) {
+            const url = new URL(request.url);
+            if (request.method === 'GET' && url.pathname === '/healthz') {
+                return jsonResponse({ ok: true, service: 'dearharness-daemon' });
+            }
+            if (url.pathname === '/tasks' || url.pathname.startsWith('/tasks/')) {
+                const authResponse = requireBearerToken(request, options.token);
+                if (authResponse)
+                    return authResponse;
+            }
+            if (request.method === 'POST' && url.pathname === '/tasks') {
+                const parsedBody = await parseJsonBody(request);
+                if (parsedBody.error)
+                    return jsonResponse({ error: parsedBody.error }, 400);
+                const parsedTask = parseTaskRequest(parsedBody.value);
+                if (!parsedTask.task)
+                    return jsonResponse({ error: parsedTask.error }, 400);
+                const createdAt = new Date().toISOString();
+                const record = {
+                    id: randomUUID(),
+                    status: 'succeeded',
+                    request: parsedTask.task,
+                    result: null,
+                    error: null,
+                    createdAt,
+                    finishedAt: createdAt,
+                };
+                try {
+                    record.result = await runTask(parsedTask.task);
+                    record.finishedAt = new Date().toISOString();
+                }
+                catch (error) {
+                    record.status = 'failed';
+                    record.error = error instanceof Error ? error.message : String(error);
+                    record.finishedAt = new Date().toISOString();
+                }
+                tasks.set(record.id, record);
+                return jsonResponse(record, record.status === 'succeeded' ? 200 : 500);
+            }
+            if (request.method === 'GET' && url.pathname.startsWith('/tasks/')) {
+                const id = decodeURIComponent(url.pathname.slice('/tasks/'.length));
+                const record = tasks.get(id);
+                if (!record)
+                    return jsonResponse({ error: 'task not found' }, 404);
+                return jsonResponse(record);
+            }
+            return jsonResponse({ error: 'not found' }, 404);
+        },
+    };
+}
+export async function startDaemon(options = {}) {
+    const host = options.host ?? '127.0.0.1';
+    const daemon = createDaemonServer(options);
+    const server = http.createServer((request, response) => {
+        nodeRequestToWebRequest(request)
+            .then((webRequest) => daemon.handleRequest(webRequest))
+            .then((webResponse) => writeWebResponse(webResponse, response))
+            .catch((error) => writeWebResponse(jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 500), response));
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(options.port ?? 18790, host);
+    });
+    const address = server.address();
+    return {
+        host,
+        port: address.port,
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        }),
+    };
+}

package/dist/extensions/builtin/policy-instructions.js

@@ -0,0 +1,19 @@
+export const policyInstructionsExtension = {
+    name: 'policy-instructions',
+    instructionSources: [
+        async ({ policyMode }) => {
+            if (policyMode === 'auto') {
+                return [];
+            }
+            return [
+                {
+                    role: 'system',
+                    layer: 'extension',
+                    source: 'policy-instructions',
+                    content: `Current policy mode is ${policyMode}. Plan actions that can succeed under this mode and explain when a write or exec step would be blocked.`
+                }
+            ];
+        }
+    ],
+    hooks: []
+};