@arnilo/prism 0.8.0 → 0.10.0

package/docs/tools.md

@@ -159,6 +159,23 @@ await session.run(input, { toolNames: ["web_search"] });
 
 Scope the active `ToolRegistry` (or declarative `AgentDefinition.tools`) at agent construction. `PermissionPolicy` / `RunOptions.validate` still fail closed at dispatch; `toolNames` only intersects that host-active set.
 
+### Per-turn tool narrowing
+
+`toolNarrowing` on `AgentConfig` / `RunOptions` (run wins) is an optional host callback invoked at `loopCtx.assemble` before each provider turn. It receives `{ turn, lastAssistantText?, toolIds }` and must return a subset of the run grant (`toolIds`). Unknown or extra names are dropped (restrictive-only); the runtime emits `tool_narrowing_clamped` with the dropped names and continues with the clamped set. A throw fails the turn — no partial schema is sent.
+
+This is not a middleware hook and not `RunOptions.tools`. `filterTools` on the run snapshot preserves run order, so identical consecutive subsets keep schema bytes identical (prompt-cache prefixes stay stable). Changing the subset rewrites tool schemas; pair with `toolsDisclosure: "search"` when the run set is large.
+
+Tools hidden this turn are not in the provider schema. They stay callable-by-name only when `allowHiddenToolCalls: true` (default off); otherwise dispatch blocks them with `tool_denied`. Each provider turn records `metadata.tools: { count, idsHash }` (hash of names in request order; no args) — see [Agent events](agent-events.md).
+
+```ts
+const agent = createAgent({
+  model, provider, tools,
+  toolNarrowing: async ({ turn, lastAssistantText, toolIds }) =>
+    plane === "knowledge" ? toolIds.filter((id) => id.startsWith("wiki.")) : toolIds,
+});
+await session.run(input, { toolNarrowing: async ({ toolIds }) => toolIds.slice(0, 4) });
+```
+
 ### Artifact-loop tools
 
 `generate-validate-revise` treats provider tools as inert by default. Set `loop.toolCalls: "bounded"` and `RunOptions.limits.maxToolRounds` only when an artifact needs a host-owned lookup before its next candidate. Each response with one-or-more calls consumes one shared round, dispatches calls sequentially through this exact `dispatchToolCall()` path, persists assistant-call then result transcript rows, and skips artifact parsing/validation for that response. A post-limit call executes nothing; the loop emits `artifact_failed` with `metadata.reason: "tool_round_limit"`. Tools do not consume `maxRevisions`, and tool schemas/context never grant authority.
@@ -280,7 +297,7 @@ Limits (mirroring the skill-disclosure DEFAULT/HARD cap pattern):
 
 ## Guardrails
 
-`DispatchToolCallOptions.guardrails` evaluates `tool_input` after `tool_call` middleware normalization and before lookup, permission, validation, execution policy, or side effect. `tool_output` evaluates raw completed results before redaction, event emission, ledger rows, and transcript append. A block returns a blocked result; tripwire fails the enclosing run. See [Guardrails](guardrails.md).
+`DispatchToolCallOptions.guardrails` evaluates `tool_input` after `tool_call` middleware normalization and before lookup, permission, validation, execution policy, or side effect. `tool_output` evaluates raw completed results before redaction, event emission, ledger rows, and transcript append. A block returns a blocked result; tripwire fails the enclosing run. A blocked call's `error.message` names the refusing rule — `Blocked by guardrail rule pack:<pack>/<rule>`, plus the pack's reason when it set one, bounded to 200 bytes and redacted; a hand-written guardrail keeps `Tool call blocked by guardrail` / `Tool result blocked by guardrail`. The `tool_execution_blocked` event carries the same text in `error.message` while its `reason` stays the machine code. See [Guardrails](guardrails.md).
 
 ## Related APIs
 

package/docs/wiki.md

@@ -45,7 +45,7 @@ The Karpathy LLM Wiki pattern is structured into 3 distinct tiers:
 
 - `/wiki-init`: Scaffolds `.wiki/`, instantiates `SCHEMA.md`, `index.md`, and `log.md`, deploys skills, and adds the `qmd` collection.
 - `/wiki-refresh`: Detects modified source files via SHA-256 Merkle diffing, compiles updates to affected entity pages, reconciles contradictions in `log.md`, and runs `qmd update`.
-- `/wiki-lint`: Checks OKF frontmatter (`type`, ISO `generated.at`), leftover `[[wikilinks]]`, unresolved relative markdown links, dead line anchors, and orphan pages.
+- `/wiki-lint`: Checks OKF frontmatter (`type`, ISO `generated.at`), leftover `[[wikilinks]]`, unresolved relative markdown links, dead line anchors, orphan pages, and pruned sources (an entity page whose raw sources were retired or deleted — reported for re-filing, never a failure).
 - `/wiki-ingest`: `{ text?, path?, url?, title? }` — stages one external source into `raw/ingest/<utc>-<slug>/` (`source.*` original + `extract.md`), then returns a brief (staged paths, extract preview, source URL when applicable, Karpathy filing checklist). When the host injects `drivers`, the command calls `drivers.startRun(brief, { activeSkills: ["wiki-maintainer"] })` so the maintainer skill files the source into the wiki; without drivers it stages only and reports `runStarted: false`. Results are labeled `metadata.trust: "untrusted_external"`.
 
 ### Standalone CLI Commands
@@ -57,7 +57,7 @@ npx prism-wiki init --profile codebase
 # Refresh wiki after code edits
 npx prism-wiki refresh
 
-# Check wiki health and dead anchors
+# Check wiki health: dead anchors, broken links, orphans, pruned sources
 npx prism-wiki lint
 
 # Search wiki from terminal
@@ -71,6 +71,8 @@ npx prism-wiki ingest --path notes/paper.pdf --title "Paper"
 npx prism-wiki ingest --url https://example.com/rfc.pdf   # → exit 1
 ```
 
+Lint output is one summary line plus per-issue detail, and the report shape is `{ deadAnchors, brokenLinks, orphans, gaps, prunedSources, ok }`. **Pruned sources are not a failure**: a page whose raw sources were retired (`retireWikiSources`), re-pointed to a path that does not exist, or deleted out-of-band is maintainer work, so it is reported as `prunedSources` entries (`{ page, missing }`, both workspace-relative, capped to the first few paths in command/CLI text) while the health check stays `ok` and the CLI exits 0. The `wiki-maintainer` skill covers the response: re-read the surviving sources and re-file the page, or delete it when none remain.
+
 ## Outputs / response / events
 
 - `wiki_search` returns a structured markdown payload containing section breadcrumbs, conceptual summaries, and clickable source line links (`file:///path#Lxx-Lyy`).

package/docs/workflows.md

@@ -88,11 +88,16 @@ All workflow limits and runtime `concurrency` reject non-safe integers, zero, ne
 | `runId` | Caller-supplied id; otherwise generated (`wfr_…`) |
 | `resume` | For suspended runs: `{ decision: "approve" | "deny", input?, expectedVersion }`; version is mandatory for an exact-once CAS claim |
 | `validateResume` | Host validator for resume input; required when `suspend()` declares `resumeSchema` |
+| `metadata` | Sidecar map (`Record<string, unknown>`) persisted on the checkpoint value; a resume that does not re-state it keeps the recorded map |
+| `restoreHooks` | External-state restore hooks (`CheckpointRestoreHook`) run sequentially on every resume before the scheduler writes; the first failure/timeout throws `CheckpointRestoreError` (`ERR_PRISM_CHECKPOINT_RESTORE`) and leaves the checkpoint untouched |
+| `restoreHookTimeoutMs` | Per-hook restore ceiling in ms; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS` (10 s) |
 | `validateState` | Host validator for every initial/restored/updated state; required when workflow declares `state.schema` |
 | `initialState` | Optional host initial state override; nested workflows receive parent state automatically |
 
 A function node returns `suspend({ reason, data?, resumeSchema? })` to persist `status: "suspended"`. Its next invocation receives `ctx.resume` only after an approved resume. `resumeWorkflow(workflow, { runId }, options)` validates schema/version/ownership/`definitionHash`, claims the checkpoint before node execution, and continues the suspended node. Denial persists terminal `denied` status without invoking it. Existing failed/aborted checkpoint resume remains available without a human decision.
 
+Restore hooks make the resume all-or-nothing across layers: workflow checkpoints carry the host's `metadata` (git commit, document version, workspace fingerprint), `restoreHooks` put each recorded layer back, and only when every hook succeeds does the scheduler claim the checkpoint and continue. Each hook receives `{ workflowId, runId, version, status, metadata, checkpoint }` and an `AbortSignal`; the successful run's `workflow_resumed` event carries `restore: { hooks: [{ hook, durationMs }], durationMs }`. No hooks ⇒ no hook call and no `restore` field.
+
 > **Contract — resume-aware nodes.** After an approved resume, the **same** node's `execute` is re-invoked with `ctx.resume`. Returning `suspend(...)` unconditionally re-suspends silently; downstream nodes never run. Branch on `ctx.resume`:
 >
 > ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -50,6 +50,10 @@
       "types": "./dist/testing/compaction-conformance.d.ts",
       "default": "./dist/testing/compaction-conformance.js"
     },
+    "./testing/prefix-stability-conformance": {
+      "types": "./dist/testing/prefix-stability-conformance.d.ts",
+      "default": "./dist/testing/prefix-stability-conformance.js"
+    },
     "./testing/tool-conformance": {
       "types": "./dist/testing/tool-conformance.d.ts",
       "default": "./dist/testing/tool-conformance.js"
@@ -131,7 +135,8 @@
     "packages/prism-coding-tools",
     "packages/ag-ui",
     "packages/web-tools",
-    "packages/acp-agent"
+    "packages/acp-agent",
+    "packages/hooks"
   ],
   "scripts": {
     "build:core": "node scripts/with-build-lock.mjs tsc",
@@ -151,6 +156,7 @@
     "test:postgres:run": "node scripts/require-postgres-url.mjs && npm run test:postgres --workspace @arnilo/prism-core --if-present && npm run test:postgres --workspace @arnilo/prism-memory && npm run test:postgres --workspace @arnilo/prism-channels && node --test scripts/phase7-conformance.test.mjs scripts/phase12-restart-recovery.test.mjs scripts/phase22-conformance.test.mjs",
     "test:nats": "node scripts/require-nats-url.mjs && npm run test:nats --workspace @arnilo/prism-core --if-present",
     "release:dry-run": "npm run sdk:ready",
+    "post-publish:smoke": "node scripts/post-publish-smoke.mjs",
     "release:check": "node scripts/release.mjs check",
     "release:publish": "node scripts/release.mjs publish",
     "release:evidence": "node scripts/release-skip-manifest.mjs",