@arnilo/prism 0.0.1

package/docs/configuration-and-manifests.md

@@ -0,0 +1,142 @@
+# Configuration and manifests
+
+## What it does
+
+Configuration helpers merge host-provided JSON config layers in a deterministic order. Manifest helpers validate data-only package manifests that describe contribution/resource declarations and config defaults without importing or executing package code.
+
+APIs:
+
+- `mergeConfigLayers()` / `ConfigLayer`
+- `loadConfigLayers()` / `ConfigProvider`
+- `isJsonObject()` / `assertJsonObject()`
+- `definePrismManifest()` / `parsePrismManifest()`
+- `PrismManifest`, `ManifestContributionDeclaration`, `ManifestResourceDeclaration`
+
+## When to use it
+
+Use these APIs when a host or package needs an in-memory config merge or wants to publish a data-only Prism manifest.
+
+Do not use them for package discovery, dynamic imports, executable plugin loading, credential storage, filesystem config loading, resource fetching, or agent/session runtime startup. Those are explicit host or later-phase choices.
+
+## Inputs / request
+
+```ts
+mergeConfigLayers(layers: readonly ConfigLayer[]): JsonObject
+loadConfigLayers(providers: readonly ConfigProvider[], context?: ConfigLoadContext): Promise<ConfigLayer[]>
+definePrismManifest(manifest: PrismManifest): PrismManifest
+parsePrismManifest(value: unknown): PrismManifest
+```
+
+`ConfigLayer`:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `name` | `string` | Layer name used for diagnostics. |
+| `config` | `JsonObject` | JSON config values for that layer. |
+
+`PrismManifest`:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `name` | `string` | Package/manifest name. |
+| `version` | `string` | Optional package/manifest version. |
+| `description` | `string` | Optional description. |
+| `configDefaults` | `JsonObject` | Optional JSON defaults contributed by the manifest. |
+| `contributions` | `ManifestContributionDeclaration[]` | Optional data-only contribution declarations. |
+| `resources` | `ManifestResourceDeclaration[]` | Optional prompt/skill/package resource declarations by URI. |
+| `metadata` | `JsonObject` | Optional JSON metadata. |
+
+`ManifestContributionKind` values match `createContributionRegistries()` categories:
+
+| Kind | Registry | Notes |
+| --- | --- | --- |
+| `provider` | `providers` | Provider adapter declaration. |
+| `model` | `models` | Model metadata declaration. |
+| `tool` | `tools` | Tool definition declaration. |
+| `contextProvider` | `contextProviders` | Context provider declaration. |
+| `skill` | `skills` | Skill declaration. |
+| `command` | `commands` | RPC command declaration. |
+| `agent` | `agents` | Agent definition declaration. |
+| `inputBuilder` | `inputBuilders` | Input builder declaration. |
+| `promptBuilder` | `promptBuilders` | Prompt builder declaration. |
+| `compactionStrategy` | `compactionStrategies` | Compaction strategy declaration. |
+| `retryPolicy` | `retryPolicies` | Retry policy declaration. |
+| `storeFactory` | `storeFactories` | Session store factory declaration. |
+| `resourceLoader` | `resourceLoaders` | Resource loader declaration. |
+| `settingsProvider` | `settingsProviders` | Settings provider declaration. |
+| `credentialResolver` | `credentialResolvers` | Credential resolver declaration. |
+| `providerPackage` | `providerPackages` | Provider package declaration. |
+| `authMethod` | `authMethods` | Auth method descriptor; uses `credentialName`, never a resolved credential value. |
+| `providerRequestPolicy` | `providerRequestPolicies` | Provider request policy declaration. |
+| `systemPromptContribution` | `systemPromptContributions` | System prompt contribution declaration. |
+
+## Outputs / response / events
+
+- `mergeConfigLayers()` returns a new JSON object and does not mutate inputs.
+- Later config layers override earlier layers.
+- Nested plain objects merge recursively.
+- Arrays and primitives replace previous values.
+- `parsePrismManifest()` returns a validated manifest or throws a field-specific validation error.
+- No events are emitted and no registries are modified by these helpers.
+
+## Request/response example
+
+```json
+{
+  "layers": ["built-in", "manifest", "host", "user", "runtime"],
+  "manifest": {
+    "name": "demo-package",
+    "configDefaults": { "demo": { "enabled": true } }
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { definePrismManifest, mergeConfigLayers } from "@arnilo/prism";
+
+const manifest = definePrismManifest({
+  name: "demo-package",
+  configDefaults: { demo: { enabled: true, tools: ["echo"] } },
+  contributions: [
+    { kind: "tool", name: "demo.echo", module: "./tool.js", exportName: "tool" },
+    { kind: "retryPolicy", name: "demo.retry", module: "./retry.js", exportName: "retry" },
+    { kind: "providerPackage", name: "demo-provider" },
+    { kind: "authMethod", name: "demo.api-key", metadata: { credentialName: "apiKey" } },
+    { kind: "providerRequestPolicy", name: "demo.cache" },
+    { kind: "systemPromptContribution", name: "demo.prompt" },
+  ],
+  resources: [{ uri: "package://demo/prompt.md", purpose: "prompt" }],
+});
+
+const config = mergeConfigLayers([
+  { name: "built-in", config: {} },
+  { name: "manifest", config: manifest.configDefaults ?? {} },
+  { name: "runtime", config: { demo: { enabled: false } } },
+]);
+
+console.log(config.demo);
+```
+
+## Extension and configuration notes
+
+- 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`.
+- 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.
+- 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.
+
+## Related APIs
+
+- [Contribution registries](contribution-registries.md): manifest contribution `kind` values describe registry categories.
+- [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.

package/docs/context-and-skills.md

@@ -0,0 +1,113 @@
+# Context and skills
+
+## What it does
+
+`resolveContextProviders()` runs host-selected `ContextProvider` objects in caller order and returns explicit `ContextBlock[]`. `createSkillRegistry()` stores host-selected `Skill` objects, and `resolveActiveSkills()` discloses only requested skills after checking their `toolNames` against host-active tools.
+
+## 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.
+
+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.
+
+## Inputs / request
+
+```ts
+import { resolveContextProviders } from "@arnilo/prism";
+
+const context = await resolveContextProviders({
+  providers: [projectContext],
+  messages,
+  sessionId: "s1",
+  runId: "r1",
+  metadata: { requestId: "r1" },
+  signal,
+});
+```
+
+`ResolveContextOptions` accepts `providers`, `messages`, optional session/run ids, metadata, abort signal, and optional middleware.
+
+Skill selection:
+
+```ts
+import { createSkillRegistry, resolveActiveSkills } from "@arnilo/prism";
+
+const registry = createSkillRegistry([{ name: "brief", instructions: "Answer briefly.", toolNames: ["echo"] }]);
+const active = resolveActiveSkills({
+  registry,
+  names: ["brief"],
+  tools: activeTools,
+});
+```
+
+`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.
+
+## Request/response example
+
+```json
+{
+  "providers": ["project"],
+  "skills": ["brief"],
+  "activeTools": ["echo"],
+  "messages": [{ "role": "user", "content": [{ "type": "text", "text": "Explain" }] }]
+}
+```
+
+```json
+[
+  { "title": "Project", "content": "Project context" }
+]
+```
+
+## Implementation example
+
+```ts
+import { assembleProviderInput, createDefaultPromptBuilder, resolveActiveSkills, resolveContextProviders } from "@arnilo/prism";
+
+const blocks = await resolveContextProviders({ providers, messages });
+
+const activeSkills = resolveActiveSkills({ registry: skills, names: ["brief"], tools: activeTools });
+const request = await assembleProviderInput({
+  model: { provider: "mock", model: "demo" },
+  input: "Explain this file",
+  contextProviders: providers,
+  promptBuilder: createDefaultPromptBuilder(),
+  skills: activeSkills,
+  tools: activeTools,
+});
+```
+
+## 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.
+
+```ts
+const providers = [kernel.registries.contextProviders.resolve("project")];
+const skillRegistry = createSkillRegistry([kernel.registries.skills.resolve("brief")]);
+const skills = resolveActiveSkills({ registry: skillRegistry, names: ["brief"], tools: activeTools });
+```
+
+`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.
+
+## 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.
+- 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.
+
+## 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.
+- [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.
+- [Tools](tools.md): host-owned active tools and permissions.

package/docs/contribution-registries.md

@@ -0,0 +1,118 @@
+# Contribution registries
+
+## What it does
+
+Contribution registries are explicit, host-owned maps for extension/package contributions. They let hosts register and resolve providers, models, provider packages, auth methods, provider request policies, system prompt contributions, tools, context providers, skills, commands, agents, input builders, prompt builders, compaction strategies, retry policies, store factories, resource loaders, settings providers, and credential resolvers without hidden globals.
+
+APIs:
+
+- `createContributionRegistry<T>()` / `ContributionRegistry<T>`: generic string-keyed registry.
+- `createContributionRegistries()` / `ContributionRegistries`: typed bundle for Phase 2 contribution categories.
+
+## When to use it
+
+Use these registries when a host app or extension kernel needs direct registration and fail-closed lookup before runtime behavior executes.
+
+Do not use them as a dependency injection container, manifest loader, settings loader, credential store, active tool registry, tool dispatcher, or agent/session runtime. For tools, copy selected `registries.tools` entries into `createToolRegistry()` before dispatch.
+
+## Inputs / request
+
+```ts
+createContributionRegistry<T>(options?: { label?: string }): ContributionRegistry<T>
+createContributionRegistries(): ContributionRegistries
+```
+
+`ContributionRegistry<T>` methods:
+
+| Method | Input | Result |
+| --- | --- | --- |
+| `register(key, contribution)` | string key and contribution | Stores or replaces the contribution for that key. |
+| `get(key)` | string key | Returns the contribution or `undefined`. |
+| `resolve(key)` | string key | Returns the contribution or throws `Unknown <label>: <key>`. |
+| `list()` | none | Returns contributions in insertion order. |
+
+`ContributionRegistries` includes existing `providers` and `models` registries plus generic registries for `providerPackages`, `authMethods`, `providerRequestPolicies`, `systemPromptContributions`, `tools`, `contextProviders`, `skills`, `commands`, `agents`, `inputBuilders`, `promptBuilders`, `compactionStrategies`, `retryPolicies`, `storeFactories`, `resourceLoaders`, `settingsProviders`, and `credentialResolvers`.
+
+## Outputs / response / events
+
+Registry calls return plain contribution objects. Unknown `resolve()` calls throw before provider, model, tool, credential, prompt, resource, or session behavior can run. `systemPromptContributions` are inert until a host passes selected values to `AgentConfig.systemPrompt` or `RunOptions.systemPrompt`.
+
+Registering the same key replaces the contribution deterministically. Registries do not emit events by themselves; the extension kernel may emit events when it uses them.
+
+## Request/response example
+
+```json
+{
+  "registered": "echo",
+  "resolved": "echo"
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createContributionRegistries, type ToolDefinition } from "@arnilo/prism";
+
+const tool: ToolDefinition = {
+  name: "echo",
+  execute(args, context) {
+    return { toolCallId: context.toolCallId, name: "echo", value: args };
+  },
+};
+
+const registries = createContributionRegistries();
+registries.tools.register(tool.name, tool);
+registries.agents.register("demo", {
+  name: "demo",
+  create: () => createAgent({ model, provider, tools: [tool] }),
+});
+
+const resolved = registries.tools.resolve("echo");
+console.log(resolved.name); // contributed only, not active for dispatch yet
+
+const inputBuilder = registries.inputBuilders.get("custom-input");
+const contextProviders = registries.contextProviders.get("project") ? [registries.contextProviders.resolve("project")] : [];
+const promptBuilder = registries.promptBuilders.get("custom-prompt");
+const skill = registries.skills.get("brief");
+const agent = await registries.agents.resolve("demo").create();
+void agent;
+void inputBuilder;
+void contextProviders;
+void promptBuilder;
+void skill;
+```
+
+## Extension and configuration notes
+
+- Hosts can use contribution registries directly and skip extension loading entirely.
+- Extension packages should register contributions through the host-provided extension API once the extension kernel is in use.
+- Registry keys are explicit strings. Prefer stable ids/names such as `provider.id`, `tool.name`, `skill.name`, or package-qualified names when collisions matter.
+- Manifest contribution `kind` values match these registry keys. For example, `authMethods` accepts `authMethod` manifest declarations, `providerPackages` accepts `providerPackage`, `providerRequestPolicies` accepts `providerRequestPolicy`, and `systemPromptContributions` accepts `systemPromptContribution`.
+- Manifest and configuration loading are separate APIs; this page only covers in-memory registration.
+- Tool contributions are inert. They are not executable until the host registers selected definitions in an active tool registry and passes that registry to `dispatchToolCall()`.
+- Provider packages, auth methods, provider request policies, and system prompt contributions are inert until the host resolves them and explicitly calls setup or passes them to a runtime/helper that documents the call site.
+- Input builders, prompt builders, context providers, skills, compaction strategies, and retry policies are inert until the host resolves them and calls, passes, registers, or selects them for runtime helpers.
+- Agent definitions are inert until the host resolves one and calls `create()`. A definition may call `createAgent()` with explicit provider/tools/context/skills; registries are not hidden globals for the runtime.
+
+## Security and performance notes
+
+- Generic registries are `Map`-backed with O(1) lookup.
+- Registries are explicit objects returned by factories. Prism does not create hidden global contribution registries.
+- Registries must not store resolved credential values, tokens, headers, or secret-bearing settings.
+- `credentialResolvers` may store resolver objects, but resolved credentials must stay at the edge that needs them.
+- Registry operations do not perform network, filesystem, provider, credential, tool, or resource work.
+- Resolving a tool contribution returns data/code supplied by the host or extension; it does not grant allow-list permission or execute the tool.
+- Resolving Phase 5 builder/context/skill contributions only returns data/code. The host still chooses which builder, provider, or skill to pass into input/prompt assembly.
+
+## Related APIs
+
+- [Provider packages](provider-packages.md): provider package and model metadata contribution primitives.
+- [Provider layer](provider-layer.md): existing provider/model registries reused by `ContributionRegistries`.
+- [Agent/session runtime](agent-session-runtime.md): selected `AgentDefinition` values can create runtime agents with explicit config.
+- [Input and prompt assembly](input-and-prompt-assembly.md): default builders and provider-input assembly for selected contributions.
+- [System prompts](system-prompts.md): composing selected system prompt contributions.
+- [Context and skills](context-and-skills.md): ordered resolution for selected context providers and progressive disclosure for selected skills.
+- [Tools](tools.md): active host tool registry, filtering, and dispatch for selected tool definitions.
+- [Compaction and retry policies](compaction-and-retry.md): selected compaction strategy and retry policy behavior.
+- [Public contracts](public-contracts.md): contribution contract types stored in these registries.
+- [Credentials and redaction](credentials-and-redaction.md): credential resolver and secret-redaction rules.

package/docs/credentials-and-redaction.md

@@ -0,0 +1,122 @@
+# Credentials and redaction
+
+## What it does
+
+Prism provides small helpers for host-owned credentials and known-secret redaction:
+
+- `resolveCredentialValue()`: resolves a credential from a direct string, callback, or `CredentialResolver`.
+- `createExplicitCredentialResolver()`: tries named resolver sources in caller-provided order, such as runtime override → stored → env object → fallback.
+- `createEnvCredentialResolver()`: reads only a caller-supplied env-like object and map.
+- `refreshOAuthCredential()`: calls a provider OAuth refresh function and writes the result to a caller-owned store when supplied.
+- `CredentialValueSource`: the accepted source type for `resolveCredentialValue()`.
+- `redactSecrets()`: replaces known secret string values inside strings, arrays, and plain objects.
+- `errorToErrorInfo()`: converts unknown errors into `ErrorInfo` and redacts known secret values from error text.
+
+These helpers do not persist credentials, scan environment variables, execute commands, or load settings.
+
+## When to use it
+
+Use these helpers inside provider adapters or host integration code that needs to resolve a credential at request time and prevent known secret values from appearing in emitted errors or logs.
+
+Do not use them as a credential manager, general secret scanner, vault, settings loader, or permission system.
+
+## Inputs / request
+
+```ts
+resolveCredentialValue(
+  source: CredentialValueSource | undefined,
+  request: CredentialRequest,
+): Promise<string | undefined>
+```
+
+`CredentialValueSource` can be:
+
+| Source | Behavior |
+| --- | --- |
+| `string` | Returned directly. |
+| `() => string | undefined | Promise<string | undefined>` | Called when a credential is needed. |
+| `CredentialResolver` | `resolve(request)` is called and `.value` is returned. |
+
+```ts
+createExplicitCredentialResolver(sources: readonly CredentialResolverSource[]): CredentialResolver
+createEnvCredentialResolver(env: Readonly<Record<string, string | undefined>>, map: Readonly<Record<string, string>>): CredentialResolver
+refreshOAuthCredential(options: { provider: OAuthProvider; credentials: OAuthCredentials; store?: OAuthCredentialStore }): Promise<OAuthCredentials>
+redactSecrets<T>(value: T, secrets: readonly (string | undefined)[]): T
+errorToErrorInfo(error: unknown, secrets?: readonly (string | undefined)[]): ErrorInfo
+```
+
+`secrets` must be the exact values to redact. Undefined and empty values are ignored.
+
+## Outputs / response / events
+
+- `resolveCredentialValue()` returns a credential string or `undefined`.
+- `redactSecrets()` returns the same value shape with known string secrets replaced by `[REDACTED]`.
+- `errorToErrorInfo()` returns `{ name?, message, code?, cause? }` with known secret values removed from message/cause text.
+
+## Request/response example
+
+```json
+{
+  "request": { "name": "apiKey", "provider": "demo" },
+  "resolved": "<host-owned credential value>",
+  "redactedError": { "message": "bad key [REDACTED]" }
+}
+```
+
+## Implementation example
+
+```ts
+import {
+  createEnvCredentialResolver,
+  createExplicitCredentialResolver,
+  errorToErrorInfo,
+  redactSecrets,
+  resolveCredentialValue,
+} from "@arnilo/prism";
+
+const runtime = { resolve: () => undefined };
+const stored = { resolve: () => undefined };
+const env = createEnvCredentialResolver({ DEMO_API_KEY: "fake-demo-key" }, { demo: "DEMO_API_KEY" });
+const resolver = createExplicitCredentialResolver([
+  { name: "runtime", resolver: runtime },
+  { name: "stored", resolver: stored },
+  { name: "env", resolver: env },
+]);
+
+const apiKey = await resolveCredentialValue(resolver, { name: "apiKey", provider: "demo" });
+
+const message = redactSecrets(`request failed for ${apiKey}`, [apiKey]);
+const error = errorToErrorInfo(new Error(`bad credential ${apiKey}`), [apiKey]);
+
+console.log(message);
+console.log(error.message);
+```
+
+## Extension and configuration notes
+
+- Hosts and extension packages can implement `CredentialResolver` and pass it explicitly to code that needs credentials.
+- Use `createExplicitCredentialResolver()` when documenting a fixed order such as runtime override, stored credential, caller-provided env object, then fallback resolver.
+- Use `createEnvCredentialResolver()` only with an object supplied by the host; Prism does not read `process.env` for you.
+- Provider adapters should resolve credentials as late as possible, per request.
+- Keep resolved credential values local to the request path. Do not put them in registries, model configs, messages, provider events, agent events, session entries, compaction summaries, or logs.
+- Future settings/config loaders may provide credential resolver instances, but core helpers remain storage-free.
+
+## Security and performance notes
+
+- Redaction only removes exact known secret values passed to the helper. It is not a general-purpose secret detector.
+- Do not pass empty strings as secrets; they are ignored.
+- `redactSecrets()` recursively walks arrays and object entries, so avoid using it on huge objects unless needed.
+- Cycle and non-JSON value handling: `redactSecrets()` is cycle-safe via a `WeakSet` visited-set. Self-referential or mutually referenced objects render `"[Circular]"` at the back-reference instead of throwing. `Date` and `RegExp` values are passed through unchanged; `ArrayBuffer` and typed arrays are passed through unchanged; `Map` is normalized to a plain object and `Set` to an array so the output stays JSON-compatible. `errorToErrorInfo()` tolerates a cyclic `error.cause` (rendered via `String()`).
+- Use placeholders in tests and docs. Never commit real tokens.
+- Live provider/worker tests are gated behind explicit environment variables and skipped by default: `PRISM_LIVE_PROVIDER_TESTS`, `PRISM_LIVE_COMPACTION_TESTS`, `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS`. Default `npm test` is network-free; do not add ungated network calls to default tests.
+- `resolveCredentialValue()` and `createExplicitCredentialResolver()` do not cache values. Add host-side caching only if a real credential source needs it.
+- `refreshOAuthCredential()` only calls the supplied OAuth provider and optional store; it has no built-in persistence or retry loop.
+
+## Related APIs
+
+- [Public contracts](public-contracts.md): `CredentialRequest`, `Credential`, `CredentialResolver`, `CredentialResolverSource`, `OAuthLoginCallbacks`, `OAuthCredentials`, `OAuthProvider`, and `ErrorInfo`.
+- [Provider layer](provider-layer.md): `providerError()` uses `errorToErrorInfo()` for redacted provider error events.
+- [LLM compaction package](compaction-llm.md): resolves optional summary-provider credentials per compaction call and redacts exact known values.
+- [OpenAI-compatible provider](providers/openai-compatible.md): resolves API keys per request and redacts known values from adapter errors.
+
+Phase 10 added `createMemoryCredentialStore()`, `createChainedCredentialResolver()`, and `createSecretRedactor()` for opt-in in-memory auth and runtime redaction. Phase 11 adds OAuth/API-key contracts plus explicit resolver order helpers. Core still has no persistent secret store and does not read environment variables or files for credentials. See [Security/auth/trust](settings-auth-trust-security.md).

package/docs/extensions.md

@@ -0,0 +1,139 @@
+# Extension kernel and event bus
+
+## What it does
+
+The extension kernel loads host-provided `Extension` objects in order and gives each extension a runtime `ExtensionAPI`. The API can register contributions into explicit registries, register middleware, subscribe to lifecycle events, and emit events.
+
+APIs:
+
+- `createExtensionKernel()` / `ExtensionKernel`
+- `createExtensionEventBus()` / `ExtensionEventBus`
+- `ExtensionAPI`, `ExtensionEvent`, and `extension_error` events
+- Shared `MiddlewareRegistry` access and `api.use()` registration
+
+## When to use it
+
+Use the extension kernel when a host wants packages to contribute provider packages, providers, models, auth methods, provider request policies, system prompt contributions, tools, context providers, skills, commands, agents, builders, strategies, stores, resources, settings providers, or credential resolvers without editing Prism internals.
+
+Skip the kernel and use contribution registries directly when the host does not need extension setup lifecycle or events.
+
+## Inputs / request
+
+```ts
+createExtensionKernel(options?: ExtensionKernelOptions): ExtensionKernel
+createExtensionEventBus(options?: { errorPolicy?: "event" | "throw"; secrets?: readonly string[] }): ExtensionEventBus
+```
+
+`ExtensionKernelOptions`:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `registries` | `ContributionRegistries` | Optional host-created registry bundle. |
+| `middleware` | `MiddlewareRegistry` | Optional host-created middleware registry. |
+| `errorPolicy` | `"event" | "throw"` | Defaults to `"event"`; use `"throw"` for fail-fast setup/listener/middleware errors. |
+| `secrets` | readonly strings | Known secret values to redact from extension error events. |
+
+`ExtensionAPI` includes `registries`, `middleware`, `on()`, `emit()`, `use()`, and registration methods for all contribution categories, including provider packages, auth methods, provider request policies, and system prompt contributions.
+
+## Outputs / response / events
+
+- `kernel.load(extensions)` calls each extension's `setup(api)` in host-provided order.
+- `kernel.registries` exposes the explicit contribution registry bundle.
+- `kernel.events.on(type, handler)` registers ordered event handlers and returns an unsubscribe function.
+- `kernel.events.emit(event)` calls matching handlers in registration order.
+- `kernel.middleware.run(hook, value)` runs matching middleware in registration order.
+- With default `errorPolicy: "event"`, setup/listener/middleware errors become `extension_error` events with redacted `ErrorInfo`.
+- With `errorPolicy: "throw"`, setup/listener/middleware errors reject/throw.
+
+## Request/response example
+
+```json
+{
+  "loaded": ["demo-extension"],
+  "events": [{ "type": "extension_error", "extension": "demo-extension" }]
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createExtensionKernel, type Extension } from "@arnilo/prism";
+
+const extension: Extension = {
+  name: "demo-extension",
+  setup(api) {
+    api.registerProviderPackage({ name: "demo-provider", setup: () => undefined });
+    api.registerModel({ provider: "mock", model: "demo", capabilities: { input: ["text"] } });
+    api.registerAuthMethod({ provider: "mock", kind: "api_key", credentialName: "apiKey" });
+    api.registerProviderRequestPolicy({ name: "cache", apply: ({ request }) => request });
+    api.registerSystemPromptContribution({ id: "demo-prompt", source: "package", mode: "append", text: "Use demo rules." });
+    api.registerTool({ name: "echo", execute: (args, ctx) => ({ toolCallId: ctx.toolCallId, name: "echo", value: args }) });
+    api.registerContextProvider({ name: "project", resolve: () => [{ title: "Project", content: "Context" }] });
+    api.registerInputBuilder({ name: "input", build: async () => [{ role: "user", content: [{ type: "text", text: "Hello" }] }] });
+    api.registerPromptBuilder({ name: "prompt", build: async (request) => request.messages });
+    api.registerSkill({ name: "brief", instructions: "Answer briefly.", toolNames: ["echo"] });
+    api.registerAgent({ name: "demo", create: () => createAgent({ model, provider }) });
+    api.registerCompactionStrategy({ name: "compact", compact: () => ({ summary: "summary" }) });
+    api.registerRetryPolicy({ name: "retry", decide: () => ({ retry: false }) });
+    api.on("session_start", (event) => {
+      console.log(event.type);
+    });
+    api.use("provider_request", (request) => request);
+    api.use("compaction", (payload) => payload);
+    api.use("retry", (payload) => payload);
+  },
+};
+
+const kernel = createExtensionKernel({ errorPolicy: "event" });
+await kernel.load([extension]);
+
+console.log(kernel.registries.models.resolve("mock", "demo").model);
+console.log(kernel.registries.tools.resolve("echo").name); // contributed only; host must activate before dispatch
+console.log(kernel.registries.contextProviders.resolve("project").name); // contributed only; host must select before context resolution
+console.log(kernel.registries.inputBuilders.resolve("input").name); // contributed only; host must pass it to assembly
+console.log(kernel.registries.promptBuilders.resolve("prompt").name); // contributed only; host must pass it to assembly
+console.log(kernel.registries.skills.resolve("brief").name); // contributed only; host must select before prompt use
+console.log(kernel.registries.agents.resolve("demo").name); // contributed only; host must create/select before runtime use
+console.log(kernel.registries.systemPromptContributions.resolve("demo-prompt").text); // contributed only; host must select before prompt use
+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.
+- 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.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.
+- `api.use("compaction", middleware)` and `api.use("retry", middleware)` observe or adjust runtime compaction/retry payloads only when the host passes that middleware registry to `createAgent({ middleware })`; compaction strategy and retry policy contributions remain inert until selected by the host.
+- Manifest contribution `kind` values for provider packages, auth methods, provider request policies, and system prompt contributions match the registry keys populated by the extension API. See [Configuration and manifests](configuration-and-manifests.md) for data-only declaration examples.
+
+## Security and performance notes
+
+- No hidden global extension kernel, provider registry, credential resolver, settings provider, store, or resource loader is created.
+- 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.
+- Extension middleware cannot bypass host tool permissions: tool dispatch re-checks active registry lookup, filters, and object arguments after `tool_call` middleware. Skills that reference `toolNames` are checked against host-active tools by `resolveActiveSkills()`.
+
+## Related APIs
+
+- [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`.
+- [Tools](tools.md): host activation, filtering, and dispatch for contributed tool definitions.
+- [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.
+- [Agent/session runtime](agent-session-runtime.md): `AgentDefinition.create()` can return agents built with `createAgent()` from explicit host-selected config.
+- [Compaction and retry policies](compaction-and-retry.md): compaction strategy/retry policy contributions and `compaction`/`retry` middleware runtime behavior.
+- [LLM compaction package](compaction-llm.md): optional extension helper that registers a provider-backed compaction strategy.
+- [Observational memory compaction package](compaction-observational-memory.md): optional extension helper that registers an inert fast memory compaction strategy.
+- [Public contracts](public-contracts.md): `Extension`, `ExtensionAPI`, and contribution contract types.
+- [Credentials and redaction](credentials-and-redaction.md): secret-redaction behavior used for extension errors.
+
+`createExtensionKernel({ permission })` checks `extension:<name>:setup` before each extension `setup()`. Denied extensions do not run. Prism does not sandbox extension code or auto-load project-local extensions. See [Security/auth/trust](settings-auth-trust-security.md).