@noetic-tools/types 3.2.0 → 3.2.2

package/dist/types/step.d.ts

@@ -1,11 +1,11 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { AcpAgent, AcpClientCapabilityConfig, AcpContentBlock, AcpMcpServer, AcpPermissionHandler, AcpPermissionPolicy, AcpSessionPolicy } from './acp.js';
 import type { Channel } from './channel.js';
 import type { ModelParams, RetryPolicy, ServerToolSpec, StepMeta } from './common.js';
 import type { Context } from './context.js';
 import type { ContextConfig, ContextData, ContextLayer, ProjectionPolicy } from './context-layer.js';
 import type { NoeticError } from './error.js';
 import type { OutputCodec } from './output-codec.js';
-import type { SubHarness, SubHarnessKind, SubHarnessSessionPolicy, SubHarnessSettings } from './sub-harness.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
 import type { Tool } from './tool.js';
 /**
@@ -52,13 +52,14 @@ export interface Verdict {
 export type Until = (snapshot: Snapshot) => Verdict | Promise<Verdict>;
 /**
  * Field type that accepts either an eager value or a `(ctx) => value` getter.
- * Used by `step.llm` for params that may vary per execution (model, instructions,
- * tool list). The getter runs at step execution time with the live context.
+ * Used by `step.callModel` for params that may vary per execution (model,
+ * instructions, tool list). The getter runs at step execution time with the
+ * live context.
  * @public
  */
 export type Lazy<T, TContext = ContextData> = T | ((ctx: Context<TContext>) => T | Promise<T>);
 /**
- * Outcome of a single path in a `settle`-mode fork (mirrors `Promise.allSettled`).
+ * Outcome of a single path in a `settle`-mode inParallel step (mirrors `Promise.allSettled`).
  * @public
  */
 export interface SettleResult<O> {
@@ -72,10 +73,10 @@ export interface SettleResult<O> {
     error?: NoeticError;
 }
 /** @public Discriminated union of all step kinds that can be composed into an execution tree. */
-export type Step<TContext = ContextData, I = unknown, O = unknown> = StepRun<TContext, I, O> | StepLLM<TContext, I, O> | StepSubHarness<TContext, I, O> | StepTool<TContext, I, O> | StepBranch<TContext, I, O> | StepFork<TContext, I, O> | StepSpawn<TContext, I, O> | StepProvide<TContext, I, O> | StepLoop<TContext, I, O> | StepEvery<TContext, I, O>;
+export type Step<TContext = ContextData, I = unknown, O = unknown> = StepRunCode<TContext, I, O> | StepCallModel<TContext, I, O> | StepAcpAgent<TContext, I, O> | StepInvokeTool<TContext, I, O> | StepConditional<TContext, I, O> | StepInParallel<TContext, I, O> | StepSpawn<TContext, I, O> | StepWithContext<TContext, I, O> | StepLoop<TContext, I, O> | StepSchedule<TContext, I, O>;
 /** @public A step that executes arbitrary async logic via a user-supplied function. */
-export interface StepRun<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'run';
+export interface StepRunCode<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'runCode';
     id: string;
     execute: (input: I, ctx: Context<TContext>) => Promise<O>;
     retry?: RetryPolicy;
@@ -88,8 +89,8 @@ export interface StepRun<TContext = ContextData, I = unknown, O = unknown> {
     subprocess?: SubprocessAdapter;
 }
 /** @public A step that sends a prompt to a language model and returns its response. */
-export interface StepLLM<TContext = ContextData, _I = unknown, O = unknown> {
-    kind: 'llm';
+export interface StepCallModel<TContext = ContextData, _I = unknown, O = unknown> {
+    kind: 'callModel';
     id: string;
     /** Model id. Accepts either an eager string or a `(ctx) => string` getter. */
     model: Lazy<string, TContext>;
@@ -122,63 +123,77 @@ export interface StepLLM<TContext = ContextData, _I = unknown, O = unknown> {
     projection?: ProjectionPolicy;
 }
 /**
- * A step that delegates a turn to an external coding-agent harness
- * (Claude Code, Codex, opencode, pi). Each harness kind is a distinct
- * `Step.kind`, but every variant shares this shape and is executed by one
- * interpreter handler.
+ * A step that delegates a turn to an external coding agent over the Agent
+ * Client Protocol. One step kind serves every ACP-speaking agent — the agent
+ * itself is supplied as an adapter, so the set of supported agents is open.
  * @public
  */
-export interface StepSubHarness<TContext = ContextData, _I = unknown, O = unknown> {
-    /** The harness kind, equal to the backing adapter's `harnessId`. */
-    kind: SubHarnessKind;
+export interface StepAcpAgent<TContext = ContextData, _I = unknown, O = unknown> {
+    kind: 'acp-agent';
     id: string;
     /**
-     * The harness adapter that runs the turn. Eager or `(ctx) => SubHarness`.
+     * The ACP agent adapter that runs the turn. Eager or `(ctx) => AcpAgent`.
      * Programmatic builders take it inline; the JSON hydrator resolves it from
-     * the workflow's harness registry and inlines it here.
+     * the workflow's agent registry and inlines it here.
      */
-    harness: Lazy<SubHarness, TContext>;
-    /** Turn prompt. Eager string or `(ctx) => string` getter. */
-    prompt: Lazy<string, TContext>;
-    /** Shared harness settings (model, permission mode, …). */
-    settings?: SubHarnessSettings;
-    /** System instructions applied on the first message of a fresh session. */
-    instructions?: Lazy<string | undefined, TContext>;
+    agent: Lazy<AcpAgent, TContext>;
+    /** Turn prompt as plain text. Eager string or `(ctx) => string` getter. */
+    prompt?: Lazy<string, TContext>;
+    /**
+     * Full ACP prompt content — images, audio, resource links, embedded context.
+     * Appended after `prompt` when both are given. Validated against the agent's
+     * advertised `promptCapabilities` before the turn is sent.
+     */
+    content?: Lazy<ReadonlyArray<AcpContentBlock> | undefined, TContext>;
+    /** MCP servers to expose to the agent for this session. */
+    mcpServers?: Lazy<ReadonlyArray<AcpMcpServer> | undefined, TContext>;
+    /** Working directory for the session. Defaults to `ctx.cwdState.cwd`. */
+    cwd?: Lazy<string | undefined, TContext>;
+    /** Session mode to switch to before prompting (e.g. `'plan'`). */
+    mode?: Lazy<string | undefined, TContext>;
+    /** Model to select before prompting, for agents that expose model selection. */
+    model?: Lazy<string | undefined, TContext>;
+    /** Declarative answer to the agent's permission requests. */
+    permissions?: AcpPermissionPolicy;
+    /** Async resolver consulted when policy and steering both abstain. */
+    onPermissionRequest?: AcpPermissionHandler;
+    /** Which client capabilities to advertise to the agent. */
+    clientCapabilities?: AcpClientCapabilityConfig;
     /** When set, the assistant text is JSON-parsed and validated against this Standard Schema. */
     output?: StandardSchemaV1<unknown, O>;
     /** Session reuse + teardown policy across steps. */
-    session?: SubHarnessSessionPolicy;
+    session?: AcpSessionPolicy;
     /** Controls framework event emission for this step. Defaults to `true`. */
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
 }
-/** @public A step that invokes a single tool directly, bypassing the LLM. */
-export interface StepTool<_TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'tool';
+/** @public A step that invokes a single tool directly, bypassing the model. */
+export interface StepInvokeTool<_TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'invokeTool';
     id: string;
     tool: Tool<StandardSchemaV1<unknown, I>, StandardSchemaV1<unknown, O>>;
     args?: Partial<I>;
 }
 /** @public A step that dynamically selects and executes one of several possible sub-steps. */
-export interface StepBranch<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'branch';
+export interface StepConditional<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'conditional';
     id: string;
     route: (input: I, ctx: Context<TContext>) => Step<TContext, I, O> | null | Promise<Step<TContext, I, O> | null>;
     _optimizable?: Step<TContext>[];
 }
-/** @public Union of fork step variants (`race`, `all`, `settle`) for concurrent path execution. */
-export type StepFork<TContext = ContextData, I = unknown, O = unknown> = StepForkRace<TContext, I, O> | StepForkAll<TContext, I, O> | StepForkSettle<TContext, I, O>;
-/** @public A fork step that returns the result of the first path to complete. */
-export interface StepForkRace<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'fork';
+/** @public Union of inParallel step variants (`race`, `all`, `settle`) for concurrent path execution. */
+export type StepInParallel<TContext = ContextData, I = unknown, O = unknown> = StepInParallelRace<TContext, I, O> | StepInParallelAll<TContext, I, O> | StepInParallelSettle<TContext, I, O>;
+/** @public An inParallel step that returns the result of the first path to complete. */
+export interface StepInParallelRace<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'inParallel';
     id: string;
     mode: 'race';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
     concurrency?: number;
     _optimizable?: Step<TContext>[];
 }
-/** @public A fork step that runs all paths and merges their results. */
-export interface StepForkAll<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'fork';
+/** @public An inParallel step that runs all paths and merges their results. */
+export interface StepInParallelAll<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'inParallel';
     id: string;
     mode: 'all';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
@@ -186,9 +201,9 @@ export interface StepForkAll<TContext = ContextData, I = unknown, O = unknown> {
     concurrency?: number;
     _optimizable?: Step<TContext>[];
 }
-/** @public A fork step that runs all paths and collects fulfilled/rejected outcomes. */
-export interface StepForkSettle<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'fork';
+/** @public An inParallel step that runs all paths and collects fulfilled/rejected outcomes. */
+export interface StepInParallelSettle<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'inParallel';
     id: string;
     mode: 'settle';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
@@ -202,8 +217,8 @@ export interface StepForkSettle<TContext = ContextData, I = unknown, O = unknown
  * Spawn and detachedSpawn break the inheritance chain.
  * @public
  */
-export interface StepProvide<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'provide';
+export interface StepWithContext<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'withContext';
     id: string;
     child: Step<TContext, I, O>;
     context: ContextConfig | ContextLayer[];
@@ -248,33 +263,33 @@ export interface StepLoop<TContext = ContextData, I = unknown, O = unknown> {
     onError?: (error: NoeticError, ctx: Context<TContext>) => 'retry' | 'skip' | 'abort';
 }
 /**
- * Error policy for the `every` operator when its body step throws.
+ * Error policy for the `schedule` operator when its body step throws.
  * - `'continue'` (default): emit a span event recording the error and continue parking.
  * - `'fail'`: re-throw, terminating the operator.
  * @public
  */
-export type EveryErrorPolicy = 'continue' | 'fail';
+export type ScheduleErrorPolicy = 'continue' | 'fail';
 /**
  * A step that runs a body step on a fixed-interval schedule, optionally woken
- * sooner by a wake channel. Runs forever until the executing context is cancelled.
+ * sooner by an inbox channel. Runs forever until the executing context is cancelled.
  *
- * The operator output is `void` — `every` does not accumulate iteration outputs.
+ * The operator output is `void` — `schedule` does not accumulate iteration outputs.
  * The `O` type parameter exists only to anchor the body step's output type.
  *
  * @public
  */
-export interface StepEvery<TContext = ContextData, I = unknown, O = unknown> {
-    kind: 'every';
+export interface StepSchedule<TContext = ContextData, I = unknown, O = unknown> {
+    kind: 'schedule';
     /** Unique step identifier used in traces and error messages. */
     id: string;
     /** Body step executed on each iteration. */
     step: Step<TContext, I, O>;
     /** Park duration between iterations in milliseconds. Must be >= 0. */
-    ms: number;
+    interval: number;
     /** Optional channel that wakes the parking interval when any value arrives. */
-    wakeOn?: Channel<unknown>;
+    inbox?: Channel<unknown>;
     /** Behavior when `step` throws. Defaults to `'continue'`. */
-    onError?: EveryErrorPolicy;
+    onError?: ScheduleErrorPolicy;
     /** Random jitter applied to the park duration in milliseconds. Must be >= 0. Default 0. */
     jitter?: number;
 }

package/dist/types/tool-context.d.ts

@@ -25,13 +25,6 @@ export interface ToolExecutionContext {
     readonly shell: ShellAdapter;
     /** Per-layer state accessor for reading/writing tool-specific state. */
     readonly context: ToolContext;
-    /**
-     * @deprecated Renamed to `context`. Returns the same accessor.
-     *
-     * Required for the same reason as `Context.memory` — pre-rename code calls
-     * `toolCtx.memory.get(...)` directly.
-     */
-    readonly memory: ToolContext;
     /** The fully assembled conversation view at the point of tool invocation. */
     readonly assembledView: ReadonlyArray<Item>;
     /** Metadata from the most recent step execution (token usage, tool calls, etc.). */

package/dist/util/message-helpers.js

@@ -98,7 +98,14 @@ export function trackUsage(ctx, response) {
     ctx.tokens.input += response.usage.inputTokens;
     ctx.tokens.output += response.usage.outputTokens;
     ctx.tokens.total += response.usage.inputTokens + response.usage.outputTokens;
-    ctx.tokens.cached = (ctx.tokens.cached ?? 0) + (response.usage.cachedTokens ?? 0);
+    // Only write `cached` when the response actually carried a figure. Defaulting
+    // a missing report to 0 would erase the `RoundUsage` invariant that
+    // `undefined` means "this provider says nothing about caching" — callers that
+    // steer on cache behaviour could no longer tell that from "nothing was
+    // cached". Mirrors the child→parent merge in execute-action.
+    if (response.usage.cachedTokens !== undefined) {
+        ctx.tokens.cached = (ctx.tokens.cached ?? 0) + response.usage.cachedTokens;
+    }
     if (response.cost) {
         ctx.cost = ctx.cost + response.cost;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",
@@ -56,6 +56,7 @@
   "dependencies": {
     "@openrouter/agent": "^0.6.0",
     "@standard-schema/spec": "1.1.0",
+    "@zed-industries/agent-client-protocol": "^0.4.5",
     "zod": "^4.0.0"
   },
   "scripts": {

package/dist/deprecated.d.ts

@@ -1,39 +0,0 @@
-/**
- * Deprecated aliases from the "memory layer" era of the framework.
- *
- * The layer system assembles the model's *context window* — recall, budget
- * allocation, history projection, the item-append pipeline — so it is named
- * after context, not memory. Every name below still resolves to its
- * replacement; nothing here changes behaviour.
- *
- * These are scheduled for removal in the next major of `@noetic-tools/types`.
- */
-import type { ContextConfig, ContextData, ContextLayer, ContextLayerHooks, InferContext, InferContextShape } from './types/context-layer.js';
-import type { ContextScope, LayerCallModelRequest } from './types/context-scope.js';
-import type { LayerTraceSpan } from './types/observability.js';
-import type { ToolContextDeclaration } from './types/tool.js';
-import type { ToolContext } from './types/tool-context.js';
-/** @public @deprecated Renamed to {@link ContextLayer}. */
-export type MemoryLayer<TState = unknown> = ContextLayer<TState>;
-/** @public @deprecated Renamed to {@link ContextLayerHooks}. */
-export type MemoryHooks<TState = unknown> = ContextLayerHooks<TState>;
-/** @public @deprecated Renamed to {@link ContextConfig}. */
-export type MemoryConfig<TLayers extends readonly ContextLayer[] = readonly ContextLayer[]> = ContextConfig<TLayers>;
-/** @public @deprecated Renamed to {@link ContextData}. */
-export type ContextMemory = ContextData;
-/** @public @deprecated Renamed to {@link InferContext}. */
-export type InferMemory<T extends {
-    readonly _shape: unknown;
-}> = InferContext<T>;
-/** @public @deprecated Renamed to {@link InferContextShape}. */
-export type InferMemoryShape<T extends readonly ContextLayer[]> = InferContextShape<T>;
-/** @public @deprecated Renamed to {@link ContextScope}. */
-export type MemoryScope = ContextScope;
-/** @public @deprecated Renamed to {@link LayerCallModelRequest}. */
-export type MemoryCallModelRequest = LayerCallModelRequest;
-/** @public @deprecated Renamed to {@link LayerTraceSpan}. */
-export type MemoryTraceSpan = LayerTraceSpan;
-/** @public @deprecated Renamed to {@link ToolContext}. */
-export type ToolMemory = ToolContext;
-/** @public @deprecated Renamed to {@link ToolContextDeclaration}. */
-export type ToolMemoryDeclaration<TState = unknown> = ToolContextDeclaration<TState>;

package/dist/types/sub-harness.d.ts

@@ -1,273 +0,0 @@
-/**
- * Coding-agent harness contract.
- *
- * A "harness" here is a pluggable backend that drives an external agentic
- * coding tool — Claude Code, Codex, opencode, pi — as a Noetic step. It is the
- * direct analogue of the `ContextLayer` contract: defined in the dependency-free
- * `@noetic-tools/types` foundation so both `@noetic-tools/core` (which executes
- * harness steps) and the per-tool `@noetic-tools/sub-harness-*` packages (which
- * implement them) can depend on it without forming a cycle.
- *
- * Modelled on Vercel's `HarnessV1` spec: a tagged spec version, a small set of
- * descriptive fields, and a single `doStart` entry point that yields a session.
- * Optional capabilities are signalled by the presence of optional methods, not
- * a static capabilities object — an adapter that cannot satisfy a request
- * throws {@link SubHarnessCapabilityError} from the relevant method.
- */
-import { z } from 'zod';
-import type { TokenUsage } from './common.js';
-import type { FsAdapter } from './fs-adapter.js';
-import type { Item } from './items.js';
-import type { ShellAdapter } from './shell-adapter.js';
-import type { SubprocessAdapter } from './subprocess-adapter.js';
-/**
- * The set of harness step kinds. Each value is a distinct `Step.kind`, so a
- * `step.claudeCode(...)` and a `step.codex(...)` are separate, individually
- * typed step variants — while the interpreter routes all of them through a
- * single shared `executeSubHarness` handler.
- * @public
- */
-export declare const SubHarnessKind: {
-    readonly ClaudeCode: 'claude-code';
-    readonly Codex: 'codex';
-    readonly Opencode: 'opencode';
-    readonly Pi: 'pi';
-};
-/** @public Union of all harness step kinds. */
-export type SubHarnessKind = (typeof SubHarnessKind)[keyof typeof SubHarnessKind];
-/** @public Ordered list of every harness kind — the single source of truth consumed by the JSON schema and the interpreter. */
-export declare const SUB_HARNESS_KINDS: ReadonlyArray<SubHarnessKind>;
-/**
- * Settings shared by every harness step. Tool-specific knobs that don't map to
- * a shared concept go through `extra`, which each adapter interprets (and may
- * reject with {@link SubHarnessCapabilityError}).
- * @public
- */
-export interface SubHarnessSettings {
-    /** Model identifier for the underlying agent (e.g. `claude-opus-4-8`). */
-    model?: string;
-    /** Permission posture for tool/file mutations the agent attempts. */
-    permissionMode?: 'default' | 'plan' | 'acceptEdits' | 'bypassPermissions';
-    /** Hard cap on internal agent turns before it must yield. */
-    maxTurns?: number;
-    /** Restrict the agent to this set of built-in tool names. */
-    allowedTools?: ReadonlyArray<string>;
-    /** Tool-specific passthrough options interpreted by the adapter. */
-    extra?: Record<string, unknown>;
-}
-/**
- * Controls how a harness session is reused and torn down across steps.
- * @public
- */
-export interface SubHarnessSessionPolicy {
-    /**
-     * Reuse a live session keyed by this id across multiple harness steps. When
-     * omitted, each step gets a fresh session that is stopped on completion.
-     */
-    reuse?: string;
-    /**
-     * Lifecycle action when the step completes. `'stop'` (default) persists state
-     * and stops the runtime; `'detach'` parks it for later resume; `'destroy'`
-     * discards it with no resume state.
-     */
-    onComplete?: 'stop' | 'detach' | 'destroy';
-}
-/** @public Why an agentic turn ended. */
-export type SubHarnessFinishReason = 'stop' | 'length' | 'aborted' | 'error' | 'tool-calls';
-/**
- * Runtime validation schema for {@link SubHarnessStreamPart}. Adapters that move
- * events across a process or transport boundary (e.g. a sandbox bridge)
- * validate with this before forwarding.
- * @public
- */
-export declare const SubHarnessStreamPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    type: z.ZodLiteral<"stream-start">;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"text-delta">;
-    delta: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"reasoning-delta">;
-    delta: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"tool-call">;
-    toolCallId: z.ZodString;
-    toolName: z.ZodString;
-    input: z.ZodUnknown;
-    providerExecuted: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"tool-result">;
-    toolCallId: z.ZodString;
-    toolName: z.ZodString;
-    output: z.ZodUnknown;
-    isError: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"file-change">;
-    path: z.ZodOptional<z.ZodString>;
-    summary: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"finish">;
-    finishReason: z.ZodEnum<{
-        aborted: "aborted";
-        error: "error";
-        length: "length";
-        stop: "stop";
-        "tool-calls": "tool-calls";
-    }>;
-    usage: z.ZodOptional<z.ZodObject<{
-        input: z.ZodNumber;
-        output: z.ZodNumber;
-        total: z.ZodOptional<z.ZodNumber>;
-        cached: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>>;
-    cost: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"error">;
-    error: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"raw">;
-    value: z.ZodUnknown;
-}, z.core.$strip>], "type">;
-/**
- * A single event emitted by a harness during a turn. Mirrors the model-stream
- * primitives so the interpreter can forward them as framework events with
- * minimal translation. Adapter-specific metadata rides on `raw`.
- * @public
- */
-export type SubHarnessStreamPart = z.infer<typeof SubHarnessStreamPartSchema>;
-/**
- * The workspace surface a harness session may touch during a turn. A focused
- * subset of {@link Context} so adapters don't depend on the full runtime type.
- * @public
- */
-export interface SubHarnessRunContext {
-    /** Working directory the agent runs in (resolved from `ctx.cwdState.cwd`). */
-    readonly cwd: string;
-    readonly fs: FsAdapter;
-    readonly shell: ShellAdapter;
-    readonly subprocess: SubprocessAdapter;
-    /** Conversation thread id, for adapters that persist per-thread session state. */
-    readonly threadId: string;
-    /** Abort signal for the surrounding execution. */
-    readonly signal?: AbortSignal;
-}
-/** @public Opaque, adapter-defined state for resuming a stopped/detached session. */
-export interface SubHarnessResumeState {
-    readonly harnessId: string;
-    readonly sessionId: string;
-    readonly state: unknown;
-}
-/** @public Opaque, adapter-defined state for continuing a turn frozen mid-flight. */
-export interface SubHarnessContinueState {
-    readonly harnessId: string;
-    readonly sessionId: string;
-    readonly state: unknown;
-}
-/** @public Options handed to {@link SubHarness.doStart}. */
-export interface SubHarnessStartOptions<TSettings = SubHarnessSettings> {
-    /** Per-step settings (model, permission mode, …). */
-    settings?: TSettings;
-    /**
-     * System instructions applied once on the first message of a fresh session.
-     * Never re-applied on resume.
-     */
-    instructions?: string;
-    /**
-     * Prior conversation history (from earlier LLM/sub-harness steps and turns)
-     * used to seed a fresh session so the agent has full context of the
-     * conversation so far. Empty for the very first step of a run.
-     */
-    history?: ReadonlyArray<Item>;
-    /** The workspace surface for this run. */
-    ctx: SubHarnessRunContext;
-    /** Resume a previously stopped/detached session. */
-    resumeFrom?: SubHarnessResumeState;
-    /** Continue a turn previously frozen via {@link SubHarnessSession.doSuspendTurn}. */
-    continueFrom?: SubHarnessContinueState;
-    signal?: AbortSignal;
-}
-/** @public Options for a single agentic turn. */
-export interface SubHarnessPromptTurnOptions {
-    /** Fresh turn input only — the session owns conversation history. */
-    prompt: string;
-    /** Sink for stream events produced during the turn. */
-    emit: (part: SubHarnessStreamPart) => void;
-    signal?: AbortSignal;
-}
-/** @public Options for continuing a turn frozen mid-flight. */
-export interface SubHarnessContinueTurnOptions {
-    emit: (part: SubHarnessStreamPart) => void;
-    signal?: AbortSignal;
-}
-/**
- * Result of a completed agentic turn. The interpreter appends `items` to the
- * item log, charges `usage`/`cost`, and returns `text` (or parses it through
- * the step's output schema).
- * @public
- */
-export interface SubHarnessTurnResult {
-    /** Noetic Items produced this turn (assistant message, tool calls/results). */
-    items: Item[];
-    /** Final assistant text of the turn. */
-    text: string;
-    usage?: TokenUsage;
-    cost?: number;
-    finishReason?: SubHarnessFinishReason;
-    /** Adapter-specific metadata (peer to provider metadata, not a subtype). */
-    harnessMetadata?: Record<string, unknown>;
-}
-/**
- * Describes a tool the underlying agent executes natively, mapped to a shared
- * `commonName` so consumers can recognise "the same kind of tool" across
- * harnesses (Claude's `Bash`, Codex's `shell`, pi's `bash` → `shell`).
- * @public
- */
-export interface SubHarnessBuiltinTool {
-    /** The agent's native tool name. */
-    readonly nativeName: string;
-    /** Shared cross-harness name, when one exists. */
-    readonly commonName?: string;
-    readonly description?: string;
-}
-/**
- * A live harness session: one workspace + one conversation history + one
- * running runtime, kept across turns by the interpreter.
- * @public
- */
-export interface SubHarnessSession {
-    readonly sessionId: string;
-    /** True when this session was resumed rather than freshly started. */
-    readonly isResume: boolean;
-    /** The model the session resolved to, when the runtime reports it. */
-    readonly modelId?: string;
-    /** Run one agentic turn to completion. */
-    doPromptTurn(opts: SubHarnessPromptTurnOptions): Promise<SubHarnessTurnResult>;
-    /** Continue a turn previously frozen via {@link doSuspendTurn}. */
-    doContinueTurn?(opts: SubHarnessContinueTurnOptions): Promise<SubHarnessTurnResult>;
-    /** Freeze the current turn at a precise event cursor; runtime stays alive. */
-    doSuspendTurn?(): Promise<SubHarnessContinueState>;
-    /** Manually compact conversation history. Throws {@link SubHarnessCapabilityError} if unsupported. */
-    doCompact?(customInstructions?: string): Promise<void>;
-    /** Park the session between turns; runtime stays alive. */
-    doDetach?(): Promise<SubHarnessResumeState>;
-    /** Persist state and stop the runtime. */
-    doStop(): Promise<SubHarnessResumeState>;
-    /** Stop the runtime with no resume state. */
-    doDestroy?(): Promise<void>;
-}
-/**
- * A coding-agent harness. Each `@noetic-tools/sub-harness-*` package exports a
- * factory returning one of these (e.g. `claudeCode({ model })`).
- * @public
- */
-export interface SubHarness<TSettings = SubHarnessSettings> {
-    /** Spec tag for forward-compatibility. */
-    readonly specificationVersion: 'harness-v1';
-    /** Stable identifier, equal to the step kind it backs (e.g. `claude-code`). */
-    readonly harnessId: SubHarnessKind;
-    /** Tools the underlying agent executes natively. */
-    readonly builtinTools?: ReadonlyArray<SubHarnessBuiltinTool>;
-    /** Validates `resumeFrom`/`continueFrom` payloads, when the adapter persists them. */
-    readonly lifecycleStateSchema?: z.ZodType;
-    /** Start (or resume/continue) a session. */
-    doStart(opts: SubHarnessStartOptions<TSettings>): Promise<SubHarnessSession>;
-}