agentfootprint 2.6.4 → 2.7.1

package/AGENTS.md

@@ -426,7 +426,7 @@ agent.on('agentfootprint.agent.turn_end', (e) =>
   console.log(`[${e.payload.iterationCount} iter, ${e.payload.totalInputTokens}+${e.payload.totalOutputTokens} tokens]`));
 ```
 
-Wildcard `.on('agentfootprint.*', ...)` works. All events typed via `AgentfootprintEventMap`.
+Wildcards: `.on('*', ...)` for every event, or `.on('agentfootprint.<domain>.*', ...)` per-domain (`agent`, `stream`, `context`, `tools`, `memory`, `cost`, `error`, …). `'agentfootprint.*'` is NOT a valid pattern — the dispatcher accepts `'*'` or `'agentfootprint.<DOMAIN>.*'` only. All events typed via `AgentfootprintEventMap`.
 
 Recorders (auto-attached when relevant builder method is called):
 - `ContextRecorder` — `context.evaluated` / `context.injected` / `context.slot_composed`

package/CLAUDE.md

@@ -426,7 +426,7 @@ agent.on('agentfootprint.agent.turn_end', (e) =>
   console.log(`[${e.payload.iterationCount} iter, ${e.payload.totalInputTokens}+${e.payload.totalOutputTokens} tokens]`));
 ```
 
-Wildcard `.on('agentfootprint.*', ...)` works. All events typed via `AgentfootprintEventMap`.
+Wildcards: `.on('*', ...)` for every event, or `.on('agentfootprint.<domain>.*', ...)` per-domain (`agent`, `stream`, `context`, `tools`, `memory`, `cost`, `error`, …). `'agentfootprint.*'` is NOT a valid pattern — the dispatcher accepts `'*'` or `'agentfootprint.<DOMAIN>.*'` only. All events typed via `AgentfootprintEventMap`.
 
 Recorders (auto-attached when relevant builder method is called):
 - `ContextRecorder` — `context.evaluated` / `context.injected` / `context.slot_composed`

package/ai-instructions/claude-code/SKILL.md

@@ -367,8 +367,10 @@ agent.on('agentfootprint.stream.tool_start', (e) =>
 agent.on('agentfootprint.agent.turn_end', (e) =>
   console.log(`[${e.payload.iterationCount} iter, tokens=${e.payload.totalInputTokens}+${e.payload.totalOutputTokens}]`));
 
-// Wildcards work
-agent.on('agentfootprint.*', (e) => log(e));
+// Wildcards: '*' for every event, or 'agentfootprint.<domain>.*' per-domain.
+// 'agentfootprint.*' is NOT a valid pattern — silently matches nothing.
+agent.on('*', (e) => log(e));
+agent.on('agentfootprint.stream.*', (e) => log(e));
 ```
 
 ## Anti-patterns — Don't

package/dist/esm/status.js

@@ -0,0 +1,49 @@
+/**
+ * agentfootprint/status — chat-bubble status surface.
+ *
+ * Pattern: pure projection. `selectThinkingState` walks the typed
+ *          event log forward, tracking active pause / tool / LLM state,
+ *          and returns the CURRENT thinking state (or null when the
+ *          bubble should hide).
+ * Role:    Outer ring. Consumers (Lens, custom chat UIs, embedded
+ *          widgets) call this to drive a "what is the agent doing
+ *          right now?" indicator. Output feeds `renderThinkingLine`
+ *          which resolves a template + variables to a final string.
+ *
+ * Why a subpath:
+ *   - Consistent with `agentfootprint/observe` and
+ *     `agentfootprint/locales` — every observability surface gets its
+ *     own entry point.
+ *   - Self-documenting at the import line: `from 'agentfootprint/status'`
+ *     vs an opaque main-export grab.
+ *   - Future home for extended-thinking primitives (Anthropic
+ *     `thinking_delta` / `redacted_thinking` blocks). Adding them here
+ *     is non-breaking; consumers already importing from
+ *     `agentfootprint/status` get the new state surface for free.
+ *
+ * Back-compat: every export here is also re-exported from the main
+ * `agentfootprint` entry. Migrating consumers is mechanical (rewrite
+ * the import path); both paths work.
+ *
+ * State machine (4 states + null):
+ *
+ *      ┌──────────┐  llm.start, no tools yet
+ *  ────┤  idle    ├────────────────────────────► "Thinking…"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  stream.token chunks accumulate
+ *  ────┤streaming ├────────────────────────────► "{{partial}}"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  tool.start, no tool.end yet
+ *  ────┤   tool   ├────────────────────────────► "Working on `weather`…"
+ *      └──────────┘                               (or per-tool override)
+ *
+ *      ┌──────────┐  pause.request, no resume yet
+ *  ────┤  paused  ├────────────────────────────► "Waiting on you: …"
+ *      └──────────┘
+ *
+ *      (null)        run done / between calls   → bubble hidden
+ */
+export { defaultThinkingTemplates, selectThinkingState, renderThinkingLine, } from './recorders/observability/thinking/thinkingTemplates.js';
+//# sourceMappingURL=status.js.map

package/dist/esm/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,GAKnB,MAAM,yDAAyD,CAAC"}

package/dist/status.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * agentfootprint/status — chat-bubble status surface.
+ *
+ * Pattern: pure projection. `selectThinkingState` walks the typed
+ *          event log forward, tracking active pause / tool / LLM state,
+ *          and returns the CURRENT thinking state (or null when the
+ *          bubble should hide).
+ * Role:    Outer ring. Consumers (Lens, custom chat UIs, embedded
+ *          widgets) call this to drive a "what is the agent doing
+ *          right now?" indicator. Output feeds `renderThinkingLine`
+ *          which resolves a template + variables to a final string.
+ *
+ * Why a subpath:
+ *   - Consistent with `agentfootprint/observe` and
+ *     `agentfootprint/locales` — every observability surface gets its
+ *     own entry point.
+ *   - Self-documenting at the import line: `from 'agentfootprint/status'`
+ *     vs an opaque main-export grab.
+ *   - Future home for extended-thinking primitives (Anthropic
+ *     `thinking_delta` / `redacted_thinking` blocks). Adding them here
+ *     is non-breaking; consumers already importing from
+ *     `agentfootprint/status` get the new state surface for free.
+ *
+ * Back-compat: every export here is also re-exported from the main
+ * `agentfootprint` entry. Migrating consumers is mechanical (rewrite
+ * the import path); both paths work.
+ *
+ * State machine (4 states + null):
+ *
+ *      ┌──────────┐  llm.start, no tools yet
+ *  ────┤  idle    ├────────────────────────────► "Thinking…"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  stream.token chunks accumulate
+ *  ────┤streaming ├────────────────────────────► "{{partial}}"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  tool.start, no tool.end yet
+ *  ────┤   tool   ├────────────────────────────► "Working on `weather`…"
+ *      └──────────┘                               (or per-tool override)
+ *
+ *      ┌──────────┐  pause.request, no resume yet
+ *  ────┤  paused  ├────────────────────────────► "Waiting on you: …"
+ *      └──────────┘
+ *
+ *      (null)        run done / between calls   → bubble hidden
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderThinkingLine = exports.selectThinkingState = exports.defaultThinkingTemplates = void 0;
+var thinkingTemplates_js_1 = require("./recorders/observability/thinking/thinkingTemplates.js");
+Object.defineProperty(exports, "defaultThinkingTemplates", { enumerable: true, get: function () { return thinkingTemplates_js_1.defaultThinkingTemplates; } });
+Object.defineProperty(exports, "selectThinkingState", { enumerable: true, get: function () { return thinkingTemplates_js_1.selectThinkingState; } });
+Object.defineProperty(exports, "renderThinkingLine", { enumerable: true, get: function () { return thinkingTemplates_js_1.renderThinkingLine; } });
+//# sourceMappingURL=status.js.map

package/dist/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;;;AAEH,gGAQiE;AAP/D,gIAAA,wBAAwB,OAAA;AACxB,2HAAA,mBAAmB,OAAA;AACnB,0HAAA,kBAAkB,OAAA"}

package/dist/types/status.d.ts

@@ -0,0 +1,49 @@
+/**
+ * agentfootprint/status — chat-bubble status surface.
+ *
+ * Pattern: pure projection. `selectThinkingState` walks the typed
+ *          event log forward, tracking active pause / tool / LLM state,
+ *          and returns the CURRENT thinking state (or null when the
+ *          bubble should hide).
+ * Role:    Outer ring. Consumers (Lens, custom chat UIs, embedded
+ *          widgets) call this to drive a "what is the agent doing
+ *          right now?" indicator. Output feeds `renderThinkingLine`
+ *          which resolves a template + variables to a final string.
+ *
+ * Why a subpath:
+ *   - Consistent with `agentfootprint/observe` and
+ *     `agentfootprint/locales` — every observability surface gets its
+ *     own entry point.
+ *   - Self-documenting at the import line: `from 'agentfootprint/status'`
+ *     vs an opaque main-export grab.
+ *   - Future home for extended-thinking primitives (Anthropic
+ *     `thinking_delta` / `redacted_thinking` blocks). Adding them here
+ *     is non-breaking; consumers already importing from
+ *     `agentfootprint/status` get the new state surface for free.
+ *
+ * Back-compat: every export here is also re-exported from the main
+ * `agentfootprint` entry. Migrating consumers is mechanical (rewrite
+ * the import path); both paths work.
+ *
+ * State machine (4 states + null):
+ *
+ *      ┌──────────┐  llm.start, no tools yet
+ *  ────┤  idle    ├────────────────────────────► "Thinking…"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  stream.token chunks accumulate
+ *  ────┤streaming ├────────────────────────────► "{{partial}}"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  tool.start, no tool.end yet
+ *  ────┤   tool   ├────────────────────────────► "Working on `weather`…"
+ *      └──────────┘                               (or per-tool override)
+ *
+ *      ┌──────────┐  pause.request, no resume yet
+ *  ────┤  paused  ├────────────────────────────► "Waiting on you: …"
+ *      └──────────┘
+ *
+ *      (null)        run done / between calls   → bubble hidden
+ */
+export { defaultThinkingTemplates, selectThinkingState, renderThinkingLine, type ThinkingState, type ThinkingStateKind, type ThinkingTemplates, type ThinkingContext, } from './recorders/observability/thinking/thinkingTemplates.js';
+//# sourceMappingURL=status.d.ts.map

package/dist/types/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,yDAAyD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.6.4",
+  "version": "2.7.1",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -153,6 +153,11 @@
       "types": "./dist/types/locales/index.d.ts",
       "import": "./dist/esm/locales/index.js",
       "require": "./dist/locales/index.js"
+    },
+    "./status": {
+      "types": "./dist/types/status.d.ts",
+      "import": "./dist/esm/status.js",
+      "require": "./dist/status.js"
     }
   },
   "sideEffects": false,