@arnilo/prism 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,3 +1,71 @@
+## [0.3.2] - 2026-08-29 (plan 050)
+
+### Added
+- **OKF adoption (`@arnilo/prism-wiki`)**: wiki-init/refresh/lint emit and validate
+  OKF v0.2 bundles (Karpathy prompt retained). See `docs/wiki.md`.
+- **DOCS-1 (Clay integration findings)**: three integrator contracts, in place on
+  the pages that own them — resume-aware workflow nodes (`ctx.resume` or silent
+  re-suspend) in `docs/workflows.md`; supervisor child factories return `Agent`
+  not `AgentSession` (`SupervisorError: child "<id>" factory must return an
+  Agent, got <type>`) plus durable-store nested approvals in `docs/supervisors.md`;
+  task-boundary `session.compact()` fails closed during an active run in
+  `docs/compaction-and-retry.md`. Each block links `examples/autonomous-coding-loop.ts`.
+- **FEATURE-2 (Clay integration findings)**: documented bounded iterate-until-done
+  host-loop pattern in `docs/workflows.md` — one `runWorkflow` per iteration,
+  iteration state in workflow inputs, explicit termination predicate and budgets,
+  typed `BudgetExhaustedError` (fail-closed, never a hang), `replayWorkflow` per
+  iteration run id. Seeded by `examples/autonomous-coding-loop.ts`. Plan 045 `loop`
+  node remains the future in-graph primitive; this intake ships the docs+example
+  minimum only.
+- **FEATURE-6 (Clay integration findings)**: composite `examples/autonomous-coding-loop.ts`
+  conformance reference — goal → roadmap → per-task supervisor children (per-child
+  models) → `runCodingGoalVerify`-style validation → observational-memory attach +
+  task-boundary compact + recall → human gate with simulated restart → host-side
+  bounded iterate-until-done with deterministic budget exhaustion. Mock providers
+  only; no credentials or network.
+- **FEATURE-3 (Clay integration findings)**: host-opt-in command driver hooks.
+  `CommandExecutionContext` gains an optional `drivers?: CommandDrivers`
+  (`startRun` / `startWorkflow` / `steer` — typed minimal handles returning
+  `AgentRunResult`-shaped results / workflow run id + status) so a contributed
+  command can act through host-injected capabilities instead of being
+  re-implemented host-side. The RPC session factory accepts `drivers` and
+  forwards them at the single command-execution site; absent drivers leave
+  the context shape unchanged (no key, no allocation). Drivers are
+  host-injected capabilities, never package-supplied.
+### Fixed
+- **FEATURE-1 (Clay integration findings)**: `resolveAgentDefinition` no longer
+  throws `Agent "<name>" has no model` when the declarative definition omits
+  `model` but `context.overrides.model` supplies one — the fallback is a
+  single `??` at `buildBaseConfig`, the `create()` path is unchanged, and a
+  definition with neither source still fails closed.
+
+## [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

package/README.md

@@ -171,8 +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 |
@@ -191,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 a 47-package workspace closure — omits document-reader, OpenAPI tools, NATS, Caveman, Ponytail, Impeccable, computer-use-linux, and antigravity-agent |
+| `@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-definitions.js

@@ -20,7 +20,10 @@ export function resolveAgentDefinition(def, context) {
     return createAgent(applyConfigOverrides(baseConfig, context.overrides));
 }
 function buildBaseConfig(def, context) {
-    const model = resolveModel(def.name, def.model, context);
+    // Model precedence: explicit def.model wins; a definition without a model
+    // falls back to context.overrides.model (host-injected selection). Neither
+    // present still fails closed in resolveModel.
+    const model = resolveModel(def.name, def.model ?? context.overrides?.model, context);
     const tools = resolveTools(def.tools, context);
     const skills = resolveSkills(def.skills, tools, context);
     return {

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

@@ -1,7 +1,7 @@
 /** Contracts-core agent family (0.2.5 plan 025 Task 1 split).
  * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
-import type { InputAssemblyLayout, RunLedger, ToolDefinition, ToolEffectStore, ToolRegistry } from "../contracts-protocol.js";
-import type { AgentRunStateOptions, AgentSession } from "../contracts-run-state.js";
+import type { InputAssemblyLayout, RunLedger, RunOptions, ToolDefinition, ToolEffectStore, ToolRegistry } from "../contracts-protocol.js";
+import type { AgentRunResult, AgentRunStateOptions, AgentSession } from "../contracts-run-state.js";
 import type { ContributionRegistries } from "../contributions.js";
 import type { MiddlewareRegistry } from "../middleware.js";
 import type { SecretRedactor } from "../redaction.js";
@@ -147,6 +147,27 @@ export interface CommandExecutionContext {
     readonly runId?: string;
     readonly signal?: AbortSignal;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Host-injected driver capabilities (host-opt-in; never package-supplied).
+     *  Absent in hosts that don't supply them — commands stay inert data there. */
+    readonly drivers?: CommandDrivers;
+}
+/** Minimal run reference returned by {@link CommandDrivers.startWorkflow}. */
+export interface CommandWorkflowRun {
+    readonly runId: string;
+    readonly status: string;
+}
+/** Host-injected capabilities a contributed command may act through when the
+ *  host opts in. Drivers are supplied by the host at context construction
+ *  (e.g. the RPC session factory), never by packages; core only types and
+ *  forwards them. `metadata.trust` labeling is unaffected. */
+export interface CommandDrivers {
+    /** Start a session run. */
+    startRun(input: string, options?: RunOptions): Promise<AgentRunResult> | AgentRunResult;
+    /** Start a run on a host-understood orchestration definition. Returns at
+     *  minimum the run id and status; richer host shapes pass through as-is. */
+    startWorkflow(definition: object, input: unknown, options?: Readonly<Record<string, unknown>>): Promise<CommandWorkflowRun>;
+    /** Steer an active run with additional input. */
+    steer(runId: string, input: string): Promise<void> | void;
 }
 export interface CommandResult {
     readonly name: string;
@@ -225,6 +246,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/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,12 +33,12 @@ 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";
 export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.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 { DelegatedAgentStepInput } from "./delegated-agent-step.js";
 export type { ExecutionAction, ExecutionDecision, ExecutionPolicy, ExecutionRisk } from "./execution-policy.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
 export type { ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
@@ -73,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";
@@ -110,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.3.0";
+export declare const version = "0.3.2";
 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,9 +17,9 @@ 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 { 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 { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
 export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
@@ -40,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";
@@ -60,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.3.0";
+export const version = "0.3.2";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/input.js

@@ -41,16 +41,22 @@ export function createDefaultPromptBuilder() {
             // Tool-capable models receive schemas via request.tools; the text list only serves
             // text-only (or unknown-capability) models — duplicating it doubles tool tokens per turn.
             const tools = request.model?.capabilities?.tools === true ? undefined : request.tools;
-            return [
-                ...contextMessages(request.context),
-                ...buildSkillMessages(request.skills, {
-                    disclosure: request.skillsDisclosure,
-                    loaded: request.loadedSkills,
-                    demotedBodies: request.demotedSkillBodies?.length ? new Set(request.demotedSkillBodies) : undefined,
-                }),
-                ...toolMessages(tools),
-                ...request.messages,
-            ];
+            const context = contextMessages(request.context);
+            const skills = buildSkillMessages(request.skills, {
+                disclosure: request.skillsDisclosure,
+                loaded: request.loadedSkills,
+                demotedBodies: request.demotedSkillBodies?.length ? new Set(request.demotedSkillBodies) : undefined,
+            });
+            const declarations = toolMessages(tools);
+            if ((request.inputLayout ?? "cache_aware") === "legacy") {
+                return [...context, ...skills, ...declarations, ...request.messages];
+            }
+            // Default input assembly keeps stable instruction messages at the front. Keep that
+            // boundary ahead of dynamic context/skills; legacy retains the old whole-prompt order.
+            const firstNonSystem = request.messages.findIndex((message) => message.role !== "system");
+            const stable = firstNonSystem < 0 ? request.messages : request.messages.slice(0, firstNonSystem);
+            const dynamic = firstNonSystem < 0 ? [] : request.messages.slice(firstNonSystem);
+            return [...stable, ...context, ...skills, ...declarations, ...dynamic];
         },
     };
 }
@@ -165,6 +171,7 @@ export async function assembleProviderInput(options) {
     const promptRequest = options.middleware
         ? await options.middleware.run("prompt_build", {
             messages,
+            inputLayout: layout,
             context,
             skills,
             skillsDisclosure: options.skillsDisclosure,
@@ -176,6 +183,7 @@ export async function assembleProviderInput(options) {
         })
         : {
             messages,
+            inputLayout: layout,
             context,
             skills,
             skillsDisclosure: options.skillsDisclosure,
@@ -185,7 +193,7 @@ export async function assembleProviderInput(options) {
             metadata: options.metadata,
             signal: options.signal,
         };
-    const providerMessages = await promptBuilder.build({ ...promptRequest, tools, model: options.model });
+    const providerMessages = await promptBuilder.build({ ...promptRequest, inputLayout: layout, tools, model: options.model });
     assertMessagesSupportModelCapabilities(options.model, providerMessages);
     const metadata = budgetReport ? { ...options.metadata, [CONTEXT_BUDGET_REPORT_METADATA_KEY]: budgetReport } : options.metadata;
     return {

package/dist/node/session-store-jsonl.js

@@ -14,7 +14,9 @@ export function createJsonlSessionStore(pathOrOptions) {
     const idempotencySeen = new Set();
     return {
         append(entry, appendOptions) {
-            appendChain = appendChain.then(async () => {
+            const operation = appendChain
+                .catch(() => undefined)
+                .then(async () => {
                 if (options.createDirectory !== false)
                     await mkdir(dirname(path), { recursive: true });
                 const readResult = await readJsonlSessionEntries(path);
@@ -29,7 +31,8 @@ export function createJsonlSessionStore(pathOrOptions) {
                 if (dedupKey !== undefined && idempotencySeen.has(dedupKey)) {
                     throw new SessionAppendConflictError({ code: SESSION_APPEND_CONFLICT_CODE, idempotencyDuplicate: true });
                 }
-                if (appendOptions?.expectedParentId !== undefined && !entries.some((existing) => existing.id === appendOptions.expectedParentId)) {
+                if (appendOptions?.expectedParentId !== undefined &&
+                    !entries.some((existing) => existing.id === appendOptions.expectedParentId)) {
                     throw new SessionAppendConflictError({ code: SESSION_APPEND_CONFLICT_CODE, expectedParentId: appendOptions.expectedParentId });
                 }
                 if (entries.some((existing) => existing.id === entry.id))
@@ -38,7 +41,8 @@ export function createJsonlSessionStore(pathOrOptions) {
                     idempotencySeen.add(dedupKey);
                 await appendFile(path, `${JSON.stringify(entry)}\n`, "utf8");
             });
-            return appendChain;
+            appendChain = operation.catch(() => undefined);
+            return operation;
         },
         async list(sessionId) {
             return (await readEntries(path)).filter((entry) => entry.sessionId === sessionId);

package/dist/providers/openai-compatible.js

@@ -1,6 +1,7 @@
 import { resolveCredentialValue } from "../credentials.js";
 import { providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallFromArgumentsText, } from "../provider-events.js";
 import { assertStructuredOutputRequestSupported } from "../structured-output.js";
+import { trimTrailingSlashes } from "../trim-trailing-slashes.js";
 import { applyOpenAIChatStructuredOutput, assertOpenAIChatMessage, mapOpenAIChatUsage, serializeOpenAIChatMessage, serializeOpenAITool, } from "./openai-primitives.js";
 import { httpStatusError, ProviderTransportError, readBoundedResponseText, readSseEvents } from "./transport.js";
 /**
@@ -100,7 +101,7 @@ export function createOpenAICompatibleProvider(options) {
             try {
                 const url = typeof options.chatCompletionsUrl === "function"
                     ? options.chatCompletionsUrl(request)
-                    : (options.chatCompletionsUrl ?? `${options.baseUrl.replace(/\/+$/, "")}/chat/completions`);
+                    : (options.chatCompletionsUrl ?? `${trimTrailingSlashes(options.baseUrl)}/chat/completions`);
                 const authStyle = options.authStyle ?? "bearer";
                 const headers = {
                     ...Object.fromEntries(Object.entries(request.options?.headers ?? {}).filter((entry) => typeof entry[1] === "string")),