@framers/agentos 0.9.15 → 0.9.17

package/README.md

@@ -404,6 +404,38 @@ Provider fallback is an explicit opt-in via `agent({ fallbackProviders: [...] })
 
 [Full API reference ->](https://docs.agentos.sh/api) * [High-Level API guide ->](https://docs.agentos.sh/getting-started/high-level-api)
 
+### Tuning generation knobs
+
+Per-LLM-call knobs live on a flat namespace. Override chain runs **per-call → per-agent → provider default**.
+
+| Knob | Where you set it | What it does |
+|---|---|---|
+| `maxTokens` | `agent({ maxTokens })` / `generate(prompt, { maxTokens })` / `generateText({ maxTokens })` / `generateObject({ maxTokens })` | Caps completion tokens per call. Provider defaults: Anthropic **16000** (was 4096 pre-`0.9.13`; raised so Claude 4 tool-use responses don't truncate mid-JSON), OpenAI 4096, Gemini 8192. |
+| `temperature` | Same surfaces | 0-2; lower = deterministic, higher = creative. Opus 4.7 ignores this — extended-thinking models use their own sampler. |
+| `maxSteps` | `agent({ maxSteps })` | Caps the inner tool-use loop per `.generate()`. Default `5`. Keep low (3-5) when an outer scheduler also iterates; tool latency multiplies by steps. |
+| `controls.maxTotalTokens` | `agent({ controls: { maxTotalTokens } })` | Hard ceiling on input + output combined per turn; full-runtime `agency()` enforces it. |
+| `controls.maxDurationMs` | Same | Hard wall-clock cap per turn; surfaces as a thrown error rather than letting the API hang. |
+| `fallbackProviders` | `agent({ fallbackProviders })` | Ordered chain of `{ provider, model? }` entries the runtime walks on retryable errors. |
+| `provider` / `model` | `agent({ provider, model })` or pass `"provider/model"` to any generate helper | Routing. Slash form auto-detects when prefix matches a known provider id. |
+
+```ts
+// Pin defaults at agent construction:
+const writer = agent({
+  provider: 'anthropic',
+  model: 'claude-opus-4-7',
+  instructions: 'Write punchy product copy.',
+  maxTokens: 2000,
+  temperature: 0.7,
+});
+
+// Override on a specific call when one response needs more room:
+const longform = await writer.generate('Draft a 4-page whitepaper.', {
+  maxTokens: 16000,
+});
+```
+
+Caveat: `generateObject()` auto-derives a sane default for `maxTokens` from the Zod schema shape when omitted — Boolean schemas land ~50 tokens, large array-of-object schemas land ~8k. Explicit `maxTokens` overrides the estimate.
+
 ---
 
 ## Documentation & Community

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.9.15",
+  "version": "0.9.17",
   "description": "AgentOS — open-source TypeScript runtime for autonomous AI agents. Unified graph orchestration, cognitive memory, runtime tool generation, multi-tier guardrails, voice pipeline, and 21 LLM providers.",
   "homepage": "https://agentos.sh",
   "repository": {
@@ -568,6 +568,7 @@
   },
   "scripts": {
     "clean": "rimraf dist tsconfig.build.tsbuildinfo",
+    "prepare": "test -d dist || npm run build",
     "build": "npm run clean && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && node scripts/fix-esm-imports.mjs",
     "build:knowledge": "node scripts/build-knowledge-corpus.mjs",
     "verify:exports": "node --test scripts/package-exports.test.mjs",
@@ -641,8 +642,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.11.0",
-    "@framers/agentos-extensions-registry": "^0.18.0",
-    "@framers/sql-storage-adapter": "^0.6.5",
+    "@framers/agentos-extensions-registry": "^0.18.2",
     "@opentelemetry/context-async-hooks": "^2.0.1",
     "@opentelemetry/sdk-metrics": "^2.0.1",
     "@opentelemetry/sdk-trace-base": "^2.0.1",
@@ -675,6 +675,7 @@
     "vitest": "^1.6.0"
   },
   "dependencies": {
+    "@framers/sql-storage-adapter": "^0.6.6",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.201.1",
     "ajv": "^8.17.1",
@@ -696,7 +697,6 @@
     "zod-to-json-schema": "^3.25.2"
   },
   "peerDependencies": {
-    "@framers/sql-storage-adapter": "^0.6.5",
     "graphology": ">=0.25.0",
     "graphology-communities-louvain": ">=2.0.0",
     "graphology-types": ">=0.24.0",
@@ -707,9 +707,6 @@
     "typescript": ">=5.0.0"
   },
   "peerDependenciesMeta": {
-    "@framers/sql-storage-adapter": {
-      "optional": true
-    },
     "graphology": {
       "optional": true
     },