@owlmeans/llm-common 0.1.15 → 0.1.16-rc.0

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

@@ -7,7 +7,7 @@ applyTo: "**/*.ts, **/*.tsx"
 # @owlmeans/llm-common
 
 **Layer:** Core
-**Install:** `"@owlmeans/llm-common": "^0.1.15"` in `dependencies`
+**Install:** `"@owlmeans/llm-common": "^0.1.16-rc.0"` in `dependencies`
 
 The contracts half of the LLM stack. **No `@langchain/*` runtime dependency** — importable
 from a browser bundle or a queue worker. Dependency direction is one-way: a domain contracts

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "package": "@owlmeans/llm-common",
-  "version": "0.1.15",
-  "generatedAt": "2026-08-07T17:06:32.908Z",
+  "version": "0.1.16-rc.0",
+  "generatedAt": "2026-08-11T14:02:34.991Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 name: llm-common
-description: How to use @owlmeans/llm-common — runtime-free serializable contracts for LLM inference and execution (ModelProvider, ExecutionEffort/Level, ModelPolicy, ExecutionState, spectator records, NullCapture). Auto-invoked when importing those contracts or extending them for a domain.
+description: How to use @owlmeans/llm-common — runtime-free serializable contracts for LLM inference and execution (ModelProvider, ExecutionEffort/Level, ModelPolicy, PromptPolicy, SkillDefinition, ExecutionState, spectator records, NullCapture, LlmFileProvider). Auto-invoked when importing those contracts or extending them for a domain.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/llm-common
 
 **Layer:** Core
-**Install:** `"@owlmeans/llm-common": "^0.1.15"` in `dependencies`
+**Install:** `"@owlmeans/llm-common": "^0.1.16-rc.0"` 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.
@@ -29,6 +29,11 @@ The dependency direction is one-way: a domain contracts package extends these;
 | `ModelPolicy` | `{ effort, roleOverrides?, modelOverrides? }` — inherited by every refinement. |
 | `ExecutionState` / `TaskExecutionState` | The persistable core (`level`/`purpose`/`policy`, plus `phase`/`completed`/`cursor`/`data`). |
 | `LlmPurpose` | `{ type?, dedication? }` — metadata carried on every model call. |
+| `PromptBlock`, `PROMPT_BLOCK_ORDER`, `DEFAULT_SKILL_ORDER` | The ordered sections of a composed system prompt — the order IS the cache key. |
+| `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. |
 | `NullCapture`, `NullKind` | Full diagnostics of a call that returned nothing usable. |
 | `SpectatorArgument`, `SpectatorEntry`, `SpectatorEntryLogged`, `SpectatorEntryMessage` | What an observability sink stores. |
 

package/build/consts.d.ts

@@ -53,4 +53,33 @@ export declare enum SpectatorContentType {
 }
 /** Default spectator entry kind for consumers that do not classify their calls. */
 export declare const SPECTATOR_GENERAL = "general";
+/**
+ * Ordered sections of a composed system prompt.
+ *
+ * The ordering is not cosmetic — it IS the prompt-cache design. Every provider caches
+ * a prompt by exact PREFIX match, so the sections are laid out most-stable first and a
+ * cache breakpoint is placed at each stability boundary:
+ *
+ * - `Role`     — the base system prompt defining who the model is. Stable per role.
+ * - `Skills`   — the statically declared capabilities, rendered in a deterministic
+ *                order. Stable per helper. A breakpoint closes `Role` + `Skills`.
+ * - `Packages` — capabilities resolved from whatever the request happens to mention.
+ *                Varies per request, so it gets its OWN breakpoint and can never
+ *                invalidate the two blocks above it.
+ * - `Context`  — volatile, caller-supplied system text. Never cached.
+ */
+export declare enum PromptBlock {
+    Role = "role",
+    Skills = "skills",
+    Packages = "packages",
+    Context = "context"
+}
+/**
+ * Emission order of {@link PromptBlock}. Declared explicitly rather than derived from
+ * the enum: the composed prompt must be byte-identical across processes and runtimes,
+ * and enum iteration order is not part of any contract worth betting a cache on.
+ */
+export declare const PROMPT_BLOCK_ORDER: readonly PromptBlock[];
+/** Sort weight of a skill that declares none — see `SkillDefinition.order`. */
+export declare const DEFAULT_SKILL_ORDER = 100;
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,oBAAY,aAAa;IACvB,yFAAyF;IACzF,MAAM,WAAW;IACjB,8BAA8B;IAC9B,SAAS,cAAc;IACvB,yFAAyF;IACzF,UAAU,eAAe;CAC1B;AAED;;;GAGG;AACH,oBAAY,cAAc;IACxB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED;;;;GAIG;AACH,oBAAY,eAAe;IACzB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,IAAI,SAAS;IACb,GAAG,QAAQ;CACZ;AAED;;;;;;;;;GASG;AACH,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,0DAA0D;AAC1D,oBAAY,oBAAoB;IAC9B,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,cAAc;CACvB;AAED,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,YAAY,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,oBAAY,aAAa;IACvB,yFAAyF;IACzF,MAAM,WAAW;IACjB,8BAA8B;IAC9B,SAAS,cAAc;IACvB,yFAAyF;IACzF,UAAU,eAAe;CAC1B;AAED;;;GAGG;AACH,oBAAY,cAAc;IACxB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED;;;;GAIG;AACH,oBAAY,eAAe;IACzB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,IAAI,SAAS;IACb,GAAG,QAAQ;CACZ;AAED;;;;;;;;;GASG;AACH,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,0DAA0D;AAC1D,oBAAY,oBAAoB;IAC9B,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,cAAc;CACvB;AAED,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,YAAY,CAAA;AAE1C;;;;;;;;;;;;;;GAcG;AACH,oBAAY,WAAW;IACrB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,WAAW,EAK3C,CAAA;AAEV,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,MAAM,CAAA"}

package/build/consts.js

@@ -58,4 +58,39 @@ export var SpectatorContentType;
 })(SpectatorContentType || (SpectatorContentType = {}));
 /** Default spectator entry kind for consumers that do not classify their calls. */
 export const SPECTATOR_GENERAL = 'general';
+/**
+ * Ordered sections of a composed system prompt.
+ *
+ * The ordering is not cosmetic — it IS the prompt-cache design. Every provider caches
+ * a prompt by exact PREFIX match, so the sections are laid out most-stable first and a
+ * cache breakpoint is placed at each stability boundary:
+ *
+ * - `Role`     — the base system prompt defining who the model is. Stable per role.
+ * - `Skills`   — the statically declared capabilities, rendered in a deterministic
+ *                order. Stable per helper. A breakpoint closes `Role` + `Skills`.
+ * - `Packages` — capabilities resolved from whatever the request happens to mention.
+ *                Varies per request, so it gets its OWN breakpoint and can never
+ *                invalidate the two blocks above it.
+ * - `Context`  — volatile, caller-supplied system text. Never cached.
+ */
+export var PromptBlock;
+(function (PromptBlock) {
+    PromptBlock["Role"] = "role";
+    PromptBlock["Skills"] = "skills";
+    PromptBlock["Packages"] = "packages";
+    PromptBlock["Context"] = "context";
+})(PromptBlock || (PromptBlock = {}));
+/**
+ * Emission order of {@link PromptBlock}. Declared explicitly rather than derived from
+ * the enum: the composed prompt must be byte-identical across processes and runtimes,
+ * and enum iteration order is not part of any contract worth betting a cache on.
+ */
+export const PROMPT_BLOCK_ORDER = [
+    PromptBlock.Role,
+    PromptBlock.Skills,
+    PromptBlock.Packages,
+    PromptBlock.Context,
+];
+/** Sort weight of a skill that declares none — see `SkillDefinition.order`. */
+export const DEFAULT_SKILL_ORDER = 100;
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,MAAM,CAAN,IAAY,aAOX;AAPD,WAAY,aAAa;IACvB,yFAAyF;IACzF,kCAAiB,CAAA;IACjB,8BAA8B;IAC9B,wCAAuB,CAAA;IACvB,yFAAyF;IACzF,0CAAyB,CAAA;AAC3B,CAAC,EAPW,aAAa,KAAb,aAAa,QAOxB;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,qCAAmB,CAAA;IACnB,+BAAa,CAAA;IACb,mCAAiB,CAAA;AACnB,CAAC,EAJW,cAAc,KAAd,cAAc,QAIzB;AAED;;;;GAIG;AACH,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,sCAAmB,CAAA;IACnB,wCAAqB,CAAA;IACrB,gCAAa,CAAA;IACb,8BAAW,CAAA;AACb,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B;AAED;;;;;;;;;GASG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,mCAAiB,CAAA;IACjB,+BAAa,CAAA;AACf,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAED,0DAA0D;AAC1D,MAAM,CAAN,IAAY,oBAIX;AAJD,WAAY,oBAAoB;IAC9B,qCAAa,CAAA;IACb,qCAAa,CAAA;IACb,8CAAsB,CAAA;AACxB,CAAC,EAJW,oBAAoB,KAApB,oBAAoB,QAI/B;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,MAAM,CAAN,IAAY,aAOX;AAPD,WAAY,aAAa;IACvB,yFAAyF;IACzF,kCAAiB,CAAA;IACjB,8BAA8B;IAC9B,wCAAuB,CAAA;IACvB,yFAAyF;IACzF,0CAAyB,CAAA;AAC3B,CAAC,EAPW,aAAa,KAAb,aAAa,QAOxB;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,cAIX;AAJD,WAAY,cAAc;IACxB,qCAAmB,CAAA;IACnB,+BAAa,CAAA;IACb,mCAAiB,CAAA;AACnB,CAAC,EAJW,cAAc,KAAd,cAAc,QAIzB;AAED;;;;GAIG;AACH,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,sCAAmB,CAAA;IACnB,wCAAqB,CAAA;IACrB,gCAAa,CAAA;IACb,8BAAW,CAAA;AACb,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B;AAED;;;;;;;;;GASG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,mCAAiB,CAAA;IACjB,+BAAa,CAAA;AACf,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAED,0DAA0D;AAC1D,MAAM,CAAN,IAAY,oBAIX;AAJD,WAAY,oBAAoB;IAC9B,qCAAa,CAAA;IACb,qCAAa,CAAA;IACb,8CAAsB,CAAA;AACxB,CAAC,EAJW,oBAAoB,KAApB,oBAAoB,QAI/B;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAA;AAE1C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,4BAAa,CAAA;IACb,gCAAiB,CAAA;IACjB,oCAAqB,CAAA;IACrB,kCAAmB,CAAA;AACrB,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,WAAW,CAAC,IAAI;IAChB,WAAW,CAAC,MAAM;IAClB,WAAW,CAAC,QAAQ;IACpB,WAAW,CAAC,OAAO;CACX,CAAA;AAEV,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA"}

package/build/files/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The slice of a host application's file access that the LLM layer is allowed to see.
+ *
+ * A consumer almost always owns a much richer file helper (project metadata, source
+ * classification, remote/sandbox transports). This contract is deliberately the smallest
+ * useful subset, so a prompt plugin can read a package manifest or write a scratch file
+ * without the common layer learning anything about the consumer's project model. A
+ * consumer's own helper satisfies it structurally — declare
+ * `interface FileHelper extends LlmFileProvider` and nothing else changes.
+ *
+ * It lives in `llm-common` (not `llm`) because it is a contract, not a runtime: the
+ * package stays dependency-free and browser-safe.
+ *
+ * Every path is relative to the host's project root. Resolving that root is deliberately
+ * NOT part of the contract — a consumer with a multi-root layout types its own accessor
+ * with its own enum, and narrowing an inherited signature is exactly the kind of change
+ * that stops a rich helper from satisfying this one.
+ */
+export interface LlmFileProvider {
+    /** Read a file relative to the root. With `noThrow`, a missing file yields `''`. */
+    readFile: (filePath: string, noThrow?: boolean) => Promise<string>;
+    /** Glob for files relative to the root. */
+    getSourceList: (pattern?: string) => Promise<string[]>;
+    /** Write a file relative to the root, creating parent directories as needed. */
+    writeFile: (filePath: string, content: string) => Promise<void>;
+    /** Delete a file relative to the root. With `noThrow`, a missing file is a no-op. */
+    deleteFile: (filePath: string, noThrow?: boolean) => Promise<void>;
+}
+/**
+ * A provider, or a resolver for one.
+ *
+ * Collaborators in this layer are usually late-bound functions so a service can be
+ * swapped or cloned — but a file helper is just as often a plain object a consumer
+ * already holds. Accepting both spares every call site a wrapper.
+ */
+export type FileProviderRef = LlmFileProvider | (() => LlmFileProvider);
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/files/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAElE,2CAA2C;IAC3C,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAEtD,gFAAgF;IAChF,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/D,qFAAqF;IACrF,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACnE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,CAAC,MAAM,eAAe,CAAC,CAAA"}

package/build/files/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/files/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/files/types.ts"],"names":[],"mappings":""}

package/build/files/utils.d.ts

@@ -0,0 +1,4 @@
+import type { FileProviderRef, LlmFileProvider } from './types.js';
+/** Unwrap a {@link FileProviderRef} whichever form it arrived in. */
+export declare const resolveFileProvider: (ref: FileProviderRef | undefined) => LlmFileProvider | undefined;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +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"}

package/build/files/utils.js

@@ -0,0 +1,3 @@
+/** Unwrap a {@link FileProviderRef} whichever form it arrived in. */
+export const resolveFileProvider = (ref) => typeof ref === 'function' ? ref() : ref;
+//# sourceMappingURL=utils.js.map

package/build/files/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/files/utils.ts"],"names":[],"mappings":"AAEA,qEAAqE;AACrE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,GAAgC,EACH,EAAE,CAAC,OAAO,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAA"}

package/build/index.d.ts

@@ -1,4 +1,6 @@
 export * from './consts.js';
 export type * from './types.js';
 export type * from './spectator/types.js';
+export type * from './files/types.js';
+export * from './files/utils.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,sBAAsB,CAAA;AACzC,mBAAmB,kBAAkB,CAAA;AACrC,cAAc,kBAAkB,CAAA"}

package/build/index.js

@@ -1,2 +1,3 @@
 export * from './consts.js';
+export * from './files/utils.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAI3B,cAAc,kBAAkB,CAAA"}

package/build/types.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionEffort, ExecutionLevel } from './consts.js';
+import type { ExecutionEffort, ExecutionLevel, PromptBlock } from './consts.js';
 /**
  * Free-form observability metadata attached to every model call — forwarded to the
  * inference provider as run metadata and recorded on every spectator entry. Kept
@@ -45,6 +45,68 @@ export interface ModelPolicy {
     /** "Pin a role to a specific model/config" — alias or partial config override. */
     modelOverrides?: Partial<Record<ModelRole, ModelConfigOverride>>;
 }
+/**
+ * Lifetime of a provider-side prompt cache entry. `'1h'` costs roughly twice as much to
+ * write as `'5m'`, so it only pays off from the third read onward — use it for a system
+ * prefix that survives a long run, not for a one-shot call.
+ */
+export type CacheTtl = '5m' | '1h';
+/**
+ * One named, reusable chunk of system-prompt knowledge — a capability the model is told
+ * it has. Registered once (by the package that owns the knowledge or by the final app)
+ * and referenced by `alias` from any execution level.
+ *
+ * `body` must be a PURE CONSTANT: no timestamps, no absolute paths, no interpolated
+ * request data. Every skill lands in the cached region of the system prompt, and one
+ * varying byte invalidates the whole prefix for every call that shares it.
+ */
+export interface SkillDefinition {
+    /** Stable slug — how executions reference the skill. */
+    alias: string;
+    /** Rendered as the skill's heading; falls back to `alias`. */
+    title?: string;
+    /** Not sent to the model — documentation for whoever wires the registry. */
+    description?: string;
+    /** The prompt text itself. */
+    body: string;
+    /** Sort weight; ties broken by `alias`. Defaults to `DEFAULT_SKILL_ORDER`. */
+    order?: number;
+    /** Which block to render into. Defaults to `PromptBlock.Skills`. */
+    block?: PromptBlock;
+    /** Aliases pulled in transitively when this skill is enabled. */
+    requires?: string[];
+}
+/**
+ * The "flexible execution parameters" that shape a system prompt. Carried on
+ * {@link ExecutionState}, so it is JSON-safe, survives a checkpoint/restore round trip,
+ * and accumulates down the execution chain: a task adds skills on top of the project,
+ * a helper on top of the task. `role` is overridden by the deepest level that sets it;
+ * `skills` are unioned.
+ */
+export interface PromptPolicy {
+    /** Base system prompt — becomes the first block. */
+    role?: string;
+    /** Skill aliases enabled at this level. */
+    skills?: string[];
+    /** Mark the composed system prompt cacheable. Defaults to `true`. */
+    cacheSystem?: boolean;
+    /** Cache lifetime for the system prefix. Defaults to `'5m'`. */
+    cacheTtl?: CacheTtl;
+}
+/**
+ * Prompt-cache accounting for a single call, normalized across providers. The only
+ * reliable way to tell whether caching actually works: if `read` stays 0 across repeated
+ * calls with the same prefix, something is silently invalidating it.
+ */
+export interface CacheUsage {
+    /** Tokens served from cache (~0.1x price). */
+    read: number;
+    /** Tokens written to cache (~1.25x price at 5m TTL, ~2x at 1h). */
+    creation: number;
+    /** Tokens processed at full price. */
+    input: number;
+    output: number;
+}
 /**
  * Serializable execution state — no functions, no file access, no model instances.
  * The runtime `Execution` (`@owlmeans/llm`) = this state + attached collaborators.
@@ -55,6 +117,8 @@ export interface ExecutionState {
     level: ExecutionLevel;
     purpose: LlmPurpose;
     policy: ModelPolicy;
+    /** Role + skills for this level; merged downward by `ExecutionService`. */
+    prompt?: PromptPolicy;
 }
 /** Resumable state of a task-level execution. */
 export interface TaskExecutionState extends ExecutionState {

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/llm-common",
-  "version": "0.1.15",
+  "version": "0.1.16-rc.0",
   "license": "MIT",
   "type": "module",
   "scripts": {

package/src/consts.ts

@@ -59,3 +59,40 @@ export enum SpectatorContentType {
 
 /** Default spectator entry kind for consumers that do not classify their calls. */
 export const SPECTATOR_GENERAL = 'general'
+
+/**
+ * Ordered sections of a composed system prompt.
+ *
+ * The ordering is not cosmetic — it IS the prompt-cache design. Every provider caches
+ * a prompt by exact PREFIX match, so the sections are laid out most-stable first and a
+ * cache breakpoint is placed at each stability boundary:
+ *
+ * - `Role`     — the base system prompt defining who the model is. Stable per role.
+ * - `Skills`   — the statically declared capabilities, rendered in a deterministic
+ *                order. Stable per helper. A breakpoint closes `Role` + `Skills`.
+ * - `Packages` — capabilities resolved from whatever the request happens to mention.
+ *                Varies per request, so it gets its OWN breakpoint and can never
+ *                invalidate the two blocks above it.
+ * - `Context`  — volatile, caller-supplied system text. Never cached.
+ */
+export enum PromptBlock {
+  Role = 'role',
+  Skills = 'skills',
+  Packages = 'packages',
+  Context = 'context',
+}
+
+/**
+ * Emission order of {@link PromptBlock}. Declared explicitly rather than derived from
+ * the enum: the composed prompt must be byte-identical across processes and runtimes,
+ * and enum iteration order is not part of any contract worth betting a cache on.
+ */
+export const PROMPT_BLOCK_ORDER: readonly PromptBlock[] = [
+  PromptBlock.Role,
+  PromptBlock.Skills,
+  PromptBlock.Packages,
+  PromptBlock.Context,
+] as const
+
+/** Sort weight of a skill that declares none — see `SkillDefinition.order`. */
+export const DEFAULT_SKILL_ORDER = 100

package/src/files/types.ts

@@ -0,0 +1,40 @@
+/**
+ * The slice of a host application's file access that the LLM layer is allowed to see.
+ *
+ * A consumer almost always owns a much richer file helper (project metadata, source
+ * classification, remote/sandbox transports). This contract is deliberately the smallest
+ * useful subset, so a prompt plugin can read a package manifest or write a scratch file
+ * without the common layer learning anything about the consumer's project model. A
+ * consumer's own helper satisfies it structurally — declare
+ * `interface FileHelper extends LlmFileProvider` and nothing else changes.
+ *
+ * It lives in `llm-common` (not `llm`) because it is a contract, not a runtime: the
+ * package stays dependency-free and browser-safe.
+ *
+ * Every path is relative to the host's project root. Resolving that root is deliberately
+ * NOT part of the contract — a consumer with a multi-root layout types its own accessor
+ * with its own enum, and narrowing an inherited signature is exactly the kind of change
+ * that stops a rich helper from satisfying this one.
+ */
+export interface LlmFileProvider {
+  /** Read a file relative to the root. With `noThrow`, a missing file yields `''`. */
+  readFile: (filePath: string, noThrow?: boolean) => Promise<string>
+
+  /** Glob for files relative to the root. */
+  getSourceList: (pattern?: string) => Promise<string[]>
+
+  /** Write a file relative to the root, creating parent directories as needed. */
+  writeFile: (filePath: string, content: string) => Promise<void>
+
+  /** Delete a file relative to the root. With `noThrow`, a missing file is a no-op. */
+  deleteFile: (filePath: string, noThrow?: boolean) => Promise<void>
+}
+
+/**
+ * A provider, or a resolver for one.
+ *
+ * Collaborators in this layer are usually late-bound functions so a service can be
+ * swapped or cloned — but a file helper is just as often a plain object a consumer
+ * already holds. Accepting both spares every call site a wrapper.
+ */
+export type FileProviderRef = LlmFileProvider | (() => LlmFileProvider)

package/src/files/utils.ts

@@ -0,0 +1,6 @@
+import type { FileProviderRef, LlmFileProvider } from './types.js'
+
+/** Unwrap a {@link FileProviderRef} whichever form it arrived in. */
+export const resolveFileProvider = (
+  ref: FileProviderRef | undefined,
+): LlmFileProvider | undefined => typeof ref === 'function' ? ref() : ref

package/src/index.ts

@@ -2,3 +2,5 @@
 export * from './consts.js'
 export type * from './types.js'
 export type * from './spectator/types.js'
+export type * from './files/types.js'
+export * from './files/utils.js'

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { ExecutionEffort, ExecutionLevel } from './consts.js'
+import type { ExecutionEffort, ExecutionLevel, PromptBlock } from './consts.js'
 
 /**
  * Free-form observability metadata attached to every model call — forwarded to the
@@ -51,6 +51,72 @@ export interface ModelPolicy {
   modelOverrides?: Partial<Record<ModelRole, ModelConfigOverride>>
 }
 
+/**
+ * Lifetime of a provider-side prompt cache entry. `'1h'` costs roughly twice as much to
+ * write as `'5m'`, so it only pays off from the third read onward — use it for a system
+ * prefix that survives a long run, not for a one-shot call.
+ */
+export type CacheTtl = '5m' | '1h'
+
+/**
+ * One named, reusable chunk of system-prompt knowledge — a capability the model is told
+ * it has. Registered once (by the package that owns the knowledge or by the final app)
+ * and referenced by `alias` from any execution level.
+ *
+ * `body` must be a PURE CONSTANT: no timestamps, no absolute paths, no interpolated
+ * request data. Every skill lands in the cached region of the system prompt, and one
+ * varying byte invalidates the whole prefix for every call that shares it.
+ */
+export interface SkillDefinition {
+  /** Stable slug — how executions reference the skill. */
+  alias: string
+  /** Rendered as the skill's heading; falls back to `alias`. */
+  title?: string
+  /** Not sent to the model — documentation for whoever wires the registry. */
+  description?: string
+  /** The prompt text itself. */
+  body: string
+  /** Sort weight; ties broken by `alias`. Defaults to `DEFAULT_SKILL_ORDER`. */
+  order?: number
+  /** Which block to render into. Defaults to `PromptBlock.Skills`. */
+  block?: PromptBlock
+  /** Aliases pulled in transitively when this skill is enabled. */
+  requires?: string[]
+}
+
+/**
+ * The "flexible execution parameters" that shape a system prompt. Carried on
+ * {@link ExecutionState}, so it is JSON-safe, survives a checkpoint/restore round trip,
+ * and accumulates down the execution chain: a task adds skills on top of the project,
+ * a helper on top of the task. `role` is overridden by the deepest level that sets it;
+ * `skills` are unioned.
+ */
+export interface PromptPolicy {
+  /** Base system prompt — becomes the first block. */
+  role?: string
+  /** Skill aliases enabled at this level. */
+  skills?: string[]
+  /** Mark the composed system prompt cacheable. Defaults to `true`. */
+  cacheSystem?: boolean
+  /** Cache lifetime for the system prefix. Defaults to `'5m'`. */
+  cacheTtl?: CacheTtl
+}
+
+/**
+ * Prompt-cache accounting for a single call, normalized across providers. The only
+ * reliable way to tell whether caching actually works: if `read` stays 0 across repeated
+ * calls with the same prefix, something is silently invalidating it.
+ */
+export interface CacheUsage {
+  /** Tokens served from cache (~0.1x price). */
+  read: number
+  /** Tokens written to cache (~1.25x price at 5m TTL, ~2x at 1h). */
+  creation: number
+  /** Tokens processed at full price. */
+  input: number
+  output: number
+}
+
 /**
  * Serializable execution state — no functions, no file access, no model instances.
  * The runtime `Execution` (`@owlmeans/llm`) = this state + attached collaborators.
@@ -61,6 +127,8 @@ export interface ExecutionState {
   level: ExecutionLevel
   purpose: LlmPurpose
   policy: ModelPolicy
+  /** Role + skills for this level; merged downward by `ExecutionService`. */
+  prompt?: PromptPolicy
 }
 
 /** Resumable state of a task-level execution. */