@noetic-tools/core 2.1.0 → 2.2.1

package/dist/adapters/openrouter.d.ts

@@ -43,6 +43,8 @@ export interface ExecuteToolCallParams {
     context: Context;
     harness: AgentHarnessContract;
     layers?: MemoryLayer[];
+    /** The model's `function_call` id — keys this call's tool-UI region. */
+    callId?: string;
 }
 /** @internal Execute a single tool call with steering checks. */
 export declare function executeToolCall(params: ExecuteToolCallParams): Promise<{

package/dist/adapters/openrouter.js

@@ -1,6 +1,7 @@
 import { frameworkCast, isAssistantMessage, NoeticConfigError, SteeringAction, } from '@noetic-tools/types';
 import { z } from 'zod';
 import { buildToolExecutionContext } from '../runtime/tool-memory.js';
+import { emitToolUi } from '../runtime/tool-ui.js';
 const EmbeddingsResponseSchema = z.object({
     data: z.array(z.object({
         embedding: z.array(z.number()),
@@ -204,17 +205,6 @@ function isAsyncGenerator(value) {
     }
     return Symbol.asyncIterator in value;
 }
-async function consumeGenerator(generator) {
-    let result;
-    while (true) {
-        const next = await generator.next();
-        if (next.done) {
-            result = next.value;
-            break;
-        }
-    }
-    return result;
-}
 /** @internal Execute a single tool call with steering checks. */
 export async function executeToolCall(params) {
     // Model sees sanitised tool names (see `sanitizeToolNameForWire`). Match
@@ -245,18 +235,67 @@ export async function executeToolCall(params) {
         }
     }
     const toolCtx = buildToolExecutionContext(params.context, params.harness);
+    const callId = params.callId;
+    const uiBase = callId !== undefined
+        ? {
+            ctx: params.context,
+            tool: matchedTool,
+            callId,
+            args: params.args,
+        }
+        : undefined;
+    if (uiBase) {
+        emitToolUi({
+            ...uiBase,
+            phase: 'call',
+        });
+    }
     try {
         const executionResult = matchedTool.execute(params.args, toolCtx);
-        // Handle generator-based tools (like Bash) that return AsyncGenerator
-        const result = isAsyncGenerator(executionResult)
-            ? await consumeGenerator(executionResult)
-            : await executionResult;
+        // Generator tools stream progress; drive them here so tool-UI `progress`
+        // fragments emit per yield (the non-UI case just consumes to the return).
+        let result;
+        if (isAsyncGenerator(executionResult)) {
+            const events = [];
+            for (;;) {
+                const next = await executionResult.next();
+                if (next.done) {
+                    result = next.value;
+                    break;
+                }
+                events.push(next.value);
+                if (uiBase) {
+                    emitToolUi({
+                        ...uiBase,
+                        phase: 'progress',
+                        events,
+                    });
+                }
+            }
+        }
+        else {
+            result = await executionResult;
+        }
+        if (uiBase) {
+            emitToolUi({
+                ...uiBase,
+                phase: 'result',
+                output: result,
+            });
+        }
         return {
             output: typeof result === 'string' ? result : JSON.stringify(result),
             result,
         };
     }
     catch (e) {
+        if (uiBase) {
+            emitToolUi({
+                ...uiBase,
+                phase: 'error',
+                error: e,
+            });
+        }
         return {
             output: `Error: ${e instanceof Error ? e.message : String(e)}`,
             error: true,

package/dist/builders/step-builders.d.ts

@@ -1,5 +1,5 @@
 import type { ContextMemory } from '@noetic-tools/memory';
-import type { Context, Lazy, ModelParams, RetryPolicy, ServerToolSpec, StepLLM, StepRun, StepSubHarness, StepTool, SubHarness, SubHarnessSessionPolicy, SubHarnessSettings, SubprocessAdapter, Tool } from '@noetic-tools/types';
+import type { Context, Lazy, ModelParams, OutputCodec, RetryPolicy, ServerToolSpec, StepLLM, StepRun, StepSubHarness, StepTool, SubHarness, SubHarnessSessionPolicy, SubHarnessSettings, SubprocessAdapter, Tool } from '@noetic-tools/types';
 import type { ZodType } from 'zod';
 interface StepRunOpts<TMemory, I, O> {
     id: string;
@@ -24,7 +24,8 @@ interface StepLLMOpts<TMemory, O> {
      * server tool the provider executes, e.g. web search/fetch).
      */
     tools?: Lazy<(Tool | ServerToolSpec)[] | undefined, TMemory>;
-    output?: ZodType<O>;
+    /** Structured output: a Zod schema or a streaming `OutputCodec` (e.g. OpenUI Lang). */
+    output?: ZodType<O> | OutputCodec<O>;
     params?: ModelParams;
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
 }

package/dist/builders/workflow-hydrator.d.ts

@@ -6,7 +6,7 @@
  * ones — they register in the step registry, carry retry policies, etc.
  */
 import type { ContextMemory, MemoryLayer } from '@noetic-tools/memory';
-import type { ExecuteStepFn, Step, SubHarness, SubHarnessKind, SubprocessAdapter, Tool } from '@noetic-tools/types';
+import type { ExecuteStepFn, OutputCodec, Step, SubHarness, SubHarnessKind, SubprocessAdapter, Tool } from '@noetic-tools/types';
 import type { WorkflowDocument, WorkflowNode } from '../schemas/workflow.js';
 /** @public Context required to hydrate a JSON workflow into live steps. */
 export interface HydrationContext {
@@ -15,6 +15,13 @@ export interface HydrationContext {
     layers?: ReadonlyMap<string, MemoryLayer>;
     /** SubHarness adapters keyed by harness id, resolving `claude-code`/`codex`/… nodes. */
     subHarnesses?: ReadonlyMap<SubHarnessKind, SubHarness>;
+    /**
+     * Output codecs keyed by the `library` ref an `llm` node's `output` codec
+     * reference names — the live codec built from a component library, e.g.
+     * `new Map([['dashboard-lib', openUi(dashboardLibrary)]])` from
+     * `@noetic-tools/openui`. Resolved the same way sub-harness adapters are.
+     */
+    uiLibraries?: ReadonlyMap<string, OutputCodec>;
     /**
      * Resolves a named subprocess adapter ref declared on a `run` node's
      * `subprocess` field. When a node omits the ref, the step falls back to

package/dist/builders/workflow-hydrator.js

@@ -49,21 +49,19 @@ function hydrateUntilPredicate(pred) {
 }
 //#endregion
 //#region Node Hydrators
-function hydrateLlmNode(node, ctx) {
-    if (node.kind !== 'llm') {
-        return frameworkCast(undefined);
-    }
-    // Every `tools` entry is an object `{ type, parameters? }`. Partition by the
-    // `type` value: a reserved `openrouter:*` server-tool literal is a SERVER
-    // tool (flows through unchanged); any other `type` is a CLIENT tool whose
-    // `type` is the registered tool NAME (resolved from the registry; a client
-    // entry's `parameters` is ignored). Both kinds are combined back into one
-    // `tools` array; the interpreter partitions them again at execution (server
-    // specs bypass the client-tool machinery and reach the model call's
-    // server-tool channel).
+/**
+ * Resolve an llm node's `tools` entries into a combined client+server list.
+ *
+ * Every entry is `{ type, parameters? }`. A reserved `openrouter:*` literal is
+ * a SERVER tool (flows through unchanged); any other `type` is a CLIENT tool
+ * whose `type` is the registered tool NAME (resolved from the registry). Both
+ * kinds combine into one `tools` array; the interpreter partitions them again
+ * at execution.
+ */
+function resolveLlmTools(entries, registry) {
     const toolNames = [];
     const serverSpecs = [];
-    for (const entry of node.tools ?? []) {
+    for (const entry of entries ?? []) {
         if (isServerToolSpec(entry)) {
             serverSpecs.push(entry);
         }
@@ -71,17 +69,53 @@ function hydrateLlmNode(node, ctx) {
             toolNames.push(entry.type);
         }
     }
-    const resolvedTools = resolveTools(toolNames, ctx.tools);
-    const combined = [
-        ...resolvedTools,
+    return [
+        ...resolveTools(toolNames, registry),
         ...serverSpecs,
     ];
+}
+function hydrateLlmNode(node, ctx) {
+    if (node.kind !== 'llm') {
+        return frameworkCast(undefined);
+    }
+    const combined = resolveLlmTools(node.tools, ctx.tools);
     return step.llm({
         id: node.id,
         model: node.model ?? 'openai/gpt-4o',
         instructions: node.instructions,
         tools: combined.length > 0 ? combined : undefined,
         params: node.params,
+        output: resolveOutputCodec(node.output, node.id, ctx),
+    });
+}
+/**
+ * Resolve an `llm` node's `output` codec reference to a live `OutputCodec`.
+ *
+ * Hydrated steps are typed `<string, string>` (the JSON boundary erases output
+ * types), so the resolved codec is cast to the step's erased output type — the
+ * runtime still returns the codec's real value. This is the same erasure the
+ * rest of the hydrator applies via `frameworkCast`.
+ */
+function availableLibraries(ctx) {
+    if (!ctx.uiLibraries || ctx.uiLibraries.size === 0) {
+        return '(none)';
+    }
+    return [
+        ...ctx.uiLibraries.keys(),
+    ].join(', ');
+}
+function resolveOutputCodec(ref, nodeId, ctx) {
+    if (!ref) {
+        return undefined;
+    }
+    const codec = ctx.uiLibraries?.get(ref.library);
+    if (codec) {
+        return frameworkCast(codec);
+    }
+    throw new NoeticConfigError({
+        code: 'UNKNOWN_UI_LIBRARY_REFERENCE',
+        message: `UI library '${ref.library}' referenced in workflow node '${nodeId}' is not registered.`,
+        hint: `Pass output codecs via HydrationContext.uiLibraries, e.g. new Map([['${ref.library}', openUi(myLibrary)]]) from @noetic-tools/openui. Available: ${availableLibraries(ctx)}`,
     });
 }
 function hydrateToolNode(node, ctx) {

package/dist/harness/model-call.js

@@ -685,6 +685,7 @@ export class AgentHarnessModelCaller {
             context: request.ctx,
             harness: this.opts.harness,
             layers: request.layers,
+            callId: fc.callId,
         });
         // Owner-scoped result validation: a tool's `toolResults` schemas apply
         // only to that tool's own result items. Harness-level `opts.itemSchemas`

package/dist/interpreter/action-deps.d.ts

@@ -2,7 +2,7 @@ export type { LayerStateStore } from '@noetic-tools/memory';
 export { allocateBudgets, assembleView, commitLayerUsage, computeLayerUsage, contextToExecCtx, DEFAULT_PROJECTION, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/memory';
 export type { ItemSchemaRegistry } from '@noetic-tools/types';
 export { defaultItemSchemaRegistry } from '@noetic-tools/types';
-export { emitFrameworkEvent, getBroadcaster } from '../runtime/broadcaster-utils.js';
+export { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
 export { ContextImpl } from '../runtime/context-impl.js';
 export { snapshotCwdState } from '../runtime/cwd-helpers.js';
 export { buildToolExecutionContext } from '../runtime/tool-memory.js';

package/dist/interpreter/action-deps.js

@@ -1,6 +1,6 @@
 export { allocateBudgets, assembleView, commitLayerUsage, computeLayerUsage, contextToExecCtx, DEFAULT_PROJECTION, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/memory';
 export { defaultItemSchemaRegistry } from '@noetic-tools/types';
-export { emitFrameworkEvent, getBroadcaster } from '../runtime/broadcaster-utils.js';
+export { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
 export { ContextImpl } from '../runtime/context-impl.js';
 export { snapshotCwdState } from '../runtime/cwd-helpers.js';
 export { buildToolExecutionContext } from '../runtime/tool-memory.js';

package/dist/interpreter/execute-action.js

@@ -1,9 +1,10 @@
 /**
  * Action step handlers: run, llm, spawn, provide, tool.
  */
-import { createMessage, estimateTokens, extractAssistantText, frameworkCast, isNoeticError, NoeticConfigError, NoeticErrorImpl, } from '@noetic-tools/types';
+import { createMessage, estimateTokens, extractAssistantText, frameworkCast, isNoeticError, isOutputCodec, NoeticConfigError, NoeticErrorImpl, } from '@noetic-tools/types';
 import { ZodError } from 'zod';
-import { allocateBudgets, assembleView, buildToolExecutionContext, ContextImpl, commitLayerUsage, computeLayerUsage, contextToExecCtx, DEFAULT_PROJECTION, defaultItemSchemaRegistry, emitFrameworkEvent, getBroadcaster, resolveLayerTools, returnLayers, snapshotCwdState, spawnLayers, } from './action-deps.js';
+import { emitToolUi } from '../runtime/tool-ui.js';
+import { allocateBudgets, assembleView, buildToolExecutionContext, ContextImpl, commitLayerUsage, computeLayerUsage, contextToExecCtx, DEFAULT_PROJECTION, defaultItemSchemaRegistry, emitFrameworkEvent, getBroadcaster, resolveLayerTools, returnLayers, shouldEmit, snapshotCwdState, spawnLayers, } from './action-deps.js';
 import { isServerToolSpec, SteeringAction } from './action-types.js';
 import { cloneWithGuard } from './clone-guard.js';
 import { collectAllTools, deduplicateTools } from './collect-tools.js';
@@ -164,6 +165,102 @@ async function runInputPipeline({ ctx, layers, input, }) {
     }
     return rerenderRequests;
 }
+/**
+ * Classify a step's `output` into the JSON-schema vs streaming-codec modes.
+ *
+ * An `OutputCodec` (e.g. OpenUI Lang) carries its own system-prompt fragment
+ * and is NOT a JSON schema — its `instructions` fold into the system prompt and
+ * it is kept off `outputSchema` (which drives JSON-schema formatting).
+ */
+function resolveOutputMode(output, baseInstructions) {
+    // A generic type predicate does not reliably narrow a `ZodType<O> |
+    // OutputCodec<O>` union through a free type parameter, so bridge the two
+    // branches with the sanctioned framework cast — `isOutputCodec` guarantees
+    // the discriminant at runtime.
+    const isCodec = isOutputCodec(output);
+    const outputCodec = isCodec ? frameworkCast(output) : undefined;
+    const outputSchema = isCodec ? undefined : frameworkCast(output);
+    const codecInstructions = outputCodec?.instructions;
+    const resolvedInstructions = codecInstructions !== undefined
+        ? [
+            baseInstructions,
+            codecInstructions,
+        ]
+            .filter((s) => s !== undefined)
+            .join('\n\n')
+        : baseInstructions;
+    return {
+        outputCodec,
+        outputSchema,
+        resolvedInstructions,
+    };
+}
+/**
+ * Drive an `OutputCodec` with the finished assistant text: emit its `openui.*`
+ * framework events (gated by `step.emit`) and return the codec's typed value.
+ * True per-delta streaming lives in the model caller; here the statements are
+ * delivered at turn finalization, which the transport still forwards.
+ */
+function finalizeCodecOutput(codec, lastText, ctx, emit) {
+    const session = codec.start();
+    const broadcaster = getBroadcaster(ctx);
+    const agentName = ctx.harness.config.name;
+    // A streaming codec emits per completed (newline-terminated) statement, so the
+    // final line — usually `root` — would stay buffered and never be emitted.
+    // Push a newline-terminated copy so that last statement is flushed as an event
+    // too; `finish` still reparses the original text for the returned value.
+    const textForEmit = lastText.endsWith('\n') ? lastText : `${lastText}\n`;
+    session.push(textForEmit, (eventType, data) => {
+        if (shouldEmit(emit, eventType, data)) {
+            emitFrameworkEvent({
+                broadcaster,
+                agentName,
+                eventType,
+                data,
+            });
+        }
+    });
+    return session.finish(lastText);
+}
+/** JSON-parse + Zod-validate the assistant text, raising `llm_parse_error`. */
+function parseSchemaOutput(schema, lastText, stepId) {
+    try {
+        return schema.parse(JSON.parse(lastText));
+    }
+    catch (e) {
+        if (e instanceof SyntaxError || e instanceof ZodError) {
+            throw new NoeticErrorImpl({
+                kind: 'llm_parse_error',
+                stepId,
+                raw: lastText,
+                schema,
+                zodError: e instanceof ZodError
+                    ? e
+                    : new ZodError([
+                        {
+                            code: 'custom',
+                            message: `Invalid JSON: ${e.message}`,
+                            path: [],
+                        },
+                    ]),
+            });
+        }
+        throw e;
+    }
+}
+/**
+ * Turn the finished assistant text into the step's typed output: a streaming
+ * codec, a Zod schema, or raw text passthrough.
+ */
+function finalizeStepOutput(params) {
+    if (params.outputCodec) {
+        return finalizeCodecOutput(params.outputCodec, params.lastText, params.ctx, params.emit);
+    }
+    if (params.outputSchema) {
+        return parseSchemaOutput(params.outputSchema, params.lastText, params.stepId);
+    }
+    return frameworkCast(params.lastText);
+}
 export async function executeLLM(step, input, ctx, layers) {
     const baseCtx = frameworkCast(ctx);
     const hasLayers = layers !== undefined && layers.length > 0;
@@ -178,7 +275,8 @@ export async function executeLLM(step, input, ctx, layers) {
             hint: "Ensure `model` (or your `(ctx) => string` getter) returns a non-empty identifier, e.g. 'anthropic/claude-sonnet-4-20250514'.",
         });
     }
-    const resolvedInstructions = await resolveLazy(step.instructions, ctx);
+    const baseInstructions = await resolveLazy(step.instructions, ctx);
+    const { outputCodec, outputSchema, resolvedInstructions } = resolveOutputMode(step.output, baseInstructions);
     const resolvedStepTools = await resolveLazy(step.tools, ctx);
     // `step.tools` is heterogeneous: client `Tool`s plus inline OpenRouter
     // server-tool specs (web search/fetch). Partition them — client tools flow
@@ -309,7 +407,7 @@ export async function executeLLM(step, input, ctx, layers) {
                 instructions: resolvedInstructions,
                 tools: resolvedTools,
                 params: step.params,
-                outputSchema: step.output,
+                outputSchema: outputSchema,
                 emit: step.emit,
                 _serverTools,
                 ctx: baseCtx,
@@ -323,7 +421,7 @@ export async function executeLLM(step, input, ctx, layers) {
                 items: assembledItems,
                 instructions: resolvedInstructions,
                 params: step.params,
-                outputSchema: step.output,
+                outputSchema: outputSchema,
                 emit: step.emit,
                 _serverTools,
                 nodeId: step.id,
@@ -376,33 +474,14 @@ export async function executeLLM(step, input, ctx, layers) {
             await baseCtx.harness.storeLayers(layers, response, baseCtx);
         }
         const lastText = extractAssistantText(response.items);
-        if (step.output) {
-            try {
-                const parsed = JSON.parse(lastText);
-                return step.output.parse(parsed);
-            }
-            catch (e) {
-                if (e instanceof SyntaxError || e instanceof ZodError) {
-                    throw new NoeticErrorImpl({
-                        kind: 'llm_parse_error',
-                        stepId: step.id,
-                        raw: lastText,
-                        schema: step.output,
-                        zodError: e instanceof ZodError
-                            ? e
-                            : new ZodError([
-                                {
-                                    code: 'custom',
-                                    message: `Invalid JSON: ${e.message}`,
-                                    path: [],
-                                },
-                            ]),
-                    });
-                }
-                throw e;
-            }
-        }
-        return frameworkCast(lastText);
+        return finalizeStepOutput({
+            stepId: step.id,
+            emit: step.emit,
+            outputCodec,
+            outputSchema,
+            lastText,
+            ctx: baseCtx,
+        });
     }
     // Safety net: the loop above always returns or throws within the body.
     // This throw is unreachable but protects against future refactors that
@@ -610,21 +689,32 @@ function isAsyncGenerator(value) {
 async function consumeToolGenerator(params) {
     const broadcaster = getBroadcaster(params.ctx);
     const agentName = params.ctx.harness.config.name;
+    const events = [];
     while (true) {
         const next = await params.generator.next();
         if (next.done) {
             return next.value;
         }
+        events.push(next.value);
         emitFrameworkEvent({
             broadcaster,
             agentName,
             eventType: 'tool_progress',
             data: {
                 stepId: params.stepId,
-                toolName: params.toolName,
+                toolName: params.tool.name,
                 event: next.value,
             },
         });
+        // A direct `step.tool` has no model call id — the step id keys its region.
+        emitToolUi({
+            ctx: params.ctx,
+            tool: params.tool,
+            callId: params.stepId,
+            phase: 'progress',
+            args: params.args,
+            events,
+        });
     }
 }
 export async function executeTool(step, input, ctx, harness, layers) {
@@ -648,20 +738,44 @@ export async function executeTool(step, input, ctx, harness, layers) {
             });
         }
     }
+    emitToolUi({
+        ctx: baseCtx,
+        tool: step.tool,
+        callId: step.id,
+        phase: 'call',
+        args: parseResult.data,
+    });
     try {
         const toolCtx = buildToolExecutionContext(baseCtx, harness);
-        const result = step.tool.execute(parseResult.data, toolCtx);
-        if (isAsyncGenerator(result)) {
-            return frameworkCast(await consumeToolGenerator({
-                generator: result,
+        const execResult = step.tool.execute(parseResult.data, toolCtx);
+        const result = isAsyncGenerator(execResult)
+            ? await consumeToolGenerator({
+                generator: execResult,
                 stepId: step.id,
-                toolName: step.tool.name,
+                tool: step.tool,
                 ctx: baseCtx,
-            }));
-        }
-        return frameworkCast(await result);
+                args: parseResult.data,
+            })
+            : await execResult;
+        emitToolUi({
+            ctx: baseCtx,
+            tool: step.tool,
+            callId: step.id,
+            phase: 'result',
+            args: parseResult.data,
+            output: result,
+        });
+        return frameworkCast(result);
     }
     catch (e) {
+        emitToolUi({
+            ctx: baseCtx,
+            tool: step.tool,
+            callId: step.id,
+            phase: 'error',
+            args: parseResult.data,
+            error: e,
+        });
         if (e instanceof NoeticErrorImpl) {
             throw e;
         }

package/dist/runtime/tool-ui.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tool-authored UI fragment emission.
+ *
+ * When a tool declares a `ui` block (`ToolUiDeclaration`), the runtime runs its
+ * render functions at the call / progress / result / error lifecycle points and
+ * forwards each returned `UiFragment` as an `openui.fragment` framework event
+ * (namespaced `${agentName}:openui.fragment`). The framework never interprets
+ * the fragment source — a UI surface (memory layer + transport) composes it.
+ *
+ * The `ui` methods are declared bivariantly on `ToolUiDeclaration`, so the
+ * erased `Tool` handle the runtime holds can call them with runtime values.
+ */
+import type { Context, Tool } from '@noetic-tools/types';
+/** The tool-UI lifecycle point being rendered. */
+export type ToolUiPhase = 'call' | 'progress' | 'result' | 'error';
+/** Parameters for {@link emitToolUi}. */
+export interface EmitToolUiParams {
+    ctx: Context;
+    tool: Tool;
+    callId: string;
+    phase: ToolUiPhase;
+    /** Parsed tool args (partial at `call` time). */
+    args: unknown;
+    /** Events seen so far — for `progress`. */
+    events?: unknown[];
+    /** The tool's return value — for `result`. */
+    output?: unknown;
+    /** The thrown error — for `error`. */
+    error?: unknown;
+}
+/**
+ * Render the tool's UI fragment for one lifecycle phase and, when it produces
+ * one, emit it as an `openui.fragment` framework event. No-op when the tool
+ * declares no `ui` for that phase.
+ */
+export declare function emitToolUi(params: EmitToolUiParams): void;

package/dist/runtime/tool-ui.js

@@ -0,0 +1,57 @@
+/**
+ * Tool-authored UI fragment emission.
+ *
+ * When a tool declares a `ui` block (`ToolUiDeclaration`), the runtime runs its
+ * render functions at the call / progress / result / error lifecycle points and
+ * forwards each returned `UiFragment` as an `openui.fragment` framework event
+ * (namespaced `${agentName}:openui.fragment`). The framework never interprets
+ * the fragment source — a UI surface (memory layer + transport) composes it.
+ *
+ * The `ui` methods are declared bivariantly on `ToolUiDeclaration`, so the
+ * erased `Tool` handle the runtime holds can call them with runtime values.
+ */
+import { frameworkCast } from '@noetic-tools/types';
+import { emitFrameworkEvent, getBroadcaster } from './broadcaster-utils.js';
+const OPENUI_FRAGMENT_EVENT = 'openui.fragment';
+function renderFragment(params) {
+    const ui = params.tool.ui;
+    if (!ui) {
+        return null;
+    }
+    // The `ui` methods are typed against the tool's own I/O schemas, erased to
+    // `ZodTypeAny` on the `Tool` handle the runtime holds. frameworkCast bridges
+    // the runtime values (`unknown`) to those erased parameter types.
+    const args = frameworkCast(params.args);
+    const output = frameworkCast(params.output);
+    switch (params.phase) {
+        case 'call':
+            return ui.call ? ui.call(args) : null;
+        case 'progress':
+            return ui.progress ? ui.progress(params.events ?? []) : null;
+        case 'result':
+            return ui.result ? ui.result(output, args) : null;
+        case 'error':
+            return ui.error ? ui.error(params.error, args) : null;
+    }
+}
+/**
+ * Render the tool's UI fragment for one lifecycle phase and, when it produces
+ * one, emit it as an `openui.fragment` framework event. No-op when the tool
+ * declares no `ui` for that phase.
+ */
+export function emitToolUi(params) {
+    const fragment = renderFragment(params);
+    if (fragment === null) {
+        return;
+    }
+    emitFrameworkEvent({
+        broadcaster: getBroadcaster(params.ctx),
+        agentName: params.ctx.harness.config.name,
+        eventType: OPENUI_FRAGMENT_EVENT,
+        data: {
+            callId: params.callId,
+            dialect: fragment.dialect,
+            source: fragment.source,
+        },
+    });
+}

package/dist/schemas/workflow.d.ts

@@ -114,6 +114,19 @@ declare const HarnessSessionPolicySchema: z.ZodObject<{
 interface WorkflowNodeBase {
     id: string;
 }
+/**
+ * A reference to a streaming `OutputCodec` for an `llm` node's structured
+ * output. The hydrator resolves `library` from `HydrationContext.uiLibraries`
+ * to a live codec (e.g. `openUi(myLibrary)` from `@noetic-tools/openui`), the
+ * same registry-resolution pattern sub-harness nodes use for adapters. Kept a
+ * *reference* because a codec is a runtime object, not JSON-expressible.
+ */
+export interface OutputCodecRef {
+    /** The codec dialect. Only `'openui'` is defined today. */
+    codec: 'openui';
+    /** Registry key resolved from `HydrationContext.uiLibraries`. */
+    library: string;
+}
 export interface LlmWorkflowNode extends WorkflowNodeBase {
     kind: 'llm';
     model?: string;
@@ -127,6 +140,8 @@ export interface LlmWorkflowNode extends WorkflowNodeBase {
      */
     tools?: z.infer<typeof LlmToolEntrySchema>[];
     params?: z.infer<typeof ModelParamsSchema>;
+    /** Streaming output-codec reference, resolved from `HydrationContext.uiLibraries`. */
+    output?: OutputCodecRef;
 }
 export interface ToolWorkflowNode extends WorkflowNodeBase {
     kind: 'tool';

package/dist/schemas/workflow.js

@@ -151,6 +151,10 @@ const WorkflowNodeRef = z.lazy(() => WorkflowNodeSchema);
 const SHARED_FIELDS = {
     id: z.string().min(1),
 };
+const OutputCodecRefSchema = z.object({
+    codec: z.literal('openui'),
+    library: z.string().min(1),
+});
 const LlmNodeSchema = z.object({
     kind: z.literal('llm'),
     ...SHARED_FIELDS,
@@ -158,6 +162,7 @@ const LlmNodeSchema = z.object({
     instructions: z.string(),
     tools: z.array(LlmToolEntrySchema).optional(),
     params: ModelParamsSchema.optional(),
+    output: OutputCodecRefSchema.optional(),
 });
 const ToolNodeSchema = z.object({
     kind: z.literal('tool'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "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.2.0",
+    "@noetic-tools/types": "^1.3.0",
     "@openrouter/agent": "^0.6.0",
     "zod": "^4.0.0"
   },

package/schema/noetic-workflow.schema.json

@@ -86,6 +86,24 @@
                 }
               },
               "additionalProperties": false
+            },
+            "output": {
+              "type": "object",
+              "properties": {
+                "codec": {
+                  "type": "string",
+                  "const": "openui"
+                },
+                "library": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "required": [
+                "codec",
+                "library"
+              ],
+              "additionalProperties": false
             }
           },
           "required": [