@gullabs/any-llm 0.8.0 → 0.8.2

package/dist/index.cjs

@@ -6,7 +6,7 @@ var google = require('@gullabs/google');
 // src/index.ts
 
 // package.json
-var version = "0.8.0";
+var version = "0.8.2";
 
 // src/index.ts
 var ANY_LLM_VERSION = version;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../package.json","../src/index.ts"],"names":[],"mappings":";;;;;;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;ACcN,IAAM,eAAA,GAA0B","file":"index.cjs","sourcesContent":["{\n  \"name\": \"@gullabs/any-llm\",\n  \"version\": \"0.8.0\",\n  \"description\": \"Batteries-included any-llm client for Gemini: engine, adapter, and Google SDK in one install.\",\n  \"type\": \"module\",\n  \"license\": \"Apache-2.0\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/gullabs/any-llm.git\",\n    \"directory\": \"packages/any-llm\"\n  },\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\",\n      \"require\": \"./dist/index.cjs\"\n    }\n  },\n  \"files\": [\n    \"dist\",\n    \"skills\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsup\"\n  },\n  \"dependencies\": {\n    \"@google/genai\": \"^1.45.0 || ^2\",\n    \"@gullabs/core\": \"workspace:*\",\n    \"@gullabs/google\": \"workspace:*\"\n  },\n  \"engines\": {\n    \"node\": \">=20.9.0\"\n  },\n  \"sideEffects\": false,\n  \"keywords\": [\n    \"llm\",\n    \"gemini\",\n    \"google-genai\",\n    \"ai\",\n    \"tokens\",\n    \"cost\",\n    \"usage\",\n    \"observability\",\n    \"typescript\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"homepage\": \"https://github.com/gullabs/any-llm/tree/main/packages/any-llm#readme\",\n  \"bugs\": \"https://github.com/gullabs/any-llm/issues\"\n}\n","/**\n * @gullabs/any-llm — batteries-included public entrypoint.\n *\n * This package is the default client install path. It re-exports the core\n * engine and Gemini adapter while depending on the Gemini SDK for a one-package\n * setup.\n *\n * @module\n */\n\nexport * from '@gullabs/core'\nexport * from '@gullabs/google'\n\nimport { version } from '../package.json'\n\n/** Library version, sourced from package.json at build time. */\nexport const ANY_LLM_VERSION: string = version\n"]}
+{"version":3,"sources":["../package.json","../src/index.ts"],"names":[],"mappings":";;;;;;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;ACcN,IAAM,eAAA,GAA0B","file":"index.cjs","sourcesContent":["{\n  \"name\": \"@gullabs/any-llm\",\n  \"version\": \"0.8.2\",\n  \"description\": \"Batteries-included any-llm client for Gemini: engine, adapter, and Google SDK in one install.\",\n  \"type\": \"module\",\n  \"license\": \"Apache-2.0\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/gullabs/any-llm.git\",\n    \"directory\": \"packages/any-llm\"\n  },\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\",\n      \"require\": \"./dist/index.cjs\"\n    }\n  },\n  \"files\": [\n    \"dist\",\n    \"skills\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsup\"\n  },\n  \"dependencies\": {\n    \"@google/genai\": \"^1.45.0 || ^2\",\n    \"@gullabs/core\": \"workspace:*\",\n    \"@gullabs/google\": \"workspace:*\"\n  },\n  \"engines\": {\n    \"node\": \">=20.9.0\"\n  },\n  \"sideEffects\": false,\n  \"keywords\": [\n    \"llm\",\n    \"gemini\",\n    \"google-genai\",\n    \"ai\",\n    \"tokens\",\n    \"cost\",\n    \"usage\",\n    \"observability\",\n    \"typescript\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"homepage\": \"https://github.com/gullabs/any-llm/tree/main/packages/any-llm#readme\",\n  \"bugs\": \"https://github.com/gullabs/any-llm/issues\"\n}\n","/**\n * @gullabs/any-llm — batteries-included public entrypoint.\n *\n * This package is the default client install path. It re-exports the core\n * engine and Gemini adapter while depending on the Gemini SDK for a one-package\n * setup.\n *\n * @module\n */\n\nexport * from '@gullabs/core'\nexport * from '@gullabs/google'\n\nimport { version } from '../package.json'\n\n/** Library version, sourced from package.json at build time. */\nexport const ANY_LLM_VERSION: string = version\n"]}

package/dist/index.js

@@ -4,7 +4,7 @@ export * from '@gullabs/google';
 // src/index.ts
 
 // package.json
-var version = "0.8.0";
+var version = "0.8.2";
 
 // src/index.ts
 var ANY_LLM_VERSION = version;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../package.json","../src/index.ts"],"names":[],"mappings":";;;;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;ACcN,IAAM,eAAA,GAA0B","file":"index.js","sourcesContent":["{\n  \"name\": \"@gullabs/any-llm\",\n  \"version\": \"0.8.0\",\n  \"description\": \"Batteries-included any-llm client for Gemini: engine, adapter, and Google SDK in one install.\",\n  \"type\": \"module\",\n  \"license\": \"Apache-2.0\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/gullabs/any-llm.git\",\n    \"directory\": \"packages/any-llm\"\n  },\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\",\n      \"require\": \"./dist/index.cjs\"\n    }\n  },\n  \"files\": [\n    \"dist\",\n    \"skills\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsup\"\n  },\n  \"dependencies\": {\n    \"@google/genai\": \"^1.45.0 || ^2\",\n    \"@gullabs/core\": \"workspace:*\",\n    \"@gullabs/google\": \"workspace:*\"\n  },\n  \"engines\": {\n    \"node\": \">=20.9.0\"\n  },\n  \"sideEffects\": false,\n  \"keywords\": [\n    \"llm\",\n    \"gemini\",\n    \"google-genai\",\n    \"ai\",\n    \"tokens\",\n    \"cost\",\n    \"usage\",\n    \"observability\",\n    \"typescript\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"homepage\": \"https://github.com/gullabs/any-llm/tree/main/packages/any-llm#readme\",\n  \"bugs\": \"https://github.com/gullabs/any-llm/issues\"\n}\n","/**\n * @gullabs/any-llm — batteries-included public entrypoint.\n *\n * This package is the default client install path. It re-exports the core\n * engine and Gemini adapter while depending on the Gemini SDK for a one-package\n * setup.\n *\n * @module\n */\n\nexport * from '@gullabs/core'\nexport * from '@gullabs/google'\n\nimport { version } from '../package.json'\n\n/** Library version, sourced from package.json at build time. */\nexport const ANY_LLM_VERSION: string = version\n"]}
+{"version":3,"sources":["../package.json","../src/index.ts"],"names":[],"mappings":";;;;;;AAEE,IAAA,OAAA,GAAW,OAAA;;;ACcN,IAAM,eAAA,GAA0B","file":"index.js","sourcesContent":["{\n  \"name\": \"@gullabs/any-llm\",\n  \"version\": \"0.8.2\",\n  \"description\": \"Batteries-included any-llm client for Gemini: engine, adapter, and Google SDK in one install.\",\n  \"type\": \"module\",\n  \"license\": \"Apache-2.0\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/gullabs/any-llm.git\",\n    \"directory\": \"packages/any-llm\"\n  },\n  \"main\": \"./dist/index.cjs\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\",\n      \"require\": \"./dist/index.cjs\"\n    }\n  },\n  \"files\": [\n    \"dist\",\n    \"skills\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsup\"\n  },\n  \"dependencies\": {\n    \"@google/genai\": \"^1.45.0 || ^2\",\n    \"@gullabs/core\": \"workspace:*\",\n    \"@gullabs/google\": \"workspace:*\"\n  },\n  \"engines\": {\n    \"node\": \">=20.9.0\"\n  },\n  \"sideEffects\": false,\n  \"keywords\": [\n    \"llm\",\n    \"gemini\",\n    \"google-genai\",\n    \"ai\",\n    \"tokens\",\n    \"cost\",\n    \"usage\",\n    \"observability\",\n    \"typescript\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\"\n  },\n  \"homepage\": \"https://github.com/gullabs/any-llm/tree/main/packages/any-llm#readme\",\n  \"bugs\": \"https://github.com/gullabs/any-llm/issues\"\n}\n","/**\n * @gullabs/any-llm — batteries-included public entrypoint.\n *\n * This package is the default client install path. It re-exports the core\n * engine and Gemini adapter while depending on the Gemini SDK for a one-package\n * setup.\n *\n * @module\n */\n\nexport * from '@gullabs/core'\nexport * from '@gullabs/google'\n\nimport { version } from '../package.json'\n\n/** Library version, sourced from package.json at build time. */\nexport const ANY_LLM_VERSION: string = version\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gullabs/any-llm",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Batteries-included any-llm client for Gemini: engine, adapter, and Google SDK in one install.",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,8 +25,8 @@
   ],
   "dependencies": {
     "@google/genai": "^1.45.0 || ^2",
-    "@gullabs/core": "0.8.0",
-    "@gullabs/google": "0.8.0"
+    "@gullabs/core": "0.9.0",
+    "@gullabs/google": "0.8.1"
   },
   "engines": {
     "node": ">=20.9.0"

package/skills/any-llm/SKILL.md

@@ -163,6 +163,32 @@ const result = await client.generate(
 `Grok45ConfigSchema`. Unlike Gemini, xai has no `serviceTier` concept and no `topK`;
 its config schema is a single strict object with no tier branching.
 
+## xAI structured-output schemas vs. OpenAI-strict / codex-cli schemas
+
+As of the 2026-07-09 live probes, xAI's `strict: true` structured-output validation
+on `text.format` json_schema performed no OpenAI-style compile-time schema checks —
+schemas missing root/nested `additionalProperties: false`, properties omitted from
+`required` (optional properties), `format`/other keywords, `anyOf`, `$defs`/`$ref`,
+and nullable unions (`type: [T, 'null']`) were all accepted with HTTP 200.
+`@gullabs/xai`'s adapter forwards schemas to xAI verbatim; no rewriting is applied.
+
+`@gullabs/codex-cli`, by contrast, targets the codex CLI's own `--output-schema`
+backend, which (verified 2026-07-09 via live probes against the real codex CLI
+binary/backend) enforces exactly two structural rules: every object node must carry
+`additionalProperties: false`, and `required` must be present and include every key
+in `properties` (optional semantics are preserved by adding `null` to that
+property's type, not by simply marking it required). `@gullabs/codex-cli` exports
+`toOpenAiStrictOutputSchema` — an explicit opt-in transformer, never called
+automatically by the adapter — that rewrites a schema to satisfy those two rules.
+codex-cli's local preflight (`assertOpenAiStrictOutputSchema` in
+`packages/codex-cli/src/adapter.ts`) enforces both rules locally before dispatch,
+turning what used to be a live-round-trip provider 400 into an immediate local
+`bad_request`.
+
+This preflight/transformer pair is specific to codex-cli's own `--output-schema`
+contract, not a general any-llm behavior — it is not applied to xai, which has no
+such preflight (see the xAI Grok section above).
+
 ## Migrating raw `@google/genai` prompts
 
 `geminiContentToMessages` (from `@gullabs/google`) converts hand-authored
@@ -203,6 +229,17 @@ const result = await client.generate(
 `system` is derived only from the explicit `systemInstruction` input — never inferred
 from `contents`.
 
+## Testing with `@gullabs/testing`
+
+Real hosts don't call `createClient()` at call sites — they own a factory module that
+assembles the client once and hand call sites the built client. `@gullabs/testing`'s
+fakes (`makeFakeGemini`, `FakeAdapter`, `RecordingSink`, `FakeClock`, `FakeIds`, ...) are
+designed to inject through that same host-owned factory unchanged, via injectable
+override parameters with production defaults — not via `vi.mock()`. See
+`packages/testing/README.md` § "Wiring fakes through a host-owned factory" for a
+complete two-file (factory + vitest test) example, including the port-level
+`FakeAdapter` variant for bypassing the Gemini SDK shape entirely.
+
 ## `defineCallSite` — reusable prompt templates
 
 ```ts
@@ -222,12 +259,106 @@ const result = await client.runStructured(summarize, { article: text }, { auth }
 
 `{{var}}` interpolation is non-recursive (substituted values are never re-scanned for
 further `{{...}}`, preventing template injection) and applies to both `system` and
-`userTemplate`. A missing var is left as the literal `{{var}}` placeholder, not an
-empty string. `runStructured` also accepts a two-arg form, `(callSite, opts)`, when the
-template has no vars. Config resolution order everywhere is
+`userTemplate`. **Strict by default (no opt-out):** every `{{var}}` placeholder must have
+a string-typed value in `vars`, or `runStructured` throws before any request is built —
+see "Input contracts" below. `runStructured` also accepts a two-arg form, `(callSite,
+opts)`, when the template has no vars. Config resolution order everywhere is
 `clientDefaults → callSite.config → opts.config`, and the merged config must still pass
 the selected descriptor's strict runtime schema before dispatch.
 
+## Input contracts — strict interpolation, `inputSchema`, `inputContract`
+
+**Strict template interpolation is the default, with no opt-out.** Every `{{var}}`
+placeholder referenced by `callSite.system` or `callSite.userTemplate` must have a
+string-typed value present in `vars`, or `runStructured` refuses the call before any
+request is built — zero tokens spent:
+
+```ts
+import { defineCallSite, LlmError } from '@gullabs/core'
+
+const summarize = defineCallSite({
+  id: 'summarize-article',
+  provider: 'google',
+  model: 'gemini-2.5-flash',
+  userTemplate: 'Summarize this article in 3 sentences:\n\n{{article}}',
+})
+
+try {
+  // Missing `article` — throws before any I/O.
+  await client.runStructured(summarize, {}, { auth })
+} catch (e) {
+  if (e instanceof LlmError && e.kind === 'bad_request') {
+    console.log(e.issues) // [{ path: 'article', message: '...' }]
+  }
+}
+```
+
+`null`, `undefined`, and non-string values (numbers, objects) are all violations — never
+coerced to a string. Unused `vars` entries (present in `vars` but not referenced by any
+template) are allowed. There is no escape syntax for literal `{{...}}` text.
+
+**`CallSite.inputSchema`** validates `vars` with a `StandardSchemaV1` validator (zod,
+valibot, ...) before interpolation runs, so a missing business field surfaces in your own
+schema's vocabulary instead of as a downstream placeholder violation:
+
+```ts
+import { z } from 'zod'
+
+const reviewCallSite = defineCallSite({
+  id: 'code-review',
+  provider: 'google',
+  model: 'gemini-2.5-flash',
+  userTemplate: 'Review this diff as {{reviewer}}:\n\n{{diff}}',
+  inputSchema: z.object({
+    reviewer: z.string().min(1),
+    diff: z.string().min(1),
+  }),
+})
+
+await client.runStructured(
+  reviewCallSite,
+  { reviewer: 'senior-reviewer', diff },
+  { auth },
+)
+```
+
+**`LlmRequest.inputContract`** is the equivalent opt-in contract for the `generate()`
+path (callers who render their own prompt strings and never touch `CallSite`):
+
+```ts
+const result = await client.generate(
+  {
+    provider: 'google',
+    model: 'gemini-2.5-flash',
+    messages: [{ role: 'user', parts: [{ kind: 'text', text: renderedPrompt }] }],
+    inputContract: { schema: myZodSchema, value: sourceContext },
+  },
+  { auth },
+)
+```
+
+`inputContract` is validated once per logical call, before `@gullabs/quota` or any retry
+middleware runs — a violation never consumes rate-limit budget and is never retried.
+`generate()` and `runStructured()` are independent paths: `runStructured` never
+auto-populates `inputContract` from `inputSchema`, and `generate()` never reads
+`inputSchema`.
+
+**`createClient({ requireInputContract: true })`** is a fleet-wide toggle: every
+`generate()` call must carry `inputContract`, and every `runStructured()` call site must
+carry `inputSchema`, or the call is refused. Off by default.
+
+**All violations throw `LlmError('bad_request')`** with a structured `issues` array
+(`{ path, message }[]`, one entry per violation) on top of the usual `.message` string.
+
+**Ledger semantics of refusals.** A refusal that never got a `callId` (unresolved
+placeholders, `CallSite.inputSchema`, or `requireInputContract` on the `runStructured`
+path — all thrown in the `runStructured` prologue) writes **no** ledger row. A refusal
+that already has a `callId` (`inputContract` violations and `requireInputContract` on the
+`generate()` path, thrown inside the pipeline after `callId` assignment) writes **one**
+zero-usage record with `attemptNumber: 0` — including `@gullabs/quota` denials, which get
+the same treatment with no `@gullabs/quota` code changes. See ADR-025 in `DECISIONS.md`
+for the full boundary table.
+
 ## Strict model-config boundary
 
 Treat model config as descriptor-owned:
@@ -379,7 +510,8 @@ try {
 ```
 
 `LlmError` also carries `httpStatus?`, `retryAfterMs?`, `provider?`, `callId?`,
-`attemptId?`, `servedServiceTier?`, and `cause` (the original thrown value).
+`attemptId?`, `servedServiceTier?`, `issues?` (structured `{ path, message }[]` — see
+"Input contracts" above), and `cause` (the original thrown value).
 
 ## Reject, don't map