@kindgi/agents 0.0.0-bootstrap.0 → 0.1.0

package/dist/conversation-binding.d.ts

@@ -0,0 +1,111 @@
+import type { RunBinding } from '@kindgi/runtime';
+import type { Result, Semver, TenantId } from '@kindgi/types';
+import type { AgentError } from './errors.js';
+import type { AgentId, Conversation, ConversationId, ConversationMessage, MessageRole } from './types.js';
+export interface OpenConversationInput {
+    readonly tenantId: TenantId;
+    readonly agentId: AgentId;
+    readonly agentVersion: Semver;
+    readonly title: string;
+    readonly participantId?: string;
+    readonly scope: Readonly<Record<string, unknown>>;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ListConversationsInput {
+    readonly tenantId: TenantId;
+    readonly agentId?: AgentId;
+    readonly participantId?: string;
+    /** If true, only conversations without a `closedAt` are returned. Default false. */
+    readonly openOnly?: boolean;
+    readonly limit?: number;
+}
+export interface AppendMessageInput {
+    readonly tenantId: TenantId;
+    readonly conversationId: ConversationId;
+    readonly role: MessageRole;
+    readonly content: string | Readonly<Record<string, unknown>>;
+    readonly actor?: string;
+    readonly toolCall?: {
+        readonly toolId: string;
+        readonly invocationId: string;
+    };
+    /**
+     * When true, this message is a mid-turn assistant emission (e.g. the
+     * assistant message that contains tool calls before the final
+     * response). `turnCount` is NOT incremented for these — one turn is
+     * one user↔agent exchange, not one message. Default false; the final
+     * assistant response for a turn omits this flag (counts as a turn).
+     */
+    readonly isIntermediate?: boolean;
+}
+export interface ReadMessagesInput {
+    readonly tenantId: TenantId;
+    readonly conversationId: ConversationId;
+    readonly sinceSequence?: number;
+    readonly limit?: number;
+}
+/**
+ * Keyset marker used by `listConversationsPage`. When present, only
+ * rows strictly before this marker (by `openedAt` desc, then `id`
+ * desc) are returned. The api route encodes / decodes this to an
+ * opaque wire cursor.
+ */
+export interface ConversationPageCursor {
+    /** ISO 8601 `openedAt` timestamp of the last row from the previous page. */
+    readonly openedAt: string;
+    readonly id: ConversationId;
+}
+export interface ListConversationsPageInput {
+    readonly tenantId: TenantId;
+    readonly agentId?: AgentId;
+    /** When set, filter to open (no closedAt) or closed (closedAt set) rows only. */
+    readonly status?: 'open' | 'closed';
+    /** Keyset for the next page — see `ConversationPageCursor`. */
+    readonly before?: ConversationPageCursor;
+    /**
+     * Row cap PER PAGE. Impls fetch `limit + 1` internally to compute
+     * `hasMore` without a second query.
+     */
+    readonly limit: number;
+}
+export interface ConversationPage {
+    readonly data: readonly Conversation[];
+    readonly hasMore: boolean;
+}
+/**
+ * `ConversationBinding` — the public seam between @kindgi/agents and
+ * whatever conversation-store implementation a deployment plugs in
+ * (the Kindgi runtime ships a Postgres-backed one; alternatives possible).
+ *
+ * Every method is tenant-scoped: RLS (or the moral equivalent for
+ * non-Postgres impls) is expected to be enforced inside the binding.
+ * Callers pass the tenant on every method — the binding does not
+ * carry request-scoped identity.
+ *
+ * `closeConversation` accepts an optional `RunBinding` so the impl can
+ * cascade-cancel pending waitpoints owned by runs in the closing
+ * conversation. Impls without access to the run lifecycle skip the
+ * cascade.
+ *
+ * `appendMessage` / `readMessages` route message content through the
+ * memory subsystem — impls capture a `MemoryQueryBinding` at
+ * construction and expose it here transparently.
+ */
+export interface ConversationBinding {
+    openConversation(input: OpenConversationInput): Promise<Result<Conversation, AgentError>>;
+    getConversation(tenantId: TenantId, id: ConversationId): Promise<Result<Conversation, AgentError>>;
+    listConversations(input: ListConversationsInput): Promise<Result<readonly Conversation[], AgentError>>;
+    /**
+     * Cursor-paginated + keyset-ordered variant of `listConversations`
+     * for the HTTP surface. Sort: `openedAt DESC, id DESC` (chronological
+     * — most-recently-opened first, id disambiguating). Fills the
+     * `hasMore` marker inline. Filters: `agentId`, `status` (`open` /
+     * `closed`), `before` keyset.
+     */
+    listConversationsPage(input: ListConversationsPageInput): Promise<Result<ConversationPage, AgentError>>;
+    closeConversation(tenantId: TenantId, id: ConversationId, runBinding?: RunBinding): Promise<Result<Conversation, AgentError>>;
+    deleteConversation(tenantId: TenantId, id: ConversationId): Promise<Result<void, AgentError>>;
+    appendMessage(input: AppendMessageInput): Promise<Result<ConversationMessage, AgentError>>;
+    readMessages(input: ReadMessagesInput): Promise<Result<readonly ConversationMessage[], AgentError>>;
+}
+//# sourceMappingURL=conversation-binding.d.ts.map

package/dist/conversation-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-binding.d.ts","sourceRoot":"","sources":["../src/conversation-binding.ts"],"names":[],"mappings":"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"}

package/dist/conversation-binding.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=conversation-binding.js.map

package/dist/conversation-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-binding.js","sourceRoot":"","sources":["../src/conversation-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/define.d.ts

@@ -0,0 +1,180 @@
+import { type ToolErrorsSpec } from '@kindgi/policy-contract';
+import { type AnySchema } from '@kindgi/schema';
+import type { Result } from '@kindgi/types';
+import type { InvalidAgentError } from './errors.js';
+import type { Agent, ConversationPolicy, PromptParameter, RetrievalIntent, ToolRef, TurnBudget } from './types.js';
+/**
+ * Public API to construct an agent definition. Validates every field,
+ * brands ids, and returns a `Result` — no throws.
+ *
+ * ```ts
+ * const agent = defineAgent({
+ *   id: 'acme.citation-verifier',
+ *   version: '1.0.0',
+ *   name: 'Citation Verifier',
+ *   instructions: 'Verify every citation against the case-law index.',
+ *   capabilities: [{ needs: [{ feature: 'structured-output' }] }],
+ *   tools: [{ id: 'acme.verify-citation', version: '1.0.0' }],
+ *   retrieval: [{ types: ['prior-verification'], scope: 'same-project' }],
+ *   guardrails: ['no-hallucinated-citations'],
+ * });
+ * if (agent.kind === 'err') throw new Error(agent.error.message);
+ * registry.register(agent.value);
+ * ```
+ */
+export declare function defineAgent(spec: DefineAgentSpec): Result<Agent, InvalidAgentError>;
+/**
+ * Author-facing input shape for `defineAgent`. `id` and `version` are
+ * strings (they get branded inside `defineAgent`); array fields are
+ * `readonly` so callers can pass literal arrays.
+ *
+ * ## Field-by-field authoring guide
+ *
+ * The most common author mistake is treating `tools` as a list of
+ * tool ids (strings). It is NOT — it is a list of `{id, version}`
+ * refs where `version` is an npm-style semver RANGE (`'^1.0.0'`,
+ * `'~1.2.3'`, `'1.0.0'`, `'>=1.0.0 <2.0.0'`). Resolution happens at
+ * run start via `semver.maxSatisfying`.
+ *
+ * @example
+ * ```ts
+ * const agent = defineAgent({
+ *   id: 'my-pack.summarizer',
+ *   version: '1.0.0',
+ *   name: 'Summarizer',
+ *   instructions: 'Summarize the user message in one sentence.',
+ *   capabilities: [{ needs: [{ feature: 'tool-use' }] }],
+ *   tools: [
+ *     { id: 'my-pack.fetch-doc', version: '^0.1.0' },
+ *   ],
+ *   retrieval: [],
+ *   guardrails: [],
+ *   budget: { maxSteps: 6, maxCostUsd: 0.1, maxWallMs: 30_000 },
+ * });
+ * ```
+ */
+export interface DefineAgentSpec {
+    /**
+     * Business identifier. Convention: `<pack-id>.<agent-name>` (e.g.
+     * `'acme.contract-reviewer'`). Non-empty. Gets branded as
+     * `AgentId` inside `defineAgent`.
+     */
+    readonly id: string;
+    /**
+     * Exact semver of THIS agent revision (e.g. `'1.0.0'`,
+     * `'0.2.1-alpha.3'`). Distinct from tool version RANGES on
+     * `tools[]`. Every publish under the same id must bump this.
+     */
+    readonly version: string;
+    /** Human-readable name for UI and logs. */
+    readonly name: string;
+    /** Optional longer description shown in catalogs / admin surfaces. */
+    readonly description?: string;
+    /**
+     * The system prompt. Sent to the model with every turn as the
+     * baseline instructions. Load-bearing — this is where you shape
+     * the agent's behavior (persona, output format, tool-use policy).
+     */
+    readonly instructions: string;
+    /**
+     * Required capabilities the agent needs from a `ModelProvider`.
+     * Typically one entry: `[{ needs: [{ feature: 'tool-use' }] }]`
+     * for a tool-calling agent, `[{ needs: [{ feature: 'structured-output' }] }]`
+     * for an agent that returns schema-constrained JSON. The router uses
+     * the first entry to pick a compatible provider from the tenant's
+     * `ProviderRegistry`.
+     */
+    readonly capabilities: Agent['capabilities'];
+    /**
+     * Tools the agent may call. **NOT** a list of tool ids —
+     * a list of `{id, version}` refs where `version` is an npm-style
+     * semver range. At run start, each ref resolves against the
+     * registered versions via `semver.maxSatisfying`; unresolvable
+     * refs fail the turn with `tool-version-unresolvable`.
+     *
+     * The model sees each tool's `id`, `description`, and input
+     * schema — write tool descriptions carefully (that's what the
+     * LLM reads to decide when to call).
+     */
+    readonly tools: readonly ToolRef[];
+    /**
+     * Retrieval intents the agent runs BEFORE calling the model.
+     * Each intent names fact types, a scope, and a retrieval mode; the
+     * results are injected into the model input as retrieved
+     * context. Empty array `[]` = no retrieval, model sees only the
+     * conversation history + user message.
+     */
+    readonly retrieval: readonly RetrievalIntent[];
+    /**
+     * Guardrail IDs that guard this agent's turns. Each id must
+     * resolve among the guardrails bound for the run, or the turn fails
+     * with `unresolved-guardrail`. Guardrails are evaluated once per
+     * turn, on the final response before it is stored — see
+     * `defineCheck` for the checker side.
+     *
+     * Empty array `[]` = no guarding.
+     */
+    readonly guardrails: readonly string[];
+    /**
+     * Optional named prompt parameters. Callers pass values for these
+     * in `invokeAgent({parameters: {...}})`; the framework substitutes
+     * them into `instructions`. Each parameter declares its type +
+     * default. Absent = agent takes no runtime parameters.
+     */
+    readonly parameters?: readonly PromptParameter[];
+    /**
+     * Preferred model provider by id. Soft hint — the router prefers
+     * this provider when it satisfies `capabilities.needs` + tenant
+     * policy, falling back to normal capability-based selection when
+     * the preferred provider is unregistered or filtered out. Enables
+     * A/B'ing agents across providers without churning registrations:
+     * register several, pin the agent to the one you want to test.
+     *
+     * The value is a `ProviderMetadata.id` string (e.g.
+     * `'anthropic-claude-sonnet-4-6'`). Unset = capability-match only.
+     */
+    readonly preferredProvider?: string;
+    /**
+     * Preferred model name within the selected provider. Soft hint — see
+     * `Agent.preferredModel`.
+     */
+    readonly preferredModel?: string;
+    /**
+     * A typed result: the final answer must be JSON matching `schema`
+     * (JSON Schema, or a Zod schema converted at definition time). An
+     * invalid answer is sent back to the model with the problems listed,
+     * up to `maxRepairs` times (default 1). See `AgentOutputSpec`.
+     */
+    readonly output?: {
+        readonly schema: AnySchema;
+        readonly name?: string;
+        readonly maxRepairs?: number;
+    };
+    /**
+     * What the turn does when a tool call fails: the failure goes back to
+     * the model as the call's result, so it can correct the call, up to
+     * `maxRetries` times per turn, for the kinds in `retryOn`. Default:
+     * one retry, for `invalid-arguments` and `unknown-tool` (nothing ran).
+     * A tenant's `tool-errors` policy can lower it. See `ToolErrorsSpec`.
+     */
+    readonly toolErrors?: ToolErrorsSpec;
+    /**
+     * Per-conversation behavior — how much history to load, when to
+     * gate on HITL, when to auto-close. Every field optional; defaults
+     * are "load the full history, no HITL, no auto-close". See
+     * `ConversationPolicy` for the full shape including tool-level
+     * HITL rules.
+     */
+    readonly conversationPolicy?: ConversationPolicy;
+    /**
+     * Turn budget caps. `maxSteps` limits model+tool call loop
+     * iterations per turn; `maxCostUsd` caps model spend per turn;
+     * `maxWallMs` bounds turn wall-clock time. Exceeding any cap
+     * ends the turn with a `budget-exceeded` failure. Sensible dev
+     * defaults: `{maxSteps: 6, maxCostUsd: 0.1, maxWallMs: 30_000}`.
+     */
+    readonly budget?: TurnBudget;
+    /** Free-form tags for catalog filtering. Not interpreted by the runtime. */
+    readonly tags?: readonly string[];
+}
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,cAAc,EAA0B,MAAM,yBAAyB,CAAC;AACtF,OAAO,EACL,KAAK,SAAS,EAKf,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAAU,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EACV,KAAK,EAGL,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,OAAO,EACP,UAAU,EACX,MAAM,YAAY,CAAC;AAIpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC,KAAK,EAAE,iBAAiB,CAAC,CA6BnF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC7C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;QAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC"}

package/dist/define.js

@@ -0,0 +1,361 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { validateToolErrorsSpec } from '@kindgi/policy-contract';
+import { compileInlineSchema, isZodSchema, loadZodConverterSync, toJSONSchemaSync, } from '@kindgi/schema';
+/**
+ * Public API to construct an agent definition. Validates every field,
+ * brands ids, and returns a `Result` — no throws.
+ *
+ * ```ts
+ * const agent = defineAgent({
+ *   id: 'acme.citation-verifier',
+ *   version: '1.0.0',
+ *   name: 'Citation Verifier',
+ *   instructions: 'Verify every citation against the case-law index.',
+ *   capabilities: [{ needs: [{ feature: 'structured-output' }] }],
+ *   tools: [{ id: 'acme.verify-citation', version: '1.0.0' }],
+ *   retrieval: [{ types: ['prior-verification'], scope: 'same-project' }],
+ *   guardrails: ['no-hallucinated-citations'],
+ * });
+ * if (agent.kind === 'err') throw new Error(agent.error.message);
+ * registry.register(agent.value);
+ * ```
+ */
+export function defineAgent(spec) {
+    const issues = [
+        ...validateIdentity(spec),
+        ...validateContent(spec),
+        ...validateArrays(spec),
+        ...validateRetrieval(spec),
+        ...validateParameters(spec.parameters),
+        ...validateBudget(spec.budget),
+        ...validateConversationPolicy(spec.conversationPolicy),
+        ...validateToolErrors(spec.toolErrors),
+    ];
+    const output = resolveOutput(spec.output);
+    if (output.kind === 'err')
+        issues.push(...output.issues);
+    if (issues.length > 0) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'invalid-agent',
+                message: `Agent "${String(spec.id)}" is invalid (${issues.length} issue${issues.length === 1 ? '' : 's'})`,
+                issues,
+            },
+        };
+    }
+    return {
+        kind: 'ok',
+        value: buildAgent(spec, output.kind === 'ok' ? output.value : undefined),
+    };
+}
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+function validateIdentity(spec) {
+    const out = [];
+    if (typeof spec.id !== 'string' || spec.id.trim().length === 0) {
+        out.push({ path: '/id', message: 'id must be a non-empty string' });
+    }
+    if (typeof spec.version !== 'string' || !SEMVER_RE.test(spec.version)) {
+        out.push({ path: '/version', message: 'version must be a valid semver string' });
+    }
+    if (typeof spec.name !== 'string' || spec.name.trim().length === 0) {
+        out.push({ path: '/name', message: 'name must be a non-empty string' });
+    }
+    return out;
+}
+function validateContent(spec) {
+    const out = [];
+    if (typeof spec.instructions !== 'string' || spec.instructions.trim().length === 0) {
+        out.push({ path: '/instructions', message: 'instructions must be a non-empty string' });
+    }
+    if (!Array.isArray(spec.capabilities) || spec.capabilities.length === 0) {
+        out.push({
+            path: '/capabilities',
+            message: 'capabilities must be a non-empty array of Capability declarations',
+        });
+    }
+    return out;
+}
+function validateArrays(spec) {
+    const out = [];
+    if (!Array.isArray(spec.tools)) {
+        out.push({
+            path: '/tools',
+            message: 'tools must be an array of { id: string, version: string } refs. No bare-string ids — every tool must carry a semver range.',
+        });
+    }
+    else {
+        spec.tools.forEach((ref, i) => out.push(...validateToolRef(ref, i)));
+    }
+    if (!Array.isArray(spec.guardrails)) {
+        out.push({ path: '/guardrails', message: 'guardrails must be an array of guardrail ids' });
+    }
+    return out;
+}
+function validateToolRef(ref, i) {
+    const out = [];
+    if (ref === null || typeof ref !== 'object') {
+        out.push({
+            path: `/tools/${i}`,
+            message: 'each tool must be a { id, version } object; bare-string ids are not allowed',
+        });
+        return out;
+    }
+    const obj = ref;
+    if (typeof obj.id !== 'string' || obj.id.trim().length === 0) {
+        out.push({ path: `/tools/${i}/id`, message: 'tool id must be a non-empty string' });
+    }
+    if (typeof obj.version !== 'string' || obj.version.trim().length === 0) {
+        out.push({
+            path: `/tools/${i}/version`,
+            message: 'tool version must be a non-empty semver range string (e.g., "1.2.3", "^1.2.3", "~1.2.3"). Deep grammar validation runs at dispatch time via the `semver` library.',
+        });
+    }
+    return out;
+}
+function validateRetrieval(spec) {
+    if (!Array.isArray(spec.retrieval)) {
+        return [{ path: '/retrieval', message: 'retrieval must be an array of RetrievalIntents' }];
+    }
+    const out = [];
+    spec.retrieval.forEach((intent, i) => out.push(...validateIntent(intent, i)));
+    return out;
+}
+function validateIntent(intent, i) {
+    const out = [];
+    if (!Array.isArray(intent.types) || intent.types.length === 0) {
+        out.push({
+            path: `/retrieval/${i}/types`,
+            message: 'each retrieval intent must declare at least one type',
+        });
+    }
+    if (intent.scope !== 'same-conversation' &&
+        intent.scope !== 'same-project' &&
+        intent.scope !== 'tenant') {
+        out.push({
+            path: `/retrieval/${i}/scope`,
+            message: 'scope must be same-conversation, same-project, or tenant',
+        });
+    }
+    if (intent.limit !== undefined && (!Number.isInteger(intent.limit) || intent.limit <= 0)) {
+        out.push({ path: `/retrieval/${i}/limit`, message: 'limit must be a positive integer' });
+    }
+    return out;
+}
+const VALID_PARAM_TYPES = new Set(['string', 'number', 'boolean', 'date']);
+const AUTO_INJECTED_NAMES = new Set(['today', 'now', 'agent', 'conversation']);
+function validateParameters(parameters) {
+    if (parameters === undefined)
+        return [];
+    const out = [];
+    const seen = new Set();
+    parameters.forEach((p, i) => {
+        if (typeof p.name !== 'string' || p.name.trim().length === 0) {
+            out.push({ path: `/parameters/${i}/name`, message: 'name must be a non-empty string' });
+        }
+        if (seen.has(p.name)) {
+            out.push({
+                path: `/parameters/${i}/name`,
+                message: `duplicate parameter name "${p.name}"`,
+            });
+        }
+        seen.add(p.name);
+        if (AUTO_INJECTED_NAMES.has(p.name)) {
+            out.push({
+                path: `/parameters/${i}/name`,
+                message: `"${p.name}" is a reserved auto-injected variable — do not declare it as a parameter`,
+            });
+        }
+        if (!VALID_PARAM_TYPES.has(p.type)) {
+            out.push({
+                path: `/parameters/${i}/type`,
+                message: 'type must be string, number, boolean, or date',
+            });
+        }
+    });
+    return out;
+}
+function validateBudget(budget) {
+    if (budget === undefined)
+        return [];
+    const out = [];
+    if (budget.maxSteps !== undefined &&
+        (!Number.isInteger(budget.maxSteps) || budget.maxSteps <= 0)) {
+        out.push({ path: '/budget/maxSteps', message: 'maxSteps must be a positive integer' });
+    }
+    if (budget.maxCostUsd !== undefined &&
+        (typeof budget.maxCostUsd !== 'number' || budget.maxCostUsd < 0)) {
+        out.push({
+            path: '/budget/maxCostUsd',
+            message: 'maxCostUsd must be a non-negative number',
+        });
+    }
+    if (budget.maxWallMs !== undefined &&
+        (!Number.isInteger(budget.maxWallMs) || budget.maxWallMs <= 0)) {
+        out.push({ path: '/budget/maxWallMs', message: 'maxWallMs must be a positive integer' });
+    }
+    return out;
+}
+function validateToolErrors(toolErrors) {
+    if (toolErrors === undefined)
+        return [];
+    const checked = validateToolErrorsSpec(toolErrors);
+    return checked.kind === 'ok'
+        ? []
+        : checked.issues.map((i) => ({ path: `/toolErrors${i.path}`, message: i.message }));
+}
+function validateConversationPolicy(policy) {
+    if (policy === undefined)
+        return [];
+    const out = [];
+    if (policy.historyLimit !== undefined &&
+        (!Number.isInteger(policy.historyLimit) || policy.historyLimit <= 0)) {
+        out.push({
+            path: '/conversationPolicy/historyLimit',
+            message: 'historyLimit must be a positive integer',
+        });
+    }
+    if (policy.autoCloseAfterInactiveSeconds !== undefined &&
+        (!Number.isInteger(policy.autoCloseAfterInactiveSeconds) ||
+            policy.autoCloseAfterInactiveSeconds <= 0)) {
+        out.push({
+            path: '/conversationPolicy/autoCloseAfterInactiveSeconds',
+            message: 'autoCloseAfterInactiveSeconds must be a positive integer',
+        });
+    }
+    if (policy.hitlAfterTurns !== undefined &&
+        (!Number.isInteger(policy.hitlAfterTurns) || policy.hitlAfterTurns <= 0)) {
+        out.push({
+            path: '/conversationPolicy/hitlAfterTurns',
+            message: 'hitlAfterTurns must be a positive integer',
+        });
+    }
+    // Nested hitl policy.
+    if (policy.hitl !== undefined) {
+        const h = policy.hitl;
+        if (h.afterTurns !== undefined && (!Number.isInteger(h.afterTurns) || h.afterTurns <= 0)) {
+            out.push({
+                path: '/conversationPolicy/hitl/afterTurns',
+                message: 'hitl.afterTurns must be a positive integer',
+            });
+        }
+        if (h.timeoutMs !== undefined && (!Number.isInteger(h.timeoutMs) || h.timeoutMs <= 0)) {
+            out.push({
+                path: '/conversationPolicy/hitl/timeoutMs',
+                message: 'hitl.timeoutMs must be a positive integer (ms)',
+            });
+        }
+        const ROLES = new Set(['standard', 'senior', 'admin']);
+        if (h.defaultReviewerRole !== undefined &&
+            !ROLES.has(h.defaultReviewerRole)) {
+            out.push({
+                path: '/conversationPolicy/hitl/defaultReviewerRole',
+                message: 'hitl.defaultReviewerRole must be one of: standard, senior, admin',
+            });
+        }
+        const MODES = new Set(['never_ask', 'ask_on_first_use', 'always_ask']);
+        if (h.tools?.default !== undefined && !MODES.has(h.tools.default)) {
+            out.push({
+                path: '/conversationPolicy/hitl/tools/default',
+                message: 'hitl.tools.default must be one of: never_ask, ask_on_first_use, always_ask',
+            });
+        }
+        if (h.tools?.overrides !== undefined) {
+            for (const [toolId, rule] of Object.entries(h.tools.overrides)) {
+                const mode = typeof rule === 'string' ? rule : rule.mode;
+                if (!MODES.has(mode)) {
+                    out.push({
+                        path: `/conversationPolicy/hitl/tools/overrides/${toolId}`,
+                        message: 'override mode must be one of: never_ask, ask_on_first_use, always_ask',
+                    });
+                }
+                if (typeof rule === 'object' &&
+                    rule.requiredRole !== undefined &&
+                    !ROLES.has(rule.requiredRole)) {
+                    out.push({
+                        path: `/conversationPolicy/hitl/tools/overrides/${toolId}/requiredRole`,
+                        message: 'override requiredRole must be one of: standard, senior, admin',
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}
+/** The output spec in its wire form: JSON Schema that compiles, and a valid repair count. */
+function resolveOutput(output) {
+    if (output === undefined)
+        return { kind: 'none' };
+    const issues = [];
+    if (output.maxRepairs !== undefined &&
+        (!Number.isInteger(output.maxRepairs) || output.maxRepairs < 0)) {
+        issues.push({
+            path: '/output/maxRepairs',
+            message: 'maxRepairs must be a non-negative integer',
+        });
+    }
+    if (output.name !== undefined && (typeof output.name !== 'string' || output.name.length === 0)) {
+        issues.push({ path: '/output/name', message: 'name must be a non-empty string' });
+    }
+    let schema;
+    if (isZodSchema(output.schema)) {
+        // The output side: downstream steps read every field, defaulted ones included.
+        const converted = toJSONSchemaSync(output.schema, loadZodConverterSync(), 'output');
+        if (converted.kind === 'err') {
+            return {
+                kind: 'err',
+                issues: [...issues, { path: '/output/schema', message: converted.error.message }],
+            };
+        }
+        schema = converted.value;
+    }
+    else {
+        schema = output.schema;
+    }
+    const compiled = compileInlineSchema(schema);
+    if (compiled.kind === 'err') {
+        issues.push({ path: '/output/schema', message: compiled.error.message });
+    }
+    if (issues.length > 0)
+        return { kind: 'err', issues };
+    return {
+        kind: 'ok',
+        value: {
+            schema,
+            ...(output.name !== undefined && { name: output.name }),
+            ...(output.maxRepairs !== undefined && { maxRepairs: output.maxRepairs }),
+        },
+    };
+}
+function buildAgent(spec, output) {
+    return {
+        id: spec.id,
+        version: spec.version,
+        name: spec.name,
+        ...(spec.description !== undefined && { description: spec.description }),
+        instructions: spec.instructions,
+        capabilities: spec.capabilities.map((c) => ({ ...c })),
+        tools: [...spec.tools],
+        retrieval: spec.retrieval.map((r) => ({ ...r })),
+        guardrails: [...spec.guardrails],
+        ...(spec.parameters !== undefined && {
+            parameters: spec.parameters.map((p) => ({ ...p })),
+        }),
+        ...(spec.preferredProvider !== undefined && { preferredProvider: spec.preferredProvider }),
+        ...(spec.preferredModel !== undefined && { preferredModel: spec.preferredModel }),
+        ...(spec.conversationPolicy !== undefined && {
+            conversationPolicy: { ...spec.conversationPolicy },
+        }),
+        ...(spec.budget !== undefined && { budget: { ...spec.budget } }),
+        ...(spec.tags !== undefined && { tags: [...spec.tags] }),
+        ...(output !== undefined && { output }),
+        ...(spec.toolErrors !== undefined && {
+            toolErrors: {
+                ...spec.toolErrors,
+                ...(spec.toolErrors.retryOn !== undefined && { retryOn: [...spec.toolErrors.retryOn] }),
+            },
+        }),
+    };
+}
+//# sourceMappingURL=define.js.map