@codespar/sdk 0.9.0 → 0.10.1

package/dist/__tests__/tool-result-codes.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tool-result code guard tests.
+ *
+ * Asserts:
+ *   - Positive + negative paths per guard.
+ *   - Sibling-field-missing fixtures — a well-formed `code` with
+ *     missing required siblings (e.g. `rule_id` for policy_denied)
+ *     returns false. The guard does not narrow on the discriminant
+ *     alone.
+ *   - Unknown-code defense-in-depth — an unknown `code` value never
+ *     narrows positive on any guard.
+ *   - assertExhaustiveToolResult compiles when every variant is
+ *     handled (the test below is the compile-time witness).
+ *   - output.code vs error_code disagreement — guards key on the
+ *     `code` field on the payload, ignoring sibling discrepancies.
+ */
+export {};
+//# sourceMappingURL=tool-result-codes.test.d.ts.map

package/dist/__tests__/tool-result-codes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result-codes.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/tool-result-codes.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/__tests__/tool-result-codes.test.js

@@ -0,0 +1,164 @@
+/**
+ * Tool-result code guard tests.
+ *
+ * Asserts:
+ *   - Positive + negative paths per guard.
+ *   - Sibling-field-missing fixtures — a well-formed `code` with
+ *     missing required siblings (e.g. `rule_id` for policy_denied)
+ *     returns false. The guard does not narrow on the discriminant
+ *     alone.
+ *   - Unknown-code defense-in-depth — an unknown `code` value never
+ *     narrows positive on any guard.
+ *   - assertExhaustiveToolResult compiles when every variant is
+ *     handled (the test below is the compile-time witness).
+ *   - output.code vs error_code disagreement — guards key on the
+ *     `code` field on the payload, ignoring sibling discrepancies.
+ */
+import { describe, it, expect } from "vitest";
+import { TOOL_RESULT_CODES, ToolResultCode, assertExhaustiveToolResult, isApprovalRequired, isMocksEngineError, isMocksExhausted, isPolicyDenied, isToolNotMocked, } from "../tool-result-codes.js";
+describe("TOOL_RESULT_CODES set", () => {
+    it("includes the five canonical codes", () => {
+        expect(TOOL_RESULT_CODES).toContain("policy_denied");
+        expect(TOOL_RESULT_CODES).toContain("approval_required");
+        expect(TOOL_RESULT_CODES).toContain("mocks_exhausted");
+        expect(TOOL_RESULT_CODES).toContain("mocks_engine_error");
+        expect(TOOL_RESULT_CODES).toContain("tool_not_mocked");
+    });
+});
+describe("isPolicyDenied", () => {
+    it("returns true for a well-formed policy_denied output", () => {
+        const out = {
+            code: ToolResultCode.PolicyDenied,
+            rule_id: "spend_cap",
+            message: "exceeds tenant cap",
+        };
+        expect(isPolicyDenied(out)).toBe(true);
+    });
+    it("returns false when rule_id is missing", () => {
+        const out = {
+            code: ToolResultCode.PolicyDenied,
+            message: "missing rule",
+        };
+        expect(isPolicyDenied(out)).toBe(false);
+    });
+    it("returns false when message is missing", () => {
+        const out = {
+            code: ToolResultCode.PolicyDenied,
+            rule_id: "spend_cap",
+        };
+        expect(isPolicyDenied(out)).toBe(false);
+    });
+    it("returns false on a foreign discriminant", () => {
+        const out = {
+            code: "approval_required",
+            rule_id: "x",
+            message: "y",
+        };
+        expect(isPolicyDenied(out)).toBe(false);
+    });
+    it("returns false on an unknown code (defense in depth)", () => {
+        const out = {
+            code: "totally_made_up",
+            rule_id: "x",
+            message: "y",
+        };
+        expect(isPolicyDenied(out)).toBe(false);
+    });
+    it("returns false on null/undefined/non-object", () => {
+        expect(isPolicyDenied(null)).toBe(false);
+        expect(isPolicyDenied(undefined)).toBe(false);
+        expect(isPolicyDenied("policy_denied")).toBe(false);
+    });
+});
+describe("isApprovalRequired", () => {
+    it("returns true for a well-formed approval_required output", () => {
+        const out = {
+            code: ToolResultCode.ApprovalRequired,
+            approval_id: "apr_abc",
+            expires_at: "2026-12-01T00:00:00Z",
+            message: "approve the transfer",
+        };
+        expect(isApprovalRequired(out)).toBe(true);
+    });
+    it("returns false when approval_id is missing", () => {
+        const out = {
+            code: ToolResultCode.ApprovalRequired,
+            expires_at: "2026-12-01T00:00:00Z",
+            message: "x",
+        };
+        expect(isApprovalRequired(out)).toBe(false);
+    });
+    it("returns false when expires_at is missing", () => {
+        const out = {
+            code: ToolResultCode.ApprovalRequired,
+            approval_id: "apr_abc",
+            message: "x",
+        };
+        expect(isApprovalRequired(out)).toBe(false);
+    });
+    it("returns false when message is missing", () => {
+        const out = {
+            code: ToolResultCode.ApprovalRequired,
+            approval_id: "apr_abc",
+            expires_at: "x",
+        };
+        expect(isApprovalRequired(out)).toBe(false);
+    });
+});
+describe("isMocksExhausted and isMocksEngineError", () => {
+    it("isMocksExhausted: positive + sibling-missing", () => {
+        expect(isMocksExhausted({ code: ToolResultCode.MocksExhausted, message: "drained" })).toBe(true);
+        expect(isMocksExhausted({ code: ToolResultCode.MocksExhausted })).toBe(false);
+    });
+    it("isMocksEngineError: positive + sibling-missing", () => {
+        expect(isMocksEngineError({
+            code: ToolResultCode.MocksEngineError,
+            message: "consume failed",
+        })).toBe(true);
+        expect(isMocksEngineError({ code: ToolResultCode.MocksEngineError })).toBe(false);
+    });
+});
+describe("isToolNotMocked", () => {
+    it("returns true with tool_name + message", () => {
+        expect(isToolNotMocked({
+            code: ToolResultCode.ToolNotMocked,
+            tool_name: "asaas/create_payment",
+            message: "not in mocks map",
+        })).toBe(true);
+    });
+    it("returns false when tool_name is missing", () => {
+        expect(isToolNotMocked({ code: ToolResultCode.ToolNotMocked, message: "x" })).toBe(false);
+    });
+});
+describe("assertExhaustiveToolResult", () => {
+    it("compiles when every code variant is handled", () => {
+        // The test BODY here is the compile-time witness; runtime asserts
+        // the unreachable-default branch throws on a hostile cast.
+        function describe(value) {
+            switch (value.code) {
+                case ToolResultCode.PolicyDenied:
+                    return "denied";
+                case ToolResultCode.ApprovalRequired:
+                    return "approval";
+                case ToolResultCode.MocksExhausted:
+                    return "exhausted";
+                case ToolResultCode.MocksEngineError:
+                    return "engine";
+                case ToolResultCode.ToolNotMocked:
+                    return "not_mocked";
+                default:
+                    // If a 6th code lands without this branch being updated, TS
+                    // fails: assertExhaustiveToolResult(value) would error at
+                    // compile time on a non-never argument.
+                    return assertExhaustiveToolResult(value);
+            }
+        }
+        expect(describe({
+            code: ToolResultCode.PolicyDenied,
+            rule_id: "x",
+            message: "y",
+        })).toBe("denied");
+        expect(() => assertExhaustiveToolResult({ code: "rogue" })).toThrow(/tool-result-codes/i);
+    });
+});
+//# sourceMappingURL=tool-result-codes.test.js.map

package/dist/__tests__/tool-result-codes.test.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Structured exception for every transport-failure path through the
+ * SDK. Replaces the old `throw new Error("send failed: 500 ...")`
+ * shape, so callers can branch on `e.code` rather than parsing
+ * `e.message` strings.
+ *
+ * The reserved code namespace covers the hosted-test-mode wire
+ * contract (tool-result codes + create-time envelope codes —
+ * see the README's "Reserved error codes" section). Customers
+ * extending CodesparApiError should prefix their own codes (e.g.
+ * `"myapp.policy_denied"`) to avoid collision with reserved values.
+ *
+ * `status: 0` is reserved for network errors that never reached the
+ * backend; the underlying `cause` carries the original `TypeError`
+ * or `DOMException` that `fetch` rejected with.
+ */
+export interface CodesparApiErrorOptions {
+    status: number;
+    code?: string;
+    body?: unknown;
+    cause?: unknown;
+}
+export declare class CodesparApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly body?: unknown;
+    constructor(message: string, options: CodesparApiErrorOptions);
+}
+/**
+ * Build the canonical error message + extract the structured code +
+ * preserve the parsed body. Centralised so every transport call site
+ * surfaces the same shape — a customer parsing `e.message` is
+ * already on the deprecated path; new code branches on `e.code`.
+ */
+export declare function throwFromResponse(response: Response, what: string): Promise<never>;
+/**
+ * Convert a `fetch` rejection (network error, abort, DNS, TLS, etc.)
+ * into a CodesparApiError with `status: 0`. Preserves the underlying
+ * error as `cause` so callers debugging a transport failure can dig
+ * into the original `TypeError`.
+ */
+export declare function networkErrorToApiError(cause: unknown, what: string): CodesparApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB;CAY9D;AAkCD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,KAAK,CAAC,CAehB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAMrF"}

package/dist/errors.js

@@ -0,0 +1,77 @@
+export class CodesparApiError extends Error {
+    status;
+    code;
+    body;
+    constructor(message, options) {
+        // ES2022 `cause` shape — supported by Node 20 + modern browsers.
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        // Restore the prototype chain — without this, `instanceof
+        // CodesparApiError` returns false across some transpilers and
+        // realms (the classic ES5-target Error subclass trap).
+        Object.setPrototypeOf(this, CodesparApiError.prototype);
+        this.name = "CodesparApiError";
+        this.status = options.status;
+        this.code = options.code;
+        this.body = options.body;
+    }
+}
+function parseErrorPayload(raw) {
+    if (!raw)
+        return { body: undefined, parsed: {} };
+    try {
+        const body = JSON.parse(raw);
+        if (body && typeof body === "object" && !Array.isArray(body)) {
+            const obj = body;
+            const code = typeof obj.code === "string" ? obj.code : undefined;
+            // Legacy fallback: pre-PRD envelopes used `error` as the
+            // discriminant. `code` takes precedence; `error` honored only
+            // when `code` is missing.
+            const fallbackCode = code ?? (typeof obj.error === "string" ? obj.error : undefined);
+            const message = typeof obj.message === "string" ? obj.message : undefined;
+            return {
+                body,
+                parsed: { code: fallbackCode, message },
+            };
+        }
+        return { body, parsed: {} };
+    }
+    catch {
+        return { body: raw, parsed: {} };
+    }
+}
+/**
+ * Build the canonical error message + extract the structured code +
+ * preserve the parsed body. Centralised so every transport call site
+ * surfaces the same shape — a customer parsing `e.message` is
+ * already on the deprecated path; new code branches on `e.code`.
+ */
+export async function throwFromResponse(response, what) {
+    const raw = await response.text();
+    const { body, parsed } = parseErrorPayload(raw);
+    const suffix = parsed.message
+        ? ` — ${parsed.message}`
+        : parsed.code
+            ? ` — ${parsed.code}`
+            : raw
+                ? ` ${raw}`
+                : "";
+    throw new CodesparApiError(`${what} failed: ${response.status}${suffix}`, {
+        status: response.status,
+        code: parsed.code,
+        body,
+    });
+}
+/**
+ * Convert a `fetch` rejection (network error, abort, DNS, TLS, etc.)
+ * into a CodesparApiError with `status: 0`. Preserves the underlying
+ * error as `cause` so callers debugging a transport failure can dig
+ * into the original `TypeError`.
+ */
+export function networkErrorToApiError(cause, what) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return new CodesparApiError(`${what} network error: ${message}`, {
+        status: 0,
+        cause,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAuBA,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,MAAM,CAAS;IACf,IAAI,CAAU;IACd,IAAI,CAAW;IAExB,YAAY,OAAe,EAAE,OAAgC;QAC3D,iEAAiE;QACjE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACnF,0DAA0D;QAC1D,8DAA8D;QAC9D,uDAAuD;QACvD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF;AAOD,SAAS,iBAAiB,CAAC,GAAW;IAIpC,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;QACxC,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7D,MAAM,GAAG,GAAG,IAA+B,CAAC;YAC5C,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YACjE,yDAAyD;YACzD,8DAA8D;YAC9D,0BAA0B;YAC1B,MAAM,YAAY,GAChB,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,GAAG,CAAC,KAAgB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YAC9E,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1E,OAAO;gBACL,IAAI;gBACJ,MAAM,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE;aACxC,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACnC,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAkB,EAClB,IAAY;IAEZ,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAClC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO;QAC3B,CAAC,CAAC,MAAM,MAAM,CAAC,OAAO,EAAE;QACxB,CAAC,CAAC,MAAM,CAAC,IAAI;YACX,CAAC,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE;YACrB,CAAC,CAAC,GAAG;gBACH,CAAC,CAAC,IAAI,GAAG,EAAE;gBACX,CAAC,CAAC,EAAE,CAAC;IACX,MAAM,IAAI,gBAAgB,CAAC,GAAG,IAAI,YAAY,QAAQ,CAAC,MAAM,GAAG,MAAM,EAAE,EAAE;QACxE,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI;KACL,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc,EAAE,IAAY;IACjE,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,IAAI,gBAAgB,CAAC,GAAG,IAAI,mBAAmB,OAAO,EAAE,EAAE;QAC/D,MAAM,EAAE,CAAC;QACT,KAAK;KACN,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -28,6 +28,10 @@ export type { CodeSparConfig, SessionConfig, Tool, LoopConfig, LoopStep, LoopRes
 export { SessionConfigSchema } from "./types.js";
 export { loop } from "./loop.js";
 export { tools, findTools } from "./tools.js";
+export { CodesparApiError } from "./errors.js";
+export type { CodesparApiErrorOptions } from "./errors.js";
+export { TOOL_RESULT_CODES, ToolResultCode, assertExhaustiveToolResult, isApprovalRequired, isMocksEngineError, isMocksExhausted, isPolicyDenied, isToolNotMocked, } from "./tool-result-codes.js";
+export type { ApprovalRequiredOutput, ApprovalRequiredToolCall, MocksEngineErrorOutput, MocksEngineErrorToolCall, MocksExhaustedOutput, MocksExhaustedToolCall, PolicyDeniedOutput, PolicyDeniedToolCall, ToolNotMockedOutput, ToolNotMockedToolCall, ToolResultOutcome, } from "./tool-result-codes.js";
 import type { CodeSparConfig, SessionConfig } from "./types.js";
 import type { Session } from "@codespar/types";
 export declare class CodeSpar {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,cAAc,iBAAiB,CAAC;AAEhC,YAAY,EACV,cAAc,EACd,aAAa,EACb,IAAI,EACJ,UAAU,EACV,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;gBAEtC,MAAM,GAAE,cAAmB;IAevC;;;;;OAKG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;CAS3E;AAED,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,cAAc,iBAAiB,CAAC;AAEhC,YAAY,EACV,cAAc,EACd,aAAa,EACb,IAAI,EACJ,UAAU,EACV,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;gBAEtC,MAAM,GAAE,cAAmB;IAevC;;;;;OAKG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;CAS3E;AAED,eAAe,QAAQ,CAAC"}

package/dist/index.js

@@ -27,6 +27,8 @@ export * from "@codespar/types";
 export { SessionConfigSchema } from "./types.js";
 export { loop } from "./loop.js";
 export { tools, findTools } from "./tools.js";
+export { CodesparApiError } from "./errors.js";
+export { TOOL_RESULT_CODES, ToolResultCode, assertExhaustiveToolResult, isApprovalRequired, isMocksEngineError, isMocksExhausted, isPolicyDenied, isToolNotMocked, } from "./tool-result-codes.js";
 import { SessionConfigSchema } from "./types.js";
 import { createSession } from "./session.js";
 const DEFAULT_BASE_URL = "https://api.codespar.dev";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,cAAc,iBAAiB,CAAC;AAWhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAEpD,MAAM,OAAO,QAAQ;IACF,MAAM,CAA2B;IAElD,YAAY,SAAyB,EAAE;QACrC,IAAI,CAAC,MAAM,GAAG;YACZ,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE;YAC3D,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,gBAAgB;YAC5E,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE;SAClC,CAAC;QAEF,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,yFAAyF;gBACvF,sEAAsE,CACzE,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,SAAwB,EAAE;QACrD,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,SAAS,CAAC;QACzE,OAAO,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE;YACnC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC1B,SAAS,EAAE,SAAS,IAAI,SAAS;SAClC,CAAC,CAAC;IACL,CAAC;CACF;AAED,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,cAAc,iBAAiB,CAAC;AAWhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAiBhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAEpD,MAAM,OAAO,QAAQ;IACF,MAAM,CAA2B;IAElD,YAAY,SAAyB,EAAE;QACrC,IAAI,CAAC,MAAM,GAAG;YACZ,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE;YAC3D,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,gBAAgB;YAC5E,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE;SAClC,CAAC;QAEF,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,yFAAyF;gBACvF,sEAAsE,CACzE,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,SAAwB,EAAE;QACrD,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,SAAS,CAAC;QACzE,OAAO,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE;YACnC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC1B,SAAS,EAAE,SAAS,IAAI,SAAS;SAClC,CAAC,CAAC;IACL,CAAC;CACF;AAED,eAAe,QAAQ,CAAC"}

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAQ,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EACV,OAAO,EAsBR,MAAM,iBAAiB,CAAC;AAEzB,UAAU,WAAW;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoBD,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,OAAO,CAAC,CAkWlB"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAQ,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EACV,OAAO,EA4BR,MAAM,iBAAiB,CAAC;AAEzB,UAAU,WAAW;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoCD,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,OAAO,CAAC,CAodlB"}