melchizedek-agents 0.9.6 → 0.16.0

package/dist/lib/storage/postgres/taskStore.d.ts

@@ -0,0 +1,55 @@
+/**
+ * lib/storage/postgres/taskStore.ts — the A2A SDK's TaskStore on Postgres.
+ *
+ * Tasks outlive the process that started them and are visible to every
+ * instance, so a client that polls a different replica, or polls after a
+ * restart, still finds its task. Each task is filed under the tenant and
+ * owner the SDK's own scoping rule derives from the call context (the
+ * default resolver reads the authenticated user name), so one caller cannot
+ * load or list another's task. `list` mirrors the SDK's InMemoryTaskStore:
+ * same filters, same newest-first order, same page-token format.
+ */
+import type { Pool } from 'pg';
+import type { TaskStore } from '@a2a-js/sdk/server';
+type Task = Parameters<TaskStore['save']>[0];
+type Context = Parameters<TaskStore['save']>[1];
+type ListParams = Parameters<TaskStore['list']>[0];
+type ListResult = Awaited<ReturnType<TaskStore['list']>>;
+export interface PostgresTaskStoreOptions {
+    /** Owner of a call. Default: the SDK's resolveUserScope (the authenticated user name). */
+    ownerResolver?: (context: Context) => string;
+    /** Days a task is kept after its last update (expire_at). Default 7. */
+    ttlDays?: number;
+    /**
+     * While a task is running (submitted or working) it is leased to this
+     * instance until `ttlMs` from its last save or renewal (migration 0006).
+     */
+    lease?: TaskLease;
+}
+export interface TaskLease {
+    /** This process's id: what a lease names as its owner. */
+    instanceId: string;
+    ttlMs: number;
+}
+/** Extends every lease this instance holds. Returns how many it renewed. */
+export declare function renewTaskLeases(pool: Pool, lease: TaskLease): Promise<number>;
+/**
+ * Marks running tasks whose lease expired (their instance died) as failed,
+ * with a message saying so. Any instance may run it: rows are claimed with
+ * SKIP LOCKED, so two reapers never fail the same task twice. Returns how
+ * many it failed.
+ */
+export declare function reapExpiredTasks(pool: Pool, limit?: number): Promise<number>;
+export declare class PostgresTaskStore implements TaskStore {
+    private readonly owner;
+    private readonly ttlMs;
+    private readonly pool;
+    private readonly agentId;
+    private readonly lease?;
+    constructor(pool: Pool, agentId: string, options?: PostgresTaskStoreOptions);
+    private scope;
+    save(task: Task, context: Context): Promise<void>;
+    load(taskId: string, context: Context): Promise<Task | undefined>;
+    list(params: ListParams, context: Context): Promise<ListResult>;
+}
+export {};

package/dist/lib/storage/postgres/taskStore.js

@@ -0,0 +1,168 @@
+/**
+ * lib/storage/postgres/taskStore.ts — the A2A SDK's TaskStore on Postgres.
+ *
+ * Tasks outlive the process that started them and are visible to every
+ * instance, so a client that polls a different replica, or polls after a
+ * restart, still finds its task. Each task is filed under the tenant and
+ * owner the SDK's own scoping rule derives from the call context (the
+ * default resolver reads the authenticated user name), so one caller cannot
+ * load or list another's task. `list` mirrors the SDK's InMemoryTaskStore:
+ * same filters, same newest-first order, same page-token format.
+ */
+import { randomUUID } from 'node:crypto';
+import { Role, TaskState } from '@a2a-js/sdk';
+import { resolveUserScope } from '@a2a-js/sdk/server';
+const DEFAULT_PAGE_SIZE = 50;
+/** States in which a task is being worked on by some instance. */
+const RUNNING = new Set([TaskState.TASK_STATE_SUBMITTED, TaskState.TASK_STATE_WORKING]);
+/** Extends every lease this instance holds. Returns how many it renewed. */
+export async function renewTaskLeases(pool, lease) {
+    const r = await pool.query(`UPDATE adk_a2a_tasks SET lease_until = now() + ($2::int * interval '1 millisecond')
+     WHERE lease_owner = $1 AND lease_until IS NOT NULL`, [lease.instanceId, lease.ttlMs]);
+    return r.rowCount ?? 0;
+}
+/** The status a task gets when the instance running it is gone. */
+const ORPHANED = 'The server running this task stopped before it finished; send the message again.';
+/**
+ * Marks running tasks whose lease expired (their instance died) as failed,
+ * with a message saying so. Any instance may run it: rows are claimed with
+ * SKIP LOCKED, so two reapers never fail the same task twice. Returns how
+ * many it failed.
+ */
+export async function reapExpiredTasks(pool, limit = 100) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const r = await client.query(`SELECT tenant, owner, agent_id, id, task FROM adk_a2a_tasks
+       WHERE lease_until IS NOT NULL AND lease_until < now()
+       ORDER BY lease_until LIMIT $1 FOR UPDATE SKIP LOCKED`, [limit]);
+        for (const row of r.rows) {
+            const task = row.task;
+            const timestamp = new Date().toISOString();
+            task.status = {
+                state: TaskState.TASK_STATE_FAILED,
+                timestamp,
+                message: {
+                    messageId: randomUUID(),
+                    contextId: task.contextId ?? '',
+                    taskId: task.id,
+                    role: Role.ROLE_AGENT,
+                    parts: [{ content: { $case: 'text', value: ORPHANED }, filename: '', mediaType: 'text/plain' }],
+                    extensions: [],
+                    referenceTaskIds: [],
+                },
+            };
+            await client.query(`UPDATE adk_a2a_tasks SET task = $5::jsonb, state = $6, status_ts = $7, updated_at = now(),
+                lease_owner = NULL, lease_until = NULL
+         WHERE tenant = $1 AND owner = $2 AND agent_id = $3 AND id = $4`, [row.tenant, row.owner, row.agent_id, row.id, JSON.stringify(task), TaskState.TASK_STATE_FAILED, timestamp]);
+        }
+        await client.query('COMMIT');
+        return r.rows.length;
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => { });
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+function encodePageToken(timestamp, id) {
+    return Buffer.from(`${timestamp}|${id}`).toString('base64');
+}
+function decodePageToken(token) {
+    const [timestamp, ...idParts] = Buffer.from(token, 'base64').toString('utf-8').split('|');
+    if (idParts.length === 0)
+        throw new Error('Invalid page token format.');
+    return { timestamp, id: idParts.join('|') };
+}
+export class PostgresTaskStore {
+    owner;
+    ttlMs;
+    pool;
+    agentId;
+    lease;
+    constructor(pool, agentId, options = {}) {
+        this.pool = pool;
+        this.agentId = agentId;
+        this.owner = options.ownerResolver ?? resolveUserScope;
+        this.ttlMs = (options.ttlDays ?? 7) * 24 * 60 * 60 * 1000;
+        this.lease = options.lease;
+    }
+    scope(context) {
+        return [context.tenant ?? '', this.owner(context)];
+    }
+    async save(task, context) {
+        const [tenant, owner] = this.scope(context);
+        const t = task;
+        // A running task is leased to this instance; any other state holds none.
+        const leased = !!this.lease && RUNNING.has(t.status?.state ?? -1);
+        await this.pool.query(`INSERT INTO adk_a2a_tasks (tenant, owner, agent_id, id, context_id, state, status_ts, task, updated_at, expire_at, lease_owner, lease_until)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, now(), $9, $10,
+               CASE WHEN $10::text IS NULL THEN NULL ELSE now() + ($11::int * interval '1 millisecond') END)
+       ON CONFLICT (tenant, owner, agent_id, id) DO UPDATE
+         SET context_id = EXCLUDED.context_id, state = EXCLUDED.state, status_ts = EXCLUDED.status_ts,
+             task = EXCLUDED.task, updated_at = now(), expire_at = EXCLUDED.expire_at,
+             lease_owner = EXCLUDED.lease_owner, lease_until = EXCLUDED.lease_until`, [
+            tenant,
+            owner,
+            this.agentId,
+            t.id,
+            t.contextId ?? null,
+            t.status?.state ?? null,
+            t.status?.timestamp ?? '',
+            JSON.stringify(task),
+            new Date(Date.now() + this.ttlMs).toISOString(),
+            leased ? this.lease.instanceId : null,
+            this.lease?.ttlMs ?? 0,
+        ]);
+    }
+    async load(taskId, context) {
+        const [tenant, owner] = this.scope(context);
+        const r = await this.pool.query('SELECT task FROM adk_a2a_tasks WHERE tenant = $1 AND owner = $2 AND agent_id = $3 AND id = $4', [tenant, owner, this.agentId, taskId]);
+        return r.rowCount ? r.rows[0].task : undefined;
+    }
+    async list(params, context) {
+        const [tenant, owner] = this.scope(context);
+        const p = params;
+        const pageSize = p.pageSize || DEFAULT_PAGE_SIZE;
+        const args = [tenant, owner, this.agentId];
+        let where = 'tenant = $1 AND owner = $2 AND agent_id = $3';
+        if (p.contextId) {
+            args.push(p.contextId);
+            where += ` AND context_id = $${args.length}`;
+        }
+        if (p.status !== undefined && p.status !== 0) {
+            args.push(p.status);
+            where += ` AND state = $${args.length}`;
+        }
+        if (p.statusTimestampAfter) {
+            args.push(new Date(p.statusTimestampAfter).toISOString());
+            where += ` AND status_ts <> '' AND status_ts::timestamptz > $${args.length}::timestamptz`;
+        }
+        const total = await this.pool.query(`SELECT count(*)::int AS n FROM adk_a2a_tasks WHERE ${where}`, args);
+        let cursor = '';
+        if (p.pageToken) {
+            const c = decodePageToken(p.pageToken);
+            args.push(c.timestamp, c.id);
+            cursor = ` AND (status_ts, id) < ($${args.length - 1}, $${args.length})`;
+        }
+        args.push(pageSize + 1);
+        const rows = await this.pool.query(`SELECT task, status_ts, id FROM adk_a2a_tasks WHERE ${where}${cursor}
+        ORDER BY status_ts DESC, id DESC LIMIT $${args.length}`, args);
+        const page = rows.rows.slice(0, pageSize);
+        const tasks = page.map((row) => {
+            const task = row.task;
+            if (!p.includeArtifacts)
+                task.artifacts = [];
+            return task;
+        });
+        const last = page[page.length - 1];
+        return {
+            tasks,
+            nextPageToken: rows.rows.length > pageSize && last ? encodePageToken(last.status_ts ?? '', last.id) : '',
+            pageSize,
+            totalSize: total.rows[0].n,
+        };
+    }
+}

package/dist/lib/storage/schema.d.ts

@@ -0,0 +1,27 @@
+/**
+ * lib/storage/schema.ts — the database schema the tables live in
+ * (ADR 0021 item 2).
+ *
+ * The default is `public`, where every existing deployment's tables are.
+ * A deployment on its own Postgres can keep them in a private schema
+ * instead (MELCHIZEDEK_DB_SCHEMA, e.g. `melchizedek`): a REST layer such as
+ * Supabase's exposes `public` by default, so a private schema has no anon
+ * REST path at all. It is reached over DATABASE_URL (postgresStorage), which
+ * sets the connection's search_path; supabase-js storage cannot use it.
+ *
+ * The SQL in db/ names `public` in three places, which `sqlForSchema`
+ * rewrites, and nowhere else (pinned by tests):
+ *   - `SET search_path = public` on function definitions;
+ *   - `'public.<table>'` in to_regclass lookups;
+ *   - `= 'public'` in catalog filters;
+ * plus the pg_cron jobs, which run outside any search_path and so call
+ * their function by its qualified name. `public` stays on the path after
+ * the schema, for the pgvector type and functions.
+ */
+export declare const SCHEMA_NAME: RegExp;
+/** The configured schema: MELCHIZEDEK_DB_SCHEMA, else `public`. */
+export declare function dbSchema(env?: NodeJS.ProcessEnv): string;
+/** A db/ file's SQL for `schema` (unchanged for `public`). */
+export declare function sqlForSchema(sql: string, schema: string): string;
+/** The pg connection option that puts `schema` first on the search_path. */
+export declare function searchPathOption(schema: string): string | undefined;

package/dist/lib/storage/schema.js

@@ -0,0 +1,50 @@
+/**
+ * lib/storage/schema.ts — the database schema the tables live in
+ * (ADR 0021 item 2).
+ *
+ * The default is `public`, where every existing deployment's tables are.
+ * A deployment on its own Postgres can keep them in a private schema
+ * instead (MELCHIZEDEK_DB_SCHEMA, e.g. `melchizedek`): a REST layer such as
+ * Supabase's exposes `public` by default, so a private schema has no anon
+ * REST path at all. It is reached over DATABASE_URL (postgresStorage), which
+ * sets the connection's search_path; supabase-js storage cannot use it.
+ *
+ * The SQL in db/ names `public` in three places, which `sqlForSchema`
+ * rewrites, and nowhere else (pinned by tests):
+ *   - `SET search_path = public` on function definitions;
+ *   - `'public.<table>'` in to_regclass lookups;
+ *   - `= 'public'` in catalog filters;
+ * plus the pg_cron jobs, which run outside any search_path and so call
+ * their function by its qualified name. `public` stays on the path after
+ * the schema, for the pgvector type and functions.
+ */
+export const SCHEMA_NAME = /^[a-z_][a-z0-9_]{0,62}$/;
+/** The configured schema: MELCHIZEDEK_DB_SCHEMA, else `public`. */
+export function dbSchema(env = process.env) {
+    const s = env.MELCHIZEDEK_DB_SCHEMA?.trim() || 'public';
+    if (!SCHEMA_NAME.test(s)) {
+        throw new Error(`MELCHIZEDEK_DB_SCHEMA must be a lower-case identifier (letters, digits, _), got "${s}"`);
+    }
+    return s;
+}
+/** A db/ file's SQL for `schema` (unchanged for `public`). */
+export function sqlForSchema(sql, schema) {
+    if (schema === 'public')
+        return sql;
+    if (!SCHEMA_NAME.test(schema))
+        throw new Error(`invalid schema name "${schema}"`);
+    const body = sql
+        .replaceAll('SET search_path = public', `SET search_path = ${schema}, public`)
+        .replaceAll("'public.", `'${schema}.`)
+        .replaceAll("= 'public'", `= '${schema}'`)
+        .replace(/'SELECT (melchizedek_[a-z_]+\(\))'/g, `'SELECT ${schema}.$1'`);
+    return `CREATE SCHEMA IF NOT EXISTS ${schema};\nSET search_path = ${schema}, public;\n${body}`;
+}
+/** The pg connection option that puts `schema` first on the search_path. */
+export function searchPathOption(schema) {
+    if (schema === 'public')
+        return undefined;
+    if (!SCHEMA_NAME.test(schema))
+        throw new Error(`invalid schema name "${schema}"`);
+    return `-c search_path=${schema},public`;
+}

package/dist/lib/storage/schemaVersion.d.ts

@@ -0,0 +1,25 @@
+/**
+ * lib/storage/schemaVersion.ts — the database schema this package expects
+ * (ADR 0021 item 3).
+ *
+ * Every numbered migration in db/migrations/ records itself in
+ * `melchizedek_schema_version`. The highest number shipped with the package
+ * is the schema this code is written against; a database below it is missing
+ * tables or functions the server will call, so the server refuses to start on
+ * it and names the fix. A database ABOVE it is a newer migration applied
+ * before this server was upgraded (a rolling deploy): migrations are additive,
+ * so that only warns.
+ */
+/** db/ of this package, from the source tree or from dist/. */
+export declare function packageDbDir(): string;
+/** The highest migration number in db/migrations/ (NNNN_name.sql). */
+export declare function shippedSchemaVersion(migrationsDir?: string): number;
+export interface SchemaCheck {
+    /** Version recorded in the database; null when it has none. */
+    db: number | null;
+    shipped: number;
+    state: 'match' | 'behind' | 'ahead';
+}
+export declare function compareSchema(db: number | null, shipped: number): SchemaCheck;
+/** The message for a database behind the code: what is missing and the fix. */
+export declare function schemaBehindMessage(check: SchemaCheck): string;

package/dist/lib/storage/schemaVersion.js

@@ -0,0 +1,46 @@
+/**
+ * lib/storage/schemaVersion.ts — the database schema this package expects
+ * (ADR 0021 item 3).
+ *
+ * Every numbered migration in db/migrations/ records itself in
+ * `melchizedek_schema_version`. The highest number shipped with the package
+ * is the schema this code is written against; a database below it is missing
+ * tables or functions the server will call, so the server refuses to start on
+ * it and names the fix. A database ABOVE it is a newer migration applied
+ * before this server was upgraded (a rolling deploy): migrations are additive,
+ * so that only warns.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** db/ of this package, from the source tree or from dist/. */
+export function packageDbDir() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        if (existsSync(join(dir, 'db', 'migrations')))
+            return join(dir, 'db');
+        dir = dirname(dir);
+    }
+    throw new Error('db/migrations/ not found next to this package');
+}
+/** The highest migration number in db/migrations/ (NNNN_name.sql). */
+export function shippedSchemaVersion(migrationsDir = join(packageDbDir(), 'migrations')) {
+    let max = 0;
+    for (const f of readdirSync(migrationsDir)) {
+        const m = /^(\d{4})_[a-z0-9_]+\.sql$/.exec(f);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return max;
+}
+export function compareSchema(db, shipped) {
+    const v = db ?? 0;
+    return { db, shipped, state: v === shipped ? 'match' : v < shipped ? 'behind' : 'ahead' };
+}
+/** The message for a database behind the code: what is missing and the fix. */
+export function schemaBehindMessage(check) {
+    const have = check.db === null ? 'no recorded schema version' : `schema version ${check.db}`;
+    return (`The database has ${have}; this server needs version ${check.shipped}. ` +
+        'Run `npx melchizedek-db apply` (or `npm run db -- apply`) against it, ' +
+        'or set ALLOW_SCHEMA_MISMATCH=true to start anyway.');
+}

package/dist/lib/syndicateSchema.d.ts

@@ -0,0 +1,275 @@
+/**
+ * lib/syndicateSchema.ts — the syndicate YAML contract, as a validator.
+ *
+ * WHY this file exists:
+ *   A syndicate YAML is the framework's primary authoring surface, and the
+ *   loader used to type-cast it (`parse(...) as SyndicateYamlConfig`). A typo
+ *   either crashed deep inside the compiler (`orchestator:` → "cannot read
+ *   'model' of undefined") or, worse, was accepted and silently changed
+ *   behaviour (`memory_system: internl-only` disabled memory in the A2A
+ *   server). Here the shape the interfaces in lib/loadSyndicate.ts declare is
+ *   written once as a zod schema, checked at load, and every problem is
+ *   reported with its key path and, for a misspelt key, the key it was meant
+ *   to be.
+ *
+ *   The same schema emits config/agents/syndicate.schema.json (npm run
+ *   schema:gen) so an editor can flag the typo before a run does; a test
+ *   keeps the committed file equal to the generated one.
+ *
+ * Strictness is deliberate at the syndicate, agent and dispatch levels — the
+ * places a misspelt key silently does nothing — and deliberately ABSENT inside
+ * `generateContentConfig` and `outputSchema`, which pass through to provider
+ * SDKs whose fields this repo does not own.
+ */
+import { z } from 'zod';
+import type { SyndicateYamlConfig } from './loadSyndicate.ts';
+export declare const MEMORY_SYSTEMS: readonly ['internal-only', 'session-only', 'long-term'];
+export declare const agentSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    model: z.ZodString;
+    instruction: z.ZodString;
+    globalInstruction: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    require_approval: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    includeContents: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        none: "none";
+    }>>;
+    disallowTransferToParent: z.ZodOptional<z.ZodBoolean>;
+    disallowTransferToPeers: z.ZodOptional<z.ZodBoolean>;
+    outputKey: z.ZodOptional<z.ZodString>;
+    generateContentConfig: z.ZodOptional<z.ZodObject<{
+        temperature: z.ZodOptional<z.ZodNumber>;
+        topP: z.ZodOptional<z.ZodNumber>;
+        topK: z.ZodOptional<z.ZodNumber>;
+        maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        candidateCount: z.ZodOptional<z.ZodNumber>;
+        presencePenalty: z.ZodOptional<z.ZodNumber>;
+        frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+        seed: z.ZodOptional<z.ZodNumber>;
+        responseMimeType: z.ZodOptional<z.ZodString>;
+        safetySettings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            category: z.ZodString;
+            threshold: z.ZodString;
+        }, z.core.$loose>>>;
+        thinkingConfig: z.ZodOptional<z.ZodObject<{
+            thinkingBudget: z.ZodOptional<z.ZodNumber>;
+            includeThoughts: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    mcp_server_url: z.ZodOptional<z.ZodString>;
+    orchestration: z.ZodOptional<z.ZodObject<{
+        role: z.ZodOptional<z.ZodEnum<{
+            primary: "primary";
+            "sub-agent": "sub-agent";
+        }>>;
+        delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * Model and instruction are optional at the type level because a nested
+ * (`yaml_reference`) or remote (`a2a_agent_url`) subagent brings its own; the
+ * "an ordinary subagent needs an instruction" rule is checked in
+ * crossFieldProblems so it can name the alternative keys in its message.
+ */
+export declare const subagentSchema: z.ZodObject<{
+    name: z.ZodString;
+    globalInstruction: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    require_approval: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    includeContents: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        none: "none";
+    }>>;
+    disallowTransferToParent: z.ZodOptional<z.ZodBoolean>;
+    disallowTransferToPeers: z.ZodOptional<z.ZodBoolean>;
+    outputKey: z.ZodOptional<z.ZodString>;
+    generateContentConfig: z.ZodOptional<z.ZodObject<{
+        temperature: z.ZodOptional<z.ZodNumber>;
+        topP: z.ZodOptional<z.ZodNumber>;
+        topK: z.ZodOptional<z.ZodNumber>;
+        maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        candidateCount: z.ZodOptional<z.ZodNumber>;
+        presencePenalty: z.ZodOptional<z.ZodNumber>;
+        frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+        seed: z.ZodOptional<z.ZodNumber>;
+        responseMimeType: z.ZodOptional<z.ZodString>;
+        safetySettings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            category: z.ZodString;
+            threshold: z.ZodString;
+        }, z.core.$loose>>>;
+        thinkingConfig: z.ZodOptional<z.ZodObject<{
+            thinkingBudget: z.ZodOptional<z.ZodNumber>;
+            includeThoughts: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    mcp_server_url: z.ZodOptional<z.ZodString>;
+    orchestration: z.ZodOptional<z.ZodObject<{
+        role: z.ZodOptional<z.ZodEnum<{
+            primary: "primary";
+            "sub-agent": "sub-agent";
+        }>>;
+        delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    description: z.ZodString;
+    model: z.ZodOptional<z.ZodString>;
+    instruction: z.ZodOptional<z.ZodString>;
+    yaml_reference: z.ZodOptional<z.ZodString>;
+    a2a_agent_url: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const syndicateSchema: z.ZodObject<{
+    syndicate_name: z.ZodString;
+    orchestrator: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        model: z.ZodString;
+        instruction: z.ZodString;
+        globalInstruction: z.ZodOptional<z.ZodString>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        require_approval: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        includeContents: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            none: "none";
+        }>>;
+        disallowTransferToParent: z.ZodOptional<z.ZodBoolean>;
+        disallowTransferToPeers: z.ZodOptional<z.ZodBoolean>;
+        outputKey: z.ZodOptional<z.ZodString>;
+        generateContentConfig: z.ZodOptional<z.ZodObject<{
+            temperature: z.ZodOptional<z.ZodNumber>;
+            topP: z.ZodOptional<z.ZodNumber>;
+            topK: z.ZodOptional<z.ZodNumber>;
+            maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+            stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            candidateCount: z.ZodOptional<z.ZodNumber>;
+            presencePenalty: z.ZodOptional<z.ZodNumber>;
+            frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+            seed: z.ZodOptional<z.ZodNumber>;
+            responseMimeType: z.ZodOptional<z.ZodString>;
+            safetySettings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                category: z.ZodString;
+                threshold: z.ZodString;
+            }, z.core.$loose>>>;
+            thinkingConfig: z.ZodOptional<z.ZodObject<{
+                thinkingBudget: z.ZodOptional<z.ZodNumber>;
+                includeThoughts: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        mcp_server_url: z.ZodOptional<z.ZodString>;
+        orchestration: z.ZodOptional<z.ZodObject<{
+            role: z.ZodOptional<z.ZodEnum<{
+                primary: "primary";
+                "sub-agent": "sub-agent";
+            }>>;
+            delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    subagents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        globalInstruction: z.ZodOptional<z.ZodString>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        require_approval: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        includeContents: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            none: "none";
+        }>>;
+        disallowTransferToParent: z.ZodOptional<z.ZodBoolean>;
+        disallowTransferToPeers: z.ZodOptional<z.ZodBoolean>;
+        outputKey: z.ZodOptional<z.ZodString>;
+        generateContentConfig: z.ZodOptional<z.ZodObject<{
+            temperature: z.ZodOptional<z.ZodNumber>;
+            topP: z.ZodOptional<z.ZodNumber>;
+            topK: z.ZodOptional<z.ZodNumber>;
+            maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+            stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            candidateCount: z.ZodOptional<z.ZodNumber>;
+            presencePenalty: z.ZodOptional<z.ZodNumber>;
+            frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+            seed: z.ZodOptional<z.ZodNumber>;
+            responseMimeType: z.ZodOptional<z.ZodString>;
+            safetySettings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                category: z.ZodString;
+                threshold: z.ZodString;
+            }, z.core.$loose>>>;
+            thinkingConfig: z.ZodOptional<z.ZodObject<{
+                thinkingBudget: z.ZodOptional<z.ZodNumber>;
+                includeThoughts: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        mcp_server_url: z.ZodOptional<z.ZodString>;
+        orchestration: z.ZodOptional<z.ZodObject<{
+            role: z.ZodOptional<z.ZodEnum<{
+                primary: "primary";
+                "sub-agent": "sub-agent";
+            }>>;
+            delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        description: z.ZodString;
+        model: z.ZodOptional<z.ZodString>;
+        instruction: z.ZodOptional<z.ZodString>;
+        yaml_reference: z.ZodOptional<z.ZodString>;
+        a2a_agent_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    dispatch: z.ZodOptional<z.ZodObject<{
+        default_route: z.ZodString;
+        route_key: z.ZodOptional<z.ZodString>;
+        reason_key: z.ZodOptional<z.ZodString>;
+        route_overrides: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            route: z.ZodString;
+            pattern: z.ZodString;
+            flags: z.ZodOptional<z.ZodString>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    memory_system: z.ZodOptional<z.ZodEnum<{
+        "internal-only": "internal-only";
+        "long-term": "long-term";
+        "session-only": "session-only";
+    }>>;
+    guards: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    memory_namespace: z.ZodOptional<z.ZodString>;
+    memory_extraction_rules: z.ZodOptional<z.ZodString>;
+    memory_extraction_model: z.ZodOptional<z.ZodString>;
+    memory_retention_days: z.ZodOptional<z.ZodNumber>;
+    max_steps: z.ZodOptional<z.ZodNumber>;
+    bundled_references: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strict>;
+/**
+ * The closest candidate, if it is close enough to be a typo. Case and
+ * snake/camel drift (`output_key` for `outputKey`) count as an exact match.
+ */
+export declare function suggest(input: string, candidates: readonly string[]): string | undefined;
+/**
+ * Thrown by validateSyndicateConfig. `problems` holds one `<file>: <path> —
+ * <what>` line per problem (the message lists them all); `issues` holds the
+ * same lines without the file, for callers that already show it.
+ */
+export declare class SyndicateValidationError extends Error {
+    readonly file: string | undefined;
+    readonly issues: string[];
+    readonly problems: string[];
+    constructor(issues: string[], file?: string);
+}
+/**
+ * Validate a parsed syndicate and return it typed, or throw ONE error that
+ * lists every problem as `<file>: <key.path> — <what is wrong>`.
+ *
+ * Runs on the interpolated config: a `{{token}}` inside a string is still a
+ * string, and a full-token number (`max_steps: "{{n}}"`) is checked as the
+ * value it resolved to.
+ */
+export declare function validateSyndicateConfig(raw: unknown, file?: string): SyndicateYamlConfig;
+/**
+ * The syndicate contract as JSON Schema (draft-07: the widest editor
+ * support), for `# yaml-language-server: $schema=` and other tooling.
+ * Cross-field rules zod expresses as code are added back where JSON Schema
+ * can say them, so an editor flags a subagent with no instruction too.
+ */
+export declare function syndicateJsonSchema(): Record<string, unknown>;