@noetic-tools/types 1.1.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/common.d.ts

@@ -13,6 +13,28 @@ export interface RetryPolicy {
     /** Upper bound in ms for the computed delay (caps exponential/linear growth). */
     maxDelay?: number;
 }
+/**
+ * Declares an OpenRouter server-executed tool on an LLM step. OpenRouter runs
+ * the tool (web search, web fetch) provider-side and returns the result item in
+ * the response — no client-side execute function is involved.
+ *
+ * `parameters` keys are camelCase (e.g. `maxResults`, `searchContextSize`); the
+ * SDK re-serialises them to the wire format and silently drops unknown keys.
+ * @public
+ */
+export interface ServerToolSpec {
+    /** Server tool discriminator. */
+    type: 'openrouter:web_search' | 'openrouter:web_fetch';
+    /** Optional provider config forwarded to the tool (camelCase keys). */
+    parameters?: Record<string, unknown>;
+}
+/**
+ * Distinguishes an inline `ServerToolSpec` from a client `Tool` in a
+ * heterogeneous `tools` list. A server-tool spec carries a server-tool `type`
+ * discriminator and, unlike a `Tool`, has no `execute` method.
+ * @public
+ */
+export declare function isServerToolSpec(value: unknown): value is ServerToolSpec;
 /**
  * Optional parameters forwarded to the model provider during an LLM step.
  * @public

package/dist/types/common.js

@@ -1 +1,19 @@
-export {};
+/**
+ * Distinguishes an inline `ServerToolSpec` from a client `Tool` in a
+ * heterogeneous `tools` list. A server-tool spec carries a server-tool `type`
+ * discriminator and, unlike a `Tool`, has no `execute` method.
+ * @public
+ */
+export function isServerToolSpec(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if ('execute' in value) {
+        return false;
+    }
+    if (!('type' in value)) {
+        return false;
+    }
+    const { type } = value;
+    return type === 'openrouter:web_search' || type === 'openrouter:web_fetch';
+}

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

@@ -1,6 +1,6 @@
 import type { ZodType } from 'zod';
 import type { Channel, ChannelHandle, ExternalChannel } from './channel.js';
-import type { LLMResponse, ModelParams } from './common.js';
+import type { LLMResponse, ModelParams, ServerToolSpec } from './common.js';
 import type { Context, CwdState } from './context.js';
 import type { DetachedHandle } from './detached.js';
 import type { FsAdapter } from './fs-adapter.js';
@@ -54,6 +54,16 @@ interface CallModelRequestBase {
     outputSchema?: ZodType;
     /** Controls framework event emission. Defaults to `true`. Passed through from `StepLLM.emit`. */
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+    /**
+     * @internal
+     * Framework-internal carrier for OpenRouter server tools (web search/fetch).
+     * Server tools are an authoring concept inside `StepLLM.tools` — the
+     * interpreter partitions those entries out of the client `tools` list and
+     * stamps the specs here so the model caller can wrap them via the SDK's
+     * `serverTool()` and append them to the SDK tools array. NOT an authored
+     * field: public callers declare server tools as `tools` entries, never here.
+     */
+    _serverTools?: ServerToolSpec[];
     /** Optional signal for cancelling the in-flight call (used by session abort). */
     signal?: AbortSignal;
     /**

package/dist/types/step.d.ts

@@ -1,9 +1,10 @@
 import type { ZodType } from 'zod';
 import type { Channel } from './channel.js';
-import type { ModelParams, RetryPolicy, StepMeta } from './common.js';
+import type { ModelParams, RetryPolicy, ServerToolSpec, 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 { 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';
@@ -94,9 +95,20 @@ export interface StepLLM<TMemory = ContextMemory, _I = unknown, O = unknown> {
     model: Lazy<string, TMemory>;
     /** System instructions. Eager string or `(ctx) => string | undefined` getter. */
     instructions?: Lazy<string | undefined, TMemory>;
-    /** Tools exposed to the LLM. Eager array or `(ctx) => Tool[] | undefined` getter. Function-form tools do not contribute to the pre-computed `ctx.unifiedTools`; they are resolved per execution. */
-    tools?: Lazy<Tool[] | undefined, TMemory>;
-    output?: ZodType<O>;
+    /**
+     * Tools exposed to the LLM. Eager array or `(ctx) => (...)[] | undefined` getter.
+     * Entries are either a client `Tool` or an inline `ServerToolSpec` (an
+     * OpenRouter server tool the provider executes, e.g. web search/fetch).
+     * Function-form tools do not contribute to the pre-computed `ctx.unifiedTools`;
+     * they are resolved per execution.
+     */
+    tools?: Lazy<(Tool | ServerToolSpec)[] | undefined, TMemory>;
+    /**
+     * 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.1.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",