@arnilo/prism 0.2.9 → 0.3.1

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## [0.3.1] - 2026-08-29
+
+> Root + 28 changed packages move to 0.3.1 in the plan 039 changed-package cut; `@arnilo/prism-rag` moves 0.3.1 → 0.3.2; `@arnilo/prism-obscura` publishes new at 0.3.0. Distinct from the 2026-08-26 rag/memory/otel 0.3.1 patch below (independent Decision B tags).
+
+### Added
+- `@arnilo/prism-obscura` (new workspace package, 0.3.0): optional Obscura headless-browser engine over a **host-installed** binary — fail-closed `spawnObscuraProcess` lifecycle (absolute shell-free command, Docker argv, bounded readiness, group close), `createObscuraMcpTools` bridging the complete advertised MCP surface (reads effect-free; mutations and unknown future tools exclusive/serialized; `obscura_` prefix; loopback-default HTTP), `connectObscuraCdp` managed/external CDP + Playwright `connectOverCDP` composition, and `createObscuraWebTools` (standard `web_search`/`web_fetch` through one replaceable HTML search profile plus native `obscura_fetch`/`obscura_scrape`; public-HTTP(S)-only URL validation, byte/count/timeout caps, `allowEval`-gated custom expressions, untrusted-content labeling). Deliberately omitted from `prism-all`/`prism-base`/`prism-sdk` umbrella profiles — installation does not supply the binary/image; consumers install it explicitly.
+- Cross-host conformance (`scripts/obscura-host-conformance.test.mjs`, wired into `npm test`): the same Obscura `ToolDefinition[]` executes through core agent sessions, the Prism MCP server, the server handler, AG-UI, ACP, workflow nodes, supervisor children, and Antigravity delegated exposure — no host branch; host authorization/selection deny before execution; abort kills owned children.
+- New required peers: `@arnilo/prism-obscura` peers `@arnilo/prism` and `@arnilo/prism-web-tools` (reused citation/normalized shapes; `WebProvider` widened with `"obscura"`); `@arnilo/prism-obscura` also peers `@arnilo/prism-mcp`, `@arnilo/prism-browser`, and optional `playwright-core@1.61.0`.
+
+## [0.3.1] - 2026-08-26
+
+### Added
+- **Release 0.3.1 (plan 034)** is the first Decision B independent patch: only `@arnilo/prism-rag`, `@arnilo/prism-memory`, and `@arnilo/prism-observability-opentelemetry` move `0.3.0 → 0.3.1`. Internal `^0.3.0` ranges stay valid; root and every other workspace package stay at their pre-plan versions. Production RAG engine (P1–P8):
+  - **P1 transactional pgvector store** — `createPostgresVectorStore` (standalone) plus the existing `createPostgresMemoryStores().vectorStore` now implement `getBySource` + `transaction`. Additive DDL: `embedder_id` / `content_hash` / `generation`, `text_tsv` + GIN, HNSW when the embedding dimension is pinned, per-scope generation pointer table. Host names schema/table and owns the knowledge database.
+  - **P2 hybrid retrieve** — `retrieveContext({ lexical: "fts" | "bm25" | "off" })` fuses vector + lexical legs with RRF (`fusion: "rrf"`, `rrfK` 60 / cap 1,000). Provenance `retrieval` is `vector` | `lexical` | `hybrid`. Stores advertise `lexicalModes`; unsupported `bm25` fails closed. `fuseReciprocalRank` / `tokenizeLexical` exported.
+  - **P3 embedder identity** — `Embedder.id` is required and stamped as `embedderId`. Retrieve fails closed with `ERR_PRISM_RAG_EMBEDDER_MISMATCH` on id/dimension drift or legacy rows without an id (re-index path named). **TypeScript break for Embedder implementers** — add `readonly id: string`; see `docs/migration.md` `0.3.0 → 0.3.1`.
+  - **P4 content-hash skip** — `replaceSource({ contentHash })` skips unchanged sources (`{ indexed: 0, skipped: true }`) and reuses embeddings when chunk text matches (`reuseEmbeddings`, `isValidContentHash`).
+  - **P5 heading metadata** — `chunkMarkdown` stamps `metadata.heading` (parent-first ATX stack) unless the caller supplied one; parser metadata (`page`, `section`, …) copies onto chunks.
+  - **P6 generation visibility** — `replaceSource` bumps a scope-level generation; retrieval filters to the current generation (legacy generation-less rows stay visible). `getCurrentGeneration` / `setCurrentGeneration` support rollback.
+  - **P7 RAG telemetry** — dependency-free `RagTelemetry` seam; `createRagTelemetry()` in the OpenTelemetry package maps the `rag_request` / `rag_index` span tree. Span-name + `rag.*` allow-list drops raw chunk text.
+  - **P8 TEI reranker** — `createTeiReranker({ baseUrl })` posts `{query, texts, raw_scores:false}` to host TEI `/rerank`, permutation-only, fail-closed parse, 65,536-byte ceiling, `pinnedFetch` default. SSRF/URL policy stays host-side.
+  - **multi-scope retrieve** — `retrieveContext({ scopes: [org, user, session] })` embeds once, runs per-scope vector/lexical legs, fuses with one RRF, reranks once, and cuts `topK`. `scope` still valid; empty `scopes` returns zero hits with no embed/search/rerank (host “no allowed corpora” path). `HARD_RETRIEVE_SCOPE_CAP` is 8. Provenance carries `tenantId`/`resourceId`/`corpusId`. Telemetry: `rag.scope_count` + chunk tenant/corpus.
+- Compat baselines regenerated (`--update-baseline`). Scanner sees additive exports only; the Embedder.id implementer break is documented, not a name-level removal. No `--allow-break`. Publication remains the operator handoff (`docs/release-and-install.md` `0.3.1 independent RAG engine patch` — package tags `@arnilo/prism-memory@0.3.1`, `@arnilo/prism-rag@0.3.1`, `@arnilo/prism-observability-opentelemetry@0.3.1`).
+
+### Changed
+- Store compatibility with 0.3.0: **compatible, additive**. New columns/indexes/tables are `IF NOT EXISTS`; 0.3.0 rows remain readable. Rollback = restore the 0.3.0 package versions (generation-less retrieve still works; heading/hash/telemetry/TEI simply disappear). No root/core persisted-shape change.
+
+## [0.3.0] - 2026-08-20
+
+### Added
+- **Release 0.3.0 (plans 030, 031)** is the final lockstep cut and first independent-versioning line. The graph contains 57 publishable manifests; internal first-party ranges use `^0.3.0`, Decision B permits changed packages to patch/minor independently inside `<0.4.0`, and later publication uses `@arnilo/<package>@<version>` tags.
+- Optional `@arnilo/prism-antigravity-agent` delegates autonomous coding sessions to the official Google Antigravity CLI (`agy`) with per-run loopback HTTP MCP capability exposure, AG-UI timeline projection, secret redaction, and `--conversation` continuation. Host owns the official binary and `agy login` authentication state.
+- Optional `@arnilo/prism-computer-use-linux` wraps a host-owned Linux `computer-use-linux` MCP binary. DeviceAdapter admission is deny-by-default, setup tools are opt-in, mutating calls require approval/ExecutionPolicy, results are bounded and untrusted, input is serialized, and the package is omitted from umbrellas.
+- Coding/ACP closeouts: `read.findText`, visible fuzzy edit outcomes and nearby miss context, ACP editor-buffer filesystem operations, spawnable per-session coding registries, and delete/move result locations.
+
+### Changed
+- Release automation keeps explicit `--lockstep --version 0.3.0` for the final cut, then defaults to changed-package validation/publication and package tags. No Changesets or new core runtime dependency.
+- No persisted store migration. Live-service canaries and delegated Cursor adapter remain later demand-gated 0.3.x work.
+
 ## [0.2.9] - 2026-08-19
 
 ### Changed

package/README.md

@@ -4,7 +4,9 @@
 bring their tools, providers, credentials, storage, and UI; Prism supplies the
 common contracts, registries, agent/session runtime, replaceable input/prompt
 and compaction strategies, CLI/RPC adapters, and first-party provider/compaction
-packages. Prism defines contracts, not apps.
+packages. The current 0.3.0 line contains 56 publishable manifests, including
+optional Linux desktop control and independent package versioning after the final
+lockstep cut. Prism defines contracts, not apps.
 
 ## Current scope
 
@@ -18,9 +20,10 @@ packages. Prism defines contracts, not apps.
   OpenAI/OpenRouter use best-effort explicit cache hints, NeuralWatt uses
   best-effort implicit prefix caching, and other providers have route/model-specific
   or no cache-control support; see [docs/provider-caching.md](docs/provider-caching.md).
-- **First-party packages**: fourteen provider adapters, two compaction strategies,
+- **First-party packages**: seventeen provider adapters, two compaction strategies,
   coding tools/security, JSON Schema validation, MCP, workflows, OpenTelemetry,
-  encrypted credentials, SQLite/PostgreSQL persistence, and manifest-only install profiles.
+  encrypted credentials, SQLite/PostgreSQL persistence, Linux desktop control,
+  and manifest-only install profiles.
 - **Tools, context, skills**: host-owned tool registry with allow/deny filtering
   and dispatch, context providers, and a skill registry with progressive
   disclosure.
@@ -56,7 +59,7 @@ npm install @arnilo/prism @arnilo/prism-provider-openai    # core + one provider
 npm install @arnilo/prism-base                              # core + compaction + validation
 npm install @arnilo/prism-code @arnilo/prism-provider-openai # coding-agent profile
 npm install @arnilo/prism-sdk @arnilo/prism-provider-openai  # application profile
-npm install @arnilo/prism-all                               # broad umbrella (21 direct / 44 transitive packages)
+npm install @arnilo/prism-all                               # broad umbrella (21 direct / 47 workspace packages)
 npm install @arnilo/prism-server @arnilo/prism-workflows    # optional Web API boundary
 npm install @arnilo/prism-supervisor                         # optional local delegation + A2A 1.0
 npm install @arnilo/prism-web-tools                          # optional bounded Brave/Exa/Firecrawl research
@@ -168,6 +171,10 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | `@arnilo/prism-provider-vertex` | Google Vertex provider |
 | `@arnilo/prism-provider-ai-sdk` | AI SDK interoperability adapter |
 | `@arnilo/prism-browser` | optional host-wired Playwright browser automation (not core; not auto-activated) |
+| `@arnilo/prism-obscura` | optional Obscura headless-browser engine over a host-installed binary: MCP surface, CDP + Playwright, bounded CLI web tools (not in umbrellas; install explicitly) |
+| `@arnilo/prism-computer-use-linux` | optional Linux desktop-control tools over a host-owned `computer-use-linux` MCP binary |
+| `@arnilo/prism-antigravity-agent` | optional Antigravity CLI delegated agent adapter with per-run Prism MCP capability exposure |
+| `@arnilo/prism-wiki` | optional Karpathy LLM Wiki knowledge compiler with local `qmd` hybrid search and Context7 line navigation |
 | `@arnilo/prism-compaction-llm` | provider-backed compaction strategy |
 | `@arnilo/prism-compaction-observational-memory` | source-backed memory + recall tool |
 | `@arnilo/prism-coding-agent` | bounded shell/read/write/edit tools |
@@ -186,7 +193,7 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | `@arnilo/prism-base` | profile: core + compaction + JSON Schema validation |
 | `@arnilo/prism-code` | profile: base + coding tools/security + MCP |
 | `@arnilo/prism-sdk` | profile: base + workflows + MCP + credentials + OpenTelemetry |
-| `@arnilo/prism-all` | broad umbrella: 21 first-party packages (47 transitive) across runtime, capability, provider, and persistence — omits document-reader, OpenAPI tools, NATS, Caveman, Ponytail, and Impeccable |
+| `@arnilo/prism-all` | broad umbrella: 21 first-party packages (47 transitive) across a 47-package workspace closure — omits document-reader, OpenAPI tools, NATS, Caveman, Ponytail, Impeccable, computer-use-linux, antigravity-agent, Graft, Obscura, and wiki |
 
 ## Scripts
 

package/dist/agent-loops.js

@@ -80,12 +80,29 @@ export function generateValidateReviseLoop(opts) {
     const max = opts.maxRevisions ?? 3;
     const repairer = opts.repairer ?? defaultRepairer();
     const finalOnly = opts.structuredOutputTiming === "final-turn-only" && opts.toolCalls === "bounded";
-    // ponytail: per-run state hoisted to factory scope so snapshot/restore can capture it;
-    // resolveLoop invokes this factory once per run, so there is no cross-run leakage.
+    // ponytail: keep only current-run state in this strategy so snapshot/restore can capture it;
+    // supplied strategy instances may be reused, so a new non-restored run resets these locals.
     let attempts = 0;
     let artifactPhase = !finalOnly;
     let savedSchema;
     let pendingHistory = [];
+    let stateOwner;
+    let restoredStatePending = false;
+    const resetState = () => {
+        attempts = 0;
+        artifactPhase = !finalOnly;
+        savedSchema = undefined;
+        pendingHistory = [];
+    };
+    const prepareRunState = (ctx) => {
+        const sameRun = stateOwner?.sessionId === ctx.sessionId && stateOwner.runId === ctx.runId;
+        if (!sameRun) {
+            if (!restoredStatePending)
+                resetState();
+            stateOwner = { sessionId: ctx.sessionId, runId: ctx.runId };
+        }
+        restoredStatePending = false;
+    };
     return {
         name: "generate-validate-revise",
         revision: "1",
@@ -108,8 +125,10 @@ export function generateValidateReviseLoop(opts) {
             // Repair messages were appended to the session before suspension, so the rebuilt
             // history already carries them; re-applying pendingHistory would duplicate them.
             pendingHistory = [];
+            restoredStatePending = true;
         },
         async run(ctx) {
+            prepareRunState(ctx);
             let usage;
             let nextInput = ctx.input;
             let toolRounds = 0;
@@ -260,17 +279,35 @@ export async function dispatchToolCallsInOrder(calls, ctx) {
     }
     const results = new Array(calls.length);
     let nextIndex = 0;
+    let stopped = false;
+    let firstFailure;
+    const recordFailure = (error) => {
+        if (stopped)
+            return;
+        stopped = true;
+        firstFailure = error;
+    };
     const workers = Array.from({ length: concurrency }, async () => {
         for (;;) {
-            throwIfAborted(ctx.signal);
-            const index = nextIndex;
-            nextIndex += 1;
-            if (index >= calls.length)
+            if (stopped)
                 return;
-            results[index] = await ctx.dispatchToolCall(calls[index]);
+            try {
+                throwIfAborted(ctx.signal);
+                const index = nextIndex;
+                nextIndex += 1;
+                if (index >= calls.length)
+                    return;
+                results[index] = await ctx.dispatchToolCall(calls[index]);
+            }
+            catch (error) {
+                recordFailure(error);
+                return;
+            }
         }
     });
-    await Promise.all(workers);
+    await Promise.allSettled(workers);
+    if (stopped)
+        throw firstFailure;
     for (const result of results) {
         throwIfAborted(ctx.signal);
         if (!result)

package/dist/agent-session/helpers.js

@@ -142,10 +142,10 @@ export function throwIfAbortedSignal(signal) {
     if (signal?.aborted)
         throw signal.reason instanceof Error ? signal.reason : new Error("Agent run aborted");
 }
-const jsonTextEncoder = new TextEncoder();
 export function jsonBytes(value) {
     try {
-        return jsonTextEncoder.encode(JSON.stringify(value)).byteLength;
+        const serialized = JSON.stringify(value);
+        return serialized === undefined ? 0 : Buffer.byteLength(serialized, "utf8");
     }
     catch {
         throw new TypeError("Provider request or event must be JSON-serializable for run limits");

package/dist/cache-helpers.d.ts

@@ -23,6 +23,17 @@ export interface CacheUsageReport {
 export declare function sanitizeCacheKey(value: string | undefined, maxLength: number): string | undefined;
 export declare function mapCacheRetention(retention: CacheRetention | undefined, model: ModelConfig): "short" | "long" | undefined;
 export declare function applyCacheControl(messages: readonly Message[], breakpoints: readonly PromptCacheBreakpoint[], options?: ApplyCacheControlOptions): readonly CacheControlledMessage[];
+export interface SystemCacheControlTextBlock {
+    readonly type: "text";
+    readonly text: string;
+    readonly cache_control?: CacheControlValue;
+}
+/**
+ * Provider-style `system` field: plain joined string by default; native text
+ * blocks only when cache-control markers must survive (system_prompt breakpoints).
+ */
+export declare function systemCacheControlField(messages: readonly CacheControlledMessage[], toText: (message: Message) => string): string | readonly SystemCacheControlTextBlock[] | undefined;
 export declare function cacheHitRate(usage: Usage | undefined): number | undefined;
 export declare function cacheSavings(usage: Usage | undefined, model: ModelConfig): number | undefined;
 export declare function cacheUsageReport(usage: Usage | undefined, model?: ModelConfig): CacheUsageReport | undefined;
+export declare function resolveBreakpoint(messages: readonly Message[], breakpoint: PromptCacheBreakpoint): number;

package/dist/cache-helpers.js

@@ -1,8 +1,15 @@
 export function sanitizeCacheKey(value, maxLength) {
-    const key = value
-        ?.replace(/[^A-Za-z0-9_.:-]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, Math.max(0, maxLength));
+    const replaced = value?.replace(/[^A-Za-z0-9_.:-]+/g, "-");
+    if (!replaced)
+        return undefined;
+    // Index/slice edge trim instead of the `/^-+|-+$/g` alternation (CodeQL js/polynomial-redos, alert 22).
+    let start = 0;
+    let end = replaced.length;
+    while (start < end && replaced.charCodeAt(start) === 45)
+        start += 1;
+    while (end > start && replaced.charCodeAt(end - 1) === 45)
+        end -= 1;
+    const key = replaced.slice(start, end).slice(0, Math.max(0, maxLength));
     return key || undefined;
 }
 export function mapCacheRetention(retention, model) {
@@ -29,6 +36,23 @@ export function applyCacheControl(messages, breakpoints, options = {}) {
         return { ...message, content };
     });
 }
+/**
+ * Provider-style `system` field: plain joined string by default; native text
+ * blocks only when cache-control markers must survive (system_prompt breakpoints).
+ */
+export function systemCacheControlField(messages, toText) {
+    const system = messages.filter((message) => message.role === "system");
+    if (!system.length)
+        return undefined;
+    if (!system.some((message) => message.content.some((block) => block.cache_control))) {
+        return system.map(toText).join("\n\n") || undefined;
+    }
+    return system.map((message) => {
+        const cache_control = message.content.find((block) => block.cache_control)?.cache_control;
+        const block = { type: "text", text: toText(message) };
+        return cache_control ? { ...block, cache_control } : block;
+    });
+}
 export function cacheHitRate(usage) {
     const read = usage?.cacheReadTokens;
     const input = usage?.inputTokens;
@@ -54,7 +78,7 @@ export function cacheUsageReport(usage, model) {
         currency: estimatedSavings === undefined ? usage.currency : (model?.cost?.currency ?? usage.currency),
     };
 }
-function resolveBreakpoint(messages, breakpoint) {
+export function resolveBreakpoint(messages, breakpoint) {
     switch (breakpoint.location) {
         case "system_prompt":
             return messages.findIndex((message) => message.role === "system");

package/dist/cli-provider-add.js

@@ -2,6 +2,7 @@ import { accessSync, constants as fsConstants } from "node:fs";
 import { access, mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export class ProviderAddUsageError extends Error {
 }
 const NPM_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
@@ -208,7 +209,7 @@ function buildTokens(input) {
         __PROVIDER_PASCAL__: pascal,
         __PACKAGE_NAME__: input.name,
         __PRISM_VERSION__: input.version,
-        __BASE_URL__: input.baseUrl.replace(/\/+$/, ""),
+        __BASE_URL__: trimTrailingSlashes(input.baseUrl),
         __ENV_KEY__: input.envKey,
         __MODEL_ID__: input.model,
     };

package/dist/context-budget.js

@@ -20,7 +20,7 @@ export function estimateTextTokens(text) {
     return Math.ceil(text.length / 4);
 }
 export function estimateTextBytes(text) {
-    return new TextEncoder().encode(text).byteLength;
+    return Buffer.byteLength(text, "utf8");
 }
 export function estimateMessageTokens(message) {
     return estimateTextTokens(messageText(message));
@@ -64,11 +64,12 @@ export function applyContextBudget(options) {
     const tools = options.tools ? [...options.tools] : undefined;
     const omitted = [];
     const demotedBodies = new Set();
+    const historyCursor = { index: 0 };
     // Measure once, then subtract each dropped item's own estimate (dropNext computes it
     // with the same estimators) — avoids an O(n²) re-scan of the full keep-set per drop.
     const kept = measureAll(groups, context, skills, tools, skillContext, demotedBodies);
     while (overBudget(kept, budget)) {
-        const drop = dropNext(groups, context, skills, layout, skillContext, demotedBodies);
+        const drop = dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor);
         if (!drop) {
             throw new ContextBudgetError();
         }
@@ -77,6 +78,8 @@ export function applyContextBudget(options) {
         if (omitted.length < HARD_MAX_CONTEXT_BUDGET_OMISSIONS)
             omitted.push(drop);
     }
+    if (historyCursor.index > 0)
+        groups.history = groups.history.slice(historyCursor.index);
     const reportOmissions = omitted.slice(0, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS);
     return {
         groups,
@@ -94,8 +97,8 @@ export function applyContextBudget(options) {
         },
     };
 }
-function dropNext(groups, context, skills, layout, skillContext, demotedBodies) {
-    // ponytail: drop droppable groups in layout order; within history, drop oldest first (shift).
+function dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor) {
+    // ponytail: drop droppable groups in layout order; within history, advance a cursor and slice once.
     // cache_aware keeps attachments longer so stable prefix stays intact while budget still allows it.
     const order = layout === "cache_aware"
         ? ["tool_results", "history", "summaries", "context", "skills", "attachments"]
@@ -105,8 +108,8 @@ function dropNext(groups, context, skills, layout, skillContext, demotedBodies)
             const message = groups.toolResults.pop();
             return omission("tool_results", message.id ?? toolResultId(message), message);
         }
-        if (kind === "history" && groups.history.length > 0) {
-            const message = groups.history.shift();
+        if (kind === "history" && historyCursor.index < groups.history.length) {
+            const message = groups.history[historyCursor.index++];
             return omission("history", message.id, message);
         }
         if (kind === "summaries" && groups.summaries.length > 0) {

package/dist/contracts-core/agent.d.ts

@@ -225,6 +225,8 @@ export interface PromptBuilder {
 }
 export interface PromptBuildRequest {
     readonly messages: readonly Message[];
+    /** Input layout selected by the host; the default builder uses cache-aware ordering unless legacy is explicit. */
+    readonly inputLayout?: InputAssemblyLayout;
     readonly context?: readonly ContextBlock[];
     readonly skills?: readonly Skill[];
     readonly skillsDisclosure?: import("../skill-disclosure.js").SkillsDisclosure;

package/dist/contracts-core/provider.d.ts

@@ -11,6 +11,8 @@ export interface ModelCacheCapabilities {
     readonly maxBreakpoints?: number;
     readonly minCacheableTokens?: number;
     readonly longRetention?: boolean;
+    /** Model accepts explicit per-block cache breakpoints (e.g. OpenAI GPT-5.6+ `prompt_cache_breakpoint`). */
+    readonly explicitBreakpoints?: boolean;
 }
 export type PromptCacheMode = "auto" | "on" | "off";
 export type PromptCacheBreakpointLocation = "system_prompt" | "tools" | "stable_context" | "last_stable_message" | "last_user_message" | "message_id";

package/dist/contracts-protocol.d.ts

@@ -108,6 +108,36 @@ export interface ToolExecutionMetadata {
     readonly durationMs: number;
     readonly status: ToolCallStatus;
 }
+export type DelegatedAgentStepState = "active" | "done" | "error";
+export type DelegatedAgentStepKind = "assistant" | "tool" | "subagent" | "checkpoint" | "unknown";
+/** Token counters only; delegated adapters must never put thought text in this shape. */
+export interface DelegatedAgentStepUsage {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly thinkingTokens?: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly totalTokens?: number;
+}
+/** Safe delegated timeline metadata. Raw arguments, results, paths, URIs, and event bodies are not fields. */
+export interface DelegatedAgentStep {
+    readonly type: "delegated_agent_step";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly adapterId: string;
+    readonly externalConversationId: string;
+    readonly stepIndex: number;
+    readonly state: DelegatedAgentStepState;
+    readonly kind: DelegatedAgentStepKind;
+    readonly durationMs?: number;
+    readonly usage?: DelegatedAgentStepUsage;
+    readonly toolName?: string;
+    readonly subagentType?: string;
+    readonly detail?: {
+        readonly referenceId?: string;
+        readonly label?: string;
+    };
+}
 export type AgentFinishReason = "turn_limit" | "token_limit" | "refusal";
 export type AgentEvent = {
     readonly type: "agent_started";
@@ -176,7 +206,7 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly message: Message;
-} | {
+} | DelegatedAgentStep | {
     readonly type: "tool_execution_started";
     readonly sessionId: string;
     readonly runId: string;

package/dist/delegated-agent-step.d.ts

@@ -0,0 +1,20 @@
+import type { DelegatedAgentStep } from "./contracts-protocol.js";
+export declare const MAX_DELEGATED_AGENT_EVENT_BYTES: number;
+export declare const MAX_DELEGATED_AGENT_ID_BYTES = 512;
+export declare const MAX_DELEGATED_AGENT_NAME_BYTES = 256;
+export declare const MAX_DELEGATED_AGENT_STEP_INDEX = 1000000;
+export declare const MAX_DELEGATED_AGENT_DURATION_MS: number;
+export declare const MAX_DELEGATED_AGENT_TOKEN_COUNT = 1000000000000;
+export interface DelegatedAgentStepInput extends Omit<DelegatedAgentStep, "type" | "kind" | "state"> {
+    readonly kind: string;
+    readonly state: string;
+}
+export declare class DelegatedAgentStepError extends Error {
+    readonly code = "ERR_PRISM_DELEGATED_AGENT_STEP";
+    constructor(message: string);
+}
+/**
+ * Builds the only safe core shape for delegated timeline metadata. Unknown step
+ * kinds become `unknown`; unbounded or malformed identity/counter fields fail closed.
+ */
+export declare function createDelegatedAgentStep(input: DelegatedAgentStepInput): DelegatedAgentStep;

package/dist/delegated-agent-step.js

@@ -0,0 +1,99 @@
+export const MAX_DELEGATED_AGENT_EVENT_BYTES = 64 * 1024;
+export const MAX_DELEGATED_AGENT_ID_BYTES = 512;
+export const MAX_DELEGATED_AGENT_NAME_BYTES = 256;
+export const MAX_DELEGATED_AGENT_STEP_INDEX = 1_000_000;
+export const MAX_DELEGATED_AGENT_DURATION_MS = 24 * 60 * 60 * 1000;
+export const MAX_DELEGATED_AGENT_TOKEN_COUNT = 1_000_000_000_000;
+export class DelegatedAgentStepError extends Error {
+    code = "ERR_PRISM_DELEGATED_AGENT_STEP";
+    constructor(message) {
+        super(message);
+        this.name = "DelegatedAgentStepError";
+    }
+}
+/**
+ * Builds the only safe core shape for delegated timeline metadata. Unknown step
+ * kinds become `unknown`; unbounded or malformed identity/counter fields fail closed.
+ */
+export function createDelegatedAgentStep(input) {
+    if (!input || typeof input !== "object")
+        throw invalid("event");
+    const state = input.state;
+    if (state !== "active" && state !== "done" && state !== "error")
+        throw invalid("state");
+    const kind = normalizeKind(input.kind);
+    if (!Number.isSafeInteger(input.stepIndex) || input.stepIndex < 0 || input.stepIndex > MAX_DELEGATED_AGENT_STEP_INDEX) {
+        throw invalid("stepIndex");
+    }
+    const event = {
+        type: "delegated_agent_step",
+        sessionId: boundedText(input.sessionId, "sessionId", MAX_DELEGATED_AGENT_ID_BYTES),
+        runId: boundedText(input.runId, "runId", MAX_DELEGATED_AGENT_ID_BYTES),
+        adapterId: boundedText(input.adapterId, "adapterId", MAX_DELEGATED_AGENT_ID_BYTES),
+        externalConversationId: boundedText(input.externalConversationId, "externalConversationId", MAX_DELEGATED_AGENT_ID_BYTES),
+        stepIndex: input.stepIndex,
+        state,
+        kind,
+        ...(input.durationMs === undefined
+            ? {}
+            : { durationMs: boundedNumber(input.durationMs, "durationMs", MAX_DELEGATED_AGENT_DURATION_MS) }),
+        ...(input.usage === undefined ? {} : { usage: normalizeUsage(input.usage) }),
+        ...(input.toolName === undefined ? {} : { toolName: boundedText(input.toolName, "toolName", MAX_DELEGATED_AGENT_NAME_BYTES) }),
+        ...(input.subagentType === undefined
+            ? {}
+            : { subagentType: boundedText(input.subagentType, "subagentType", MAX_DELEGATED_AGENT_NAME_BYTES) }),
+        ...(input.detail === undefined ? {} : { detail: normalizeDetail(input.detail) }),
+    };
+    if (utf8Bytes(JSON.stringify(event)) > MAX_DELEGATED_AGENT_EVENT_BYTES)
+        throw invalid("event bytes");
+    return event;
+}
+function normalizeKind(value) {
+    return value === "assistant" || value === "tool" || value === "subagent" || value === "checkpoint" || value === "unknown"
+        ? value
+        : "unknown";
+}
+function normalizeUsage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw invalid("usage");
+    const output = {};
+    for (const key of ["inputTokens", "outputTokens", "thinkingTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens"]) {
+        const amount = value[key];
+        if (amount === undefined)
+            continue;
+        output[key] = boundedNumber(amount, key, MAX_DELEGATED_AGENT_TOKEN_COUNT);
+    }
+    return output;
+}
+function normalizeDetail(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw invalid("detail");
+    const referenceId = value.referenceId === undefined ? undefined : boundedOpaque(value.referenceId, "detail.referenceId", MAX_DELEGATED_AGENT_ID_BYTES);
+    const label = value.label === undefined ? undefined : boundedText(value.label, "detail.label", MAX_DELEGATED_AGENT_NAME_BYTES);
+    return {
+        ...(referenceId === undefined ? {} : { referenceId }),
+        ...(label === undefined ? {} : { label }),
+    };
+}
+function boundedText(value, name, maxBytes) {
+    if (typeof value !== "string" || value.length === 0 || /[\0\r\n]/.test(value) || utf8Bytes(value) > maxBytes)
+        throw invalid(name);
+    return value;
+}
+function boundedOpaque(value, name, maxBytes) {
+    if (typeof value !== "string" || /[\\/:]/.test(value))
+        throw invalid(name);
+    return boundedText(value, name, maxBytes);
+}
+function boundedNumber(value, name, max) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > max)
+        throw invalid(name);
+    return value;
+}
+function utf8Bytes(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function invalid(field) {
+    return new DelegatedAgentStepError(`Invalid delegated agent step ${field}`);
+}
+//# sourceMappingURL=delegated-agent-step.js.map

package/dist/event-multiplexer.js

@@ -119,10 +119,6 @@ export function createEventMultiplexer(options = {}) {
         isClosed = true;
         options.signal?.removeEventListener("abort", abort);
         finishSources();
-        queue.length = 0;
-        // Free the single-consumer slot: a consumer suspended at a yield may never pull
-        // again, and after close a fresh subscriber terminates immediately anyway.
-        activeConsumer = false;
         if (waiter) {
             const resolve = waiter;
             waiter = undefined;

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream }
 export type { ArtifactApproval, ArtifactApprovalState, ArtifactBodyErrorCode, ArtifactBodyPresignOptions, ArtifactBodyRef, ArtifactBodyStore, ArtifactBodyTransferOptions, ArtifactCitation, ArtifactDecisionState, ArtifactDeliveryToken, ArtifactRecord, ArtifactRevision, } from "./artifacts.js";
 export { ARTIFACT_BODY_ERROR_CODES, ARTIFACT_CHECKPOINT_NAMESPACE, ArtifactBodyStoreError, ArtifactError, artifactApprovalState, artifactCheckpointKey, } from "./artifacts.js";
 export type { ApplyCacheControlOptions, CacheControlledContentBlock, CacheControlledMessage, CacheControlValue, CacheUsageReport, } from "./cache-helpers.js";
-export { applyCacheControl, cacheHitRate, cacheSavings, cacheUsageReport, mapCacheRetention, sanitizeCacheKey } from "./cache-helpers.js";
+export { applyCacheControl, cacheHitRate, cacheSavings, cacheUsageReport, mapCacheRetention, resolveBreakpoint, sanitizeCacheKey, systemCacheControlField, } from "./cache-helpers.js";
 export type { CacheTelemetry, CacheTelemetryOptions, CacheTelemetryReport, CacheTelemetrySample, } from "./cache-telemetry.js";
 export { CACHE_TELEMETRY_OVERFLOW_KEY, CacheTelemetryError, createCacheTelemetry, DEFAULT_CACHE_TELEMETRY_CAP, } from "./cache-telemetry.js";
 export type { MemoryCheckpointStoreOptions } from "./checkpoints.js";
@@ -33,6 +33,8 @@ export type { ConversationBranchRef, ConversationReplayCursor, ConversationThrea
 export { CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, decodeConversationReplayCursor, encodeConversationReplayCursor, HARD_MAX_CONVERSATION_CURSOR_BYTES, } from "./conversations.js";
 export type { CredentialRecord, CredentialValueSource, MemoryCredentialStore, RevocableOAuthCredentialStore } from "./credentials.js";
 export { createChainedCredentialResolver, createEnvCredentialResolver, createExplicitCredentialResolver, createMemoryCredentialStore, refreshOAuthCredential, resolveCredentialValue, revokeOAuthCredential, } from "./credentials.js";
+export type { DelegatedAgentStepInput } from "./delegated-agent-step.js";
+export { createDelegatedAgentStep, DelegatedAgentStepError, MAX_DELEGATED_AGENT_DURATION_MS, MAX_DELEGATED_AGENT_EVENT_BYTES, MAX_DELEGATED_AGENT_ID_BYTES, MAX_DELEGATED_AGENT_NAME_BYTES, MAX_DELEGATED_AGENT_STEP_INDEX, MAX_DELEGATED_AGENT_TOKEN_COUNT, } from "./delegated-agent-step.js";
 export type { DeviceAdapter, DeviceAdmitRequest, DeviceChunkResult, DeviceConformanceResult, DeviceKind, DevicePolicyErrorCode, DevicePolicyOptions, DeviceStreamLimits, ResolvedDevicePolicy, } from "./devices.js";
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
 export type { EventMultiplexer, EventMultiplexerOptions, EventOverflowInfo, EventOverflowPolicy } from "./event-multiplexer.js";
@@ -71,6 +73,7 @@ export { providerContentDelta, providerContinuationRequired, providerDone, provi
 export { authMethodKey, defineProviderPackage, systemPromptContributionKey } from "./provider-packages.js";
 export type { SessionCachePolicyOptions } from "./provider-request-policy.js";
 export { createProviderRequestPolicyChain, createSessionCachePolicy, mergeProviderRequestOptions } from "./provider-request-policy.js";
+export { canonicalizeJsonSchema } from "./providers/schema.js";
 export type { ProviderRegistry, ProviderRegistryOptions } from "./providers.js";
 export { createProviderRegistry, createProviderResolver } from "./providers.js";
 export type { SecretRedactor } from "./redaction.js";
@@ -108,8 +111,9 @@ export type { FoldToolResultsContext, ResolvedToolResultFoldOptions, ToolResultF
 export { DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS, DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES, foldedToolResultHeader, foldToolResultHistory, foldToolResults, formatFoldedToolResult, HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, resolveToolResultFold, TOOL_RESULT_FOLD_TURN_METADATA_KEY, } from "./tool-result-fold.js";
 export type { DispatchToolCallOptions, ToolArgumentValidationError, ToolArgumentValidationResult, ToolArgumentValidator, ToolFilter, ToolFilterInput, ToolParameterValidatorOptions, ToolRegistryOptions, ToolValidator, } from "./tools.js";
 export { createToolParameterValidator, createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
+export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.2.9";
+export declare const version = "0.3.1";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -5,7 +5,7 @@ export { createAgentRunLifecycle } from "./agent-run-lifecycle.js";
 export { AGENT_RUN_STATE_NAMESPACE, AGENT_RUN_STATE_SCHEMA_VERSION, agentFingerprint, DEFAULT_MAX_AGENT_RUN_STATE_BYTES, HARD_MAX_AGENT_RUN_STATE_BYTES, loadAgentRunState, } from "./agent-run-state.js";
 export { createAgent, createAgentSession, resumeAgentRun, resumeAgentRunStream } from "./agents.js";
 export { ARTIFACT_BODY_ERROR_CODES, ARTIFACT_CHECKPOINT_NAMESPACE, ArtifactBodyStoreError, ArtifactError, artifactApprovalState, artifactCheckpointKey, } from "./artifacts.js";
-export { applyCacheControl, cacheHitRate, cacheSavings, cacheUsageReport, mapCacheRetention, sanitizeCacheKey } from "./cache-helpers.js";
+export { applyCacheControl, cacheHitRate, cacheSavings, cacheUsageReport, mapCacheRetention, resolveBreakpoint, sanitizeCacheKey, systemCacheControlField, } from "./cache-helpers.js";
 export { CACHE_TELEMETRY_OVERFLOW_KEY, CacheTelemetryError, createCacheTelemetry, DEFAULT_CACHE_TELEMETRY_CAP, } from "./cache-telemetry.js";
 export { CHECKPOINT_CONFLICT_CODE, CheckpointConflictError, createMemoryCheckpointStore } from "./checkpoints.js";
 export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compaction.js";
@@ -17,6 +17,7 @@ export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
 export { CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, decodeConversationReplayCursor, encodeConversationReplayCursor, HARD_MAX_CONVERSATION_CURSOR_BYTES, } from "./conversations.js";
 export { createChainedCredentialResolver, createEnvCredentialResolver, createExplicitCredentialResolver, createMemoryCredentialStore, refreshOAuthCredential, resolveCredentialValue, revokeOAuthCredential, } from "./credentials.js";
+export { createDelegatedAgentStep, DelegatedAgentStepError, MAX_DELEGATED_AGENT_DURATION_MS, MAX_DELEGATED_AGENT_EVENT_BYTES, MAX_DELEGATED_AGENT_ID_BYTES, MAX_DELEGATED_AGENT_NAME_BYTES, MAX_DELEGATED_AGENT_STEP_INDEX, MAX_DELEGATED_AGENT_TOKEN_COUNT, } from "./delegated-agent-step.js";
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
 export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
@@ -39,6 +40,7 @@ export { boundResponse, defaultResolver, isLoopbackAddress, isLoopbackHostname,
 export { providerContentDelta, providerContinuationRequired, providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallContent, toolCallFromArgumentsText, } from "./provider-events.js";
 export { authMethodKey, defineProviderPackage, systemPromptContributionKey } from "./provider-packages.js";
 export { createProviderRequestPolicyChain, createSessionCachePolicy, mergeProviderRequestOptions } from "./provider-request-policy.js";
+export { canonicalizeJsonSchema } from "./providers/schema.js";
 export { createProviderRegistry, createProviderResolver } from "./providers.js";
 export { createSecretRedactor, errorToErrorInfo, redactAgentEvent, redactMessage, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry, resolveRedactor, } from "./redaction.js";
 export { loadBinaryResource, loadJsonResource, loadManifestResource, loadTextResource } from "./resources.js";
@@ -59,8 +61,9 @@ export { applyThinkingLevel, isThinkingLevel, normalizeThinkingLevel, THINKING_L
 export { createMemoryToolEffectStore, ToolEffectError } from "./tool-effects.js";
 export { DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS, DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES, foldedToolResultHeader, foldToolResultHistory, foldToolResults, formatFoldedToolResult, HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, resolveToolResultFold, TOOL_RESULT_FOLD_TURN_METADATA_KEY, } from "./tool-result-fold.js";
 export { createToolParameterValidator, createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
+export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.2.9";
+export const version = "0.3.1";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map