@owlmeans/llm 0.1.16-rc.0 → 0.1.16

package/README.md

@@ -178,10 +178,9 @@ root `.env`. With none set they self-skip with a printed reason — never a fail
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
 
-This package ships embedded Claude Code skills and GitHub Copilot instructions under
-`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
-agent-skills installer to place them into your project's native locations
-(`.claude/skills/` and `.github/instructions/`):
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
 
 ```sh
 npx @owlmeans/agent-skills

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "package": "@owlmeans/llm",
-  "version": "0.1.16-rc.0",
-  "generatedAt": "2026-08-11T14:02:34.979Z",
+  "version": "0.1.16",
+  "generatedAt": "2026-08-14T10:14:48.851Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -10,28 +10,14 @@
       "name": "llm",
       "category": "package-specific",
       "file": "skills/llm/SKILL.md",
-      "canonicalPath": ".claude/skills/llm/SKILL.md"
+      "canonicalPath": ".agents/skills/llm/SKILL.md"
     },
     {
       "kind": "skill",
       "name": "llm-prompt-caching",
       "category": "multi-package",
       "file": "skills/llm-prompt-caching/SKILL.md",
-      "canonicalPath": ".claude/skills/llm-prompt-caching/SKILL.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "llm",
-      "category": "package-specific",
-      "file": "instructions/llm.instructions.md",
-      "canonicalPath": ".github/instructions/llm.instructions.md"
-    },
-    {
-      "kind": "instruction",
-      "name": "llm-prompt-caching",
-      "category": "multi-package",
-      "file": "instructions/llm-prompt-caching.instructions.md",
-      "canonicalPath": ".github/instructions/llm-prompt-caching.instructions.md"
+      "canonicalPath": ".agents/skills/llm-prompt-caching/SKILL.md"
     }
   ]
 }

package/agent-meta/skills/llm/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/llm
 
 **Layer:** Core
-**Install:** `"@owlmeans/llm": "^0.1.16-rc.0"` in `dependencies` (plus the `@langchain/*` peers)
+**Install:** `"@owlmeans/llm": "^0.1.16"` in `dependencies` (plus the `@langchain/*` peers)
 
 The inference runtime. Everything provider-specific is a **plugin**; the model itself only
 owns the provider-independent parts (streaming discipline, retries, validation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/llm",
-  "version": "0.1.16-rc.0",
+  "version": "0.1.16",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -47,7 +47,7 @@
     "@langchain/core": "^1.1.39",
     "@langchain/openai": "^1.4.4",
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test": "^0.1.16-rc.0",
+    "@owlmeans/test": "^0.1.16",
     "@types/bun": "^1.3.14",
     "@types/node": "^26.1.0",
     "nodemon": "^3.1.14",
@@ -55,10 +55,10 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
-    "@owlmeans/basic-ids": "^0.1.16-rc.0",
-    "@owlmeans/context": "^0.1.16-rc.0",
-    "@owlmeans/error": "^0.1.16-rc.0",
-    "@owlmeans/llm-common": "^0.1.16-rc.0",
+    "@owlmeans/basic-ids": "^0.1.16",
+    "@owlmeans/context": "^0.1.16",
+    "@owlmeans/error": "^0.1.16",
+    "@owlmeans/llm-common": "^0.1.16",
     "ajv": "^8.17.1"
   },
   "publishConfig": {

package/agent-meta/instructions/llm-prompt-caching.instructions.md

@@ -1,100 +0,0 @@
----
-description: "How the OwlMeans LLM layer composes a system prompt from a role and skills, and the prompt-cache rules that layout exists to satisfy — block order, breakpoint budget, determinism invariants, and the provider facts behind them. Consult before changing prompt composition, skills, a prompt plugin, or anything a request sends before its first per-call byte."
-applyTo: "**/*.ts, **/*.tsx"
----
-<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
-
-# Prompt composition and caching
-
-**Layer:** Core · **Packages:** `@owlmeans/llm` (`./prompt`), `@owlmeans/llm-common`, `@owlmeans/agent-skills` (`./llm`)
-
-A prompt cache is an **exact prefix match**. Everything below follows from that: the bytes
-every call shares must come first, physically, and must be identical down to the
-whitespace.
-
-## The block layout
-
-`PromptService.compose()` renders four ordered blocks into one system message:
-
-| # | Block | Contributed by | Changes | Breakpoint |
-|---|-------|----------------|---------|-----------|
-| 0 | `Role` | `rolePlugin` ← `PromptPolicy.role` | per role | — |
-| 1 | `Skills` | `skillsPlugin` ← registry + `inline` | per helper | ✅ closes role+skills |
-| 2 | `Packages` | app plugins | per request | ✅ its own |
-| 3 | `Context` | `contextPlugin` ← `context`, `callSkills` | per call | **never** (unless sole block) |
-
-A caller's own leading `SystemMessage` is detached by `makeLlmModel` and re-emitted as
-`Context`, so a helper that has not adopted `prompt: { role, skills }` keeps working.
-
-## Rules
-
-- **Order is the cache key.** `PROMPT_BLOCK_ORDER` is explicit; skills sort by
-  `(order, alias)` with a code-unit comparison (never `localeCompare`); detected packages
-  sort alphabetically.
-- **Skill bodies are pure constants** — no timestamps, paths, or interpolated request data.
-- **A volatile block is never marked.** The trailing `Context` block changes every
-  call: a breakpoint there would pay a cache WRITE on every request and never read
-  one back. It is marked ONLY when it is the entire prompt (a caller that has not
-  adopted role/skills), because there it IS the stable part. Its parts are merged
-  into one chunk for the same reason — nothing downstream needs them separable.
-- **Volatile content goes last.** Per-call skills use `LlmCallOptions.skills` (→ `Context`),
-  never the execution's `skills` (→ the cached `Skills` block).
-- **Budget: 4 breakpoints per request.** The system prompt spends at most 3.
-- **The last message is never cached** — it is the per-call payload.
-- **Markers are placed in-place, on the caller's objects.** A caller that carries its
-  message array across calls (a coder's growing conversation, a fix loop) hands them back
-  still marked, and they accumulate. `prepare()` therefore calls `stripCacheMarkers()`
-  first, so the per-request count depends on THIS call alone. Anything that places a
-  marker outside that pipeline must do the same.
-- **A prefix below `MIN_CACHEABLE_TOKENS` is left unmarked** (`ModelConfig.cacheMinTokens`
-  overrides per alias).
-- **A prompt plugin MUST be deterministic**, and registering the same alias twice replaces
-  rather than appends.
-
-## Verifying it works
-> **The smoke test cannot catch a caching bug.** It makes no model calls. A breakpoint-budget
-> or marker-accumulation fault only appears under a real multi-call agent run — and it
-> surfaces as a `400`, which the retry loop can bury for minutes. Check the agent's own pod
-> logs for `Prompt cache [` lines and a non-zero `read`.
-
-
-`readCacheUsage(message)` from `@owlmeans/llm/helpers` reads
-`usage_metadata.input_token_details`. If `read` stays 0 across repeated calls that share a
-prefix, something is invalidating it — diff `PromptResult.blocks` between two calls.
-
-## Package skills in a prompt (`@owlmeans/agent-skills/llm`)
-
-`owlmeansPackagesPlugin(options)` notices which `@owlmeans/*` packages a request mentions
-and loads their published skills into the `Packages` block. Everything a package documents
-is loaded — there is no relevance filtering, by design.
-
-Resolution order per package: the host's `LlmFileProvider` (the only path that sees a
-sandbox or remote workspace) → an installed copy under `node_modules` → the canonical
-repository over HTTPS. Every failure is a miss, never a throw. Results, including misses,
-are cached per plugin instance.
-
-```typescript
-ctx.prompts().use(owlmeansPackagesPlugin({
-  files: () => ctx.files(),      // tried first
-  exclude: ['@owlmeans/llm'],    // already covered by the static Skills block
-  fetch: false,                  // air-gapped: skip the repository fallback
-}))
-```
-
-The manifest deliberately carries no git ref — version-matching comes from shipping the
-copy inside the tarball, so for a package that is NOT installed the ref is a plugin option
-(`ref`, default `main`).
-
-## Provider facts these rules encode
-
-**Anthropic** ([docs](https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md)):
-render order `tools` → `system` → `messages`; max 4 breakpoints; minimum cacheable prefix is
-model-dependent and **not monotonic** (512 newest / 1024 most / 4096 on Opus 4.6-4.5 and
-Haiku 4.5); writes cost ~1.25× at 5m TTL and ~2× at 1h; a `system` change invalidates
-system + messages but not `tools`.
-
-**OpenAI** ([docs](https://developers.openai.com/api/docs/guides/prompt-caching)): automatic
-from 1024 tokens; routing hashes roughly the first 256 tokens and mixes in
-`prompt_cache_key`. The `openai` plugin sets it from the config alias; the `compatible`
-plugin does not, because aggregators with `provider.require_parameters` can drop providers
-over an unknown field.

package/agent-meta/instructions/llm.instructions.md

@@ -1,76 +0,0 @@
----
-description: "How to use @owlmeans/llm — the LLM inference runtime: four-method model, provider plugins, model factory service, the policy-driven execution abstraction, and the prompt/skill composition service."
-applyTo: "**/*.ts, **/*.tsx"
----
-<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
-
-# @owlmeans/llm
-
-**Layer:** Core
-**Install:** `"@owlmeans/llm": "^0.1.16-rc.0"` in `dependencies` (plus the `@langchain/*` peers)
-
-The inference runtime. Everything provider-specific is a **plugin**; the model owns only the
-provider-independent parts. Serializable contracts live in `@owlmeans/llm-common`.
-
-## Key Exports
-
-| Export | Description |
-|--------|-------------|
-| `makeLlmModel(options, spectator)` | `ask` / `talk` / `invoke` / `request`. |
-| `makeLlmService` · `appendLlmService` · `llmServiceApi` | Model factory/registry; `llmServiceApi` composes into your own service. |
-| `makeExecutionService` · `appendExecutionService` · `executionServiceApi` | Frozen 3-level executions, policy resolution, snapshot/restore/checkpoint. |
-| `makePromptService` · `appendPromptService` · `promptServiceApi` | Skill registry + composition plugin chain (`@owlmeans/llm/prompt`). |
-| `renderSkill`, `sortSkills`, `compareAlias`, `readCacheUsage` | Deterministic rendering and prompt-cache accounting. |
-| `plugins`, `registerLlmPlugin`, `resolvePlugin`, `pluginOf`, `pluginFor` | Provider-plugin registry (`@owlmeans/llm/plugins`). |
-| `anthropicPlugin`, `openAiPlugin`, `compatiblePlugin`, `openAiFamily` | Built-ins; spread `openAiFamily` into a new OpenAI-compatible plugin. |
-| `withRetry`, `registerFatalError`, `spectate`, `normalizeInput`, `parseJsonContent`, `coerceToSchema` | Helpers (`@owlmeans/llm/helpers`). |
-| `LlmModelError` (retryable), `LlmMissconfiguredError`, `LlmPluginError`, `LlmRetryExceededError` | `ResilientError` family. |
-
-## Rules
-
-- `src/helpers/` is what consumers may use; `src/utils/` is library-private and never
-  exported. Place a new function on the right side rather than exporting a util for a test.
-- Never branch on the provider (`instanceof ChatAnthropic`, `provider === …`) in the model or
-  the service — put it on the `LlmPlugin` (`build` / `owns` / `family` / `refine` /
-  `structuredMode` / `toolChoice` / `responseFormat` / `patchSystem` / `patchCache` / `isFatal`).
-- Plugin registration order is load-bearing: `pluginFor` returns the first `owns` match, and
-  `compatible` precedes `openai` so an unlabelled `ChatOpenAI` gets the conservative
-  tool-calling behaviour.
-- Never `instanceof` an error from a provider SDK: `@langchain/*` bundle their own
-  nested copies, so the check silently fails and a fatal `400` gets retried eight
-  times. Match `status === 400` instead.
-- `@langchain/*` are **peer** dependencies — model instances cross the package boundary and
-  two installed copies are nominally distinct types. Pin one copy in the consumer.
-- Extend the execution generically: your own `ExecutionShape`, your collaborator fields in
-  `collaboratorKeys`. Do not narrow inherited method signatures (contravariance error).
-- Never hand-build a persona as a `SystemMessage` in a helper. Declare it as
-  `PromptPolicy.role` plus registered skills and let the prompt service compose it —
-  otherwise the knowledge duplicates and the cacheable prefix stops being stable. Skills
-  accumulate project → task → helper; the deepest declared role wins (`mergePrompt`).
-  Block order, breakpoint budget and the provider facts: `llm-prompt-caching`.
-
-## Usage
-
-```typescript
-import { makeLlmModel, makeLlmService } from '@owlmeans/llm'
-
-const llm = makeLlmService({ models: () => configs })
-const model = makeLlmModel(
-  { model: llm.getModel('analyst'), purpose: { type: 'analysis' } }, spectator
-)
-const spec = await model.invoke('Describe the app', SpecSchema, { action: 'spec' })
-```
-
-Execution resolution precedence: **roleOverride → modelOverride → effort tier →
-`LlmService.getModel`**.
-
-## Already handled — do not reimplement
-
-Idle stream deadline · duplicate-final-chunk dedup · output-budget escalation ·
-reasoning-cap shrink · same-family fallback model · schema coercion · JSON salvage from
-prose · `NullCapture` diagnostics · fatal-error short-circuit.
-
-## Depends On
-
-- `@owlmeans/llm-common`, `@owlmeans/context`, `@owlmeans/error`, `@owlmeans/basic-ids`, `ajv`
-- peer `@langchain/core`, `@langchain/openai`, `@langchain/anthropic`