@warlock.js/ai-panoptic 5.34.2 → 5.35.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@warlock.js/ai-panoptic` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.34.3 - 2026-10-20
+
+### Changed
+
+- Condensed the package agent skill description to at most 450 characters, with API names and package routing guidance.
+
 ## 5.34.2 - 2026-10-19
 
 ### Fixed

package/llms-full.txt

@@ -7,7 +7,7 @@
 ## Package orientation
 
 ---
-description: "Observability for @warlock.js/ai: turns agent, workflow and team run reports into traces and ships them to OpenTelemetry, Langfuse, file, console or a local dashboard. Exports `panoptic`, `createCollector`, `createInMemoryTraceStore`, `otelExporter`, `langfuseExporter`, `consoleExporter`, `fileExporter`, `dashboard`. Use for: trace an agent run, see token cost and latency per span, send traces to Langfuse or OTel, query past traces, open a local trace viewer, evaluate a system prompt. Not this package: plain logging → @warlock.js/logger; building agents → @warlock.js/ai; provider adapters → ai-<provider> packages."
+description: 'AI tracing, usage, cost analysis and dashboards: `panoptic`, `createCollector`, `createInMemoryTraceStore`, `consoleExporter`, `otelExporter`, `langfuseExporter` and `dashboard`. Use for "trace an agent run", "compare prompt costs", "export spans" or "inspect the AI dashboard". Not this package → @warlock.js/ai for running agents and evals; @warlock.js/logger for logs; @warlock.js/devtools for HTTP debugging.'
 ---
 
 # @warlock.js/ai-panoptic
@@ -30,7 +30,7 @@ Panoptic subscribes to the execution reports every `@warlock.js/ai` primitive al
 - `@opentelemetry/*` and `langfuse` are optional; install only the one you export to.
 
 
-## evaluate-system-prompt  `@warlock.js/ai-panoptic/evaluate-system-prompt/SKILL.md`
+## evaluate-system-prompt  `@warlock.js/ai-panoptic/skills/evaluate-system-prompt/SKILL.md`
 
 ---
 name: evaluate-system-prompt
@@ -124,7 +124,7 @@ curl -X POST 'http://127.0.0.1:4319/api/traces/tr_1/spans/sp_1/evaluate' \
 - `ai.prompts().validate({ criteria })` in `@warlock.js/ai` — the sibling capability this reuses: grading raw prompt TEXT you already have in code, no trace or dashboard involved.
 
 
-## export-traces  `@warlock.js/ai-panoptic/export-traces/SKILL.md`
+## export-traces  `@warlock.js/ai-panoptic/skills/export-traces/SKILL.md`
 
 ---
 name: export-traces
@@ -320,7 +320,7 @@ Reach for `reportToTrace` when you already hold a finished `result.report` and w
 - The `run-ai-agent` topic of the `warlock-js-ai` skill — running the agent and the `BaseReport` shape Panoptic projects into a `Trace`.
 
 
-## observe-with-panoptic  `@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`
+## observe-with-panoptic  `@warlock.js/ai-panoptic/skills/observe-with-panoptic/SKILL.md`
 
 ---
 name: observe-with-panoptic
@@ -534,7 +534,7 @@ remain absent; do not infer semantic-cache hits from zero tokens. An incomplete
 run is identified by its status or normalized `AGENT_INCOMPLETE` error code.
 
 
-## query-traces  `@warlock.js/ai-panoptic/query-traces/SKILL.md`
+## query-traces  `@warlock.js/ai-panoptic/skills/query-traces/SKILL.md`
 
 ---
 name: query-traces
@@ -788,7 +788,7 @@ panel does not clear application trace history. Enable flow observation first;
 installing the viewer alone does not collect runs.
 
 
-## use-local-dashboard  `@warlock.js/ai-panoptic/use-local-dashboard/SKILL.md`
+## use-local-dashboard  `@warlock.js/ai-panoptic/skills/use-local-dashboard/SKILL.md`
 
 ---
 name: use-local-dashboard

package/llms.txt

@@ -6,9 +6,9 @@
 
 ## Skills
 
-- [Package orientation](@warlock.js/ai-panoptic/skills/index.md): Observability for @warlock.js/ai: turns agent, workflow and team run reports into traces and ships them to OpenTelemetry, Langfuse, file, console or a local dashboard. Exports `panoptic`, `createCollector`, `createInMemoryTraceStore`, `otelExporter`, `langfuseExporter`, `consoleExporter`, `fileExporter`, `dashboard`. Use for: trace an agent run, see token cost and latency per span, send traces to Langfuse or OTel, query past traces, open a local trace viewer, evaluate a system prompt. Not this package: plain logging → @warlock.js/logger; building agents → @warlock.js/ai; provider adapters → ai-<provider> packages.
-- [evaluate-system-prompt](@warlock.js/ai-panoptic/evaluate-system-prompt/SKILL.md): Grade a single trace's LAST captured system prompt from the dashboard drawer — the dashboard's only write-capable feature, config-gated via `DashboardOptions.evaluate` (`ai.config({ panoptic: { dashboard: { evaluate: { model, instructions } } } })`). Triggers: `evaluate`, `EvaluateConfig`, `EvaluateVerdict`, `evaluateSystemPrompt`, `extractLastSystemPrompt`, `findSpanById`, "Evaluate system prompt" button, `POST .../spans/:spanId/evaluate`, grading a prompt from a real trace, judging a captured system prompt, per-run instructions override, judge model factory; 'evaluate this trace's prompt', 'grade the system prompt from the dashboard', 'judge a captured run', 'score a live system prompt'. Skip: grading raw prompt TEXT you already have in code (no trace involved) — `@warlock.js/ai`'s `ai.prompts().validate({ criteria })`, the same judge machinery this wraps; a DATASET of test cases run through an agent — `@warlock.js/ai`'s `ai.dataset` + `agent.eval`; viewing/filtering/grouping traces without grading them — the `use-local-dashboard` topic; capturing the content this feature reads — the `export-traces` topic (`captureContent`).
-- [export-traces](@warlock.js/ai-panoptic/export-traces/SKILL.md): Send @warlock.js/ai-panoptic traces to an observability backend via pluggable exporters, including capturing prompt/response content onto spans. Triggers: `consoleExporter`, `fileExporter`, `otelExporter`, `langfuseExporter`, `ExporterContract`, `ContentCaptureOptions`, `captureContent`, `redactContent`, `fullHistory`, `ContentRedactor`, `toGenAiAttributes`, `walkSpans`, `totalCostUsd`, `GEN_AI_ATTRIBUTES`, `WARLOCK_ATTRIBUTES`, `reportToTrace`, `reportToSpan`, `extractSpanAttributes`, `normalizeError`, `formatSpanLine`, `createPanopticMiddleware`; 'export AI traces to OpenTelemetry', 'send traces to Langfuse', 'log traces to console / a file', 'capture the full prompt/conversation onto a span', 'gen_ai semantic conventions', 'write a custom exporter'; typical import `import { otelExporter, langfuseExporter, consoleExporter, fileExporter } from "@warlock.js/ai-panoptic"`. Skip: wiring the subscriber/collector into a run — the `observe-with-panoptic` topic; the core report shape — the `run-ai-agent` topic of the `warlock-js-ai` skill.
-- [observe-with-panoptic](@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md): Wire @warlock.js/ai-panoptic into an agent/workflow/supervisor/orchestrator — declaratively via `ai.config({ panoptic })` (registers panoptic on core's Observer seam) or with the one-call `panoptic({ exporters })` subscriber. Triggers: `panoptic`, `Panoptic`, `PanopticOptions`, `PanopticConfig`, `ai.config({ panoptic })`, `observeAll`, per-flow `observe`, `FlowObserveOption`, `registerObserver`, `Observer`, `.attach`, `.middleware`, `.collect`, `.toTrace`, `observe.attach(agent)`, `panoptic().middleware()`, `completedEvents`, `middlewareName`; 'observe a warlock agent', 'trace an agent run', 'attach observability to a workflow/supervisor', 'observe every flow by default', 'add a tracing middleware', 'collect an orchestrator turn report', 'wire OTel/Langfuse into my agent'; typical import `import { ai } from "@warlock.js/ai"` + `import "@warlock.js/ai-panoptic"` (or `import { panoptic } from "@warlock.js/ai-panoptic"`). Skip: the zero-setup local dashboard — the `use-local-dashboard` topic; writing/choosing an exporter (the sink end) — the `export-traces` topic; the core report shape / running the agent itself — the `run-ai-agent` topic of the `warlock-js-ai` skill.
-- [query-traces](@warlock.js/ai-panoptic/query-traces/SKILL.md): Retain @warlock.js/ai-panoptic traces in a queryable store — in-memory, or cache-backed so they survive a process restart — and slice them after the fact: get one run by id, list a session, filter failed runs in a window, roll up usage + cost. Triggers: `createInMemoryTraceStore`, `createCacheTraceStore`, `CacheTraceStoreHandle`, `CacheTraceStoreOptions`, `CacheDriverInput`, `store.ready`, `TraceStoreContract`, `TraceQuery`, `TraceAggregate`, `InMemoryTraceStoreOptions`, `store.query`, `store.aggregate`, `store.get`, `store.add`, `store.clear`, `store.size`, `capacity`, `prefix`, `onError`, `sumUsage`, `emptyUsage`, `matchTrace`; 'query collected traces', 'aggregate AI cost per session', 'how much did this session spend', 'list failed runs', 'retain traces in memory', 'persist traces across a restart', 'cache-backed trace store', 'Redis trace store', 'roll up token usage'; typical import `import { createInMemoryTraceStore, createCacheTraceStore } from "@warlock.js/ai-panoptic"`. Skip: sending traces to an external backend (OTel/Langfuse/console/file) — the `export-traces` topic; wiring the subscriber into a run — the `observe-with-panoptic` topic.
-- [use-local-dashboard](@warlock.js/ai-panoptic/use-local-dashboard/SKILL.md): Run the zero-setup local Panoptic dashboard — a loopback `node:http` server over a trace store served from `ai.config({ panoptic: { dashboard } })`, with a two-pane call-tree + metadata UI (light/dark/system theme, search/filter, session + prompt-version grouping, cost heatmap, Gantt timeline, errors filter, hash deep-links) and an optional cache-backed persistent store. Triggers: `dashboard`, `DashboardOptions`, `DashboardHandle`, `ai.config({ panoptic })`, `panoptic.dashboard`, `panoptic.cache`, `port: 4319`, `basePath`, `open`, `authToken`, `allowedHosts`, `/api/traces`, `/api/aggregate`, `/api/traces/:id`, `createRequestHandler`, `dashboardHtml`, `sanitizeHref`, `ServeConfig`, `TraceStoreContract`, `createCacheTraceStore`, theme, dark mode, call tree, metadata panel, cost heatmap, timeline / Gantt, errors only, deep-link, group by session, prompt version, group by type, type stats panel, started / ended timestamps, team type; 'open a local AI trace dashboard', 'view agent traces in the browser', 'self-hosted panoptic UI', 'inspect traces without Langfuse', 'spin up a dev observability server', 'dark mode dashboard', 'persist traces across restart', 'group traces by session / prompt version / type', 'cost heatmap', 'timeline / waterfall view', 'filter failed runs in the dashboard', 'per-type stats panel', 'is the dashboard bearer token safe', 'markdown links XSS in trace content'; typical import `import { ai } from "@warlock.js/ai"` + `import "@warlock.js/ai-panoptic"`. Skip: shipping traces to a backend (OTel / Langfuse / file) — the `export-traces` topic; the queryable store API the dashboard reads — the `query-traces` topic; wiring the subscriber by hand — the `observe-with-panoptic` topic.
+- [Package orientation](@warlock.js/ai-panoptic/skills/index.md): AI tracing, usage, cost analysis and dashboards: `panoptic`, `createCollector`, `createInMemoryTraceStore`, `consoleExporter`, `otelExporter`, `langfuseExporter` and `dashboard`. Use for "trace an agent run", "compare prompt costs", "export spans" or "inspect the AI dashboard". Not this package → @warlock.js/ai for running agents and evals; @warlock.js/logger for logs; @warlock.js/devtools for HTTP debugging.
+- [evaluate-system-prompt](@warlock.js/ai-panoptic/skills/evaluate-system-prompt/SKILL.md): Grade a single trace's LAST captured system prompt from the dashboard drawer — the dashboard's only write-capable feature, config-gated via `DashboardOptions.evaluate` (`ai.config({ panoptic: { dashboard: { evaluate: { model, instructions } } } })`). Triggers: `evaluate`, `EvaluateConfig`, `EvaluateVerdict`, `evaluateSystemPrompt`, `extractLastSystemPrompt`, `findSpanById`, "Evaluate system prompt" button, `POST .../spans/:spanId/evaluate`, grading a prompt from a real trace, judging a captured system prompt, per-run instructions override, judge model factory; 'evaluate this trace's prompt', 'grade the system prompt from the dashboard', 'judge a captured run', 'score a live system prompt'. Skip: grading raw prompt TEXT you already have in code (no trace involved) — `@warlock.js/ai`'s `ai.prompts().validate({ criteria })`, the same judge machinery this wraps; a DATASET of test cases run through an agent — `@warlock.js/ai`'s `ai.dataset` + `agent.eval`; viewing/filtering/grouping traces without grading them — the `use-local-dashboard` topic; capturing the content this feature reads — the `export-traces` topic (`captureContent`).
+- [export-traces](@warlock.js/ai-panoptic/skills/export-traces/SKILL.md): Send @warlock.js/ai-panoptic traces to an observability backend via pluggable exporters, including capturing prompt/response content onto spans. Triggers: `consoleExporter`, `fileExporter`, `otelExporter`, `langfuseExporter`, `ExporterContract`, `ContentCaptureOptions`, `captureContent`, `redactContent`, `fullHistory`, `ContentRedactor`, `toGenAiAttributes`, `walkSpans`, `totalCostUsd`, `GEN_AI_ATTRIBUTES`, `WARLOCK_ATTRIBUTES`, `reportToTrace`, `reportToSpan`, `extractSpanAttributes`, `normalizeError`, `formatSpanLine`, `createPanopticMiddleware`; 'export AI traces to OpenTelemetry', 'send traces to Langfuse', 'log traces to console / a file', 'capture the full prompt/conversation onto a span', 'gen_ai semantic conventions', 'write a custom exporter'; typical import `import { otelExporter, langfuseExporter, consoleExporter, fileExporter } from "@warlock.js/ai-panoptic"`. Skip: wiring the subscriber/collector into a run — the `observe-with-panoptic` topic; the core report shape — the `run-ai-agent` topic of the `warlock-js-ai` skill.
+- [observe-with-panoptic](@warlock.js/ai-panoptic/skills/observe-with-panoptic/SKILL.md): Wire @warlock.js/ai-panoptic into an agent/workflow/supervisor/orchestrator — declaratively via `ai.config({ panoptic })` (registers panoptic on core's Observer seam) or with the one-call `panoptic({ exporters })` subscriber. Triggers: `panoptic`, `Panoptic`, `PanopticOptions`, `PanopticConfig`, `ai.config({ panoptic })`, `observeAll`, per-flow `observe`, `FlowObserveOption`, `registerObserver`, `Observer`, `.attach`, `.middleware`, `.collect`, `.toTrace`, `observe.attach(agent)`, `panoptic().middleware()`, `completedEvents`, `middlewareName`; 'observe a warlock agent', 'trace an agent run', 'attach observability to a workflow/supervisor', 'observe every flow by default', 'add a tracing middleware', 'collect an orchestrator turn report', 'wire OTel/Langfuse into my agent'; typical import `import { ai } from "@warlock.js/ai"` + `import "@warlock.js/ai-panoptic"` (or `import { panoptic } from "@warlock.js/ai-panoptic"`). Skip: the zero-setup local dashboard — the `use-local-dashboard` topic; writing/choosing an exporter (the sink end) — the `export-traces` topic; the core report shape / running the agent itself — the `run-ai-agent` topic of the `warlock-js-ai` skill.
+- [query-traces](@warlock.js/ai-panoptic/skills/query-traces/SKILL.md): Retain @warlock.js/ai-panoptic traces in a queryable store — in-memory, or cache-backed so they survive a process restart — and slice them after the fact: get one run by id, list a session, filter failed runs in a window, roll up usage + cost. Triggers: `createInMemoryTraceStore`, `createCacheTraceStore`, `CacheTraceStoreHandle`, `CacheTraceStoreOptions`, `CacheDriverInput`, `store.ready`, `TraceStoreContract`, `TraceQuery`, `TraceAggregate`, `InMemoryTraceStoreOptions`, `store.query`, `store.aggregate`, `store.get`, `store.add`, `store.clear`, `store.size`, `capacity`, `prefix`, `onError`, `sumUsage`, `emptyUsage`, `matchTrace`; 'query collected traces', 'aggregate AI cost per session', 'how much did this session spend', 'list failed runs', 'retain traces in memory', 'persist traces across a restart', 'cache-backed trace store', 'Redis trace store', 'roll up token usage'; typical import `import { createInMemoryTraceStore, createCacheTraceStore } from "@warlock.js/ai-panoptic"`. Skip: sending traces to an external backend (OTel/Langfuse/console/file) — the `export-traces` topic; wiring the subscriber into a run — the `observe-with-panoptic` topic.
+- [use-local-dashboard](@warlock.js/ai-panoptic/skills/use-local-dashboard/SKILL.md): Run the zero-setup local Panoptic dashboard — a loopback `node:http` server over a trace store served from `ai.config({ panoptic: { dashboard } })`, with a two-pane call-tree + metadata UI (light/dark/system theme, search/filter, session + prompt-version grouping, cost heatmap, Gantt timeline, errors filter, hash deep-links) and an optional cache-backed persistent store. Triggers: `dashboard`, `DashboardOptions`, `DashboardHandle`, `ai.config({ panoptic })`, `panoptic.dashboard`, `panoptic.cache`, `port: 4319`, `basePath`, `open`, `authToken`, `allowedHosts`, `/api/traces`, `/api/aggregate`, `/api/traces/:id`, `createRequestHandler`, `dashboardHtml`, `sanitizeHref`, `ServeConfig`, `TraceStoreContract`, `createCacheTraceStore`, theme, dark mode, call tree, metadata panel, cost heatmap, timeline / Gantt, errors only, deep-link, group by session, prompt version, group by type, type stats panel, started / ended timestamps, team type; 'open a local AI trace dashboard', 'view agent traces in the browser', 'self-hosted panoptic UI', 'inspect traces without Langfuse', 'spin up a dev observability server', 'dark mode dashboard', 'persist traces across restart', 'group traces by session / prompt version / type', 'cost heatmap', 'timeline / waterfall view', 'filter failed runs in the dashboard', 'per-type stats panel', 'is the dashboard bearer token safe', 'markdown links XSS in trace content'; typical import `import { ai } from "@warlock.js/ai"` + `import "@warlock.js/ai-panoptic"`. Skip: shipping traces to a backend (OTel / Langfuse / file) — the `export-traces` topic; the queryable store API the dashboard reads — the `query-traces` topic; wiring the subscriber by hand — the `observe-with-panoptic` topic.

package/package.json

@@ -19,9 +19,9 @@
   "peerDependencies": {
     "@opentelemetry/api": "*",
     "@opentelemetry/sdk-trace-base": "*",
-    "@warlock.js/ai": "5.34.2",
-    "@warlock.js/cache": "5.34.2",
-    "@warlock.js/logger": "5.34.2",
+    "@warlock.js/ai": "5.35.0",
+    "@warlock.js/cache": "5.35.0",
+    "@warlock.js/logger": "5.35.0",
     "langfuse": "*"
   },
   "peerDependenciesMeta": {
@@ -41,7 +41,7 @@
   "dependencies": {
     "langfuse": "^3.38.20"
   },
-  "version": "5.34.2",
+  "version": "5.35.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/index.md

@@ -1,5 +1,5 @@
 ---
-description: "Observability for @warlock.js/ai: turns agent, workflow and team run reports into traces and ships them to OpenTelemetry, Langfuse, file, console or a local dashboard. Exports `panoptic`, `createCollector`, `createInMemoryTraceStore`, `otelExporter`, `langfuseExporter`, `consoleExporter`, `fileExporter`, `dashboard`. Use for: trace an agent run, see token cost and latency per span, send traces to Langfuse or OTel, query past traces, open a local trace viewer, evaluate a system prompt. Not this package: plain logging → @warlock.js/logger; building agents → @warlock.js/ai; provider adapters → ai-<provider> packages."
+description: 'AI tracing, usage, cost analysis and dashboards: `panoptic`, `createCollector`, `createInMemoryTraceStore`, `consoleExporter`, `otelExporter`, `langfuseExporter` and `dashboard`. Use for "trace an agent run", "compare prompt costs", "export spans" or "inspect the AI dashboard". Not this package → @warlock.js/ai for running agents and evals; @warlock.js/logger for logs; @warlock.js/devtools for HTTP debugging.'
 ---
 
 # @warlock.js/ai-panoptic