@arnilo/prism 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.2] - 2026-07-05
+
 ### Added
 
 - Added `LICENSE` (MIT) and `CHANGELOG.md` to the published `prism` package.
@@ -19,8 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `dist/**/*.map` from published tarballs; source maps remain emitted locally
   for debugging but are no longer shipped.
 - Core tarball now ships the `/docs` hub.
-- Made `prism` a required peer dependency for all first-party workspace packages; it is no longer optional. The peer range remains `0.0.1` and will widen to `^1.0.0` at the 1.x stable release.
-- Pinned the no-network `npm test` budget at < 30s on Node 20 (measured baseline ~22s); recorded in `roadmap.md` Phase 17.
+- Made `prism` a required peer dependency for all first-party workspace packages; it is no longer optional. The peer range remains `0.0.2` and will widen to `^1.0.0` at the 1.x stable release.
+- Pinned the no-network `npm test` budget at < 60s on Node 20 (measured baseline ~45s) after the default suite grew to include every first-party package, offline install smoke, packaging guards, docs examples, and workspace tests.
 
 ## [0.0.1] - 2026-06-22
 

package/README.md

@@ -13,10 +13,14 @@ packages. Prism defines contracts, not apps.
   compact, and navigate branches.
 - **Providers and models**: provider/model registries, provider event helpers,
   credential redaction helpers, mock provider, and an optional
-  OpenAI-compatible provider subpath.
+  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](docs/provider-caching.md).
 - **First-party packages**: `@arnilo/prism-provider-openai`, `@arnilo/prism-provider-opencode-go`,
   `@arnilo/prism-provider-openrouter`, `@arnilo/prism-provider-zai`, `@arnilo/prism-provider-kimi`,
-  `@arnilo/prism-compaction-llm`, and `@arnilo/prism-compaction-observational-memory`.
+  `@arnilo/prism-provider-neuralwatt`, `@arnilo/prism-compaction-llm`, and
+  `@arnilo/prism-compaction-observational-memory`.
 - **Tools, context, skills**: host-owned tool registry with allow/deny filtering
   and dispatch, context providers, and a skill registry with progressive
   disclosure.
@@ -63,11 +67,16 @@ 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.
 (async () => {
-  for await (const event of session.subscribe()) {
-    // AgentEvent: agent_started, message_delta, turn_finished, ...
-  }
-  await session.run("Hi");
+  const consumer = (async () => {
+    for await (const event of session.subscribe()) {
+      // AgentEvent: agent_started, message_delta, turn_finished, ...
+    }
+  })();
+  await Promise.all([consumer, session.run("Hi")]);
 })();
 ```
 
@@ -115,9 +124,10 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 | `@arnilo/prism-provider-openrouter` | OpenRouter provider with per-model cache control |
 | `@arnilo/prism-provider-zai` | ZAI GLM provider |
 | `@arnilo/prism-provider-kimi` | Kimi For Coding provider |
+| `@arnilo/prism-provider-neuralwatt` | NeuralWatt provider with implicit vLLM prefix caching |
 | `@arnilo/prism-compaction-llm` | provider-backed compaction strategy |
 | `@arnilo/prism-compaction-observational-memory` | source-backed memory + recall tool |
-| `@arnilo/prism-providers` | umbrella: all 5 provider adapters |
+| `@arnilo/prism-providers` | umbrella: all 6 provider adapters |
 | `@arnilo/prism-compaction` | umbrella: both compaction strategies |
 | `@arnilo/prism-all` | umbrella: core + providers + compaction |
 

package/dist/agent-definitions.d.ts

@@ -0,0 +1,12 @@
+import type { Agent, AgentDefinition, AgentDefinitionResolutionContext } from "./contracts.js";
+/** Resolve an {@link AgentDefinition} into a runnable {@link Agent}.
+ *
+ *  If the definition provides a `create()` escape hatch, that factory is called
+ *  with a config built from the declarative fields and `context.overrides` are
+ *  merged into the returned agent. Otherwise the declarative fields are resolved
+ *  against the supplied registries and turned into an agent via
+ *  {@link createAgent}.
+ *
+ *  The host controls scope by which registries it passes. Missing dependencies
+ *  fail closed at resolution time, before any provider turn. */
+export declare function resolveAgentDefinition(def: AgentDefinition, context: AgentDefinitionResolutionContext): Promise<Agent> | Agent;

package/dist/agent-definitions.js

@@ -0,0 +1,131 @@
+import { createAgent } from "./agents.js";
+import { resolveActiveSkills, createSkillRegistry } from "./skills.js";
+import { createToolRegistry } from "./tools.js";
+/** Resolve an {@link AgentDefinition} into a runnable {@link Agent}.
+ *
+ *  If the definition provides a `create()` escape hatch, that factory is called
+ *  with a config built from the declarative fields and `context.overrides` are
+ *  merged into the returned agent. Otherwise the declarative fields are resolved
+ *  against the supplied registries and turned into an agent via
+ *  {@link createAgent}.
+ *
+ *  The host controls scope by which registries it passes. Missing dependencies
+ *  fail closed at resolution time, before any provider turn. */
+export function resolveAgentDefinition(def, context) {
+    const baseConfig = buildBaseConfig(def, context);
+    if (def.create) {
+        const agentOrPromise = def.create(baseConfig);
+        return applyAgentOverrides(agentOrPromise, context.overrides);
+    }
+    return createAgent(applyConfigOverrides(baseConfig, context.overrides));
+}
+function buildBaseConfig(def, context) {
+    const model = resolveModel(def.name, def.model, context);
+    const tools = resolveTools(def.tools, context);
+    const skills = resolveSkills(def.skills, tools, context);
+    return {
+        model,
+        ...resolveProviderOptions(model, context),
+        ...(tools !== undefined && { tools }),
+        ...(skills !== undefined && { skills }),
+        ...(def.context !== undefined && { context: resolveContextProviders(def.name, def.context, context) }),
+        ...(def.systemPrompt !== undefined && { systemPrompt: def.systemPrompt }),
+        ...(def.instructions !== undefined && { instructions: def.instructions }),
+        ...(def.loop !== undefined && { loop: def.loop }),
+        ...(def.metadata !== undefined && { metadata: def.metadata }),
+    };
+}
+function resolveModel(agentName, model, context) {
+    if (!model)
+        throw new Error(`Agent "${agentName}" has no model`);
+    if (typeof model !== "string")
+        return model;
+    const slash = model.indexOf("/");
+    if (slash === -1) {
+        throw new Error(`Unknown model: ${model}`);
+    }
+    const provider = model.slice(0, slash);
+    const modelId = model.slice(slash + 1);
+    if (context.registries?.models) {
+        return context.registries.models.resolve(provider, modelId);
+    }
+    return { provider, model: modelId };
+}
+function resolveProviderOptions(model, context) {
+    if (context.providerSource) {
+        return { providerSource: context.providerSource };
+    }
+    if (context.registries?.providers) {
+        return { provider: context.registries.providers.resolve(model) };
+    }
+    return undefined;
+}
+function resolveTools(names, context) {
+    const source = context.tools ?? context.registries?.tools;
+    if (!names) {
+        if (!context.activateAllCapabilities)
+            return undefined;
+        if (!source)
+            return undefined;
+        return asToolRegistry(source);
+    }
+    if (!source)
+        throw new Error("No tool registry in scope");
+    const available = listFromToolSource(source);
+    const resolved = names.map((name) => {
+        const tool = available.find((item) => item.name === name);
+        if (!tool)
+            throw new Error(`Unknown tool: ${name}`);
+        return tool;
+    });
+    return createToolRegistry(resolved);
+}
+function asToolRegistry(source) {
+    if (hasList(source)) {
+        return createToolRegistry(source.list());
+    }
+    return createToolRegistry(source);
+}
+function listFromToolSource(source) {
+    if (hasList(source)) {
+        return source.list();
+    }
+    return source;
+}
+function hasList(value) {
+    return typeof value === "object" && value !== null && "list" in value && typeof value.list === "function";
+}
+function resolveSkills(names, tools, context) {
+    const registry = context.skillsRegistry ??
+        (context.registries?.skills ? createSkillRegistry(context.registries.skills.list()) : undefined);
+    if (!names && !context.activateAllCapabilities)
+        return undefined;
+    if (!registry) {
+        if (!names)
+            return undefined;
+        throw new Error("No skill registry in scope");
+    }
+    const toolList = tools?.list() ?? [];
+    const activeNames = names ?? registry.list().map((skill) => skill.name);
+    return resolveActiveSkills({ registry, names: activeNames, tools: toolList });
+}
+function resolveContextProviders(agentName, names, context) {
+    const registry = context.registries?.contextProviders;
+    if (!registry)
+        throw new Error(`Agent "${agentName}" declares context providers but no registry is in scope`);
+    return names.map((name) => registry.resolve(name));
+}
+function applyConfigOverrides(config, overrides) {
+    if (!overrides)
+        return config;
+    return { ...config, ...overrides };
+}
+function applyAgentOverrides(agent, overrides) {
+    if (!overrides)
+        return agent;
+    if (agent instanceof Promise) {
+        return agent.then((resolved) => createAgent({ ...resolved.config, ...overrides }));
+    }
+    return createAgent({ ...agent.config, ...overrides });
+}
+//# sourceMappingURL=agent-definitions.js.map

package/dist/agent-loops.d.ts

@@ -0,0 +1,14 @@
+import type { AgentLoopOptions, AgentLoopStrategy, ArtifactParser, ArtifactRepairer, ArtifactValidator } from "./contracts.js";
+export declare const singleShotLoop: AgentLoopStrategy;
+export declare function isAgentLoopOptions(value: AgentLoopStrategy | AgentLoopOptions | undefined): value is AgentLoopOptions;
+export declare function generateValidateReviseLoop(opts: {
+    readonly validator: ArtifactValidator<unknown>;
+    readonly parser?: ArtifactParser<unknown>;
+    readonly repairer?: ArtifactRepairer<unknown>;
+    readonly maxRevisions?: number;
+}): AgentLoopStrategy;
+export declare function resolveLoop(options: {
+    loop?: AgentLoopStrategy | AgentLoopOptions;
+}, config: {
+    loop?: AgentLoopStrategy | AgentLoopOptions;
+}): AgentLoopStrategy;

package/dist/agent-loops.js

@@ -0,0 +1,161 @@
+import { inputMessages } from "./input.js";
+function throwIfAborted(signal) {
+    if (signal.aborted)
+        throw signal.reason instanceof Error ? signal.reason : new Error("Agent run aborted");
+}
+function toolResultMessage(result) {
+    return {
+        role: "tool",
+        content: [{ type: "tool_result", toolCallId: result.toolCallId, name: result.name, result: result.value, error: result.error }, ...(result.content ?? [])],
+        metadata: result.metadata,
+    };
+}
+// ponytail: SingleShotLoop extracted bit-for-bit from the former inline turn
+// loop in RuntimeAgentSession.run. The runtime owns provider calls, retry,
+// abort, store, events via LoopContext; this only orchestrates turns. Phase 28
+// fires artifact_* events here as a noop seam — single-shot emits zero.
+export const singleShotLoop = {
+    name: "single-shot",
+    async run(ctx) {
+        let usage;
+        const toolResults = [];
+        let toolRounds = 0;
+        let nextInput = ctx.input;
+        for (let turn = 1;; turn += 1) {
+            throwIfAborted(ctx.signal);
+            ctx.emit({ type: "turn_started", sessionId: ctx.sessionId, runId: ctx.runId, turn });
+            const request = await ctx.assemble(nextInput, toolResults, turn);
+            throwIfAborted(ctx.signal);
+            const { content, calls, messageId, started, usage: turnUsage } = await ctx.generate(request);
+            usage = turnUsage ?? usage;
+            if (turn === 1)
+                ctx.history.push(...ctx.inputMessages);
+            if (started) {
+                const message = { id: messageId, role: "assistant", content };
+                ctx.history.push(message);
+                await ctx.appendMessage(message);
+                ctx.emit({ type: "message_finished", sessionId: ctx.sessionId, runId: ctx.runId, message });
+            }
+            ctx.emit({ type: "turn_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn });
+            if (calls.length === 0 || toolRounds >= ctx.maxToolRounds)
+                break;
+            toolRounds += 1;
+            for (const call of calls) {
+                const result = await ctx.dispatchToolCall(call);
+                toolResults.push(result);
+                await ctx.appendMessage(toolResultMessage(result));
+                throwIfAborted(ctx.signal);
+            }
+            nextInput = [];
+        }
+        return usage;
+    },
+};
+export function isAgentLoopOptions(value) {
+    return typeof value === "object" && value !== null && "strategy" in value;
+}
+function defaultRepairer() {
+    return (_value, failure) => ({
+        role: "user",
+        content: [{ type: "text", text: failure.errors?.map((e) => e.message).join("\n") ?? "invalid artifact" }],
+    });
+}
+// ponytail: GenerateValidateReviseLoop reuses LoopContext primitives only —
+// no provider/retry/store/event re-implementation. T is host-defined, Prism
+// never instantiates it. No tools in artifact revisions (roadmap scope is
+// generate→validate→revise; tool coupling deferred). Phase 28 fires
+// artifact_* events at the marked seams (noop here).
+export function generateValidateReviseLoop(opts) {
+    const max = opts.maxRevisions ?? 3;
+    const repairer = opts.repairer ?? defaultRepairer();
+    return {
+        name: "generate-validate-revise",
+        async run(ctx) {
+            let usage;
+            let nextInput = ctx.input;
+            for (let turn = 1; turn <= max + 1; turn += 1) {
+                throwIfAborted(ctx.signal);
+                ctx.emit({ type: "turn_started", sessionId: ctx.sessionId, runId: ctx.runId, turn });
+                const request = await ctx.assemble(nextInput, undefined, turn);
+                throwIfAborted(ctx.signal);
+                const { content, messageId, started, usage: turnUsage } = await ctx.generate(request);
+                usage = turnUsage ?? usage;
+                if (turn === 1)
+                    ctx.history.push(...ctx.inputMessages);
+                if (started) {
+                    const message = { id: messageId, role: "assistant", content };
+                    ctx.history.push(message);
+                    await ctx.appendMessage(message);
+                    ctx.emit({ type: "message_finished", sessionId: ctx.sessionId, runId: ctx.runId, message });
+                }
+                ctx.emit({ type: "turn_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn });
+                const text = content
+                    .filter((b) => b.type === "text")
+                    .map((b) => b.text)
+                    .join("");
+                const artifactCtx = {
+                    sessionId: ctx.sessionId,
+                    runId: ctx.runId,
+                    turn,
+                    signal: ctx.signal,
+                    metadata: ctx.metadata,
+                };
+                const parsed = opts.parser
+                    ? await opts.parser(text, artifactCtx)
+                    : { ok: true, value: text };
+                // Parse failure ends the loop silently (terminal parse errors stay on `error`).
+                if (!parsed.ok || parsed.value === undefined)
+                    return usage;
+                const attempt = turn;
+                ctx.emit({ type: "artifact_validation_started", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt });
+                const result = await opts.validator(parsed.value, artifactCtx);
+                ctx.emit({ type: "artifact_validation_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
+                if (result.ok) {
+                    ctx.emit({ type: "artifact_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
+                    return usage;
+                }
+                if (turn > max) {
+                    ctx.emit({ type: "artifact_failed", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
+                    return usage;
+                }
+                ctx.emit({ type: "artifact_revision_started", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, failure: result });
+                const repair = await repairer(parsed.value, result, artifactCtx);
+                const repairMessages = inputMessages(repair).map((m) => ({ ...m, id: randomId("msg") }));
+                for (const message of repairMessages) {
+                    ctx.history.push(message);
+                    await ctx.appendMessage(message);
+                }
+                nextInput = repairMessages;
+                continue;
+            }
+            return usage;
+        },
+    };
+}
+// ponytail: resolveLoop returns the loop to run. RunOptions.loop wins over
+// AgentConfig.loop; default is singleShotLoop. generate-validate-revise maps
+// its options to the factory; unknown strategy throws.
+export function resolveLoop(options, config) {
+    const loop = options.loop ?? config.loop;
+    if (!loop)
+        return singleShotLoop;
+    if (isAgentLoopOptions(loop)) {
+        const { strategy } = loop;
+        if (strategy === "single-shot")
+            return singleShotLoop;
+        if (strategy === "generate-validate-revise") {
+            return generateValidateReviseLoop({
+                validator: loop.validator,
+                parser: loop.parser,
+                repairer: loop.repairer,
+                maxRevisions: loop.maxRevisions,
+            });
+        }
+        throw new Error(`Unknown agent loop strategy: ${strategy}`);
+    }
+    return loop;
+}
+function randomId(prefix) {
+    return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
+}
+//# sourceMappingURL=agent-loops.js.map