@arnilo/prism 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.5] - 2026-07-16
+
+- `@arnilo/prism-providers` now installs all seven first-party adapters including AI SDK interoperability; `@arnilo/prism-all` now installs every first-party package while activating none automatically.
+
+- Added optional `@arnilo/prism-supervisor` with bounded explicit child delegation, derived memory scope IDs, narrowing-only permissions, A2A 1.0 cards/ES256 signatures, authorized JSON-RPC/SSE serving, and an exact-origin remote client.
+
+- Added bounded immutable run/trace feedback with exact ownership, evaluation linkage, memory/SQLite/PostgreSQL stores, schema migration 003, and safe OpenTelemetry projection.
+
+- Phase 11 extends workflows with explicit durable schedules/background execution, nested composition, bounded validated state, immutable-lineage replay, and optional command/Web bindings over existing checkpoint/lease primitives.
+
+- Optional `@arnilo/prism-server` package with authorized bounded Web-standard direct/SSE agent and durable workflow routes; `@arnilo/prism-mcp` now supports explicit authorized Prism tool/command server exposure and bounded Web-standard Streamable HTTP handling.
+- Optional `@arnilo/prism-rag` package: bounded deterministic text/Markdown chunking, Phase 7 vector indexing/retrieval, stable citations, metadata filters, redaction, and explicit ContextProvider injection.
+- Workflows now support durable human `suspend()`/approve/deny, expected-version exact-once resume, validated/redacted resume payloads, and opt-in tool approval with execution-policy recheck.
+
+### Added
+
+- Optional `@arnilo/prism-memory` package: schema/template-backed working memory, semantic recall, package-owned `Embedder`/`VectorStore` contracts, in-memory adapters, context provider, opt-in processor, shared conformance, and PostgreSQL/pgvector production path.
+
 ## [0.0.4] - 2026-07-14
 
 ### Added

package/README.md

@@ -26,13 +26,14 @@ packages. Prism defines contracts, not apps.
 - **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, and
-  observational-memory recall/status/view.
+  clone, default and LLM compaction strategies, retry policy,
+  observational-memory recall/status/view, optional working/semantic memory
+  (`@arnilo/prism-memory`), and bounded text/Markdown RAG (`@arnilo/prism-rag`).
 - **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**: `prism --mode print|json|rpc` over the same `AgentSession` API.
+- **CLI/RPC/server**: `prism --mode print|json|rpc`, `prism init`, optional framework-free authorized Web agent/workflow routes, and explicit MCP server exposure.
 
 ## Install
 
@@ -50,6 +51,8 @@ npm install @arnilo/prism-base                              # core + compaction
 npm install @arnilo/prism-code @arnilo/prism-provider-openai # coding-agent profile
 npm install @arnilo/prism-sdk @arnilo/prism-provider-openai  # application profile
 npm install @arnilo/prism-all                               # every first-party package
+npm install @arnilo/prism-server @arnilo/prism-workflows    # optional Web API boundary
+npm install @arnilo/prism-supervisor                         # optional local delegation + A2A 1.0
 ```
 
 See [docs/release-and-install.md](docs/release-and-install.md) for install
@@ -57,6 +60,17 @@ specifiers, tarball contents, and the offline test budget.
 
 ## Quick start
 
+Scaffold a tiny project (offline mock test included):
+
+```bash
+npx --package @arnilo/prism prism init my-agent
+# or, with a real provider package selected:
+npx --package @arnilo/prism prism init my-agent --provider openai
+cd my-agent && npm install && npm test
+```
+
+Or embed Prism directly:
+
 ```ts
 import { createAgent, createAgentSession, createMockProvider } from "@arnilo/prism";
 
@@ -68,9 +82,18 @@ const agent = createAgent({
 
 const session = createAgentSession({ agent });
 
-// Consume the event stream concurrently with the run. `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.
+// 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()) {
@@ -132,12 +155,13 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | `@arnilo/prism-coding-security` | coding approval, containment, and sandbox adapters |
 | `@arnilo/prism-tool-validator-json-schema` | bounded JSON Schema tool validation |
 | `@arnilo/prism-mcp` | MCP client/tool bridge |
-| `@arnilo/prism-workflows` | bounded DAG workflows and durable coordination |
+| `@arnilo/prism-workflows` | bounded DAG workflows, durable suspend/resume, schedules/background runs, composition/state/replay, and multi-process coordination |
+| `@arnilo/prism-supervisor` | bounded local child delegation and A2A 1.0 interoperability |
 | `@arnilo/prism-observability-opentelemetry` | optional OpenTelemetry adapter |
 | `@arnilo/prism-credentials-node` | encrypted-file and keychain credentials |
-| `@arnilo/prism-session-store-sqlite` | SQLite persistence/checkpoints/leases |
-| `@arnilo/prism-session-store-postgres` | PostgreSQL persistence/checkpoints/leases |
-| `@arnilo/prism-providers` | family: all 6 provider adapters |
+| `@arnilo/prism-session-store-sqlite` | SQLite persistence/checkpoints/leases/owned run feedback |
+| `@arnilo/prism-session-store-postgres` | PostgreSQL persistence/checkpoints/leases/owned run feedback |
+| `@arnilo/prism-providers` | family: all 7 provider adapters, including AI SDK interoperability |
 | `@arnilo/prism-compaction` | family: both compaction strategies |
 | `@arnilo/prism-base` | profile: core + compaction + JSON Schema validation |
 | `@arnilo/prism-code` | profile: base + coding tools/security + MCP |

package/dist/agents.js

@@ -1,3 +1,4 @@
+import { AgentRunError } from "./contracts.js";
 import { resolveLoop, resolveToolConcurrency } from "./agent-loops.js";
 import { createProviderTurnMetadata, readProviderHttpStatus } from "./observability.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "./compaction.js";
@@ -71,6 +72,8 @@ class RuntimeAgentSession {
         const model = options.model ?? this.agent.config.model;
         const startedAt = new Date().toISOString();
         let runError;
+        const runUsage = createUsageAccumulator();
+        let usage;
         try {
             this.resolveRunProvider(options);
             throwIfAborted(controller.signal);
@@ -114,6 +117,23 @@ class RuntimeAgentSession {
             const loop = resolveLoop(options, this.agent.config);
             const toolConcurrency = resolveToolConcurrency(options, this.agent.config);
             this.activeLoopTurn = 1;
+            const recordProviderUsage = async (turnUsage, turn, attempt) => {
+                runUsage.add(turnUsage);
+                if (!this.activeLedger)
+                    return;
+                const usageRecord = {
+                    id: randomId("usage"),
+                    sessionId: this.id,
+                    runId,
+                    scope: "provider_turn",
+                    turn,
+                    attempt,
+                    usage: turnUsage,
+                    recordedAt: new Date().toISOString(),
+                    ...this.activeOwnership,
+                };
+                await this.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, this.activeRedactor));
+            };
             // ponytail: LoopContext binds existing private helpers; loop orchestrates only.
             const ctx = {
                 sessionId: this.id,
@@ -152,7 +172,7 @@ class RuntimeAgentSession {
                 generate: async (request) => {
                     const policyResult = await this.applyProviderRequestPolicies(request, runId, options, metadata, controller.signal);
                     const middlewareRequest = await this.agent.config.middleware?.run("provider_request", policyResult.request) ?? policyResult.request;
-                    return this.generateWithRetry(this.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, this.activeLoopTurn);
+                    return this.generateWithRetry(this.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, this.activeLoopTurn, recordProviderUsage);
                 },
                 isToolCallExclusive: (call) => registry.get(call.name)?.exclusive === true,
                 dispatchToolCall: (call) => dispatchToolCall({
@@ -175,12 +195,14 @@ class RuntimeAgentSession {
                     this.emit(event);
                 },
             };
-            const usage = await loop.run(ctx);
+            const loopUsage = await loop.run(ctx);
+            usage = runUsage.value() ?? loopUsage;
             if (usage && this.activeLedger) {
                 const usageRecord = {
                     id: randomId("usage"),
                     sessionId: this.id,
                     runId,
+                    scope: "run_total",
                     usage,
                     recordedAt: new Date().toISOString(),
                     ...this.activeOwnership,
@@ -189,11 +211,23 @@ class RuntimeAgentSession {
             }
             await this.drainLedger();
             this.emit({ type: "agent_finished", sessionId: this.id, runId, usage });
+            return this.buildRunResult({
+                runId,
+                status: "succeeded",
+                usage,
+            });
         }
         catch (error) {
             runError = errorToErrorInfo(error);
             this.emit({ type: "error", sessionId: this.id, runId, error: runError });
-            throw error;
+            const result = this.buildRunResult({
+                runId,
+                status: controller.signal.aborted ? "aborted" : "failed",
+                usage: runUsage.value() ?? usage,
+                error: runError,
+                abortReason: controller.signal.aborted ? String(controller.signal.reason) : undefined,
+            });
+            throw new AgentRunError(result, { cause: error });
         }
         finally {
             if (this.activeRun === controller)
@@ -233,6 +267,48 @@ class RuntimeAgentSession {
     prompt(input, options) {
         return this.run(input, options);
     }
+    async *stream(input, options = {}) {
+        const { maxQueuedEvents, overflow, ...runOptions } = options;
+        const subscription = this.subscribe({ maxQueuedEvents, overflow });
+        let runOwnedId;
+        let settled = false;
+        const runPromise = this.run(input, runOptions).finally(() => {
+            settled = true;
+        });
+        try {
+            for await (const event of subscription) {
+                if ("runId" in event && typeof event.runId === "string") {
+                    if (runOwnedId === undefined && event.type === "agent_started")
+                        runOwnedId = event.runId;
+                    if (runOwnedId !== undefined && event.runId !== runOwnedId)
+                        continue;
+                }
+                yield event;
+            }
+            await runPromise;
+        }
+        finally {
+            if (!settled) {
+                this.abort(new Error("stream consumer closed"));
+                await runPromise.catch(() => undefined);
+            }
+        }
+    }
+    buildRunResult(input) {
+        const final = finalAssistantMessage(this.history);
+        return {
+            sessionId: this.id,
+            runId: input.runId,
+            status: input.status,
+            leafId: this.currentLeafId,
+            text: final.text,
+            content: final.content,
+            message: final.message,
+            usage: input.usage,
+            error: input.error,
+            abortReason: input.abortReason,
+        };
+    }
     async compact(options = {}) {
         if (this.activeRun)
             throw new Error("Agent session already has an active run");
@@ -340,13 +416,13 @@ class RuntimeAgentSession {
         if (failure)
             throw failure;
     }
-    async generateWithRetry(request, runId, options, signal, requestSecrets = [], turn = 1) {
+    async generateWithRetry(request, runId, options, signal, requestSecrets = [], turn = 1, recordUsage) {
         const retry = mergeRetry(this.agent.config.retry, options.retry);
         const secrets = [...requestSecrets, ...(retry?.secrets ?? [])];
         const policy = retry?.policy ?? (retry ? createDefaultRetryPolicy(retry) : undefined);
         for (let attempt = 1;; attempt += 1) {
             try {
-                return await this.generateProviderTurn(request, runId, signal, secrets, turn, attempt);
+                return await this.generateProviderTurn(request, runId, signal, secrets, turn, attempt, recordUsage);
             }
             catch (error) {
                 const failure = error instanceof ProviderTurnFailure ? error : undefined;
@@ -365,7 +441,7 @@ class RuntimeAgentSession {
             }
         }
     }
-    async generateProviderTurn(request, runId, signal, secrets = [], turn = 1, attempt = 1) {
+    async generateProviderTurn(request, runId, signal, secrets = [], turn = 1, attempt = 1, recordUsage) {
         const startedAt = performance.now();
         const providerId = this.activeProvider?.id ?? request.model.provider;
         const buildMetadata = (extra = {}) => createProviderTurnMetadata(request, providerId, { attempt, ...extra });
@@ -382,25 +458,20 @@ class RuntimeAgentSession {
         let messageId;
         let started = false;
         let usage;
+        let usageRecorded = false;
+        const recordTurnUsage = async () => {
+            if (!usage || usageRecorded)
+                return;
+            usageRecorded = true;
+            await recordUsage?.(usage, turn, attempt);
+        };
         try {
             for await (const event of this.activeProvider.generate(request)) {
                 throwIfAborted(signal);
                 if (event.type === "error")
                     throw new ProviderTurnFailure(event.error, started);
-                if (event.type === "usage") {
+                if (event.type === "usage")
                     usage = event.usage;
-                    if (this.activeLedger) {
-                        const usageRecord = {
-                            id: randomId("usage"),
-                            sessionId: this.id,
-                            runId,
-                            usage: event.usage,
-                            recordedAt: new Date().toISOString(),
-                            ...this.activeOwnership,
-                        };
-                        await this.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, this.activeRedactor));
-                    }
-                }
                 if (event.type === "done") {
                     usage = event.usage ?? usage;
                     break;
@@ -433,6 +504,7 @@ class RuntimeAgentSession {
                 calls.push(call);
                 this.emit({ type: "message_delta", sessionId: this.id, runId, content: call });
             }
+            await recordTurnUsage();
             const latencyMs = Math.round(performance.now() - startedAt);
             this.emit({
                 type: "provider_turn_finished",
@@ -447,12 +519,14 @@ class RuntimeAgentSession {
         catch (error) {
             const latencyMs = Math.round(performance.now() - startedAt);
             const info = error instanceof ProviderTurnFailure ? redactSecrets(error.info, secrets) : errorToErrorInfo(error, secrets);
+            await recordTurnUsage();
             this.emit({
                 type: "provider_turn_finished",
                 sessionId: this.id,
                 runId,
                 turn,
                 metadata: buildMetadata({ latencyMs, httpStatus: readProviderHttpStatus(info) }),
+                usage,
                 error: info,
             });
             if (error instanceof ProviderTurnFailure)
@@ -608,6 +682,19 @@ function inputToMessages(input) {
         return [input];
     return [...input];
 }
+function finalAssistantMessage(history) {
+    for (let index = history.length - 1; index >= 0; index -= 1) {
+        const message = history[index];
+        if (message.role !== "assistant")
+            continue;
+        const text = message.content
+            .filter((block) => block.type === "text")
+            .map((block) => block.text)
+            .join("");
+        return { message, content: message.content, text };
+    }
+    return { content: [], text: "" };
+}
 function activeTools(tools) {
     if (!tools)
         return { registry: createToolRegistry(), tools: [] };
@@ -673,6 +760,46 @@ function throwIfAbortedSignal(signal) {
     if (signal?.aborted)
         throw signal.reason instanceof Error ? signal.reason : new Error("Agent run aborted");
 }
+function createUsageAccumulator() {
+    const sums = new Map();
+    let costCurrency;
+    let costCompatible = true;
+    return {
+        add(usage) {
+            for (const key of ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"]) {
+                const value = usage[key];
+                if (value !== undefined)
+                    sums.set(key, (sums.get(key) ?? 0) + value);
+            }
+            const total = usage.totalTokens
+                ?? (usage.inputTokens !== undefined || usage.outputTokens !== undefined
+                    ? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)
+                    : undefined);
+            if (total !== undefined)
+                sums.set("totalTokens", (sums.get("totalTokens") ?? 0) + total);
+            if (usage.cost !== undefined && costCompatible) {
+                if (!sums.has("cost"))
+                    costCurrency = usage.currency;
+                else if (usage.currency !== costCurrency)
+                    costCompatible = false;
+                if (costCompatible)
+                    sums.set("cost", (sums.get("cost") ?? 0) + usage.cost);
+            }
+        },
+        value() {
+            if (sums.size === 0)
+                return undefined;
+            const usage = {};
+            for (const [key, value] of sums) {
+                if (key !== "cost" || costCompatible)
+                    usage[key] = value;
+            }
+            if (costCompatible && sums.has("cost") && costCurrency !== undefined)
+                usage.currency = costCurrency;
+            return Object.keys(usage).length > 0 ? usage : undefined;
+        },
+    };
+}
 function randomId(prefix) {
     return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
 }

package/dist/cli-init.d.ts

@@ -0,0 +1,41 @@
+import type { Writable } from "node:stream";
+export declare class InitUsageError extends Error {
+}
+export type InitProvider = string;
+export interface InitOptions {
+    readonly directory: string;
+    readonly provider: InitProvider;
+    readonly withWorkflows: boolean;
+    readonly withEvals: boolean;
+    readonly force: boolean;
+    readonly help: boolean;
+}
+export interface InitRuntime {
+    readonly stdout: Writable;
+    readonly stderr: Writable;
+    /** Override template root (tests). Defaults to package `templates/init`. */
+    readonly templatesRoot?: string;
+    /** Override package version stamped into generated package.json. */
+    readonly packageVersion?: string;
+    /** Working directory used to resolve relative destinations. Defaults to process.cwd(). */
+    readonly cwd?: string;
+}
+export interface InitResult {
+    readonly targetDir: string;
+    readonly writtenFiles: readonly string[];
+    readonly provider: InitProvider;
+    readonly withWorkflows: boolean;
+    readonly withEvals: boolean;
+    readonly totalBytes: number;
+}
+/** Provider ids supported by `prism init --provider`. Loaded from templates data. */
+export declare function listInitProviders(templatesRoot?: string): readonly string[];
+/** @deprecated Prefer listInitProviders(); retained for tests that import the name. */
+export declare const INIT_PROVIDERS: readonly string[];
+export declare function getInitUsage(templatesRoot?: string): string;
+export declare const initUsage: string;
+export declare function parseInitArgs(argv: readonly string[], templatesRoot?: string): InitOptions;
+export declare function runInitCommand(argv: readonly string[], runtime: InitRuntime): Promise<number>;
+export declare function createInitProject(options: InitOptions, runtime?: InitRuntime): Promise<InitResult>;
+export declare function defaultTemplatesRoot(): string;
+export declare function isInitProvider(value: string, templatesRoot?: string): value is InitProvider;