@owlmeans/llm-common 0.1.18-rc.11 → 0.1.18-rc.12

package/README.md

@@ -20,7 +20,7 @@ extends these; `@owlmeans/llm` implements against them.
 ## Installation
 
 ```bash
-bun add @owlmeans/llm-common
+bun add @owlmeans/llm-common@^0.1.18-rc.11
 ```
 
 ## Usage
@@ -96,7 +96,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.12
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/llm-common",
-  "version": "0.1.18-rc.11",
-  "generatedAt": "2026-09-01T22:50:56.459Z",
+  "version": "0.1.18-rc.12",
+  "generatedAt": "2026-09-04T22:43:25.447Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/llm-common
 
 **Layer:** Core
-**Install:** `"@owlmeans/llm-common": "^0.1.18-rc.11"` in `dependencies`
+**Install:** `"@owlmeans/llm-common": "^0.1.18-rc.12"` in `dependencies`
 
 The contracts half of the LLM stack. **No `@langchain/*` runtime dependency** — importable
 from a browser bundle, a queue worker, or any package that must not pull an inference SDK.
@@ -34,21 +34,43 @@ The dependency direction is one-way: a domain contracts package extends these;
 | `SkillDefinition` | One named block of reusable prompt knowledge. `body` must be a pure constant. |
 | `PromptPolicy` | `{ role?, skills?, cacheSystem?, cacheTtl? }` — carried on `ExecutionState`, merged downward. |
 | `CacheTtl`, `CacheUsage` | `'5m' \| '1h'`; normalized prompt-cache accounting. |
-| `LlmFileProvider`, `FileProviderRef`, `resolveFileProvider` | The minimal read/write file contract prompt plugins work against. Its optional `key` is the provider's stable identity (project root, sandbox id) — the only thing a plugin caching per-project reads can key on, since providers are rebuilt per request. |
+| `LlmFileProvider`, `FileProviderRef`, `resolveFileProvider` | The file contract prompt plugins work against — four members, every path relative to the host's project root. `FileProviderRef` accepts the provider or a thunk returning one; `resolveFileProvider` unwraps whichever form arrived, or `undefined`. |
 | `NullCapture`, `NullKind` | Full diagnostics of a call that returned nothing usable. |
 | `SpectatorArgument`, `SpectatorEntry`, `SpectatorEntryLogged`, `SpectatorEntryMessage` | What an observability sink stores. |
 
+## `LlmFileProvider` — what a host must supply
+
+A consumer's own file helper satisfies it structurally (`interface FileHelper extends
+LlmFileProvider`); implementing it from scratch means all four:
+
+| Member | Contract |
+|---|---|
+| `readFile(path, noThrow?)` | Read a file relative to the root. With `noThrow`, a missing file yields `''`. |
+| `getSourceList(pattern?)` | Glob for files relative to the root. Project-skill discovery in `@owlmeans/agent-skills` is built on it, so a provider that stubs it indexes nothing. |
+| `writeFile(path, content)` | Write relative to the root, creating parent directories. |
+| `deleteFile(path, noThrow?)` | Delete relative to the root. With `noThrow`, a missing file is a no-op. |
+| `key?` | Optional. The provider's stable identity (project root, sandbox id) — the only thing a plugin caching per-project reads can key on, since providers are rebuilt per request. A provider without one is treated as uncacheable. |
+
+Resolving the project root is deliberately NOT part of the contract, and an implementation must not
+narrow an inherited signature — that is what stops a rich helper from satisfying this one.
+
 ## Extension rules
 
 Open types are open **on purpose** — extend, do not fork:
 
 ```typescript
+import type {
+  ExecutionState as LlmExecutionState, LlmPurpose,
+  TaskExecutionState as LlmTaskExecutionState,
+} from '@owlmeans/llm-common'
+
 // Your roles: an enum whose values satisfy the open `ModelRole` string.
 export enum MyRole { Analyst = 'analyst', Coder = 'coder' }
 
-// Your purpose and state: extend, never redeclare.
+// Your purpose and state: extend, never redeclare. Aliasing the imports keeps your own
+// `ExecutionState` the name the rest of your domain uses.
 export interface MyPurpose extends LlmPurpose { agent?: string }
-export interface MyExecutionState extends ExecutionState {
+export interface MyExecutionState extends LlmExecutionState {
   purpose: MyPurpose
   projectId?: string
 }

package/build/files/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/files/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAElE,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,GAC9B,KAAK,eAAe,GAAG,SAAS,KAC/B,eAAe,GAAG,SAAoD,CAAA"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/files/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAElE,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,QACzB,eAAe,GAAG,SAAS,KAC/B,eAAe,GAAG,SAAoD,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/llm-common",
-  "version": "0.1.18-rc.11",
+  "version": "0.1.18-rc.12",
   "license": "MIT",
   "type": "module",
   "scripts": {