knolo-core 3.1.0 → 3.1.1

package/README.md

@@ -16,7 +16,7 @@ Build a portable `.knolo` pack and run deterministic lexical retrieval with opti
 
 ---
 
-## ✨ What’s in v0.3.0
+## ✨ What’s in v0.3.1
 
 - **Deterministic lexical quality upgrades**
   - required phrase enforcement (quoted + `requirePhrases`)
@@ -31,6 +31,10 @@ Build a portable `.knolo` pack and run deterministic lexical retrieval with opti
 - **Stability & diversity**
   - near-duplicate suppression + MMR diversity
   - KNS tie-break signal for stable close-score ordering
+- **Agent/runtime utilities**
+  - embedded agent registries with strict namespace binding
+  - tool call parsing + policy gating helpers
+  - provider-agnostic routing profile + route decision validators
 - **Portable packs**
   - single `.knolo` artifact
   - semantic payload embedded directly in pack when enabled
@@ -54,6 +58,14 @@ npm run build
 
 ---
 
+## 🧪 Playground
+
+Try KnoLo Core directly in your browser with the hosted playground:
+
+- https://playgrounds.knolo.dev
+
+---
+
 ## 🚀 Quickstart
 
 ### 1) Build + mount + query
@@ -126,7 +138,7 @@ const hits = query(kb, 'throttle events', { topK: 3 });
 
 ---
 
-## 🔀 Hybrid retrieval with embeddings (recommended direction)
+## 🔀 Hybrid retrieval with embeddings (optional)
 
 KnoLo’s core retrieval remains lexical-first and deterministic. Semantic signals are added as an **optional rerank stage** when lexical confidence is low (or forced).
 
@@ -221,7 +233,6 @@ Agent namespace binding is **strict**: when `resolveAgent()` composes retrieval
 ```ts
 type AgentPromptTemplate = string[] | { format: 'markdown'; template: string };
 
-
 type AgentRegistry = {
   version: 1;
   agents: AgentDefinitionV1[];
@@ -336,6 +347,211 @@ type Hit = {
 - `buildSystemPrompt(agent, patch?) => string`
 - `isToolAllowed(agent, toolId) => boolean` (defaults to allow-all when no `toolPolicy`)
 - `assertToolAllowed(agent, toolId) => void` (throws deterministic error when blocked)
+- `parseToolCallV1FromText(text) => ToolCallV1 | null` (safe parser for model outputs)
+- `assertToolCallAllowed(agent, call) => void` (policy gate for parsed calls)
+- `isToolCallV1(value) / isToolResultV1(value)` (runtime-safe type guards)
+- `getAgentRoutingProfileV1(agent) => AgentRoutingProfileV1`
+- `getPackRoutingProfilesV1(pack) => AgentRoutingProfileV1[]`
+- `isRouteDecisionV1(value) => boolean` (strict contract guard for router output)
+- `validateRouteDecisionV1(decision, registryById) => { ok: true } | { ok: false; error: string }`
+- `selectAgentIdFromRouteDecisionV1(decision, registryById, { fallbackAgentId? }) => { agentId, reason }`
+
+### Routing discoverability conventions
+
+To make an agent easier to route, use these optional `metadata` keys on `AgentDefinitionV1`:
+
+- `tags`: comma-separated (`"shopping,checkout"`) or JSON array string (`"[\"shopping\",\"checkout\"]"`)
+- `examples`: comma-separated, newline-separated, or JSON array string
+- `capabilities`: comma-separated, newline-separated, or JSON array string
+- `heading`: short UI heading shown in routing cards
+
+`knolo-core` parses these into a compact routing profile with trimming + dedupe + caps and never throws on bad metadata formats.
+
+```ts
+type AgentRoutingProfileV1 = {
+  agentId: string;
+  namespace?: string;
+  heading?: string;
+  description?: string;
+  tags: string[];
+  examples: string[];
+  capabilities: string[];
+  toolPolicy?: unknown;
+  toolPolicySummary?: {
+    mode: 'allow_all' | 'deny_all' | 'mixed' | 'unknown';
+    allowed?: string[];
+    denied?: string[];
+  };
+};
+```
+
+Example profile payload:
+
+```json
+{
+  "agentId": "shopping.agent",
+  "namespace": "shopping",
+  "heading": "Shopping Assistant",
+  "description": "Handles product lookup, checkout help, and order tracking.",
+  "tags": ["shopping", "checkout", "order-status"],
+  "examples": ["track my order", "find running shoes under $120"],
+  "capabilities": ["catalog_search", "order_lookup"],
+  "toolPolicySummary": {
+    "mode": "mixed",
+    "allowed": ["search_docs", "order_lookup"]
+  }
+}
+```
+
+### Route decision contract
+
+`knolo-core` does not call Ollama (or any model provider). A runtime can call any router model, then validate the output with this contract:
+
+```ts
+type RouteCandidateV1 = {
+  agentId: string;
+  score: number; // 0..1
+  why?: string;
+};
+
+type RouteDecisionV1 = {
+  type: 'route_decision';
+  intent?: string;
+  entities?: Record<string, unknown>;
+  candidates: RouteCandidateV1[];
+  selected: string;
+  needsTools?: string[];
+  risk?: 'low' | 'med' | 'high';
+};
+```
+
+JSON example:
+
+```json
+{
+  "type": "route_decision",
+  "intent": "order_tracking",
+  "entities": { "orderId": "A-1023" },
+  "candidates": [
+    { "agentId": "shopping.agent", "score": 0.91, "why": "Order-related intent" },
+    { "agentId": "returns.agent", "score": 0.37 }
+  ],
+  "selected": "shopping.agent",
+  "needsTools": ["order_lookup"],
+  "risk": "low"
+}
+```
+
+Validation and selection notes:
+
+- `isRouteDecisionV1(...)` is strict and rejects malformed payloads.
+- `validateRouteDecisionV1(...)` requires `selected` and every candidate `agentId` to exist in the mounted registry and rejects duplicate candidate ids.
+- `selectAgentIdFromRouteDecisionV1(...)` is deterministic and never throws:
+  1. use `selected` if registered,
+  2. else highest-score registered candidate,
+  3. else caller `fallbackAgentId` if valid,
+  4. else lexicographically first registered agent id.
+
+### Router runtime flow (provider-agnostic)
+
+1. Receive user input text.
+2. Build routing profiles from mounted pack agents via `getPackRoutingProfilesV1(pack)`.
+3. Send input + profiles to your router model (Ollama or any provider) outside `knolo-core`.
+4. Parse model output JSON and gate with `isRouteDecisionV1`.
+5. Validate against mounted registry with `validateRouteDecisionV1`.
+6. Pick final agent using `selectAgentIdFromRouteDecisionV1`.
+7. Call `resolveAgent(pack, { agentId, ... })` and run your existing loop.
+
+### Tool call + result contracts
+
+```ts
+type ToolCallV1 = {
+  type: 'tool_call';
+  callId: string;
+  tool: string;
+  args: Record<string, unknown>;
+};
+
+type ToolResultV1 = {
+  type: 'tool_result';
+  callId: string;
+  tool: string;
+  ok: boolean;
+  output?: unknown; // when ok=true
+  error?: { message: string; code?: string; details?: unknown }; // when ok=false
+};
+```
+
+JSON examples:
+
+```json
+{
+  "type": "tool_call",
+  "callId": "call-42",
+  "tool": "search_docs",
+  "args": { "query": "bridge throttle" }
+}
+```
+
+```json
+{
+  "type": "tool_result",
+  "callId": "call-42",
+  "tool": "search_docs",
+  "ok": true,
+  "output": { "hits": [{ "id": "mobile-doc" }] }
+}
+```
+
+### Runtime loop shape (model-agnostic)
+
+1. Run model with current conversation state.
+2. Parse text output with `parseToolCallV1FromText(...)`.
+3. If parsed: gate with `assertToolCallAllowed(resolved.agent, call)`.
+4. Runtime executes the tool and creates `ToolResultV1`.
+5. Feed the tool result back into the conversation and continue until completion.
+
+### Trace events for timeline UIs
+
+```ts
+type TraceEventV1 =
+  | {
+      type: 'route.requested';
+      ts: string;
+      text: string;
+      agentCount: number;
+    }
+  | {
+      type: 'route.decided';
+      ts: string;
+      decision: RouteDecisionV1;
+      selectedAgentId: string;
+    }
+  | { type: 'agent.selected'; ts: string; agentId: string; namespace?: string }
+  | {
+      type: 'prompt.resolved';
+      ts: string;
+      agentId: string;
+      promptHash?: string;
+      patchKeys?: string[];
+    }
+  | { type: 'tool.requested'; ts: string; agentId: string; call: ToolCallV1 }
+  | {
+      type: 'tool.executed';
+      ts: string;
+      agentId: string;
+      result: ToolResultV1;
+      durationMs?: number;
+    }
+  | {
+      type: 'run.completed';
+      ts: string;
+      agentId: string;
+      status: 'ok' | 'error';
+    };
+```
+
+Helpers: `nowIso()` for timestamps and `createTrace()` for lightweight trace collection.
 
 ### Build a pack with agents and resolve at runtime
 
@@ -470,7 +686,7 @@ Yes. Runtime text encoder/decoder compatibility is included.
 
 ---
 
-## 🗺️ Direction / roadmap
+## 🗺️ Roadmap
 
 - stronger hybrid retrieval evaluation tooling
 - richer pack introspection and diagnostics

package/dist/index.d.ts

@@ -9,3 +9,13 @@ export type { QueryOptions, Hit } from './query.js';
 export type { ContextPatch } from './patch.js';
 export type { BuildInputDoc, BuildPackOptions } from './builder.js';
 export type { AgentPromptTemplate, AgentToolPolicy, AgentRetrievalDefaults, AgentDefinitionV1, AgentRegistry, ResolveAgentInput, ResolvedAgent, } from './agent.js';
+export { parseToolCallV1FromText } from './tool_parse.js';
+export { nowIso, createTrace } from './trace.js';
+export { assertToolCallAllowed } from './tool_gate.js';
+export { getAgentRoutingProfileV1, getPackRoutingProfilesV1, } from './routing_profile.js';
+export { isRouteDecisionV1, validateRouteDecisionV1, selectAgentIdFromRouteDecisionV1, } from './router.js';
+export { isToolCallV1, isToolResultV1 } from './tools.js';
+export type { ToolId, ToolCallV1, ToolResultErrorV1, ToolResultV1, ToolSpecV1, } from './tools.js';
+export type { TraceEventV1 } from './trace.js';
+export type { AgentRoutingProfileV1 } from './routing_profile.js';
+export type { RouteCandidateV1, RouteDecisionV1 } from './router.js';

package/dist/index.js

@@ -5,3 +5,9 @@ export { makeContextPatch } from './patch.js';
 export { buildPack } from './builder.js';
 export { quantizeEmbeddingInt8L2Norm, encodeScaleF16, decodeScaleF16, } from './semantic.js';
 export { listAgents, getAgent, resolveAgent, buildSystemPrompt, isToolAllowed, assertToolAllowed, validateAgentRegistry, validateAgentDefinition, } from './agent.js';
+export { parseToolCallV1FromText } from './tool_parse.js';
+export { nowIso, createTrace } from './trace.js';
+export { assertToolCallAllowed } from './tool_gate.js';
+export { getAgentRoutingProfileV1, getPackRoutingProfilesV1, } from './routing_profile.js';
+export { isRouteDecisionV1, validateRouteDecisionV1, selectAgentIdFromRouteDecisionV1, } from './router.js';
+export { isToolCallV1, isToolResultV1 } from './tools.js';

package/dist/router.d.ts

@@ -0,0 +1,28 @@
+import type { AgentDefinitionV1 } from './agent.js';
+export interface RouteCandidateV1 {
+    agentId: string;
+    score: number;
+    why?: string;
+}
+export interface RouteDecisionV1 {
+    type: 'route_decision';
+    intent?: string;
+    entities?: Record<string, unknown>;
+    candidates: RouteCandidateV1[];
+    selected: string;
+    needsTools?: string[];
+    risk?: 'low' | 'med' | 'high';
+}
+export declare function isRouteDecisionV1(x: unknown): x is RouteDecisionV1;
+export declare function validateRouteDecisionV1(decision: RouteDecisionV1, agentRegistry: Record<string, AgentDefinitionV1>): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function selectAgentIdFromRouteDecisionV1(decision: RouteDecisionV1, agentRegistry: Record<string, AgentDefinitionV1>, opts?: {
+    fallbackAgentId?: string;
+}): {
+    agentId: string;
+    reason: 'selected' | 'top_candidate' | 'fallback';
+};

package/dist/router.js

@@ -0,0 +1,74 @@
+export function isRouteDecisionV1(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const v = x;
+    if (v.type !== 'route_decision')
+        return false;
+    if (typeof v.selected !== 'string' || !v.selected.trim())
+        return false;
+    if (!Array.isArray(v.candidates) || v.candidates.length < 1)
+        return false;
+    if (v.needsTools !== undefined &&
+        (!Array.isArray(v.needsTools) ||
+            v.needsTools.some((toolId) => typeof toolId !== 'string'))) {
+        return false;
+    }
+    for (const candidate of v.candidates) {
+        if (!candidate || typeof candidate !== 'object')
+            return false;
+        const c = candidate;
+        if (typeof c.agentId !== 'string' || !c.agentId.trim())
+            return false;
+        if (typeof c.score !== 'number' || !Number.isFinite(c.score))
+            return false;
+        if (c.score < 0 || c.score > 1)
+            return false;
+        if (c.why !== undefined && typeof c.why !== 'string')
+            return false;
+    }
+    return true;
+}
+export function validateRouteDecisionV1(decision, agentRegistry) {
+    if (!agentRegistry[decision.selected]) {
+        return {
+            ok: false,
+            error: `selected agent is not registered: ${decision.selected}`,
+        };
+    }
+    const seen = new Set();
+    for (const candidate of decision.candidates) {
+        if (seen.has(candidate.agentId)) {
+            return {
+                ok: false,
+                error: `duplicate candidate agentId: ${candidate.agentId}`,
+            };
+        }
+        seen.add(candidate.agentId);
+        if (!agentRegistry[candidate.agentId]) {
+            return {
+                ok: false,
+                error: `candidate agent is not registered: ${candidate.agentId}`,
+            };
+        }
+    }
+    return { ok: true };
+}
+export function selectAgentIdFromRouteDecisionV1(decision, agentRegistry, opts = {}) {
+    if (agentRegistry[decision.selected]) {
+        return { agentId: decision.selected, reason: 'selected' };
+    }
+    const sortedCandidates = [...decision.candidates].sort((a, b) => b.score - a.score || a.agentId.localeCompare(b.agentId));
+    for (const candidate of sortedCandidates) {
+        if (agentRegistry[candidate.agentId]) {
+            return { agentId: candidate.agentId, reason: 'top_candidate' };
+        }
+    }
+    if (opts.fallbackAgentId && agentRegistry[opts.fallbackAgentId]) {
+        return { agentId: opts.fallbackAgentId, reason: 'fallback' };
+    }
+    const defaultAgentId = Object.keys(agentRegistry).sort()[0];
+    if (defaultAgentId) {
+        return { agentId: defaultAgentId, reason: 'fallback' };
+    }
+    return { agentId: '', reason: 'fallback' };
+}

package/dist/routing_profile.d.ts

@@ -0,0 +1,19 @@
+import type { AgentDefinitionV1 } from './agent.js';
+import type { Pack } from './pack.js';
+export interface AgentRoutingProfileV1 {
+    agentId: string;
+    namespace?: string;
+    heading?: string;
+    description?: string;
+    tags: string[];
+    examples: string[];
+    capabilities: string[];
+    toolPolicy?: unknown;
+    toolPolicySummary?: {
+        mode: 'allow_all' | 'deny_all' | 'mixed' | 'unknown';
+        allowed?: string[];
+        denied?: string[];
+    };
+}
+export declare function getAgentRoutingProfileV1(agent: AgentDefinitionV1): AgentRoutingProfileV1;
+export declare function getPackRoutingProfilesV1(pack: Pack): AgentRoutingProfileV1[];

package/dist/routing_profile.js

@@ -0,0 +1,102 @@
+const MAX_DISCOVERABILITY_ITEMS = 20;
+export function getAgentRoutingProfileV1(agent) {
+    const metadata = agent.metadata ?? {};
+    const heading = getStringMetadata(metadata, 'heading');
+    const namespace = getPrimaryNamespace(agent);
+    return {
+        agentId: agent.id,
+        namespace,
+        heading,
+        description: agent.description,
+        tags: parseDiscoverabilityList(metadata.tags),
+        examples: parseDiscoverabilityList(metadata.examples),
+        capabilities: parseDiscoverabilityList(metadata.capabilities),
+        toolPolicy: agent.toolPolicy,
+        toolPolicySummary: summarizeToolPolicy(agent.toolPolicy),
+    };
+}
+export function getPackRoutingProfilesV1(pack) {
+    const agents = pack.meta.agents?.agents ?? [];
+    return agents.map((agent) => getAgentRoutingProfileV1(agent));
+}
+function getPrimaryNamespace(agent) {
+    const first = agent.retrievalDefaults.namespace[0];
+    if (typeof first === 'string' && first.trim()) {
+        return first;
+    }
+    return undefined;
+}
+function getStringMetadata(metadata, key) {
+    const value = metadata[key];
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized ? normalized : undefined;
+}
+function parseDiscoverabilityList(value) {
+    if (typeof value !== 'string')
+        return [];
+    const raw = value.trim();
+    if (!raw)
+        return [];
+    let parsed;
+    if (raw.startsWith('[')) {
+        parsed = parseJsonArrayString(raw);
+    }
+    else if (raw.includes('\n')) {
+        parsed = raw.split('\n');
+    }
+    else {
+        parsed = raw.split(',');
+    }
+    const deduped = [];
+    const seen = new Set();
+    for (const item of parsed) {
+        const normalized = item.trim();
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        deduped.push(normalized);
+        if (deduped.length >= MAX_DISCOVERABILITY_ITEMS)
+            break;
+    }
+    return deduped;
+}
+function parseJsonArrayString(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((item) => typeof item === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+function summarizeToolPolicy(policy) {
+    if (!policy) {
+        return {
+            mode: 'allow_all',
+        };
+    }
+    if (!Array.isArray(policy.tools)) {
+        return {
+            mode: 'unknown',
+        };
+    }
+    if (policy.mode === 'allow') {
+        return {
+            mode: 'mixed',
+            allowed: policy.tools,
+        };
+    }
+    if (policy.mode === 'deny') {
+        return {
+            mode: 'mixed',
+            denied: policy.tools,
+        };
+    }
+    return {
+        mode: 'unknown',
+    };
+}

package/dist/tool_gate.d.ts

@@ -0,0 +1,3 @@
+import { type AgentDefinitionV1 } from './agent.js';
+import { type ToolCallV1 } from './tools.js';
+export declare function assertToolCallAllowed(agent: AgentDefinitionV1, call: ToolCallV1): void;

package/dist/tool_gate.js

@@ -0,0 +1,8 @@
+import { assertToolAllowed } from './agent.js';
+import { isToolCallV1 } from './tools.js';
+export function assertToolCallAllowed(agent, call) {
+    if (!isToolCallV1(call)) {
+        throw new Error('tool call must be a valid ToolCallV1 object.');
+    }
+    assertToolAllowed(agent, call.tool);
+}

package/dist/tool_parse.d.ts

@@ -0,0 +1,2 @@
+import { type ToolCallV1 } from './tools.js';
+export declare function parseToolCallV1FromText(text: string): ToolCallV1 | null;

package/dist/tool_parse.js

@@ -0,0 +1,102 @@
+import { isToolCallV1 } from './tools.js';
+function tryParseJson(input) {
+    try {
+        return JSON.parse(input);
+    }
+    catch {
+        return null;
+    }
+}
+function findBalancedJsonObject(text) {
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (char === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            continue;
+        }
+        if (char === '{') {
+            if (depth === 0)
+                start = i;
+            depth += 1;
+            continue;
+        }
+        if (char === '}') {
+            if (depth === 0)
+                continue;
+            depth -= 1;
+            if (depth === 0 && start >= 0) {
+                return text.slice(start, i + 1);
+            }
+        }
+    }
+    return null;
+}
+function parseToolCallCandidate(candidate) {
+    const value = tryParseJson(candidate);
+    return isToolCallV1(value) ? value : null;
+}
+function parseFromFencedBlock(text) {
+    const fencedRegex = /```(?:json)?\s*([\s\S]*?)```/gi;
+    let match;
+    while ((match = fencedRegex.exec(text)) !== null) {
+        const parsed = parseToolCallCandidate(match[1].trim());
+        if (parsed)
+            return parsed;
+    }
+    return null;
+}
+function parseFromMarkerLine(text) {
+    const lines = text.split(/\r?\n/);
+    for (const line of lines) {
+        const markerIndex = line.indexOf('TOOL_CALL:');
+        if (markerIndex === -1)
+            continue;
+        const tail = line.slice(markerIndex + 'TOOL_CALL:'.length).trim();
+        if (!tail)
+            continue;
+        const objectText = findBalancedJsonObject(tail) ?? tail;
+        const parsed = parseToolCallCandidate(objectText);
+        if (parsed)
+            return parsed;
+    }
+    return null;
+}
+function parseFirstJsonObject(text) {
+    const objectText = findBalancedJsonObject(text);
+    if (!objectText)
+        return null;
+    return tryParseJson(objectText);
+}
+export function parseToolCallV1FromText(text) {
+    if (typeof text !== 'string' || !text.trim())
+        return null;
+    const whole = parseToolCallCandidate(text.trim());
+    if (whole)
+        return whole;
+    const fenced = parseFromFencedBlock(text);
+    if (fenced)
+        return fenced;
+    const marker = parseFromMarkerLine(text);
+    if (marker)
+        return marker;
+    const firstObject = parseFirstJsonObject(text);
+    return isToolCallV1(firstObject) ? firstObject : null;
+}

package/dist/tools.d.ts

@@ -0,0 +1,27 @@
+export type ToolId = string;
+export interface ToolCallV1 {
+    type: 'tool_call';
+    callId: string;
+    tool: ToolId;
+    args: Record<string, unknown>;
+}
+export interface ToolResultErrorV1 {
+    message: string;
+    code?: string;
+    details?: unknown;
+}
+export interface ToolResultV1 {
+    type: 'tool_result';
+    callId: string;
+    tool: ToolId;
+    ok: boolean;
+    output?: unknown;
+    error?: ToolResultErrorV1;
+}
+export interface ToolSpecV1 {
+    id: ToolId;
+    description?: string;
+    jsonSchema?: unknown;
+}
+export declare function isToolCallV1(x: unknown): x is ToolCallV1;
+export declare function isToolResultV1(x: unknown): x is ToolResultV1;

package/dist/tools.js

@@ -0,0 +1,34 @@
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+export function isToolCallV1(x) {
+    if (!isPlainObject(x))
+        return false;
+    return (x.type === 'tool_call' &&
+        typeof x.callId === 'string' &&
+        x.callId.trim().length > 0 &&
+        typeof x.tool === 'string' &&
+        x.tool.trim().length > 0 &&
+        isPlainObject(x.args));
+}
+export function isToolResultV1(x) {
+    if (!isPlainObject(x))
+        return false;
+    if (x.type !== 'tool_result' ||
+        typeof x.callId !== 'string' ||
+        x.callId.trim().length === 0 ||
+        typeof x.tool !== 'string' ||
+        x.tool.trim().length === 0 ||
+        typeof x.ok !== 'boolean') {
+        return false;
+    }
+    if (x.ok) {
+        return x.error === undefined;
+    }
+    return (isPlainObject(x.error) &&
+        typeof x.error.message === 'string' &&
+        x.error.message.trim().length > 0);
+}

package/dist/trace.d.ts

@@ -0,0 +1,45 @@
+import type { ToolCallV1, ToolResultV1 } from './tools.js';
+import type { RouteDecisionV1 } from './router.js';
+export type TraceEventV1 = {
+    type: 'route.requested';
+    ts: string;
+    text: string;
+    agentCount: number;
+} | {
+    type: 'route.decided';
+    ts: string;
+    decision: RouteDecisionV1;
+    selectedAgentId: string;
+} | {
+    type: 'agent.selected';
+    ts: string;
+    agentId: string;
+    namespace?: string;
+} | {
+    type: 'prompt.resolved';
+    ts: string;
+    agentId: string;
+    promptHash?: string;
+    patchKeys?: string[];
+} | {
+    type: 'tool.requested';
+    ts: string;
+    agentId: string;
+    call: ToolCallV1;
+} | {
+    type: 'tool.executed';
+    ts: string;
+    agentId: string;
+    result: ToolResultV1;
+    durationMs?: number;
+} | {
+    type: 'run.completed';
+    ts: string;
+    agentId: string;
+    status: 'ok' | 'error';
+};
+export declare function nowIso(): string;
+export declare function createTrace(): {
+    events: TraceEventV1[];
+    push(e: TraceEventV1): void;
+};

package/dist/trace.js

@@ -0,0 +1,12 @@
+export function nowIso() {
+    return new Date().toISOString();
+}
+export function createTrace() {
+    const events = [];
+    return {
+        events,
+        push(e) {
+            events.push(e);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knolo-core",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "type": "module",
   "description": "Local-first knowledge packs for small LLMs.",
   "keywords": [