@noetic-tools/types 0.2.0 → 1.0.1

package/README.md

@@ -14,6 +14,10 @@ both of which re-export the parts relevant to their public surface. Application
 code normally imports these types from `@noetic-tools/core` rather than from
 this package directly.
 
+The `MemoryLayer` contract is additionally exported at the
+`@noetic-tools/types/contract` subpath for memory-layer authors who want the
+contract without the rest of the vocabulary.
+
 ## License
 
 Apache-2.0

package/dist/errors/noetic-error.d.ts

@@ -11,8 +11,16 @@ export declare class NoeticErrorImpl extends Error {
 /**
  * Type guard for `NoeticErrorImpl`.
  *
+ * Uses an `instanceof` fast path, then falls back to a structural check
+ * (`Error` carrying a `noeticError.kind: string`). The fallback keeps the
+ * guard reliable when multiple copies of `@noetic-tools/types` are loaded
+ * (e.g. mixed `src`/`dist` resolution or duplicated node_modules), where
+ * `instanceof` fails across realms. The inner `kind` is deliberately not
+ * validated against the closed `NoeticError` union so errors minted by a
+ * newer copy of the package still pass (forward compatibility).
+ *
  * @public
  * @param e - Value to check.
- * @returns `true` if `e` is a `NoeticErrorImpl`.
+ * @returns `true` if `e` is a `NoeticErrorImpl` (or structurally equivalent).
  */
 export declare function isNoeticError(e: unknown): e is NoeticErrorImpl;

package/dist/errors/noetic-error.js

@@ -14,12 +14,30 @@ export class NoeticErrorImpl extends Error {
 /**
  * Type guard for `NoeticErrorImpl`.
  *
+ * Uses an `instanceof` fast path, then falls back to a structural check
+ * (`Error` carrying a `noeticError.kind: string`). The fallback keeps the
+ * guard reliable when multiple copies of `@noetic-tools/types` are loaded
+ * (e.g. mixed `src`/`dist` resolution or duplicated node_modules), where
+ * `instanceof` fails across realms. The inner `kind` is deliberately not
+ * validated against the closed `NoeticError` union so errors minted by a
+ * newer copy of the package still pass (forward compatibility).
+ *
  * @public
  * @param e - Value to check.
- * @returns `true` if `e` is a `NoeticErrorImpl`.
+ * @returns `true` if `e` is a `NoeticErrorImpl` (or structurally equivalent).
  */
 export function isNoeticError(e) {
-    return e instanceof NoeticErrorImpl;
+    if (e instanceof NoeticErrorImpl) {
+        return true;
+    }
+    if (!(e instanceof Error)) {
+        return false;
+    }
+    if (!('noeticError' in e)) {
+        return false;
+    }
+    const inner = e.noeticError;
+    return (typeof inner === 'object' && inner !== null && 'kind' in inner && typeof inner.kind === 'string');
 }
 function formatMessage(error) {
     switch (error.kind) {
@@ -43,6 +61,10 @@ function formatMessage(error) {
             return `Budget exceeded: ${error.field} limit ${error.limit}, actual ${error.actual}`;
         case 'steering_denied':
             return `Steering denied${error.guidance ? `: ${error.guidance}` : ''}`;
+        case 'item_schema_mismatch':
+            return error.itemType
+                ? `Item type '${error.itemType}' did not match any registered item extension schema.`
+                : `Item did not match any registered ${error.category} extension schema.`;
         case 'handle_evicted':
             return `Subprocess handle '${error.handleId}' evicted (step '${error.stepId}'): adapter returned null for ${error.gracePeriodMs}ms`;
         default: {

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export * from './types/runtime.js';
 export * from './types/shell-adapter.js';
 export * from './types/steering.js';
 export * from './types/step.js';
+export * from './types/sub-harness.js';
 export * from './types/subprocess-adapter.js';
 export * from './types/tool.js';
 export * from './types/tool-context.js';

package/dist/index.js

@@ -22,6 +22,7 @@ export * from './types/runtime.js';
 export * from './types/shell-adapter.js';
 export * from './types/steering.js';
 export * from './types/step.js';
+export * from './types/sub-harness.js';
 export * from './types/subprocess-adapter.js';
 export * from './types/tool.js';
 export * from './types/tool-context.js';

package/dist/schemas/item.d.ts

@@ -11,6 +11,11 @@
  * Use this at trust boundaries (loading persisted session files, accepting
  * externally-supplied transcripts) where we need to reject garbage JSON but
  * don't need to re-validate every provider field TypeScript already types.
+ *
+ * Extension schemas registered on the registry are **gates, not
+ * normalizers**: they validate item shape and the ORIGINAL value is returned
+ * on match. Zod transforms, defaults, and key-stripping in extension schemas
+ * are unsupported — their output is discarded. Declare pure shape validators.
  */
 import { z } from 'zod';
 import type { Item, ItemSchemaExtensions } from '../types/items.js';
@@ -18,7 +23,14 @@ import type { Item, ItemSchemaExtensions } from '../types/items.js';
 export declare const ItemSchema: z.ZodCustom<Item, Item>;
 type ItemSchemaCategory = keyof Required<ItemSchemaExtensions>;
 export declare function mergeExtensions(a: ItemSchemaExtensions | undefined, b: ItemSchemaExtensions | undefined): ItemSchemaExtensions;
-/** @public Runtime item validator with optional tool, memory-layer, and harness extension schemas. */
+/**
+ * @public Runtime item validator with optional tool, memory-layer, and harness extension schemas.
+ *
+ * Extension schemas are pure shape validators (gate, not normalizer): on
+ * match the original value is returned unchanged, including fields the schema
+ * does not declare. Transforms and defaults in extension schemas are
+ * unsupported — their parsed output is never used.
+ */
 export declare class ItemSchemaRegistry {
     readonly extensions: ItemSchemaExtensions;
     readonly strictUnknownExtensions: boolean;
@@ -28,6 +40,13 @@ export declare class ItemSchemaRegistry {
     extend(extensions?: ItemSchemaExtensions): ItemSchemaRegistry;
     parse(value: unknown): Item;
     parseMany(values: Iterable<unknown>): Item[];
+    /**
+     * Validate `value` against the schemas registered for `category` only.
+     *
+     * When no schemas are registered for the category, falls back to
+     * `parse()`. Throws a `NoeticErrorImpl` with kind `item_schema_mismatch`
+     * when schemas exist for the category and none match.
+     */
     parseWithCategory(value: unknown, category: ItemSchemaCategory): Item;
 }
 /** @public Default item schema registry. */

package/dist/schemas/item.js

@@ -11,8 +11,14 @@
  * Use this at trust boundaries (loading persisted session files, accepting
  * externally-supplied transcripts) where we need to reject garbage JSON but
  * don't need to re-validate every provider field TypeScript already types.
+ *
+ * Extension schemas registered on the registry are **gates, not
+ * normalizers**: they validate item shape and the ORIGINAL value is returned
+ * on match. Zod transforms, defaults, and key-stripping in extension schemas
+ * are unsupported — their output is discarded. Declare pure shape validators.
  */
 import { z } from 'zod';
+import { NoeticErrorImpl } from '../errors/noetic-error.js';
 function isItemLike(value) {
     if (typeof value !== 'object' || value === null) {
         return false;
@@ -85,15 +91,19 @@ function isKnownBaseType(type) {
         type.startsWith('openrouter:'));
 }
 function schemaMismatch(category) {
-    return new z.ZodError([
-        {
-            code: 'custom',
-            message: `Item did not match any registered ${category} extension schema.`,
-            path: [],
-        },
-    ]);
+    return new NoeticErrorImpl({
+        kind: 'item_schema_mismatch',
+        category,
+    });
 }
-/** @public Runtime item validator with optional tool, memory-layer, and harness extension schemas. */
+/**
+ * @public Runtime item validator with optional tool, memory-layer, and harness extension schemas.
+ *
+ * Extension schemas are pure shape validators (gate, not normalizer): on
+ * match the original value is returned unchanged, including fields the schema
+ * does not declare. Transforms and defaults in extension schemas are
+ * unsupported — their parsed output is never used.
+ */
 export class ItemSchemaRegistry {
     extensions;
     strictUnknownExtensions;
@@ -116,25 +126,30 @@ export class ItemSchemaRegistry {
         for (const schema of schemas) {
             const parsed = schema.safeParse(value);
             if (parsed.success) {
-                return ItemSchema.parse(parsed.data);
+                // Gate, not normalizer: return the original value, not the
+                // zod-stripped clone, so undeclared fields survive validation.
+                return base;
             }
         }
         if (this.strictUnknownExtensions && !isKnownBaseType(base.type)) {
-            throw new z.ZodError([
-                {
-                    code: 'custom',
-                    message: `Item type '${base.type}' did not match any registered item extension schema.`,
-                    path: [
-                        'type',
-                    ],
-                },
-            ]);
+            throw new NoeticErrorImpl({
+                kind: 'item_schema_mismatch',
+                category: 'items',
+                itemType: base.type,
+            });
         }
         return base;
     }
     parseMany(values) {
         return Array.from(values, (value) => this.parse(value));
     }
+    /**
+     * Validate `value` against the schemas registered for `category` only.
+     *
+     * When no schemas are registered for the category, falls back to
+     * `parse()`. Throws a `NoeticErrorImpl` with kind `item_schema_mismatch`
+     * when schemas exist for the category and none match.
+     */
     parseWithCategory(value, category) {
         const schemas = schemasForCategory(this.extensions, category);
         if (schemas.length === 0) {
@@ -143,7 +158,8 @@ export class ItemSchemaRegistry {
         for (const schema of schemas) {
             const parsed = schema.safeParse(value);
             if (parsed.success) {
-                return ItemSchema.parse(parsed.data);
+                // Gate, not normalizer: validate shape, return the original value.
+                return ItemSchema.parse(value);
             }
         }
         throw schemaMismatch(category);

package/dist/types/channel.d.ts

@@ -23,6 +23,12 @@ export interface ExternalChannel<T> extends Channel<T> {
 }
 /** @public Handle for sending messages to a channel and checking its closed state. */
 export interface ChannelHandle<T> {
+    /**
+     * External-sender write: synchronous and never back-pressured. When a
+     * queue channel is at capacity the OLDEST item is dropped (with a warning)
+     * so external callers (HTTP handlers, CLI prompts) never block. Internal
+     * senders (`ctx.send`) get async back-pressure instead.
+     */
     send(value: T): void;
     readonly closed: boolean;
     readonly channel: Channel<T>;

package/dist/types/context.d.ts

@@ -135,7 +135,13 @@ export interface ContextHarness {
     projectHistory(layers: MemoryLayer[], items: ReadonlyArray<import('./items.js').Item>, ctx: Context): Promise<ReadonlyArray<import('./items.js').Item>>;
     storeLayers(layers: MemoryLayer[], response: LLMResponse, ctx: Context): Promise<void>;
     previewRequestItems(scope?: unknown): Promise<ReadonlyArray<import('./items.js').Item>>;
-    send<T>(channel: Channel<T>, value: T, ctx: Context): void;
+    /**
+     * Internal-sender channel write. Resolves immediately unless the target
+     * queue channel is at capacity, in which case the send parks until a
+     * consumer frees a slot (back-pressure; default 30s timeout →
+     * `channel_timeout`, abort → `cancelled`).
+     */
+    send<T>(channel: Channel<T>, value: T, ctx: Context): Promise<void>;
     recv<T>(channel: Channel<T>, ctx: Context, opts?: {
         timeout?: number;
     }): Promise<T>;
@@ -193,7 +199,14 @@ export interface Context<TMemory = ContextMemory, TState = unknown> {
     recv<T>(channel: Channel<T>, opts?: {
         timeout?: number;
     }): Promise<T>;
-    send<T>(channel: Channel<T>, value: T): void;
+    /**
+     * Send a value into a channel. Resolves immediately for value/topic
+     * channels and for queue channels below capacity. When a queue channel is
+     * at capacity the returned promise parks until a consumer dequeues an item
+     * (back-pressure): after the default 30s timeout it rejects with
+     * `channel_timeout`, and aborting the context rejects it with `cancelled`.
+     */
+    send<T>(channel: Channel<T>, value: T): Promise<void>;
     tryRecv<T>(channel: Channel<T>): T | null;
     checkpoint(): Promise<void>;
     complete<T>(value: T): void;

package/dist/types/error.d.ts

@@ -40,6 +40,18 @@ export type NoeticError = {
 } | {
     kind: 'cancelled';
     reason?: string;
+} | {
+    /**
+     * Raised by `ItemSchemaRegistry` when an item fails extension-schema
+     * validation: either a category item (e.g. a tool result) matches none
+     * of the schemas registered for its category, or — under
+     * `strictUnknownExtensions` — an unknown item type matches no
+     * registered extension schema. `itemType` is set for the
+     * unknown-item-type case.
+     */
+    kind: 'item_schema_mismatch';
+    category: 'items' | 'developerMessages' | 'toolCalls' | 'toolResults';
+    itemType?: string;
 } | {
     kind: 'budget_exceeded';
     field: 'cost' | 'steps' | 'duration';

package/dist/types/runtime.d.ts

@@ -195,7 +195,13 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     readonly rootCwdState: CwdState;
     /** Update the harness root cwd. Used by the TUI when the user issues a `! cd`. */
     setRootCwd(nextCwd: string): void;
-    send<T>(channel: Channel<T>, value: T, ctx: Context): void;
+    /**
+     * Internal-sender channel write (back-pressured): resolves immediately
+     * unless the queue channel is at capacity, in which case it parks until a
+     * consumer frees a slot (30s default timeout → `channel_timeout`; context
+     * abort → `cancelled`).
+     */
+    send<T>(channel: Channel<T>, value: T, ctx: Context): Promise<void>;
     recv<T>(channel: Channel<T>, ctx: Context, opts?: {
         timeout?: number;
     }): Promise<T>;

package/dist/types/step.d.ts

@@ -4,6 +4,7 @@ import type { ModelParams, RetryPolicy, StepMeta } from './common.js';
 import type { Context } from './context.js';
 import type { NoeticError } from './error.js';
 import type { ContextMemory, MemoryConfig, MemoryLayer, ProjectionPolicy } from './memory.js';
+import type { SubHarness, SubHarnessKind, SubHarnessSessionPolicy, SubHarnessSettings } from './sub-harness.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
 import type { Tool } from './tool.js';
 /**
@@ -70,7 +71,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<TMemory = ContextMemory, I = unknown, O = unknown> = StepRun<TMemory, I, O> | StepLLM<TMemory, I, O> | StepTool<TMemory, I, O> | StepBranch<TMemory, I, O> | StepFork<TMemory, I, O> | StepSpawn<TMemory, I, O> | StepProvide<TMemory, I, O> | StepLoop<TMemory, I, O> | StepEvery<TMemory, I, O>;
+export type Step<TMemory = ContextMemory, I = unknown, O = unknown> = StepRun<TMemory, I, O> | StepLLM<TMemory, I, O> | StepSubHarness<TMemory, I, O> | StepTool<TMemory, I, O> | StepBranch<TMemory, I, O> | StepFork<TMemory, I, O> | StepSpawn<TMemory, I, O> | StepProvide<TMemory, I, O> | StepLoop<TMemory, I, O> | StepEvery<TMemory, I, O>;
 /** @public A step that executes arbitrary async logic via a user-supplied function. */
 export interface StepRun<TMemory = ContextMemory, I = unknown, O = unknown> {
     kind: 'run';
@@ -102,6 +103,36 @@ export interface StepLLM<TMemory = ContextMemory, _I = unknown, O = unknown> {
     /** Projection policy for this step's context window. Overrides the harness-level default. */
     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.
+ * @public
+ */
+export interface StepSubHarness<TMemory = ContextMemory, _I = unknown, O = unknown> {
+    /** The harness kind, equal to the backing adapter's `harnessId`. */
+    kind: SubHarnessKind;
+    id: string;
+    /**
+     * The harness adapter that runs the turn. Eager or `(ctx) => SubHarness`.
+     * Programmatic builders take it inline; the JSON hydrator resolves it from
+     * the workflow's harness registry and inlines it here.
+     */
+    harness: Lazy<SubHarness, TMemory>;
+    /** Turn prompt. Eager string or `(ctx) => string` getter. */
+    prompt: Lazy<string, TMemory>;
+    /** Shared harness settings (model, permission mode, …). */
+    settings?: SubHarnessSettings;
+    /** System instructions applied on the first message of a fresh session. */
+    instructions?: Lazy<string | undefined, TMemory>;
+    /** When set, the assistant text is JSON-parsed and validated against this schema. */
+    output?: ZodType<O>;
+    /** Session reuse + teardown policy across steps. */
+    session?: SubHarnessSessionPolicy;
+    /** 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<_TMemory = ContextMemory, I = unknown, O = unknown> {
     kind: 'tool';

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

@@ -0,0 +1,273 @@
+/**
+ * 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 `MemoryLayer` 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<{
+        error: "error";
+        length: "length";
+        aborted: "aborted";
+        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

@@ -0,0 +1,106 @@
+/**
+ * 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 `MemoryLayer` 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

package/dist/util/message-helpers.d.ts

@@ -2,7 +2,11 @@ import type { LLMResponse } from '../types/common.js';
 import type { Context } from '../types/context.js';
 import type { InputMessageItem, Item, MessageItem } from '../types/items.js';
 export declare function isAssistantMessage(item: unknown): item is MessageItem;
-export declare function isUserMessage(item: unknown): item is MessageItem;
+/** @public Input message item narrowed to the `user` role. */
+export type UserMessageItem = InputMessageItem & {
+    readonly role: 'user';
+};
+export declare function isUserMessage(item: unknown): item is UserMessageItem;
 export declare function isOutputText(part: {
     type: string;
 }): part is {

package/dist/util/message-helpers.js

@@ -28,7 +28,7 @@ export function isTextPart(part) {
 /** Extracts assistant/output text from items for memory buffering (one string per message). */
 export function collectOutputText(items) {
     return items
-        .filter((i) => i.type === 'message')
+        .filter(isAssistantMessage)
         .map((i) => i.content
         .filter(isOutputText)
         .map((c) => c.text)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "0.2.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",
@@ -60,7 +60,7 @@
   "scripts": {
     "build": "bunx tsc -p tsconfig.build.json && bun scripts/add-js-extensions.ts",
     "verify:esm": "bun scripts/verify-node-esm.ts",
-    "prepublishOnly": "rm -rf dist && bun run build && bun run verify:esm",
+    "prepublishOnly": "rm -rf dist && bun run build && bun run verify:esm && bun scripts/strip-dev-conditions.ts",
     "test": "bun test",
     "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov",
     "test:ci": "bun test --coverage --coverage-reporter=lcov",