prism

prism is a TypeScript agent harness for the Bun runtime. Host apps and extension packages bring their tools, providers, credentials, storage, and UI; Prism supplies the common contracts, registries, agent/session runtime, replaceable input/prompt and compaction strategies, CLI/RPC adapters, and first-party provider/compaction packages. The current 0.12.1 line publishes the manifest-derived package inventory (see Packages); family subpaths are imports, not packages to install. Prism defines contracts, not apps.

Current scope

• Agent/session runtime: createAgent/createAgentSession, run prompts, dispatch host tools, subscribe to normalized AgentEvent streams, abort runs, compact, and navigate branches.
• Field-level classification: applyFieldPolicy + the fail-closed protected default walk JSON-like values across prompt/tool/artifact/audit/telemetry/persistence/export boundaries with allow/redact/tokenize/deny decisions, explicit per-boundary labelFor hints, bounded traversal, and sparse-copy allocation; seams at the egress redaction functions, the audit-export redactor hook, and the OpenTelemetry attribute policy. See docs/data-classification.md.
• Providers and models: provider/model registries, provider event helpers, credential redaction helpers, mock provider, and an optional OpenAI-compatible provider subpath. Cache support is provider-specific: OpenAI/OpenRouter use best-effort explicit cache hints, NeuralWatt uses best-effort implicit prefix caching, and other providers have route/model-specific or no cache-control support; see docs/provider-caching.md.
• First-party packages: 22 provider adapter subpaths, two compaction strategies, coding tools/security, JSON Schema validation, MCP, workflows, OpenTelemetry, encrypted credentials, SQLite/PostgreSQL persistence, and Linux desktop control.
• Tools, context, skills: host-owned tool registry with allow/deny filtering and dispatch, context providers, and a skill registry with progressive disclosure.
• Input/prompt/context: default input and prompt builders, system-prompt layering, and provider-input assembly — every stage replaceable.
• Sessions and memory: in-memory and JSONL session stores, branching/fork/ clone, default and LLM compaction strategies, retry policy, observational-memory recall/status/view, and the @arnilo/prism-memory family (working/semantic memory plus /rag, /compaction/*, /graft, /wiki subpaths).
• Extensions and manifests: extension kernel + event bus, contribution registries, middleware hooks, and data-only package manifests.
• Config, settings, security: layered config merge, settings providers, credential resolvers, trust/permission policies, and secret redaction.
• CLI/RPC/server: prism --mode print|json|rpc, prism init, optional framework-free authorized Web agent/workflow routes, and explicit MCP server exposure.
• Ecosystem parity: OpenAI hosted-tool attribution, bounded Responses continuation/Realtime, exact AI SDK V4 mapping, bounded RAG lifecycle/reranking/trust, and consent-bound memory export/rebuild; provider, RAG, and memory packages remain optional.
• Co-work contracts: conversation/artifact review types, deny-by-default device contracts, and OAuth refresh/revoke helpers; services stay in optional packages.

Install

bun add @arnilo/prism

First-party code packages require @arnilo/prism as a non-optional peer. Install the package that owns each capability; importing a subpath activates nothing until the host configures it:

bun add @arnilo/prism @arnilo/prism-providers                 # provider adapters
bun add @arnilo/prism @arnilo/prism-core @arnilo/prism-memory # persistence and memory
bun add @arnilo/prism @arnilo/prism-agent-sdk                 # configurable agent SDK
bun add @arnilo/prism @arnilo/prism-core @arnilo/prism-coding-tools @arnilo/prism-mcp
bun add @arnilo/prism @arnilo/prism-web-tools                 # web research and browser subpaths

Use subpaths only in imports, after installing their owning package:

import { createPostgresPersistence } from "@arnilo/prism-core/sessions/postgres";
import { createOpenAIProviderPackage } from "@arnilo/prism-providers/openai";

See docs/release-and-install.md for install specifiers, tarball contents, and the offline test budget.

Quick start

Scaffold a project (offline mock test included):

bunx --package @arnilo/prism prism init my-agent
# or, scaffold with a real provider package selected:
bunx --package @arnilo/prism prism init my-agent --provider openai
# or, scaffold a full deep research agent from the template gallery:
bunx --package @arnilo/prism prism init my-research --template deep-research
cd my-agent && bun install && bun test

List available template gallery starters:

prism init --list-templates

Or embed Prism directly:

import { createAgent, createAgentSession, createMockProvider } from "@arnilo/prism";

// Host owns the provider. createMockProvider is for tests/demos only.
const agent = createAgent({
  model: { provider: "mock", model: "demo" },
  provider: createMockProvider([{ type: "text", text: "Hello" }, { type: "done" }]),
});

const session = createAgentSession({ agent });

// Direct result: run/prompt return AgentRunResult (text, usage, status, ids).
const result = await session.run("Hi");
console.log(result.text, result.usage?.totalTokens);

// Integrated streaming: subscribe-before-run for one owned run.
for await (const event of session.stream("Hi again")) {
  // AgentEvent: agent_started, message_delta, turn_finished, ...
}

// Long-lived subscribe() still works when you need a subscriber across runs.
// `subscribe()` only emits while a run is in progress, so the loop and `run()`
// must run together; awaiting the loop before calling `run()` would deadlock.
(async () => {
  const consumer = (async () => {
    for await (const event of session.subscribe()) {
      // AgentEvent: agent_started, message_delta, turn_finished, ...
    }
  })();
  await Promise.all([consumer, session.run("Hi")]);
})();

Register a first-party provider package through the extension kernel:

import { createExtensionKernel, createEnvCredentialResolver } from "@arnilo/prism";
import { createOpenAIProviderPackage } from "@arnilo/prism-providers/openai";

const kernel = createExtensionKernel();
await kernel.load([
  createOpenAIProviderPackage({
    apiKey: createEnvCredentialResolver({ OPENAI_API_KEY: "fake" }, { openai: "OPENAI_API_KEY" }),
  }),
]);

Hosts own credentials. Do not put secrets in prompts, messages, events, stores, or logs. Prism never reads process.env on its own; credential resolvers are caller-supplied.

CLI

prism --provider mock --model demo -p "Hi"          # print mode (default)
prism --provider mock --mode json -p "Hi"            # one event envelope per line
printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
  | prism --provider mock --mode rpc                 # LF-delimited JSONL RPC

Docs

• docs/index.md — navigational map of every public surface.
• The examples/ directory holds compile-checked typed examples and runnable offline demos covering providers, auth, tools, stores, compaction, structured output, multimodality, workflows, CLI, and RPC.

Packages

14 publishable manifests — root @arnilo/prism plus 13 workspace packages (4 prism-* family packages, 9 capability packages). Generated by bun scripts/package-truth.mjs --emit-docs — do not hand-edit.

| package | version | notes | | --- | --- | --- | | @arnilo/prism | 0.12.1 | core — runtime, CLI/RPC, templates, docs | | @arnilo/prism-channels | 0.12.1 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal | | @arnilo/prism-coding-tools | 0.12.1 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /impeccable subpaths | | @arnilo/prism-core | 0.12.1 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths | | @arnilo/prism-providers | 0.12.1 | family — all provider adapters as /<adapter> subpaths | | @arnilo/prism-acp-agent | 0.12.1 | capability — ACP adapter | | @arnilo/prism-ag-ui | 0.12.1 | capability — AG-UI/A2A/A2UI adapter | | @arnilo/prism-agent-sdk | 0.1.0 | capability — configurable agent runtime assembly over tool planes, skills, instructions, MCP, and hooks | | @arnilo/prism-code | 0.4.0 | capability — terminal coding agent app: TUI, headless print/json, and ACP surfaces with bundled coding tools, repo sessions, observational memory, and optional web/wiki planes | | @arnilo/prism-hooks | 0.12.1 | capability — Claude/Codex-compatible hooks.json adapter compiled onto middleware, guardrail, injector, and stop-hook seams | | @arnilo/prism-mcp | 0.12.1 | capability — MCP client/server/OAuth interop | | @arnilo/prism-memory | 0.12.1 | capability — memory plus /rag, /compaction/*, /fabric, /wiki subpaths | | @arnilo/prism-web-tools | 0.12.1 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths | | @arnilo/prism-work | 0.12.1 | capability — /connectors, /documents, /sheets, /diagrams, /document-extraction, /document-reader, /sandbox, /skills, /tools subpaths |

Scripts

| command | action | |---------|--------| | bun ci | Install dependencies from the committed bun.lock (frozen) | | bun run build | Compile TypeScript to dist/ (core + workspaces) | | bun run typecheck | Type-check without emitting | | bun run test | Build + run network-free tests (npm test still works) | | bun run test:coverage | Coverage gate: bun test --coverage over the core suite and every gated workspace, with Bun-measured floors (scripts/coverage-thresholds.json) | | bun run test:live | Run live suites whose credentials are present (skip the rest) | | prism --help | CLI help |

Non-goals (v1)

• Privileged tools, MCP servers, telemetry, credentials, or databases activated by install — hosts explicitly configure and register every capability.
• Browser automation or interactive terminal UI in core — hosts may opt into the @arnilo/prism-web-tools/browser subpath with their own Playwright lifecycle; Prism does not auto-start browsers or ship a TUI.
• Provider, credential, extension, or package auto-discovery.
• Core-owned database drivers, secret persistence, sandbox, or application policy — optional packages implement adapters over host-owned boundaries.