taias 0.9.2 → 0.9.3

package/dist/index.d.cts

@@ -1,399 +0,0 @@
-/**
- * Default slots for backwards compatibility.
- * Users can define custom slots by passing a type parameter.
- */
-type DefaultSlots = "primaryCta" | "secondaryCta" | "widgetVariant";
-/**
- * Alias for backwards compatibility in exports.
- * @deprecated Use DefaultSlots or define your own slot type
- */
-type CanonicalSlot = DefaultSlots;
-type Binding = {
-    key: string;
-    value: string;
-};
-/**
- * Input format for registering affordance bindings.
- * - { toolName } is shorthand for { key: "nextTool", value: toolName }
- * - { key, value } is the generalized form for custom bindings
- */
-type BindingInput = {
-    toolName: string;
-} | {
-    key: string;
-    value: string;
-};
-/**
- * A registered UI affordance handle.
- * Generic over slot type S for custom slot support.
- */
-type HandleRegistration<S extends string = DefaultSlots> = {
-    slot: S;
-    handleId: string;
-    bindsTo: Binding;
-};
-type Selection = {
-    handleId: string;
-    bindsTo: Binding;
-};
-/**
- * UI selections keyed by slot name.
- * Generic over slot type S for custom slot support.
- */
-type UiSelections<S extends string = DefaultSlots> = Partial<Record<S, Selection>>;
-/**
- * Collection of registered handles.
- * Generic over slot type S for custom slot support.
- */
-type AffordanceRegistry<S extends string = DefaultSlots> = {
-    handles: HandleRegistration<S>[];
-};
-
-/**
- * Generalized decision object.
- * Contains nextTool plus any custom fields returned by step handlers.
- */
-type Decision = Record<string, string | undefined>;
-/**
- * Context passed to a step handler.
- *
- * - toolName: the name of the tool being executed
- * - params: the input parameters of the tool call (optional)
- * - result: the output of the tool's execution (optional)
- */
-type TaiasContext = {
-    toolName: string;
-    params?: Record<string, unknown>;
-    result?: Record<string, unknown>;
-};
-/**
- * Decision returned by a step handler specifying the next tool.
- * Additional custom fields can be included for multi-dimensional UI control.
- */
-type StepDecision = {
-    nextTool: string;
-    [key: string]: string;
-};
-/**
- * Affordances returned by resolve():
- * - advice: LLM guidance text
- * - decision: generalized decision object (contains nextTool + custom fields)
- * - selections: UI affordance selections (may be empty)
- *
- * Generic over slot type S for custom slot support.
- */
-type Affordances<S extends string = DefaultSlots> = {
-    advice: string;
-    decision: Decision;
-    selections: UiSelections<S>;
-};
-/**
- * Handler function for a flow step.
- * Can return synchronously or asynchronously.
- */
-type StepHandler = (ctx: TaiasContext) => StepDecision | null | Promise<StepDecision | null>;
-/**
- * A condition operator applied to a single field value.
- *
- * - { is: value }    -- exact equality (field === value)
- * - { isNot: value } -- not equal      (field !== value)
- *
- * Condition accepts unknown values, enabling matching on strings, numbers,
- * booleans, and any other value type. Comparison uses strict equality (===).
- *
- * The operator system is pure data (not wrapper functions), aligning with
- * the logic-as-data philosophy. New operators (oneOf, contains, etc.) can
- * be added as union members without changing the evaluation architecture.
- */
-type Condition = {
-    is: unknown;
-} | {
-    isNot: unknown;
-};
-/**
- * Match condition for a logic statement.
- *
- * All fields are optional -- steps can match on any combination of
- * toolName, params, and result. Each field uses explicit Condition
- * operators ({ is: ... } or { isNot: ... }).
- *
- * For params and result, conditions are specified per-key. Only the
- * specified keys are checked (subset matching); unspecified keys are
- * ignored. If a step specifies a params/result condition but the
- * context doesn't include params/result, the step does not match.
- */
-type MatchCondition = {
-    toolName?: Condition;
-    params?: Record<string, Condition>;
-    result?: Record<string, Condition>;
-};
-/**
- * A declarative logic statement -- the core primitive of the decision engine.
- *
- * Formalizes the implicit "Given X, then Y" logic into structured data
- * that Taias can understand, validate, and optimize.
- *
- * - match: the conditions under which this statement applies
- * - decision: the decision to produce when matched
- */
-type LogicStatement = {
-    match: MatchCondition;
-    decision: StepDecision;
-};
-/**
- * A step within a flow. Discriminated union:
- *
- * - "logic": A declarative logic statement. The statement is the sole source
- *   of truth for its match conditions and decision.
- * - "handler": A handler function (backwards-compatible escape hatch).
- *   The match condition is stored alongside the handler since the function
- *   itself has no formal match conditions.
- */
-type FlowStep = {
-    kind: "logic";
-    statement: LogicStatement;
-} | {
-    kind: "handler";
-    match: MatchCondition;
-    handler: StepHandler;
-};
-/**
- * A complete flow definition with an id and its steps.
- */
-type FlowDefinition = {
-    id: string;
-    steps: Array<FlowStep>;
-};
-/**
- * The input accepted by flow.step() -- either a handler function
- * or a static StepDecision object.
- */
-type StepInput = StepHandler | StepDecision;
-/**
- * Builder interface for defining flow steps.
- *
- * step() takes two arguments:
- *   - match: a MatchCondition object describing the conditions under which
- *     this step applies. All fields use explicit operator objects.
- *   - input: a StepDecision object (creates a logic statement).
- *     A StepHandler function is also accepted for backwards compatibility.
- */
-interface FlowBuilder {
-    step(match: MatchCondition, input: StepInput): void;
-}
-/**
- * Evaluation record for a single step during resolve().
- * Present when tracing: "detailed" is enabled.
- */
-type StepEvaluation = {
-    stepIndex: number;
-    match: MatchCondition;
-    result: "matched" | "no-match";
-    fieldResults?: Record<string, {
-        condition: Condition;
-        actual: unknown;
-        passed: boolean;
-    }>;
-};
-/**
- * Trace of how resolve() reached its decision.
- *
- * Always includes summary information (which step matched, how it was found).
- * When tracing: "detailed", also includes per-step evaluation breakdowns.
- */
-type ResolveTrace = {
-    matched: boolean;
-    matchedStepIndex: number | null;
-    matchedStepKind: "logic" | "handler" | null;
-    matchedStepMatch: MatchCondition | null;
-    phase: "indexed" | "broad" | null;
-    resolutionPath: string[];
-    candidatesEvaluated: number;
-    evaluations?: StepEvaluation[];
-};
-/**
- * Structured event emitted on every resolve() call.
- *
- * Four-part structure:
- *   1. context  -- what was passed to resolve()
- *   2. trace    -- how the decision was reached
- *   3. decision -- what was decided
- *   4. affordances -- how the decision was manifested (advice + selections)
- */
-type ResolveEvent<S extends string = DefaultSlots> = {
-    flowId: string;
-    timestamp: number;
-    durationMs: number;
-    context: TaiasContext;
-    trace: ResolveTrace;
-    decision: Decision | null;
-    affordances: {
-        advice: string;
-        selections: UiSelections<S>;
-    } | null;
-};
-/**
- * Map of event names to their event types.
- * Extensible to future event types (e.g., "init", "error").
- */
-type TaiasEventMap<S extends string = DefaultSlots> = {
-    resolve: ResolveEvent<S>;
-};
-/**
- * Options for the built-in debug subscriber.
- *
- * - format: "default" (multi-line breakdown) or "compact" (single line).
- * - logger: Custom log function (defaults to console.log).
- */
-type DebugOptions = {
-    format?: "default" | "compact";
-    logger?: (...args: unknown[]) => void;
-};
-/**
- * Options for creating a Taias instance.
- * Generic over slot type S for custom slot support.
- */
-type TaiasOptions<S extends string = DefaultSlots> = {
-    flow: FlowDefinition;
-    affordances?: AffordanceRegistry<S>;
-    devMode?: boolean;
-    debug?: boolean | DebugOptions;
-    tracing?: "summary" | "detailed";
-    onMissingStep?: (ctx: TaiasContext) => void;
-    onWarn?: (msg: string) => void;
-};
-/**
- * The Taias instance interface.
- * Generic over slot type S for custom slot support.
- */
-interface Taias<S extends string = DefaultSlots> {
-    resolve(ctx: TaiasContext): Affordances<S> | null | Promise<Affordances<S> | null>;
-    on<E extends keyof TaiasEventMap<S>>(event: E, handler: (data: TaiasEventMap<S>[E]) => void): void;
-    off<E extends keyof TaiasEventMap<S>>(event: E, handler: (data: TaiasEventMap<S>[E]) => void): void;
-}
-
-/**
- * Define a flow with its steps.
- *
- * @param flowId - Unique identifier for the flow
- * @param builder - Callback that receives a FlowBuilder to define steps
- * @returns A FlowDefinition object
- *
- * @example Logic statement matching on toolName
- * ```ts
- * const onboardRepoFlow = defineFlow("onboard_repo", (flow) => {
- *   flow.step({ toolName: { is: "scan_repo" } }, { nextTool: "configure_app" });
- * });
- * ```
- *
- * @example Matching on params and result
- * ```ts
- * flow.step(
- *   { toolName: { is: "scan_repo" }, params: { language: { is: "python" } } },
- *   { nextTool: "configure_python" },
- * );
- * flow.step(
- *   { result: { hasConfig: { is: true } } },
- *   { nextTool: "review_config" },
- * );
- * ```
- *
- * @example isNot operator
- * ```ts
- * flow.step({ toolName: { isNot: "abort_session" } }, { nextTool: "continue_flow" });
- * ```
- */
-declare function defineFlow(flowId: string, builder: (flow: FlowBuilder) => void): FlowDefinition;
-
-/**
- * createTaias constructs a decision engine.
- *
- * Taias resolves context into a generalized Decision object,
- * and then manifests that decision into concrete affordances:
- *
- *   - LLM guidance (advice)
- *   - UI affordance selections
- *
- * Flow logic is expressed as logic statements -- structured data that
- * Taias understands. (Handler functions remain as a backwards-compatible
- * escape hatch.)
- *
- * Flow logic determines *what should happen next*.
- * UI affordances determine *how that decision appears in the interface*.
- *
- * This file is the boundary where:
- *
- *   Inputs -> Decision -> Manifestations
- *
- * are unified into a single resolve() call.
- *
- * @example
- * ```ts
- * const taias = createTaias({ flow, affordances });
- * ```
- */
-declare function createTaias<S extends string = DefaultSlots>(options: TaiasOptions<S>): Taias<S>;
-
-type DebugSubscriberOptions = DebugOptions;
-/**
- * Create a debug subscriber for Taias resolve events.
- *
- * Returns a handler function suitable for `taias.on("resolve", handler)`.
- *
- * - "default" format: multi-line breakdown of context, trace, decision, and affordances.
- * - "compact" format: single line per resolve call.
- */
-declare function createDebugSubscriber(options?: DebugSubscriberOptions): (event: ResolveEvent) => void;
-
-/**
- * Mapped type that creates a registration method for each slot in S.
- * This enables fully typed custom slots via generics.
- */
-type AffordanceRegistrar<S extends string = DefaultSlots> = {
-    [K in S]: (handleId: string, bindsTo: BindingInput) => void;
-};
-/**
- * Define UI affordances for a widget using a builder pattern.
- *
- * @example Default slots (backwards compatible)
- * ```ts
- * const affordances = defineAffordances((r) => {
- *   r.primaryCta("cta.recommend", { toolName: "get_recommendations" });
- *   r.widgetVariant("variant.discovery", { toolName: "get_recommendations" });
- * });
- * ```
- *
- * @example Custom slots (fully type-safe)
- * ```ts
- * type MySlots = "primaryCta" | "contentArea" | "headerStyle";
- * const affordances = defineAffordances<MySlots>((r) => {
- *   r.primaryCta("cta.create", { toolName: "createUser" });
- *   r.contentArea("content.form", { key: "contentArea", value: "email-form" });
- *   r.headerStyle("header.progress", { key: "headerStyle", value: "step-1" });
- * });
- * ```
- */
-declare function defineAffordances<S extends string = DefaultSlots>(builder: (r: AffordanceRegistrar<S>) => void): AffordanceRegistry<S>;
-
-type MergeAffordancesOptions = {
-    devMode?: boolean;
-    onWarn?: (msg: string) => void;
-};
-/**
- * Merge multiple affordance registries into one.
- * Generic over slot type S for custom slot support.
- *
- * @example Default slots
- * ```ts
- * const merged = mergeAffordances([widgetA, widgetB]);
- * ```
- *
- * @example Custom slots
- * ```ts
- * type MySlots = "primaryCta" | "contentArea";
- * const merged = mergeAffordances<MySlots>([widgetA, widgetB]);
- * ```
- */
-declare function mergeAffordances<S extends string = DefaultSlots>(registries: AffordanceRegistry<S>[], opts?: MergeAffordancesOptions): AffordanceRegistry<S>;
-
-export { type AffordanceRegistrar, type AffordanceRegistry, type Affordances, type Binding, type BindingInput, type CanonicalSlot, type Condition, type DebugOptions, type Decision, type DefaultSlots, type FlowBuilder, type FlowDefinition, type FlowStep, type HandleRegistration, type LogicStatement, type MatchCondition, type ResolveEvent, type ResolveTrace, type Selection, type StepDecision, type StepEvaluation, type StepHandler, type StepInput, type Taias, type TaiasContext, type TaiasEventMap, type TaiasOptions, type UiSelections, createDebugSubscriber, createTaias, defineAffordances, defineFlow, mergeAffordances };