melchizedek-agents 1.13.0 → 1.15.0

package/dist/lib/envSyndicate.d.ts

@@ -0,0 +1,35 @@
+/**
+ * lib/envSyndicate.ts — a syndicate handed to the server in the environment.
+ *
+ * A container started from the published server image has no agents
+ * directory of its own and, without a database, no registry to load from.
+ * `MELCHIZEDEK_AGENT_YAML` carries the whole syndicate file, base64-encoded
+ * (`base64 < agent.yaml`), so a host that only takes environment variables
+ * can still run one. `MELCHIZEDEK_AGENT_ID` names it (default `agent`): the
+ * id callers address at `/<id>/` and list in `A2A_SERVED_AGENTS`.
+ *
+ * The file is written into a fresh private directory (0700, the file 0600)
+ * that becomes the agents directory, then loaded once, so a bad definition
+ * stops the boot instead of failing the first request. Nested
+ * `yaml_reference`s have no files to load from here: each must be carried in
+ * the definition's own `bundled_references`, as a registry
+ * version carries them, or the boot names the missing ones.
+ *
+ * Imports only node built-ins and lib/loadSyndicate.ts.
+ */
+/** The id a syndicate from the environment is served under unless MELCHIZEDEK_AGENT_ID says otherwise. */
+export declare const ENV_AGENT_ID = "agent";
+export interface EnvSyndicate {
+    /** The private directory the file was written to; the server's agents directory. */
+    agentsDir: string;
+    /** The served id. */
+    id: string;
+    /** `<id>.yaml`, the default syndicate's file name. */
+    file: string;
+}
+/**
+ * The syndicate in `MELCHIZEDEK_AGENT_YAML`, written to disk and checked, or
+ * undefined when the variable is unset. Throws naming the variable and, for
+ * a definition that does not load, the loader's own reason.
+ */
+export declare function envSyndicate(env?: NodeJS.ProcessEnv, parent?: string): EnvSyndicate | undefined;

package/dist/lib/envSyndicate.js

@@ -0,0 +1,70 @@
+/**
+ * lib/envSyndicate.ts — a syndicate handed to the server in the environment.
+ *
+ * A container started from the published server image has no agents
+ * directory of its own and, without a database, no registry to load from.
+ * `MELCHIZEDEK_AGENT_YAML` carries the whole syndicate file, base64-encoded
+ * (`base64 < agent.yaml`), so a host that only takes environment variables
+ * can still run one. `MELCHIZEDEK_AGENT_ID` names it (default `agent`): the
+ * id callers address at `/<id>/` and list in `A2A_SERVED_AGENTS`.
+ *
+ * The file is written into a fresh private directory (0700, the file 0600)
+ * that becomes the agents directory, then loaded once, so a bad definition
+ * stops the boot instead of failing the first request. Nested
+ * `yaml_reference`s have no files to load from here: each must be carried in
+ * the definition's own `bundled_references`, as a registry
+ * version carries them, or the boot names the missing ones.
+ *
+ * Imports only node built-ins and lib/loadSyndicate.ts.
+ */
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadSyndicate } from './loadSyndicate.js';
+/** The id a syndicate from the environment is served under unless MELCHIZEDEK_AGENT_ID says otherwise. */
+export const ENV_AGENT_ID = 'agent';
+/** Same charset as an A2A agent id (lib/a2a/app.ts isValidAgentId), without `:` and `.`, which name registry rows and files. */
+const AGENT_ID = /^[A-Za-z0-9_-]{1,120}$/;
+const BASE64 = /^[A-Za-z0-9+/_-]+={0,2}$/;
+/**
+ * The syndicate in `MELCHIZEDEK_AGENT_YAML`, written to disk and checked, or
+ * undefined when the variable is unset. Throws naming the variable and, for
+ * a definition that does not load, the loader's own reason.
+ */
+export function envSyndicate(env = process.env, parent = tmpdir()) {
+    const encoded = env.MELCHIZEDEK_AGENT_YAML?.replace(/\s+/g, '');
+    if (!encoded)
+        return undefined;
+    const id = env.MELCHIZEDEK_AGENT_ID?.trim() || ENV_AGENT_ID;
+    if (!AGENT_ID.test(id)) {
+        throw new Error('MELCHIZEDEK_AGENT_ID must be 1-120 letters, digits, _ or -.');
+    }
+    if (env.MELCHIZEDEK_AGENTS_DIR?.trim()) {
+        throw new Error('MELCHIZEDEK_AGENT_YAML and MELCHIZEDEK_AGENTS_DIR are both set: the syndicate comes from one place. Unset one of them.');
+    }
+    // Node's base64 decoder takes the URL-safe alphabet too.
+    const bytes = BASE64.test(encoded) ? Buffer.from(encoded, 'base64') : undefined;
+    if (!bytes?.length) {
+        throw new Error('MELCHIZEDEK_AGENT_YAML must be the syndicate file base64-encoded (base64 < agent.yaml), not the YAML itself.');
+    }
+    const agentsDir = mkdtempSync(join(parent, 'melchizedek-agent-'));
+    const file = `${id}.yaml`;
+    writeFileSync(join(agentsDir, file), bytes, { mode: 0o600 });
+    let config;
+    try {
+        config = loadSyndicate(file, { agentsDir, shippedFallback: false });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`MELCHIZEDEK_AGENT_YAML does not load: ${message}`);
+    }
+    const bundled = config.bundled_references ?? {};
+    const missing = (config.subagents ?? [])
+        .map((s) => s.yaml_reference)
+        .filter((ref) => typeof ref === 'string' && !Object.hasOwn(bundled, ref));
+    if (missing.length) {
+        throw new Error(`MELCHIZEDEK_AGENT_YAML references nested syndicates it does not carry: ${missing.join(', ')}. `
+            + 'Put each in the definition\'s bundled_references, or serve from the registry (A2A_REGISTRY_AGENTS).');
+    }
+    return { agentsDir, id, file };
+}

package/dist/lib/index.d.ts

@@ -68,6 +68,8 @@ export type { MemoryStore } from './memory/store.ts';
 export { validateSyndicateConfig, syndicateJsonSchema, SyndicateValidationError } from './syndicateSchema.ts';
 export { PROVIDERS, providerForModel, providerKeyPresent, providerStatuses, logProviderStatuses, resolveModel, describeCapabilities, capabilitySummary, planTransport, gatewayConfig, gatewayProblem, gatewayUsable, GATEWAYS, } from './models/registry.ts';
 export { loadEnv } from './loadEnv.ts';
+export { attachmentSupport, takesBlob } from './models/attachments.ts';
+export type { AttachmentSupport } from './models/attachments.ts';
 export { setCredentialSource, credentialValue } from './models/credentialSource.ts';
 export type { CredentialSource } from './models/credentialSource.ts';
 export { PROJECT_MANIFEST, projectManifestSchema, ProjectManifestError, findProject, findProjectRoot, loadProject, parseProjectManifest, resolveAgentsDir, listProjectSyndicates, checkProject, type Project, type ProjectManifest, type ProjectCheck, } from './project.ts';

package/dist/lib/index.js

@@ -54,6 +54,8 @@ export { PROVIDERS, providerForModel, providerKeyPresent, providerStatuses, logP
 // subpath until 0.16.0.
 describeCapabilities, capabilitySummary, planTransport, gatewayConfig, gatewayProblem, gatewayUsable, GATEWAYS, } from './models/registry.js';
 export { loadEnv } from './loadEnv.js';
+// Which files a model's path takes in a user message, and how large.
+export { attachmentSupport, takesBlob } from './models/attachments.js';
 // Where credentials are read, by environment variable name (ADR 0133).
 export { setCredentialSource, credentialValue } from './models/credentialSource.js';
 // Project manifest, melchizedek.json (ADR 0138).

package/dist/lib/loadSyndicate.d.ts

@@ -5,7 +5,7 @@ import type { OpenApiConfig } from './tools/openapiTools.ts';
 import type { McpAuthConfig } from './tools/oauthTools.ts';
 import type { McpTransportKind } from './tools/mcpTransports.ts';
 import type { McpServerConfig } from './tools/mcpToolFactory.ts';
-import type { ContextConfig, ExampleConfig } from './compile.ts';
+import type { ContextSetting, ExampleConfig } from './compile.ts';
 export type { OpenApiConfig } from './tools/openapiTools.ts';
 export type { SkillsConfig } from './tools/skillToolset.ts';
 import type { WorkflowConfig } from './workflowConfig.ts';
@@ -182,8 +182,8 @@ export interface AgentYamlConfig {
     run_code?: {
         attach?: boolean;
     };
-    /** Compact a long conversation into a summary past a token threshold (ADR 0033). Delegate orchestrator only. */
-    context?: ContextConfig;
+    /** What the model is sent of a long conversation: masking and compaction, both on by default (ADR 0033, ADR 0152, ADR 0154), or `off`. */
+    context?: ContextSetting;
     /** `task`: the agent works until it calls finish_task; its arguments are the node's output. Workflow nodes only. */
     mode?: 'task';
     /** Few-shot exchanges added to every request's instruction (ADK's ExampleTool). */
@@ -415,8 +415,20 @@ export declare function nestedLoader(config: SyndicateYamlConfig, fromFiles?: (r
  */
 export declare function validateRegistryConfig(config: Record<string, any>): void;
 /**
- * Loads a syndicate configuration from the Supabase registry.
- * @param registryId The document ID in the adk_agent_registry table
- * @param options Load options (bindings and overrides)
+ * Where registry rows are read from over a direct database connection
+ * (DATABASE_URL): `postgresRegistryReader(pool)` in lib/registry.ts, which
+ * postgresStorage supplies as `registry`.
  */
-export declare function loadSyndicateFromRegistry(registryId: string, options?: LoadSyndicateOptions): Promise<SyndicateYamlConfig>;
+export interface RegistryReader {
+    /** The active definition of `id`, or with `version` that stored version; undefined when there is none. */
+    definition(id: string, version?: number): Promise<unknown>;
+}
+/**
+ * Loads a syndicate configuration from the registry: through `registry`
+ * (a direct Postgres connection) when given, else over the Supabase API.
+ * @param registryId The document ID in the adk_agent_registry table; `<id>@<version>` loads one stored version
+ * @param options Load options (bindings and overrides), and the reader
+ */
+export declare function loadSyndicateFromRegistry(registryId: string, options?: LoadSyndicateOptions & {
+    registry?: RegistryReader;
+}): Promise<SyndicateYamlConfig>;

package/dist/lib/loadSyndicate.js

@@ -400,13 +400,22 @@ export function validateRegistryConfig(config) {
     }
 }
 /**
- * Loads a syndicate configuration from the Supabase registry.
- * @param registryId The document ID in the adk_agent_registry table
- * @param options Load options (bindings and overrides)
+ * Loads a syndicate configuration from the registry: through `registry`
+ * (a direct Postgres connection) when given, else over the Supabase API.
+ * @param registryId The document ID in the adk_agent_registry table; `<id>@<version>` loads one stored version
+ * @param options Load options (bindings and overrides), and the reader
  */
 export async function loadSyndicateFromRegistry(registryId, options = {}) {
+    const { registry, ...loadOptions } = options;
+    if (registry) {
+        const pinnedRef = /^(.+)@(\d+)$/.exec(registryId);
+        const definition = pinnedRef ? await registry.definition(pinnedRef[1], Number(pinnedRef[2])) : await registry.definition(registryId);
+        if (definition === undefined || definition === null)
+            throw new Error(`Registry document ${registryId} not found`);
+        return resolveAndValidate(definition, `registry:${registryId}`, loadOptions);
+    }
     if (!hasSupabaseCredentials()) {
-        throw new Error('Supabase credentials not available for registry loading.');
+        throw new Error('No registry to load from: set DATABASE_URL (a direct Postgres connection), or SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.');
     }
     const supabaseUrl = process.env.SUPABASE_URL;
     const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
@@ -427,5 +436,5 @@ export async function loadSyndicateFromRegistry(registryId, options = {}) {
     }
     // The registry row is the live copy of a file (scripts/deploy_agent.ts), so
     // it answers to the same schema; the label says where the bad copy lives.
-    return resolveAndValidate(data.yaml_content, `registry:${registryId}`, options);
+    return resolveAndValidate(data.yaml_content, `registry:${registryId}`, loadOptions);
 }

package/dist/lib/models/attachments.d.ts

@@ -0,0 +1,42 @@
+/**
+ * lib/models/attachments.ts — which files a model's path takes in a user
+ * message, and how large.
+ *
+ * WHY this file exists:
+ *   A file reaches a model as a blob part, and what an adapter can send
+ *   differs by provider: Gemini takes audio and video, the Messages API and
+ *   the Responses API take PDFs, a chat-completions path takes images only. A
+ *   caller that converts or shrinks a file first (the desktop app), and the
+ *   A2A server that refuses one, read the same table, so neither learns of a
+ *   mismatch from a provider's 400.
+ *
+ * Limits are the provider's published ones, set a little under where the
+ * base64 a request carries is what is counted. `maxRequestBytes` is decoded
+ * bytes across a whole request, and a conversation's earlier files are in it.
+ */
+export interface AttachmentSupport {
+    /** Image types sent as images. */
+    images: readonly string[];
+    /** Document types sent as documents; anything else must arrive as text. */
+    documents: readonly string[];
+    /** Audio and video types sent as they are. */
+    media: readonly string[];
+    /** The longest image edge worth sending, in pixels: past it the provider shrinks the image or refuses it. */
+    maxImageEdge: number;
+    /** Largest image, decoded bytes. */
+    maxImageBytes: number;
+    /** Largest document or media file, decoded bytes. */
+    maxFileBytes: number;
+    /** Largest total of files in one request, decoded bytes. */
+    maxRequestBytes: number;
+}
+/**
+ * What `model` takes on the path it will actually run on. A gateway speaks
+ * chat completions whichever provider is behind it, so a direct-only type is
+ * not offered there. An id no path serves reads as the plain table.
+ */
+export declare function attachmentSupport(model: unknown, opts?: {
+    callerKey?: boolean;
+}): AttachmentSupport;
+/** Whether a media type is sent as a blob on this path (not whether it fits). */
+export declare function takesBlob(support: AttachmentSupport, mediaType: string): boolean;

package/dist/lib/models/attachments.js

@@ -0,0 +1,80 @@
+/**
+ * lib/models/attachments.ts — which files a model's path takes in a user
+ * message, and how large.
+ *
+ * WHY this file exists:
+ *   A file reaches a model as a blob part, and what an adapter can send
+ *   differs by provider: Gemini takes audio and video, the Messages API and
+ *   the Responses API take PDFs, a chat-completions path takes images only. A
+ *   caller that converts or shrinks a file first (the desktop app), and the
+ *   A2A server that refuses one, read the same table, so neither learns of a
+ *   mismatch from a provider's 400.
+ *
+ * Limits are the provider's published ones, set a little under where the
+ * base64 a request carries is what is counted. `maxRequestBytes` is decoded
+ * bytes across a whole request, and a conversation's earlier files are in it.
+ */
+import { planTransport } from './gateway.js';
+const MB = 1024 * 1024;
+/** Any path that takes a data URI: the chat-completions adapters, Ollama and the gateways. */
+const PLAIN = {
+    images: ['image/jpeg', 'image/png'],
+    documents: [],
+    media: [],
+    maxImageEdge: 1568,
+    maxImageBytes: 8 * MB,
+    maxFileBytes: 0,
+    maxRequestBytes: 14 * MB,
+};
+const DIRECT = {
+    anthropic: {
+        images: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+        documents: ['application/pdf'],
+        media: [],
+        maxImageEdge: 1568,
+        maxImageBytes: 3.75 * MB,
+        maxFileBytes: 22 * MB,
+        maxRequestBytes: 22 * MB,
+    },
+    openai: {
+        images: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+        documents: ['application/pdf'],
+        media: [],
+        maxImageEdge: 2048,
+        maxImageBytes: 20 * MB,
+        maxFileBytes: 32 * MB,
+        maxRequestBytes: 36 * MB,
+    },
+    gemini: {
+        images: ['image/jpeg', 'image/png', 'image/webp', 'image/heic', 'image/heif'],
+        documents: ['application/pdf'],
+        media: [
+            'audio/wav', 'audio/mp3', 'audio/mpeg', 'audio/aiff', 'audio/aac', 'audio/ogg', 'audio/flac',
+            'video/mp4', 'video/mpeg', 'video/quicktime', 'video/webm',
+        ],
+        maxImageEdge: 3072,
+        maxImageBytes: 14 * MB,
+        maxFileBytes: 14 * MB,
+        maxRequestBytes: 14 * MB,
+    },
+};
+/**
+ * What `model` takes on the path it will actually run on. A gateway speaks
+ * chat completions whichever provider is behind it, so a direct-only type is
+ * not offered there. An id no path serves reads as the plain table.
+ */
+export function attachmentSupport(model, opts = {}) {
+    if (typeof model !== 'string' || !model)
+        return PLAIN;
+    try {
+        const plan = planTransport(model, opts);
+        return (plan.transport === 'direct' && DIRECT[plan.provider]) || PLAIN;
+    }
+    catch {
+        return PLAIN;
+    }
+}
+/** Whether a media type is sent as a blob on this path (not whether it fits). */
+export function takesBlob(support, mediaType) {
+    return support.images.includes(mediaType) || support.documents.includes(mediaType) || support.media.includes(mediaType);
+}

package/dist/lib/models/capabilities.d.ts

@@ -48,6 +48,8 @@ export interface CapabilityReport {
     dropped: string[];
     /** Declared client-side tools; portable across every path. */
     portable: string[];
+    /** The tokens the model's context holds (lib/models/contextWindow.ts); absent for a provider the table does not know. */
+    contextWindow?: number;
 }
 export declare function describeCapabilities(model: string, tools?: readonly string[], opts?: {
     callerKey?: boolean;

package/dist/lib/models/capabilities.js

@@ -21,6 +21,7 @@ import { PROVIDERS } from './providerMap.js';
 import { gatewaySearch, planTransport } from './gateway.js';
 import { nativeSearchOn, PLATFORMS_FOR, platformFromEnv } from './endpoints.js';
 import { claudeGeneration, claudeUrlImagesOn } from './claudeModels.js';
+import { contextWindowOf } from './contextWindow.js';
 /** The platform a direct path uses (ADR 0023); a misconfigured one reads as direct here, the doctor reports it. */
 function directPlatform(provider) {
     try {
@@ -79,6 +80,7 @@ export function describeCapabilities(model, tools = [], opts = {}) {
         native,
         dropped,
         portable,
+        ...(contextWindowOf(model) !== undefined ? { contextWindow: contextWindowOf(model) } : {}),
     };
 }
 /**

package/dist/lib/models/chatCompletionsAdapter.js

@@ -837,7 +837,12 @@ export class ChatCompletionsAdapter {
                         else if (part.data) {
                             // Inline only: a data URI for vision models. A URL blob is not
                             // sent (Moonshot takes no public image URLs).
-                            images.push({ type: 'image_url', image_url: { url: `data:${part.mimeType || 'image/png'};base64,${part.data}` } });
+                            const type = !part.mimeType || part.mimeType === 'application/octet-stream' ? 'image/png' : part.mimeType;
+                            // This wire has images only; a PDF labelled as one would fail the whole request.
+                            if (type.startsWith('image/'))
+                                images.push({ type: 'image_url', image_url: { url: `data:${type};base64,${part.data}` } });
+                            else
+                                console.warn(`⚠ A file part (${type.replace(/[^\x20-\x7e]/g, '?').slice(0, 64)}) is not sent: this path takes images only.`);
                         }
                     }
                     const text = texts.join('\n');
@@ -891,6 +896,19 @@ export class ChatCompletionsAdapter {
                     return;
             }
         });
+        // This step's notes, after the history: joined to a last user message's
+        // text, or a user message of their own after tool results, so the cached
+        // prefix before them holds. Never a trailing system message: some
+        // OpenAI-compatible servers take system first only.
+        if (request.turnNotes) {
+            const last = messages[messages.length - 1];
+            if (last?.role === 'user' && typeof last.content === 'string')
+                last.content = `${last.content}\n\n${request.turnNotes}`;
+            else if (last?.role === 'user' && Array.isArray(last.content))
+                last.content.push({ type: 'text', text: request.turnNotes });
+            else
+                messages.push({ role: 'user', content: request.turnNotes });
+        }
         if (system.length > 0)
             messages.unshift({ role: 'system', content: system.join('\n\n') });
         return messages;

package/dist/lib/models/claudeAdapter.js

@@ -105,6 +105,16 @@ function imageBlockFor(part, urlImages) {
     const named = (type) => type.replace(/[^\x20-\x7e]/g, '?').slice(0, 64);
     const declared = String(part.mimeType ?? '').toLowerCase();
     const untyped = UNTYPED.has(declared);
+    if (declared === 'application/pdf') {
+        if (part.data !== undefined)
+            return part.data ? { type: 'document', source: { type: 'base64', media_type: 'application/pdf', data: part.data } } : undefined;
+        const uri = String(part.url ?? '');
+        if (!uri)
+            return undefined;
+        if (!/^https:\/\//i.test(uri))
+            return `non-https URL (${/^[a-z][a-z0-9+.-]*:/i.exec(uri)?.[0] ?? 'no scheme'})`;
+        return urlImages ? { type: 'document', source: { type: 'url', url: uri } } : URL_SOURCE;
+    }
     if (part.data !== undefined) {
         if (!part.data)
             return undefined;
@@ -341,6 +351,15 @@ export class ClaudeAdapter {
             if (blocks.length > 0)
                 messages.push({ role, content: blocks });
         });
+        // This step's notes, after the history: on the last user message (tool
+        // results are user content here too), so the cached prefix before it holds.
+        if (request.turnNotes) {
+            const last = messages[messages.length - 1];
+            if (last?.role === 'user')
+                last.content.push({ type: 'text', text: request.turnNotes });
+            else
+                messages.push({ role: 'user', content: [{ type: 'text', text: request.turnNotes }] });
+        }
         if (droppedImages.size > 0) {
             setLlmSpanAttribute('llm.image.dropped', [...droppedImages].join(','));
             for (const what of droppedImages) {
@@ -474,6 +493,12 @@ export class ClaudeAdapter {
             ...(thinking ? { thinking } : {}),
             ...(Object.keys(outputConfig).length > 0 ? { output_config: outputConfig } : {}),
             ...(plan?.dropBlock ? { betas: [THINKING_BINDING_BETA] } : {}),
+            // Automatic prompt caching: the API puts the breakpoint on the last
+            // cacheable block and moves it forward as the history grows, so each
+            // step reads the previous step's prefix at the cached price. The loop
+            // keeps the prefix stable for it (ModelRequest.turnNotes). Anthropic's
+            // own API only until Bedrock and Vertex are confirmed to take the field.
+            ...(endpoint.platform === 'direct' ? { cache_control: { type: 'ephemeral' } } : {}),
         };
         return { body, beta: plan?.dropBlock === true, structuredTool: structuredTool !== undefined };
     }

package/dist/lib/models/contextWindow.d.ts

@@ -0,0 +1,32 @@
+/**
+ * lib/models/contextWindow.ts — how many tokens a model's context holds,
+ * read from the model id (ADR 0154).
+ *
+ * WHY this file exists:
+ *   Compaction on by default needs a threshold per model, and nothing in the
+ *   registry said how big a window is. The numbers here are each provider's
+ *   published context length for the id families the engine routes
+ *   (lib/models/providerMap.ts), newest row first; an id a family does not
+ *   name gets the family's newest row, as the Claude generation table does.
+ *   Ollama's is whatever the server was started with: OLLAMA_CONTEXT_LENGTH
+ *   when set, else Ollama's 4,096 default (lib/models/ollamaAdapter.ts), the
+ *   one provider that cannot report an overflow, which is why its threshold
+ *   must be right.
+ *
+ *   `compactAfterTokens(model)` is the default `compact_after_tokens`: 60%
+ *   of the window, so a step's own output, the summary and a tool result
+ *   or two still fit after the threshold is passed. A window the table does
+ *   not know gets UNKNOWN_WINDOW.
+ */
+/** Assumed for a provider the table does not know. */
+export declare const UNKNOWN_WINDOW = 100000;
+/** The share of the window past which an agent compacts by default. */
+export declare const COMPACT_AT_SHARE = 0.6;
+/** Ollama's context length unless the server says otherwise. */
+export declare const OLLAMA_DEFAULT_CONTEXT = 4096;
+/** The Ollama server's context length: OLLAMA_CONTEXT_LENGTH, else Ollama's default. */
+export declare function ollamaContextLength(env?: NodeJS.ProcessEnv): number;
+/** The tokens `model`'s context holds, or undefined for a provider the table does not know (Jev, a gateway-only id). */
+export declare function contextWindowOf(model: string, env?: NodeJS.ProcessEnv): number | undefined;
+/** The default `compact_after_tokens` for `model`: COMPACT_AT_SHARE of its window. */
+export declare function compactAfterTokens(model: string, env?: NodeJS.ProcessEnv): number;

package/dist/lib/models/contextWindow.js

@@ -0,0 +1,73 @@
+/**
+ * lib/models/contextWindow.ts — how many tokens a model's context holds,
+ * read from the model id (ADR 0154).
+ *
+ * WHY this file exists:
+ *   Compaction on by default needs a threshold per model, and nothing in the
+ *   registry said how big a window is. The numbers here are each provider's
+ *   published context length for the id families the engine routes
+ *   (lib/models/providerMap.ts), newest row first; an id a family does not
+ *   name gets the family's newest row, as the Claude generation table does.
+ *   Ollama's is whatever the server was started with: OLLAMA_CONTEXT_LENGTH
+ *   when set, else Ollama's 4,096 default (lib/models/ollamaAdapter.ts), the
+ *   one provider that cannot report an overflow, which is why its threshold
+ *   must be right.
+ *
+ *   `compactAfterTokens(model)` is the default `compact_after_tokens`: 60%
+ *   of the window, so a step's own output, the summary and a tool result
+ *   or two still fit after the threshold is passed. A window the table does
+ *   not know gets UNKNOWN_WINDOW.
+ */
+import { providerForModel } from './providerMap.js';
+/** Assumed for a provider the table does not know. */
+export const UNKNOWN_WINDOW = 100_000;
+/** The share of the window past which an agent compacts by default. */
+export const COMPACT_AT_SHARE = 0.6;
+/** Ollama's context length unless the server says otherwise. */
+export const OLLAMA_DEFAULT_CONTEXT = 4_096;
+const CLAUDE = [[/^claude-/, 200_000]];
+const OPENAI = [
+    [/^gpt-4o/, 128_000],
+    [/^gpt-4\.1/, 1_047_576],
+    [/^o[0-9]/, 200_000],
+    [/^gpt-5/, 400_000],
+];
+const GEMINI = [[/^gemini-/, 1_048_576]];
+const XAI = [
+    [/^grok-3/, 131_072],
+    [/^grok-4/, 256_000],
+];
+const MOONSHOT = [
+    [/^kimi-k2/, 262_144],
+    [/^kimi-k3/, 1_000_000],
+];
+const DEEPSEEK = [[/^deepseek-/, 1_000_000]];
+const FAMILIES = {
+    anthropic: CLAUDE,
+    openai: OPENAI,
+    gemini: GEMINI,
+    xai: XAI,
+    moonshot: MOONSHOT,
+    deepseek: DEEPSEEK,
+};
+/** The Ollama server's context length: OLLAMA_CONTEXT_LENGTH, else Ollama's default. */
+export function ollamaContextLength(env = process.env) {
+    const set = Number(env.OLLAMA_CONTEXT_LENGTH);
+    return Number.isFinite(set) && set > 0 ? Math.floor(set) : OLLAMA_DEFAULT_CONTEXT;
+}
+/** The tokens `model`'s context holds, or undefined for a provider the table does not know (Jev, a gateway-only id). */
+export function contextWindowOf(model, env = process.env) {
+    const provider = providerForModel(model);
+    if (provider === 'ollama')
+        return ollamaContextLength(env);
+    const rows = FAMILIES[provider];
+    if (!rows || rows.length === 0)
+        return undefined;
+    const bare = model.replace(/^[a-z-]+\//, '');
+    const hit = rows.find(([pattern]) => pattern.test(bare));
+    return (hit ?? rows[rows.length - 1])[1];
+}
+/** The default `compact_after_tokens` for `model`: COMPACT_AT_SHARE of its window. */
+export function compactAfterTokens(model, env = process.env) {
+    return Math.round((contextWindowOf(model, env) ?? UNKNOWN_WINDOW) * COMPACT_AT_SHARE);
+}

package/dist/lib/models/contract.d.ts

@@ -207,10 +207,24 @@ export interface ModelRequest {
      * request on.
      */
     model: string;
-    /** The system prompt. */
+    /**
+     * The system prompt. Only text that is the same from one request of the
+     * agent to the next belongs here: every provider caches the prompt as a
+     * prefix (tools, then system, then the history), so a word that changes
+     * here misses the whole history behind it. Text for this step alone goes
+     * in `turnNotes`.
+     */
     system?: string;
     /** The conversation, oldest first. */
     messages: Message[];
+    /**
+     * Text the model reads this step that is not part of the durable
+     * instruction: recalled facts, a note for this turn. Each adapter places
+     * it after the history, where it leaves the cached prefix alone: as text
+     * at the end of the last user message, or as a user message of its own
+     * when the history ends on tool results. Absent means none.
+     */
+    turnNotes?: string;
     /** Client-side tools. */
     tools?: ToolDeclaration[];
     /** Provider-side tools, by name. */

package/dist/lib/models/errorResponse.d.ts

@@ -33,6 +33,10 @@ export declare const ERROR_STATUS_KEY = "error.status";
 export declare function errorText(err: unknown): string;
 /** What a caught error says about trying again. A cancellation never is retryable. */
 export declare function errorDecision(err: unknown): RetryDecision;
+export declare function isContextOverflow(error: {
+    message?: string;
+    status?: number;
+} | undefined): boolean;
 /** What a non-2xx HTTP status says about trying again. */
 export declare function statusDecision(status: number): RetryDecision;
 /**

package/dist/lib/models/errorResponse.js

@@ -14,6 +14,31 @@ export function errorDecision(err) {
     const decision = classifyError(err);
     return err?.name === 'AbortError' ? { ...decision, retryable: false } : decision;
 }
+/**
+ * The provider refused the request because the prompt no longer fits the
+ * model's window (ADR 0154): a 400 (or 413, or a status it did not give)
+ * whose message says so in one of the providers' spellings. The loop
+ * answers it with a forced compaction and one retry; the fallback never
+ * redirects it (it is the request's fault, not the provider's).
+ *
+ *   Anthropic  "prompt is too long: 213463 tokens > 200000 maximum"
+ *   OpenAI     "This model's maximum context length is 128000 tokens …" /
+ *              "Your input exceeds the context window of this model" (context_length_exceeded)
+ *   Gemini     "The input token count (…) exceeds the maximum number of tokens allowed (…)"
+ *   xAI        "This model's maximum prompt length is 131072 …"
+ *   Moonshot   "Your request exceeded model token limit: 262144"
+ *   DeepSeek   "This model's maximum context length is 1000000 tokens …"
+ *   llama.cpp  "the request exceeds the available context size"
+ *   Ollama reports nothing: it truncates the prompt instead.
+ */
+const OVERFLOW_MESSAGE = /prompt is too long|context[_ ]length|context window|maximum (?:prompt|context) length|input token count .*exceeds|exceeds the (?:available )?context|exceeded model token limit|request_too_large|input is too long|too many tokens/i;
+export function isContextOverflow(error) {
+    if (!error?.message)
+        return false;
+    if (error.status !== undefined && error.status !== 400 && error.status !== 413)
+        return false;
+    return OVERFLOW_MESSAGE.test(error.message);
+}
 /** What a non-2xx HTTP status says about trying again. */
 export function statusDecision(status) {
     return { retryable: isRetryableStatus(status), status };

package/dist/lib/models/geminiAdapter.js

@@ -249,6 +249,15 @@ function buildRequest(request, options) {
         if (parts.length)
             contents.push({ role: message.role === 'assistant' ? 'model' : 'user', parts });
     });
+    // This step's notes, after the history, on the last user content (function
+    // responses are user content too), so the cached prefix before it holds.
+    if (request.turnNotes) {
+        const last = contents[contents.length - 1];
+        if (last?.role === 'user')
+            last.parts.push({ text: request.turnNotes });
+        else
+            contents.push({ role: 'user', parts: [{ text: request.turnNotes }] });
+    }
     const config = {};
     if (system.length)
         config.systemInstruction = { parts: system.map((text) => ({ text })) };