@noetic-tools/core 1.1.0 → 1.1.2

package/dist/interpreter/sub-harness-events.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Maps a sub-harness turn's output onto the harness's observable event surface.
+ *
+ * A sub-harness adapter emits {@link SubHarnessStreamPart}s; this bridge
+ * translates each one into the same `source: 'sdk'` broadcaster events the
+ * model-call path emits, so a coding agent's text, reasoning, and tool calls
+ * flow through `getTextStream()` / `getReasoningStream()` / `getItemStream()` /
+ * `getFullStream()` exactly like an LLM step's output. It also re-emits the raw
+ * part as a `sub_harness_event` framework event for harness-native consumers.
+ *
+ * `finalize()` guarantees a turn always emits its output: if an adapter returns
+ * a result without streaming any text/tool parts, the result's content is
+ * synthesized into events.
+ */
+import type { Context, ContextMemory, StepSubHarness, SubHarnessStreamPart, SubHarnessTurnResult } from '@noetic-tools/types';
+export declare class SubHarnessEventBridge {
+    private readonly broadcaster?;
+    private readonly agentName;
+    private readonly stepId;
+    private readonly stepKind;
+    private readonly emitOption;
+    private started;
+    private completed;
+    private nextOutputIndex;
+    private messageOutputIndex;
+    private sawText;
+    private sawToolCall;
+    constructor(step: Pick<StepSubHarness, 'id' | 'kind' | 'emit'>, ctx: Context<ContextMemory>);
+    /**
+     * Open the turn on the event surface. Emits `response.created` so every turn
+     * always brackets with a lifecycle marker — even a custom adapter that
+     * streams nothing still emits output.
+     */
+    begin(): void;
+    /** Forward one stream part: a structured framework event + the mapped sdk events. */
+    forward(part: SubHarnessStreamPart): void;
+    /**
+     * Ensure the turn's output reached the event surface. For adapters that
+     * return a result without streaming, synthesize events from the result.
+     */
+    finalize(result: SubHarnessTurnResult): void;
+    private sdk;
+    private start;
+    private openMessage;
+    private closeMessage;
+    private emitToolCall;
+    private translate;
+}

package/dist/interpreter/sub-harness-events.js

@@ -0,0 +1,208 @@
+/**
+ * Maps a sub-harness turn's output onto the harness's observable event surface.
+ *
+ * A sub-harness adapter emits {@link SubHarnessStreamPart}s; this bridge
+ * translates each one into the same `source: 'sdk'` broadcaster events the
+ * model-call path emits, so a coding agent's text, reasoning, and tool calls
+ * flow through `getTextStream()` / `getReasoningStream()` / `getItemStream()` /
+ * `getFullStream()` exactly like an LLM step's output. It also re-emits the raw
+ * part as a `sub_harness_event` framework event for harness-native consumers.
+ *
+ * `finalize()` guarantees a turn always emits its output: if an adapter returns
+ * a result without streaming any text/tool parts, the result's content is
+ * synthesized into events.
+ */
+import { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
+import { isFunctionCall } from './typeguards.js';
+export class SubHarnessEventBridge {
+    broadcaster;
+    agentName;
+    stepId;
+    stepKind;
+    emitOption;
+    started = false;
+    completed = false;
+    nextOutputIndex = 0;
+    messageOutputIndex = null;
+    sawText = false;
+    sawToolCall = false;
+    constructor(step, ctx) {
+        this.broadcaster = getBroadcaster(ctx);
+        this.agentName = ctx.harness.config.name;
+        this.stepId = step.id;
+        this.stepKind = step.kind;
+        this.emitOption = step.emit;
+    }
+    /**
+     * Open the turn on the event surface. Emits `response.created` so every turn
+     * always brackets with a lifecycle marker — even a custom adapter that
+     * streams nothing still emits output.
+     */
+    begin() {
+        this.start();
+    }
+    /** Forward one stream part: a structured framework event + the mapped sdk events. */
+    forward(part) {
+        if (!this.broadcaster) {
+            return;
+        }
+        const data = {
+            stepId: this.stepId,
+            kind: this.stepKind,
+            part,
+        };
+        if (shouldEmit(this.emitOption, 'sub_harness_event', data)) {
+            emitFrameworkEvent({
+                broadcaster: this.broadcaster,
+                agentName: this.agentName,
+                eventType: 'sub_harness_event',
+                data,
+            });
+        }
+        this.translate(part);
+    }
+    /**
+     * Ensure the turn's output reached the event surface. For adapters that
+     * return a result without streaming, synthesize events from the result.
+     */
+    finalize(result) {
+        if (!this.broadcaster) {
+            return;
+        }
+        if (!this.sawText && result.text.length > 0) {
+            this.openMessage();
+            this.sdk('response.output_text.delta', {
+                delta: result.text,
+            }, this.messageOutputIndex ?? 0);
+            this.sawText = true;
+        }
+        if (!this.sawToolCall) {
+            for (const item of result.items) {
+                if (isFunctionCall(item)) {
+                    this.emitToolCall(item.callId, item.name, item.arguments);
+                }
+            }
+        }
+        this.closeMessage();
+        // Always close the turn so every turn emits a completion marker.
+        if (!this.completed) {
+            this.start();
+            this.sdk('response.completed', {});
+            this.completed = true;
+        }
+    }
+    //#region internals
+    sdk(type, data, outputIndex) {
+        if (!this.broadcaster) {
+            return;
+        }
+        if (!shouldEmit(this.emitOption, type, data)) {
+            return;
+        }
+        this.broadcaster.emit({
+            source: 'sdk',
+            type,
+            data,
+            outputIndex,
+        });
+    }
+    start() {
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+        this.sdk('response.created', {});
+    }
+    openMessage() {
+        if (this.messageOutputIndex !== null) {
+            return;
+        }
+        this.start();
+        const id = `sub-harness-msg-${crypto.randomUUID()}`;
+        this.messageOutputIndex = this.nextOutputIndex++;
+        this.sdk('response.output_item.added', {
+            item: {
+                id,
+                type: 'message',
+                role: 'assistant',
+                status: 'in_progress',
+                content: [
+                    {
+                        type: 'output_text',
+                        text: '',
+                    },
+                ],
+            },
+        }, this.messageOutputIndex);
+    }
+    closeMessage() {
+        if (this.messageOutputIndex === null) {
+            return;
+        }
+        const index = this.messageOutputIndex;
+        this.sdk('response.output_text.done', {}, index);
+        this.sdk('response.output_item.done', {}, index);
+        this.messageOutputIndex = null;
+    }
+    emitToolCall(toolCallId, name, input) {
+        this.start();
+        const index = this.nextOutputIndex++;
+        const args = typeof input === 'string' ? input : JSON.stringify(input ?? {});
+        this.sdk('response.output_item.added', {
+            item: {
+                id: toolCallId,
+                type: 'function_call',
+                status: 'in_progress',
+                callId: toolCallId,
+                name,
+                arguments: '',
+            },
+        }, index);
+        this.sdk('response.function_call_arguments.delta', {
+            delta: args,
+        }, index);
+        this.sdk('response.function_call_arguments.done', {
+            arguments: args,
+        }, index);
+        this.sdk('response.output_item.done', {}, index);
+        this.sawToolCall = true;
+    }
+    translate(part) {
+        if (part.type === 'stream-start') {
+            this.start();
+            return;
+        }
+        if (part.type === 'text-delta') {
+            this.openMessage();
+            this.sdk('response.output_text.delta', {
+                delta: part.delta,
+            }, this.messageOutputIndex ?? 0);
+            this.sawText = true;
+            return;
+        }
+        if (part.type === 'reasoning-delta') {
+            this.start();
+            this.sdk('response.reasoning.delta', {
+                delta: part.delta,
+            });
+            return;
+        }
+        if (part.type === 'tool-call') {
+            this.closeMessage();
+            this.emitToolCall(part.toolCallId, part.toolName, part.input);
+            return;
+        }
+        if (part.type === 'finish') {
+            this.closeMessage();
+            this.sdk('response.completed', {
+                finishReason: part.finishReason,
+            });
+            this.completed = true;
+            return;
+        }
+        // file-change | tool-result | error | raw — surfaced on the full stream only.
+        this.sdk(`sub_harness.${part.type}`, {
+            part,
+        });
+    }
+}

package/dist/patterns/dynamic-workflow.js

@@ -27,6 +27,9 @@ A WorkflowNode is one of:
 - { "kind": "loop", "id": "<unique>", "body": <WorkflowNode>, "until": { "kind": "maxSteps", "n": <number> } }
 - { "kind": "branch", "id": "<unique>", "routes": [{ "match": "<substring>", "target": <WorkflowNode> }], "default": <WorkflowNode> }
 - { "kind": "spawn", "id": "<unique>", "child": <WorkflowNode> }
+- { "kind": "claude-code"|"codex"|"opencode"|"pi", "id": "<unique>", "prompt": "<turn prompt>", "settings": { "model": "<optional>", "permissionMode": "<optional>" } }
+
+SubHarness nodes (claude-code, codex, opencode, pi) delegate a turn to an external coding agent; only emit one if a matching harness adapter is registered for the workflow.
 
 Until predicates: maxSteps, maxCost, maxDuration, noToolCalls, outputContains, outputEquals, converged, any, all.
 

package/dist/schemas/workflow.d.ts

@@ -6,6 +6,7 @@
  * closures). The hydrator in `builders/workflow-hydrator.ts` converts a
  * validated document back into live `Step` objects via the existing builders.
  */
+import type { SubHarnessKind } from '@noetic-tools/types';
 import { z } from 'zod';
 interface UntilAnyPredicate {
     kind: 'any';
@@ -59,6 +60,26 @@ declare const ModelParamsSchema: z.ZodObject<{
     maxTokens: z.ZodOptional<z.ZodNumber>;
     stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+declare const HarnessSettingsSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    permissionMode: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        plan: "plan";
+        acceptEdits: "acceptEdits";
+        bypassPermissions: "bypassPermissions";
+    }>>;
+    maxTurns: z.ZodOptional<z.ZodNumber>;
+    allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const HarnessSessionPolicySchema: z.ZodObject<{
+    reuse: z.ZodOptional<z.ZodString>;
+    onComplete: z.ZodOptional<z.ZodEnum<{
+        stop: "stop";
+        detach: "detach";
+        destroy: "destroy";
+    }>>;
+}, z.core.$strip>;
 interface WorkflowNodeBase {
     id: string;
 }
@@ -116,9 +137,21 @@ export interface EveryWorkflowNode extends WorkflowNodeBase {
     ms: number;
     onError?: 'continue' | 'fail';
 }
+/**
+ * A node that delegates a turn to a coding-agent harness. `kind` is the harness
+ * id (e.g. `claude-code`); the hydrator resolves the matching adapter from the
+ * workflow's harness registry.
+ */
+export interface SubHarnessWorkflowNode extends WorkflowNodeBase {
+    kind: SubHarnessKind;
+    prompt: string;
+    instructions?: string;
+    settings?: z.infer<typeof HarnessSettingsSchema>;
+    session?: z.infer<typeof HarnessSessionPolicySchema>;
+}
 /** @public Discriminated union of all JSON-serialisable workflow node kinds. */
-export type WorkflowNode = LlmWorkflowNode | ToolWorkflowNode | BranchWorkflowNode | ForkWorkflowNode | SpawnWorkflowNode | ProvideWorkflowNode | LoopWorkflowNode | SequenceWorkflowNode | EveryWorkflowNode;
-/** @public Zod schema validating a single `WorkflowNode` (any of the 9 JSON-safe kinds). */
+export type WorkflowNode = LlmWorkflowNode | ToolWorkflowNode | BranchWorkflowNode | ForkWorkflowNode | SpawnWorkflowNode | ProvideWorkflowNode | LoopWorkflowNode | SequenceWorkflowNode | EveryWorkflowNode | SubHarnessWorkflowNode;
+/** @public Zod schema validating a single `WorkflowNode` (any JSON-safe kind). */
 export declare const WorkflowNodeSchema: z.ZodType<WorkflowNode>;
 /** @public Top-level envelope for a JSON workflow definition. */
 export interface WorkflowDocument {

package/dist/schemas/workflow.js

@@ -85,6 +85,32 @@ const ModelParamsSchema = z.object({
     stopSequences: z.array(z.string()).optional(),
 });
 //#endregion
+//#region SubHarness Settings
+const HarnessSettingsSchema = z.object({
+    model: z.string().optional(),
+    permissionMode: z
+        .enum([
+        'default',
+        'plan',
+        'acceptEdits',
+        'bypassPermissions',
+    ])
+        .optional(),
+    maxTurns: z.number().int().positive().optional(),
+    allowedTools: z.array(z.string()).optional(),
+    extra: z.record(z.string(), z.unknown()).optional(),
+});
+const HarnessSessionPolicySchema = z.object({
+    reuse: z.string().min(1).optional(),
+    onComplete: z
+        .enum([
+        'stop',
+        'detach',
+        'destroy',
+    ])
+        .optional(),
+});
+//#endregion
 //#region Workflow Node Schema
 const WorkflowNodeRef = z.lazy(() => WorkflowNodeSchema);
 const SHARED_FIELDS = {
@@ -162,7 +188,22 @@ const EveryNodeSchema = z.object({
     ])
         .optional(),
 });
-/** @public Zod schema validating a single `WorkflowNode` (any of the 9 JSON-safe kinds). */
+/** Builds the schema for a single harness node kind (`claude-code`, `codex`, …). */
+function subHarnessNodeSchema(kind) {
+    return z.object({
+        kind: z.literal(kind),
+        ...SHARED_FIELDS,
+        prompt: z.string().min(1),
+        instructions: z.string().optional(),
+        settings: HarnessSettingsSchema.optional(),
+        session: HarnessSessionPolicySchema.optional(),
+    });
+}
+const ClaudeCodeNodeSchema = subHarnessNodeSchema('claude-code');
+const CodexNodeSchema = subHarnessNodeSchema('codex');
+const OpencodeNodeSchema = subHarnessNodeSchema('opencode');
+const PiNodeSchema = subHarnessNodeSchema('pi');
+/** @public Zod schema validating a single `WorkflowNode` (any JSON-safe kind). */
 export const WorkflowNodeSchema = z
     .discriminatedUnion('kind', [
     LlmNodeSchema,
@@ -174,6 +215,10 @@ export const WorkflowNodeSchema = z
     LoopNodeSchema,
     SequenceNodeSchema,
     EveryNodeSchema,
+    ClaudeCodeNodeSchema,
+    CodexNodeSchema,
+    OpencodeNodeSchema,
+    PiNodeSchema,
 ])
     .meta({
     id: 'WorkflowNode',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and memory layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -67,7 +67,7 @@
   },
   "dependencies": {
     "@noetic-tools/memory": "^1.0.1",
-    "@noetic-tools/types": "^1.0.0",
+    "@noetic-tools/types": "^1.0.1",
     "@openrouter/agent": "^0.6.0",
     "zod": "^4.0.0"
   },