@noetic-tools/types 3.2.1 → 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';
 /**
@@ -73,7 +73,7 @@ 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> = StepRunCode<TContext, I, O> | StepCallModel<TContext, I, O> | StepSubHarness<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>;
+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 StepRunCode<TContext = ContextData, I = unknown, O = unknown> {
     kind: 'runCode';
@@ -123,32 +123,46 @@ export interface StepCallModel<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);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "3.2.1",
+  "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/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>;
-}

package/dist/types/sub-harness.js

@@ -1,106 +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';
-//#region Step-kind discriminator
-/**
- * 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 const SubHarnessKind = {
-    ClaudeCode: 'claude-code',
-    Codex: 'codex',
-    Opencode: 'opencode',
-    Pi: 'pi',
-};
-/** @public Ordered list of every harness kind — the single source of truth consumed by the JSON schema and the interpreter. */
-export const SUB_HARNESS_KINDS = [
-    SubHarnessKind.ClaudeCode,
-    SubHarnessKind.Codex,
-    SubHarnessKind.Opencode,
-    SubHarnessKind.Pi,
-];
-const HarnessFinishReasonSchema = z.enum([
-    'stop',
-    'length',
-    'aborted',
-    'error',
-    'tool-calls',
-]);
-const TokenUsageSchema = z.object({
-    input: z.number(),
-    output: z.number(),
-    total: z.number().optional(),
-    cached: z.number().optional(),
-});
-/**
- * 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 const SubHarnessStreamPartSchema = z.discriminatedUnion('type', [
-    z.object({
-        type: z.literal('stream-start'),
-    }),
-    z.object({
-        type: z.literal('text-delta'),
-        delta: z.string(),
-    }),
-    z.object({
-        type: z.literal('reasoning-delta'),
-        delta: z.string(),
-    }),
-    z.object({
-        type: z.literal('tool-call'),
-        toolCallId: z.string(),
-        toolName: z.string(),
-        input: z.unknown(),
-        /** True when the underlying agent executed the tool itself (vs. host dispatch). */
-        providerExecuted: z.boolean().optional(),
-    }),
-    z.object({
-        type: z.literal('tool-result'),
-        toolCallId: z.string(),
-        toolName: z.string(),
-        output: z.unknown(),
-        isError: z.boolean().optional(),
-    }),
-    z.object({
-        type: z.literal('file-change'),
-        path: z.string().optional(),
-        summary: z.string().optional(),
-    }),
-    z.object({
-        type: z.literal('finish'),
-        finishReason: HarnessFinishReasonSchema,
-        usage: TokenUsageSchema.optional(),
-        cost: z.number().optional(),
-    }),
-    z.object({
-        type: z.literal('error'),
-        error: z.string(),
-    }),
-    /** Adapter-specific passthrough for events with no canonical mapping. */
-    z.object({
-        type: z.literal('raw'),
-        value: z.unknown(),
-    }),
-]);
-//#endregion