llmz 0.1.4 → 0.2.0

package/dist/index.d.ts

@@ -4,11 +4,11 @@ export { Exit, ExitResult } from './exit.js';
 export { ObjectInstance } from './objects.js';
 export { SnapshotSignal, ThinkSignal, LoopExceededError } from './errors.js';
 export { parseExit, type ParsedExit } from './exit-parser.js';
-export { Component, RenderedComponent, LeafComponentDefinition, ContainerComponentDefinition, DefaultComponentDefinition, ComponentDefinition, assertValidComponent, isComponent, isAnyComponent, renderToTsx, } from './component.js';
+export { Component, RenderedComponent, LeafComponentDefinition, ContainerComponentDefinition, DefaultComponentDefinition, ComponentDefinition, assertValidComponent, isComponent, isAnyComponent, } from './component.js';
 export { Citation, CitationsManager } from './citations.js';
 export { DefaultComponents } from './component.default.js';
 export { Snapshot } from './snapshots.js';
-export { Chat, type MessageHandler } from './chat.js';
+export { Chat, type MessageHandler, type MessageDelta, type MessageDeltaHandler } from './chat.js';
 import { ExecutionResult } from './result.js';
 import { type ExecutionProps } from './runtime/types.js';
 import { truncateWrappedContent, wrapContent } from './truncator.js';
@@ -16,15 +16,18 @@ export { Transcript } from './transcript.js';
 export { ErrorExecutionResult, ExecutionResult, PartialExecutionResult, SuccessExecutionResult } from './result.js';
 export { type Trace, type Traces } from './types.js';
 export { type Iteration, ListenExit, ThinkExit, DefaultExit, IterationStatuses, IterationStatus } from './context.js';
-export { type Context } from './context.js';
-export type { LLMzPrompts } from './prompts/prompt.js';
+export { type Context, type TokenUsage, type ContextTokens } from './context.js';
+export type { LLMzPrompts, ParsedSend, ParsedNext, ParsedAssistantResponse } from './prompts/prompt.js';
+export type { ExecutionProps, ExecutionHooks } from './runtime/types.js';
 export { type ValueOrGetter, getValue } from './getter.js';
+export * from './message-stream/index.js';
 export * from './custom-client.js';
 export declare const utils: {
     toValidObjectName: (str: string) => string;
     toValidFunctionName: (str: string) => string;
     wrapContent: typeof wrapContent;
     truncateWrappedContent: typeof truncateWrappedContent;
+    stripTruncationTags: (content: string) => string;
 };
 /**
  * Executes an LLMz agent in either Chat Mode or Worker Mode.
@@ -45,7 +48,7 @@ export declare const utils: {
  * @param props.model - Optional model name (or array or models to use as fallback) (static or dynamic function)
  * @param props.temperature - Optional temperature value (static or dynamic function)
  * @param props.metadata - Optional metadata attached to cognitive usage records for each LLM call
- * @param props.options - Optional execution options (loop limit, timeout)
+ * @param props.options - Optional execution options (loop limit, timeout, maxTokens context cap)
  * @param props.onTrace - Optional non-blocking hook for monitoring traces during execution
  * @param props.onIterationEnd - Optional blocking hook called after each iteration
  * @param props.onExit - Optional blocking hook called when an exit is reached (can prevent exit)

package/dist/index.js

@@ -10,8 +10,14 @@ import {
   _CustomModelClient,
   getValue,
   parseExit
-} from "./chunk-TIZWOIDF.js";
-import "./chunk-2O3UTPVH.js";
+} from "./chunk-33AB6SVX.js";
+import {
+  MARKER,
+  NAME_REGEX,
+  StreamingMessageParser,
+  generateInstructions,
+  tryParseJson
+} from "./chunk-E5NHK3FS.js";
 import {
   Tool
 } from "./chunk-IRCB4FRM.js";
@@ -33,18 +39,20 @@ import {
   Component,
   assertValidComponent,
   isAnyComponent,
-  isComponent,
-  renderToTsx
-} from "./chunk-3T5IU7OU.js";
+  isComponent
+} from "./chunk-KWQTYXAT.js";
 import "./chunk-XTEHT2TK.js";
 import {
+  stripTruncationTags,
   truncateWrappedContent,
   wrapContent
-} from "./chunk-L74UZONX.js";
+} from "./chunk-HM5H556L.js";
 import {
   escapeString,
   getMultilineComment,
+  isJsonSchema,
   isValidIdentifier,
+  isZuiSchema,
   toValidFunctionName,
   toValidObjectName
 } from "./chunk-YX27XM67.js";
@@ -54,7 +62,7 @@ import {
 } from "./chunk-34GJUS6U.js";
 
 // package.json
-var version = "0.1.4";
+var version = "0.2.0";
 
 // src/objects.ts
 import { z } from "@bpinternal/zui";
@@ -964,7 +972,7 @@ var Text = new Component({
   type: "default",
   name: "Message",
   aliases: ["Text", "Markdown"],
-  description: "Markdown-formatted text that appears directly inside components like <Message>.",
+  description: "A Markdown-formatted text message.",
   examples: [
     {
       name: "Basic Markdown",
@@ -993,6 +1001,7 @@ var DefaultComponents = {
 // src/chat.ts
 var Chat = class {
   handler;
+  onMessageDelta;
   transcript;
   components;
   /**
@@ -1045,6 +1054,7 @@ var Chat = class {
    */
   constructor(props) {
     this.handler = props.handler;
+    this.onMessageDelta = props.onMessageDelta;
     this.components = props.components;
     this.transcript = props.transcript || [];
   }
@@ -1108,33 +1118,481 @@ var Chat = class {
   }
 };
 
+// src/message-stream/replayable.ts
+var ReplayableAsyncIterable = class {
+  _source;
+  _chunks = [];
+  _done = false;
+  _failed = false;
+  _error;
+  _lock = Promise.resolve();
+  constructor(source) {
+    this._source = source[Symbol.asyncIterator]();
+  }
+  /** True once the underlying source has been fully consumed (or has failed). */
+  get done() {
+    return this._done;
+  }
+  /** The chunks pulled from the source so far. */
+  get chunks() {
+    return [...this._chunks];
+  }
+  async *[Symbol.asyncIterator]() {
+    let index = 0;
+    while (true) {
+      if (index < this._chunks.length) {
+        yield this._chunks[index++];
+      } else if (this._failed) {
+        throw this._error;
+      } else if (this._done) {
+        return;
+      } else {
+        await this._pull();
+      }
+    }
+  }
+  /** Consumes the entire source and returns all chunks. */
+  async collect() {
+    for await (const _ of this) {
+    }
+    return this.chunks;
+  }
+  _pull() {
+    const next = this._lock.then(async () => {
+      if (this._done) {
+        return;
+      }
+      let result;
+      try {
+        result = await this._source.next();
+      } catch (thrown) {
+        this._done = true;
+        this._failed = true;
+        this._error = thrown;
+        throw thrown;
+      }
+      if (result.done) {
+        this._done = true;
+      } else {
+        this._chunks.push(result.value);
+      }
+    });
+    this._lock = next.catch(() => {
+    });
+    return next;
+  }
+};
+var collectText = async (iterable) => {
+  let text = "";
+  for await (const chunk of iterable) {
+    text += chunk;
+  }
+  return text;
+};
+
+// src/message-stream/stream.ts
+var BaseResponse = class {
+  constructor(action, item) {
+    this.action = action;
+    this.item = item;
+  }
+  get diagnostics() {
+    return this.item.diagnostics;
+  }
+};
+var SendResponse = class extends BaseResponse {
+  constructor(item, content) {
+    super("send", item);
+    this.content = content;
+  }
+  get component() {
+    return this.item.name;
+  }
+  get props() {
+    return this.item.props;
+  }
+  static formatToText(component, props, body) {
+    const header = `${MARKER}send=${component}${props && Object.keys(props).length ? ` ${JSON.stringify(props)}` : ""}`;
+    return body ? `${header}
+${body}` : header;
+  }
+};
+var RunResponse = class extends BaseResponse {
+  constructor(item, code) {
+    super("run", item);
+    this.code = code;
+  }
+  static formatToText(code) {
+    return `${MARKER}run
+${code}`;
+  }
+};
+var NextResponse = class extends BaseResponse {
+  constructor(item) {
+    super("next", item);
+  }
+  get name() {
+    return this.item.name;
+  }
+  get props() {
+    return this.item.props;
+  }
+  static formatToText(name, props) {
+    return `${MARKER}next=${name}${props && Object.keys(props).length ? ` ${JSON.stringify(props)}` : ""}`;
+  }
+};
+var EventPump = class {
+  _iterator;
+  _parser;
+  _queue = [];
+  _sourceDone = false;
+  _lock = Promise.resolve();
+  constructor(stream, parser) {
+    this._iterator = stream[Symbol.asyncIterator]();
+    this._parser = parser;
+  }
+  next() {
+    const next = this._lock.then(() => this._next());
+    this._lock = next.catch(() => {
+    });
+    return next;
+  }
+  unshift(event) {
+    this._queue.unshift(event);
+  }
+  async _next() {
+    while (this._queue.length === 0) {
+      if (this._sourceDone) {
+        return void 0;
+      }
+      let result;
+      try {
+        result = await this._iterator.next();
+      } catch {
+        this._sourceDone = true;
+        this._queue.push(...this._parser.finish("interrupted"));
+        continue;
+      }
+      if (result.done) {
+        this._sourceDone = true;
+        this._queue.push(...this._parser.finish());
+      } else {
+        this._queue.push(...this._parser.push(result.value));
+      }
+    }
+    return this._queue.shift();
+  }
+};
+function parseStream(stream, options) {
+  return parseResponses(stream, options);
+}
+function parseText(text, options) {
+  return parseResponses(
+    async function* () {
+      yield text;
+    }(),
+    options
+  );
+}
+async function* parseResponses(stream, options) {
+  const parser = new StreamingMessageParser(options);
+  const pump = new EventPump(stream, parser);
+  let activeBody;
+  while (true) {
+    if (activeBody) {
+      await activeBody.collect();
+      activeBody = void 0;
+    }
+    const event = await pump.next();
+    if (!event) {
+      return;
+    }
+    if (event.type === "item-ready" && (event.item.kind === "send" || event.item.kind === "run")) {
+      const body = new ReplayableAsyncIterable(bodyStream(pump, event.item.id));
+      activeBody = body;
+      yield event.item.kind === "send" ? new SendResponse(event.item, body) : new RunResponse(event.item, body);
+      continue;
+    }
+    if (event.type === "item-complete" && event.item.kind === "next") {
+      yield new NextResponse(event.item);
+      continue;
+    }
+  }
+}
+async function* bodyStream(pump, itemId) {
+  while (true) {
+    const event = await pump.next();
+    if (!event) {
+      return;
+    }
+    if (event.type === "body-delta" && event.itemId === itemId) {
+      yield event.delta;
+      continue;
+    }
+    if (event.type === "body-start" && event.itemId === itemId) {
+      continue;
+    }
+    if (event.type === "diagnostic") {
+      continue;
+    }
+    if (event.type === "item-complete" && event.item.id === itemId) {
+      return;
+    }
+    pump.unshift(event);
+    return;
+  }
+}
+
+// src/message-stream/registry.ts
+var ComponentRegistry = class {
+  _definitions = /* @__PURE__ */ new Map();
+  constructor(definitions = []) {
+    for (const definition of definitions) {
+      this.register(definition);
+    }
+  }
+  register(definition) {
+    if (!NAME_REGEX.test(definition.name)) {
+      throw new Error(
+        `Invalid component name "${definition.name}". Component names must be lowercase ([a-z][a-z0-9_-]*).`
+      );
+    }
+    this._definitions.set(definition.name, definition);
+  }
+  unregister(name) {
+    this._definitions.delete(name);
+  }
+  has(name) {
+    return this._definitions.has(name);
+  }
+  get(name) {
+    return this._definitions.get(name);
+  }
+  list() {
+    return [...this._definitions.values()];
+  }
+};
+
+// src/message-stream/normalizer.ts
+import { transforms } from "@bpinternal/zui";
+var EMPTY_PROPS_SCHEMA = { type: "object", properties: {}, additionalProperties: false };
+var normalizeComponentName = (name) => name.trim().toLowerCase();
+function normalizeComponentDefinition(definition) {
+  const name = normalizeComponentName(definition.name ?? "");
+  if (!NAME_REGEX.test(name)) {
+    throw new Error(
+      `Invalid component name "${definition.name}". Component names must be lowercase ([a-z][a-z0-9_-]*).`
+    );
+  }
+  return {
+    name,
+    description: definition.description,
+    propsJsonSchema: normalizePropsSchema(definition.props, name),
+    body: definition.body ? {
+      format: definition.body.type,
+      description: definition.body.description,
+      required: definition.body.required ?? false
+    } : void 0,
+    generation: definition.generation
+  };
+}
+function normalizePropsSchema(props, name) {
+  if (props === void 0) {
+    return EMPTY_PROPS_SCHEMA;
+  }
+  if (isZuiSchema(props)) {
+    try {
+      return transforms.toJSONSchema(props);
+    } catch {
+      return transforms.toJSONSchemaLegacy(props);
+    }
+  }
+  if (isJsonSchema(props)) {
+    return props;
+  }
+  throw new Error(
+    `Invalid props schema for "${name}". Expected a ZUI/Zod object schema or a JSON schema, but got type "${typeof props}".`
+  );
+}
+
+// src/message-stream/validator.ts
+function validateComponent(item, registry) {
+  const definition = registry.get(item.name);
+  if (!definition) {
+    const registered = registry.list().map((d) => d.name).join(", ") || "(none)";
+    return {
+      valid: false,
+      props: item.props,
+      errors: [
+        {
+          code: "unknown-component",
+          message: `Unknown component "${item.name}". Registered components: ${registered}`
+        }
+      ]
+    };
+  }
+  const errors = [
+    ..._validateProps(item.props, definition),
+    ..._validateBody(item, definition)
+  ];
+  return { valid: errors.length === 0, props: item.props, errors };
+}
+function validateProps(props, schema) {
+  const errors = [];
+  _checkValue(props, schema, "", errors);
+  return errors;
+}
+var _validateProps = (props, definition) => validateProps(props, definition.propsJsonSchema);
+var _validateBody = (item, definition) => {
+  var _a;
+  const hasBody = typeof item.body === "string" && item.body.length > 0;
+  if (hasBody && !definition.body) {
+    return [
+      {
+        code: "body-not-allowed",
+        message: `Component "${definition.name}" does not support a body`
+      }
+    ];
+  }
+  if (!hasBody && ((_a = definition.body) == null ? void 0 : _a.required)) {
+    return [
+      {
+        code: "missing-required-body",
+        message: `Component "${definition.name}" requires a body`
+      }
+    ];
+  }
+  return [];
+};
+var _typeOf = (value) => {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  return typeof value;
+};
+var _matchesType = (value, type) => {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number";
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "null":
+      return value === null;
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return !!value && typeof value === "object" && !Array.isArray(value);
+    default:
+      return true;
+  }
+};
+var _isEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+var _checkValue = (value, schema, path, errors) => {
+  if (schema === void 0 || typeof schema === "boolean" || typeof schema !== "object") {
+    return;
+  }
+  const label = path || "props";
+  const propError = (message) => {
+    errors.push({ code: "invalid-prop-value", message, path: path || void 0 });
+  };
+  if (schema.const !== void 0 && !_isEqual(value, schema.const)) {
+    propError(`Expected "${label}" to equal ${JSON.stringify(schema.const)}`);
+    return;
+  }
+  if (schema.enum && !schema.enum.some((allowed) => _isEqual(value, allowed))) {
+    propError(`Expected "${label}" to be one of: ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}`);
+    return;
+  }
+  const variants = schema.anyOf ?? schema.oneOf;
+  if (variants == null ? void 0 : variants.length) {
+    const matchesAny = variants.some((variant) => {
+      const variantErrors = [];
+      _checkValue(value, variant, path, variantErrors);
+      return variantErrors.length === 0;
+    });
+    if (!matchesAny) {
+      propError(`Value of "${label}" does not match any of the allowed types`);
+      return;
+    }
+  }
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((type) => _matchesType(value, type))) {
+      propError(`Expected "${label}" to be of type ${types.join(" | ")}, but got ${_typeOf(value)}`);
+      return;
+    }
+  }
+  if (Array.isArray(value) && schema.items && !Array.isArray(schema.items)) {
+    value.forEach((item, index) => _checkValue(item, schema.items, `${label}[${index}]`, errors));
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const record = value;
+    const properties = schema.properties ?? {};
+    for (const requiredKey of schema.required ?? []) {
+      if (record[requiredKey] === void 0) {
+        errors.push({
+          code: "missing-required-prop",
+          message: `Missing required prop "${path ? `${path}.` : ""}${requiredKey}"`,
+          path: path ? `${path}.${requiredKey}` : requiredKey
+        });
+      }
+    }
+    for (const [key, propValue] of Object.entries(record)) {
+      const propSchema = properties[key];
+      const propPath = path ? `${path}.${key}` : key;
+      if (propSchema === void 0) {
+        if (schema.additionalProperties === false) {
+          errors.push({
+            code: "unexpected-prop",
+            message: `Unexpected prop "${propPath}"`,
+            path: propPath
+          });
+        }
+        continue;
+      }
+      _checkValue(propValue, propSchema, propPath, errors);
+    }
+  }
+};
+
+// src/message-stream/sanitize.ts
+var sanitizeMessageText = (value, options = {}) => value.replaceAll(MARKER, options.markerReplacement ?? "\u25AA");
+
 // src/index.ts
 var utils = {
   toValidObjectName,
   toValidFunctionName,
   wrapContent,
-  truncateWrappedContent
+  truncateWrappedContent,
+  stripTruncationTags
 };
 var execute = async (props) => {
-  const { executeContext } = await import("./execute-ZENBZBWL.js");
+  const { executeContext } = await import("./execute-HIRXXR6X.js");
   return executeContext(props);
 };
 var init = async () => {
-  await import("./execute-ZENBZBWL.js");
-  await import("./component-2Z3KLWLX.js");
+  await import("./execute-HIRXXR6X.js");
+  await import("./component-ASNZHQUR.js");
   await import("./tool-DNHVW3KC.js");
   await import("./exit-VJATJTQI.js");
   await import("./jsx-DDZ63UUF.js");
-  await import("./vm-PYCKS77H.js");
+  await import("./vm-44H4UKI2.js");
   await import("./utils-ZEZ66X6Q.js");
-  await import("./truncator-3U2QUUJJ.js");
+  await import("./truncator-OZOBNYON.js");
   await import("./typings-3YV3RDMP.js");
-  await import("./dual-modes-HEXPFVUE.js");
+  await import("./dual-modes-RMF7V7ZQ.js");
 };
 export {
+  BaseResponse,
   Chat,
   CitationsManager,
   Component,
+  ComponentRegistry,
   DefaultComponents,
   DefaultExit,
   ErrorExecutionResult,
@@ -1142,23 +1600,40 @@ export {
   Exit,
   ListenExit,
   LoopExceededError,
+  MARKER,
+  NAME_REGEX,
+  NextResponse,
   ObjectInstance,
   PartialExecutionResult,
+  ReplayableAsyncIterable,
+  RunResponse,
+  SendResponse,
   Snapshot,
   SnapshotSignal,
+  StreamingMessageParser,
   SuccessExecutionResult,
   ThinkExit,
   ThinkSignal,
   Tool,
   _CustomModelClient,
   assertValidComponent,
+  collectText,
   execute,
+  generateInstructions,
   getValue,
   init,
   isAnyComponent,
   isComponent,
+  normalizeComponentDefinition,
+  normalizeComponentName,
+  normalizePropsSchema,
   parseExit,
-  renderToTsx,
+  parseStream,
+  parseText,
+  sanitizeMessageText,
+  tryParseJson,
   utils,
+  validateComponent,
+  validateProps,
   version
 };

package/dist/message-stream/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types.js';
+export { StreamingMessageParser, tryParseJson, type StreamingParserOptions } from './parser.js';
+export { BaseResponse, NextResponse, RunResponse, SendResponse, parseStream, parseText, type MessageStreamResponse, } from './stream.js';
+export { ReplayableAsyncIterable, collectText } from './replayable.js';
+export { ComponentRegistry } from './registry.js';
+export { normalizeComponentDefinition, normalizeComponentName, normalizePropsSchema, type GenerativeComponentDefinition, } from './normalizer.js';
+export { validateComponent, validateProps, type ComponentValidationError, type ComponentValidationResult, } from './validator.js';
+export { generateInstructions, type InstructionGeneratorOptions, type InstructionVerbosity } from './instructions.js';
+export { sanitizeMessageText, type SanitizeOptions } from './sanitize.js';

package/dist/message-stream/instructions.d.ts

@@ -0,0 +1,22 @@
+import { type NormalizedComponentDefinition, type NormalizedExitDefinition } from './types.js';
+export type InstructionVerbosity = 'compact' | 'standard' | 'verbose';
+export type InstructionGeneratorOptions = {
+    /** Exits available to `■next`. */
+    exits?: NormalizedExitDefinition[];
+    /** Whether the `■run` directive is available. Default: true. */
+    includeRun?: boolean;
+    /** Whether the `■send` directive is available. Default: true when at least one component is registered. */
+    includeSend?: boolean;
+    verbosity?: InstructionVerbosity;
+    /** Defaults to true, except in compact mode. */
+    includeExamples?: boolean;
+    maxExamples?: number;
+    /** Sort components by priority then name. Default: true. */
+    sortComponents?: boolean;
+};
+/**
+ * Converts registered component and exit definitions into a deterministic,
+ * model-facing protocol specification. Given the same definitions and options,
+ * the output is byte-identical — safe for prompt caching and snapshots.
+ */
+export declare function generateInstructions(components: NormalizedComponentDefinition[], options?: InstructionGeneratorOptions): string;

package/dist/message-stream/normalizer.d.ts

@@ -0,0 +1,21 @@
+import { type ZodObject } from '@bpinternal/zui';
+import { type BodyFormat, type GenerativeComponentMetadata, type JsonSchema, type NormalizedComponentDefinition } from './types.js';
+/**
+ * User-facing component definition. Props may be declared with a ZUI/Zod object
+ * schema or a plain JSON schema. Everything downstream of the normalizer
+ * (parser, validator, instruction generator) is independent of ZUI/Zod.
+ */
+export type GenerativeComponentDefinition = {
+    name: string;
+    description?: string;
+    props?: ZodObject<any> | JsonSchema;
+    body?: {
+        type: BodyFormat;
+        description?: string;
+        required?: boolean;
+    };
+    generation?: GenerativeComponentMetadata;
+};
+export declare const normalizeComponentName: (name: string) => string;
+export declare function normalizeComponentDefinition(definition: GenerativeComponentDefinition): NormalizedComponentDefinition;
+export declare function normalizePropsSchema(props: ZodObject<any> | JsonSchema | undefined, name: string): JsonSchema;