@anteros/core 0.0.42 → 0.0.44

package/tests/replication-change-stream.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Change-stream replication — the **default** mode (`replication.mode` unset).
+ *
+ * What separates it from the scan engine, and what these cases pin down:
+ *  - nothing has to be triggered: a write reaches the destination on its own;
+ *  - deletes come from the oplog, so a collection **without hooks** propagates them
+ *    too (the scan engine can only see applicative tombstones, which is why an
+ *    `_audit_` entry deleted out of band used to survive on the destination);
+ *  - the position is a resume token, not a date cursor;
+ *  - the stream owns a collection, so a one-shot run leaves it alone;
+ *  - `reset()` re-arms the stream, which cold-starts again.
+ */
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants } from "../database/tenant";
+import { syncCollections } from "../database/collection";
+import { syncVars } from "../database/vars";
+import {
+    startReplication,
+    stopReplication,
+    replicateTenant,
+    getReplicationState,
+    resetReplication,
+} from "../database/replication";
+import { AUDIT_COLLECTION } from "../database/audit";
+
+const ORDERS_T = "cs-orders";
+const ORDERS_DIR = "packages/core/tests/fixtures/replication-meta";
+const ORDERS_SRC = "mongodb://localhost:27017/_CS_SRC";
+const ORDERS_DST = "mongodb://localhost:27017/_CS_DST";
+const DEST_ID = "backup";
+
+const VARS_T = "cs-vars";
+const VARS_DIR = "packages/core/tests/fixtures/vars-tenant";
+const VARS_SRC = "mongodb://localhost:27017/_CS_VARS_SRC";
+const VARS_DST = "mongodb://localhost:27017/_CS_VARS_DST";
+
+let rest: InstanceType<typeof useRest>;
+let restVars: InstanceType<typeof useRest>;
+let src: MongoClient;
+let dest: MongoClient;
+let varsDest: MongoClient;
+
+/** Poll `check` until it holds — a change stream is asynchronous by nature. */
+async function waitFor(check: () => Promise<boolean>, timeout = 8_000, step = 50): Promise<boolean> {
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        if (await check()) return true;
+        await Bun.sleep(step);
+    }
+    return false;
+}
+
+const ordersDest = () => dest.db().collection("orders");
+const auditDest = () => dest.db().collection(AUDIT_COLLECTION);
+const varsOnDest = (ns: string, key: string) => varsDest.db().collection("_vars_").findOne({ ns, key });
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [
+            {
+                id: ORDERS_T,
+                dir: ORDERS_DIR,
+                database: { uri: ORDERS_SRC },
+                // No `mode`: change streams are the default. No `key`, no `batchSize`,
+                // no `schedule` either — the stream is the whole engine.
+                replication: { runOnBoot: false, destinations: [{ id: DEST_ID, uri: ORDERS_DST }] },
+            },
+            {
+                id: VARS_T,
+                dir: VARS_DIR,
+                database: { uri: VARS_SRC },
+                replication: { runOnBoot: false, destinations: [{ id: "backup", uri: VARS_DST }] },
+            },
+        ],
+    });
+
+    await syncTenants();
+    await syncCollections();
+    await syncVars();
+    await startReplication();
+
+    rest = new useRest({ tenant_id: ORDERS_T });
+    restVars = new useRest({ tenant_id: VARS_T });
+    src = new MongoClient(ORDERS_SRC, { serverSelectionTimeoutMS: 3000 });
+    dest = new MongoClient(ORDERS_DST, { serverSelectionTimeoutMS: 3000 });
+    varsDest = new MongoClient(VARS_DST, { serverSelectionTimeoutMS: 3000 });
+    await Promise.all([src.connect(), dest.connect(), varsDest.connect()]);
+});
+
+afterAll(async () => {
+    await stopReplication();
+    for (const uri of [ORDERS_SRC, ORDERS_DST, VARS_SRC, VARS_DST]) {
+        try {
+            const client = new MongoClient(uri);
+            await client.connect();
+            await client.db().dropDatabase();
+            await client.close();
+        } catch (_) {}
+    }
+    cfg.agents = [];
+    cfg.agentMemories = [];
+    try { await src.close(); } catch (_) {}
+    try { await dest.close(); } catch (_) {}
+    try { await varsDest.close(); } catch (_) {}
+});
+
+describe("replication — changeStream mode", () => {
+    it("replicates a write on its own, with no run to trigger", async () => {
+        const marker = `cs-insert-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: marker });
+
+        // No `replicateTenant()` call anywhere: the stream is the engine
+        expect(await waitFor(async () => Boolean(await ordersDest().findOne({ title: marker })))).toBe(true);
+    });
+
+    it("replicates an update in place", async () => {
+        const marker = `cs-update-${crypto.randomUUID()}`;
+        const doc: any = await rest.insertOne("orders", { title: marker });
+        expect(await waitFor(async () => Boolean(await ordersDest().findOne({ title: marker })))).toBe(true);
+
+        await rest.updateOne("orders", doc._id, { $set: { title: `${marker}-paid` } });
+        expect(await waitFor(async () => (await ordersDest().countDocuments({ title: `${marker}-paid` })) === 1)).toBe(true);
+    });
+
+    it("propagates a delete without writing a tombstone", async () => {
+        const marker = `cs-delete-${crypto.randomUUID()}`;
+        const doc: any = await rest.insertOne("orders", { title: marker });
+        expect(await waitFor(async () => Boolean(await ordersDest().findOne({ title: marker })))).toBe(true);
+
+        await rest.deleteOne("orders", doc._id);
+        expect(await waitFor(async () => (await ordersDest().countDocuments({ title: marker })) === 0)).toBe(true);
+
+        // The oplog carried it: the hook + tombstone path is not even installed here
+        const tombstones = await src.db().collection("_replication_").countDocuments({ type: "delete", collection: "orders" });
+        expect(tombstones).toBe(0);
+    });
+
+    it("propagates a delete on a framework collection no hook can see", async () => {
+        const marker = `cs-audit-${crypto.randomUUID()}`;
+        await rest.audit.addActivities([{
+            internal: true,
+            trace: { id: crypto.randomUUID() },
+            meta: {},
+            operation: {
+                tenant: ORDERS_T, action: marker, collection: "orders",
+                status: "success", input: null, result: null, error: null, duration: 0, transaction: false,
+            },
+            ts: new Date(),
+        } as any]);
+        expect(await waitFor(async () => Boolean(await auditDest().findOne({ "operation.action": marker })))).toBe(true);
+
+        // Out of band: no applicative hook runs, no tombstone is written — the scan
+        // engine would leave this entry on the destination forever
+        await src.db().collection(AUDIT_COLLECTION).deleteOne({ "operation.action": marker } as any);
+
+        expect(await waitFor(async () => (await auditDest().countDocuments({ "operation.action": marker })) === 0)).toBe(true);
+    }, 20_000);
+
+    it("stores a resume token in `_replication_`, tagged with the mode", async () => {
+        const [state] = await getReplicationState(ORDERS_T, DEST_ID, "orders");
+        expect(state?.mode).toBe("changeStream");
+        expect(state?.resumeToken).toBeDefined();
+        expect(state?.status).toBe("watching");
+    });
+
+    it("leaves a streamed collection alone when a run is triggered", async () => {
+        const results = await replicateTenant(ORDERS_T);
+
+        // The stream owns it: a scan on top would let a stale read overwrite a fresh
+        // event, so the run reports nothing for that collection
+        expect(results.find((result) => result.collection === "orders")).toBeUndefined();
+    });
+
+    it("cold-starts again after `reset()` — the position is really cleared", async () => {
+        const marker = `cs-reset-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: marker });
+        expect(await waitFor(async () => Boolean(await ordersDest().findOne({ title: marker })))).toBe(true);
+
+        // Lose the copy, then forget the position: only a backfill can bring it back
+        await ordersDest().deleteMany({});
+        const reset = await resetReplication(ORDERS_T, { destination: DEST_ID, collection: "orders" });
+        expect(reset.state).toBeGreaterThanOrEqual(1);
+
+        expect(await waitFor(async () => (await ordersDest().countDocuments({ title: marker })) === 1, 20_000)).toBe(true);
+    }, 30_000);
+
+    it("applies the collection's document filter to the stream (`_vars_` namespaces)", async () => {
+        const marker = `cs-vars-${crypto.randomUUID()}`;
+        await restVars.vars.set("config", marker, "REPLICATED");
+        await restVars.vars.set("private", "secret", marker);
+
+        expect(await waitFor(async () => Boolean(await varsOnDest("config", marker)))).toBe(true);
+        // `private.var.ts` opts out: the filter is on the post-image, so the stream
+        // never even writes it
+        expect(await varsOnDest("private", "secret")).toBeNull();
+    });
+});
+
+describe("replication — changeStream shutdown", () => {
+    it("stops writing once replication is stopped", async () => {
+        await stopReplication();
+
+        const marker = `cs-after-stop-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: marker });
+        await Bun.sleep(1_500); // long enough for a stream that is still alive
+
+        expect(await ordersDest().countDocuments({ title: marker })).toBe(0);
+    });
+
+    it("does not wait forever on a collection another writer owns", async () => {
+        // A stream elsewhere already owns `orders`; this boot must not block on it
+        await rest.lock(`replication:${DEST_ID}:orders`, 60_000);
+
+        const startedAt = Date.now();
+        await startReplication();
+        const elapsed = Date.now() - startedAt;
+
+        expect(elapsed).toBeLessThan(25_000);
+
+        // …and the collections it *could* take are still watched: an entry written
+        // with no run reaches the destination while `orders` is skipped
+        const marker = `cs-partial-${crypto.randomUUID()}`;
+        await rest.audit.addActivities([{
+            internal: true,
+            trace: { id: crypto.randomUUID() },
+            meta: {},
+            operation: {
+                tenant: ORDERS_T, action: marker, collection: "orders",
+                status: "success", input: null, result: null, error: null, duration: 0, transaction: false,
+            },
+            ts: new Date(),
+        } as any]);
+
+        expect(await waitFor(async () => (await auditDest().countDocuments({ "operation.action": marker })) === 1)).toBe(true);
+    }, 60_000);
+});

package/tests/replication-control.test.ts

@@ -28,6 +28,8 @@ beforeAll(async () => {
             dir: "src",
             database: { uri: SRC_DB },
             replication: {
+                // These cases exercise the scan engine (cursor, tombstones, seeding)
+                mode: "scan",
                 runOnBoot: false,
                 schedule: { interval: "1h" },
                 destinations: [{ id: DEST_ID, uri: DEST_DB }],

package/tests/replication-initial-sync.test.ts

@@ -21,6 +21,8 @@ beforeAll(async () => {
             dir: "src",
             database: { uri: SRC_DB },
             replication: {
+                // These cases exercise the scan engine's `initialSync` seeding
+                mode: "scan",
                 runOnBoot: false,
                 schedule: { interval: "1h" },
                 destinations: [{ id: DEST_ID, uri: DEST_DB }],

package/tests/replication-meta.test.ts

@@ -42,6 +42,8 @@ beforeAll(async () => {
                 // Opt-in retention, so the destination's copy is pruned the same way
                 audit: { retention: "30d" },
                 replication: {
+                    // These cases exercise the scan engine (meta collections, exclude)
+                    mode: "scan",
                     runOnBoot: false,
                     schedule: { interval: "1h" },
                     destinations: [{ id: "backup", uri: ALL_T_DEST }],
@@ -52,6 +54,7 @@ beforeAll(async () => {
                 dir: DIR,
                 database: { uri: OFF_T_DB },
                 replication: {
+                    mode: "scan",
                     runOnBoot: false,
                     schedule: { interval: "1h" },
                     exclude: ["audit", "workflows", "locks", "replication", "vars", "memory"],

package/tests/replication.test.ts

@@ -26,6 +26,8 @@ beforeAll(async () => {
             dir: "src",
             database: { uri: SRC_DB },
             replication: {
+                // These cases exercise the scan engine (cursor, tombstones, initial sync)
+                mode: "scan",
                 runOnBoot: false,
                 schedule: { interval: "1h" },
                 destinations: [{ id: DEST_ID, uri: DEST_DB }],

package/tests/vars-replication.test.ts

@@ -21,6 +21,8 @@ beforeAll(async () => {
             dir: "packages/core/tests/fixtures/vars-tenant",
             database: { uri: SRC_DB },
             replication: {
+                // These cases exercise the scan engine (vars namespace filter)
+                mode: "scan",
                 runOnBoot: false,
                 schedule: { interval: "1h" },
                 destinations: [{ id: "backup", uri: DEST_DB }],

package/types/agent.d.ts

@@ -10,7 +10,14 @@ import type { Agent } from "../lib/agent";
  * `'openai'` (the default) also covers every OpenAI-compatible gateway
  * (Groq, Mistral, OpenRouter, Ollama, LM Studio, vLLM…) — only `baseUrl` changes.
  */
-export type AgentCompatible = "openai" | "anthropic";
+export type AgentProtocol = "openai" | "anthropic";
+
+/**
+ * @deprecated Renamed to `AgentProtocol` — the field was named after a property
+ * of the remote endpoint, when what it really selects is the shape of the
+ * request and response on the wire.
+ */
+export type AgentCompatible = AgentProtocol;
 
 /**
  * Model provider — **where** the agent's reasoning comes from: the model, the
@@ -18,21 +25,30 @@ export type AgentCompatible = "openai" | "anthropic";
  *
  * ```ts
  * provider: { model: 'gpt-4o-mini', apiKey: 'sk-…' }                       // OpenAI
- * provider: { model: 'claude-sonnet-4-5', apiKey: 'sk-ant-…', compatible: 'anthropic' }
- * provider: { model: 'llama3.1', compatible: 'openai', baseUrl: 'http://localhost:11434/v1' }
+ * provider: { model: 'claude-sonnet-4-5', apiKey: 'sk-ant-…', protocol: 'anthropic' }
+ * provider: { model: 'llama3.1', protocol: 'openai', baseUrl: 'http://localhost:11434/v1' }
  * ```
  *
  * The key falls back to the environment when omitted:
  * `ANTEROS_AI_API_KEY`, then `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` according to
- * `compatible`. It is therefore never required in the source.
+ * `protocol`. It is therefore never required in the source.
  */
 export type AgentProvider = {
     /** Model id sent to the API (e.g. `gpt-4o-mini`, `claude-sonnet-4-5`). */
     model: string;
     /** API key — falls back to the environment (see above). */
     apiKey?: string;
-    /** Wire protocol (default `'openai'`). */
-    compatible?: AgentCompatible;
+    /**
+     * Wire protocol of the endpoint (default `'openai'`). `'openai'` is the
+     * Chat Completions API — the one every OpenAI-compatible gateway
+     * (Groq, Mistral, Ollama…) speaks too — `'anthropic'` is the Messages API.
+     */
+    protocol?: AgentProtocol;
+    /**
+     * @deprecated Alias of `protocol`, kept so a definition written before the
+     * rename keeps working. `protocol` wins when both are set.
+     */
+    compatible?: AgentProtocol;
     /** API root override — default `https://api.openai.com/v1` or `https://api.anthropic.com`. */
     baseUrl?: string;
     /** Extra headers sent with every request. */
@@ -60,6 +76,15 @@ export type AgentOptions = {
     timeout?: number;
     /** Retries on network errors, 429 and 5xx (default 2). */
     retries?: number;
+    /**
+     * Mark the stable prefix of the prompt for the provider's **prompt cache**
+     * (default `false`). Anthropic only: a `cache_control` breakpoint is set on the
+     * system prompt (instructions + skills + working memory) and on the last tool,
+     * so the instructions are billed once instead of on every run.
+     *
+     * Ignored by an OpenAI-compatible gateway, which caches on its own.
+     */
+    cache?: boolean;
 };
 
 /** Text part of a multimodal message. */
@@ -345,6 +370,21 @@ export type AgentTool = {
     execute?: (input: any, ctx: AgentToolContext) => any | Promise<any>;
     /** MCP-compatible handler (`define.McpTool`) — adapted automatically. */
     exec?: (ctx: any) => any | Promise<any>;
+    /**
+     * Give up on this tool after N ms (default: the agent's `toolTimeoutMs`). The
+     * model is told it timed out and the run continues — an outbound call is the one
+     * thing the framework cannot bound for you.
+     */
+    timeoutMs?: number;
+    /**
+     * Ask the caller before running this tool (a payment, a delete, an email).
+     *
+     * The run **pauses** with `finishReason: 'approval_required'` and
+     * `result.pendingApprovals`; the caller resumes with
+     * `{ resume: { messages: result.messages, decisions } }`. Nothing is executed
+     * before a decision, and a refusal is reported to the model as a tool error.
+     */
+    approval?: boolean;
 };
 
 /** What a tool must carry to be **declared** — `define.Tool` enforces the id. */
@@ -429,6 +469,14 @@ export type AgentMemoryContext = {
      * boundary: gate `history` / `clear` with `api.access`.
      */
     resourceId?: string;
+    /** Memory thread of the run — what a processor keys a per-thread cache on. */
+    thread?: string;
+    /**
+     * The store of the agent running — so a processor can read and write the
+     * scratchpad state of a thread (see `agents.memory.summarize`). Exposed on the
+     * **run** context only.
+     */
+    memory?: AgentMemory;
 };
 
 /** A thread as listed by a memory store (`agents.memory.Mongo().list()`). */
@@ -540,11 +588,50 @@ export type RedisAgentMemoryOptions = AgentMemoryOptions & {
 /** Structured output request — the answer is parsed and validated against `schema`. */
 export type AgentStructuredOutput = {
     schema: Joi.Schema | any;
-    /** Only used by OpenAI-compatible providers (`response_format.json_schema`). */
+    /**
+     * Name of the schema on the wire — `response_format.json_schema.name`
+     * (default: the agent id, sanitized).
+     */
     name?: string;
+    /** What the object holds, sent to the provider next to the schema. */
     description?: string;
 };
 
+/**
+ * A tool call that is waiting for its caller's decision — see
+ * `AgentTool.approval`. Served on `result.pendingApprovals`.
+ */
+export type AgentPendingApproval = {
+    toolCallId: string;
+    name: string;
+    args: any;
+};
+
+/**
+ * What a paused run needs to go on: **the conversation it stopped on**, and one
+ * decision per pending call.
+ *
+ * ```ts
+ * const paused = await agent.generate('Refund order A-1', { thread: 't1' });
+ * if (paused.finishReason === 'approval_required') {
+ *   await agent.generate('ignored — the run resumes from `messages`', {
+ *     thread: 't1',
+ *     resume: { messages: paused.messages, decisions: { [paused.pendingApprovals![0]!.toolCallId]: true } },
+ *   });
+ * }
+ * ```
+ *
+ * The paused step is **not replayed through the model**: the approved tools run and
+ * the loop continues, so approving costs exactly one model call. A call left without
+ * a decision stays pending — the run pauses again.
+ */
+export type AgentResume = {
+    /** The conversation to continue — `result.messages` of the paused run. */
+    messages: AgentMessage[] | AgentMessageInput[];
+    /** One decision per pending call, by `toolCallId` — `true` runs it, `false` refuses it. */
+    decisions: Record<string, boolean>;
+};
+
 export type AgentCallOptions = {
     /** Thread to read from / write to the memory (same as `memory.thread`). */
     thread?: string;
@@ -643,6 +730,31 @@ export type AgentCallOptions = {
     };
     /** Called after each model call, before its tools run. */
     onStepFinish?: (step: AgentStep) => void | Promise<void>;
+    /**
+     * Give up on a single tool after N ms (default: the agent's `toolTimeoutMs`).
+     * A tool that times out is reported to the model as an error, and the run goes on.
+     */
+    toolTimeoutMs?: number;
+    /**
+     * Run the tools of one step **in parallel** (default `false` — sequential).
+     *
+     * Only safe when the tools do not write to the same place: two calls of the same
+     * tool with the same target can interleave. Read-only tools are the point.
+     */
+    parallelTools?: boolean;
+    /**
+     * Store what the run produced even when it **fails** (default `false`).
+     *
+     * Without it, a provider error at step 3 throws and the whole exchange is lost —
+     * the tokens are paid and the thread never hears about it. With it, the thread
+     * keeps the turns up to the failure, and the next call resumes from there.
+     */
+    savePartial?: boolean;
+    /**
+     * Continue a run that paused for an approval instead of starting a new one —
+     * see `AgentResume`.
+     */
+    resume?: AgentResume;
 };
 
 export type AgentGenerateResult<T = any> = {
@@ -658,6 +770,12 @@ export type AgentGenerateResult<T = any> = {
     finishReason: string;
     /** The complete conversation, ready to be persisted. */
     messages: AgentMessage[];
+    /**
+     * Calls waiting for a decision — present (and `finishReason`
+     * `'approval_required'`) when a tool declaring `approval: true` was called.
+     * Resume the run with `{ resume: { messages, decisions } }`.
+     */
+    pendingApprovals?: AgentPendingApproval[];
     error?: string;
 };
 
@@ -773,9 +891,72 @@ export type AgentApi = {
      * Schema returned by the `object` action. Declared **server-side** on purpose:
      * a client never dictates the shape, and the answer is really validated.
      */
+    /** Schema returned by the `object` action. Declared **server-side** on purpose:
+     * a client never dictates the shape, and the answer is really validated.
+     */
     object?: AgentStructuredOutput;
 };
 
+/**
+ * How an agent declares the documents injected into its system prompt — links to
+ * markdown files, nothing else:
+ *
+ * - a **string** is a path or a glob — `.md` only, resolved from the **tenant
+ *   directory** (an absolute path is used as-is): `'./docs/*.md'`, `'./guide/ml.md'`,
+ *   `'./guides/**\/SKILL.md'`
+ * - a **RegExp** is matched against every file of the tenant directory (`.md` only):
+ *   `/^runbooks\/.*\.md$/`
+ */
+export type AgentSkillSource = string | RegExp;
+
+/**
+ * A resolved skill — one markdown file with a frontmatter header:
+ *
+ * ```md
+ * ---
+ * name: pdf-forms
+ * description: Fill, flatten and merge PDF forms. Use for any AcroForm work.
+ * license: MIT
+ * compatibility: Needs the `pdftk` binary.
+ * metadata: { owner: platform }
+ * allowed-tools: read_pdf write_pdf
+ * ---
+ *
+ * # Filling a form
+ * …
+ * ```
+ *
+ * `name` and `description` are required (the name is kebab-case, 1-64 characters,
+ * and must match the containing directory when the file is a `SKILL.md`);
+ * everything else is optional. Unknown keys are kept out of the prompt and logged,
+ * and a file that is not markdown is never a skill — as is one whose body is empty:
+ * a skill *is* the text the model reads.
+ *
+ * The **`content`** is what the model reads — it is part of the system prompt of
+ * every run, so it costs tokens on every call: keep skills short and factual.
+ */
+export type AgentSkill = {
+    /** Kebab-case identifier, unique per agent. */
+    name: string;
+    /** What the skill does and when to use it (≤ 1024 characters). */
+    description: string;
+    /** License name or reference to a bundled license file. */
+    license?: string;
+    /** Environment requirements (≤ 500 characters). */
+    compatibility?: string;
+    /** Arbitrary key-value pairs — metadata only, never injected. */
+    metadata?: Record<string, any>;
+    /**
+     * Tools the skill may use. Parsed and served by `getSkills()`, **not enforced**
+     * by the run (a skill is always in the prompt — there is no activation to scope).
+     */
+    allowedTools?: string[];
+    /** The markdown body — injected as-is, frontmatter stripped. */
+    content: string;
+    /** Where it came from, relative to the tenant directory. */
+    source: string;
+};
+
 /**
  * An agent definition — `{tenant.dir}/agents/**\/*.agent.ts`, declared with
  * `define.Agent({ … })`.
@@ -787,6 +968,13 @@ export type AgentConfig = {
     /** Identifier — required, unique per tenant. */
     id?: string;
     name?: string;
+    /**
+     * What this prompt **is** — a free string (`'2026-09-24'`, `'v3'`, a commit).
+     *
+     * Like a workflow's `version`, it is served by `info` and written on every audit
+     * entry, so an answer can be traced back to the prompt that produced it.
+     */
+    version?: string;
     /** What the agent is for — required (served by `info`, read by humans). */
     description?: string;
     instructions: AgentInstructions;
@@ -795,6 +983,30 @@ export type AgentConfig = {
     memory?: AgentMemory;
     /** Max model calls per run (default 5). */
     maxSteps?: number;
+    /** Default deadline for one tool call, in ms — see `AgentTool.timeoutMs`. */
+    toolTimeoutMs?: number;
+    /** Run the tools of one step in parallel by default — see `AgentCallOptions`. */
+    parallelTools?: boolean;
+    /** Store a failed run's conversation by default — see `AgentCallOptions`. */
+    savePartial?: boolean;
+    /**
+     * Other agents exposed to this one **as tools** — the model decides when to
+     * delegate: `agents: [researcher]` (an agent definition, usually the default
+     * export of another agent file).
+     *
+     * Each one becomes a tool named after its `id`, described by its `description`,
+     * taking `{ input }` and answering with the sub-agent's text. A local tool with
+     * the same name wins.
+     */
+    agents?: AgentConfig | AgentConfig[];
+    /**
+     * Remote **MCP servers** whose tools this agent may use: `['https://host/mcp']`
+     * or `{ docs: 'https://docs/mcp' }` (the name is for the logs).
+     *
+     * Connected once, at first use. A remote tool keeps its name; a tool the agent
+     * declares itself wins over a remote one of the same name.
+     */
+    mcp?: string[] | Record<string, string>;
     /** Default tool choice for every run (default `'auto'`). */
     toolChoice?: AgentToolChoice;
     /** Default reasoning for every run (default off) — overridable per call. */
@@ -805,6 +1017,24 @@ export type AgentConfig = {
      * round stores several messages, so count is a proxy, not a measure).
      */
     lastMessages?: number;
+    /**
+     * **Markdown documents injected into the system prompt** of every run —
+     * resolved once at load, from `{tenant.dir}`:
+     *
+     * ```ts
+     * define.Agent({
+     *   skills: ['./docs/*.md', './guide/ml.md', /^runbooks\/.*\.md$/],
+     * })
+     * ```
+     *
+     * Each file carries a frontmatter header (`name`, `description`, `license`,
+     * `compatibility`, `metadata`, `allowed-tools`) and its body is what the model
+     * reads. A file that is not markdown is skipped (logged); a malformed skill
+     * refuses **the agent** at load — the others keep loading. See `AgentSkill`.
+     */
+    skills?: AgentSkillSource[];
+    /** @internal — resolved from `skills` by the loader. */
+    _skills_?: AgentSkill[];
     /**
      * The agent's durable scratchpad — see `AgentWorkingMemory`. Needs a store that
      * supports it (the three built-in ones do) and, for the default scope, a