@atoms-agent/core 0.3.0

package/dist/spec.d.ts

@@ -0,0 +1,29 @@
+import type { JsonValue } from "@atoms-agent/llm";
+import type { RunLimits } from "./limits.js";
+import { type StructuredOutputConfig } from "./structured-output.js";
+/**
+ * AgentSpec —— 可序列化的 Agent 声明（PRD §8.1）。
+ *
+ * 只包含 Ref 与 JSON 数据；禁止 Function、Class Instance、Provider Client、
+ * Secret、AbortSignal（核心不变量 7）。Ref 由 RuntimeRegistry 在运行时解析。
+ */
+export type AgentSpec = {
+    id: string;
+    model: {
+        ref: string;
+    };
+    systemPrompt: string;
+    tools: Array<{
+        ref: string;
+        config?: JsonValue;
+    }>;
+    context?: {
+        ref: string;
+        config?: JsonValue;
+    };
+    limits?: RunLimits;
+    structuredOutput?: StructuredOutputConfig;
+};
+/** Run 前的运行时边界校验；拒绝 TypeScript 类型系统外传入的非法对象。 */
+export declare function assertAgentSpec(value: unknown): asserts value is AgentSpec;
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAgC,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEnG;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IAClD,OAAO,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC;IAC9C,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C,CAAC;AAwBF,gDAAgD;AAChD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,CAwD1E"}

package/dist/spec.js

@@ -0,0 +1,141 @@
+import { AtomsAgentError } from "@atoms-agent/llm";
+import { MAX_TIMEOUT_MS } from "./limits.js";
+import { assertStructuredOutputConfig } from "./structured-output.js";
+const SPEC_KEYS = new Set([
+    "id",
+    "model",
+    "systemPrompt",
+    "tools",
+    "context",
+    "limits",
+    "structuredOutput",
+]);
+const BINDING_KEYS = new Set(["ref", "config"]);
+const MODEL_KEYS = new Set(["ref"]);
+const LIMIT_KEYS = new Set(["maxTurns", "timeoutMs"]);
+const SECRET_KEYS = new Set([
+    "apikey",
+    "api_key",
+    "secret",
+    "password",
+    "credential",
+    "accesstoken",
+    "auth_token",
+]);
+/** Run 前的运行时边界校验；拒绝 TypeScript 类型系统外传入的非法对象。 */
+export function assertAgentSpec(value) {
+    const spec = requirePlainObject(value, "AgentSpec");
+    assertOnlyKeys(spec, SPEC_KEYS, "AgentSpec");
+    requireNonEmptyString(spec.id, "AgentSpec.id");
+    if (typeof spec.systemPrompt !== "string") {
+        configError("AgentSpec.systemPrompt must be a string.");
+    }
+    const model = requirePlainObject(spec.model, "AgentSpec.model");
+    assertOnlyKeys(model, MODEL_KEYS, "AgentSpec.model");
+    requireNonEmptyString(model.ref, "AgentSpec.model.ref");
+    if (!Array.isArray(spec.tools)) {
+        configError("AgentSpec.tools must be an array.");
+    }
+    const toolRefs = new Set();
+    for (const [index, binding] of spec.tools.entries()) {
+        const ref = assertBinding(binding, `AgentSpec.tools[${index}]`);
+        if (toolRefs.has(ref)) {
+            configError(`AgentSpec contains duplicate Tool ref ${ref}.`);
+        }
+        toolRefs.add(ref);
+    }
+    if (Object.hasOwn(spec, "context") && spec.context === undefined) {
+        configError("AgentSpec.context must not be undefined when present.");
+    }
+    if (spec.context !== undefined) {
+        assertBinding(spec.context, "AgentSpec.context");
+    }
+    if (Object.hasOwn(spec, "limits") && spec.limits === undefined) {
+        configError("AgentSpec.limits must not be undefined when present.");
+    }
+    if (spec.limits !== undefined) {
+        const limits = requirePlainObject(spec.limits, "AgentSpec.limits");
+        assertOnlyKeys(limits, LIMIT_KEYS, "AgentSpec.limits");
+        for (const key of LIMIT_KEYS) {
+            if (Object.hasOwn(limits, key)) {
+                const limit = limits[key];
+                if (!Number.isInteger(limit) || limit <= 0) {
+                    configError(`AgentSpec.limits.${key} must be a positive integer.`);
+                }
+                if (key === "timeoutMs" && limit > MAX_TIMEOUT_MS) {
+                    configError(`AgentSpec.limits.timeoutMs must not exceed ${MAX_TIMEOUT_MS}.`);
+                }
+            }
+        }
+    }
+    if (Object.hasOwn(spec, "structuredOutput") && spec.structuredOutput === undefined) {
+        configError("AgentSpec.structuredOutput must not be undefined when present.");
+    }
+    if (spec.structuredOutput !== undefined) {
+        assertStructuredOutputConfig(spec.structuredOutput, "AgentSpec.structuredOutput");
+    }
+}
+function assertBinding(value, path) {
+    const binding = requirePlainObject(value, path);
+    assertOnlyKeys(binding, BINDING_KEYS, path);
+    const ref = requireNonEmptyString(binding.ref, `${path}.ref`);
+    if (Object.hasOwn(binding, "config")) {
+        assertJsonValue(binding.config, `${path}.config`, new WeakSet());
+    }
+    return ref;
+}
+function assertJsonValue(value, path, seen) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value))) {
+        return;
+    }
+    if (typeof value !== "object") {
+        configError(`${path} must contain only JSON-safe values.`);
+    }
+    if (seen.has(value)) {
+        configError(`${path} must not contain circular references.`);
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertJsonValue(item, `${path}[${index}]`, seen));
+    }
+    else {
+        const object = requirePlainObject(value, path);
+        for (const [key, item] of Object.entries(object)) {
+            if (SECRET_KEYS.has(key.toLowerCase())) {
+                configError(`${path} must not contain secrets (${key}).`);
+            }
+            assertJsonValue(item, `${path}.${key}`, seen);
+        }
+    }
+    seen.delete(value);
+}
+function requirePlainObject(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        configError(`${path} must be a plain object.`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        configError(`${path} must be a plain object.`);
+    }
+    return value;
+}
+function assertOnlyKeys(value, allowed, path) {
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string" || !allowed.has(key)) {
+            configError(`${path} contains unsupported field ${String(key)}.`);
+        }
+    }
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        configError(`${path} must be a non-empty string.`);
+    }
+    return value;
+}
+function configError(message) {
+    throw new AtomsAgentError("CONFIG_ERROR", message);
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

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

package/dist/state.d.ts

@@ -0,0 +1,42 @@
+import type { AgentMessage } from "@atoms-agent/llm";
+/**
+ * AgentState —— 运行所需的最小状态（PRD §8.5）。
+ *
+ * v0.2（任务 V202）提供 JSON 导出/恢复；不承诺 Crash Consistency、
+ * 并发写入或副作用恢复。不保存 Function、Client、Secret 或 Active Operation。
+ */
+export type AgentState = {
+    messages: AgentMessage[];
+};
+/** 当前 Snapshot 协议版本；不兼容版本在 restore 时被拒绝。 */
+export declare const AGENT_STATE_SCHEMA_VERSION: 1;
+/**
+ * 应用层可持久化的 JSON-safe 快照。
+ *
+ * 只包含消息历史与 schemaVersion。不包含 AgentSpec、Registry Binding、
+ * AbortSignal、Provider Client 或未完成的 Tool 操作。
+ */
+export type AgentStateSnapshot = {
+    schemaVersion: typeof AGENT_STATE_SCHEMA_VERSION;
+    messages: AgentMessage[];
+};
+/**
+ * 导出 JSON-safe 状态快照（深拷贝）。
+ * 返回值可直接 `JSON.stringify` 并由应用层自行存储。
+ */
+export declare function exportState(state: AgentState): AgentStateSnapshot;
+/**
+ * 校验并恢复 AgentState。
+ *
+ * - 拒绝未知/不兼容 schemaVersion。
+ * - 校验每条 Message 的 role 与 Content Block 结构。
+ * - 校验 Tool Call/Result 的顺序、一一配对、ID 与名称。
+ * - 拒绝 Function、Class Instance、循环引用与非 JSON 值。
+ * - 不承诺 Crash Consistency、并发写或副作用恢复。
+ */
+export declare function restoreState(snapshot: unknown): AgentState;
+/** 运行时校验 Snapshot；通过后返回窄化后的类型。 */
+export declare function assertAgentStateSnapshot(value: unknown): AgentStateSnapshot;
+/** 验证消息结构以及 Assistant Tool Call 与紧随其后的 Tool Result 配对。 */
+export declare function assertAgentMessageHistory(value: unknown, path: string): AgentMessage[];
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAQb,MAAM,kBAAkB,CAAC;AAG1B;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B,CAAC;AAEF,4CAA4C;AAC5C,eAAO,MAAM,0BAA0B,EAAG,CAAU,CAAC;AAErD;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,aAAa,EAAE,OAAO,0BAA0B,CAAC;IACjD,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B,CAAC;AAQF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,kBAAkB,CAMjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU,CAK1D;AAED,kCAAkC;AAClC,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAe3E;AAED,0DAA0D;AAC1D,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,CAOtF"}

package/dist/state.js

@@ -0,0 +1,263 @@
+import { AtomsAgentError } from "@atoms-agent/llm";
+/** 当前 Snapshot 协议版本；不兼容版本在 restore 时被拒绝。 */
+export const AGENT_STATE_SCHEMA_VERSION = 1;
+const SNAPSHOT_KEYS = new Set(["schemaVersion", "messages"]);
+const MESSAGE_KEYS = new Set(["role", "content"]);
+const TEXT_BLOCK_KEYS = new Set(["type", "text"]);
+const TOOL_CALL_KEYS = new Set(["type", "toolCallId", "toolName", "input"]);
+const TOOL_RESULT_KEYS = new Set(["type", "toolCallId", "toolName", "content", "isError"]);
+/**
+ * 导出 JSON-safe 状态快照（深拷贝）。
+ * 返回值可直接 `JSON.stringify` 并由应用层自行存储。
+ */
+export function exportState(state) {
+    const messages = assertAgentMessageHistory(state.messages, "AgentState.messages");
+    return {
+        schemaVersion: AGENT_STATE_SCHEMA_VERSION,
+        messages,
+    };
+}
+/**
+ * 校验并恢复 AgentState。
+ *
+ * - 拒绝未知/不兼容 schemaVersion。
+ * - 校验每条 Message 的 role 与 Content Block 结构。
+ * - 校验 Tool Call/Result 的顺序、一一配对、ID 与名称。
+ * - 拒绝 Function、Class Instance、循环引用与非 JSON 值。
+ * - 不承诺 Crash Consistency、并发写或副作用恢复。
+ */
+export function restoreState(snapshot) {
+    const validated = assertAgentStateSnapshot(snapshot);
+    return {
+        messages: structuredClone(validated.messages),
+    };
+}
+/** 运行时校验 Snapshot；通过后返回窄化后的类型。 */
+export function assertAgentStateSnapshot(value) {
+    const snapshot = requirePlainObject(value, "AgentStateSnapshot");
+    assertOnlyKeys(snapshot, SNAPSHOT_KEYS, "AgentStateSnapshot");
+    if (snapshot.schemaVersion !== AGENT_STATE_SCHEMA_VERSION) {
+        configError(`AgentStateSnapshot.schemaVersion must be ${AGENT_STATE_SCHEMA_VERSION}; got ${String(snapshot.schemaVersion)}.`);
+    }
+    const messages = assertAgentMessageHistory(snapshot.messages, "AgentStateSnapshot.messages");
+    return {
+        schemaVersion: AGENT_STATE_SCHEMA_VERSION,
+        messages,
+    };
+}
+/** 验证消息结构以及 Assistant Tool Call 与紧随其后的 Tool Result 配对。 */
+export function assertAgentMessageHistory(value, path) {
+    if (!Array.isArray(value)) {
+        configError(`${path} must be an array.`);
+    }
+    const messages = value.map((message, index) => assertAgentMessage(message, `${path}[${index}]`));
+    assertToolResultPairing(messages, path);
+    return messages;
+}
+function assertAgentMessage(value, path) {
+    const message = requirePlainObject(value, path);
+    assertOnlyKeys(message, MESSAGE_KEYS, path);
+    if (message.role === "user") {
+        return assertUserMessage(message, path);
+    }
+    if (message.role === "assistant") {
+        return assertAssistantMessage(message, path);
+    }
+    if (message.role === "tool") {
+        return assertToolMessage(message, path);
+    }
+    configError(`${path}.role must be "user", "assistant", or "tool".`);
+}
+function assertUserMessage(message, path) {
+    if (!Array.isArray(message.content) || message.content.length === 0) {
+        configError(`${path}.content must be a non-empty array of text blocks.`);
+    }
+    return {
+        role: "user",
+        content: message.content.map((block, index) => assertTextBlock(block, `${path}.content[${index}]`)),
+    };
+}
+function assertAssistantMessage(message, path) {
+    if (!Array.isArray(message.content)) {
+        configError(`${path}.content must be an array of text/tool_call blocks.`);
+    }
+    return {
+        role: "assistant",
+        content: message.content.map((block, index) => assertAssistantBlock(block, `${path}.content[${index}]`)),
+    };
+}
+function assertToolResultPairing(messages, path) {
+    let pending;
+    for (const [index, message] of messages.entries()) {
+        if (pending !== undefined) {
+            if (message.role !== "tool") {
+                configError(`${path}[${pending.index}] Tool Calls must be followed immediately by one Tool Result message.`);
+            }
+            if (message.content.length !== pending.calls.length) {
+                configError(`${path}[${index}] must contain exactly one result for each preceding Tool Call.`);
+            }
+            const resultIds = new Set();
+            for (const result of message.content) {
+                const call = pending.byId.get(result.toolCallId);
+                if (call === undefined ||
+                    resultIds.has(result.toolCallId) ||
+                    call.toolName !== result.toolName) {
+                    configError(`${path}[${index}] contains an unmatched or duplicate Tool Result.`);
+                }
+                resultIds.add(result.toolCallId);
+            }
+            pending = undefined;
+            continue;
+        }
+        if (message.role === "tool") {
+            configError(`${path}[${index}] is a Tool Result message without preceding Tool Calls.`);
+        }
+        if (message.role !== "assistant") {
+            continue;
+        }
+        const calls = message.content.filter((block) => block.type === "tool_call");
+        if (calls.length === 0) {
+            continue;
+        }
+        const byId = new Map();
+        for (const call of calls) {
+            if (byId.has(call.toolCallId)) {
+                configError(`${path}[${index}] contains duplicate Tool Call IDs.`);
+            }
+            byId.set(call.toolCallId, call);
+        }
+        pending = { index, calls, byId };
+    }
+    if (pending !== undefined) {
+        configError(`${path}[${pending.index}] contains Tool Calls without matching Tool Results.`);
+    }
+}
+function assertToolMessage(message, path) {
+    if (!Array.isArray(message.content) || message.content.length === 0) {
+        configError(`${path}.content must be a non-empty array of tool_result blocks.`);
+    }
+    return {
+        role: "tool",
+        content: message.content.map((block, index) => assertToolResultBlock(block, `${path}.content[${index}]`)),
+    };
+}
+function assertAssistantBlock(value, path) {
+    const block = requirePlainObject(value, path);
+    if (block.type === "text") {
+        return assertTextBlock(block, path);
+    }
+    if (block.type === "tool_call") {
+        return assertToolCallBlock(block, path);
+    }
+    configError(`${path}.type must be "text" or "tool_call".`);
+}
+function assertTextBlock(value, path) {
+    const block = requirePlainObject(value, path);
+    assertOnlyKeys(block, TEXT_BLOCK_KEYS, path);
+    if (block.type !== "text") {
+        configError(`${path}.type must be "text".`);
+    }
+    if (typeof block.text !== "string") {
+        configError(`${path}.text must be a string.`);
+    }
+    return { type: "text", text: block.text };
+}
+function assertToolCallBlock(value, path) {
+    const block = requirePlainObject(value, path);
+    assertOnlyKeys(block, TOOL_CALL_KEYS, path);
+    if (block.type !== "tool_call") {
+        configError(`${path}.type must be "tool_call".`);
+    }
+    const toolCallId = requireNonEmptyString(block.toolCallId, `${path}.toolCallId`);
+    const toolName = requireNonEmptyString(block.toolName, `${path}.toolName`);
+    assertJsonValue(block.input, `${path}.input`, new WeakSet());
+    return {
+        type: "tool_call",
+        toolCallId,
+        toolName,
+        input: block.input,
+    };
+}
+function assertToolResultBlock(value, path) {
+    const block = requirePlainObject(value, path);
+    assertOnlyKeys(block, TOOL_RESULT_KEYS, path);
+    if (block.type !== "tool_result") {
+        configError(`${path}.type must be "tool_result".`);
+    }
+    const toolCallId = requireNonEmptyString(block.toolCallId, `${path}.toolCallId`);
+    const toolName = requireNonEmptyString(block.toolName, `${path}.toolName`);
+    if (typeof block.content !== "string") {
+        configError(`${path}.content must be a string.`);
+    }
+    const content = block.content;
+    if (!Object.hasOwn(block, "isError")) {
+        return {
+            type: "tool_result",
+            toolCallId,
+            toolName,
+            content,
+        };
+    }
+    if (typeof block.isError !== "boolean") {
+        configError(`${path}.isError must be a boolean when present.`);
+    }
+    return {
+        type: "tool_result",
+        toolCallId,
+        toolName,
+        content,
+        isError: block.isError,
+    };
+}
+function assertJsonValue(value, path, seen) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value))) {
+        return;
+    }
+    if (typeof value !== "object") {
+        configError(`${path} must contain only JSON-safe values.`);
+    }
+    if (seen.has(value)) {
+        configError(`${path} must not contain circular references.`);
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertJsonValue(item, `${path}[${index}]`, seen));
+    }
+    else {
+        const object = requirePlainObject(value, path);
+        for (const [key, item] of Object.entries(object)) {
+            assertJsonValue(item, `${path}.${key}`, seen);
+        }
+    }
+    seen.delete(value);
+}
+function requirePlainObject(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        configError(`${path} must be a plain object.`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        configError(`${path} must be a plain object.`);
+    }
+    return value;
+}
+function assertOnlyKeys(value, allowed, path) {
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string" || !allowed.has(key)) {
+            configError(`${path} contains unsupported field ${String(key)}.`);
+        }
+    }
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        configError(`${path} must be a non-empty string.`);
+    }
+    return value;
+}
+function configError(message) {
+    throw new AtomsAgentError("CONFIG_ERROR", message);
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

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

package/dist/structured-output.d.ts

@@ -0,0 +1,41 @@
+import type { JsonSchema, JsonValue, StructuredOutputRequest } from "@atoms-agent/llm";
+import { AtomsAgentError } from "@atoms-agent/llm";
+export type StructuredOutputConfig = {
+    /** Provider Wire Format 使用的稳定名称；省略时为 agent_output。 */
+    name?: string;
+    description?: string;
+    schema: JsonSchema;
+};
+export type StructuredOutputDiagnostic = {
+    instancePath: string;
+    schemaPath: string;
+    keyword: string;
+    message: string;
+};
+export type StructuredOutputResult = {
+    valid: true;
+    value: JsonValue;
+    diagnostics: StructuredOutputDiagnostic[];
+    repairAttempted: boolean;
+} | {
+    valid: false;
+    diagnostics: StructuredOutputDiagnostic[];
+    repairAttempted: boolean;
+};
+export type StructuredOutputFailure = Extract<StructuredOutputResult, {
+    valid: false;
+}>;
+export type StructuredOutputRuntime = {
+    request: StructuredOutputRequest;
+    promptInstruction: string;
+    validate(text: string, repairAttempted: boolean): StructuredOutputResult;
+    repairPrompt(diagnostics: readonly StructuredOutputDiagnostic[]): string;
+};
+export declare function assertStructuredOutputConfig(value: unknown, path?: string): asserts value is StructuredOutputConfig;
+export declare function createStructuredOutputRuntime(config: StructuredOutputConfig): StructuredOutputRuntime;
+export declare function createStructuredOutputFailure(diagnostics: readonly StructuredOutputDiagnostic[], repairAttempted: boolean): StructuredOutputFailure;
+export declare class StructuredOutputValidationError extends AtomsAgentError {
+    readonly result: StructuredOutputFailure;
+    constructor(result: StructuredOutputFailure);
+}
+//# sourceMappingURL=structured-output.d.ts.map

package/dist/structured-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../src/structured-output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAInD,MAAM,MAAM,sBAAsB,GAAG;IACnC,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAC9B;IACE,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,EAAE,0BAA0B,EAAE,CAAC;IAC1C,eAAe,EAAE,OAAO,CAAC;CAC1B,GACD;IACE,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,0BAA0B,EAAE,CAAC;IAC1C,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEN,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,EAAE;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAExF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,uBAAuB,CAAC;IACjC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,GAAG,sBAAsB,CAAC;IACzE,YAAY,CAAC,WAAW,EAAE,SAAS,0BAA0B,EAAE,GAAG,MAAM,CAAC;CAC1E,CAAC;AAKF,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,EACd,IAAI,SAAsB,GACzB,OAAO,CAAC,KAAK,IAAI,sBAAsB,CAiBzC;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,sBAAsB,GAC7B,uBAAuB,CA+DzB;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,SAAS,0BAA0B,EAAE,EAClD,eAAe,EAAE,OAAO,GACvB,uBAAuB,CAMzB;AAED,qBAAa,+BAAgC,SAAQ,eAAe;IAClE,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;gBAE7B,MAAM,EAAE,uBAAuB;CAQ5C"}