@agentick/core 0.0.1

package/dist/hooks/index.js

@@ -0,0 +1,47 @@
+/**
+ * V2 Hooks
+ *
+ * Custom hooks for Agentick components.
+ */
+// Re-export React hooks for convenience
+export { useState, useEffect, useRef, useCallback, useMemo, useContext } from "react";
+// Context hooks
+export { useCom, useTickState, COMProvider, TickStateProvider, AgentickProvider } from "./context";
+// COM state hook
+export { useComState } from "./com-state";
+// Runtime context (per-session state)
+export { createRuntimeStore, useRuntimeStore, RuntimeProvider, storeHasPendingData, storeResolvePendingData, storeRunTickStartCallbacks, storeRunTickEndCallbacks, storeRunAfterCompileCallbacks, storeClearLifecycleCallbacks, storeClearDataCache, storeGetSerializableDataCache, storeSetDataCache, storeInvalidateData, } from "./runtime-context";
+// Knobs
+export { knob, isKnob, useKnob, } from "./knob";
+export { Knobs, useKnobsContext, useKnobsContextOptional, } from "./knobs-component";
+// Lifecycle hooks
+export { useOnMount, useOnUnmount, useOnTickStart, useOnTickEnd, useAfterCompile, useContinuation, } from "./lifecycle";
+// Data hook
+export { useData, useInvalidateData } from "./data";
+// Signal hooks and utilities
+export { 
+// React hooks
+useSignal, useComputed, 
+// Standalone signal functions
+signal, computed, effect, createSignal, 
+// Batching and utilities
+batch, untracked, 
+// Type guards
+isSignal, isComputed, isEffect, 
+// COM state integration
+createCOMStateSignal, createReadonlyCOMStateSignal, 
+// Context utilities
+runWithSignalContext, runWithSignalContextAsync, 
+// Symbols (for advanced use)
+SIGNAL_SYMBOL, COMPUTED_SYMBOL, EFFECT_SYMBOL, COM_SIGNAL_SYMBOL, WATCH_SIGNAL_SYMBOL, PROPS_SIGNAL_SYMBOL, REQUIRED_INPUT_SYMBOL, } from "./signal";
+// Formatter context
+export { FormatterBoundary, useFormatter } from "./formatter-context";
+// Message context
+export { createMessageStore, MessageProvider, useMessageContext, useOnMessage, useQueuedMessages, useLastMessage, } from "./message-context";
+// Timeline hooks (re-exported from jsx/components/timeline for convenience)
+export { useTimelineContext, useTimelineContextOptional, useConversationHistory, } from "../jsx/components/timeline";
+// Context info hook (real-time context utilization)
+export { useContextInfo, useContextInfoStore, createContextInfoStore, ContextInfoProvider, } from "./context-info";
+// Types
+export * from "./types";
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wCAAwC;AACxC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAEtF,gBAAgB;AAChB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAEnG,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,sCAAsC;AACtC,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,0BAA0B,EAC1B,wBAAwB,EACxB,6BAA6B,EAC7B,4BAA4B,EAC5B,mBAAmB,EACnB,6BAA6B,EAC7B,iBAAiB,EACjB,mBAAmB,GAKpB,MAAM,mBAAmB,CAAC;AAE3B,QAAQ;AACR,OAAO,EACL,IAAI,EACJ,MAAM,EACN,OAAO,GAKR,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,KAAK,EACL,eAAe,EACf,uBAAuB,GAKxB,MAAM,mBAAmB,CAAC;AAE3B,kBAAkB;AAClB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,YAAY;AACZ,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAEpD,6BAA6B;AAC7B,OAAO;AACL,cAAc;AACd,SAAS,EACT,WAAW;AACX,8BAA8B;AAC9B,MAAM,EACN,QAAQ,EACR,MAAM,EACN,YAAY;AACZ,yBAAyB;AACzB,KAAK,EACL,SAAS;AACT,cAAc;AACd,QAAQ,EACR,UAAU,EACV,QAAQ;AACR,wBAAwB;AACxB,oBAAoB,EACpB,4BAA4B;AAC5B,oBAAoB;AACpB,oBAAoB,EACpB,yBAAyB;AACzB,6BAA6B;AAC7B,aAAa,EACb,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GAOtB,MAAM,UAAU,CAAC;AAElB,oBAAoB;AACpB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAA8B,MAAM,qBAAqB,CAAC;AAElG,kBAAkB;AAClB,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,cAAc,GAIf,MAAM,mBAAmB,CAAC;AAE3B,4EAA4E;AAC5E,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AAEpC,oDAAoD;AACpD,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,GAGpB,MAAM,gBAAgB,CAAC;AAExB,QAAQ;AACR,cAAc,SAAS,CAAC"}

package/dist/hooks/knob.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Knob — model-visible, model-settable reactive state.
+ *
+ * Three pieces:
+ * 1. `knob()` — descriptor factory for config-level declaration
+ * 2. `useKnob()` — hook returning [value, setter] tuple + registers in knobRegistry
+ * 3. `isKnob()` — type guard for detecting KnobDescriptor values
+ *
+ * Knobs present primitive values (string, number, boolean) to the model.
+ * An optional resolve callback maps the primitive to a rich application value.
+ *
+ * Constraints are type-safe: number knobs accept min/max/step,
+ * string knobs accept maxLength/pattern. Boolean knobs have no constraints.
+ */
+declare const KNOB_SYMBOL: unique symbol;
+export type KnobPrimitive = string | number | boolean;
+/**
+ * Type-safe constraints based on value type.
+ * Numbers get min/max/step. Strings get maxLength/pattern.
+ */
+export type KnobConstraints<T extends KnobPrimitive> = T extends number ? {
+    min?: number;
+    max?: number;
+    step?: number;
+} : T extends string ? {
+    maxLength?: number;
+    pattern?: string;
+} : {};
+/**
+ * Options for knob() and useKnob(). Type-safe constraints based on value type.
+ */
+export type KnobOpts<T extends KnobPrimitive> = KnobConstraints<T> & {
+    description: string;
+    options?: T[];
+    group?: string;
+    required?: boolean;
+    validate?: (value: T) => true | string;
+};
+/**
+ * Descriptor carrying a knob's default value, constraints, and optional resolver.
+ * Created by knob(), consumed by useKnob() and <Knobs />.
+ *
+ * Stores the superset of all constraint fields (the user-facing KnobOpts<T>
+ * provides compile-time safety; the descriptor is a runtime carrier).
+ */
+export interface KnobDescriptor<T extends KnobPrimitive = KnobPrimitive, R = T> {
+    [KNOB_SYMBOL]: true;
+    defaultValue: T;
+    description: string;
+    options?: T[];
+    valueType: "string" | "number" | "boolean";
+    resolve?: (value: T) => R;
+    group?: string;
+    required?: boolean;
+    validate?: (value: T) => true | string;
+    min?: number;
+    max?: number;
+    step?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+/**
+ * Create a knob descriptor (no resolver — primitive IS the value).
+ */
+export declare function knob<T extends KnobPrimitive>(defaultValue: T, opts: KnobOpts<T>): KnobDescriptor<T, T>;
+/**
+ * Create a knob descriptor with a resolver (primitive → rich value).
+ */
+export declare function knob<T extends KnobPrimitive, R>(defaultValue: T, opts: KnobOpts<T>, resolve: (value: T) => R): KnobDescriptor<T, R>;
+/**
+ * Check if a value is a KnobDescriptor.
+ */
+export declare function isKnob(value: unknown): value is KnobDescriptor;
+/**
+ * Create a knob (no resolver). Returns [value, setter].
+ */
+export declare function useKnob<T extends KnobPrimitive>(name: string, defaultValue: T, opts: KnobOpts<T>): [T, (value: T) => void];
+/**
+ * Create a knob with a resolver. Returns [resolvedValue, primitiveSetter].
+ */
+export declare function useKnob<T extends KnobPrimitive, R>(name: string, defaultValue: T, opts: KnobOpts<T>, resolve: (value: T) => R): [R, (value: T) => void];
+/**
+ * Create a knob from a KnobDescriptor. Returns [resolvedValue, primitiveSetter].
+ */
+export declare function useKnob<T extends KnobPrimitive, R>(name: string, descriptor: KnobDescriptor<T, R>): [R, (value: T) => void];
+export {};
+//# sourceMappingURL=knob.d.ts.map

package/dist/hooks/knob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knob.d.ts","sourceRoot":"","sources":["../../src/hooks/knob.ts"],"names":[],"mappings":"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"}

package/dist/hooks/knob.js

@@ -0,0 +1,129 @@
+/**
+ * Knob — model-visible, model-settable reactive state.
+ *
+ * Three pieces:
+ * 1. `knob()` — descriptor factory for config-level declaration
+ * 2. `useKnob()` — hook returning [value, setter] tuple + registers in knobRegistry
+ * 3. `isKnob()` — type guard for detecting KnobDescriptor values
+ *
+ * Knobs present primitive values (string, number, boolean) to the model.
+ * An optional resolve callback maps the primitive to a rich application value.
+ *
+ * Constraints are type-safe: number knobs accept min/max/step,
+ * string knobs accept maxLength/pattern. Boolean knobs have no constraints.
+ */
+import { useEffect, useMemo } from "react";
+import { useRuntimeStore } from "./runtime-context";
+import { useComState } from "./com-state";
+// ============================================================================
+// Types — Primitives, Constraints, Options
+// ============================================================================
+const KNOB_SYMBOL = Symbol.for("agentick.knob");
+export function knob(defaultValue, opts, resolve) {
+    return {
+        [KNOB_SYMBOL]: true,
+        defaultValue,
+        description: opts.description,
+        options: opts.options,
+        valueType: typeof defaultValue,
+        resolve,
+        group: opts.group,
+        required: opts.required,
+        validate: opts.validate,
+        min: opts.min,
+        max: opts.max,
+        step: opts.step,
+        maxLength: opts.maxLength,
+        pattern: opts.pattern,
+    };
+}
+/**
+ * Check if a value is a KnobDescriptor.
+ */
+export function isKnob(value) {
+    return typeof value === "object" && value !== null && KNOB_SYMBOL in value;
+}
+export function useKnob(name, defaultOrDescriptor, optsOrUndefined, maybeResolve) {
+    // Normalize arguments — extract all fields from descriptor or opts
+    let defaultValue;
+    let description;
+    let options;
+    let valueType;
+    let resolve;
+    let group;
+    let required;
+    let validate;
+    let min;
+    let max;
+    let step;
+    let maxLength;
+    let pattern;
+    if (isKnob(defaultOrDescriptor)) {
+        defaultValue = defaultOrDescriptor.defaultValue;
+        description = defaultOrDescriptor.description;
+        options = defaultOrDescriptor.options;
+        valueType = defaultOrDescriptor.valueType;
+        resolve = defaultOrDescriptor.resolve;
+        group = defaultOrDescriptor.group;
+        required = defaultOrDescriptor.required;
+        validate = defaultOrDescriptor.validate;
+        min = defaultOrDescriptor.min;
+        max = defaultOrDescriptor.max;
+        step = defaultOrDescriptor.step;
+        maxLength = defaultOrDescriptor.maxLength;
+        pattern = defaultOrDescriptor.pattern;
+    }
+    else {
+        defaultValue = defaultOrDescriptor;
+        const opts = optsOrUndefined;
+        description = opts.description;
+        options = opts.options;
+        valueType = typeof defaultValue;
+        resolve = maybeResolve;
+        group = opts.group;
+        required = opts.required;
+        validate = opts.validate;
+        min = opts.min;
+        max = opts.max;
+        step = opts.step;
+        maxLength = opts.maxLength;
+        pattern = opts.pattern;
+    }
+    const store = useRuntimeStore();
+    const comKey = `knob:${name}`;
+    // COM-persisted state with automatic re-render on external changes
+    const primitiveSignal = useComState(comKey, defaultValue);
+    // Register in knobRegistry eagerly so <Knobs /> sees it on the same render pass.
+    // NOTE: Intentional render-time side effect — safe because Agentick's reconciler
+    // is synchronous/single-pass. Would not be safe in concurrent React.
+    useMemo(() => {
+        store.knobRegistry.set(name, {
+            name,
+            description,
+            getPrimitive: () => primitiveSignal(),
+            setPrimitive: (v) => primitiveSignal.set(v),
+            defaultValue,
+            options,
+            valueType,
+            group,
+            required,
+            validate,
+            min,
+            max,
+            step,
+            maxLength,
+            pattern,
+        });
+    }, [name]);
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            store.knobRegistry.delete(name);
+        };
+    }, [name, store]);
+    // Current value — resolved if callback provided, primitive otherwise
+    const primitive = primitiveSignal();
+    const value = resolve ? resolve(primitive) : primitive;
+    return [value, (v) => primitiveSignal.set(v)];
+}
+//# sourceMappingURL=knob.js.map

package/dist/hooks/knob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knob.js","sourceRoot":"","sources":["../../src/hooks/knob.ts"],"names":[],"mappings":"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"}

package/dist/hooks/knobs-component.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Knobs — provider pattern for model-visible knob state.
+ *
+ * Three modes:
+ * 1. `<Knobs />`               — default rendering (tool + section)
+ * 2. `<Knobs>{(groups) => …}</Knobs>` — render prop for custom section
+ * 3. `<Knobs.Provider>` + `useKnobsContext()` — full custom rendering
+ *
+ * The set_knob tool is always registered automatically in all three modes.
+ */
+import React, { type ReactNode } from "react";
+/** Read-only snapshot of a knob for rendering. */
+export interface KnobInfo {
+    name: string;
+    description: string;
+    value: string | number | boolean;
+    defaultValue: string | number | boolean;
+    semanticType: "toggle" | "range" | "number" | "select" | "text";
+    valueType: "string" | "number" | "boolean";
+    group?: string;
+    options?: (string | number | boolean)[];
+    min?: number;
+    max?: number;
+    step?: number;
+    maxLength?: number;
+    pattern?: string;
+    required?: boolean;
+}
+export interface KnobGroup {
+    name: string;
+    knobs: KnobInfo[];
+}
+export interface KnobsContextValue {
+    knobs: KnobInfo[];
+    groups: KnobGroup[];
+    get: (name: string) => KnobInfo | undefined;
+}
+export type KnobsRenderFn = (groups: KnobGroup[]) => React.ReactElement | null;
+export interface KnobsProps {
+    children?: KnobsRenderFn;
+}
+/**
+ * Renders the set_knob tool + knob section when knobs are registered.
+ *
+ * Three modes:
+ * - `<Knobs />` — default section rendering
+ * - `<Knobs>{(groups) => <section>…</section>}</Knobs>` — custom section via render prop
+ * - Use `<Knobs.Provider>` + `<Knobs.Controls />` for full custom rendering
+ */
+export declare function Knobs(props: KnobsProps): React.ReactElement | null;
+export declare namespace Knobs {
+    var Provider: ({ children }: {
+        children: ReactNode;
+    }) => React.ReactElement;
+    var Controls: (props: KnobsControlsProps) => React.ReactElement;
+}
+interface KnobsControlsProps {
+    renderKnob?: (knob: KnobInfo) => React.ReactElement | null;
+    renderGroup?: (group: KnobGroup) => React.ReactElement | null;
+}
+/**
+ * Access knob context from within Knobs.Provider. Throws if not in provider.
+ */
+export declare function useKnobsContext(): KnobsContextValue;
+/**
+ * Access knob context, returning null if not within provider.
+ */
+export declare function useKnobsContextOptional(): KnobsContextValue | null;
+export {};
+//# sourceMappingURL=knobs-component.d.ts.map

package/dist/hooks/knobs-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knobs-component.d.ts","sourceRoot":"","sources":["../../src/hooks/knobs-component.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAgBzE,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACjC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACxC,YAAY,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IAChE,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;AAE/E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AA0ND;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAyBlE;yBAzBe,KAAK;iCA0CiC;QAAE,QAAQ,EAAE,SAAS,CAAA;KAAE,KAAG,KAAK,CAAC,YAAY;0BA2CnD,kBAAkB,KAAG,KAAK,CAAC,YAAY;;AAZtF,UAAU,kBAAkB;IAC1B,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;IAC3D,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;CAC/D;AA6BD;;GAEG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,CAMnD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,GAAG,IAAI,CAElE"}

package/dist/hooks/knobs-component.js

@@ -0,0 +1,300 @@
+/**
+ * Knobs — provider pattern for model-visible knob state.
+ *
+ * Three modes:
+ * 1. `<Knobs />`               — default rendering (tool + section)
+ * 2. `<Knobs>{(groups) => …}</Knobs>` — render prop for custom section
+ * 3. `<Knobs.Provider>` + `useKnobsContext()` — full custom rendering
+ *
+ * The set_knob tool is always registered automatically in all three modes.
+ */
+import React, { createContext, useContext } from "react";
+import { z } from "zod";
+import { useRuntimeStore } from "./runtime-context";
+import { useCom } from "./context";
+import { createTool } from "../tool/tool";
+const h = React.createElement;
+/** COM state key where the knob registry is stashed for the tool handler. */
+const KNOB_REGISTRY_KEY = "__knobRegistry";
+// ============================================================================
+// React Context
+// ============================================================================
+const KnobsContext = createContext(null);
+// ============================================================================
+// Semantic Type Inference
+// ============================================================================
+function inferSemanticType(knob) {
+    if (knob.valueType === "boolean")
+        return "toggle";
+    if (knob.valueType === "number" && (knob.min !== undefined || knob.max !== undefined))
+        return "range";
+    if (knob.valueType === "number")
+        return "number";
+    if (knob.valueType === "string" && knob.options?.length)
+        return "select";
+    return "text";
+}
+// ============================================================================
+// KnobInfo / KnobGroup Builders
+// ============================================================================
+function buildKnobInfo(reg) {
+    return {
+        name: reg.name,
+        description: reg.description,
+        value: reg.getPrimitive(),
+        defaultValue: reg.defaultValue,
+        semanticType: inferSemanticType(reg),
+        valueType: reg.valueType,
+        group: reg.group,
+        options: reg.options,
+        min: reg.min,
+        max: reg.max,
+        step: reg.step,
+        maxLength: reg.maxLength,
+        pattern: reg.pattern,
+        required: reg.required,
+    };
+}
+function buildGroups(knobs) {
+    const ungrouped = [];
+    const grouped = new Map();
+    for (const [, reg] of knobs) {
+        const info = buildKnobInfo(reg);
+        if (reg.group) {
+            const list = grouped.get(reg.group) ?? [];
+            list.push(info);
+            grouped.set(reg.group, list);
+        }
+        else {
+            ungrouped.push(info);
+        }
+    }
+    const result = [];
+    if (ungrouped.length > 0) {
+        result.push({ name: "", knobs: ungrouped });
+    }
+    for (const [name, knobs] of grouped) {
+        result.push({ name, knobs });
+    }
+    return result;
+}
+// ============================================================================
+// Formatting
+// ============================================================================
+function formatValue(value) {
+    return typeof value === "string" ? `"${value}"` : String(value);
+}
+function formatKnobLine(knob) {
+    const parts = [
+        `${knob.name} [${knob.semanticType}]: ${formatValue(knob.value)} — ${knob.description}`,
+    ];
+    const hints = [];
+    if (knob.options?.length) {
+        hints.push(`options: ${knob.options.map(formatValue).join(", ")}`);
+    }
+    if (knob.min !== undefined || knob.max !== undefined) {
+        const range = `${knob.min ?? "*"} - ${knob.max ?? "*"}`;
+        hints.push(range);
+    }
+    if (knob.step !== undefined)
+        hints.push(`step ${knob.step}`);
+    if (knob.maxLength !== undefined)
+        hints.push(`max ${knob.maxLength} chars`);
+    if (knob.pattern !== undefined)
+        hints.push(`pattern: ${knob.pattern}`);
+    if (knob.required)
+        hints.push("required");
+    if (hints.length > 0) {
+        parts.push(` (${hints.join(", ")})`);
+    }
+    return parts.join("");
+}
+function formatKnobsForModel(groups) {
+    const lines = [
+        "Knobs are adjustable parameters you can modify using the set_knob tool.",
+        "",
+    ];
+    let firstGroup = true;
+    for (const group of groups) {
+        if (group.name === "") {
+            // Ungrouped knobs (no header)
+            for (const knob of group.knobs) {
+                lines.push(formatKnobLine(knob));
+            }
+        }
+        else {
+            if (!firstGroup || lines.length > 2)
+                lines.push("");
+            lines.push(`### ${group.name}`);
+            for (const knob of group.knobs) {
+                lines.push(formatKnobLine(knob));
+            }
+        }
+        firstGroup = false;
+    }
+    return lines.join("\n").trimEnd();
+}
+// ============================================================================
+// Validation
+// ============================================================================
+function error(text) {
+    return [{ type: "text", text }];
+}
+function executeSetKnob(knobs, input) {
+    const knob = knobs.get(input.name);
+    if (!knob) {
+        return error(`Unknown knob "${input.name}". Available: ${[...knobs.keys()].join(", ")}`);
+    }
+    // Type check
+    if (typeof input.value !== knob.valueType) {
+        return error(`Invalid type for "${input.name}". Expected ${knob.valueType}, got ${typeof input.value}.`);
+    }
+    // Options check (enum constraint)
+    if (knob.options?.length && !knob.options.some((o) => o === input.value)) {
+        const opts = knob.options.map(formatValue).join(", ");
+        return error(`Invalid value for "${input.name}". Valid options: ${opts}`);
+    }
+    // Number constraints
+    if (typeof input.value === "number") {
+        if (knob.min !== undefined && input.value < knob.min) {
+            return error(`Value for "${input.name}" must be >= ${knob.min}. Got ${input.value}.`);
+        }
+        if (knob.max !== undefined && input.value > knob.max) {
+            return error(`Value for "${input.name}" must be <= ${knob.max}. Got ${input.value}.`);
+        }
+    }
+    // String constraints
+    if (typeof input.value === "string") {
+        if (knob.maxLength !== undefined && input.value.length > knob.maxLength) {
+            return error(`Value for "${input.name}" exceeds max length of ${knob.maxLength}. Got ${input.value.length} chars.`);
+        }
+        if (knob.pattern !== undefined && !new RegExp(knob.pattern).test(input.value)) {
+            return error(`Value for "${input.name}" does not match pattern: ${knob.pattern}`);
+        }
+    }
+    // Custom validate
+    if (knob.validate) {
+        const result = knob.validate(input.value);
+        if (result !== true) {
+            return error(`Validation failed for "${input.name}": ${result}`);
+        }
+    }
+    knob.setPrimitive(input.value);
+    return [{ type: "text", text: `Set ${input.name} to ${formatValue(input.value)}.` }];
+}
+// ============================================================================
+// SetKnobTool — tool-only, no render
+// ============================================================================
+const SetKnobTool = createTool({
+    name: "set_knob",
+    description: "Set a knob value. See the knobs section for available knobs and options.",
+    input: z.object({
+        name: z.string().describe("Name of the knob to set"),
+        value: z.union([z.string(), z.number(), z.boolean()]).describe("New value for the knob"),
+    }),
+    handler: (input, ctx) => {
+        const knobs = ctx?.getState(KNOB_REGISTRY_KEY);
+        if (!knobs?.size) {
+            return [{ type: "text", text: "No knobs are currently registered." }];
+        }
+        return executeSetKnob(knobs, input);
+    },
+    // No render — tool registration only. Section rendered by Knobs/Provider.
+});
+// ============================================================================
+// <Knobs /> — default + render prop
+// ============================================================================
+/**
+ * Renders the set_knob tool + knob section when knobs are registered.
+ *
+ * Three modes:
+ * - `<Knobs />` — default section rendering
+ * - `<Knobs>{(groups) => <section>…</section>}</Knobs>` — custom section via render prop
+ * - Use `<Knobs.Provider>` + `<Knobs.Controls />` for full custom rendering
+ */
+export function Knobs(props) {
+    const store = useRuntimeStore();
+    const ctx = useCom();
+    if (store.knobRegistry.size === 0) {
+        return null;
+    }
+    // Stash registry on COM so the tool handler can access it via ctx.getState().
+    ctx.setState(KNOB_REGISTRY_KEY, store.knobRegistry);
+    const groups = buildGroups(store.knobRegistry);
+    if (typeof props.children === "function") {
+        // Render prop: tool + custom content
+        return h(React.Fragment, null, h(SetKnobTool), props.children(groups));
+    }
+    // Default: tool + default section
+    return h(React.Fragment, null, h(SetKnobTool), h("section", { id: "knobs", audience: "model" }, formatKnobsForModel(groups)));
+}
+// ============================================================================
+// <Knobs.Provider>
+// ============================================================================
+/**
+ * Provider that exposes knob context to descendants.
+ * Always registers the set_knob tool.
+ *
+ * @example
+ * ```tsx
+ * <Knobs.Provider>
+ *   <Knobs.Controls />
+ * </Knobs.Provider>
+ * ```
+ */
+Knobs.Provider = function KnobsProvider({ children }) {
+    const store = useRuntimeStore();
+    const ctx = useCom();
+    if (store.knobRegistry.size === 0) {
+        return h(React.Fragment, null, children);
+    }
+    ctx.setState(KNOB_REGISTRY_KEY, store.knobRegistry);
+    const groups = buildGroups(store.knobRegistry);
+    const knobs = groups.flatMap((g) => g.knobs);
+    const contextValue = {
+        knobs,
+        groups,
+        get: (name) => knobs.find((k) => k.name === name),
+    };
+    return h(React.Fragment, null, h(SetKnobTool), h(KnobsContext.Provider, { value: contextValue }, children));
+};
+/**
+ * Renders knob content from Knobs.Provider context.
+ *
+ * - No props: default section rendering
+ * - `renderKnob`: custom per-knob rendering
+ * - `renderGroup`: custom per-group rendering
+ */
+Knobs.Controls = function KnobsControls(props) {
+    const context = useContext(KnobsContext);
+    if (!context)
+        return h(React.Fragment, null);
+    if (props.renderGroup) {
+        return h(React.Fragment, null, ...context.groups.map((g) => props.renderGroup(g)));
+    }
+    if (props.renderKnob) {
+        return h(React.Fragment, null, ...context.knobs.map((k) => props.renderKnob(k)));
+    }
+    // Default rendering from context
+    return h("section", { id: "knobs", audience: "model" }, formatKnobsForModel(context.groups));
+};
+// ============================================================================
+// Hooks
+// ============================================================================
+/**
+ * Access knob context from within Knobs.Provider. Throws if not in provider.
+ */
+export function useKnobsContext() {
+    const context = useContext(KnobsContext);
+    if (!context) {
+        throw new Error("useKnobsContext must be used within a Knobs.Provider");
+    }
+    return context;
+}
+/**
+ * Access knob context, returning null if not within provider.
+ */
+export function useKnobsContextOptional() {
+    return useContext(KnobsContext);
+}
+//# sourceMappingURL=knobs-component.js.map