taias 0.7.1 → 0.9.0

package/README.md

@@ -31,8 +31,8 @@ npm install taias
 import { defineFlow, createTaias } from "taias";
 
 const flow = defineFlow("onboard", (flow) => {
-  flow.step({ toolName: "scan_repo" }, { nextTool: "configure_app" });
-  flow.step({ toolName: "configure_app" }, { nextTool: "deploy" });
+  flow.step({ toolName: { is: "scan_repo" } }, { nextTool: "configure_app" });
+  flow.step({ toolName: { is: "configure_app" } }, { nextTool: "deploy" });
 });
 ```
 
@@ -80,13 +80,20 @@ return {
 
 ### `defineFlow(flowId, builder)`
 
-Creates a flow definition. Each step is a logic statement: a match condition paired with a decision. Match condition fields support operators (`is`, `isNot`); bare strings are sugar for `{ is: "..." }`.
+Creates a flow definition. Each step is a logic statement: a match condition paired with a decision. Match conditions use explicit operators (`{ is: ... }`, `{ isNot: ... }`) and can match on `toolName`, `params`, and `result`.
 
 ```ts
 const myFlow = defineFlow("my_flow", (flow) => {
-  flow.step({ toolName: { is: "tool_a" } }, { nextTool: "tool_b" });      // explicit equality
-  flow.step({ toolName: { isNot: "abort" } }, { nextTool: "continue" });   // negation
-  flow.step({ toolName: "tool_a" }, { nextTool: "tool_b" });              // bare string = sugar for { is: "tool_a" }
+  flow.step({ toolName: { is: "tool_a" } }, { nextTool: "tool_b" });
+  flow.step({ toolName: { isNot: "abort" } }, { nextTool: "continue" });
+  flow.step(
+    { toolName: { is: "scan_repo" }, params: { language: { is: "python" } } },
+    { nextTool: "configure_python" },
+  );
+  flow.step(
+    { result: { hasConfig: { is: true } } },
+    { nextTool: "review_config" },
+  );
 });
 ```
 
@@ -113,6 +120,8 @@ const taias = createTaias({
 **Options:**
 - `flow` - A `FlowDefinition` created by `defineFlow`
 - `devMode` (optional) - Enable development mode checks
+- `debug` (optional) - `true` or `{ format, logger }` -- enable built-in debug output
+- `tracing` (optional) - `"summary"` (default) or `"detailed"` -- controls trace depth
 - `onMissingStep` (optional) - Callback invoked when no step matches
 
 **Returns:** `Taias` instance
@@ -143,6 +152,31 @@ const affordances = await taias.resolve({
 
 See the [full documentation](https://taias.xyz/docs) for complete API reference and types.
 
+## Observability
+
+Enable debug output with a single option:
+
+```ts
+const taias = createTaias({ flow, debug: true });
+```
+
+Every `resolve()` call prints a formatted breakdown to the console -- what went in, how the decision was reached, and what was produced.
+
+For compact single-line output:
+
+```ts
+const taias = createTaias({ flow, debug: { format: "compact" } });
+// [Taias] scan_repo → nextTool=configure_app (indexed, step 0, 1 evaluated)
+```
+
+Enable detailed tracing for per-step evaluation breakdowns (verbose -- best used when debugging specific resolve calls):
+
+```ts
+const taias = createTaias({ flow, debug: true, tracing: "detailed" });
+```
+
+For programmatic access to resolve events, use the event emitter API (`taias.on` / `taias.off`). See the [full documentation](https://taias.xyz/docs) for details.
+
 ## Dev Mode
 
 <details>

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  createDebugSubscriber: () => createDebugSubscriber,
   createTaias: () => createTaias,
   defineAffordances: () => defineAffordances,
   defineFlow: () => defineFlow,
@@ -32,14 +33,13 @@ function defineFlow(flowId, builder) {
   const steps = [];
   const flowBuilder = {
     step(match, input) {
-      const condition = typeof match === "string" ? { toolName: match } : match;
       if (typeof input === "function") {
-        steps.push({ kind: "handler", match: condition, handler: input });
+        steps.push({ kind: "handler", match, handler: input });
       } else {
         steps.push({
           kind: "logic",
           statement: {
-            match: condition,
+            match,
             decision: input
           }
         });
@@ -107,98 +107,396 @@ function selectUiAffordances(decision, index, opts = {}) {
   return selections;
 }
 
+// src/debugSubscriber.ts
+function formatContext(context) {
+  const parts = [];
+  if (context.toolName) parts.push(`toolName=${context.toolName}`);
+  if (context.params) parts.push(`params=${JSON.stringify(context.params)}`);
+  if (context.result) parts.push(`result=${JSON.stringify(context.result)}`);
+  return parts.length > 0 ? parts.join(", ") : "(empty)";
+}
+function formatContextLabel(context) {
+  if (context.toolName) return context.toolName;
+  if (context.params) return `params:${JSON.stringify(context.params)}`;
+  if (context.result) return `result:${JSON.stringify(context.result)}`;
+  return "(empty)";
+}
+function createDebugSubscriber(options) {
+  const format = options?.format ?? "default";
+  const log = options?.logger ?? console.log;
+  if (format === "compact") {
+    return (event) => {
+      const { trace, context } = event;
+      const label = formatContextLabel(context);
+      if (!trace.matched) {
+        log(`[Taias] ${label} \u2192 no match (${trace.candidatesEvaluated} evaluated)`);
+        return;
+      }
+      const decisionSummary = event.decision ? Object.entries(event.decision).map(([k, v]) => `${k}=${v}`).join(", ") : "null";
+      log(
+        `[Taias] ${label} \u2192 ${decisionSummary} (${trace.phase}, step ${trace.matchedStepIndex}, ${trace.candidatesEvaluated} evaluated)`
+      );
+    };
+  }
+  return (event) => {
+    const { trace, context } = event;
+    const lines = [];
+    lines.push("\u250C\u2500 Taias Resolve \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    lines.push(`\u2502 Flow: ${event.flowId}`);
+    lines.push(`\u2502 Context: ${formatContext(context)}`);
+    lines.push("\u2502");
+    if (!trace.matched) {
+      lines.push("\u2502 Result: NO MATCH");
+      lines.push(`\u2502 Candidates evaluated: ${trace.candidatesEvaluated}`);
+    } else {
+      lines.push(`\u2502 Matched: step ${trace.matchedStepIndex} (${trace.matchedStepKind})`);
+      lines.push(`\u2502 Phase: ${trace.phase}`);
+      if (trace.resolutionPath.length > 0) {
+        lines.push(`\u2502 Resolution path: ${trace.resolutionPath.join(" \u2192 ")}`);
+      }
+      lines.push(`\u2502 Candidates evaluated: ${trace.candidatesEvaluated}`);
+      if (trace.matchedStepMatch) {
+        lines.push(`\u2502 Match condition: ${JSON.stringify(trace.matchedStepMatch)}`);
+      }
+    }
+    lines.push("\u2502");
+    if (event.decision) {
+      const fields = Object.entries(event.decision).map(([k, v]) => `${k}=${v}`).join(", ");
+      lines.push(`\u2502 Decision: ${fields}`);
+    } else {
+      lines.push("\u2502 Decision: null");
+    }
+    if (event.affordances) {
+      lines.push(`\u2502 Advice: ${event.affordances.advice.slice(0, 80)}${event.affordances.advice.length > 80 ? "..." : ""}`);
+    }
+    lines.push(`\u2502 Duration: ${event.durationMs.toFixed(2)}ms`);
+    if (trace.evaluations) {
+      lines.push("\u2502");
+      lines.push("\u2502 Detailed evaluations:");
+      for (const evaluation of trace.evaluations) {
+        const icon = evaluation.result === "matched" ? "\u2713" : "\u2717";
+        lines.push(`\u2502   ${icon} step ${evaluation.stepIndex}: ${evaluation.result}`);
+        if (evaluation.fieldResults) {
+          for (const [field, fr] of Object.entries(evaluation.fieldResults)) {
+            const fieldIcon = fr.passed ? "\u2713" : "\u2717";
+            lines.push(`\u2502     ${fieldIcon} ${field}: ${JSON.stringify(fr.condition)} vs ${JSON.stringify(fr.actual)}`);
+          }
+        }
+      }
+    }
+    lines.push("\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    log(lines.join("\n"));
+  };
+}
+
 // src/createTaias.ts
 function generateAdvice(nextTool) {
   return `FOR THE BEST USER EXPERIENCE, TELL THE USER TO USE THE ${nextTool} TOOL NEXT!!!!!`;
 }
-function normalizeFieldCondition(field) {
-  return typeof field === "string" ? { is: field } : field;
-}
 function evaluateCondition(condition, value) {
   if ("is" in condition) return value === condition.is;
   if ("isNot" in condition) return value !== condition.isNot;
   return false;
 }
 function evaluateMatch(match, ctx) {
-  const toolCondition = normalizeFieldCondition(match.toolName);
-  return evaluateCondition(toolCondition, ctx.toolName);
+  if (match.toolName && !evaluateCondition(match.toolName, ctx.toolName)) return false;
+  if (match.params) {
+    if (!ctx.params) return false;
+    for (const [key, condition] of Object.entries(match.params)) {
+      if (!evaluateCondition(condition, ctx.params[key])) return false;
+    }
+  }
+  if (match.result) {
+    if (!ctx.result) return false;
+    for (const [key, condition] of Object.entries(match.result)) {
+      if (!evaluateCondition(condition, ctx.result[key])) return false;
+    }
+  }
+  return true;
 }
-function isIndexable(field) {
-  if (typeof field === "string") return true;
-  return "is" in field;
+function evaluateMatchDetailed(match, ctx) {
+  const fieldResults = {};
+  let allPassed = true;
+  if (match.toolName) {
+    const actual = ctx.toolName;
+    const passed = evaluateCondition(match.toolName, actual);
+    fieldResults["toolName"] = { condition: match.toolName, actual, passed };
+    if (!passed) allPassed = false;
+  }
+  if (match.params) {
+    if (!ctx.params) {
+      for (const [key, condition] of Object.entries(match.params)) {
+        fieldResults[`params.${key}`] = { condition, actual: void 0, passed: false };
+      }
+      allPassed = false;
+    } else {
+      for (const [key, condition] of Object.entries(match.params)) {
+        const actual = ctx.params[key];
+        const passed = evaluateCondition(condition, actual);
+        fieldResults[`params.${key}`] = { condition, actual, passed };
+        if (!passed) allPassed = false;
+      }
+    }
+  }
+  if (match.result) {
+    if (!ctx.result) {
+      for (const [key, condition] of Object.entries(match.result)) {
+        fieldResults[`result.${key}`] = { condition, actual: void 0, passed: false };
+      }
+      allPassed = false;
+    } else {
+      for (const [key, condition] of Object.entries(match.result)) {
+        const actual = ctx.result[key];
+        const passed = evaluateCondition(condition, actual);
+        fieldResults[`result.${key}`] = { condition, actual, passed };
+        if (!passed) allPassed = false;
+      }
+    }
+  }
+  return { passed: allPassed, fieldResults };
 }
-function indexKey(field) {
-  if (typeof field === "string") return field;
-  if ("is" in field) return field.is;
-  throw new Error("Cannot derive index key from non-indexable condition");
+function extractIsConditions(match) {
+  const conditions = [];
+  if (match.toolName && "is" in match.toolName) {
+    conditions.push({ path: "toolName", value: match.toolName.is });
+  }
+  if (match.params) {
+    for (const [key, cond] of Object.entries(match.params)) {
+      if ("is" in cond) conditions.push({ path: `params.${key}`, value: cond.is });
+    }
+  }
+  if (match.result) {
+    for (const [key, cond] of Object.entries(match.result)) {
+      if ("is" in cond) conditions.push({ path: `result.${key}`, value: cond.is });
+    }
+  }
+  return conditions;
+}
+function hasConditionOnField(match, path) {
+  if (path === "toolName") return !!match.toolName;
+  if (path.startsWith("params.")) return !!match.params?.[path.slice(7)];
+  if (path.startsWith("result.")) return !!match.result?.[path.slice(7)];
+  return false;
+}
+function getContextValue(ctx, path) {
+  if (path === "toolName") return ctx.toolName;
+  if (path.startsWith("params.")) return ctx.params?.[path.slice(7)];
+  if (path.startsWith("result.")) return ctx.result?.[path.slice(7)];
+  return void 0;
 }
 function getMatch(step) {
   return step.kind === "logic" ? step.statement.match : step.match;
 }
 function serializeMatch(match) {
-  const normalized = normalizeFieldCondition(match.toolName);
-  return JSON.stringify({ toolName: normalized });
+  return JSON.stringify(match);
 }
 function createTaias(options) {
   const {
     flow,
     affordances,
     devMode = false,
+    debug = false,
+    tracing = "summary",
     onMissingStep,
     onWarn
   } = options;
   const warn = onWarn ?? ((msg) => console.warn(msg));
+  const detailed = tracing === "detailed";
   if (devMode) {
     const seenKeys = /* @__PURE__ */ new Set();
     for (const step of flow.steps) {
       const key = serializeMatch(getMatch(step));
       if (seenKeys.has(key)) {
-        const match = getMatch(step);
-        const normalized = normalizeFieldCondition(match.toolName);
-        const label = "is" in normalized ? normalized.is : `isNot:${normalized.isNot}`;
         throw new Error(
-          `Taias: Duplicate match condition '${label}' in flow '${flow.id}'. Each step must have a unique match condition.`
+          `Taias: Duplicate match condition in flow '${flow.id}'. Each step must have a unique match condition. Duplicate: ${key}`
         );
       }
       seenKeys.add(key);
     }
   }
-  const exactIndex = /* @__PURE__ */ new Map();
-  const broadSteps = [];
-  for (const step of flow.steps) {
-    const match = getMatch(step);
-    if (isIndexable(match.toolName)) {
-      exactIndex.set(indexKey(match.toolName), step);
-    } else {
-      broadSteps.push(step);
+  const fieldIndexes = /* @__PURE__ */ new Map();
+  const indexableStepIndices = [];
+  const broadStepIndices = [];
+  for (let i = 0; i < flow.steps.length; i++) {
+    const match = getMatch(flow.steps[i]);
+    const isConditions = extractIsConditions(match);
+    if (isConditions.length === 0) {
+      broadStepIndices.push(i);
+      continue;
+    }
+    indexableStepIndices.push(i);
+    for (const { path, value } of isConditions) {
+      let fieldIndex = fieldIndexes.get(path);
+      if (!fieldIndex) {
+        fieldIndex = { valueMap: /* @__PURE__ */ new Map(), unconstrained: [] };
+        fieldIndexes.set(path, fieldIndex);
+      }
+      let stepList = fieldIndex.valueMap.get(value);
+      if (!stepList) {
+        stepList = [];
+        fieldIndex.valueMap.set(value, stepList);
+      }
+      stepList.push(i);
+    }
+  }
+  for (const [fieldPath, fieldIndex] of fieldIndexes) {
+    for (const i of indexableStepIndices) {
+      if (!hasConditionOnField(getMatch(flow.steps[i]), fieldPath)) {
+        fieldIndex.unconstrained.push(i);
+      }
     }
   }
-  const hasBroadSteps = broadSteps.length > 0;
+  const hasBroadSteps = broadStepIndices.length > 0;
   const registryIndex = buildRegistryIndex(affordances);
+  const listeners = /* @__PURE__ */ new Map();
+  function emit(event, data) {
+    const handlers = listeners.get(event);
+    if (handlers) {
+      for (const handler of handlers) handler(data);
+    }
+  }
+  function on(event, handler) {
+    let set = listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      listeners.set(event, set);
+    }
+    set.add(handler);
+  }
+  function off(event, handler) {
+    listeners.get(event)?.delete(handler);
+  }
+  if (debug) {
+    const debugOpts = typeof debug === "object" ? debug : void 0;
+    on("resolve", createDebugSubscriber(debugOpts));
+  }
   return {
     async resolve(ctx) {
-      let step;
-      if (!hasBroadSteps) {
-        step = exactIndex.get(ctx.toolName);
-      } else {
-        for (const candidate of flow.steps) {
-          if (evaluateMatch(getMatch(candidate), ctx)) {
-            step = candidate;
+      const startTime = performance.now();
+      const timestamp = Date.now();
+      let matchedStep;
+      let matchedStepIndex = null;
+      let matchPhase = null;
+      const resolutionPath = [];
+      let candidatesEvaluated = 0;
+      const evaluations = detailed ? [] : void 0;
+      function tryMatch(idx) {
+        candidatesEvaluated++;
+        const step = flow.steps[idx];
+        const match = getMatch(step);
+        if (detailed) {
+          const { passed, fieldResults } = evaluateMatchDetailed(match, ctx);
+          evaluations.push({
+            stepIndex: idx,
+            match,
+            result: passed ? "matched" : "no-match",
+            fieldResults
+          });
+          return passed;
+        }
+        return evaluateMatch(match, ctx);
+      }
+      const applicableFieldPaths = [];
+      for (const fieldPath of fieldIndexes.keys()) {
+        const ctxValue = getContextValue(ctx, fieldPath);
+        if (ctxValue !== void 0) {
+          applicableFieldPaths.push(fieldPath);
+        }
+      }
+      resolutionPath.push(...applicableFieldPaths);
+      if (applicableFieldPaths.length > 0) {
+        let candidates = null;
+        for (const fieldPath of applicableFieldPaths) {
+          const fieldIndex = fieldIndexes.get(fieldPath);
+          const ctxValue = getContextValue(ctx, fieldPath);
+          const fieldCandidates = /* @__PURE__ */ new Set();
+          const indexed = fieldIndex.valueMap.get(ctxValue);
+          if (indexed) {
+            for (const idx of indexed) fieldCandidates.add(idx);
+          }
+          for (const idx of fieldIndex.unconstrained) {
+            fieldCandidates.add(idx);
+          }
+          if (candidates === null) {
+            candidates = fieldCandidates;
+          } else {
+            for (const idx of candidates) {
+              if (!fieldCandidates.has(idx)) candidates.delete(idx);
+            }
+          }
+        }
+        if (candidates && candidates.size > 0) {
+          const sorted = [...candidates].sort((a, b) => a - b);
+          for (const idx of sorted) {
+            if (tryMatch(idx)) {
+              matchedStep = flow.steps[idx];
+              matchedStepIndex = idx;
+              matchPhase = "indexed";
+              break;
+            }
+          }
+        }
+      } else if (indexableStepIndices.length > 0) {
+        for (const idx of indexableStepIndices) {
+          if (tryMatch(idx)) {
+            matchedStep = flow.steps[idx];
+            matchedStepIndex = idx;
+            matchPhase = "indexed";
+            break;
+          }
+        }
+      }
+      if (!matchedStep && hasBroadSteps) {
+        for (const idx of broadStepIndices) {
+          if (tryMatch(idx)) {
+            matchedStep = flow.steps[idx];
+            matchedStepIndex = idx;
+            matchPhase = "broad";
             break;
           }
         }
       }
-      if (!step) {
+      const trace = {
+        matched: !!matchedStep,
+        matchedStepIndex,
+        matchedStepKind: matchedStep?.kind ?? null,
+        matchedStepMatch: matchedStep ? getMatch(matchedStep) : null,
+        phase: matchPhase,
+        resolutionPath,
+        candidatesEvaluated,
+        ...evaluations !== void 0 ? { evaluations } : {}
+      };
+      if (!matchedStep) {
         onMissingStep?.(ctx);
+        emit("resolve", {
+          flowId: flow.id,
+          timestamp,
+          durationMs: performance.now() - startTime,
+          context: ctx,
+          trace,
+          decision: null,
+          affordances: null
+        });
         return null;
       }
       let result;
-      if (step.kind === "logic") {
-        result = step.statement.decision;
+      if (matchedStep.kind === "logic") {
+        result = matchedStep.statement.decision;
       } else {
-        result = await step.handler(ctx);
+        result = await matchedStep.handler(ctx);
+      }
+      if (!result) {
+        emit("resolve", {
+          flowId: flow.id,
+          timestamp,
+          durationMs: performance.now() - startTime,
+          context: ctx,
+          trace,
+          decision: null,
+          affordances: null
+        });
+        return null;
       }
-      if (!result) return null;
       if (devMode && result.nextTool === "") {
         warn(`Taias: nextTool for tool '${ctx.toolName}' is empty.`);
       }
@@ -207,12 +505,20 @@ function createTaias(options) {
         devMode,
         onWarn: warn
       });
-      return {
-        advice: generateAdvice(result.nextTool),
+      const advice = generateAdvice(result.nextTool);
+      emit("resolve", {
+        flowId: flow.id,
+        timestamp,
+        durationMs: performance.now() - startTime,
+        context: ctx,
+        trace,
         decision,
-        selections
-      };
-    }
+        affordances: { advice, selections }
+      });
+      return { advice, decision, selections };
+    },
+    on,
+    off
   };
 }
 
@@ -263,6 +569,7 @@ function mergeAffordances(registries, opts = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createDebugSubscriber,
   createTaias,
   defineAffordances,
   defineFlow,