@arnilo/prism 0.0.1 → 0.0.3

package/docs/contribution-discovery.md

@@ -0,0 +1,149 @@
+# Contribution discovery (workspace)
+
+## What it does
+
+Discovery scans the filesystem for workspace contribution directories and turns their on-disk files into inert `DiscoveredContribution` envelopes the host then registers. It reads text only — it never `import()`s, `require()`s, or otherwise executes contribution code, and it never grants tools, permissions, credentials, or provider slots.
+
+APIs (Node subpath `@arnilo/prism/node/contribution-discovery`, parsers and registrar on the main barrel):
+
+- `discoverContributions(options)` / `DiscoveryOptions`: directory-walking scanner for the workspace `.agents/` tree. One `readdir` per kind-root.
+- `parseSkillFile(text, path)`: stdlib-only frontmatter parser for `SKILL.md` (no YAML dependency, no `node:*` import). Re-exported from `@arnilo/prism`.
+- `registerDiscoveredContributions(registries, contributions)`: registers realized `Skill` objects for the `skill` kind and descriptor-only stubs for other kinds. Re-exported from `@arnilo/prism`.
+- `ContributionFileKind`, `DiscoveredContribution`: contract types re-exported from `@arnilo/prism`.
+- `createPathTrustPolicy` / `isPathInsideReal` (from `@arnilo/prism/node/trust`): realpath-resolved, fail-closed containment used to gate workspace roots.
+
+## When to use it
+
+Use discovery when a host or the `prism` CLI wants to honor a project-local contribution layout without wiring every contribution by hand. Typical hosts pass `--discover` on the CLI or call `discoverContributions()` on startup, then feed the result through `registerDiscoveredContributions()` into their existing `ContributionRegistries`.
+
+Do not use it to discover providers — provider/model packages stay config/package-driven (Phase 24; see [Provider packages](provider-packages.md)). Do not use it to auto-activate anything: discovery registers, never activates. Skills become selectable only when a run passes `RunOptions.activeSkills`, and `toolNames` is still enforced against the resolved tool set at activation time.
+
+## Inputs / request
+
+### Directory layout
+
+| Origin | Path | Scanned by |
+| --- | --- | --- |
+| Workspace | `<workspace>/.agents/{skills,tools,context,instructions}/<name>/` | `workspaceRoot`, gated by `trust` |
+
+### Per-kind entry file
+
+| Kind | Entry file | Parsed into |
+| --- | --- | --- |
+| `skill` | `<dir>/SKILL.md` | A realized `Skill` (placed in `DiscoveredContribution.skill`) |
+| `tool` / `context` / `instructions` | `<dir>/manifest.json` | A `ManifestContributionDeclaration` |
+
+### Frontmatter keys
+
+`SKILL.md` frontmatter (YAML-like, parsed by a stdlib-only parser — no YAML dependency):
+
+| Key | Meaning |
+| --- | --- |
+| `name` | Required if you want an explicit name; otherwise the parent directory name is used. |
+| `description` | Optional skill description. |
+| `toolNames` | Optional comma list (`[a, b]`) or YAML block list (`- a`). Enforced at activation, not at discovery. |
+
+The markdown body below the front fence becomes `Skill.instructions`. Unknown frontmatter keys are tolerated and collected into `Skill.metadata` (never fatal).
+
+`manifest.json` entries follow the [`ManifestContributionDeclaration`](configuration-and-manifests.md) shape: `kind`, `name`, and optional `module`/`exportName`/`resource`/`metadata`.
+
+### `DiscoveryOptions`
+
+| Field | Meaning |
+| --- | --- |
+| `kinds` | Which `ContributionFileKind` values to scan (`skill`, `tool`, `context`, `instructions`). |
+| `workspaceRoot` | Workspace root. Gated by `trust`; untrusted roots are skipped silently. |
+| `permission?` | `PermissionPolicy` asserting each directory read (`assertPermission`). |
+| `trust?` | `TrustPolicy` (e.g. `createPathTrustPolicy`) fail-closed against the workspace root. |
+
+### CLI flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--discover` | Enable workspace contribution discovery. Opt-in; default runs never touch the filesystem. |
+| `--discover-kinds <csv>` | Kinds to scan. Defaults to `skill`. Accepts `skill,tool,context,instructions`. |
+| `--no-discovery` | Hard-disable discovery even if `--discover` is set. |
+
+## Outputs / response / events
+
+`discoverContributions()` returns `readonly DiscoveredContribution[]`. Each envelope has `kind`, `name`, `origin` (`"global"` | `"workspace"`), `path`, and either `skill` (for the `skill` kind) or `declaration` (a `ManifestContributionDeclaration` for other kinds), plus optional `metadata`. The envelope is inert: it contains no executable code, no credential, and no resolved provider/model/tool reference.
+
+`registerDiscoveredContributions(registries, contributions)` writes into the existing `ContributionRegistries`: `skills` get full `Skill` objects; `tool`/`context` get descriptor-only stubs whose `execute`/`resolve` throw (executable behavior is host-owned); `instructions` get descriptors with empty `text` (Phase 30 lifts `declaration.resource` into actual text). The host retains the original `DiscoveredContribution[]` for provenance — tool and context descriptors carry no `metadata.discovered` slot because `ToolDefinition` and `ContextProvider` have no metadata field. Phase 30 adds a host-owned `loadInstructionInjector` adapter (see [Instruction injection](instruction-injection.md)) that turns a discovered `kind: "instructions"` contribution into a live `InstructionInjector` — markdown-only → static `every_turn` injector; module-referenced → resolved through a host-supplied `moduleLoader` (core never auto-`import()`s).
+
+## Request/response example
+
+Discovering a workspace skill:
+
+```json
+[
+  { "kind": "skill", "name": "greeter", "origin": "workspace", "path": "/proj/.agents/skills/greeter/SKILL.md", "skill": { "name": "greeter", "description": "g", "instructions": "..." } }
+]
+```
+
+## Implementation example
+
+```ts
+import {
+  createContributionRegistries,
+  registerDiscoveredContributions,
+  createSkillRegistry,
+  createAgent,
+  createMockProvider,
+  providerDone,
+} from "@arnilo/prism";
+import { discoverContributions } from "@arnilo/prism/node/contribution-discovery";
+import { createPathTrustPolicy } from "@arnilo/prism/node/trust";
+
+// 1. Discover — workspace gated by trust.
+const trust = createPathTrustPolicy({ trustedRoots: [workspaceRoot] });
+const discovered = await discoverContributions({
+  kinds: ["skill"],
+  workspaceRoot,
+  trust,
+});
+
+// 2. Register — skills become full Skill objects; other kinds register as stubs.
+//    Discovery never imports or executes contribution code.
+const registries = createContributionRegistries();
+registerDiscoveredContributions(registries, discovered);
+
+// 3. Run — discovery did NOT activate anything. The run explicitly selects skills.
+const session = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerDone()]),
+  skills: createSkillRegistry(registries.skills.list()),
+}).createSession();
+
+await session.run("Hi", { activeSkills: ["greeter"] });
+```
+
+A complete runnable example lives at `examples/discover-skills.ts`.
+
+## Extension and configuration notes
+
+- Discovery is loader-driven, not module-driven. The on-disk contribution is a data file (`SKILL.md`/`manifest.json`); the host decides whether, when, and how to register and activate it. There is no `import()` of untrusted modules.
+- `ContributionFileKind` is the discovery-side kind name (`skill`/`tool`/`context`/`instructions`). The manifest-side kind is `ManifestContributionKind` ([Configuration and manifests](configuration-and-manifests.md)); the node scanner maps between them.
+- The `--discover-kinds` CSV lets a host scan a subset. The CLI default is `skill`; other kinds register descriptor stubs only (host-owned execution).
+- First-party skills are expected to ship as installable packages (separate request); Phase 29 ships discovery infrastructure only and adds no first-party skill package.
+
+## Security and performance notes
+
+- **Workspace gating**: workspace roots are checked through `createPathTrustPolicy` + `isPathInsideReal`, which resolve symlinks and fail closed (return false) if either root or target cannot be resolved. Untrusted workspace roots are skipped silently, never thrown over. Permission is asserted per directory read via `assertPermission`.
+- **Symlink handling**: symlinked entries that escape the kind root after realpath resolution are excluded. `SKILL.md` and `manifest.json` are also realpath-checked against their contribution directory before read, so an entry-file symlink cannot escape to another path.
+- **Opt-in**: discovery is opt-in — it runs only when the host passes `--discover` or calls `discoverContributions()` explicitly. Default runs perform no filesystem I/O.
+- **No auto-execute**: discovery reads text. It does not `import()`, `require()`, or run contribution code. `registerDiscoveredContributions` registers descriptor stubs whose execution methods throw — the host lifts them into live tools/providers itself.
+- **No auto-activate**: discovery registers skills; it does not select them. Activation requires explicit `RunOptions.activeSkills`, and `toolNames` is still validated against the resolved tool set. Discovery grants no tools, permissions, or provider slots.
+- **No provider scanning**: provider/model discovery stays config/package-driven (Phase 24). See [Provider packages](provider-packages.md).
+- **AGENTS.md / SYSTEM.md are not discovery kinds**: the root-level `AGENTS.md` (workspace) prompt file does not fit the named-subdir scanner and is loaded by a sibling Node loader, `loadSystemPromptFiles` from `@arnilo/prism/node/system-prompts`. See [System prompts](system-prompts.md). The CLI auto-loads `AGENTS.md` in print/json modes; RPC mode does not (host-owned).
+- **Secrets**: the secrets-redaction path is unaffected — discovery reads contribution files, not provider request content. Skill `instructions` flow through normal input assembly and the same redaction pipeline as any system message.
+- **Performance**: one `readdir` per kind-root per origin; missing kind directories are normal (ENOENT-tolerant). Default runs perform no discovery I/O at all. The merged output is inert.
+
+## Related APIs
+
+- [Contribution registries](contribution-registries.md): where discovered envelopes are registered.
+- [Context and skills](context-and-skills.md): `createSkillRegistry` / `resolveActiveSkills` and the `RunOptions.activeSkills` activation that consumes discovered skills.
+- [Extensions](extensions.md): host-provided extensions still register contributions programmatically; discovery is the filesystem-driven complement.
+- [Configuration and manifests](configuration-and-manifests.md): `ManifestContributionDeclaration` / `ManifestContributionKind` shapes used by non-skill entries.
+- [CLI/RPC](cli-rpc.md): the `--discover`, `--discover-kinds`, and `--no-discovery` flags.
+- [System prompts](system-prompts.md): `loadSystemPromptFiles` loads root-level `AGENTS.md` / `SYSTEM.md` — a sibling loader, not a scanner kind.
+- [Security/auth/trust](settings-auth-trust-security.md): `createPathTrustPolicy`, `assertPermission`, and the trust model.

package/docs/contribution-registries.md

@@ -18,15 +18,15 @@ Do not use them as a dependency injection container, manifest loader, settings l
 ## Inputs / request
 
 ```ts
-createContributionRegistry<T>(options?: { label?: string }): ContributionRegistry<T>
-createContributionRegistries(): ContributionRegistries
+createContributionRegistry<T>(options?: { label?: string; duplicate?: "replace" | "error" }): ContributionRegistry<T>
+createContributionRegistries(options?: { duplicate?: "replace" | "error" }): ContributionRegistries
 ```
 
 `ContributionRegistry<T>` methods:
 
 | Method | Input | Result |
 | --- | --- | --- |
-| `register(key, contribution)` | string key and contribution | Stores or replaces the contribution for that key. |
+| `register(key, contribution)` | string key and contribution | Stores/replaces the contribution for that key; throws `Duplicate <label>: <key>` when `duplicate: "error"`. |
 | `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. |
@@ -37,7 +37,7 @@ createContributionRegistries(): ContributionRegistries
 
 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.
+Registering the same key replaces the contribution deterministically by default. Passing `duplicate: "error"` adds one `Map.has()` check before `set()` and throws `Duplicate <label>: <key>` instead of silently shadowing. Registries do not emit events by themselves; the extension kernel may emit events when it uses them.
 
 ## Request/response example
 
@@ -60,7 +60,7 @@ const tool: ToolDefinition = {
   },
 };
 
-const registries = createContributionRegistries();
+const registries = createContributionRegistries({ duplicate: "error" });
 registries.tools.register(tool.name, tool);
 registries.agents.register("demo", {
   name: "demo",
@@ -87,6 +87,8 @@ void skill;
 - 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.
+- Default duplicate policy is `"replace"` for compatibility and deterministic last-write-wins behavior. External apps that load third-party contributions should prefer `duplicate: "error"` to prevent silent shadowing.
+- Migration safety: when moving from legacy all-in-scope capability activation to named `AgentDefinition.tools` / `skills`, enable strict registries first so duplicate third-party names fail during registration instead of changing which capability a name resolves to.
 - 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()`.
@@ -96,7 +98,7 @@ void skill;
 
 ## Security and performance notes
 
-- Generic registries are `Map`-backed with O(1) lookup.
+- Generic registries are `Map`-backed with O(1) lookup; strict duplicate checks add one O(1) `Map.has()` during registration only.
 - 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.
@@ -116,3 +118,4 @@ void skill;
 - [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.
+- [Contribution discovery (workspace)](contribution-discovery.md): opt-in directory scanner that fills these registries from `SKILL.md`/`manifest.json`.

package/docs/credentials-and-redaction.md

@@ -95,6 +95,7 @@ console.log(error.message);
 ## Extension and configuration notes
 
 - Hosts and extension packages can implement `CredentialResolver` and pass it explicitly to code that needs credentials.
+- `AgentConfig.credentials` is host-owned metadata for compatibility; `createAgent()` / `session.run()` do not call `credentials.resolve()`. Provider adapters, compaction workers, or request policies should receive and resolve credentials at the provider edge.
 - 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.
@@ -109,6 +110,7 @@ console.log(error.message);
 - 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.
+- `AgentConfig.credentials` is not eagerly resolved, serialized into provider requests/events/stores, or passed to loops/compaction by the core runtime.
 - `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.
 

package/docs/customization.md

@@ -0,0 +1,191 @@
+# SDK customization guide
+
+## What it does
+
+This guide maps every supported Prism customization seam to the existing public API. Use it when an embedding app wants to replace provider resolution, middleware, context, input/prompt builders, instruction injectors, agent loops, compaction, retry, session stores, or skill selection without forking the runtime.
+
+Prism customization is explicit wiring. There is no hidden global middleware, package auto-activation, provider discovery, tool grant, or background runtime.
+
+## When to use it
+
+Use this guide when the default agent/session runtime is close enough, but your host app needs one or more custom policies:
+
+- route models to providers dynamically
+- add middleware at documented runtime boundaries
+- resolve host context or selected skills
+- replace input/prompt assembly
+- add inert instruction injectors
+- choose a built-in or custom agent loop
+- configure compaction/retry strategies
+- use a durable session store
+
+Do not use customization hooks as a sandbox, permission system, credential manager, package loader, workflow engine, vector memory, or hidden tool activator. Host policy and activation stay outside the hook.
+
+## Inputs / request
+
+Most seams are fields on `AgentConfig` or per-run `RunOptions`. Per-run options win where both exist.
+
+| Customize | Entry point | Detailed page |
+| --- | --- | --- |
+| Provider resolution | `provider`, `providerSource`, `createProviderResolver()` | [Provider layer](provider-layer.md) |
+| Middleware | `middleware`, `createMiddlewareRegistry()` | [Middleware hooks](middleware-hooks.md) |
+| Context | `context`, `resolveContextProviders()` | [Context and skills](context-and-skills.md) |
+| Skills | `skills`, `activeSkills`, `createSkillRegistry()`, `resolveActiveSkills()` | [Context and skills](context-and-skills.md) |
+| Input builder | `inputBuilder`, `createDefaultInputBuilder()` | [Input and prompt assembly](input-and-prompt-assembly.md) |
+| Prompt builder | `promptBuilder`, `createDefaultPromptBuilder()` | [Input and prompt assembly](input-and-prompt-assembly.md) |
+| Instruction injectors | `instructionInjectors`, `resolveInstructionInjectors()` | [Instruction injection](instruction-injection.md) |
+| Agent loops | `loop`, `singleShotLoop`, `generateValidateReviseLoop()` | [Agent loops](agent-loops.md) |
+| Compaction | `compaction`, `createDefaultCompactionStrategy()` | [Compaction and retry](compaction-and-retry.md) |
+| Retry | `retry`, `createDefaultRetryPolicy()` | [Compaction and retry](compaction-and-retry.md) |
+| Session store | `store`, `SessionStore`, `createMemorySessionStore()` | [Session stores](session-stores.md) |
+
+## Outputs / response / events
+
+Customization changes what the existing runtime calls. It does not create new runtime phases.
+
+- provider resolution happens once per run before any provider turn
+- input/prompt builders run during provider-request assembly
+- context providers and skills are resolved only when passed to the agent/run
+- middleware runs only for documented hook call sites when a registry is supplied
+- instruction injectors contribute only instructions/context blocks during assembly
+- loops orchestrate shared runtime primitives and return usage
+- compaction/retry run only when configured and triggered
+- session stores receive redacted `SessionEntry` values when a redactor is active
+
+Events remain the normal `AgentEvent` stream for runs, tools, compaction, retry, and artifact validation.
+
+## Request/response example
+
+```json
+{
+  "agent": {
+    "providerSource": "host resolver",
+    "middleware": "host registry",
+    "inputBuilder": "custom input builder",
+    "promptBuilder": "custom prompt builder",
+    "context": ["project"],
+    "skills": ["brief"],
+    "instructionInjectors": ["json"],
+    "loop": "generate-validate-revise",
+    "compaction": "host strategy",
+    "retry": "host policy",
+    "store": "host session store"
+  }
+}
+```
+
+The JSON is a map of seams, not a Prism config format. Hosts wire concrete public API objects into `createAgent()` or `session.run()`.
+
+## Implementation example
+
+```ts
+import {
+  createAgent,
+  createDefaultCompactionStrategy,
+  createDefaultRetryPolicy,
+  createMemorySessionStore,
+  createMiddlewareRegistry,
+  createMockProvider,
+  createProviderResolver,
+  createProviderRegistry,
+  createSkillRegistry,
+  createToolRegistry,
+  generateValidateReviseLoop,
+  providerDone,
+  type ArtifactValidator,
+  type ContextProvider,
+  type InputBuilder,
+  type PromptBuilder,
+} from "@arnilo/prism";
+
+const provider = createMockProvider([providerDone()]);
+const providerSource = createProviderResolver(createProviderRegistry([provider]));
+const middleware = createMiddlewareRegistry();
+middleware.use("provider_request", (request, next) => next(request));
+
+const context: ContextProvider = {
+  name: "project",
+  resolve: () => [{ title: "Project", content: "Host-selected context." }],
+};
+
+const inputBuilder: InputBuilder = {
+  name: "custom-input",
+  build: async (input) => [{ role: "user", content: [{ type: "text", text: String(input) }] }],
+};
+
+const promptBuilder: PromptBuilder = {
+  name: "custom-prompt",
+  build: async (request) => request.messages,
+};
+
+const validator: ArtifactValidator<unknown> = (value) =>
+  typeof value === "string" && value.length > 0
+    ? { ok: true }
+    : { ok: false, errors: [{ message: "empty output" }] };
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  providerSource,
+  middleware,
+  context: [context],
+  skills: createSkillRegistry([{ name: "brief", instructions: "Be brief." }]),
+  tools: createToolRegistry([], { duplicate: "error" }),
+  inputBuilder,
+  promptBuilder,
+  instructionInjectors: [{ name: "json", apply: () => ({ when: "every_turn", instructions: "Use JSON." }) }],
+  loop: generateValidateReviseLoop({ validator }),
+  compaction: { strategy: createDefaultCompactionStrategy(), thresholdEntries: 40 },
+  retry: { policy: createDefaultRetryPolicy({ maxAttempts: 3 }) },
+  store: createMemorySessionStore(),
+});
+
+await agent.createSession().run("Hello", { activeSkills: ["brief"] });
+```
+
+### Per-run override examples
+
+```ts
+await session.run("Use a different provider just this run", { providerSource: otherResolver });
+await session.run("No auto compaction here", { compaction: false });
+await session.run("No retry here", { retry: false });
+await session.run("Use only this skill", { activeSkills: ["brief"] });
+await session.run("Use a different loop", { loop: { strategy: "single-shot" } });
+```
+
+## Extension and configuration notes
+
+- Direct `AgentConfig.provider` takes first precedence and bypasses `providerSource`. Without a direct provider, `RunOptions.providerSource` wins over `AgentConfig.providerSource`.
+- A custom `ProviderResolver` returns an `AIProvider | undefined`; `undefined` fails closed before the provider turn.
+- Middleware is not global. It runs only when the host passes a `MiddlewareRegistry` to `createAgent()`, `assembleProviderInput()`, `dispatchToolCall()`, compaction, or retry paths that document a hook.
+- Context providers are host-selected arrays. Extension-contributed providers remain inert until resolved from registries and passed into config.
+- Skills are selected by the host. `toolNames` only require active tools; they never register, allow, permit, or execute tools.
+- Input and prompt builders are replaceable objects. Default builders remain available when omitted.
+- Instruction injectors can add instructions and context blocks only. They grant no tools, skills, permissions, validators, credentials, resource access, or provider options.
+- Agent loops should use `LoopContext` primitives instead of reimplementing provider calls, retry, abort, store appends, redaction, or event emission.
+- Compaction and retry strategies are inert until selected on `AgentConfig` or `RunOptions`. `RunOptions.compaction: false` and `RunOptions.retry: false` disable configured defaults for one run.
+- Session stores are explicit. `AgentSessionConfig.store` wins over `AgentConfig.store`; otherwise the session uses a private in-memory store.
+- Extension packages can register builders, strategies, policies, providers, tools, context, skills, and injectors, but host code still chooses which contributions become active.
+
+## Security and performance notes
+
+- Customization cannot grant tools or permissions unless the host explicitly activates tools and permission policies at the tool-dispatch boundary.
+- Middleware, skills, context providers, prompt builders, and instruction injectors cannot bypass tool lookup, allow/deny filters, object-argument checks, permission checks, or `ToolValidator`.
+- Do not put credentials in models, prompts, context, skills, instruction injectors, middleware payloads, cache keys, session entries, ledgers, or examples.
+- Use `createSecretRedactor()` on agent/run config when custom components may handle known secret values.
+- Replaceable hooks are in-process calls on the active path. Prism adds no hidden global middleware, background workers, watchers, package scans, provider calls, resource loads, tool execution, or credential resolution unless the host wires that operation.
+- Custom providers, stores, tools, middleware, loops, and extensions are host code. Prism does not sandbox them.
+- Strict duplicate registries (`{ duplicate: "error" }`) prevent silent shadowing when loading third-party contributions.
+
+## Related APIs
+
+- [Provider layer](provider-layer.md): provider registries/resolvers and model routing.
+- [Middleware hooks](middleware-hooks.md): hook names and runtime call sites.
+- [Input and prompt assembly](input-and-prompt-assembly.md): default/custom builders, templates, context, and tools in provider requests.
+- [Instruction injection](instruction-injection.md): inert package instructions/context blocks.
+- [Agent loops](agent-loops.md): `singleShotLoop`, `generateValidateReviseLoop`, custom `AgentLoopStrategy`, and `LoopContext`.
+- [Compaction and retry](compaction-and-retry.md): compaction/retry options, strategies, middleware, and disabling per run.
+- [Context and skills](context-and-skills.md): ordered context providers, skill registries, active-skill selection, and `toolNames` fail-closed behavior.
+- [Session stores](session-stores.md): store selection, branch reads, and conformance.
+- [Tools](tools.md): active tool registry, filtering, permission, validation, and no sandbox.
+- [Extension authoring guide](extension-authoring.md): publishing inert contributions for hosts to select.
+- [Host security guide](host-security.md): fail-closed security checklist for embedding apps.