@arnilo/prism 0.0.1 → 0.0.3

package/docs/coding-agent-tools.md

@@ -0,0 +1,208 @@
+# Coding agent tools (first-party package)
+
+## What it does
+
+`@arnilo/prism-coding-agent` is an optional first-party package that provides host shell/filesystem tools as Prism `ToolDefinition` objects. It ships four tools — `shell`, `read`, `write`, `edit` — plus aggregator factories. The tools are **inert** until a host imports them and registers them into a `ToolRegistry`. Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`edit` tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies; only `diff` plus the Node standard library).
+
+| Export | Purpose |
+| --- | --- |
+| `createShellTool(cwd, options?)` | `shell` tool: run a shell command and return combined output + exit code. |
+| `createReadTool(cwd, options?)` | `read` tool: read a text or image file into `TextContent` / `ImageContent`. |
+| `createWriteTool(cwd, options?)` | `write` tool: create or overwrite a file, creating parent directories. |
+| `createEditTool(cwd, options?)` | `edit` tool: precise exact-then-fuzzy text replacement in an existing file. |
+| `createCodingTools(cwd, options?)` | All four tools (`shell`, `read`, `write`, `edit`). |
+| `createReadOnlyTools(cwd, options?)` | Read-only subset: `read` only. |
+| `createAllTools(cwd, options?)` | Every tool the package provides (currently identical to `createCodingTools`). |
+| `detectSupportedImageMimeType(buf)` / `detectSupportedImageMimeTypeFromFile(path)` | Magic-byte image MIME detection (PNG/JPEG/GIF/WebP/BMP) used by `read`. |
+| `withFileMutationQueue(path, fn)` | Per-path serialization primitive re-exported for hosts. |
+
+Each factory returns a plain `ToolDefinition` (no auto-registration). Register what you need:
+
+```ts
+import { createToolRegistry } from "@arnilo/prism";
+import { createCodingTools } from "@arnilo/prism-coding-agent";
+
+const tools = createToolRegistry(createCodingTools(process.cwd()));
+```
+
+## When to use it
+
+Use this package when a host wants ready-made coding tools for an agent, session, or run, registered explicitly into a `ToolRegistry` and dispatched through the normal Prism tool harness. The tools perform **real** shell and filesystem operations on the host — they are not mocked or sandboxed. Use the individual factories when you need per-tool options or custom operation backends; use the aggregators when you want the default set.
+
+Do not use this package as a sandbox, permission policy, secret store, or provider loop. Prism gates tool dispatch with `PermissionPolicy` / `ToolValidator` / trust policies; the package performs no gating of its own. Do not register these tools for an untrusted provider.
+
+### pi name mapping
+
+| Prism (`@arnilo/prism-coding-agent`) | pi coding agent |
+| --- | --- |
+| `shell` | `bash` |
+| `read` | `read` |
+| `write` | `write` |
+| `edit` | `edit` |
+
+## Tools
+
+### `shell`
+
+Run a shell command and return combined stdout+stderr.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `command` | `string` | Shell command to execute (required). |
+| `timeout` | `number` | Timeout in **seconds** (optional; no default). |
+
+**Outputs:** a `ToolResult` whose `content[0]` is a `TextContent` with the combined output. Non-zero exit is **not** a tool error: it is returned as a normal result with `[Command exited with code N]` appended to the content and `exitCode` in metadata. Timeout and abort are error results that still carry the partial output captured so far.
+
+`shell` result `metadata`:
+
+| Field | Present when | Purpose |
+| --- | --- | --- |
+| `exitCode` | always | Process exit code, or `null` when the process was killed by timeout/abort. |
+| `truncation` | always | `TruncationResult` from the bounded output accumulator. |
+| `fullOutputPath?` | truncated only | Path to the spilled temp file holding the full output. |
+
+Shell resolution honors `options.shellPath` → `SHELL` env → `/bin/bash` → `sh`, and the process group is killed on timeout/abort (`process.kill(-pid)` on Unix, `taskkill /F /T` on Windows).
+
+### `read`
+
+Read a text or image file.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Path to the file (relative or absolute; `~` and `file://` expanded). Required. |
+| `offset` | `number` | Line to start reading from (1-indexed). |
+| `limit` | `number` | Maximum number of lines to read. |
+
+**Outputs:** text files become a single `TextContent`, truncated to `maxLines`/`maxBytes` (defaults 2000 lines / 50 KB) with a `Use offset=N to continue` footer when more remains. Image files (PNG/JPEG/GIF/WebP/BMP by magic bytes) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Read failures (missing file, offset beyond end, abort) are error results.
+
+`read` result `metadata`:
+
+| Field | Present when | Purpose |
+| --- | --- | --- |
+| `truncation` | text reads | `TruncationResult`. |
+| `image` | image reads | `{ mimeType, resized: false }`. |
+
+> `autoResizeImages` is accepted but is currently a documented no-op (deferred); images are returned at their original size with `image.resized = false`.
+
+### `write`
+
+Create or overwrite a file, creating parent directories as needed.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Path to the file to write (relative or absolute). Required. |
+| `content` | `string` | Content to write (empty string creates an empty file). Required. |
+
+**Outputs:** a `TextContent` confirmation naming the **absolute path** with UTF-8 byte and line counts (e.g. `Successfully wrote 42 bytes (3 lines) to /abs/path.txt`). Write failures and abort are error results. Empty `content` is valid.
+
+`write` result `metadata`: `{ bytes, lines, path }` (absolute path). Concurrent writes to the same path serialize through `withFileMutationQueue`; writes to different paths run in parallel.
+
+### `edit`
+
+Precise text replacement in an existing file via exact-then-fuzzy matching.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Path to the file to edit. Required. |
+| `edits` | `Array<{ oldText: string, newText: string }>` | Targeted replacements, each matched against the **original** file (not incrementally). No overlapping/nested edits. Required, non-empty. |
+
+Each `edits[].oldText` must match a unique, non-overlapping region of the original file. Matching is exact first, then fuzzy (unicode normalization / whitespace collapse). A BOM is stripped before matching and re-prepended on write; original line endings are restored.
+
+**Outputs:** a `TextContent` confirmation (`Successfully replaced N block(s) in {path}.`) plus `metadata`. Any failure — missing/unreadable file, no match, duplicate (non-unique) match, overlap, empty `oldText`, no-op edit, or abort — is an error result, and the file is left **unchanged** (the match runs before the write).
+
+`edit` result `metadata`: `{ diff, patch, firstChangedLine }` — a display-oriented diff, a standard unified patch, and the first changed line in the new file. These are host-readable; the model only sees the short confirmation (keeps model context small).
+
+## Outputs / response / events
+
+Every tool returns a `ToolResult` with `toolCallId`, `name`, `content` (`readonly ContentBlock[]`), optional `error`, and optional `metadata`. Mutating tools (`shell` with same cwd, `write`, `edit`) serialize per realpath through `withFileMutationQueue` so concurrent calls targeting one file do not interleave. The package emits no events of its own; hosts observe tool execution through the normal Prism `AgentEvent` stream via `dispatchToolCall`.
+
+## Request/response example
+
+```json
+// edit request
+{ "path": "src/app.ts", "edits": [{ "oldText": "const x = 1;", "newText": "const x = 2;" }] }
+```
+
+```json
+// edit success result
+{
+  "toolCallId": "call_1",
+  "name": "edit",
+  "content": [{ "type": "text", "text": "Successfully replaced 1 block(s) in src/app.ts." }],
+  "metadata": { "diff": "...", "patch": "--- src/app.ts\n+++ src/app.ts\n...", "firstChangedLine": 3 }
+}
+```
+
+```json
+// edit no-match result (file unchanged)
+{
+  "toolCallId": "call_2",
+  "name": "edit",
+  "error": { "message": "Could not find edits[0] in src/app.ts. The oldText must match exactly including all whitespace and newlines." }
+}
+```
+
+## Implementation example
+
+Minimal drop-in for any Prism app:
+
+```ts
+import { createToolRegistry } from "@arnilo/prism";
+import { createCodingTools, createReadOnlyTools } from "@arnilo/prism-coding-agent";
+
+// Full coding set (shell + read + write + edit) against the project root:
+const tools = createToolRegistry(createCodingTools(process.cwd()));
+
+// Or a read-only set for inspection-only agents:
+const ro = createToolRegistry(createReadOnlyTools(process.cwd()));
+```
+
+Customizing a single tool (force bash, cap output, delegate writes to a remote backend):
+
+```ts
+import { createShellTool, createWriteTool } from "@arnilo/prism-coding-agent";
+
+const shell = createShellTool("/repo", {
+  shellPath: "/bin/bash",
+  commandPrefix: "set -euo pipefail",
+  maxLines: 500,
+});
+
+const remoteWrite = createWriteTool("/repo", {
+  operations: {
+    writeFile: async (abs, content) => { /* ship to remote */ },
+    mkdir: async (dir) => { /* mkdir -p remotely */ },
+  },
+});
+```
+
+## Extension and configuration notes
+
+- **Pluggable operation backends.** Every tool accepts an `operations` seam so a host can delegate to a remote system (e.g. SSH) while keeping the tool's matching/serialization behavior: `BashOperations` (`shell`), `ReadOperations` (`read`), `WriteOperations` (`write`), `EditOperations` (`edit`).
+- **Per-tool options.** `ShellToolOptions` (`shellPath`, `commandPrefix`, `maxLines`, `maxBytes`, `tempFilePrefix`, `operations`, `spawnHook`); `ReadToolOptions` (`operations`, `autoResizeImages`, `maxLines`, `maxBytes`); `WriteToolOptions` (`operations`); `EditToolOptions` (`operations`).
+- **Aggregator options.** `ToolsOptions` (`{ shell?, read?, write?, edit? }`) threads each sub-object to the matching tool.
+- **`ToolsOptions`** and the per-tool option types are exported from the package barrel for host configuration.
+- No auto-discovery or manifest registration: import and register explicitly. This package registers no extensions and owns no globals (the mutation queue is a process-wide per-path map — see `ponytail:` note in the source).
+
+## Security and performance notes
+
+- **Host shell/filesystem access.** These tools run real commands and read/write real files. They provide **no sandbox**. Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. See [Host security guide](host-security.md) and [Security/auth/trust](settings-auth-trust-security.md).
+- **Non-zero exit is not an error.** A failing command is a normal `shell` result (exit code in metadata); only timeout/abort/spawn failures are error results. Do not assume `error == undefined` means the command succeeded.
+- **Bounded output.** `shell`/`read` accumulate output into a rolling tail bounded by `maxLines`/`maxBytes`; oversized output spills to a temp file (`fullOutputPath`), so memory use is bounded regardless of command output size.
+- **Per-path serialization.** Concurrent mutations to the same file serialize; concurrent mutations to different files do not block each other. The queue is a process-wide map — across sessions in one process, same-path writes still serialize (upgrade path: scope per registry if throughput matters).
+- **Single runtime dependency.** `diff` (for `edit` unified patch/diff generation) plus the Node standard library. No native modules; no image-processing native dependency (image auto-resize is deferred, so no `sharp`/WASM dependency).
+
+## Related APIs
+
+- [Tools](tools.md): the host-owned tool harness — `createToolRegistry`, `dispatchToolCall`, filtering, and the `ToolDefinition` contract these factories satisfy.
+- [Public contracts](public-contracts.md): `ToolDefinition`, `ToolResult`, `ToolExecutionContext`, `ContentBlock`, and `JsonObject` shapes.
+- [Host security guide](host-security.md): fail-closed checklist for permission policies, tool validation, and trust boundaries that must gate these tools.
+- [Tool conformance](tool-conformance.md): assertions for the tool-dispatch blocked-reason matrix these tools participate in.

package/docs/compaction-and-retry.md

@@ -145,11 +145,11 @@ await session.compact({ keepRecentEntries: 4 });
 
 ## Extension and configuration notes
 
-Retry policies are ordinary `RetryPolicy` implementations and can be registered as `retryPolicy` contributions. Hosts must still pass the selected policy/config to `createAgent()` or `session.run()`. Retry middleware receives `{ context, decision }` before a retry is scheduled and can reduce delay or stop retrying.
+Retry policies are ordinary `RetryPolicy` implementations and can be registered as `retryPolicy` contributions. Hosts must still pass the selected policy/config to `createAgent()` or `session.run()`. Retry middleware receives `{ context, decision }` before a retry is scheduled and can reduce delay or stop retrying. First-party providers emit `ErrorInfo.code` as the numeric HTTP status so the default policy's transient-code set (`429`/`500`/`502`/`503`) classifies retryability without provider-specific core branches; `@arnilo/prism-provider-neuralwatt` additionally exports `classifyNeuralWattError()` for hosts that want structured `Retry-After`/`retry_strategy` metadata.
 
 Compaction strategies are ordinary `CompactionStrategy` implementations. Extensions can register strategies through the existing compaction strategy contribution registry, but registration is inert until a host explicitly selects and passes a strategy to runtime code. Extensions can also register `compaction` middleware; the runtime calls it only when the agent/session has that middleware registry configured.
 
-The default strategy does not call a provider. Hosts that need model-generated summaries can use the optional [`@arnilo/prism-compaction-llm` package](compaction-llm.md). Hosts that need prepared source-backed memory without a compaction-time model call can use [`@arnilo/prism-compaction-observational-memory`](compaction-observational-memory.md).
+The default strategy does not call a provider. Hosts that need model-generated summaries can use the optional [`@arnilo/prism-compaction-llm` package](compaction-llm.md); its `maxOutputTokens`/`maxSummaryTokens` budget is passed through `model.parameters.maxTokens` and first-party providers serialize that to provider output-token fields. Hosts that need prepared source-backed memory without a compaction-time model call can use [`@arnilo/prism-compaction-observational-memory`](compaction-observational-memory.md).
 
 ## Security and performance notes
 

package/docs/compaction-conformance.md

@@ -0,0 +1,76 @@
+# Compaction conformance
+
+## What it does
+
+Compaction conformance helpers are dependency-free assertions for `CompactionStrategy` adapter tests. They exercise the summary-result shape, secret redaction, and abort observation of any `CompactionStrategy` without network or credentials.
+
+Exported from `@arnilo/prism/testing/compaction-conformance`:
+
+- `assertCompactionStrategyConforms(strategy, options?)`
+- `CompactionConformanceOptions`
+
+## When to use it
+
+Use this helper when implementing a custom `CompactionStrategy` (the core default strategy and the first-party LLM compaction package both conform). It asserts:
+
+- `compact()` returns a `CompactionResult` with a non-empty string `summary`
+- known secrets are redacted from the summary and any returned `entries`
+- (when `exerciseAbort: true`) an already-aborted `signal` is observed
+
+## Inputs / request
+
+```ts
+import { assertCompactionStrategyConforms } from "@arnilo/prism/testing/compaction-conformance";
+import type { CompactionStrategy } from "@arnilo/prism";
+
+const { summary } = await assertCompactionStrategyConforms(myStrategy, {
+  secrets: ["api-key-value"],
+  exerciseAbort: true,
+});
+```
+
+`CompactionConformanceOptions`:
+- `secrets?: readonly string[]` — secrets that must not appear in the summary or returned entries
+- `exerciseAbort?: boolean` — assert the strategy observes an already-aborted `signal`
+
+## Outputs / response / events
+
+Returns `Promise<{ summary: string }>`; throws a plain `Error` on the first contract violation. No events, no runner.
+
+## Request/response example
+
+```ts
+import { assertCompactionStrategyConforms } from "@arnilo/prism/testing/compaction-conformance";
+
+await assertCompactionStrategyConforms(myStrategy, { secrets: ["secret-value"] });
+// throws if the summary is empty, a secret leaks into the summary, or a
+// secret leaks into the returned entries.
+```
+
+## Implementation example
+
+```ts
+import { assertCompactionStrategyConforms } from "@arnilo/prism/testing/compaction-conformance";
+import { createDefaultCompactionStrategy } from "@arnilo/prism";
+
+await assertCompactionStrategyConforms(
+  createDefaultCompactionStrategy({ keepRecentEntries: 1, secrets: ["secret-value"] }),
+  { secrets: ["secret-value"] },
+);
+```
+
+## Extension and configuration notes
+
+- The helper builds a tiny two-message fixture; it does not call your strategy with production entries.
+- Abort observation is optional because not every strategy performs async work that can be aborted.
+
+## Security and performance notes
+
+- No credentials, no network, no real secrets required; pass fake secret strings.
+- The helper asserts redaction of exactly the secrets you supply (mirroring `createSecretRedactor`'s exact-match behavior); it does not detect arbitrary secret patterns.
+
+## Related APIs
+
+- [Compaction and retry](compaction-and-retry.md)
+- [Provider conformance](provider-conformance.md)
+- [Session store conformance](session-store-conformance.md)

package/docs/compaction-llm.md

@@ -33,7 +33,7 @@ Key exports:
 | `thinkingLevel` | Passed as `ProviderRequest.options.extra.thinkingLevel`. |
 | `reserveTokens` | Output budget basis; defaults to `16384`. |
 | `keepRecentTokens` | Approximate recent-token budget; defaults to `20000`. |
-| `maxSummaryTokens` / `maxOutputTokens` | Sets generic `model.parameters.maxTokens` and truncates oversized collected summaries. |
+| `maxSummaryTokens` / `maxOutputTokens` | Computes the summary output budget, writes it to `summaryModel/model.parameters.maxTokens`, and truncates oversized collected summaries. First-party providers serialize that generic field to their real request field (`max_output_tokens` for OpenAI Responses, `max_tokens` for OpenAI-compatible/Anthropic-style providers). |
 | `maxToolResultChars` | Tool-result JSON truncation limit; defaults to `2000`. |
 | `trackFileOperations`, `includeFileOperations` | Control file path extraction and final summary blocks. |
 | `secrets` | Exact strings to redact from serialized prompts and final summaries. |
@@ -61,12 +61,15 @@ import { createLlmCompactionStrategy } from "@arnilo/prism-compaction-llm";
 
 const strategy = createLlmCompactionStrategy({
   provider: summaryProvider,
-  model: { provider: "mock", model: "cheap-summary" },
+  model: { provider: "openai", model: "gpt-4.1-mini" },
   keepRecentTokens: 20_000,
   reserveTokens: 16_384,
+  maxOutputTokens: 800,
   providerOptions: { cacheRetention: "short" },
   customInstructions: "Focus on current files and failing tests.",
 });
+// Provider request model includes: { parameters: { maxTokens: 800 } }.
+// First-party serializers map it to max_output_tokens/max_tokens on the wire.
 
 await session.compact({ strategy, secrets: [apiKey] });
 ```
@@ -99,7 +102,7 @@ const agent = createAgent({ model, provider, compaction: { strategy, thresholdEn
 Registration only contributes an inert strategy. The host must resolve and pass it to runtime config.
 
 ## Security and performance notes
-Preparation is O(n) over branch entries and uses only arrays, strings, and JSON serialization. The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. It does not discover credentials, read files, start background jobs, or add provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history or provider output.
+Preparation is O(n) over branch entries and uses only arrays, strings, and JSON serialization. Output-budget calculation is O(1) and does not add an extra summarization call. The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. It does not discover credentials, read files, start background jobs, or add provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history or provider output.
 
 ## Related APIs
 - [Compaction and retry policies](compaction-and-retry.md): core compaction strategy surface.

package/docs/compaction-observational-memory.md

@@ -38,7 +38,7 @@ Key exports:
 | `recallObservationalMemory()` | Recover source evidence for a known observation/reflection id from supplied current-branch entries. |
 | `createMemoryId()` / `isMemoryId()` | Create/check 12-character ids. |
 | `resolveObservationalMemorySettings()` | Merge `observational-memory` settings with defaults and overrides. |
-| `createObservationalMemoryRuntime()` | Explicitly run observer/reflector/dropper workers for a supplied session/store/provider. |
+| `createObservationalMemoryRuntime()` | Explicitly run observer/reflector/dropper workers for a supplied session, owned append callback, and provider. |
 | `createObservationalMemoryCompactionStrategy()` | Render existing folded memory as a standard Prism compaction summary with `data.memory`. |
 | `createObservationalMemoryExtension()` | Inert extension helper that registers the strategy contribution unless disabled. |
 | `createRecallMemoryTool()` | Optional exact-id `recall` tool factory backed by host-supplied current-branch entries. |
@@ -74,7 +74,7 @@ const evidence = recallObservationalMemory(entries, "aaaaaaaaaaaa");
 
 const memory = createObservationalMemoryRuntime({
   session,
-  store,
+  appendEntry: (entry) => store.append(entry),
   workerProvider,
   workerModel: { provider: "mock", model: "memory" },
 });
@@ -92,7 +92,7 @@ await kernel.load([createObservationalMemoryExtension({ recallTool: { getEntries
 
 Settings are read from the `observational-memory` key only when a host calls `resolveObservationalMemorySettings()` or `runtime.flush()`. Defaults are `observeAfterTokens: 10000`, `reflectAfterTokens: 20000`, `compactAfterTokens: 81000`, `observationsPoolMaxTokens: 20000`, `observationsPoolTargetTokens: 10000`, `agentMaxTurns: 16`, `passive: false`, and `debugLog: false`.
 
-The runtime requires host-supplied `session`, matching `store`, `workerProvider`, and `workerModel`. Optional credential resolution is explicit; missing requested credentials skip worker execution.
+The runtime requires host-supplied `session`, an `appendEntry` callback bound to that session's owning store/branch, `workerProvider`, and `workerModel`. It no longer accepts a separate `store` option because mismatched session/store pairs can append memory entries outside the active branch. After each memory append, the runtime checks the appended entry is visible at the session leaf and fails closed/restores the previous checkout if the callback points elsewhere. Optional credential resolution is explicit; missing requested credentials skip worker execution.
 
 `createObservationalMemoryCompactionStrategy()` keeps recent message entries like the default compaction strategy, renders existing observations/reflections as the summary, and returns a standard Prism compaction entry. Its `data` includes `throughEntryId`, `keepEntryIds`, `strategy`, `trigger`, and `memory: { type: "om.folded", version: 1, fullFold, observations, reflections, droppedObservationIds }`. When active observations exceed `observationsPoolMaxTokens`, it performs a full fold into `data.memory`.
 
@@ -108,7 +108,7 @@ The runtime requires host-supplied `session`, matching `store`, `workerProvider`
 - Recall tool and commands only see current-branch entries supplied by the host callback.
 - Invalid or missing ids fail closed; invalid recall tool ids skip entry lookup.
 - Utilities and fast compaction are O(n) over supplied entries and use no provider, network, filesystem, timer, worker, credential, or settings access.
-- Workers serialize only supplied branch entries, enforce `agentMaxTurns`, and run one consolidation pipeline at a time per runtime.
+- Workers serialize only supplied branch entries, enforce `agentMaxTurns`, and run one consolidation pipeline at a time per runtime. Worker transcripts replay assistant `tool_call` messages before matching role `tool` `tool_result` messages so provider requests stay valid for call/result-pairing providers.
 - Compaction preserves raw history; Prism appends one standard compaction entry and rebuilds provider context from its summary plus kept recent messages.
 - Pass known secrets to render/recall/runtime/tool/command helpers to redact exact values from prompts, records, structured results, and text output.
 - Live tests are opt-in with `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS=1`.

package/docs/configuration-and-manifests.md

@@ -69,6 +69,7 @@ parsePrismManifest(value: unknown): PrismManifest
 | `authMethod` | `authMethods` | Auth method descriptor; uses `credentialName`, never a resolved credential value. |
 | `providerRequestPolicy` | `providerRequestPolicies` | Provider request policy declaration. |
 | `systemPromptContribution` | `systemPromptContributions` | System prompt contribution declaration. |
+| `instructionInjector` | `instructionInjectors` | Instruction injector declaration; selected on `AgentConfig`/`RunOptions.instructionInjectors` (Phase 30). |
 
 ## Outputs / response / events
 
@@ -76,6 +77,7 @@ parsePrismManifest(value: unknown): PrismManifest
 - Later config layers override earlier layers.
 - Nested plain objects merge recursively.
 - Arrays and primitives replace previous values.
+- Config and manifest JSON object keys named `__proto__`, `prototype`, or `constructor` are rejected at any depth before merge/clone output is built.
 - `parsePrismManifest()` returns a validated manifest or throws a field-specific validation error.
 - No events are emitted and no registries are modified by these helpers.
 
@@ -106,6 +108,7 @@ const manifest = definePrismManifest({
     { kind: "authMethod", name: "demo.api-key", metadata: { credentialName: "apiKey" } },
     { kind: "providerRequestPolicy", name: "demo.cache" },
     { kind: "systemPromptContribution", name: "demo.prompt" },
+    { kind: "instructionInjector", name: "demo.injector" },
   ],
   resources: [{ uri: "package://demo/prompt.md", purpose: "prompt" }],
 });
@@ -123,13 +126,14 @@ console.log(config.demo);
 
 - Hosts choose the layer order. Prism documents `built-in -> manifest defaults -> host app -> optional user/global -> runtime overrides` but does not load those layers automatically.
 - Manifest contribution declarations are data. Hosts may later choose to import the declared module/export and register it, but parsing the manifest never does that.
-- Contribution `kind` values match `createContributionRegistries()` categories, including the Phase 14 provider primitives `providerPackage`, `authMethod`, `providerRequestPolicy`, and `systemPromptContribution`.
+- Contribution `kind` values match `createContributionRegistries()` categories, including the Phase 14 provider primitives `providerPackage`, `authMethod`, `providerRequestPolicy`, `systemPromptContribution`, and the Phase 30 `instructionInjector`.
 - Filesystem config loading is intentionally outside the root API and belongs to the optional [`@arnilo/prism/node/config`](node-filesystem-config.md) subpath.
 - Manifest `resources` entries are URI declarations; use [resource loading](resource-loading.md) helpers with a host-provided loader to fetch them.
 
 ## Security and performance notes
 
 - Config and manifest values must be JSON-compatible data.
+- Config/manifest JSON rejects `__proto__`, `prototype`, and `constructor` keys at every depth to block prototype pollution rather than silently dropping unsafe input.
 - Do not put resolved credential values, tokens, headers, or executable code in config defaults, manifests, or metadata.
 - Manifest parsing does not execute package code, dynamically import modules, resolve credentials, call providers/tools, or read resources.
 - Config merging is dependency-free and proportional to the total number of JSON fields.
@@ -140,3 +144,4 @@ console.log(config.demo);
 - [Extension kernel and event bus](extensions.md): hosts can load extensions after they decide to execute package code.
 - [Resource loading](resource-loading.md): load manifest, prompt, skill, and package resources through host-provided loaders.
 - [Credentials and redaction](credentials-and-redaction.md): credential values stay out of manifests and config layers.
+- [Contribution discovery (workspace)](contribution-discovery.md): opt-in scanner that resolves non-skill on-disk entries into `ManifestContributionDeclaration` envelopes.

package/docs/context-and-skills.md

@@ -6,7 +6,7 @@
 
 ## When to use it
 
-Use context resolution when a host wants project/session/context blocks resolved before prompt composition. Use the skill registry when a host wants explicit progressive skill disclosure.
+Use context resolution when a host wants project/session/context blocks resolved before prompt composition. Use the skill registry when a host wants explicit progressive skill disclosure. Declarative `AgentDefinition.skills` are inactive unless listed; omitted skills means none unless the host uses the migration-only `activateAllCapabilities: true` option.
 
 Do not use these helpers as an agent loop, package discovery mechanism, context cache, token budgeter, retrier, credential resolver, semantic skill ranker, tool activator, or permission system.
 
@@ -32,7 +32,10 @@ Skill selection:
 ```ts
 import { createSkillRegistry, resolveActiveSkills } from "@arnilo/prism";
 
-const registry = createSkillRegistry([{ name: "brief", instructions: "Answer briefly.", toolNames: ["echo"] }]);
+const registry = createSkillRegistry(
+  [{ name: "brief", instructions: "Answer briefly.", toolNames: ["echo"] }],
+  { duplicate: "error" },
+);
 const active = resolveActiveSkills({
   registry,
   names: ["brief"],
@@ -40,13 +43,15 @@ const active = resolveActiveSkills({
 });
 ```
 
+`createSkillRegistry(skills?, options?)` stores skills by `skill.name`. Duplicate names replace deterministically by default for compatibility. Pass `{ duplicate: "error" }` to throw `Duplicate skill: <name>` and prevent silent shadowing.
+
 `ResolveActiveSkillsOptions` accepts a `SkillRegistry`, requested skill names, and host-active `ToolDefinition[]`.
 
 ## Outputs / response / events
 
 `resolveContextProviders()` returns `readonly ContextBlock[]` in provider order. If a middleware registry is supplied, the `context` hook can transform the final block array.
 
-`resolveActiveSkills()` returns requested skills in requested order. Unknown skills and skills that reference inactive tools throw before prompt composition.
+`resolveActiveSkills()` returns requested skills in requested order. Unknown skills, duplicate skill registrations in strict mode, and skills that reference inactive tools throw before prompt composition.
 
 ## Request/response example
 
@@ -85,7 +90,7 @@ const request = await assembleProviderInput({
 
 ## Extension and configuration notes
 
-Extensions can contribute context providers and skills with `registerContextProvider()` and `registerSkill()`, but those contributions stay inert until the host selects providers or registers/selects skills. The agent/session runtime uses the `context` and selected `skills` arrays passed on `AgentConfig`; it does not auto-select contributions.
+Extensions can contribute context providers and skills with `registerContextProvider()` and `registerSkill()`, but those contributions stay inert until the host selects providers or registers/selects skills. `resolveAgentDefinition()` only selects skills named in `AgentDefinition.skills` by default; omitted declarative skills activate none. The agent/session runtime uses the `context` and selected `skills` arrays passed on `AgentConfig`; it does not auto-select contributions.
 
 ```ts
 const providers = [kernel.registries.contextProviders.resolve("project")];
@@ -95,19 +100,87 @@ const skills = resolveActiveSkills({ registry: skillRegistry, names: ["brief"],
 
 `context` middleware runs only when a middleware registry is supplied to the helper. Middleware transforms context data; it does not grant tool access. Skills can reference tool names, but only host-active tools satisfy those references.
 
+## Runtime skill selection and activation
+
+The agent/session runtime resolves skills per run and wires each active skill's `context` into the assembled provider input. Runtime `AgentConfig.skills` and declarative `AgentDefinition.skills` have different defaults:
+
+| Surface | Config shape | Run override | Active skills |
+| --- | --- | --- | --- |
+| Runtime agent | `AgentConfig.skills: SkillRegistry` | `RunOptions.activeSkills: ["brief"]` | Named skills only, resolved with `resolveActiveSkills({ registry, names, tools })`. |
+| Runtime agent | `AgentConfig.skills: SkillRegistry` | no `activeSkills` / no `skills` | All registry skills (`SkillRegistry.list()`). |
+| Runtime agent | `AgentConfig.skills: Skill[]` | `RunOptions.skills: [...]` | Override array only. |
+| Runtime agent | `AgentConfig.skills: Skill[]` | no `RunOptions.skills` | All configured array skills. |
+| Declarative definition | `AgentDefinition.skills: ["brief"]` | later runtime `activeSkills` optional | Listed names only. |
+| Declarative definition | omitted `AgentDefinition.skills` | `activateAllCapabilities` false/default | No skills active. |
+| Declarative definition | omitted `AgentDefinition.skills` | `activateAllCapabilities: true` | All registry skills, migration-only. |
+
+Runtime selection precedence mirrors the other `RunOptions` overrides (`redactor`, `validate`):
+
+1. `AgentConfig.skills` is a `SkillRegistry` and `RunOptions.activeSkills: readonly string[]` (names) is set → the runtime calls `resolveActiveSkills({ registry, names, tools })`.
+2. `RunOptions.skills: readonly Skill[]` is set → that array replaces `AgentConfig.skills` for the run. This override exists for the case where `AgentConfig.skills` is a plain `Skill[]` (no registry), so name resolution is impossible.
+3. Neither set → all configured runtime skills are active (current behavior; `SkillRegistry.list()` or the plain array as-is). This is not the declarative default.
+
+names win when a registry exists. `RunOptions.activeSkills` cannot be used against a plain-array `AgentConfig.skills` — use `RunOptions.skills` instead. Use `RunOptions.skills: []` for an explicit no-skills runtime run.
+
+Each active skill contributes two things the runtime now wires together:
+
+- `Skill.instructions` → rendered as system messages by `skillMessages()` (active set only).
+- `Skill.context: ContextProvider[]` → collected across active skills (`activeSkills.flatMap(s => s.context ?? [])`), resolved through the existing `resolveContextProviders(...)`, and merged into the request's `context` **after** host `AgentConfig.context` blocks. Inactive skills contribute neither instructions nor context.
+
+`toolNames` enforcement is live: because selection routes through `resolveActiveSkills()`, a skill demanding a host-inactive tool throws with `Skill ${name} requires inactive tool: ${missing}` **before the first provider turn** — no provider call, no store write, no partial side effect. This is the fail-fast contract the docs already claimed; the runtime now honors it.
+
+```ts
+import { createAgent, createSkillRegistry, type ContextProvider } from "@arnilo/prism";
+
+const schema: ContextProvider = { name: "schema", resolve: () => [{ title: "Schema", content: "selected schema" }] };
+const skills = createSkillRegistry([
+  { name: "summarize", instructions: "Summarize.", context: [schema], toolNames: ["echo"] },
+  { name: "translate", instructions: "Translate." },
+]);
+
+const agent = createAgent({ model, provider, skills, tools: [echo] });
+
+// Only summarize this run: its instructions render and schema context resolves;
+// translate stays inactive and contributes neither. If `echo` were not in the
+// active tool set, this run would throw before the first provider turn.
+await agent.createSession().run(input, { activeSkills: ["summarize"] });
+
+// Same config, different active skills on the next run:
+await agent.createSession().run(input, { activeSkills: ["translate"] });
+
+// Plain-array override (no registry on AgentConfig.skills):
+await session.run(input, { skills: [{ name: "verbose", instructions: "Be verbose." }] });
+await session.run(input, { skills: [] }); // explicit no skills for this run
+```
+
+Skill selection grants no tool access and cannot bypass permissions — a skill's `toolNames` can only *require* host-active tools, never activate or grant them. Declarative skills also do not activate themselves by presence in a registry; list names on `AgentDefinition.skills` (or pass runtime `activeSkills`) when wanted. Per-skill token budgeting is deferred; the merge order (host context, then skill context) is the only priority knob today.
+
+### Migration note
+
+For declarative agents, old configs that omitted `skills` should now add explicit names:
+
+```ts
+// New safe default: no skill activates by omission.
+resolveAgentDefinition({ name: "doc", model, skills: ["brief"] }, context);
+```
+
+Use `activateAllCapabilities: true` only as a temporary all-skills/all-tools compatibility opt-in during migration. Runtime `RunOptions.activeSkills` remains the per-run narrowing tool after an agent has a skill registry configured.
+
 ## Security and performance notes
 
 - Context providers run sequentially and deterministically in caller order.
-- Skill registry lookup is `Map`-backed, and selection is linear in requested skills plus active tools.
+- Skill registry lookup is `Map`-backed, and selection is linear in requested skills plus active tools. Strict duplicate mode adds one O(1) `Map.has()` check during registration only.
 - These helpers perform no provider calls, tool execution, resource loading, package discovery, filesystem/network access, retries, timers, or watchers by themselves.
 - Context and skill output is host/extension data. Do not include secrets unless the host explicitly accepts that prompt exposure.
-- Active tools remain host-supplied; skills and middleware do not activate tools or grant permissions.
+- Active tools remain host-supplied; skills and middleware do not activate tools or grant permissions. Use `duplicate: "error"` when loading third-party skills to prevent silent name shadowing.
 
 ## Related APIs
 
 - [Agent/session runtime](agent-session-runtime.md): consumes host-selected context providers and skills from explicit agent config.
 - [Input and prompt assembly](input-and-prompt-assembly.md): default prompt builder and provider-input assembly helper.
+- [Instruction injection](instruction-injection.md): package injectors contribute `contextBlocks` that merge after host+skill provider blocks.
 - [Public contracts](public-contracts.md): `ContextProvider`, `ContextResolutionContext`, `ContextBlock`, `Skill`, `SkillRegistry`, `PromptBuilder`, and `PromptBuildRequest`.
 - [Middleware hooks](middleware-hooks.md): `context` and `prompt_build` hooks.
 - [Contribution registries](contribution-registries.md): inert context provider and skill contributions.
+- [Contribution discovery (workspace)](contribution-discovery.md): opt-in filesystem scanner that turns `SKILL.md`/`manifest.json` into registered skills and descriptor stubs. (Per-agent `AGENT.md` bundles live under an app-controlled `configRoot`; see [Agent definitions](agent-definitions.md).)
 - [Tools](tools.md): host-owned active tools and permissions.