@arnilo/prism 0.0.1

package/docs/public-contracts.md

@@ -0,0 +1,375 @@
+# Public contracts
+
+## What it does
+
+The root `@arnilo/prism` export provides TypeScript contracts for host-owned agent systems plus small runtime helpers as phases land. These contracts describe data shapes and extension points; they do not create providers, stores, credentials, tools, or network calls by themselves.
+
+Current contract groups:
+
+- JSON/data: `JsonPrimitive`, `JsonValue`, `JsonObject`, `ErrorInfo`
+- Content/messages: `ContentBlock`, `TextContent`, `ImageContent`, `ThinkingContent`, `ToolCallContent`, `ToolResultContent`, `Message`
+- Providers/models/auth: `ModelConfig`, `ModelCapabilities`, `ModelLimits`, `ModelCost`, `Usage`, `CacheRetention`, `ProviderRequestOptions`, `ProviderRequest`, `ProviderEvent`, `AIProvider`, `ProviderPackage`, `ProviderPackageAPI`, `ProviderPackageDocs`, `AuthMethod`, `ApiKeyAuthMethod`, `OAuthAuthMethod`, `CustomAuthMethod`, `OAuthLoginCallbacks`, `OAuthCredentials`, `OAuthProvider`, `CredentialResolverSource`, `OAuthCredentialStore`, `ProviderRequestPolicy`, `ProviderRequestPolicyContext`, `ProviderRequestPolicyResult`, `SystemPromptContribution`, `SystemPromptMode`, `SystemPromptSource`, `SystemPromptConfig`
+- Agents/sessions: `AgentConfig`, `AgentDefinition`, `Agent`, `AgentSessionConfig`, `AgentSessionForkOptions`, `AgentSessionCloneOptions`, `AgentSession`, `RunOptions`, `AgentEvent`
+- Tools/commands: `ToolDefinition`, `ToolRegistry`, `ToolExecutionContext`, `ToolResult`, `CommandDefinition`, `CommandExecutionContext`, `CommandResult`
+- Input/prompt/context/skills: `InputBuilder`, `InputBuildContext`, `AgentInput`, `DefaultInputBuilder`, `DefaultInputBuildContext`, `InputAttachment`, `PromptInstruction`, `PromptBuilder`, `PromptBuildRequest`, `ContextBlock`, `ContextProvider`, `ContextResolutionContext`, `Skill`, `SkillRegistry`
+- Extensions/middleware: `ExtensionLifecycleEventName`, `ExtensionEvent`, `Extension`, `ExtensionAPI`, `MiddlewareHookName`, `Middleware`, `MiddlewareNext`, `MiddlewareRegistry`
+- Configuration/manifests: `ConfigProvider`, `ConfigLayer`, `ConfigLoadContext`, `PrismManifest`, `ManifestContributionDeclaration`, `ManifestResourceDeclaration`, `ManifestContributionKind`
+- Stores/resources/settings/credentials/compaction/retry: `SessionEntry`, `SessionStore`, `StoreFactory`, `Resource`, `ResourceLoader`, `ResourceLoadContext`, `SettingsProvider`, `CredentialRequest`, `Credential`, `CredentialResolver`, `CompactionStrategy`, `CompactionContext`, `CompactionResult`, `CompactionOptions`, `CompactionMiddlewarePayload`, `CompactionEntryData`, `DefaultCompactionStrategyOptions`, `RetryPolicy`, `RetryContext`, `RetryDecision`, `RetryOptions`, `RetryMiddlewarePayload`, `DefaultRetryPolicyOptions`
+
+## When to use it
+
+Use these contracts when a host app or external package needs to type Prism-compatible providers, tools, context providers, skills, extensions, sessions, stores, resources, settings, or credential resolvers.
+
+Do not use a contract as proof that every behavior exists. The agent/session runtime, tool loops, persistence adapters, config helpers, compaction helpers, and retry helpers now exist; CLI/RPC is implemented in later phases.
+
+## Inputs / request
+
+Public contracts are imported from the root package:
+
+```ts
+import type {
+  AgentConfig,
+  AgentDefinition,
+  AIProvider,
+  AuthMethod,
+  CommandDefinition,
+  CompactionStrategy,
+  ConfigLayer,
+  ConfigProvider,
+  ContextProvider,
+  CredentialResolver,
+  OAuthProvider,
+  ProviderRequestOptions,
+  DefaultInputBuildContext,
+  Extension,
+  InputBuilder,
+  ManifestContributionDeclaration,
+  ManifestResourceDeclaration,
+  Message,
+  Middleware,
+  ModelConfig,
+  PrismManifest,
+  PromptBuilder,
+  PromptTemplateOptions,
+  ProviderPackage,
+  ProviderRequestPolicy,
+  ResourceLoader,
+  SettingsProvider,
+  Skill,
+  StoreFactory,
+  SystemPromptContribution,
+  SystemPromptConfig,
+  ToolDefinition,
+} from "@arnilo/prism";
+```
+
+Important request shapes:
+
+| Contract | Purpose |
+| --- | --- |
+| `ModelConfig` | Provider/model id plus optional display name, capabilities, limits, cost/cache pricing, opaque compat JSON, parameters, and metadata. |
+| `ProviderPackage` | Inert provider package definition with docs metadata and explicit `setup(api)` registration. |
+| `ProviderRequest` | Normalized provider input: `model`, `messages`, optional `tools`, `context`, generic `options`, `metadata`, and `signal`. |
+| `ProviderRequestOptions` | Generic provider adapter hints: session/cache identifiers, cache retention, headers, timeout/retry hints, compat, and opaque `extra`. |
+| `ProviderRequestPolicy` | Ordered pre-provider hook that can patch the request and return exact secrets for provider-error redaction. |
+| `ToolRegistry` | Host active tool registry shape: `register()`, `get()`, `resolve()`, and `list()`. |
+| `ToolExecutionContext` | Host tool execution context: session/run ids, tool call id, optional abort signal, metadata, and progress callback. |
+| `ContextResolutionContext` | Context provider input: messages plus optional session/run ids, metadata, and signal. |
+| `DefaultInputBuildContext` | Optional default input assembly context: instructions, history, summaries, attachments, explicit resources, tool results, middleware, ids, metadata, and signal. |
+| `ResolveContextOptions` | Ordered context resolution input: selected providers, messages, ids, metadata, signal, and optional middleware. |
+| `AssembleProviderInputOptions` | Provider input assembly input: model, input, optional builders, selected context providers/skills, active tools, metadata, and signal. |
+| `PromptTemplateOptions` | Missing-variable behavior for tiny `renderPromptTemplate()` substitutions. |
+| `SkillRegistry` | Host active skill registry shape: `register()`, `get()`, `resolve()`, and `list()`. |
+| `CredentialRequest` | Credential lookup request: credential `name`, optional provider id, and metadata. |
+| `OAuthProvider` | Host/package OAuth callbacks for login, optional refresh, and conversion to a `Credential`. |
+| `AgentSessionConfig` | Session creation input: optional id, agent, store, leaf id, and metadata. |
+| `RunOptions` | Per-run overrides: optional abort signal, model, max tool rounds, provider options/request policies, system prompt layers, compaction, retry, and metadata. |
+| `SystemPromptContribution` | Explicit caller-selected prompt layer with source, mode, text, and metadata. |
+| `ConfigLayer` | Named JSON config layer consumed by `mergeConfigLayers()`. |
+| `PrismManifest` | Data-only package manifest with config defaults, contribution declarations, and resource declarations. |
+
+## Outputs / response / events
+
+Important output/event shapes:
+
+| Contract | Output |
+| --- | --- |
+| `ProviderEvent` | Provider stream events: message start, content delta, tool-call delta, final tool call, usage, done, or error. |
+| `AgentEvent` | Session/runtime events: agent/turn/message/tool/queue/compaction/retry/error events, including tool started/progress/finished/error/blocked. |
+| `ToolResult` | Host tool output with optional content, value, error, and metadata. |
+| `ContextBlock` | Context text or content blocks with optional title, priority, and metadata. |
+| `SessionEntry` | Branch-aware store entry for messages, events, summaries, metadata, model changes, labels, custom data, or compaction markers. |
+| `Resource` | Loaded resource with URI, media type, text, binary data, and metadata. |
+| `Credential` | Host-resolved credential value returned only to the caller that requested it. |
+
+## Request/response example
+
+```json
+{
+  "model": { "provider": "mock", "model": "demo" },
+  "messages": [
+    {
+      "role": "user",
+      "content": [{ "type": "text", "text": "Hello" }]
+    }
+  ]
+}
+```
+
+Example provider event:
+
+```json
+{
+  "type": "content_delta",
+  "content": { "type": "text", "text": "Hello" }
+}
+```
+
+## Implementation example
+
+```ts
+import type {
+  AgentConfig,
+  AgentDefinition,
+  AIProvider,
+  AssembleProviderInputOptions,
+  CommandDefinition,
+  CompactionStrategy,
+  ConfigLayer,
+  ConfigProvider,
+  ContextProvider,
+  CredentialResolver,
+  DefaultInputBuildContext,
+  Extension,
+  InputBuilder,
+  ManifestContributionDeclaration,
+  ManifestResourceDeclaration,
+  Middleware,
+  PrismManifest,
+  PromptBuilder,
+  PromptTemplateOptions,
+  ResourceLoader,
+  SettingsProvider,
+  Skill,
+  StoreFactory,
+  ToolDefinition,
+} from "@arnilo/prism";
+import { assembleProviderInput, createDefaultInputBuilder, createDefaultPromptBuilder, createSkillRegistry, renderPromptTemplate, resolveActiveSkills, resolveContextProviders } from "@arnilo/prism";
+
+const provider: AIProvider = {
+  id: "mock",
+  async *generate() {
+    yield { type: "done" };
+  },
+};
+
+const context: ContextProvider = {
+  name: "demo-context",
+  resolve() {
+    return [{ title: "Demo", content: "Public contract example." }];
+  },
+};
+
+const tool: ToolDefinition = {
+  name: "echo",
+  parameters: { type: "object" },
+  execute(_args, ctx) {
+    return { toolCallId: ctx.toolCallId, name: "echo", value: "ok" };
+  },
+};
+
+const skill: Skill = {
+  name: "brief",
+  instructions: "Answer briefly.",
+  toolNames: ["echo"],
+};
+
+const command: CommandDefinition = {
+  name: "say",
+  execute() {
+    return { name: "say", value: "ok" };
+  },
+};
+
+const inputBuilder: InputBuilder = {
+  name: "plain-text",
+  build(input) {
+    return typeof input === "string" ? [{ role: "user", content: [{ type: "text", text: input }] }] : [];
+  },
+};
+
+const defaultInputContext: DefaultInputBuildContext = {
+  systemInstructions: "Follow host policy.",
+  attachments: [{ name: "notes.md", text: "notes" }],
+  toolResults: [{ toolCallId: "call_1", name: "echo", value: "ok" }],
+};
+
+const templateOptions: PromptTemplateOptions = { missing: "throw" };
+const renderedPrompt = renderPromptTemplate("Hello {{name}}", { name: "world" }, templateOptions);
+const defaultMessages = await createDefaultInputBuilder().build(renderedPrompt, defaultInputContext);
+
+const assemblyOptions: AssembleProviderInputOptions = {
+  model: { provider: "mock", model: "demo-model" },
+  input: "Hello",
+  contextProviders: [context],
+  promptBuilder: createDefaultPromptBuilder(),
+  tools: [tool],
+  skills: [skill],
+};
+
+const skillRegistry = createSkillRegistry([skill]);
+const activeSkills = resolveActiveSkills({ registry: skillRegistry, names: ["brief"], tools: [tool] });
+const resolvedContext = await resolveContextProviders({ providers: [context], messages: defaultMessages });
+const providerInput = await assembleProviderInput({ ...assemblyOptions, skills: activeSkills });
+
+const promptBuilder: PromptBuilder = {
+  name: "default-prompt",
+  build(request) {
+    return request.messages;
+  },
+};
+
+const providerRequestMiddleware: Middleware<{ metadata?: Record<string, unknown> }> = (request) => ({
+  ...request,
+  metadata: { ...request.metadata, source: "demo" },
+});
+
+const compaction: CompactionStrategy = {
+  name: "simple-summary",
+  compact() {
+    return { summary: "Summary placeholder." };
+  },
+};
+
+const configLayer: ConfigLayer = { name: "runtime", config: { demo: { enabled: true } } };
+const configProvider: ConfigProvider = { name: "host", load: () => configLayer.config };
+const manifestContribution: ManifestContributionDeclaration = {
+  kind: "tool",
+  name: "demo.echo",
+  module: "./tool.js",
+};
+const manifestResource: ManifestResourceDeclaration = {
+  uri: "package://demo/prompt.md",
+  purpose: "prompt",
+};
+const manifest: PrismManifest = {
+  name: "demo-package",
+  configDefaults: configLayer.config,
+  contributions: [manifestContribution],
+  resources: [manifestResource],
+};
+
+const agentDefinition: AgentDefinition = {
+  name: "demo-agent",
+  create() {
+    throw new Error("Agent runtime is implemented in a later phase.");
+  },
+};
+
+const config: AgentConfig = {
+  id: "demo-agent",
+  model: { provider: "mock", model: "demo-model" },
+  provider,
+  context: [context],
+  skills: [skill],
+  tools: [tool],
+  compaction: { strategy: compaction, thresholdEntries: 40, keepRecentEntries: 8 },
+  retry: { maxAttempts: 3, baseDelayMs: 50 },
+};
+
+const extension: Extension = {
+  name: "demo-extension",
+  setup(api) {
+    api.registerProvider(provider);
+    api.registerContextProvider(context);
+    api.registerSkill(skill);
+    api.registerTool(tool);
+  },
+};
+
+const resources: ResourceLoader = {
+  async load(uri) {
+    return { uri, mediaType: "text/plain", text: "example" };
+  },
+};
+
+const storeFactory: StoreFactory = {
+  name: "memory",
+  create() {
+    return { append: async () => undefined, list: async () => [] };
+  },
+};
+
+const settings: SettingsProvider = {
+  get<T>(key: string) {
+    return key === "demo.enabled" ? (true as T) : undefined;
+  },
+};
+
+const credentials: CredentialResolver = {
+  resolve() {
+    return undefined;
+  },
+};
+
+void config;
+void command;
+void inputBuilder;
+void renderedPrompt;
+void defaultMessages;
+void activeSkills;
+void resolvedContext;
+void providerInput;
+void promptBuilder;
+void compaction;
+void configProvider;
+void manifest;
+void providerRequestMiddleware;
+void agentDefinition;
+void extension;
+void resources;
+void storeFactory;
+void settings;
+void credentials;
+```
+
+## Extension and configuration notes
+
+- Contracts are host-owned and package-friendly. External packages can implement `AIProvider`, `ToolDefinition`, `CommandDefinition`, `AgentDefinition`, `InputBuilder`, `PromptBuilder`, `Middleware`, `ContextProvider`, `Skill`, `Extension`, config providers, data-only manifests, compaction strategies, store factories, resource loaders, settings providers, and credential resolvers.
+- `ExtensionAPI` is implemented by the extension kernel. It exposes explicit registries, ordered middleware registration, ordered event subscription/emission, and registration methods for Phase 2 contribution categories.
+- `AgentConfig.provider` can hold a direct provider instance for simple host wiring. Hosts that need config-driven selection should use `ModelConfig.provider` with explicit `createProviderRegistry()` / `createModelRegistry()` objects; Prism does not create a hidden global provider registry.
+- `SettingsProvider` and `CredentialResolver` are explicit dependencies. Prism must not hide global settings or credentials behind these contracts, and `CredentialResolver` should be passed only to the edge that needs a credential.
+- `PrismManifest` is data-only. It can describe contribution modules/resources and config defaults, but parsing it does not import modules, execute package code, or mutate registries.
+- Resource helper functions decode resources from a caller-provided `ResourceLoader`; Prism does not include filesystem, network, package, or URI router loaders.
+- `createDefaultInputBuilder()` is a small default implementation of `InputBuilder`. It is replaceable and only loads explicit URI resources through a caller-provided `ResourceLoader`.
+- `resolveContextProviders()`, `createDefaultPromptBuilder()`, `assembleProviderInput()`, `createSkillRegistry()`, `resolveActiveSkills()`, and `renderPromptTemplate()` are replaceable Phase 5 helpers. They do not execute tools, evaluate template code, or grant tool permissions.
+- `createAgent()` and `createAgentSession()` implement the session runtime. They use explicit providers only; no hidden provider registry is created. Store-backed sessions use explicit `SessionStore` values and branch methods on `AgentSession`. `AgentSession.compact()` and `AgentConfig`/`RunOptions.compaction` provide manual and opt-in auto-compaction. `AgentConfig`/`RunOptions.retry` provide bounded provider-turn retry before observable output.
+- `createMemorySessionStore()` is the built-in in-memory `SessionStore`. Node hosts can opt into file durability with `@arnilo/prism/node/session-store-jsonl`. `createSessionEntry()`, `getSessionBranchEntries()`, `listSessionBranches()`, and `rebuildSessionContext()` are pure helpers for branch-aware session entries. `rebuildSessionContext()` understands compaction entries produced by `createDefaultCompactionStrategy()`, reducing provider-context messages while keeping raw entries. They do not read files or call providers.
+
+## Security and performance notes
+
+- Type-only imports have no runtime side effects.
+- Contracts do not create clients, stores, registries, background work, config discovery, package imports, or network calls.
+- Host apps own credentials. Do not put secrets in messages, prompts, provider events, agent events, session entries, tool results, logs, or docs examples. Pass known secret strings to compaction options when summaries may include sensitive text.
+- Use `unknown`/metadata fields for host data, but validate at trust boundaries before executing tools or loading resources.
+- App-specific tool categories and business domains do not belong in public contracts.
+
+## Related APIs
+
+- [Input and prompt assembly](input-and-prompt-assembly.md): prompt template expansion and default input builder for strings, messages, history, attachments, resources, summaries, and tool results.
+- [Context and skills](context-and-skills.md): ordered context resolution, skill registry, and progressive disclosure.
+- [Configuration and manifests](configuration-and-manifests.md): in-memory config merge helpers and data-only package manifest validation.
+- [Resource loading](resource-loading.md): text, JSON, and manifest helpers over caller-provided resource loaders.
+- [Extension kernel and event bus](extensions.md): runtime implementation of `ExtensionAPI`, ordered events, and extension error isolation.
+- [Middleware hooks](middleware-hooks.md): ordered hook registry for runtime boundaries.
+- [Contribution registries](contribution-registries.md): explicit registries for contribution contracts.
+- [Tools](tools.md): active tool registry and exact allow/deny filtering built on `ToolDefinition`.
+- [Agent/session runtime](agent-session-runtime.md): `createAgent()` / `createAgentSession()` runtime, `AgentSession.compact()`, and auto-compaction config built on these contracts.
+- [Session stores and branching](session-stores-and-branching.md): branch-aware `SessionEntry` helpers and context rebuild.
+- [Compaction and retry policies](compaction-and-retry.md): default compaction strategy, default retry policy, runtime compaction/retry options, middleware payloads, and compaction entry data.
+- [Provider layer](provider-layer.md): runtime registries, provider event helpers, and mock provider built on these contracts.
+- [Provider conformance](provider-conformance.md): testing subpath for network-free provider adapter checks.
+- [Credentials and redaction](credentials-and-redaction.md): helpers for resolving host-owned credentials, explicit resolver order, OAuth refresh, env-object lookup, and redacting known secret values.
+- [OpenAI-compatible provider](providers/openai-compatible.md): optional provider adapter implementing `AIProvider`.
+
+Phase 10 public helpers include `createStaticSettingsProvider`, `createChainedSettingsProvider`, `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createStaticTrustPolicy`, `assertTrusted`, `createStaticPermissionPolicy`, `assertPermission`, and `createSecretRedactor`. Phase 11 auth/request/prompt helpers include `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `createProviderRequestPolicyChain`, `createSessionCachePolicy`, `mergeProviderRequestOptions`, `composeSystemPrompt`, and `mergeSystemPromptConfig`; they do not read env vars, persist OAuth tokens, create cache stores, discover prompt files, or load packages unless the host supplies that behavior. `@arnilo/prism/testing/provider-conformance` exports network-free provider assertion helpers. Node subpaths `@arnilo/prism/node/settings` and `@arnilo/prism/node/trust` are explicit filesystem/path helpers.

package/docs/release-and-install.md

@@ -0,0 +1,141 @@
+# Release and install
+
+## What it does
+
+Prism is published as one core package plus seven first-party workspace packages and three umbrella convenience packages. This page describes how they are packed, what each tarball contains, how to install them, the required `@arnilo/prism` peer dependency, the release workflow, and the offline test budget.
+
+Core package:
+
+- `@arnilo/prism` — the runtime, contracts, registries, streaming events, CLI, and the `/docs` hub. `files`: `dist` (with `!dist/__tests__` and `!dist/**/*.map` negations), `docs`, `CHANGELOG.md`. `bin`: `prism` -> `./dist/cli.js`. `sideEffects`: `["dist/cli.js"]`.
+
+First-party workspace packages (each `peerDependencies: { "@arnilo/prism": "0.0.1" }`, non-optional; `sideEffects: false`):
+
+- `@arnilo/prism-provider-openai`, `@arnilo/prism-provider-openrouter`, `@arnilo/prism-provider-kimi`, `@arnilo/prism-provider-zai`, `@arnilo/prism-provider-opencode-go` — provider adapters.
+- `@arnilo/prism-compaction-llm` — optional LLM-backed compaction strategy.
+- `@arnilo/prism-compaction-observational-memory` — optional source-backed observational memory.
+
+Umbrella packages (pure manifests, no code, no `dist`; ship only `README.md`; use hard `dependencies` to transitively install their family):
+
+- `@arnilo/prism-providers` — depends on all 5 `@arnilo/prism-provider-*` packages.
+- `@arnilo/prism-compaction` — depends on both `@arnilo/prism-compaction-*` packages.
+- `@arnilo/prism-all` — depends on `@arnilo/prism` + `@arnilo/prism-providers` + `@arnilo/prism-compaction` (the full kit in one install).
+
+Each code package's `files` array is `["dist", "!dist/__tests__", "!dist/**/*.map", "README.md", "CHANGELOG.md"]`; `README.md`, `LICENSE`, and `CHANGELOG.md` ship in every code-package tarball, the core tarball also ships the `docs/` directory, and umbrella tarballs ship only `README.md` + `package.json`.
+
+## When to use it
+
+Use this page when installing Prism into a host app, when adding a first-party package, when cutting a release, or when investigating why a tarball contains (or excludes) a file.
+
+Consumers install the core package for the runtime and add first-party packages for provider adapters or compaction strategies. Each first-party package requires the `@arnilo/prism` peer at its declared version; install `@arnilo/prism` alongside them or npm will report an unmet peer.
+
+## Inputs / request
+
+| Operation | Command |
+| --- | --- |
+| Install core only | `npm install @arnilo/prism` |
+| Install core + all providers | `npm install @arnilo/prism @arnilo/prism-providers` |
+| Install core + compaction | `npm install @arnilo/prism @arnilo/prism-compaction` |
+| Install everything (core + providers + compaction) | `npm install @arnilo/prism-all` |
+| Install core + a single provider | `npm install @arnilo/prism @arnilo/prism-provider-openai` |
+| Build everything (core + workspaces) | `npm run build` |
+| Run the default (network-free) test suite | `npm test` |
+| Dry-run pack core + every package | `npm run pack:dry-run` |
+| Local mirror of the release verify gate | `npm run release:dry-run` |
+
+Public core import specifiers (from the root `exports` map):
+
+| Specifier | Resolves to |
+| --- | --- |
+| `@arnilo/prism` | `dist/index.js` / `dist/index.d.ts` |
+| `@arnilo/prism/providers/openai-compatible` | `dist/providers/openai-compatible.{js,d.ts}` |
+| `@arnilo/prism/testing/provider-conformance` | `dist/testing/provider-conformance.{js,d.ts}` |
+| `@arnilo/prism/node/config` | `dist/node/config.{js,d.ts}` |
+| `@arnilo/prism/node/settings` | `dist/node/settings.{js,d.ts}` |
+| `@arnilo/prism/node/trust` | `dist/node/trust.{js,d.ts}` |
+| `@arnilo/prism/node/session-store-jsonl` | `dist/node/session-store-jsonl.{js,d.ts}` |
+
+## Outputs / response / events
+
+A packed tarball contains only public compiled output and release files:
+
+- `dist/**` compiled `.js` and `.d.ts` for every exported subpath.
+- `README.md`, `LICENSE`, `CHANGELOG.md` in every package.
+- The core tarball additionally ships the full `docs/` directory (the docs hub).
+- `dist/cli.js` and the `bin` link in core.
+- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.0.1.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.0.1.tgz` / `arnilo-prism-compaction-<name>-0.0.1.tgz`; umbrella packages produce `arnilo-prism-providers-0.0.1.tgz` / `arnilo-prism-compaction-0.0.1.tgz` / `arnilo-prism-all-0.0.1.tgz`. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
+
+Excluded from every tarball by `files` negation:
+
+- `dist/__tests__/` — compiled tests and the meta-tests (`packaging.test.js`, `install-smoke.test.js`, `docs.test.js`, `network-free-guard.test.js`, and the phase boundary tests).
+- `dist/**/*.map` — source maps. Source maps are still emitted locally (`tsconfig` `sourceMap: true`) for debugging; the `!dist/**/*.map` line is the **map-retention knob**: remove that negation to ship source maps in releases.
+- `src/`, `plans/`, `.agents/`, `.github/`, `tsconfig*.json`, `roadmap.md`, and `package-lock.json` are never packed (outside the `files` whitelist and/or explicitly ignored).
+
+`sideEffects` is `false` for every first-party package (their entrypoints export only types and declarations). Core sets `sideEffects: ["dist/cli.js"]` because `src/cli.ts` runs the CLI and sets `process.exitCode` at import time; every other core entrypoint is side-effect-free.
+
+## Request/response example
+
+```json
+{
+  "name": "host-app",
+  "type": "module",
+  "dependencies": {
+    "@arnilo/prism": "0.0.1",
+    "@arnilo/prism-provider-openai": "0.0.1",
+    "@arnilo/prism-compaction-observational-memory": "0.0.1"
+  }
+}
+```
+
+Installing the provider/compaction packages without `@arnilo/prism` present produces an unmet-peer error (the `@arnilo/prism` peer is required, not optional):
+
+```text
+npm error code ERESOLVE
+npm error Could not resolve dependency:
+npm error peer @arnilo/prism@"0.0.1" from @arnilo/prism-provider-openai@0.0.1
+```
+
+## Implementation example
+
+```ts
+// Core runtime
+import { createAgent, createAgentSession } from "@arnilo/prism";
+// OpenAI-compatible provider subpath
+import { createOpenAICompatibleProvider } from "@arnilo/prism/providers/openai-compatible";
+// Node filesystem config loader
+import { loadConfigFile } from "@arnilo/prism/node/config";
+
+const agent = createAgent({ provider: createOpenAICompatibleProvider({ /* ... */ }) });
+const session = createAgentSession(agent, { /* session store, etc. */ });
+```
+
+Local release dry-run mirrors the GitHub Actions `verify` job (build + tests + packaging/install-smoke guards + pack dry-run):
+
+```bash
+npm run release:dry-run
+```
+
+## Extension and configuration notes
+
+- **Required `@arnilo/prism` peer.** Every first-party package declares `peerDependencies: { "@arnilo/prism": "0.0.1" }` with no `peerDependenciesMeta` (non-optional). The range stays pinned to `0.0.1` for the 0.x series and will widen to `^1.0.0` at the 1.x stable release. Inside the workspace each package also declares `"@arnilo/prism": "file:../.."` in `devDependencies` so `npm install` resolves the peer locally; that devDependency is stripped from consumer installs and is not a runtime dependency.
+- **Public access.** All 11 manifests (8 code packages + 3 umbrellas) declare `"publishConfig": { "access": "public" }` so a manual `npm publish` of a scoped `@arnilo/prism-*` package defaults to public rather than `restricted` (paid). The `release.yml` flags (`npm publish --access public` + `npm publish --workspaces --access public`) are belt-and-suspenders backups.
+- **Map retention knob.** Source maps are emitted locally but stripped from tarballs by `!dist/**/*.map`. Removing that `files` negation ships maps in releases (larger tarballs, better consumer stack traces).
+- **Release workflow.** `.github/workflows/release.yml` has two jobs. `verify` runs on push (main/master, `v*` tags) and pull requests: `npm ci`, `npm test` (builds core + workspaces first, then runs the packaging and install-smoke guards), and `npm run pack:dry-run`. `publish` runs only on `refs/tags/v*` after `verify` succeeds: `npm run build`, then `npm publish --access public` for core (first, because packages require the `@arnilo/prism` peer on the registry) and `npm publish --workspaces --access public`. With no `NPM_TOKEN` secret it runs `--dry-run` instead of a real publish. `permissions.id-token: write` is set so `--provenance` can be added later without re-architecting permissions.
+- **Adding a package.** New workspace packages are picked up automatically by `npm run build --workspaces`, `npm test --workspaces`, `npm run pack:dry-run`, the packaging guard (`src/__tests__/packaging.test.ts`), and the install-smoke test (`src/__tests__/install-smoke.test.ts`) via the workspace glob; add the package to both tests' config arrays for explicit per-package assertions.
+
+## Security and performance notes
+
+- **No secrets or fixtures in tarballs.** Tests, fixtures, `src/`, `plans/`, `.agents/`, `roadmap.md`, and `tsconfig` files are excluded. The `docs avoid real-looking secret examples` docs check and the packaging guard's deny list prevent secret-bearing fixtures from shipping.
+- **Live tests stay opt-in.** The default `npm test` is network-free by construction and never sets these vars. Three opt-in gate vars exist, each gating a different set of placeholder live smoke tests; none is set by default, in CI, or during release verification. Every gated live test is currently an empty placeholder awaiting provider-specific/worker checks in a later phase.
+  - `PRISM_LIVE_PROVIDER_TESTS=1` — gates the five provider packages' `src/__tests__/live.test.ts` (`@arnilo/prism-provider-openai`, `provider-opencode-go`, `provider-openrouter`, `provider-zai`, `provider-kimi`).
+  - `PRISM_LIVE_COMPACTION_TESTS=1` — gates `@arnilo/prism-compaction-llm`'s live summary-provider smoke test.
+  - `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS=1` — gates `@arnilo/prism-compaction-observational-memory`'s live worker/provider checks.
+  - These guards use fake-safe names and carry no real credentials; the gated bodies intentionally do not read `OPENAI_API_KEY` or any provider key — they are placeholders. Itemize any provider-specific key env here only when a future phase adds a real live check that reads it.
+  - Enforced by `network-free-guard.test.ts` (default suite stays network-free) and by source-scanning meta-tests that assert each `live.test.ts` keeps its `skip:` guard.
+- **Install smoke is offline.** The install-smoke test packs core + every package into a temp dir and installs the tarballs with `--offline --no-audit --no-fund` into a fresh temp project; zero registry fetches happen because Prism has no runtime dependencies.
+- **Offline test budget.** The default `npm test` (no `PRISM_LIVE_PROVIDER_TESTS`) is pinned at **< 30s on Node 20** with a measured baseline of ~22s (build ~12.5s + tests ~9.5s, tests parallelized). The `npm test` CI step has `timeout-minutes: 3` as a hang backstop. If a future change pushes the CI median over 30s, raise it here and in `roadmap.md` Phase 17 with rationale rather than silently regressing.
+
+## Related APIs
+
+- [`docs/provider-packages.md`](provider-packages.md): first-party provider package layout and setup.
+- [`docs/cli-rpc.md`](cli-rpc.md): the `prism` CLI bin and RPC protocol shipped as `dist/cli.js`.
+- [`docs/configuration-and-manifests.md`](configuration-and-manifests.md): package manifest merging and validation.

package/docs/resource-loading.md

@@ -0,0 +1,97 @@
+# Resource loading
+
+## What it does
+
+Resource helpers decode text, JSON objects, and Prism manifests through a caller-provided `ResourceLoader`.
+
+APIs:
+
+- `loadTextResource()`
+- `loadJsonResource()`
+- `loadManifestResource()`
+- `ResourceLoader`, `Resource`, `ResourceLoadContext`
+
+## When to use it
+
+Use these helpers when a host already has a resource loader and wants small decoding helpers for prompts, skills, manifests, or package resources.
+
+Do not use them for filesystem access, network access, package discovery, URI routing, caching, trust policy, dynamic imports, or agent/session runtime startup. The host-provided loader owns all I/O and trust decisions.
+
+## Inputs / request
+
+```ts
+loadTextResource(loader, uri, context?)
+loadJsonResource(loader, uri, context?)
+loadManifestResource(loader, uri, context?)
+```
+
+Inputs:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `loader` | `ResourceLoader` | Host-owned loader called once for the requested URI. |
+| `uri` | `string` | Resource identifier chosen by the host/package. |
+| `context` | `ResourceLoadContext` | Optional abort signal and metadata forwarded to the loader. |
+
+## Outputs / response / events
+
+- `loadTextResource()` returns `resource.text` or decodes `resource.data` with `TextDecoder`.
+- `loadJsonResource()` parses text as JSON and returns a JSON object.
+- `loadManifestResource()` parses a JSON object and validates it with `parsePrismManifest()`.
+- No events are emitted and no registries are modified.
+
+## Request/response example
+
+```json
+{
+  "uri": "package://demo/prism.manifest.json",
+  "resource": {
+    "mediaType": "application/json",
+    "text": "{\"name\":\"demo-package\"}"
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { loadManifestResource, loadTextResource, type ResourceLoader } from "@arnilo/prism";
+
+const loader: ResourceLoader = {
+  async load(uri, context) {
+    context?.signal?.throwIfAborted();
+    if (uri.endsWith("prism.manifest.json")) {
+      return { uri, mediaType: "application/json", text: '{"name":"demo-package"}' };
+    }
+    return { uri, mediaType: "text/markdown", text: "Prompt text" };
+  },
+};
+
+const manifest = await loadManifestResource(loader, "package://demo/prism.manifest.json");
+const prompt = await loadTextResource(loader, "package://demo/prompt.md");
+
+console.log(manifest.name, prompt);
+```
+
+## Extension and configuration notes
+
+- Manifest `resources` entries can reference prompts, skills, manifests, and package resources by URI.
+- Helpers do not choose a loader by URI scheme. Hosts can use contribution registries or their own routing when they need that.
+- Helpers do not execute loaded text or imported modules. Package activation remains a host decision.
+- `loadManifestResource()` only validates manifest data; it does not register manifest contributions.
+
+## Security and performance notes
+
+- The caller-provided loader owns URI trust, permissions, filesystem/network access, and credential boundaries.
+- Node hosts can use `@arnilo/prism/node/trust` (`createPathTrustPolicy`) to guard filesystem paths. It resolves symlinks on the trusted root and target and rejects paths whose realpath escapes the root; missing roots or realpath errors fail closed.
+- Helpers call `loader.load()` once per helper call and do not cache, scan, list, watch, poll, or discover packages.
+- JSON parsing fails closed for invalid JSON or non-object JSON.
+- Do not put resolved credential values, tokens, headers, or executable code in loaded config, manifests, prompts, skills, or metadata.
+
+## Related APIs
+
+- [Configuration and manifests](configuration-and-manifests.md): data-only manifests and manifest resource declarations.
+- [Contribution registries](contribution-registries.md): host-owned registries can store resource loaders.
+- [Public contracts](public-contracts.md): base `ResourceLoader`, `Resource`, and `ResourceLoadContext` contracts.
+
+`ResourceLoadContext.permission` checks `resource:<uri>:load` before calling the loader. Prism still does no resource discovery, package discovery, or trust prompts; hosts own those decisions. See [Security/auth/trust](settings-auth-trust-security.md).