@zenera/neo 1.1.10 → 1.1.12

package/dist/models/factory.js

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { GeminiEmbedder } from "../embeddings/gemini.js";
+import { DEFAULT_START, RateLimiter } from "../embeddings/limiter.js";
 import { OpenAIEmbedder } from "../embeddings/openai.js";
 import { OpenRouterEmbedder } from "../embeddings/openrouter.js";
 import { AnthropicModel } from "./anthropic.js";
@@ -159,6 +160,7 @@ function expand(value, where) {
 export class ModelRegistry {
     #providers = new Map();
     #clients = new Map();
+    #limiters = new Map();
     #default = 'openai';
     /** Declares (or replaces) a provider. Nothing is contacted until it is used. */
     provider(name, spec = {}) {
@@ -170,6 +172,7 @@ export class ModelRegistry {
         // Re-declaring after a client was handed out would otherwise leave the
         // old credentials in service for the rest of the process.
         this.#clients.delete(name);
+        this.#limiters.delete(name);
         return this;
     }
     /** Names the provider a bare model id belongs to. */
@@ -201,6 +204,27 @@ export class ModelRegistry {
         this.#clients.set(name, built);
         return built;
     }
+    /**
+     * The pacing shared by every embedder on a provider, so that what one of
+     * them learns from a 429 the others do not have to learn again — and so
+     * that two of them cannot each ramp up to the full limit against one key.
+     */
+    #limiter(name) {
+        const existing = this.#limiters.get(name);
+        if (existing) {
+            return existing;
+        }
+        const spec = this.#providers.get(name);
+        const built = new RateLimiter({
+            max: spec?.concurrency,
+            start: spec?.concurrency === undefined
+                ? undefined
+                : Math.min(spec.concurrency, DEFAULT_START),
+            maxRetries: spec?.maxRetries,
+        });
+        this.#limiters.set(name, built);
+        return built;
+    }
     /** Turns a shorthand or a spec into a `Model`. */
     model(ref) {
         const spec = typeof ref === 'string' ? this.parse(ref) : ref;
@@ -213,6 +237,10 @@ export class ModelRegistry {
         // silently ignore them.
         const client = spec.client ??
             (hasCredentials(spec) ? buildClient(name, kind, spec, provider) : this.client(name));
+        // The *resolved* name, not `spec.provider`: a bare ref carries none,
+        // and a failure that cannot say which connection refused it is the
+        // thing this is here to prevent.
+        const options = { ...spec, provider: name };
         // Every protocol but OpenAI's has exactly one API, so naming one is a
         // mistake worth reporting rather than a field to ignore.
         if (defaults.protocol !== 'openai') {
@@ -221,11 +249,11 @@ export class ModelRegistry {
             }
             switch (defaults.protocol) {
                 case 'anthropic':
-                    return new AnthropicModel(spec.model, client, spec);
+                    return new AnthropicModel(spec.model, client, options);
                 case 'gemini':
-                    return new GeminiModel(spec.model, client, spec);
+                    return new GeminiModel(spec.model, client, options);
                 case 'openrouter':
-                    return new OpenRouterModel(spec.model, client, spec);
+                    return new OpenRouterModel(spec.model, client, options);
             }
         }
         const api = spec.api ?? defaults.apis[0];
@@ -234,8 +262,8 @@ export class ModelRegistry {
                 `(supported: ${defaults.apis.join(', ')})`);
         }
         return api === 'responses'
-            ? new OpenAIResponsesModel(spec.model, client, spec)
-            : new OpenAIModel(spec.model, client, spec);
+            ? new OpenAIResponsesModel(spec.model, client, options)
+            : new OpenAIModel(spec.model, client, options);
     }
     /**
      * Turns a shorthand or a spec into an `Embedder`, over the same providers
@@ -243,19 +271,26 @@ export class ModelRegistry {
      * generates and embeds without being mentioned twice.
      */
     embedder(ref) {
-        const spec = typeof ref === 'string' ? this.#parseEmbedding(ref) : ref;
+        const spec = typeof ref === 'string' ? this.parseEmbedding(ref) : ref;
         const name = spec.provider ?? this.#default;
         const provider = this.#spec(name);
         const kind = this.kindOf(name);
         const client = spec.client ??
             (hasCredentials(spec) ? buildClient(name, kind, spec, provider) : this.client(name));
+        // Inline credentials are a different connection, and so a different
+        // budget: they get pacing of their own rather than the provider's.
+        const options = {
+            ...spec,
+            provider: name,
+            limiter: spec.limiter ?? (hasCredentials(spec) ? undefined : this.#limiter(name)),
+        };
         switch (KINDS[kind].protocol) {
             case 'openai':
-                return new OpenAIEmbedder(spec.model, client, spec);
+                return new OpenAIEmbedder(spec.model, client, options);
             case 'gemini':
-                return new GeminiEmbedder(spec.model, client, spec);
+                return new GeminiEmbedder(spec.model, client, options);
             case 'openrouter':
-                return new OpenRouterEmbedder(spec.model, client, spec);
+                return new OpenRouterEmbedder(spec.model, client, options);
             case 'anthropic':
                 // Not an omission to be filled in later: Anthropic publishes no
                 // embeddings API at all, and points at third parties instead.
@@ -318,7 +353,11 @@ export class ModelRegistry {
         }
         return { provider, api, model };
     }
-    #parseEmbedding(ref) {
+    /**
+     * Splits `[provider:]model` into the spec it stands for, so a caller holding
+     * a shorthand can still set the knobs a shorthand has no room for.
+     */
+    parseEmbedding(ref) {
         const { provider, api, model } = this.parse(ref);
         if (api) {
             throw new TypeError(`"${ref}": embeddings have one api, so "${api}" means nothing here`);

package/dist/models/gemini.d.ts

@@ -1,5 +1,6 @@
 import type { GoogleGenAI } from '@google/genai';
 import type { StreamDelta } from '../events.ts';
+import { type ProviderNamed } from '../failure.ts';
 import type { Model, ModelRequest, ModelResponse } from '../model.ts';
 /** The coarse dial Gemini 3 takes in place of a token budget. */
 export type GeminiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
@@ -11,7 +12,7 @@ export type GeminiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
  * 3 takes a coarse `thinkingLevel`, and passing the wrong one is an API error
  * rather than something this adapter can paper over.
  */
-export interface GeminiModelOptions {
+export interface GeminiModelOptions extends ProviderNamed {
     /** hard cap on output tokens; the model's own default applies when unset */
     maxTokens?: number;
     /** 2.5-era budget, in tokens: `0` disables thinking, `-1` lets the model decide */

package/dist/models/gemini.js

@@ -1,3 +1,4 @@
+import { callSites, called, reading } from "../failure.js";
 import { zeroUsage, } from "../types.js";
 /**
  * Google's `ThinkingLevel` is a *string* enum, so its members are just their
@@ -40,14 +41,16 @@ export class GeminiModel {
     id;
     #client;
     #options;
+    #site;
     #nextId = 0;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#options = options;
+        this.#site = callSites(id, options.provider);
     }
     async generate(req) {
-        const res = await this.#client.models.generateContent(this.#params(req));
+        const res = await called(this.#site('llm generation', 'models.generateContent'), () => this.#client.models.generateContent(this.#params(req)));
         const read = emptyRead();
         for (const part of candidateParts(res)) {
             this.#readPart(part, read);
@@ -55,10 +58,12 @@ export class GeminiModel {
         return this.#finish(read, res);
     }
     async stream(req, onDelta) {
-        const stream = await this.#client.models.generateContentStream(this.#params(req));
+        const site = this.#site('llm streaming', 'models.generateContentStream');
+        const open = () => this.#client.models.generateContentStream(this.#params(req));
+        const stream = await called(site, open);
         const read = emptyRead();
         let last;
-        for await (const chunk of stream) {
+        for await (const chunk of reading(site, stream, open)) {
             last = chunk;
             for (const part of candidateParts(chunk)) {
                 this.#readPart(part, read, onDelta);

package/dist/models/openai-chat.d.ts

@@ -1,12 +1,13 @@
 import type OpenAI from 'openai';
 import type { StreamDelta } from '../events.ts';
+import { type ProviderNamed } from '../failure.ts';
 import type { Model, ModelRequest, ModelResponse } from '../model.ts';
 /**
  * Provider-specific knobs. Reasoning effort is deliberately *not* part of
  * `ModelRequest`: every provider spells it differently (and most models ignore
  * it), so it belongs to the concrete adapter rather than the `Model` contract.
  */
-export interface OpenAIModelOptions {
+export interface OpenAIModelOptions extends ProviderNamed {
     reasoningEffort?: OpenAI.ReasoningEffort;
 }
 export declare class OpenAIModel implements Model {

package/dist/models/openai-chat.js

@@ -1,5 +1,8 @@
 var _a;
+import { callSites, called, reading } from "../failure.js";
 import { zeroUsage } from "../types.js";
+/** The SDK call these methods make, named as it is named in a failure. */
+const API = 'chat.completions.create';
 // ---------------------------------------------------------------------------
 // OpenAI chat-completions adapter
 // ---------------------------------------------------------------------------
@@ -20,15 +23,15 @@ export class OpenAIModel {
     id;
     #client;
     #reasoningEffort;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#reasoningEffort = options.reasoningEffort;
+        this.#site = callSites(id, options.provider);
     }
     async generate(req) {
-        const res = await this.#client.chat.completions.create(this.#params(req), {
-            signal: req.signal,
-        });
+        const res = await called(this.#site('llm generation', API), () => this.#client.chat.completions.create(this.#params(req), { signal: req.signal }));
         const choice = res.choices[0];
         const message = choice?.message;
         return {
@@ -42,7 +45,9 @@ export class OpenAIModel {
         };
     }
     async stream(req, onDelta) {
-        const stream = await this.#client.chat.completions.create({ ...this.#params(req), stream: true, stream_options: { include_usage: true } }, { signal: req.signal });
+        const site = this.#site('llm streaming', API);
+        const open = () => this.#client.chat.completions.create({ ...this.#params(req), stream: true, stream_options: { include_usage: true } }, { signal: req.signal });
+        const stream = await called(site, open);
         let text = '';
         let thinking = '';
         let usage;
@@ -50,7 +55,7 @@ export class OpenAIModel {
         // Tool calls arrive as deltas keyed by index, with the id and name in the
         // first fragment and arguments trickling in afterwards.
         const calls = new Map();
-        for await (const chunk of stream) {
+        for await (const chunk of reading(site, stream, open)) {
             if (chunk.usage) {
                 usage = toUsage(chunk.usage);
             }

package/dist/models/openai-responses.d.ts

@@ -1,11 +1,12 @@
 import type OpenAI from 'openai';
 import type { StreamDelta } from '../events.ts';
+import { type ProviderNamed } from '../failure.ts';
 import type { Model, ModelRequest, ModelResponse } from '../model.ts';
 /**
  * Provider-specific knobs, mirroring `OpenAIModelOptions` but expressed the way
  * the responses API spells them.
  */
-export interface OpenAIResponsesModelOptions {
+export interface OpenAIResponsesModelOptions extends ProviderNamed {
     reasoningEffort?: OpenAI.ReasoningEffort;
     /** ask the model for a reasoning summary — the only reasoning text this API exposes */
     reasoningSummary?: 'auto' | 'concise' | 'detailed';

package/dist/models/openai-responses.js

@@ -1,5 +1,8 @@
 var _a;
+import { callSites, called, failed, reading, } from "../failure.js";
 import { zeroUsage } from "../types.js";
+/** The SDK call these methods make, named as it is named in a failure. */
+const API = 'responses.create';
 /**
  * Same `Model` contract as `OpenAIModel`, over `/v1/responses` instead of
  * `/v1/chat/completions`. Reasoning models are the reason to prefer it: effort
@@ -11,17 +14,17 @@ export class OpenAIResponsesModel {
     #reasoningEffort;
     #reasoningSummary;
     #store;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#reasoningEffort = options.reasoningEffort;
         this.#reasoningSummary = options.reasoningSummary;
         this.#store = options.store ?? false;
+        this.#site = callSites(id, options.provider);
     }
     async generate(req) {
-        const res = await this.#client.responses.create(this.#params(req), {
-            signal: req.signal,
-        });
+        const res = await called(this.#site('llm generation', API), () => this.#client.responses.create(this.#params(req), { signal: req.signal }));
         const toolCalls = readToolCalls(res.output);
         return {
             text: readText(res.output),
@@ -32,7 +35,11 @@ export class OpenAIResponsesModel {
         };
     }
     async stream(req, onDelta) {
-        const stream = await this.#client.responses.create({ ...this.#params(req), stream: true }, { signal: req.signal });
+        const site = this.#site('llm streaming', API);
+        const open = () => this.#client.responses.create({ ...this.#params(req), stream: true }, {
+            signal: req.signal,
+        });
+        const stream = await called(site, open);
         let text = '';
         let thinking = '';
         let final;
@@ -40,7 +47,7 @@ export class OpenAIResponsesModel {
         // every delta event carries — that is the only stable key while the
         // items are still being assembled.
         const calls = new Map();
-        for await (const event of stream) {
+        for await (const event of reading(site, stream, open)) {
             // Some models/gateways emit `response.reasoning.delta`, which the
             // SDK does not carry in its event union, so it is matched before
             // the typed switch.
@@ -103,9 +110,17 @@ export class OpenAIResponsesModel {
                     }
                     break;
                 }
-                case 'response.completed':
-                case 'response.incomplete':
                 case 'response.failed': {
+                    // The request was accepted, so the refusal arrives as an
+                    // event in a 200 rather than as a status. Returning it as a
+                    // response would make it an empty answer.
+                    const said = event.response.error;
+                    throw failed(site, Object.assign(new Error(said?.message ?? 'the response failed'), {
+                        code: said?.code,
+                    }));
+                }
+                case 'response.completed':
+                case 'response.incomplete': {
                     final = event.response;
                     break;
                 }

package/dist/models/openrouter.d.ts

@@ -1,6 +1,7 @@
 import type { OpenRouter } from '@openrouter/sdk';
 import type { ChatRequestPlugin, ProviderPreferences } from '@openrouter/sdk/models';
 import type { StreamDelta } from '../events.ts';
+import { type ProviderNamed } from '../failure.ts';
 import type { Model, ModelRequest, ModelResponse } from '../model.ts';
 /**
  * Which failures the SDK's backoff applies to: rate limits, request timeouts,
@@ -21,7 +22,7 @@ export declare const RETRY_STATUS_CODES: string[];
  */
 export type OpenRouterEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null;
 /** Provider-specific knobs. */
-export interface OpenRouterModelOptions {
+export interface OpenRouterModelOptions extends ProviderNamed {
     reasoningEffort?: OpenRouterEffort;
     /** ask for a reasoning summary from models that expose one */
     reasoningSummary?: 'auto' | 'concise' | 'detailed';

package/dist/models/openrouter.js

@@ -1,4 +1,5 @@
 var _a;
+import { callSites, called, reading } from "../failure.js";
 import { zeroUsage } from "../types.js";
 // ---------------------------------------------------------------------------
 // OpenRouter adapter
@@ -72,13 +73,15 @@ export class OpenRouterModel {
     id;
     #client;
     #options;
+    #site;
     constructor(id, client, options = {}) {
         this.id = id;
         this.#client = client;
         this.#options = options;
+        this.#site = callSites(id, options.provider);
     }
     async generate(req) {
-        const res = await this.#send(req, false);
+        const res = await called(this.#site('llm generation', 'chat.send'), () => this.#send(req, false));
         // Both overloads are declared to return the same union, so the narrowing
         // the `stream` flag implies has to be done here.
         if (Symbol.asyncIterator in res) {
@@ -99,10 +102,15 @@ export class OpenRouterModel {
         };
     }
     async stream(req, onDelta) {
-        const res = await this.#send(req, true);
-        if (!(Symbol.asyncIterator in res)) {
-            throw new Error(`model "${this.id}": asked for a stream, got one completion`);
-        }
+        const site = this.#site('llm streaming', 'chat.send');
+        const open = async () => {
+            const res = await this.#send(req, true);
+            if (!(Symbol.asyncIterator in res)) {
+                throw new Error(`model "${this.id}": asked for a stream, got one completion`);
+            }
+            return res;
+        };
+        const res = await called(site, open);
         let text = '';
         let thinking = '';
         let usage;
@@ -110,7 +118,7 @@ export class OpenRouterModel {
         // Tool calls arrive as deltas keyed by index, with the id and name in the
         // first fragment and arguments trickling in afterwards.
         const calls = new Map();
-        for await (const chunk of res) {
+        for await (const chunk of reading(site, res, open)) {
             // An upstream failure mid-stream arrives as a chunk on a 200, so it
             // has to be raised here or the turn ends early and looks complete.
             if (chunk.error) {

package/dist/project/config.d.ts

@@ -18,6 +18,7 @@ declare const provider: z.ZodObject<{
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     maxRetries: z.ZodOptional<z.ZodInt>;
+    concurrency: z.ZodOptional<z.ZodInt>;
     apiKey: z.ZodOptional<z.ZodString>;
     apiKeyEnv: z.ZodOptional<z.ZodString>;
     baseURL: z.ZodOptional<z.ZodString>;
@@ -47,10 +48,10 @@ declare const modelSpec: z.ZodObject<{
     thinkingBudgetTokens: z.ZodOptional<z.ZodInt>;
     thinkingBudget: z.ZodOptional<z.ZodInt>;
     thinkingLevel: z.ZodOptional<z.ZodEnum<{
-        minimal: "minimal";
         low: "low";
         medium: "medium";
         high: "high";
+        minimal: "minimal";
     }>>;
     includeThoughts: z.ZodOptional<z.ZodBoolean>;
     routing: z.ZodOptional<z.ZodObject<{
@@ -93,6 +94,7 @@ declare const embeddingSpec: z.ZodObject<{
     dimensions: z.ZodOptional<z.ZodInt>;
     title: z.ZodOptional<z.ZodString>;
     maxBatch: z.ZodOptional<z.ZodInt>;
+    maxBatchTokens: z.ZodOptional<z.ZodInt>;
     routing: z.ZodOptional<z.ZodObject<{
         order: z.ZodOptional<z.ZodArray<z.ZodString>>;
         only: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -112,6 +114,34 @@ declare const embeddingSpec: z.ZodObject<{
     baseURL: z.ZodOptional<z.ZodString>;
     baseURLEnv: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/**
+ * What an agent may do with the project's one memory graph, and which slice of
+ * it it can see. Both lists are audience labels; `'*'` is the public slice and
+ * is always readable, so `sees` can only ever widen from there.
+ *
+ * `sees` and `writes` are here and not in any tool schema on purpose: an agent
+ * that could name its own audience could read another agent's slice just by
+ * asking for it.
+ */
+declare const memoryBinding: z.ZodObject<{
+    access: z.ZodDefault<z.ZodEnum<{
+        read: "read";
+        "read-write": "read-write";
+        full: "full";
+    }>>;
+    sees: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    writes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    autoRecall: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        limit: z.ZodDefault<z.ZodInt>;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+/** Where the project's memory lives, and what vectorises it. */
+declare const memoryConfig: z.ZodObject<{
+    dir: z.ZodDefault<z.ZodString>;
+    embedding: z.ZodOptional<z.ZodString>;
+    kinds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    relations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
 /**
  * A Dockerfile to build instead of an image to pull, for the ordinary case the
  * `image:` key cannot serve: a project that needs two runtimes, or a pinned
@@ -161,6 +191,7 @@ export declare const projectSchema: z.ZodObject<{
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         maxRetries: z.ZodOptional<z.ZodInt>;
+        concurrency: z.ZodOptional<z.ZodInt>;
         apiKey: z.ZodOptional<z.ZodString>;
         apiKeyEnv: z.ZodOptional<z.ZodString>;
         baseURL: z.ZodOptional<z.ZodString>;
@@ -185,10 +216,10 @@ export declare const projectSchema: z.ZodObject<{
         thinkingBudgetTokens: z.ZodOptional<z.ZodInt>;
         thinkingBudget: z.ZodOptional<z.ZodInt>;
         thinkingLevel: z.ZodOptional<z.ZodEnum<{
-            minimal: "minimal";
             low: "low";
             medium: "medium";
             high: "high";
+            minimal: "minimal";
         }>>;
         includeThoughts: z.ZodOptional<z.ZodBoolean>;
         routing: z.ZodOptional<z.ZodObject<{
@@ -226,6 +257,7 @@ export declare const projectSchema: z.ZodObject<{
         dimensions: z.ZodOptional<z.ZodInt>;
         title: z.ZodOptional<z.ZodString>;
         maxBatch: z.ZodOptional<z.ZodInt>;
+        maxBatchTokens: z.ZodOptional<z.ZodInt>;
         routing: z.ZodOptional<z.ZodObject<{
             order: z.ZodOptional<z.ZodArray<z.ZodString>>;
             only: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -268,6 +300,12 @@ export declare const projectSchema: z.ZodObject<{
         env: z.ZodOptional<z.ZodArray<z.ZodString>>;
         keys: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
+    memory: z.ZodOptional<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+        embedding: z.ZodOptional<z.ZodString>;
+        kinds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        relations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     agents: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
@@ -278,8 +316,8 @@ export declare const projectSchema: z.ZodObject<{
         skills: z.ZodOptional<z.ZodObject<{
             provider: z.ZodOptional<z.ZodString>;
             discovery: z.ZodDefault<z.ZodEnum<{
-                search: "search";
                 none: "none";
+                search: "search";
                 index: "index";
             }>>;
             allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -290,6 +328,18 @@ export declare const projectSchema: z.ZodObject<{
             agents: z.ZodOptional<z.ZodArray<z.ZodString>>;
             maxBranches: z.ZodOptional<z.ZodInt>;
         }, z.core.$strict>]>>;
+        memory: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodObject<{
+            access: z.ZodDefault<z.ZodEnum<{
+                read: "read";
+                "read-write": "read-write";
+                full: "full";
+            }>>;
+            sees: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            writes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            autoRecall: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+                limit: z.ZodDefault<z.ZodInt>;
+            }, z.core.$strict>]>>;
+        }, z.core.$strict>>>>;
         sandbox: z.ZodOptional<z.ZodObject<{
             image: z.ZodOptional<z.ZodString>;
             build: z.ZodOptional<z.ZodObject<{
@@ -320,6 +370,8 @@ export type ModelConfig = z.infer<typeof modelSpec>;
 export type EmbeddingConfig = z.infer<typeof embeddingSpec>;
 export type SandboxConfig = z.infer<typeof sandbox>;
 export type SandboxBuildConfig = z.infer<typeof build>;
+export type MemoryConfig = z.infer<typeof memoryConfig>;
+export type MemoryBindingConfig = z.infer<typeof memoryBinding>;
 /**
  * Re-renders a zod failure as `agents.yaml: agents[1].skills.discovery — …`.
  *

package/dist/project/config.js

@@ -46,6 +46,13 @@ const provider = z
     headers: z.record(z.string().min(1), z.string()).optional(),
     timeoutMs: z.number().positive().optional(),
     maxRetries: z.int().nonnegative().optional(),
+    /**
+     * Ceiling on embedding requests in flight against this connection. The
+     * working number is discovered from the provider's own refusals; this
+     * only caps how high that may climb, for a key shared with something
+     * else that also needs quota.
+     */
+    concurrency: z.int().positive().optional(),
 })
     .strict();
 /**
@@ -120,8 +127,13 @@ const embeddingSpec = z
     dimensions: z.int().positive().optional(),
     /** gemini only: a document title the retrieval task type takes into account */
     title: z.string().min(1).optional(),
-    /** gemini only: texts per request; every `gemini-embedding-*` model takes one */
+    /**
+     * Ceilings on how a batch is split into requests. Both default to what
+     * the model is known to accept, so setting them is for a gateway whose
+     * caps are not the vendor's.
+     */
     maxBatch: z.int().positive().optional(),
+    maxBatchTokens: z.int().positive().optional(),
     /** openrouter only: who serves the request */
     routing: routing.optional(),
 })
@@ -156,6 +168,52 @@ const forkBinding = z
     maxBranches: z.int().min(2).optional(),
 })
     .strict();
+/**
+ * What an agent may do with the project's one memory graph, and which slice of
+ * it it can see. Both lists are audience labels; `'*'` is the public slice and
+ * is always readable, so `sees` can only ever widen from there.
+ *
+ * `sees` and `writes` are here and not in any tool schema on purpose: an agent
+ * that could name its own audience could read another agent's slice just by
+ * asking for it.
+ */
+const memoryBinding = z
+    .object({
+    access: z.enum(['read', 'read-write', 'full']).default('read-write'),
+    /** audience labels this agent may read, on top of the public slice */
+    sees: z.array(name).optional(),
+    /** labels it may put on what it writes */
+    writes: z.array(name).optional(),
+    /**
+     * Recall before a turn that follows new user input, rather than before
+     * every call: recalling on every turn costs tokens and defeats prompt
+     * caching for a marginal gain. `false` leaves the agent the tools and
+     * lets it decide when to look.
+     */
+    autoRecall: z
+        .union([z.boolean(), z.object({ limit: z.int().positive().default(5) }).strict()])
+        .optional(),
+})
+    .strict();
+/** Where the project's memory lives, and what vectorises it. */
+const memoryConfig = z
+    .object({
+    /** relative to the project root */
+    dir: z.string().min(1).default('memory'),
+    /**
+     * A name from `embeddings:`. Without one, recall ranks by term overlap
+     * — which works, but only finds the words the agent happened to reuse.
+     */
+    embedding: modelRef.optional(),
+    /**
+     * Closed vocabularies. Absent means the built-in sets, which is almost
+     * always right: a kind nothing else understands is a kind no other
+     * agent can search for.
+     */
+    kinds: z.array(name).min(1).optional(),
+    relations: z.array(name).min(1).optional(),
+})
+    .strict();
 /**
  * The container command-line tools run in.
  *
@@ -263,6 +321,17 @@ const agent = z
     skills: skillsBinding.optional(),
     /** parallel sub-agents; `true` is the unrestricted form */
     fork: z.union([z.boolean(), forkBinding]).optional(),
+    /**
+     * The shared memory graph. `true` is the whole feature working the
+     * obvious way — read and write, with auto-recall on.
+     *
+     * Normalised before validation rather than unioned with a boolean, so
+     * that a misspelled key inside the block is reported as
+     * `agents[0].memory.scope` instead of collapsing to "invalid input".
+     */
+    memory: z
+        .preprocess((v) => (typeof v === 'boolean' ? (v ? {} : undefined) : v), memoryBinding.optional())
+        .optional(),
     /**
      * Overrides on the project's sandbox. An agent that overrides nothing
      * shares the container with everyone else, which is what a hand-off
@@ -304,6 +373,12 @@ export const projectSchema = z
     assets: z.string().min(1).optional(),
     /** the container `run_command` and friends execute in */
     sandbox: sandbox.optional(),
+    /**
+     * The one graph every agent's `memory:` binding is a view onto. Declare
+     * it to choose where it lives or what embeds it; an agent that opts in
+     * without this block gets the defaults.
+     */
+    memory: memoryConfig.optional(),
     agents: z.array(agent).min(1),
 })
     .strict();

package/dist/project/index.d.ts

@@ -1,4 +1,4 @@
-export { parseConfig, projectSchema, type AgentConfig, type EmbeddingConfig, type ModelConfig, type ProjectConfig, type ProviderConfig, type SandboxBuildConfig, type SandboxConfig, } from './config.ts';
-export { AgentProject, assetsDir, loadProject, projectRegistry, readProjectConfig, skillDirs, skillMounts, type ProjectOptions, type ProjectSource, } from './load.ts';
+export { parseConfig, projectSchema, type AgentConfig, type EmbeddingConfig, type MemoryBindingConfig, type MemoryConfig, type ModelConfig, type ProjectConfig, type ProviderConfig, type SandboxBuildConfig, type SandboxConfig, } from './config.ts';
+export { AgentProject, assetsDir, loadProject, memoryDir, projectRegistry, readProjectConfig, skillDirs, skillMounts, type ProjectOptions, type ProjectSource, } from './load.ts';
 export { projectDir, projectFile, projectPath, projectRoot } from './refs.ts';
 //# sourceMappingURL=index.d.ts.map