@arnilo/prism 0.0.1 → 0.0.3

package/docs/extension-conformance.md

@@ -0,0 +1,80 @@
+# Extension conformance
+
+## What it does
+
+Extension conformance helpers are dependency-free assertions for `Extension` adapter tests. They exercise setup execution, inert contribution registration, and setup-error handling under the kernel's error policy, without network or credentials.
+
+Exported from `@arnilo/prism/testing/extension-conformance`:
+
+- `assertExtensionConforms(extension, options?)`
+- `ExtensionConformanceOptions`
+
+## When to use it
+
+Use this helper when authoring an `Extension` package. It asserts:
+
+- `setup` runs on load
+- registered contributions land in the inert contribution registries (no side effects until host code resolves and invokes them)
+- under the default `errorPolicy: "event"`, a failing setup emits a redacted `extension_error` event (when `secrets` is supplied)
+- under `expectThrow: true`, a failing setup rethrows to the caller
+
+## Inputs / request
+
+```ts
+import { assertExtensionConforms } from "@arnilo/prism/testing/extension-conformance";
+import type { Extension } from "@arnilo/prism";
+
+const extension: Extension = {
+  name: "demo",
+  setup(api) { api.registerSkill({ name: "brief", instructions: "Be brief." }); },
+};
+
+const kernel = await assertExtensionConforms(extension, { secrets: ["token-123"] });
+```
+
+`ExtensionConformanceOptions`:
+- `secrets?: readonly string[]` — secrets that must be redacted in the `extension_error` event (default policy only)
+- `expectThrow?: boolean` — assert a failing setup rethrows under `errorPolicy: "throw"`
+
+## Outputs / response / events
+
+Returns `Promise<ExtensionKernel>` so the caller can inspect registered contributions; throws a plain `Error` on the first violation. No runner.
+
+## Request/response example
+
+```ts
+import { assertExtensionConforms } from "@arnilo/prism/testing/extension-conformance";
+
+const kernel = await assertExtensionConforms(myExtension, { secrets: ["api-key"] });
+// throws if a failing setup's error event leaks one of the supplied secrets.
+```
+
+## Implementation example
+
+```ts
+import { assertExtensionConforms } from "@arnilo/prism/testing/extension-conformance";
+
+const kernel = await assertExtensionConforms({
+  name: "demo",
+  setup(api) { api.registerTool({ name: "ping", execute: () => ({ value: "pong" }) }); },
+});
+```
+
+## Extension and configuration notes
+
+- The helper builds a fresh `ExtensionKernel` for each call; it does not reuse host kernel state.
+- Contributions are inert by construction — the kernel stores envelopes and never invokes provider/tool/skill capabilities until host code resolves and calls them.
+- Under `expectThrow`, the helper asserts the kernel rethrows a failing setup rather than isolating it.
+
+## Security and performance notes
+
+- No credentials, no network required; pass fake secret strings.
+- Redaction is exact-match (mirroring `createSecretRedactor`); the helper does not detect arbitrary secret patterns.
+- The kernel does not sandbox tool/extension execution — hosts retain responsibility for trust and permission gating (see [Settings, auth, trust, security](settings-auth-trust-security.md)).
+
+## Related APIs
+
+- [Extensions](extensions.md)
+- [Contribution registries](contribution-registries.md)
+- [Settings, auth, trust, security](settings-auth-trust-security.md)
+- [Provider conformance](provider-conformance.md)

package/docs/extensions.md

@@ -101,11 +101,13 @@ await kernel.middleware.run("provider_request", { metadata: {} });
 ## Extension and configuration notes
 
 - Extension loading is explicit. Prism does not discover packages, read manifests, or load filesystem config in the kernel.
+- `AgentConfig.extensions` is host-owned metadata for compatibility; `createAgent()` and `session.run()` do not load it or call `Extension.setup()`. Load extensions with `createExtensionKernel().load(...)`, then pass selected contributions (`tools`, `context`, `skills`, middleware, etc.) into `createAgent()`.
 - Setup order is the order provided by the host.
 - The kernel writes only to explicit registries returned by `createContributionRegistries()` or provided by the host.
 - `api.registerTool()` contributes an inert `ToolDefinition` to `registries.tools`; it does not add the tool to an active tool registry, allow list, or dispatch loop.
 - `api.registerInputBuilder()`, `api.registerPromptBuilder()`, and `api.registerContextProvider()` contribute inert builders/providers; they do not replace defaults or run until the host passes selected entries to Phase 5 helpers.
 - `api.registerSkill()` contributes an inert `Skill` to `registries.skills`; it does not disclose instructions, activate referenced tools, or grant permissions until the host selects it.
+- `api.registerInstructionInjector()` (Phase 30) contributes an inert `InstructionInjector` to `registries.instructionInjectors`; it grants no tools, skills, or permissions and is only applied when the host selects it via `AgentConfig.instructionInjectors`/`RunOptions.instructionInjectors`. See [Instruction injection](instruction-injection.md).
 - `api.registerProviderPackage()`, `api.registerAuthMethod()`, `api.registerProviderRequestPolicy()`, and `api.registerSystemPromptContribution()` contribute inert provider-package data; they do not load packages, resolve credentials, mutate provider payloads, or change prompts until selected by a host/runtime helper that documents that behavior.
 - `api.registerAgent()` contributes an inert `AgentDefinition`; its `create()` can call `createAgent()`, but the runtime is not started until host code resolves the definition and creates/runs a session.
 - The kernel registers middleware only into the explicit registry returned by `createMiddlewareRegistry()` or provided by the host.
@@ -115,6 +117,7 @@ await kernel.middleware.run("provider_request", { metadata: {} });
 ## Security and performance notes
 
 - No hidden global extension kernel, provider registry, credential resolver, settings provider, store, or resource loader is created.
+- `AgentConfig.extensions` does not auto-execute, so constructing or running an agent cannot unexpectedly run extension code.
 - Error events use `ErrorInfo` and redact only known secret values passed in `secrets`.
 - Do not put resolved credential values in extension events, registry metadata, docs, logs, prompts, or session stores.
 - Event and middleware dispatch are ordered and dependency-free. They use no timers, background workers, filesystem discovery, network calls, provider calls, or tool execution.
@@ -122,10 +125,13 @@ await kernel.middleware.run("provider_request", { metadata: {} });
 
 ## Related APIs
 
+- [Extension authoring guide](extension-authoring.md): package-author checklist for inert contributions, host activation, trust, permissions, no sandbox, and redaction.
 - [Middleware hooks](middleware-hooks.md): ordered hook registry populated by `ExtensionAPI.use()`.
 - [Provider packages](provider-packages.md): provider package and model metadata registration through `ExtensionAPI`.
 - [Contribution registries](contribution-registries.md): registry bundle populated by `ExtensionAPI`.
+- [Contribution discovery (workspace)](contribution-discovery.md): filesystem-driven complement to extension registration — opt-in scan without `import()` or activation.
 - [Tools](tools.md): host activation, filtering, and dispatch for contributed tool definitions.
+- [Instruction injection](instruction-injection.md): package injectors that layer instructions and context blocks for `first_turn`/`every_turn`/`on_input` without granting tools.
 - [Input and prompt assembly](input-and-prompt-assembly.md): host selection for contributed input/prompt builders.
 - [System prompts](system-prompts.md): host selection for contributed system prompt layers.
 - [Context and skills](context-and-skills.md): host selection and tool checks for contributed context providers and skills.

package/docs/host-security.md

@@ -0,0 +1,141 @@
+# Host security guide
+
+## What it does
+
+This guide is a fail-closed checklist for apps embedding Prism. It maps host security responsibilities to existing Prism APIs for credentials, settings, redaction, trust roots, permission policies, session and ledger persistence, extension loading, and tool validation.
+
+Prism supplies seams and checks. The host owns policy decisions, secret sources, durable storage, approval UI, sandboxing, and which contributed capabilities become active.
+
+## When to use it
+
+Use this guide before exposing an agent to users, third-party extensions, durable storage, or real provider credentials.
+
+Do not use it as a replacement for product threat modeling, process/container sandboxing, secret management, database access control, or provider-side policy. Prism does not sandbox tools/extensions and does not detect arbitrary secrets.
+
+## Inputs / request
+
+Start from explicit host inputs. Do not let runtime code discover security state implicitly.
+
+| Security input | Host-owned source | Prism API / page |
+| --- | --- | --- |
+| Settings | app config object or caller-named files | `createStaticSettingsProvider`, `loadSettingsFiles()` |
+| Credentials | runtime override, memory store, vault/env object | `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `resolveCredentialValue()` |
+| Redaction values | exact known credential strings | `createSecretRedactor`, `redactSecrets()` |
+| Trust roots | app-selected directories/resources | `createPathTrustPolicy`, `assertTrusted()` |
+| Permission decisions | allow/deny rules or approval UI result | `createStaticPermissionPolicy`, `assertPermission()` |
+| Tool allow-list | active tools for this agent/session/run | `createToolRegistry`, `filterTools()`, `dispatchToolCall()` |
+| Tool argument rules | host validator | `AgentConfig.validator`, `RunOptions.validate`, `ToolValidator` |
+| Durable history | host database adapter | `SessionStore`, `assertSessionStoreConforms()` |
+| Durable audit | host ledger adapter | `RunLedger`, `redactRunLedgerRecord()` |
+| Extensions | explicit package imports only | `createExtensionKernel`, `ExtensionAPI` |
+
+## Outputs / response / events
+
+Security controls fail closed before side effects when wired at the guarded edge:
+
+- trust denial blocks resource/extension reads before load/use
+- permission denial blocks extension setup, resource loading, and tool execution
+- unknown or denied tools emit `tool_execution_blocked`
+- validator failures emit `tool_execution_blocked` with `validation_failed`
+- configured redactors scrub provider requests, agent events, session entries, ledger records, tool errors, extension errors, and injector context
+
+These checks are explicit function calls during load, assembly, dispatch, append, or run handling. Prism adds no background watchers, filesystem scanners, network probes, credential polling, or automatic extension discovery.
+
+## Request/response example
+
+```json
+{
+  "credentialSource": "caller-owned env object",
+  "trustedRoots": ["/workspace/app"],
+  "allowedActions": ["tool:notes/read:execute", "extension:acme:setup"],
+  "activeTools": ["notes/read"],
+  "toolValidation": "host ToolValidator",
+  "persistence": "redacted SessionStore + RunLedger"
+}
+```
+
+The JSON above is an app security plan, not a Prism config format. Hosts translate each field into the explicit APIs listed in this guide.
+
+## Implementation example
+
+```ts
+import {
+  createEnvCredentialResolver,
+  createSecretRedactor,
+  createStaticPermissionPolicy,
+  createToolRegistry,
+  filterTools,
+  resolveCredentialValue,
+  type ToolDefinition,
+  type ToolValidator,
+} from "@arnilo/prism";
+import { createPathTrustPolicy } from "@arnilo/prism/node/trust";
+
+const workspaceRoot = "/workspace/app";
+const env = { DEMO_API_KEY: "fake-demo-key" }; // docs-only placeholder
+const credentials = createEnvCredentialResolver(env, { demo: "DEMO_API_KEY" });
+const apiKey = await resolveCredentialValue(credentials, { provider: "demo", name: "apiKey" });
+
+const redactor = createSecretRedactor([apiKey]);
+const permission = createStaticPermissionPolicy({
+  allow: ["tool:notes/read:execute", "extension:acme:setup"],
+});
+const trust = createPathTrustPolicy({ trustedRoots: [workspaceRoot] });
+
+const readNotes: ToolDefinition = {
+  name: "notes/read",
+  parameters: { type: "object", properties: { id: { type: "string" } } },
+  execute(args, context) {
+    return { toolCallId: context.toolCallId, name: "notes/read", value: { id: args.id } };
+  },
+};
+
+const validate: ToolValidator = (_tool, args) =>
+  typeof args.id === "string" && args.id.length <= 100
+    ? undefined
+    : "id must be a short string";
+
+const tools = createToolRegistry(filterTools([readNotes], { allow: ["notes/read"] }), { duplicate: "error" });
+
+void { apiKey, redactor, permission, trust, tools, validate };
+```
+
+Wire those values where they matter: provider adapters receive the resolved credential, agents/runs receive `redactor`, tool dispatch receives `permission` and `validate`, resource/extension loaders receive `trust` and `permission`, and durable adapters receive already-redacted entries/records.
+
+## Extension and configuration notes
+
+- Keep security state explicit. `AgentConfig.settings` and `AgentConfig.credentials` are host-owned metadata; `createAgent()` and `session.run()` do not automatically call `settings.get()` or `credentials.resolve()`.
+- Resolve credentials at the provider/request edge, as late as possible. Do not put resolved credentials in configs, manifests, registries, prompts, messages, events, session entries, run ledgers, idempotency keys, cache keys, or logs.
+- Use `createExplicitCredentialResolver()` to document source order such as runtime override → stored credential → caller-supplied env object → fallback.
+- Use `createEnvCredentialResolver()` only with an object the host passes in. Prism does not read `process.env` for credentials.
+- Use `createPathTrustPolicy()` for workspace/resource roots and fail closed on symlink escapes.
+- Use `createContributionRegistries({ duplicate: "error" })` and prefixed names for third-party packages to prevent silent shadowing.
+- Extension contributions are inert until selected. Loading an extension package runs its `setup(api)` code, so hosts should load only trusted packages or isolate untrusted code outside Prism.
+- Skills and instruction injectors grant no tools, permissions, validators, or resource access. Host-active tools and permission policies still decide execution.
+- For production persistence, implement a database-backed `SessionStore`/`RunLedger`, run `assertSessionStoreConforms()` against the store, and follow the database schema guidance. Do not ship provider instances, credential resolvers, or secrets into durable rows.
+
+## Security and performance notes
+
+- Fail closed: unknown providers, unknown tools, denied tools, invalid tool arguments, missing skill tool dependencies, trust failures, permission failures, append conflicts, and validator failures should stop the unsafe action.
+- Prism does not sandbox host tools, extensions, provider adapters, credential resolvers, or custom middleware. Use OS/container/process isolation when code is untrusted.
+- Redaction is exact known-secret replacement only. It is not arbitrary secret detection, entropy scanning, or DLP.
+- Known secrets must be passed into redactors before data is emitted or persisted. Redact again in host adapters if they transform records after Prism redaction.
+- Tool `parameters` metadata is not validation. Add a `ToolValidator` or validate inside the tool before side effects.
+- Permission checks happen before tool validation and before `tool.execute()`. Middleware cannot grant permission by renaming a tool.
+- Session stores and ledgers receive redacted values when a redactor is active, but durable storage remains host-owned. Enforce tenant/account/user ownership and retention in the database layer.
+- Provider-owned auth/content/session/cache/security headers win over caller headers in adapters that merge headers.
+- Security checks are bounded explicit calls on the active path. Prism adds no hidden global middleware, background workers, watchers, network calls, or filesystem scans.
+
+## Related APIs
+
+- [Settings, auth, trust, and security controls](settings-auth-trust-security.md): low-level helpers and boundary hardening table.
+- [Credentials and redaction](credentials-and-redaction.md): credential resolver order, caller-supplied env objects, OAuth refresh, exact redaction, and no persistent secret store.
+- [Tools](tools.md): active tool registry, allow/deny filters, permission order, validator order, blocked events, and no sandbox.
+- [Extension authoring guide](extension-authoring.md): inert contribution package boundary and extension loading security notes.
+- [Extension kernel and event bus](extensions.md): `createExtensionKernel`, setup error redaction/rethrow, and permission-gated extension setup.
+- [Contribution discovery](contribution-discovery.md): opt-in realpath-contained scanner that imports nothing and activates nothing.
+- [Instruction injection](instruction-injection.md): redacted injector context and no capability grants.
+- [Session stores](session-stores.md): durable session store contract and secret/persistence boundaries.
+- [Runs and usage ledger](runs-and-usage.md): redacted run/event/tool/usage ledger records.
+- [Database persistence](database-persistence.md): production schema, ownership, indexes, retention, and adapter readiness checklist.
+- [Provider caching](provider-caching.md): cache keys and provider-owned header safety rules.

package/docs/index.md

@@ -6,50 +6,72 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Public contracts](public-contracts.md): type shapes for messages, content, agents, sessions, providers, tools, context, skills, extensions, stores, resources, settings, credentials, and events.
 
 ## Agent/session runtime
-- [Agent/session runtime](agent-session-runtime.md): create agents and sessions, run prompts, and subscribe to normalized session events.
+- [Agent/session runtime](agent-session-runtime.md): create agents and sessions, run prompts, subscribe to normalized events, and see which `AgentConfig` fields are runtime-consumed vs host-owned metadata. Covers tool-call loop transcript shape and prior-reasoning preservation across turns.
+- [Agent definitions](agent-definitions.md): resolve declarative `AgentDefinition` values via `resolveAgentDefinition`, and turn app-config `<configRoot>/agents/<name>/AGENT.md` bundles into runnable agents via `discoverAgentBundles` / `resolveAgentBundle` (explicit tool/skill activation by name, fail-closed omitted capabilities, migration-only `activateAllCapabilities`, strict duplicate scope checks, configurable prompt layers, no auto-discovery).
+- [Agent loops](agent-loops.md): replaceable per-run control loops — `singleShotLoop` default and `generate-validate-revise` with host-supplied `validator`/`parser`/`repairer` callbacks.
+- [Agent events](agent-events.md): the `AgentEvent` stream — agent/turn/message (including live `tool_call_delta` fragments), tool execution, queue/subscriber overflow, compaction/retry, artifact validation/refinement, and error variants, redacted via `redactAgentEvent`.
+- [Runs and usage ledger](runs-and-usage.md): `RunLedger` adapter for durable run, event, tool-call, usage persistence, cache diagnostics, ownership/idempotency, and redaction guidance.
+- [Performance limits](performance.md): bounded live subscriber queues, branch-read pagination expectations, JSONL/dev-store limits, and production sizing assumptions.
+- [Structured output](structured-output.md): the `Artifact*` seam (parser/validator/repairer, host-defined `T`) — the only typed-output path from a loop, with a Synapta-style schema→`ArtifactValidation` mapping example and an end-to-end third-party integration walkthrough.
 
 ## Compaction/session memory
 - [Compaction and retry policies](compaction-and-retry.md): summarize branch history and retry transient provider failures with host-replaceable policies.
-- [LLM compaction package](compaction-llm.md): optional provider-backed compaction strategy package.
-- [Observational memory compaction package](compaction-observational-memory.md): optional source-backed memory, fast compaction, recall tool, and status/view command package.
-- [Session stores and branching](session-stores-and-branching.md): store session entries, rebuild branch context, and navigate branch leaves.
-- [Node JSONL session store](node-jsonl-session-store.md): persist session entries to caller-named JSONL files in Node hosts.
+- [LLM compaction package](compaction-llm.md): optional provider-backed compaction strategy package with max-output budgets mapped through `model.parameters.maxTokens` to provider wire fields.
+- [Observational memory compaction package](compaction-observational-memory.md): optional source-backed memory, owned runtime append callback, provider-valid worker transcripts, fast compaction, recall tool, and status/view command package.
+- [Session stores](session-stores.md): `SessionStore` contract, `SessionAppendOptions`, `SessionAppendConflictError`, branch handles, `readBranchPath`, and dev-vs-production branch reads — start here for session persistence.
+- [Session stores and branching](session-stores-and-branching.md): detailed branch semantics and helper reference (kept for compatibility; links back to the canonical atomic append / branch-handle sections).
+- [Database persistence](database-persistence.md): production persistence contracts, conditional append transaction pattern, idempotency indexes, `readBranchPath`, reference relational schema, retention, migrations, and NoSQL mapping.
+- [Migration guide](migration.md): the two cross-cutting app migrations in one place — in-memory/JSONL → database-backed `ProductionPersistenceStore` persistence (+ `RunLedger`) and permissive capability defaults → Phase 38 explicit `tools`/`skills` activation, with before/after shapes and links to the detailed pages.
+- [Node JSONL session store](node-jsonl-session-store.md): development-only JSONL file adapter for single-process Node hosts; no cross-process safety.
 
 ## Provider and model connection
-- [Provider layer](provider-layer.md): register and resolve host-owned providers/models, create provider events, use generic provider request options, and test with the mock provider.
-- [Provider packages](provider-packages.md): define explicit provider packages, model metadata, auth descriptors, and request/cache policies without package discovery or provider-specific core behavior.
-  - Phase 12 package workspaces: [`@arnilo/prism-provider-openai`](providers/openai.md), [`@arnilo/prism-provider-opencode-go`](providers/opencode-go.md), [`@arnilo/prism-provider-openrouter`](providers/openrouter.md), [`@arnilo/prism-provider-zai`](providers/zai.md), and [`@arnilo/prism-provider-kimi`](providers/kimi.md).
+- [Provider layer](provider-layer.md): register and resolve host-owned providers/models, choose replace-or-error duplicate policy, create provider events, stream/reconstruct tool-call deltas, use generic provider request options, and test with the mock provider; deprecated provider-level timeout/retry hints point to runtime abort/retry.
+- [Model registry](model-registry.md): register and resolve `ModelConfig` records with capabilities, limits, cost, cache support metadata, compat data, and duplicate policy.
+- [Provider caching](provider-caching.md): use `PromptCacheHints`, `PromptCacheBreakpoint`, `ModelCacheCapabilities`, cache-aware stable-prefix guidance, and shared cache diagnostics helpers; includes a per-provider explicit/implicit cache matrix for OpenAI, OpenRouter, OpenCode Go, Z.AI, Kimi, and NeuralWatt; cache hints are best-effort and cache keys are never secrets.
+- [Provider request policies](provider-request-policies.md): chain `ProviderRequestPolicy` hooks, use `createSessionCachePolicy`, and merge legacy/structured cache options safely.
+- [Provider packages](provider-packages.md): define explicit provider packages, model metadata, auth descriptors, request/cache policies, and provider-owned header precedence without package discovery or provider-specific core behavior; includes a first-party cache behavior summary.
+  - Phase 12 package workspaces: [`@arnilo/prism-provider-openai`](providers/openai.md), [`@arnilo/prism-provider-opencode-go`](providers/opencode-go.md), [`@arnilo/prism-provider-openrouter`](providers/openrouter.md), [`@arnilo/prism-provider-zai`](providers/zai.md), [`@arnilo/prism-provider-kimi`](providers/kimi.md), and [`@arnilo/prism-provider-neuralwatt`](providers/neuralwatt.md) with implicit vLLM prefix caching, reasoning controls (`reasoning_effort`/`thinking_token_budget`/`enable_thinking`/`preserve_thinking`/`clear_thinking`), reasoning preservation, OpenAI-style tool-call loop, quota, telemetry, and retry classification helpers.
 - [OpenAI-compatible provider](providers/openai-compatible.md): optional provider subpath using native or injected `fetch` for Chat Completions streaming.
 
 ## Input, prompt, and context assembly
-- [Input and prompt assembly](input-and-prompt-assembly.md): render tiny prompt templates and turn common host input, history, attachments, explicit resources, summaries, and tool results into messages with replaceable builders and provider-input assembly.
-- [System prompts](system-prompts.md): compose explicit package/app/user/run system prompt layers without filesystem discovery or hidden globals.
-- [Context and skills](context-and-skills.md): resolve ordered context providers and keep context/skill selection host-owned.
+- [SDK customization guide](customization.md): map provider resolution, middleware, context, builders, injectors, loops, compaction, retry, stores, and skills to explicit host-wired APIs.
+- [Input and prompt assembly](input-and-prompt-assembly.md): render tiny prompt templates and turn common host input, history, attachments, explicit resources, summaries, and tool results into messages with replaceable builders, provider-input assembly, legacy default order, and opt-in cache-aware ordering.
+- [System prompts](system-prompts.md): compose explicit user/package/app/run system prompt layers, auto-load the standard `AGENTS.md` (workspace) / `SYSTEM.md` prompt files via the Node `loadSystemPromptFiles` loader (trust-gated for `AGENTS.md`), and append `SYSTEM.md` → per-agent `AGENT.md` body → repo `AGENTS.md` layers from a discovered agent bundle via `resolveAgentBundle`.
+- [Instruction injection](instruction-injection.md): register package injectors that layer redacted instructions/context blocks without granting tools, permissions, or resource escapes.
+- [Context and skills](context-and-skills.md): resolve ordered context providers and keep context/skill selection host-owned; omitted declarative skills stay inactive by default, `toolNames` fail closed before provider turns, and strict skill registries prevent silent shadowing.
 
 ## Tools
-- [Tools](tools.md): register host-owned active tools, apply exact allow/deny filtering, and dispatch tool calls.
+- [Tools](tools.md): register host-owned active tools with replace-or-error duplicate policy, apply exact allow/deny filtering, and dispatch tool calls.
+- [Coding agent tools](coding-agent-tools.md): optional first-party package `@arnilo/prism-coding-agent` providing `shell`, `read`, `write`, and `edit` tools (ported from pi) as `ToolDefinition`s a host registers; pluggable operation backends, per-path mutation serialization, and read-only/coding aggregators. Host shell/filesystem access — gate with permission/trust policies.
 
 ## Extensions/plugins
-- [Contribution registries](contribution-registries.md): explicit host-owned registries for extension/package contributions without hidden globals.
+- [Contribution discovery (workspace)](contribution-discovery.md): opt-in, realpath-contained directory scanner turning `SKILL.md`/`manifest.json` into inert `DiscoveredContribution` envelopes the host registers — no `import()`, no auto-activate, no provider scanning. (Per-agent `AGENT.md` bundles live under an app-controlled `configRoot`; see [Agent definitions](agent-definitions.md).)
+- [Contribution registries](contribution-registries.md): explicit host-owned registries for extension/package contributions without hidden globals, with `duplicate: "error"` strict mode for provider/model/tool/skill shadowing prevention.
 - [Extension kernel and event bus](extensions.md): load host-provided extensions in order, register contributions, emit lifecycle events, and isolate extension errors.
+- [Extension authoring guide](extension-authoring.md): publish third-party extension packages that register inert contributions and show host-owned activation, trust, permissions, redaction, and no-sandbox boundaries.
 - [Middleware hooks](middleware-hooks.md): ordered hook registry for provider, input, context, tool, retry, compaction, and session lifecycle boundaries.
 
 ## Configuration/manifests
-- [Configuration and manifests](configuration-and-manifests.md): merge in-memory JSON config layers and validate data-only package manifests.
+- [Configuration and manifests](configuration-and-manifests.md): merge in-memory JSON config layers and validate data-only package manifests with prototype-pollution key rejection.
 - [Node filesystem config loader](node-filesystem-config.md): explicitly read caller-named JSON config files in Node hosts.
 - [Resource loading](resource-loading.md): decode text, JSON, and manifest resources through caller-provided loaders.
 
 ## CLI/RPC
-- [CLI/RPC](cli-rpc.md): Run print/json modes and LF-delimited RPC over the public AgentSession runtime.
+- [CLI/RPC](cli-rpc.md): Run print/json modes and LF-delimited RPC over the public AgentSession runtime, including branch-handle results, fixed `forkSession`, and `checkout`.
 
 ## Security and credentials
-- [Security/auth/trust](settings-auth-trust-security.md): settings providers, credential helpers, trust/permission policies, and redaction controls.
-- [Credentials and redaction](credentials-and-redaction.md): compose explicit credential resolver order, use caller-supplied env objects/OAuth refresh helpers, and redact known secret values.
+- [Host security guide](host-security.md): fail-closed checklist for credentials, settings, redaction, trust roots, permission policies, persistence, extension loading, and tool validation.
+- [Security/auth/trust](settings-auth-trust-security.md): settings providers, credential helpers, trust/permission policies, redaction controls, host-owned `AgentConfig.settings`/`credentials`, and security-boundary hardening summary.
+- [Credentials and redaction](credentials-and-redaction.md): compose explicit credential resolver order, use caller-supplied env objects/OAuth refresh helpers, avoid eager `AgentConfig.credentials` resolution, and redact known secret values.
 
 ## Testing and examples
 - [Provider layer](provider-layer.md): use `createMockProvider()` and provider event helpers for deterministic tests without timers, credentials, or network.
-- [Provider conformance](provider-conformance.md): run network-free provider adapter assertions from `@arnilo/prism/testing/provider-conformance`.
-- `examples/`: compile-checked typed examples and runnable mock demos (SDK basics, provider registration, auth, tools, stores/branching, compaction, observational-memory recall, CLI, RPC).
+- [Provider conformance](provider-conformance.md): run network-free provider adapter assertions (stream order, abort, tool-call reconstruction, cache usage, content coverage, protected header ownership, secret leak) from `@arnilo/prism/testing/provider-conformance`.
+- [Session store conformance](session-store-conformance.md): assert any `SessionStore` adapter satisfies append/idempotency/conflict/branch invariants from `@arnilo/prism/testing/session-store-conformance`.
+- [Compaction conformance](compaction-conformance.md): assert any `CompactionStrategy` returns a non-empty redacted summary and observes abort from `@arnilo/prism/testing/compaction-conformance`.
+- [Tool conformance](tool-conformance.md): assert the tool-dispatch blocked-reason matrix (unknown/denied/invalid/permission/validator) and success path from `@arnilo/prism/testing/tool-conformance`.
+- [Extension conformance](extension-conformance.md): assert an `Extension` setup runs, contributions stay inert, and setup errors are redacted or rethrown from `@arnilo/prism/testing/extension-conformance`.
+- `examples/`: compile-checked typed examples and runnable mock demos (SDK basics, provider registration, auth, tools, cache-aware prompt assembly, NeuralWatt agent run, stores/branching, compaction, observational-memory recall, structured-output/artifact-loop, CLI, RPC).
 
 ## Release and install
 - [Release and install](release-and-install.md): package layout, install specifiers, required `@arnilo/prism` peer, tarball contents and exclusions, the map-retention knob, the release workflow, and the offline test budget.

package/docs/input-and-prompt-assembly.md

@@ -18,6 +18,7 @@ Do not use it for tool execution, provider calls, file discovery, credential loo
 import { createDefaultInputBuilder } from "@arnilo/prism";
 
 const messages = await createDefaultInputBuilder().build("Summarize", {
+  inputLayout: "legacy", // default; "cache_aware" passes the cache-aware layout preference
   systemInstructions: "Be accurate.",
   developerInstructions: "Cite supplied context only.",
   history,
@@ -46,6 +47,7 @@ import { assembleProviderInput, createDefaultPromptBuilder } from "@arnilo/prism
 const request = await assembleProviderInput({
   model: { provider: "mock", model: "demo" },
   input: "Explain this file",
+  inputLayout: "cache_aware",
   contextProviders: [projectContext],
   promptBuilder: createDefaultPromptBuilder(),
   tools: activeTools,
@@ -56,7 +58,8 @@ Useful exported types:
 
 - `AgentInput`: `string | Message | readonly Message[]`.
 - `DefaultInputBuilder`: the default `InputBuilder` with typed default context.
-- `DefaultInputBuildContext`: optional instructions, history, summaries, attachments, resource loader/URIs, tool results, middleware, ids, metadata, and abort signal.
+- `InputAssemblyLayout`: `"legacy" | "cache_aware"`; legacy is default.
+- `DefaultInputBuildContext`: optional input layout, instructions, history, summaries, attachments, resource loader/URIs, tool results, middleware, ids, metadata, and abort signal.
 - `InputAttachment`: already-loaded text/content or an explicit URI loaded through a caller-provided `ResourceLoader`.
 - `PromptInstruction`: labeled system instruction text.
 - `DefaultPromptBuilder`: the default `PromptBuilder`.
@@ -69,10 +72,18 @@ The builder returns `readonly Message[]`.
 
 - String input becomes one user text message.
 - `Message` and `Message[]` input are preserved.
+- Legacy layout is the default. Set `inputLayout: "cache_aware"` on the default builder, `assembleProviderInput()`, `AgentConfig`, or `RunOptions` to pass the cache-aware layout preference without replacing the builder.
+
+| Layout | Input message order |
+| --- | --- |
+| `legacy` | instructions → summaries → history → current input → attachments/resources → tool results |
+| `cache_aware` | instructions → attachments/resources → summaries → history → tool results → current input |
+
+The default prompt builder still prepends context, selected skills, and tool declarations before those input messages. Cache-aware ordering gives cache-capable providers a stable prefix only while those stable inputs stay byte-stable; changing tools, context, resources, summaries, history, or attachments changes the prefix too.
 - History is prepended before current input.
 - Instructions and summaries are system messages; compacted branch summaries from `rebuildSessionContext()` use the same path.
 - Text attachments and explicit text resources are user messages.
-- Tool results are tool messages containing `tool_result` content; the agent/session runtime uses this to feed dispatched tool results into the next provider turn, placing the assistant `tool_call` and the matching role `tool` `tool_result` before any final assistant content.
+- Tool results are tool messages containing `tool_result` content; the agent/session runtime uses this to feed dispatched tool results into the next provider turn, placing the assistant `tool_call` and the matching role `tool` `tool_result` before any final assistant content. Cache-aware layout keeps tool results before the current user suffix so it does not split tool transcripts.
 - Middleware runs only when `middleware` is supplied in the context.
 - `assembleProviderInput()` returns a `ProviderRequest` with the caller's model/tools/provider options/metadata/signal and composed messages/context.
 - `renderPromptTemplate()` replaces top-level `{{name}}` variables with caller-supplied JSON-compatible values. Strings are inserted directly; numbers, booleans, `null`, arrays, and objects are stringified deterministically with sorted object keys. Missing variables throw by default or stay unchanged with `{ missing: "preserve" }`.
@@ -123,8 +134,12 @@ const messages = await createDefaultInputBuilder().build(prompt, {
   },
   middleware,
 });
+
+await session.run("Explain this", { inputLayout: "cache_aware" });
 ```
 
+Cache-aware mode is opt-in; hosts that do nothing keep legacy order.
+
 ## Extension and configuration notes
 
 Extensions can contribute `InputBuilder`, `PromptBuilder`, and `ContextProvider` objects through the extension API, but contributions stay inert until the host resolves and calls or passes them. The agent/session runtime uses configured builders/providers only when the host puts them on `AgentConfig`; it does not load extensions or registries itself. Defaults are built-ins; hosts can replace them with compatible builders. Prompt templates are caller-side string expansion only; they do not load resources or contributions.
@@ -147,7 +162,7 @@ const request = await assembleProviderInput({
 
 ## Security and performance notes
 
-- The builder is linear in supplied messages, attachments, resources, and tool results.
+- The builder is linear in supplied messages, attachments, resources, and tool results. Layout selection is one flattening branch over already-built groups.
 - Template expansion is dependency-free string replacement over `{{name}}` variables. It does not evaluate expressions, filters, loops, partials, JavaScript, globals, or prototype properties.
 - It performs no provider calls, tool execution, credential resolution, package discovery, filesystem scan, network access, timers, or watchers.
 - URI attachments/resources load only through the caller-provided `ResourceLoader`.
@@ -157,6 +172,7 @@ const request = await assembleProviderInput({
 
 ## Related APIs
 
+- [SDK customization guide](customization.md): high-level map of replaceable provider resolution, middleware, context, builder, injector, loop, compaction, retry, store, and skill seams.
 - [Public contracts](public-contracts.md): `Message`, `ContentBlock`, `InputBuilder`, `InputBuildContext`, `ToolResult`, and `ResourceLoader` shapes.
 - [Context and skills](context-and-skills.md): ordered context resolution feeding prompt composition.
 - [Resource loading](resource-loading.md): `loadTextResource()` behavior used for explicit URI resources.

package/docs/instruction-injection.md

@@ -0,0 +1,183 @@
+# Instruction injection
+
+## What it does
+
+Instruction injectors let a package modify how context is formulated and inject its own instructions to modify agent behavior — on the first turn, every turn, or in response to user input — without forking the input/prompt pipeline and without hidden globals. Each injector contributes only `instructions` (text) and `contextBlocks`; it cannot register tools, skills, or permissions, and cannot bypass the validator or the permission gate.
+
+Injectors are the package-side complement to the host-owned `systemInstructions` base path: the host sets base instructions, then selected package injectors layer additional instructions and context blocks per turn.
+
+## When to use it
+
+- A package wants to bias the model toward a response format (e.g. "answer in JSON") every turn.
+- A package wants to inject project context (e.g. a repo summary) on the first turn only.
+- A package wants to react to user input (via a `predicate`) without re-authoring the assembler.
+- A package wants to ship a discoverable `.agents/instructions/<name>/` bundle that hosts opt into by name.
+
+Injectors are **not** a way to grant tool access, change credentials, or mutate provider request options.
+
+## Inputs / request
+
+Injectors implement `InstructionInjector`:
+
+```ts
+type InstructionTiming = "first_turn" | "every_turn" | "on_input";
+
+interface InstructionContext {
+  readonly sessionId: string;
+  readonly runId: string;
+  readonly turn: number;          // 1-based; undefined is treated as turn 1
+  readonly input: readonly Message[];  // already redacted by the runtime
+  readonly history: readonly Message[]; // redacted messages from prior turns
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly signal: AbortSignal;
+}
+
+interface InstructionContribution {
+  readonly instructions?: string;
+  readonly contextBlocks?: readonly ContextBlock[];
+  readonly when: InstructionTiming;
+  readonly predicate?: (ctx: InstructionContext) => boolean;
+}
+
+interface InstructionInjector {
+  readonly name: string;
+  readonly description?: string;
+  apply(ctx: InstructionContext): InstructionContribution;
+}
+```
+
+`InstructionContext` fields are already redacted by the runtime before `apply` runs: current input is run through the active `AgentConfig.redactor` / `RunOptions.redactor` during assembly, and history holds previously-redacted messages. Direct `assembleProviderInput()` callers that use injectors should pass the same `redactor` option to keep this boundary.
+
+### Lifecycle
+
+| `when` | `predicate` | Applied when |
+|---|---|---|
+| `first_turn` | ignored | `ctx.turn === 1` |
+| `every_turn` | ignored | every turn |
+| `on_input` | absent | every turn (default) |
+| `on_input` | present | turns where `predicate(ctx)` returns `true` |
+
+Only `instructions` and `contextBlocks` are honored from a contribution; other fields grant nothing (see [Security and performance notes](#security-and-performance-notes)).
+
+## Outputs / response / events
+
+Injectors do not emit events. Their output is folded into the assembled `ProviderRequest`:
+
+- **Instructions** layer via `composeSystemPrompt(injectorContributions, { base: systemInstructions })` as `source: "package"`, `mode: "append"`. Host base instructions come first, then injector package instructions appended. This keeps a single prompt-composition code path (no parallel prompt code in the assembler).
+- **Context blocks** merge via `resolveContextProviders`, appended after host+skill provider blocks, before the context middleware hook runs. `ponytail:` the assembler threads `injectedBlocks` into `resolveContextProviders` so the existing context middleware flow is untouched and the diff stays minimal.
+
+`runInstructionInjectors(injectors, ctx)` runs each selected injector against a turn-local `InstructionContext`, returning `{ instructions: SystemPromptContribution[]; contextBlocks: ContextBlock[] }`. It aborts on `ctx.signal`.
+
+## Request/response example
+
+```ts
+const jsonInjector: InstructionInjector = {
+  name: "json-always",
+  apply: () => ({ instructions: "Always answer in JSON.", when: "every_turn" }),
+};
+
+const projectContext: InstructionInjector = {
+  name: "project-context",
+  apply: () => ({
+    contextBlocks: [{ title: "Repo", content: "Prism monorepo — see docs/." }],
+    when: "first_turn",
+  }),
+};
+
+const onInputJson: InstructionInjector = {
+  name: "json-on-json-input",
+  apply: (ctx) => ({
+    instructions: "Reply with JSON because the user asked for JSON.",
+    when: "on_input",
+    predicate: (c) => c.input.some((m) => /json/i.test(JSON.stringify(m.content))),
+  }),
+};
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, createSecretRedactor } from "@arnilo/prism";
+
+const jsonInjector = { name: "json-always", apply: () => ({ instructions: "Answer in JSON.", when: "every_turn" as const }) };
+
+const session = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerDone()]),
+  instructions: "You are helpful.",
+  instructionInjectors: [jsonInjector],
+}).createSession();
+
+await session.run("List primes under 10.");
+```
+
+### Selection and override semantics
+
+`AgentConfig.instructionInjectors` configures a base injector list; `RunOptions.instructionInjectors` overrides it (last wins), mirroring `activeSkills`. `resolveInstructionInjectors` resolves names against a registry fail-closed:
+
+```ts
+import { resolveInstructionInjectors } from "@arnilo/prism";
+
+const injectors = resolveInstructionInjectors({ registry, names: ["json-always", "project-context"] });
+// Unknown name throws: Error: Unknown instruction injector: <name>
+```
+
+### Phase 29 discovery loading
+
+A discovered `.agents/instructions/<name>/manifest.json` (see [Contribution discovery](contribution-discovery.md)) becomes a live injector via the host-owned Node adapter — core performs no `import()`:
+
+```ts
+import { registerDiscoveredInstructionInjectors } from "@arnilo/prism/node/instruction-injectors";
+
+// markdown-only (no `module` field) → static every_turn injector reading resource text;
+// module-referenced → host-supplied moduleLoader (skipped when absent).
+// resourceTrust is only needed for absolute/outside resource files.
+await registerDiscoveredInstructionInjectors(registries, discovered, { moduleLoader, resourceTrust });
+```
+
+The CLI wires this under `--discover` (see below). Hosts embedding the SDK keep the registry empty and supply injectors directly on `AgentConfig`/`RunOptions`.
+
+### CLI and RPC
+
+CLI:
+
+```
+# select a discovered injector by name (repeatable)
+prism --discover --discover-kinds instructions --instruction json-always -p "Hi" --provider mock
+
+# load a markdown file as a static every_turn injector (repeatable)
+prism --injector-file ./rules/json.md -p "Hi" --provider mock
+
+# disable all injectors for a run (including AgentConfig injectors)
+prism --instruction false -p "Hi" --provider mock
+```
+
+`--instruction false` disables; `--instruction <name>` fails closed (exit 1) on an unknown name. Names resolve against discovered injectors only when `--discover` ran; without discovery, `--instruction` requires a name present in the session's `instructionInjectors` (host-supplied).
+
+RPC: `prompt`/`followUp` params accept an optional `instructionInjectors: readonly string[]` field. Names resolve against the `instructionInjectors` registry passed to `runRpcServer({ instructionInjectors })`; an unknown name fails closed with a correlated error response and no provider call.
+
+## Extension and configuration notes
+
+- Register via `ExtensionAPI.registerInstructionInjector(injector)` (Phase 30). Each injector is stored by `injector.name` (last-write-wins).
+- Select on `AgentConfig.instructionInjectors` or `RunOptions.instructionInjectors` (`RunOptions` wins). `RunOptions.instructionInjectors` is a list of `InstructionInjector` instances; hosts embed names by passing instances resolved through `resolveInstructionInjectors`.
+- Manifest `kind: "instructionInjector"` (Phase 30) declares contributions data-only; discovery of `kind: "instructions"` is the filesystem vehicle (see [Configuration and manifests](configuration-and-manifests.md)).
+- `turn` is plumbed through `LoopContext.assemble(nextInput, toolResults?, turn?)` (Phase 30) so injectors see the loop-local turn, not a stale value.
+
+## Security and performance notes
+
+- **No privilege grant:** `InstructionContribution` exposes only `instructions`/`contextBlocks`/`when`/`predicate`. There is no `tools`, `skills`, `permissions`, or `execute` field; a malformed contribution smuggling those fields contributes only `instructions`. Registering an injector adds entries only to `instructionInjectors`; `tools`/`skills`/`contextProviders`/`systemPromptContributions` stay empty.
+- **Cannot bypass validator or permissions:** injectors are layered into prompt assembly; tool dispatch still re-checks the active registry (`unknown_tool`), filters, arguments, the permission assertion, and `validate` (Phase 4/25/26).
+- **Secrets never enter history/events:** secrets in injector-produced `instructions`/`contextBlocks` are redacted in the outgoing `ProviderRequest` (via `redactProviderRequest`) and in emitted events (via `redactAgentEvent`). Do not put secrets in injector text at authoring time; the redactor is a backstop, not an invitation.
+- **Resource containment:** markdown-only discovered injectors resolve `resource` relative to their contribution directory and realpath-check it before read. Relative `..`, absolute paths, or symlinks that escape the contribution directory are rejected unless the host passes an explicit `resourceTrust` policy; `permission` is still checked before reading.
+- No hidden globals: injectors are resolved explicitly per run; nothing is auto-activated or auto-imported by core.
+
+## Related APIs
+
+- [Input and prompt assembly](input-and-prompt-assembly.md): default prompt builder and `assembleProviderInput`, where injector instructions/blocks are merged.
+- [System prompts](system-prompts.md): `composeSystemPrompt` and the `package`/`app`/`user`/`run` layering injectors layer into.
+- [Context and skills](context-and-skills.md): `resolveContextProviders` merge order and skill `context`.
+- [Contribution registries](contribution-registries.md): `instructionInjectors` registry.
+- [Contribution discovery](contribution-discovery.md): `.agents/instructions/<name>/` discovery and the host-owned `loadInstructionInjector` adapter.
+- [Extensions](extensions.md): `registerInstructionInjector` in the contribution-kinds list.
+- [CLI and RPC](cli-rpc.md): `--instruction`/`--injector-file` flags and the RPC `instructionInjectors` field.
+- [Credentials and redaction](credentials-and-redaction.md): `createSecretRedactor`, `redactProviderRequest`, `redactAgentEvent`.