@arnilo/prism 0.0.3 → 0.0.5

package/docs/workflows.md

@@ -0,0 +1,293 @@
+# Workflows
+
+## What it does
+
+`@arnilo/prism-workflows` is an optional package for typed, bounded DAG orchestration over Prism sessions, tools, events, and persistence seams. Hosts define acyclic workflows with agent/function/tool/conditional/fan-out/join/nested-workflow nodes; the package runs a Kahn-style scheduler with a bounded worker pool, emits package-local `WorkflowEvent`s, checkpoints progress, and can coordinate queued runs across multiple host processes using durable leases and fencing.
+
+Primary exports:
+
+| Export | Purpose |
+| --- | --- |
+| `defineWorkflow` / `buildGraph` | Validate definitions (acyclicity, edge refs, limits) and build deterministic successor/indegree maps |
+| `agentNode`, `functionNode`, `toolNode`, `conditionalNode`, `fanOutNode`, `joinNode`, `workflowNode` | Typed node factories, including composition through the same runner |
+| `runWorkflow` / `resumeWorkflow` / `suspend` / `replayWorkflow` | Execute, durably suspend, exactly-once resume, or create an immutable-lineage replay from a succeeded node |
+| `createMemoryWorkflowCheckpoints` | In-process `WorkflowCheckpointAdapter` over core `createMemoryCheckpointStore()` |
+| `createWorkflowCheckpoints` | Adapt core `CheckpointStore` (including SQLite/PostgreSQL persistence capabilities) to workflow checkpoint shapes |
+| `createWorkflowEventBus` | Bounded pub/sub for `WorkflowEvent` with overflow policy |
+| `getWorkflowRun` / `listWorkflowRuns` / `cancelWorkflowRun` | Status, paginated list, and cancel helpers |
+| `createWorkflowCommands` | Optional `CommandDefinition[]` for direct/background/replay/status/list/cancel/resume and, when selected, schedule control |
+| `enqueueWorkflow` / `startWorkflowBackground` / `createWorkflowCoordinator` | Persist queued work and atomically claim/renew/execute it across processes using `LeaseStore` |
+| `createWorkflowSchedules` | Explicit ownership-scoped one-time/interval/host-calculated schedules over existing checkpoint/lease stores |
+
+Included through `@arnilo/prism-sdk` and `@arnilo/prism-all`; installing either profile does not start workflows. Interactive TUI is out of scope (C-012 deferred).
+
+## When to use it
+
+Use this package when a host needs multi-node dependency scheduling, conditionals, bounded fan-out/join, retries/timeouts, workflow events, or checkpoint/resume — without putting graph vocabulary into core.
+
+Use `createWorkflowCoordinator()` when multiple processes share SQLite/PostgreSQL persistence and must claim queued work exclusively. It is a database-backed coordinator, not a separate broker, DSL parser, provider abstraction, or terminal UI. Agent nodes call public `AgentSession.run()` only; tool nodes go through ordinary `ToolDefinition` dispatch and optional `ExecutionPolicy`.
+
+## Inputs / request
+
+`defineWorkflow({ id, nodes, edges, limits? })`:
+
+| Field | Notes |
+| --- | --- |
+| `id` | Stable workflow id (required) |
+| `nodes` | Record of node definitions (`kind` + typed fields) |
+| `edges` | `[from, to]` pairs; must be acyclic; unknown ids rejected |
+| `limits.maxNodes` | Default 1000 |
+| `limits.maxFanOut` | Default 64 |
+| `limits.maxConcurrency` | Default 8 |
+| `limits.maxNodeOutputBytes` | Default 4 MiB |
+| `limits.maxCheckpointBytes` | Default 1 MiB |
+| `limits.maxNestedDepth` / hard cap | 8 / 32; inherited by child workflows |
+| `limits.maxStateBytes` / hard cap | 64 KiB / 512 KiB |
+| `limits.maxStateHistory` / hard cap | 32 / 128 state snapshots; updates stop before evidence would be discarded |
+| `limits.maxReplayDepth` / hard cap | 8 / 32 lineage generations |
+| `state.initial` / `state.schema` | Initial shared JSON object and optional host-validated schema |
+
+`runWorkflow(workflow, input, options?)`:
+
+| Option | Notes |
+| --- | --- |
+| `concurrency` | Worker pool size (capped by workflow/global limits) |
+| `checkpoints` | `WorkflowCheckpointAdapter` for save/load/list |
+| `agentFactory` | `(agentName) => AgentSession` for agent nodes |
+| `tools` | Tool registry/lookup for tool nodes |
+| `executionPolicy` | Optional `ExecutionPolicy`; tool actions include `workflowId`/`nodeId` metadata |
+| `runLedger` | Optional `RunLedger` for agent-event bridging |
+| `ownership` | Tenant/account/user scope copied into checkpoints |
+| `redactor` / `secrets` | Redaction before checkpoint persistence and event emission |
+| `signal` | Cancels the run and in-flight agent sessions |
+| `onEvent` | Synchronous `WorkflowEvent` sink |
+| `runId` | Caller-supplied id; otherwise generated (`wfr_…`) |
+| `resume` | For suspended runs: `{ decision: "approve" | "deny", input?, expectedVersion }`; version is mandatory for an exact-once CAS claim |
+| `validateResume` | Host validator for resume input; required when `suspend()` declares `resumeSchema` |
+| `validateState` | Host validator for every initial/restored/updated state; required when workflow declares `state.schema` |
+| `initialState` | Optional host initial state override; nested workflows receive parent state automatically |
+
+A function node returns `suspend({ reason, data?, resumeSchema? })` to persist `status: "suspended"`. Its next invocation receives `ctx.resume` only after an approved resume. `resumeWorkflow(workflow, { runId }, options)` validates schema/version/ownership/`definitionHash`, claims the checkpoint before node execution, and continues the suspended node. Denial persists terminal `denied` status without invoking it. Existing failed/aborted checkpoint resume remains available without a human decision.
+
+Every node receives bounded `ctx.state`, `ctx.stateVersion`, and async `ctx.updateState(patch, { mode: "merge" | "replace" })`. Updates serialize, validate, redact, and snapshot before checkpoint save. `workflowNode({ workflow })` runs its child with the same ownership, agent/tool registries, execution policy, redactor, signal, checkpoints, and event bus; child state replaces parent state after success.
+
+`replayWorkflow(workflow, { sourceRunId, fromNodeId, runId? }, options)` requires a succeeded source/node, creates a new checkpoint, copies terminal evidence outside the selected node's downstream closure, restores selected-node pre-state, and records `{ sourceRunId, fromNodeId, rootRunId, depth }`. Source evidence is untouched. Copying any prior nested/tool approval is rejected; replay from that approval node or earlier so Phase 8 approval executes again.
+
+`createWorkflowCoordinator({ coordinatorId, workflows, checkpoints, leases, ... })` polls queued/running checkpoints with bounded pages, atomically claims each run, renews its lease, and aborts/fences work after lease loss. Key controls: `leaseTtlMs` (default 30s), `renewalIntervalMs` (default TTL/3), `pollIntervalMs` (default 1s), `maxConcurrentRuns` (default 4), and `pageSize` (default 100, maximum 500).
+
+`createWorkflowSchedules({ store, leases, checkpoints, workflows, ownership, ownerId, calculators? })` is inert until its host calls `pollOnce()` or `run({ signal })`. Ownership requires `tenantId` plus `accountId` or `userId`. Methods are `create`, `get`, `list`, `pause`, `resume`, `trigger`, `delete`, `pollOnce`, and `run`. A record has one required `nextRunAt`, optional fixed `intervalMs` or registered `calculatorId` (never both), bounded input/metadata, status, version, and last-fire attribution. Manual trigger requires an idempotency key. Scheduled run IDs derive from schedule ID plus fire timestamp, so retry after enqueue-before-advance finds the same queued checkpoint instead of duplicating it. Defaults: page 100/hard 500, due claims 16/hard 256, input 256 KiB/hard 1 MiB, poll 1s, fire lease 30s.
+
+## Outputs / response / events
+
+`runWorkflow` / `resumeWorkflow` resolve to `WorkflowRunResult`:
+
+| Field | Notes |
+| --- | --- |
+| `runId`, `workflowId`, `status` | `queued` / `running` / `suspended` / `succeeded` / `failed` / `denied` / `aborted` |
+| `outputs` | Map of succeeded node outputs |
+| `state` | Final/current bounded shared JSON state |
+| `lineage` | Replay source/root/node/depth record when this is a replay |
+| `suspension` | Current/persisted `{ nodeId, reason, data?, resumeSchema?, requestedAt }` |
+| `resume` | Attributable resume decision/input/version/time record |
+| `version` | Checkpoint CAS identity shown to reviewers and required on suspended resume |
+
+Schedule `onEvent` receives bounded-attribution `schedule_fired` or metadata-only `schedule_failed`; schedule input is never copied into these events.
+
+Package-local `WorkflowEvent` types: `workflow_started`, `workflow_suspended`, `workflow_resumed`, `workflow_finished`, `node_started`, `node_finished`, `node_failed`, `node_skipped`, `checkpoint_saved`, `agent_event` (wraps a redacted `AgentEvent`), `workflow_event_overflow`. Sequences are monotonic; drain/order is deterministic by `(sequence, nodeId)`.
+
+## Request/response example
+
+```json
+{
+  "id": "research-draft",
+  "nodes": ["research", "draft"],
+  "edges": [["research", "draft"]],
+  "limits": { "maxNodes": 256, "maxFanOut": 32, "maxConcurrency": 4 }
+}
+```
+
+Successful run shape:
+
+```json
+{
+  "runId": "wfr_01HZX…",
+  "workflowId": "research-draft",
+  "status": "succeeded",
+  "outputs": { "research": "…", "draft": "…" },
+  "version": 3
+}
+```
+
+## Implementation example
+
+```ts
+import {
+  defineWorkflow,
+  runWorkflow,
+  resumeWorkflow,
+  functionNode,
+  agentNode,
+  createWorkflowCheckpoints,
+  createWorkflowCommands,
+  cancelWorkflowRun,
+  enqueueWorkflow,
+  createWorkflowCoordinator,
+  createWorkflowSchedules,
+  replayWorkflow,
+  workflowNode,
+  suspend,
+} from "@arnilo/prism-workflows";
+import { runRpcServer } from "@arnilo/prism";
+import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+
+const research = agentNode({
+  agent: "researcher",
+  input: (ctx) => ctx.workflowInput,
+});
+const draft = functionNode({
+  execute: async (ctx) => `Draft from ${String(ctx.upstream.research)}`,
+});
+const publish = functionNode({
+  execute: async (ctx) => ctx.resume
+    ? publishDraft(ctx.upstream.draft, ctx.resume.input)
+    : suspend({
+        reason: "publish",
+        data: { draft: ctx.upstream.draft },
+        resumeSchema: { type: "object", required: ["reviewer"] },
+      }),
+});
+
+const workflow = defineWorkflow({
+  id: "research-draft",
+  nodes: { research, draft, publish },
+  edges: [["research", "draft"], ["draft", "publish"]],
+  limits: { maxNodes: 256, maxFanOut: 32, maxConcurrency: 4 },
+});
+
+const persistence = createSqlitePersistence({ filename: "prism.db" });
+const checkpoints = createWorkflowCheckpoints({ store: persistence.checkpoints });
+
+const queued = await enqueueWorkflow(workflow, { topic: "hooks" }, {
+  checkpoints,
+  ownership: { tenantId: "t1" },
+});
+const coordinator = createWorkflowCoordinator({
+  coordinatorId: process.env.HOSTNAME ?? "worker-1",
+  workflows: { [workflow.id]: workflow },
+  checkpoints,
+  leases: persistence.leases,
+  ownership: { tenantId: "t1" },
+  runOptions: { agentFactory: (name) => agents.resolve(name).createSession() },
+  maxConcurrentRuns: 4,
+});
+await coordinator.run({ signal: shutdownSignal });
+
+// Direct single-process execution remains available:
+const result = await runWorkflow(workflow, { topic: "hooks" }, {
+  agentFactory: (name) => agents.resolve(name).createSession(),
+  checkpoints,
+  ownership: { tenantId: "t1" },
+  signal: AbortSignal.timeout(60_000),
+  onEvent: (event) => sink.push(event),
+});
+
+// Durable human resume after process restart. Use result.version shown to reviewer.
+if (result.status === "suspended") {
+  await resumeWorkflow(workflow, { runId: result.runId }, {
+    checkpoints,
+    agentFactory: (name) => agents.resolve(name).createSession(),
+    ownership: { tenantId: "t1" },
+    resume: {
+      decision: "approve",
+      input: { reviewer: "Ada" },
+      expectedVersion: result.version,
+    },
+    validateResume: ({ value }) => validateResumePayload(value),
+  });
+}
+
+await cancelWorkflowRun({
+  workflowId: workflow.id,
+  runId: result.runId,
+  checkpoints,
+  ownership: { tenantId: "t1" },
+});
+
+// Optional host control via existing CLI/RPC CommandDefinition seam:
+const schedules = createWorkflowSchedules({
+  store: persistence.checkpoints,
+  leases: persistence.leases,
+  checkpoints,
+  workflows: { [workflow.id]: workflow },
+  ownership: { tenantId: "t1", userId: "ops" },
+  ownerId: process.env.HOSTNAME ?? "scheduler-1",
+});
+await schedules.create({
+  id: "daily-research",
+  workflowId: workflow.id,
+  nextRunAt: "2026-07-17T00:00:00.000Z",
+  intervalMs: 86_400_000,
+  input: { topic: "hooks" },
+});
+// Host calls schedules.pollOnce() from an existing timer, or explicitly starts schedules.run({ signal }).
+
+const replay = await replayWorkflow(workflow, {
+  sourceRunId: result.runId,
+  fromNodeId: "draft",
+}, { checkpoints, ownership: { tenantId: "t1" }, agentFactory });
+
+runRpcServer({
+  createSession,
+  commands: createWorkflowCommands({
+    workflows: { [workflow.id]: workflow },
+    checkpoints,
+    schedules,
+    runOptions: { ownership: { tenantId: "t1" }, agentFactory },
+  }),
+});
+```
+
+## Extension and configuration notes
+
+- Workflow semantics stay in this optional package; generic checkpoint persistence and bounded event fan-in live in core.
+- `ProductionPersistenceStore.checkpoints` and `.leases` are optional generic capabilities. First-party SQLite/PostgreSQL adapters own `prism_checkpoints` / `prism_leases`; workflows only adapt them.
+- `createWorkflowEventBus()` delegates queueing, source fan-in, overflow, abort, and close behavior to core `createEventMultiplexer()`.
+- `createWorkflowCommands()` is optional; hosts can drive `workflow.start` / `enqueue` / `replay` / `status` / `list` / `cancel` / `resume`. The six `schedule.*` commands appear only when a scoped `schedules` service is supplied.
+- Hosts may bridge `WorkflowEvent` into OpenTelemetry or custom sinks; there is no built-in TUI.
+- Agent exclusivity is per session: one active `run()` at a time, same as core.
+
+## Security and performance notes
+
+- Definitions fail closed on cycles, unknown edges, self-edges, and `maxNodes` overflow.
+- Fan-out length is bounded by `maxFanOut`; concurrency by `maxConcurrency`.
+- Node outputs, shared state/history, schedule input/records, and checkpoints are byte/count/depth bounded. Checkpoint size remains the final aggregate ceiling.
+- Event buses use a bounded buffer (default 2048) with `close` / `drop_oldest` / `drop_newest` overflow.
+- Checkpoints redact suspension/resume payloads via `SecretRedactor` / `secrets` before save; resume rejects tenant, schema, definition-hash, and expected-version mismatch.
+- Suspension requires a checkpoint adapter, consumes no worker/polling slot, and is ignored by distributed coordinators until explicit resume.
+- Concurrent resumes race on checkpoint CAS before node execution; one wins and stale/duplicate reviewers fail closed. Approved tool nodes then re-run current `ExecutionPolicy`, so durable approval cannot grant stale permissions.
+- `toolNode({ approval: { reason, data?, resumeSchema? } })` suspends before tool execution. Denial is terminal `denied`; no tool side effect occurs.
+- `cancelWorkflowRun` aborts local runs immediately and writes a durable cancellation request for a remotely leased run; workers check it during lease renewal.
+- Tool nodes attach `workflowId` / `nodeId` on `ExecutionAction.metadata` for approval/audit context.
+- Nested workflows inherit host registries/policies and cannot inject broader tools, agents, ownership, or credentials. Nested depth is inherited; child suspension bubbles to the parent review cursor.
+- Replay source ownership/hash/status/node eligibility are checked before a new checkpoint is created. Source records are immutable, lineage is bounded, and copied approval-bearing paths are rejected.
+- Schedule services are ownership-scoped and explicitly started. Per-fire leases plus deterministic run IDs/CAS prevent duplicate enqueue across coordinators and crash retry. Host calculator IDs resolve only from the supplied map; no callback or cron expression is persisted.
+- Scheduler stores O(nodes + active outputs + bounded state history); ready-node work uses indegree maps, not repeated full scans.
+- Lease acquisition is atomic; opaque tokens protect renew/release; monotonically increasing fencing tokens plus checkpoint compare-and-swap prevent expired workers from committing after takeover. Node functions must honor `ctx.signal` for prompt cooperative cancellation.
+
+Use workflows for known, durable, replayable graphs. Use optional supervisor delegation only when child selection must be dynamic at runtime; do not replace deterministic nodes with model routing without a concrete need.
+
+## Related APIs
+
+- Examples: `examples/workflow-research-and-review.ts`, `examples/workflow-parallel-research.ts`, `examples/workflow-tool-approval.ts`, `examples/workflow-multimodal-document.ts`, `examples/workflow-sqlite-resume.ts`, `examples/workflow-postgres-resume.ts`, `examples/workflow-event-sink.ts`, `examples/workflow-rpc-cancel.ts`, `examples/workflow-distributed-coordinator.ts` — offline runnable demos; PostgreSQL safely skips unless `PRISM_TEST_POSTGRES_URL` is set.
+- [Workflow orchestration primitives](workflow-orchestration-primitives.md): Task 0–1 inventory and locked adapter contracts
+- [Agent/session runtime](agent-session-runtime.md): `AgentSession.run()`/`stream()`, abort, subscribe
+- [Supervisor delegation](supervisors.md): bounded dynamic child selection.
+- [Agent events](agent-events.md): core `AgentEvent` wrapped by `agent_event`
+- [Session stores and branching](session-stores-and-branching.md): session `leafId` reuse on resume
+- [CLI/RPC](cli-rpc.md): host control seam; wire `createWorkflowCommands()` into `runRpcServer`
+- [Database persistence](database-persistence.md): generic `CheckpointStore` and `LeaseStore` capabilities
+- [SQLite persistence](sqlite-persistence.md): durable `persistence.checkpoints`
+- [PostgreSQL persistence](postgres-persistence.md): durable `persistence.checkpoints`
+- [Observability](observability.md): exporting workflow/agent events
+- [Coding execution approval and sandboxing](coding-security.md): `ExecutionPolicy` for tool nodes
+- [Release and install](release-and-install.md): atomic and profile installs

package/docs/working-and-semantic-memory.md

@@ -0,0 +1,169 @@
+# Working and semantic memory
+
+## What it does
+
+`@arnilo/prism-memory` is an optional package for schema/template-backed working memory and embedding-based semantic recall. It owns narrow `Embedder` and `VectorStore` contracts reused by `@arnilo/prism-rag`, plus an in-memory reference path and one PostgreSQL/pgvector production adapter.
+
+## When to use it
+
+Use it when a host needs durable per-tenant profile/state (working memory) or top-K semantic retrieval over prior thread entries. Do not use it as a replacement for observational memory compaction: observational memory compresses source-backed observations; semantic memory retrieves embeddings; working memory stores the current structured profile.
+
+Ordinary Prism sessions do not require this package or any vector backend.
+
+## Inputs / request
+
+`createMemory(options)`:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `tenantId` | yes | Tenant isolation key |
+| `resourceId` | yes | Resource/user isolation key |
+| `threadId` | for semantic ops | Thread isolation; optional for resource-scoped working memory |
+| `embedder` | yes | Host-owned or package hash embedder |
+| `vectorStore` / `workingStore` | no | Defaults to in-memory adapters |
+| `schema` / `validateWorkingMemory` | no | Working-memory shape checks (JSON Schema subset or host hook) |
+| `workingMemoryTemplate` | no | `{{path}}` template for context injection |
+| `limits` | no | top-K, adjacent range, batch, payload, injected-token caps |
+| `redactor` / `secrets` | no | Redact text/metadata before persist/inject |
+
+Semantic indexing:
+
+```ts
+await memory.remember({ entries: [{ id, text, metadata?, sequence? }] }, { wait?: boolean })
+```
+
+Semantic recall:
+
+```ts
+await memory.recall(query, { topK?, messageRange?, signal? })
+```
+
+## Outputs / response / events
+
+| API | Result |
+| --- | --- |
+| `updateWorking` / `getWorking` | Versioned `WorkingMemoryRecord` |
+| `remember` | `{ accepted, pending, done }` — default `wait: false` indexes asynchronously |
+| `recall` | `{ hits, adjacent }` tenant/thread scoped |
+| `createContextProvider()` | Inert `ContextProvider` blocks for working and/or semantic text |
+| `createWorkingMemoryProcessor({ extract })` | Explicit host-invoked updater; never auto-runs |
+
+No package-owned agent events are emitted. Injection uses existing context assembly only.
+
+## Request/response example
+
+```json
+{
+  "tenantId": "t1",
+  "resourceId": "user-ada",
+  "threadId": "thread-1",
+  "working": { "name": "Ada", "preferences": { "format": "concise" } },
+  "recall": {
+    "query": "preferred response format",
+    "topK": 5,
+    "messageRange": 1
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+import { createHashEmbedder, createMemory } from "@arnilo/prism-memory";
+
+const memory = createMemory({
+  tenantId: "t1",
+  resourceId: "user-ada",
+  threadId: "thread-1",
+  embedder: createHashEmbedder(),
+  workingMemoryTemplate: "Name: {{name}}; Format: {{preferences.format}}",
+  schema: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      preferences: {
+        type: "object",
+        properties: { format: { type: "string" } },
+        required: ["format"],
+        additionalProperties: false,
+      },
+    },
+    required: ["name"],
+    additionalProperties: false,
+  },
+});
+
+await memory.updateWorking({ name: "Ada", preferences: { format: "concise" } });
+await memory.remember({ entries: [{ id: "m1", text: "Prefers concise answers" }] });
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("Got it."), providerDone()]),
+  context: [memory.createContextProvider()],
+});
+```
+
+PostgreSQL/pgvector:
+
+```ts
+import { createPostgresMemoryStores, createMemory, createHashEmbedder } from "@arnilo/prism-memory";
+
+const stores = await createPostgresMemoryStores({
+  connectionString: process.env.DATABASE_URL!,
+  schema: "prism_memory",
+  dimensions: 32,
+});
+
+const memory = createMemory({
+  tenantId: "t1",
+  resourceId: "user-ada",
+  threadId: "thread-1",
+  embedder: createHashEmbedder({ dimensions: 32 }),
+  workingStore: stores.workingStore,
+  vectorStore: stores.vectorStore,
+});
+```
+
+## Extension and configuration notes
+
+- Hosts wire the context provider into `AgentConfig.context` or `resolveContextProviders()`.
+- The working-memory processor is opt-in and host-invoked; middleware is not required.
+- `createHashEmbedder()` is for tests/demos only; production hosts supply a real `Embedder`.
+- Observational memory (`@arnilo/prism-compaction-observational-memory`) remains unchanged and composable.
+- Profile bundles do not include this package yet.
+
+Shared conformance:
+
+```ts
+import { runMemoryConformance, createHashEmbedder, createMemoryVectorStore, createMemoryWorkingStore } from "@arnilo/prism-memory";
+
+await runMemoryConformance(() => ({
+  embedder: createHashEmbedder(),
+  vectorStore: createMemoryVectorStore(),
+  workingStore: createMemoryWorkingStore(),
+}));
+```
+
+## Security and performance notes
+
+- Every write/query/delete requires `tenantId` + `resourceId`; semantic paths also require `threadId`.
+- Cross-tenant and cross-thread access is denied.
+- Configure `secrets` / `redactor` so memory text and metadata cannot persist or inject raw canaries.
+- Injected context is inert text — it cannot grant tools or permissions.
+- Hard caps: top-K ≤ 32, messageRange ≤ 4, embed batch ≤ 128, injected tokens ≤ 8000, payload/working-memory byte limits enforced.
+- Default `remember()` does not block agent completion; pass `{ wait: true }` when indexing must finish first.
+- PostgreSQL live suite is gated by `PRISM_TEST_POSTGRES_URL` and requires the `vector` extension.
+
+## Delegated-agent isolation
+
+Supervisor child factories receive unique derived `resourceId` and `threadId` values. Construct each child's `createMemory()` facade from those exact values; never reuse parent memory scope or let model-supplied IDs select another resource.
+
+## Related APIs
+
+- [Supervisor delegation](supervisors.md): package-derived child resource/thread scope.
+- [Retrieval-augmented generation](rag.md): bounded document chunks reuse this package's embed/vector contracts.
+- [Context and skills](context-and-skills.md): `ContextProvider` injection seam.
+- [Observational memory compaction package](compaction-observational-memory.md): source-backed observation/reflection memory distinction.
+- [PostgreSQL persistence](postgres-persistence.md): session/run persistence; memory vectors live in this optional package instead.
+- [Middleware hooks](middleware-hooks.md): reuse existing `context` hook if hosts transform injected blocks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,6 +14,18 @@
       "types": "./dist/providers/openai-compatible.d.ts",
       "default": "./dist/providers/openai-compatible.js"
     },
+    "./providers/transport": {
+      "types": "./dist/providers/transport.d.ts",
+      "default": "./dist/providers/transport.js"
+    },
+    "./providers/openai": {
+      "types": "./dist/providers/openai-primitives.d.ts",
+      "default": "./dist/providers/openai-primitives.js"
+    },
+    "./providers/media": {
+      "types": "./dist/providers/media.d.ts",
+      "default": "./dist/providers/media.js"
+    },
     "./testing/provider-conformance": {
       "types": "./dist/testing/provider-conformance.d.ts",
       "default": "./dist/testing/provider-conformance.js"
@@ -34,6 +46,18 @@
       "types": "./dist/testing/extension-conformance.d.ts",
       "default": "./dist/testing/extension-conformance.js"
     },
+    "./testing/persistence-schema": {
+      "types": "./dist/testing/persistence-schema.d.ts",
+      "default": "./dist/testing/persistence-schema.js"
+    },
+    "./testing/run-ledger-conformance": {
+      "types": "./dist/testing/run-ledger-conformance.d.ts",
+      "default": "./dist/testing/run-ledger-conformance.js"
+    },
+    "./testing/feedback": {
+      "types": "./dist/testing/feedback.d.ts",
+      "default": "./dist/testing/feedback.js"
+    },
     "./node/config": {
       "types": "./dist/node/config.d.ts",
       "default": "./dist/node/config.js"
@@ -75,23 +99,37 @@
     "!dist/__tests__",
     "!dist/**/*.map",
     "docs",
+    "templates",
     "CHANGELOG.md"
   ],
   "workspaces": [
     "packages/provider-*",
     "packages/compaction-*",
+    "packages/observability-*",
+    "packages/tool-validator-*",
+    "packages/session-store-*",
+    "packages/credentials-node",
+    "packages/mcp",
     "packages/coding-agent",
-    "packages/prism-providers",
-    "packages/prism-compaction",
-    "packages/prism-all"
+    "packages/coding-security",
+    "packages/workflows",
+    "packages/evals",
+    "packages/memory",
+    "packages/rag",
+    "packages/server",
+    "packages/supervisor",
+    "packages/prism-*"
   ],
   "scripts": {
     "build:core": "tsc",
     "build": "npm run build:core && npm run build --workspaces --if-present",
-    "typecheck": "npm run build:core && npm run typecheck --workspaces --if-present && tsc -p examples --noEmit",
+    "typecheck": "npm run build && npm run typecheck --workspaces --if-present && tsc -p examples --noEmit",
     "test": "npm run build && node --test dist/__tests__/*.test.js && npm run test --workspaces --if-present",
     "pack:dry-run": "npm pack --dry-run && npm run pack:dry-run --workspaces --if-present",
+    "test:postgres": "npm run test:postgres --workspace @arnilo/prism-session-store-postgres && npm run test:postgres --workspace @arnilo/prism-memory",
     "release:dry-run": "npm run sdk:ready",
+    "release:check": "node scripts/release.mjs check",
+    "release:publish": "node scripts/release.mjs publish",
     "sdk:ready": "npm run typecheck && npm test && npm run pack:dry-run"
   },
   "devDependencies": {

package/templates/init/README.md.tmpl

@@ -0,0 +1,28 @@
+# __PROJECT_NAME__
+
+Minimal Prism agent scaffold generated by `prism init`.
+
+__PROVIDER_README_NOTE__
+
+## Setup
+
+```bash
+npm install
+npm test
+```
+
+`npm test` always uses the built-in mock provider (no network, no credentials).
+
+__NEXT_STEPS_LIVE__
+
+## Layout
+
+- `src/agent.ts` — creates the agent with the selected provider.
+- `src/index.ts` — runs one prompt and prints `AgentRunResult.text`.
+- `src/__tests__/agent.test.ts` — offline mock smoke test.
+__OPTIONAL_DOCS__
+## Notes
+
+- Prism does not auto-load credentials, databases, telemetry, or tools.
+- Keep real secrets out of git; `.gitignore` excludes `.env` and local stores.
+- Docs: https://github.com/ashiqrniloy/prism

package/templates/init/env.example.tmpl

@@ -0,0 +1 @@
+__ENV_EXAMPLE__

package/templates/init/gitignore.tmpl

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+.env
+.env.local
+*.db
+*.sqlite
+*.sqlite3
+.prism/
+coverage/
+.DS_Store
+*.log

package/templates/init/optional/evals-example.ts.tmpl

@@ -0,0 +1,17 @@
+import type { AgentRunResult } from "@arnilo/prism";
+import { defineScorer, scoreRun } from "@arnilo/prism-evals";
+
+/**
+ * Deterministic scorer example. Not wired into `npm start` — call after a run.
+ */
+export const greetsScorer = defineScorer({
+  id: "greets",
+  score: ({ result }) => ({
+    score: /\bhello\b/i.test(result.text) ? 1 : 0,
+    reason: "checks for a hello greeting",
+  }),
+});
+
+export async function scoreGreeting(result: AgentRunResult) {
+  return scoreRun({ result, scorers: [greetsScorer] });
+}

package/templates/init/optional/workflows-example.ts.tmpl

@@ -0,0 +1,27 @@
+import {
+  createMemoryWorkflowCheckpoints,
+  defineWorkflow,
+  functionNode,
+  runWorkflow,
+} from "@arnilo/prism-workflows";
+
+/**
+ * Tiny workflow example. Not wired into `npm start` — import and call from your host.
+ */
+export async function runHelloWorkflow(name: string) {
+  const workflow = defineWorkflow({
+    id: "hello",
+    nodes: {
+      greet: functionNode({
+        execute: async (ctx) => {
+          const input = ctx.workflowInput as { name?: string };
+          return { message: `Hello, ${input.name ?? name}` };
+        },
+      }),
+    },
+  });
+
+  return runWorkflow(workflow, { name }, {
+    checkpoints: createMemoryWorkflowCheckpoints(),
+  });
+}

package/templates/init/package.json.tmpl

@@ -0,0 +1,22 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/__tests__/agent.test.js",
+    "start": "npm run build && node dist/index.js"
+  },
+  "dependencies": {
+__DEPENDENCIES__
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}