@noetic-tools/types 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export * from './types/items.js';
 export * from './types/memory.js';
 export * from './types/memory-context.js';
 export * from './types/observability.js';
+export * from './types/output-codec.js';
 export * from './types/runtime.js';
 export * from './types/shell-adapter.js';
 export * from './types/steering.js';

package/dist/index.js

@@ -18,6 +18,7 @@ export * from './types/items.js';
 export * from './types/memory.js';
 export * from './types/memory-context.js';
 export * from './types/observability.js';
+export * from './types/output-codec.js';
 export * from './types/runtime.js';
 export * from './types/shell-adapter.js';
 export * from './types/steering.js';

package/dist/types/output-codec.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Streaming output-dialect contracts for `step.llm`.
+ *
+ * An `OutputCodec` is the dialect-agnostic alternative to a Zod schema in
+ * `StepLLM.output`: instead of JSON-parsing the assistant text once at turn
+ * end, a codec is fed each text delta as it streams and produces a typed
+ * value when the turn finishes. OpenUI Lang is one dialect; the contract
+ * lives here — next to `MemoryLayer` and `SubHarness` — so `core` and
+ * dialect packages both depend on it without forming a cycle.
+ */
+/**
+ * Emitter handed to a codec session so it can surface framework events
+ * (e.g. `openui.node`) while a turn streams. Events flow through the
+ * executing step's normal framework-event surface and respect the step's
+ * `emit` gate.
+ * @public
+ */
+export type OutputCodecEventEmitter = (type: string, data: Record<string, unknown>) => void;
+/**
+ * A stateful parse of one turn's streamed output. Codecs are stateful while
+ * a turn streams, so the interpreter starts one session per turn.
+ * @public
+ */
+export interface OutputCodecSession<O = unknown> {
+    /**
+     * Fed each assistant text delta in stream order. Declared as a method
+     * (bivariant params) so concrete sessions assign to the erased form.
+     */
+    push(delta: string, emit: OutputCodecEventEmitter): void;
+    /**
+     * Called once at turn end with the full assistant text. Returns the typed
+     * output. Throwing here surfaces through the same error path as a Zod
+     * structured-output parse failure.
+     */
+    finish(fullText: string): O;
+}
+/**
+ * A streaming output dialect for `step.llm`. Discriminated from a Zod schema
+ * in `StepLLM.output` by the `kind: 'codec'` tag.
+ * @public
+ */
+export interface OutputCodec<O = unknown> {
+    kind: 'codec';
+    /** Appended to the step's system instructions (e.g. a generated component-library prompt). */
+    instructions?: string;
+    /** One session per turn. */
+    start(): OutputCodecSession<O>;
+}
+/**
+ * Narrows a `StepLLM.output` value to an `OutputCodec`. A Zod schema has no
+ * `kind: 'codec'` tag, so the discriminant is unambiguous.
+ * @public
+ */
+export declare function isOutputCodec<O>(value: unknown): value is OutputCodec<O>;

package/dist/types/output-codec.js

@@ -0,0 +1,22 @@
+/**
+ * Streaming output-dialect contracts for `step.llm`.
+ *
+ * An `OutputCodec` is the dialect-agnostic alternative to a Zod schema in
+ * `StepLLM.output`: instead of JSON-parsing the assistant text once at turn
+ * end, a codec is fed each text delta as it streams and produces a typed
+ * value when the turn finishes. OpenUI Lang is one dialect; the contract
+ * lives here — next to `MemoryLayer` and `SubHarness` — so `core` and
+ * dialect packages both depend on it without forming a cycle.
+ */
+/**
+ * Narrows a `StepLLM.output` value to an `OutputCodec`. A Zod schema has no
+ * `kind: 'codec'` tag, so the discriminant is unambiguous.
+ * @public
+ */
+export function isOutputCodec(value) {
+    if (typeof value !== 'object' || value === null || !('kind' in value) || !('start' in value)) {
+        return false;
+    }
+    const record = value;
+    return record.kind === 'codec' && typeof record.start === 'function';
+}

package/dist/types/step.d.ts

@@ -4,6 +4,7 @@ import type { ModelParams, RetryPolicy, ServerToolSpec, StepMeta } from './commo
 import type { Context } from './context.js';
 import type { NoeticError } from './error.js';
 import type { ContextMemory, MemoryConfig, MemoryLayer, ProjectionPolicy } from './memory.js';
+import type { OutputCodec } from './output-codec.js';
 import type { SubHarness, SubHarnessKind, SubHarnessSessionPolicy, SubHarnessSettings } from './sub-harness.js';
 import type { SubprocessAdapter } from './subprocess-adapter.js';
 import type { Tool } from './tool.js';
@@ -102,7 +103,12 @@ export interface StepLLM<TMemory = ContextMemory, _I = unknown, O = unknown> {
      * they are resolved per execution.
      */
     tools?: Lazy<(Tool | ServerToolSpec)[] | undefined, TMemory>;
-    output?: ZodType<O>;
+    /**
+     * Structured output: a Zod schema (assistant text is JSON-parsed and
+     * validated) or a streaming `OutputCodec` (fed each text delta, produces
+     * the typed value at turn end).
+     */
+    output?: ZodType<O> | OutputCodec<O>;
     params?: ModelParams;
     /** Controls framework event emission for this step. Defaults to `true`. Set `false` to suppress all framework events. A filter function receives `(eventType, data)` and returns `boolean`. */
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);

package/dist/types/tool.d.ts

@@ -18,6 +18,37 @@ export interface ToolMemoryDeclaration<TState = unknown> {
      */
     recall(state: TState): string | null;
 }
+/**
+ * A renderable UI fragment in a named dialect (e.g. `'openui-lang/0.5'`).
+ * The framework never interprets `source` — it forwards fragments as
+ * `openui.fragment` framework events and attaches them to items; a UI
+ * surface (memory layer + transport) composes and renders them.
+ * @public
+ */
+export interface UiFragment {
+    /** Dialect identifier, e.g. `'openui-lang/0.5'`. */
+    dialect: string;
+    /** Fragment source in that dialect, e.g. `'root = Card([Spinner()])'`. */
+    source: string;
+}
+/**
+ * Declares tool-owned UI: programmatic render functions invoked at tool
+ * lifecycle points. All methods are optional — an omitted point renders
+ * nothing (mirrors `ToolMemoryDeclaration`). Declared as methods (bivariant
+ * params) so a concretely-typed declaration assigns to the erased form the
+ * `tool()` builder and runtime consume.
+ * @public
+ */
+export interface ToolUiDeclaration<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny = ZodTypeAny, E = unknown> {
+    /** Rendered as soon as the call streams in — args may be partial. */
+    call?(args: Partial<z.infer<I>>): UiFragment | null;
+    /** Re-rendered on each event an AsyncGenerator `execute` yields. Receives all events so far. */
+    progress?(events: E[]): UiFragment | null;
+    /** Replaces the tool's region on successful completion. */
+    result?(output: z.infer<O>, args: z.infer<I>): UiFragment | null;
+    /** Replaces the tool's region when execution throws. */
+    error?(err: unknown, args: z.infer<I>): UiFragment | null;
+}
 /**
  * A tool definition that an LLM can invoke during execution.
  *
@@ -60,5 +91,7 @@ export interface Tool<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny =
     needsApproval?: boolean;
     /** Optional memory declaration — the runtime generates a MemoryLayer from this. */
     memory?: ToolMemoryDeclaration;
+    /** Optional UI declaration — the runtime emits the rendered fragments at call/progress/result points. */
+    ui?: ToolUiDeclaration<I, O>;
 }
 export {};

package/package.json

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