@anureo/sdk 0.2.0 → 0.3.0

package/src/privacy/secrets.js

@@ -0,0 +1,564 @@
+// Registers explicitly marked secrets and projects public events, state and history.
+import { boundFileChangeItem } from "./file-change-limits.js";
+import { assertDefinition } from "@anureo/protocol";
+import { HarnessSdkError } from "../errors.js";
+/**
+ * Register explicitly marked answers before projecting content for public observation.
+ * This root-exported implementation helper is owned by Session, which installs registration in
+ * InteractionRegistry's pre-response callback and projects events and request results. Direct
+ * consumers own the same registration/publication order. Secrets and pending prefixes stay in
+ * memory; the optional synchronous hook owns persistence. No native resources are acquired.
+ */
+export class SecretRedactor {
+    onRemember;
+    /**
+     * Create an empty in-memory registry with an optional synchronous persistence hook. Session
+     * forwards runtime.onMarkedSecret here; rememberScalar invokes it before accepting each new value.
+     * Construction only retains the hook. The host owns persistence and any effects its hook performs.
+     */
+    constructor(onRemember) {
+        this.onRemember = onRemember;
+    }
+    /**
+     * Register answers marked secret/writeOnly by the request before exposing or delivering them.
+     * Marked containers contribute their scalar descendants. Numbers and booleans register by string
+     * value, while empty strings, null and duplicates are ignored. At most 128 distinct values and
+     * 64 KiB of UTF-8 text are retained. Exceeding either cap throws a HarnessSdkError with code
+     * BACKPRESSURE_EXCEEDED. Hook exceptions also propagate, leaving earlier registrations intact.
+     * Schema traversal stops beyond depth 32, with the request schema at depth zero.
+     * Session installs this as InteractionRegistry's pre-response check. InteractionRegistry.respond
+     * invokes it after validation and rejects on failure before looking up a replay or starting native
+     * delivery. Direct consumers own validation and delivery.
+     */
+    rememberResponse(request, response) {
+        if (request.kind === "userInput" && response.kind === "userInput") {
+            for (const question of request.questions) {
+                if (question.secret)
+                    this.remember(response.answers[question.id]);
+            }
+        }
+        if (request.kind === "elicitation" && response.kind === "elicitation" && response.content && request.schema !== undefined) {
+            this.fromSchema(request.schema, response.content, { root: request.schema, depth: 0 });
+        }
+        if (request.kind === "dynamicTool" && response.kind === "dynamicTool" && request.schema !== undefined) {
+            this.fromSchema(request.schema, response, { root: request.schema, depth: 0 });
+        }
+    }
+    /**
+     * Replace complete secret matches with [redacted], preferring the longest match at each position.
+     * Unmatched trailing prefixes are emitted without retaining stream state. Session.projectOutput
+     * and Session.projectSubmissionStatus use this before exposure. OutputSession.publishOutput
+     * revalidates JSON returned through projectOutput and converts schema failures into failed turns.
+     */
+    text(value) { return this.values.size ? this.scan(value, "complete").text : value; }
+    /**
+     * Project an ordered text chunk, withholding a possible trailing secret prefix until the next chunk.
+     * Complete matches win even when a longer secret is incomplete. event scopes streams by turn/item
+     * and discards pending prefixes on item/completed, whose snapshot carries authoritative full text.
+     * Direct consumers must use distinct ordered keys; this method has no flush/reset operation, so
+     * they must discard the redactor when they no longer need its retained prefixes and secrets.
+     */
+    delta(stream, value) {
+        if (!this.values.size)
+            return value;
+        const result = this.scan((this.streams.get(stream) ?? "") + value, "stream");
+        if (result.pending)
+            this.streams.set(stream, result.pending);
+        else
+            this.streams.delete(stream);
+        return result.text;
+    }
+    /**
+     * Return recursively projected JSON without mutating the input. Marked numbers and booleans become
+     * the string [redacted]. If projected keys collide, the last entry in traversal order wins.
+     * Session.projectSubmissionStatus selects receipt and error content. Direct callers should also
+     * pass only content fields to preserve protocol identity.
+     */
+    json(value) {
+        if (typeof value === "string")
+            return this.text(value);
+        if (typeof value === "number" || typeof value === "boolean")
+            return this.values.has(String(value)) ? "[redacted]" : value;
+        if (Array.isArray(value))
+            return value.map((entry) => this.json(entry));
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).map(([key, child]) => [this.text(key), this.json(child)]));
+        return value;
+    }
+    /**
+     * Project configuration annotations and values without modifying validation constraints or
+     * property names. Return the original value when no configuration is advertised. state uses this
+     * for session snapshots; the caller owns storing or publishing the result.
+     */
+    capabilities(value) {
+        if (!value.config)
+            return value;
+        return {
+            ...value,
+            config: {
+                ...value.config,
+                options: value.config.options.map((option) => ({
+                    ...option,
+                    ...(option.title !== undefined ? { title: this.text(option.title) } : {}),
+                    ...(option.value !== undefined ? { value: this.json(option.value) } : {}),
+                    schema: this.schema(option.schema),
+                })),
+            },
+        };
+    }
+    /**
+     * Return a new outer value with projected goal JSON and unchanged native goal metadata.
+     * state and result call this before exposing goal content; no session state is written here.
+     */
+    goal(value) { return { ...value, goal: value.goal === null ? null : this.json(value.goal) }; }
+    /**
+     * Project content-bearing state fields while preserving bindings, protocol enums and revisions; no
+     * session bookkeeping is changed. Session.snapshot calls this on reads; event and result use it
+     * for state/config observations. Session freezes reads and validates/stores request results;
+     * direct consumers retain responsibility for validation and publication.
+     */
+    state(value) {
+        return {
+            ...value,
+            ...(value.metadata ? { metadata: this.json(value.metadata) } : {}),
+            config: Object.fromEntries(Object.entries(value.config).map(([id, entry]) => [id, this.json(entry)])),
+            capabilities: this.capabilities(value.capabilities),
+            ...(value.goal ? { goal: this.goal(value.goal) } : {}),
+        };
+    }
+    /**
+     * Project a validated configuration or goal result according to its method. Other results pass
+     * through by identity. Session.projectRequestResult routes history to history() and calls this
+     * for other projectable results. Session.executeRequest stores projected configuration or goal
+     * state and validates and freezes the returned result. Direct callers own validation and storage.
+     */
+    result(method, value) {
+        if (method === "session/config/set")
+            return this.state(value);
+        if (method === "goal/set" || method === "goal/clear")
+            return this.goal(value);
+        return value;
+    }
+    /**
+     * Project validated item content without changing protocol identity or registering new secrets.
+     * Tool-call file changes additionally use the shared material/mirror budget. event uses this for
+     * snapshots and validated patches; history applies it to each native entry. Direct consumers
+     * must validate item shape first, as Session and deltaValue do for their respective input paths.
+     */
+    item(item) {
+        if (item.extensions)
+            item = { ...item, extensions: this.json(item.extensions) };
+        switch (item.type) {
+            case "agentMessage": return { ...item, text: this.text(item.text) };
+            case "userMessage": return { ...item, content: item.content.map((block) => this.input(block)) };
+            case "reasoning": return {
+                ...item,
+                ...(item.text ? { text: this.text(item.text) } : {}),
+                ...(item.summary ? { summary: this.text(item.summary) } : {}),
+            };
+            case "toolCall": return this.toolCall(item);
+            case "plan": return { ...item, steps: item.steps.map((step) => ({ ...step, text: this.text(step.text) })) };
+            case "subagent": return {
+                ...item,
+                ...(item.name ? { name: this.text(item.name) } : {}),
+                ...(item.task ? { task: this.text(item.task) } : {}),
+            };
+            case "review": return { ...item, ...(item.text ? { text: this.text(item.text) } : {}) };
+            case "compaction": return { ...item, ...(item.summary ? { summary: this.text(item.summary) } : {}) };
+            case "hook": return {
+                ...item,
+                name: this.text(item.name),
+                ...(item.input !== undefined ? { input: this.json(item.input) } : {}),
+                ...(item.output !== undefined ? { output: this.json(item.output) } : {}),
+            };
+            case "notice": return { ...item, text: this.text(item.text) };
+        }
+    }
+    /**
+     * Project public request content while preserving identifiers, answer keys and protocol alternatives.
+     * event calls this after Session.requestInteraction applies protocol publicInteraction; direct
+     * consumers must likewise apply protocol privacy rules first. If a privatePayload is supplied
+     * directly, this method projects its JSON content and retains the field. InteractionRegistry
+     * retains the native request for response validation and marked-field lookup.
+     */
+    interaction(request) {
+        const common = {
+            ...request,
+            ...(request.title ? { title: this.text(request.title) } : {}),
+            ...(request.privatePayload ? { privatePayload: this.json(request.privatePayload) } : {}),
+        };
+        switch (common.kind) {
+            case "approval": return {
+                ...common,
+                ...(common.input !== undefined ? { input: this.json(common.input) } : {}),
+                options: common.options.map((option) => ({
+                    ...option,
+                    label: this.text(option.label),
+                    ...(option.description ? { description: this.text(option.description) } : {}),
+                })),
+            };
+            case "userInput": return {
+                ...common,
+                questions: common.questions.map((question) => ({
+                    ...question,
+                    prompt: this.text(question.prompt),
+                    ...(question.options ? { options: question.options.map((option) => ({ ...option, label: this.text(option.label) })) } : {}),
+                })),
+            };
+            case "elicitation": return { ...common, ...(common.message ? { message: this.text(common.message) } : {}) };
+            case "dynamicTool": return { ...common, arguments: this.json(common.arguments) };
+        }
+    }
+    /**
+     * Project validated events in publication order, clearing an item's buffered prefix on completion.
+     * Supply turnId to isolate reused item IDs across turns. Omission uses an item-only stream key.
+     * Session.publish invokes this after lifecycle admission and before retaining/publishing results.
+     * An invalid Item-shaped patch throws ProtocolValidationError and rejects Session.emit, which
+     * starts observation teardown. Direct consumers own event validation, ordering and publication.
+     * Completed snapshots supply authoritative item content.
+     */
+    event(event, turnId) {
+        switch (event.type) {
+            case "item/started":
+            case "item/completed": {
+                if (event.type === "item/completed")
+                    this.streams.delete(streamKey(event.payload.item.id, turnId));
+                return { ...event, payload: { item: this.item(event.payload.item) } };
+            }
+            case "item/delta": return { ...event, payload: this.itemDelta(event.payload, turnId) };
+            case "notice": return {
+                ...event,
+                payload: {
+                    ...event.payload,
+                    message: this.text(event.payload.message),
+                    ...(event.payload.raw !== undefined ? { raw: this.json(event.payload.raw) } : {}),
+                },
+            };
+            case "extension": return { ...event, payload: { ...event.payload, data: this.json(event.payload.data) } };
+            case "session/metadata": return { ...event, payload: this.json(event.payload) };
+            case "session/state": return { ...event, payload: this.state(event.payload) };
+            case "interaction/requested": return { ...event, payload: this.interaction(event.payload) };
+            case "turn/completed": return {
+                ...event,
+                payload: {
+                    ...event.payload,
+                    ...(event.payload.error ? {
+                        error: {
+                            ...event.payload.error,
+                            message: this.text(event.payload.error.message),
+                            ...(event.payload.error.details ? { details: this.json(event.payload.error.details) } : {}),
+                        },
+                    } : {}),
+                },
+            };
+            default: return event;
+        }
+    }
+    /**
+     * Project a prevalidated history page using live items' privacy/retention rules, preserving
+     * pagination and execution identities. The input must already be validated; no history is fetched
+     * here. Session.projectRequestResult calls this before executeRequest awaits the optional host
+     * redactHistory hook, validates and freezes the result; host-hook rejection fails that request.
+     */
+    history(page) { return { ...page, items: page.items.map((entry) => ({ ...entry, item: this.item(entry.item) })) }; }
+    values = new Set();
+    streams = new Map();
+    secretBytes = 0;
+    /**
+     * rememberResponse and fromSchema call this before a response can be sent. Recursively retain marked
+     * scalar values within session budgets; invoke the host hook before accepting each new value.
+     * Capacity or hook failures throw to InteractionRegistry.respond before native delivery; values
+     * already accepted during the traversal remain registered, with no rollback of host effects.
+     */
+    remember(value) {
+        if (value === undefined || value === null)
+            return;
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            this.rememberScalar(value);
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach((entry) => this.remember(entry));
+            return;
+        }
+        for (const entry of Object.values(value))
+            this.remember(entry);
+    }
+    /**
+     * Accept a new nonempty scalar only after capacity checks and the synchronous persistence hook
+     * succeed. remember preserves traversal order, so a later failure never rolls back earlier values;
+     * a failed hook leaves this value unregistered and retryable.
+     */
+    rememberScalar(value) {
+        const text = String(value);
+        if (!text || this.values.has(text))
+            return;
+        const bytes = new TextEncoder().encode(text).byteLength;
+        if (this.values.size >= 128 || this.secretBytes + bytes > 64 * 1024) {
+            throw new HarnessSdkError("BACKPRESSURE_EXCEEDED", "Marked secret limit exceeded");
+        }
+        this.onRemember?.(text);
+        this.values.add(text);
+        this.secretBytes += bytes;
+    }
+    /**
+     * Resolve a reference beginning with #/ against the original request schema. Decode JSON Pointer
+     * escapes and follow object keys. A missing key or non-object intermediate yields undefined.
+     * fromSchema checks the returned node's shape before visiting it.
+     */
+    resolveLocalReference(reference, root) {
+        let target = root;
+        for (const token of reference.slice(2).split("/")) {
+            const key = token.replace(/~1/g, "/").replace(/~0/g, "~");
+            target = isJsonObject(target) ? target[key] : undefined;
+        }
+        return target;
+    }
+    /**
+     * rememberResponse calls this for elicitation/dynamicTool schemas; recursive branches pass marked
+     * values to remember. Collect marked values through bounded local schema traversal, including
+     * referenced and sibling rules; does not validate response values or fetch references. Visit
+     * references before siblings because registration order determines host-hook and budget failures.
+     * Stop beyond depth 32; registration failures propagate without undoing earlier registrations.
+     */
+    fromSchema(schema, value, { root, depth }) {
+        if (depth > 32 || typeof schema !== "object" || !schema || value === undefined)
+            return;
+        if (schema.writeOnly === true || schema.secret === true) {
+            this.remember(value);
+            return;
+        }
+        const children = { root, depth: depth + 1 };
+        if (typeof schema.$ref === "string" && schema.$ref.startsWith("#/") && typeof root === "object") {
+            const target = this.resolveLocalReference(schema.$ref, root);
+            if (isJsonSchema(target)) {
+                this.fromSchema(target, value, children);
+            }
+        }
+        if (isJsonObject(value))
+            this.rememberObjectProperties(schema, value, children);
+        if (Array.isArray(value))
+            this.rememberArrayItems(schema, value, children);
+        this.rememberComposedSchemas(schema, value, children);
+    }
+    /**
+     * fromSchema calls this between reference and array/composition visits. Register declared
+     * properties before additional ones, sharing the next-depth context and propagating registration
+     * failures. Even a declared non-schema property excludes that key from additionalProperties.
+     */
+    rememberObjectProperties(schema, value, context) {
+        const properties = schema.properties;
+        if (isJsonObject(properties)) {
+            for (const [key, child] of Object.entries(properties)) {
+                if (isJsonSchema(child))
+                    this.fromSchema(child, value[key], context);
+            }
+        }
+        if (isJsonObject(schema.additionalProperties)) {
+            for (const [key, child] of Object.entries(value)) {
+                if (!properties || typeof properties !== "object" || !Object.hasOwn(properties, key)) {
+                    this.fromSchema(schema.additionalProperties, child, context);
+                }
+            }
+        }
+    }
+    /**
+     * fromSchema visits array elements in order under the same items schema and next-depth context.
+     * Tuple arrays and absent items rules contribute no registrations. Registration failures propagate.
+     */
+    rememberArrayItems(schema, value, context) {
+        if (!schema.items || !isJsonSchema(schema.items))
+            return;
+        for (const child of value) {
+            this.fromSchema(schema.items, child, context);
+        }
+    }
+    /**
+     * fromSchema visits composition branches after reference, object and array rules. Visit every
+     * schema branch in keyword and array order without selecting a validation match. Registration
+     * failures stop the remaining visits.
+     */
+    rememberComposedSchemas(schema, value, context) {
+        for (const key of ["allOf", "anyOf", "oneOf"]) {
+            const branches = schema[key];
+            if (!Array.isArray(branches))
+                continue;
+            for (const branch of branches) {
+                if (isJsonSchema(branch))
+                    this.fromSchema(branch, value, context);
+            }
+        }
+    }
+    /**
+     * text consumes the complete scan; delta stores a stream scan's pending prefix for the next chunk.
+     * Return longest complete matches as redactions. Stream mode withholds an unmatched trailing
+     * prefix so it cannot leak before the next chunk arrives; complete mode emits that prefix.
+     * This scan reads registered secrets but changes no stream or registration state.
+     */
+    scan(value, mode) {
+        const secretsByDescendingLength = [...this.values].sort((a, b) => b.length - a.length);
+        const output = [];
+        for (let offset = 0; offset < value.length;) {
+            const candidates = secretsByDescendingLength.filter((secret) => secret[0] === value[offset]);
+            // Prefer the longest complete match, even if a longer secret is still incomplete.
+            const completeMatch = candidates.find((entry) => value.startsWith(entry, offset));
+            if (completeMatch) {
+                output.push("[redacted]");
+                offset += completeMatch.length;
+                continue;
+            }
+            if (mode === "stream" && candidates.length) {
+                const suffix = value.slice(offset);
+                if (candidates.some((entry) => entry.startsWith(suffix))) {
+                    return { text: output.join(""), pending: suffix };
+                }
+            }
+            output.push(value.charAt(offset));
+            offset++;
+        }
+        return { text: output.join(""), pending: "" };
+    }
+    /**
+     * capabilities calls this for config-option schemas before exposing state. Project schema
+     * annotations/defaults recursively while preserving constraints and property names; privacy must not
+     * silently change validation rules. Object schemas are copied and boolean schemas pass through.
+     */
+    schema(schema) {
+        if (typeof schema === "boolean")
+            return schema;
+        const output = { ...schema };
+        for (const key of ["title", "description", "default", "examples"])
+            if (output[key] !== undefined)
+                output[key] = this.json(output[key]);
+        for (const key of ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"]) {
+            const map = output[key];
+            if (isJsonObject(map))
+                output[key] = Object.fromEntries(Object.entries(map).map(([name, child]) => [name, isJsonSchema(child) ? this.schema(child) : child]));
+        }
+        for (const key of ["additionalProperties", "unevaluatedProperties", "propertyNames", "items", "contains", "additionalItems", "unevaluatedItems", "not", "if", "then", "else", "contentSchema"]) {
+            const child = output[key];
+            if (isJsonSchema(child))
+                output[key] = this.schema(child);
+        }
+        for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+            const children = output[key];
+            if (Array.isArray(children))
+                output[key] = children.map((child) => isJsonSchema(child) ? this.schema(child) : child);
+        }
+        return output;
+    }
+    /**
+     * item maps user-message content through this projection. Project content-bearing input block fields
+     * while preserving modality and protocol structure; return a detached outer block without loading
+     * files or fetching URLs. item returns the block in the public user message.
+     */
+    input(block) {
+        if (block.type === "text")
+            return { ...block, text: this.text(block.text) };
+        if (block.type === "file")
+            return { ...block, uri: this.text(block.uri), ...(block.name ? { name: this.text(block.name) } : {}) };
+        return { ...block, ...(block.url ? { url: this.text(block.url) } : {}), ...(block.data ? { data: this.text(block.data) } : {}) };
+    }
+    /**
+     * toolCall merges these fields into projected tool-call items before bounding file-change material.
+     * Project tool image paths/prompts only; image identity and other native metadata remain
+     * authoritative. Return only the image field (or no fields) without reading or modifying an image.
+     */
+    toolImage(item) {
+        return item.image ? {
+            image: {
+                ...item.image,
+                ...(item.image.path ? { path: this.text(item.image.path) } : {}),
+                ...(item.image.revisedPrompt ? { revisedPrompt: this.text(item.image.revisedPrompt) } : {}),
+            },
+        } : {};
+    }
+    /**
+     * toolCall maps fileChanges through this before boundFileChangeItem enforces retention.
+     * Project change paths and material text while preserving source metadata; the caller subsequently
+     * applies the shared retention budget. Return copied text material without applying patches or
+     * changing unavailable-material metadata.
+     */
+    fileChange(change) {
+        return {
+            ...change,
+            path: this.text(change.path),
+            ...(change.oldPath !== undefined ? { oldPath: this.text(change.oldPath) } : {}),
+            materials: change.materials.map((material) => {
+                if (material.format === "unified")
+                    return { ...material, patch: this.text(material.patch) };
+                if (material.format === "text")
+                    return {
+                        ...material,
+                        oldText: material.oldText === null ? null : this.text(material.oldText),
+                        newText: this.text(material.newText),
+                    };
+                return material;
+            }),
+        };
+    }
+    /**
+     * item delegates tool content projection here after extensions have been projected. Redact every
+     * content field before enforcing the shared file-change budget so accounting measures projected
+     * text. Return the bounded snapshot without changing native identity or source material.
+     */
+    toolCall(item) {
+        const redactedItem = {
+            ...item,
+            ...this.toolImage(item),
+            ...(item.fileChanges !== undefined ? { fileChanges: item.fileChanges.map((change) => this.fileChange(change)) } : {}),
+            title: this.text(item.title),
+            ...(item.input !== undefined ? { input: this.json(item.input) } : {}),
+            ...(item.output !== undefined ? { output: this.json(item.output) } : {}),
+            ...(item.raw !== undefined ? { raw: this.json(item.raw) } : {}),
+            ...(item.locations ? { locations: item.locations.map((location) => ({ ...location, path: this.text(location.path) })) } : {}),
+        };
+        return boundFileChangeItem(redactedItem);
+    }
+    /**
+     * itemDelta calls this for JSON-valued payloads before Session retains or publishes the event.
+     * A patch object with type or fileChanges must pass Item validation before item projection.
+     * Item-shaped validation failures throw ProtocolValidationError. Other values receive ordinary
+     * JSON projection.
+     */
+    deltaValue(kind, value) {
+        if (kind === "patch" && isJsonObject(value) && ("type" in value || "fileChanges" in value)) {
+            assertDefinition("Item", value);
+            return this.item(value);
+        }
+        return this.json(value);
+    }
+    /**
+     * event projects delta text before validating/projecting an optional JSON value. A malformed patch
+     * throws after any prefix update, as publication fails through Session.emit; no buffered state is
+     * rolled back. Non-Item JSON still receives ordinary content projection.
+     */
+    itemDelta(payload, turnId) {
+        const projected = { ...payload };
+        if (payload.text !== undefined) {
+            projected.text = this.delta(streamKey(payload.itemId, turnId), payload.text);
+        }
+        if (payload.value !== undefined) {
+            projected.value = this.deltaValue(payload.kind, payload.value);
+        }
+        return projected;
+    }
+}
+/**
+ * Schema collection, projection and local-reference resolution use this pure shape guard before
+ * reading named children. Arrays and null cannot supply schema property maps.
+ */
+function isJsonObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * fromSchema, rememberObjectProperties and schema use this pure guard for selected schema children.
+ * Accept boolean/object nodes without validating schema keywords or response values.
+ */
+function isJsonSchema(value) {
+    return typeof value === "boolean" || isJsonObject(value);
+}
+/** Share turn/item key encoding between delta buffering and completion cleanup; omission keeps the legacy item-only key. */
+function streamKey(itemId, turnId) {
+    return turnId === undefined ? itemId : JSON.stringify([turnId, itemId]);
+}

package/src/process.d.ts

@@ -0,0 +1,92 @@
+/** Child exit status observed independently of output EOF. */
+export type ProcessExit = {
+    /** Exit status, or null for signal termination or startup failure. */
+    code: number | null;
+    /** Terminating signal, or null for normal exit or startup failure. */
+    signal: string | null;
+    /** Native code, if supplied, when the exit observer receives a child error without a PID. */
+    errorCode?: string;
+};
+/** Configure a shell-free harness launch and choose who is responsible for terminating the child. */
+export interface HarnessProcessOptions {
+    /** Executable path or name. Empty strings and NUL bytes are rejected before launch. */
+    command: string;
+    /** Literal argument vector, empty by default. Entries containing NUL bytes are rejected before launch. */
+    args?: readonly string[];
+    /** Working directory for the child; omitted means the parent working directory. */
+    cwd?: string;
+    /** Complete environment for the child. Omit to inherit the parent environment. */
+    env?: Record<string, string | undefined>;
+    /** Defaults to true. Set to false when another owner will terminate the launched child. */
+    owned?: boolean;
+    /**
+     * Grace period before escalation for an owned child. Accepts integer milliseconds from 0 to
+     * 60,000 and defaults to 1000. Validated for either ownership mode.
+     */
+    shutdownTimeoutMs?: number;
+}
+/**
+ * Local I/O handles for one harness process. Drain output and await disposal even after exit.
+ * Custom process factories for the AHP, Codex, and Hermes adapters also supply this handle.
+ * The adapter receiving it takes responsibility for disposal.
+ */
+export interface HarnessProcess {
+    /** PID captured at launch and retained after exit. */
+    readonly pid: number;
+    /** True when this handle is responsible for terminating the process tree on disposal. */
+    readonly owned: boolean;
+    /** Child stdout bytes; callers should drain buffered output before disposal. */
+    readonly stdout: AsyncIterable<Uint8Array>;
+    /** Child stderr bytes; callers should drain buffered output before disposal. */
+    readonly stderr: AsyncIterable<Uint8Array>;
+    /**
+     * Resolves with status on child exit or an observed child error without a PID. Read the output
+     * streams through EOF to collect buffered bytes.
+     */
+    readonly exited: Promise<ProcessExit>;
+    /**
+     * Write once to stdin and resolve when its native write callback completes, without waiting for
+     * the peer to consume the bytes. Reject with PROCESS_WRITE_FAILED if the input is closed, exit
+     * has been observed, disposal has started, or the native write callback reports an error.
+     */
+    write(chunk: string | Uint8Array): Promise<void>;
+    /**
+     * End stdin after queued writes. Await writes first to observe each write's outcome. Resolve when
+     * the native end callback completes, or immediately if input is already ending or destroyed.
+     * A native close callback error rejects with PROCESS_WRITE_FAILED. Output and exit remain observable.
+     */
+    closeInput(): Promise<void>;
+    /**
+     * Release local stdin, stdout, and stderr even when termination fails. Drain buffered output first.
+     * For an owned child, terminate the tree, escalating as needed, then allow up to 1000 ms for any
+     * pending child exit observation. Termination failure or a missing exit observation rejects with
+     * PROCESS_DISPOSE_FAILED. For an external child, unref it and release the pipes without waiting for
+     * exit. Every call returns the same promise, including after rejection.
+     */
+    dispose(): Promise<void>;
+}
+/** Process failure category for adapters; native causes are reduced to a format-checked code. */
+export declare class ProcessPortError extends Error {
+    /**
+     * Construct a failure using caller-supplied safe message text, which is retained verbatim.
+     * Supply a native cause to retain only its format-checked error code.
+     */
+    constructor(code: ProcessPortError['code'], message: string, options?: ErrorOptions);
+    /** Stable category for adapter startup, input, or disposal failures. */
+    readonly code: 'HARNESS_UNAVAILABLE' | 'PROCESS_WRITE_FAILED' | 'PROCESS_DISPOSE_FAILED';
+    /**
+     * Native code of 1 to 64 characters, beginning with an uppercase letter and containing only
+     * uppercase letters, digits, and underscores.
+     */
+    readonly nativeCode?: string;
+}
+/**
+ * Launch a harness executable directly with piped I/O and literal arguments, without a shell.
+ * Resolve after the spawn event provides a process handle. The caller handles protocol readiness.
+ * Invalid inputs or launch failures reject with HARNESS_UNAVAILABLE. Failed startup releases any
+ * local pipes it acquired. Drain output and await disposal even after child exit.
+ *
+ * ACP's processStream awaits launch to wire the pipes into its channel, propagates launch
+ * rejection, and delegates channel disposal to the handle.
+ */
+export declare function spawnHarnessProcess(options: HarnessProcessOptions): Promise<HarnessProcess>;