@noetic-tools/types 1.0.0 → 1.0.2

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/types/context.d.ts

@@ -9,7 +9,7 @@ import type { FsAdapter } from './fs-adapter.js';
 import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
 import type { ExecuteInput } from './items.js';
 import type { ContextMemory, MemoryLayer, ProjectionPolicy, StorageAdapter } from './memory.js';
-import type { Span } from './observability.js';
+import type { Span, TraceExporter } from './observability.js';
 import type { ShellAdapter } from './shell-adapter.js';
 import type { SteeringDecision } from './steering.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
@@ -152,6 +152,8 @@ export interface ContextHarness {
     checkpoint(ctx: Context): Promise<void>;
     restore(executionId: string): Promise<Context | null>;
     cancel(ctx: Context, reason?: string): Promise<void>;
+    /** Trace exporter spans are flushed to. Defaults to a no-op exporter. */
+    readonly traceExporter: TraceExporter;
     createSpan(name: string, parent: Span | null): Span;
     abort(scope?: unknown): Promise<void>;
     getStatus(scope?: unknown): ContextHarnessStatus;

package/dist/types/runtime.d.ts

@@ -7,7 +7,7 @@ import type { FsAdapter } from './fs-adapter.js';
 import type { HarnessResponse, StreamEvent, StreamingItem } from './harness-result.js';
 import type { ExecuteInput, Item, ItemSchemaExtensions } from './items.js';
 import type { ContextMemory, MemoryLayer, ProjectionPolicy, StorageAdapter } from './memory.js';
-import type { Span } from './observability.js';
+import type { Span, TraceExporter } from './observability.js';
 import type { ShellAdapter } from './shell-adapter.js';
 import type { SteeringDecision } from './steering.js';
 import type { Step } from './step.js';
@@ -56,6 +56,12 @@ interface CallModelRequestBase {
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
     /** Optional signal for cancelling the in-flight call (used by session abort). */
     signal?: AbortSignal;
+    /**
+     * @internal Parent span for the model-call spans this request produces. When
+     * omitted, the caller falls back to `ctx.span`. Set by `parseAndRunWorkflow`
+     * so model/tool spans nest under the root `workflow.run` span.
+     */
+    parentSpan?: Span;
 }
 /** @public Request shape when tools are provided — ctx is required for tool execution callbacks. */
 interface CallModelRequestWithTools extends CallModelRequestBase {
@@ -224,6 +230,8 @@ export interface AgentHarnessContract<TParams extends Record<string, unknown> =
     checkpoint(ctx: Context): Promise<void>;
     restore(executionId: string): Promise<Context | null>;
     cancel(ctx: Context, reason?: string): Promise<void>;
+    /** Trace exporter spans are flushed to. Defaults to a no-op exporter. */
+    readonly traceExporter: TraceExporter;
     createSpan(name: string, parent: Span | null): Span;
     getLayerState<T>(executionId: string, layerId: string): T | undefined;
     setLayerState<T>(executionId: string, layerId: string, state: T): void;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/types",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "description": "Foundational type contracts and primitives shared across the Noetic framework (items, LLM config, adapters, steering, errors).",
   "license": "Apache-2.0",