@blazingagents/sdk 0.1.0

package/dist/contracts/api.d.ts

@@ -0,0 +1,256 @@
+import { z } from "zod";
+export declare const clientRequestCorrelationSchema: z.ZodString;
+export declare const apiErrorIssueSchema: z.ZodObject<{
+    code: z.ZodString;
+    location: z.ZodEnum<{
+        body: "body";
+        header: "header";
+        path: "path";
+        query: "query";
+    }>;
+    message: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strict>;
+export type ApiErrorIssue = z.infer<typeof apiErrorIssueSchema>;
+/**
+ * `/v1` error envelope — see docs/adr/0003-ai-sdk-native-wire-protocol.md.
+ * Closed producer code set; `code` is what SDKs switch on and `message` is
+ * human-only. Resource-specific codes preserve stable product outcomes that
+ * callers need to distinguish.
+ */
+export declare const apiErrorCodeSchema: z.ZodEnum<{
+    admin_agent_managed: "admin_agent_managed";
+    agent_disabled: "agent_disabled";
+    agent_mcp_connection_not_found: "agent_mcp_connection_not_found";
+    agent_mcp_connections_invalid: "agent_mcp_connections_invalid";
+    agent_name_conflict: "agent_name_conflict";
+    agent_version_not_found: "agent_version_not_found";
+    api_key_limit_reached: "api_key_limit_reached";
+    artifact_session_cap_reached: "artifact_session_cap_reached";
+    checkout_evidence_mismatch: "checkout_evidence_mismatch";
+    internal: "internal";
+    invalid_cursor: "invalid_cursor";
+    invalid_request: "invalid_request";
+    mcp_connection_authentication_failed: "mcp_connection_authentication_failed";
+    mcp_connection_discovery_failed: "mcp_connection_discovery_failed";
+    mcp_connection_in_use: "mcp_connection_in_use";
+    mcp_connection_invalid: "mcp_connection_invalid";
+    mcp_connection_limit_reached: "mcp_connection_limit_reached";
+    mcp_connection_name_conflict: "mcp_connection_name_conflict";
+    mcp_connection_stale_credential_version: "mcp_connection_stale_credential_version";
+    mcp_connection_unreachable: "mcp_connection_unreachable";
+    message_not_found: "message_not_found";
+    model_discovery_unsupported: "model_discovery_unsupported";
+    model_not_found: "model_not_found";
+    model_validation_unavailable: "model_validation_unavailable";
+    not_found: "not_found";
+    prompt_limit_reached: "prompt_limit_reached";
+    prompt_name_conflict: "prompt_name_conflict";
+    prompt_variable_missing: "prompt_variable_missing";
+    prompt_variable_unknown: "prompt_variable_unknown";
+    provider_historical_use: "provider_historical_use";
+    provider_in_use: "provider_in_use";
+    provider_limit_reached: "provider_limit_reached";
+    provider_name_conflict: "provider_name_conflict";
+    provider_not_found: "provider_not_found";
+    provider_required: "provider_required";
+    quota_exceeded: "quota_exceeded";
+    rate_limited: "rate_limited";
+    service_unavailable: "service_unavailable";
+    session_busy: "session_busy";
+    session_version_mismatch: "session_version_mismatch";
+    skill_invalid_archive: "skill_invalid_archive";
+    skill_invalid_markdown: "skill_invalid_markdown";
+    skill_limit_reached: "skill_limit_reached";
+    skill_name_conflict: "skill_name_conflict";
+    skill_not_found: "skill_not_found";
+    skill_too_many_files: "skill_too_many_files";
+    skill_uncompressed_too_large: "skill_uncompressed_too_large";
+    subscription_required: "subscription_required";
+    task_active_run_exists: "task_active_run_exists";
+    tool_approval_continuation_not_found: "tool_approval_continuation_not_found";
+    tool_approval_decision_conflict: "tool_approval_decision_conflict";
+    unauthorized: "unauthorized";
+    usage_credit_required: "usage_credit_required";
+    validation_failed: "validation_failed";
+    workspace_busy: "workspace_busy";
+    workspace_in_use: "workspace_in_use";
+    workspace_not_found: "workspace_not_found";
+}>;
+export declare const apiErrorSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        admin_agent_managed: "admin_agent_managed";
+        agent_disabled: "agent_disabled";
+        agent_mcp_connection_not_found: "agent_mcp_connection_not_found";
+        agent_mcp_connections_invalid: "agent_mcp_connections_invalid";
+        agent_name_conflict: "agent_name_conflict";
+        agent_version_not_found: "agent_version_not_found";
+        api_key_limit_reached: "api_key_limit_reached";
+        artifact_session_cap_reached: "artifact_session_cap_reached";
+        checkout_evidence_mismatch: "checkout_evidence_mismatch";
+        internal: "internal";
+        invalid_cursor: "invalid_cursor";
+        invalid_request: "invalid_request";
+        mcp_connection_authentication_failed: "mcp_connection_authentication_failed";
+        mcp_connection_discovery_failed: "mcp_connection_discovery_failed";
+        mcp_connection_in_use: "mcp_connection_in_use";
+        mcp_connection_invalid: "mcp_connection_invalid";
+        mcp_connection_limit_reached: "mcp_connection_limit_reached";
+        mcp_connection_name_conflict: "mcp_connection_name_conflict";
+        mcp_connection_stale_credential_version: "mcp_connection_stale_credential_version";
+        mcp_connection_unreachable: "mcp_connection_unreachable";
+        message_not_found: "message_not_found";
+        model_discovery_unsupported: "model_discovery_unsupported";
+        model_not_found: "model_not_found";
+        model_validation_unavailable: "model_validation_unavailable";
+        not_found: "not_found";
+        prompt_limit_reached: "prompt_limit_reached";
+        prompt_name_conflict: "prompt_name_conflict";
+        prompt_variable_missing: "prompt_variable_missing";
+        prompt_variable_unknown: "prompt_variable_unknown";
+        provider_historical_use: "provider_historical_use";
+        provider_in_use: "provider_in_use";
+        provider_limit_reached: "provider_limit_reached";
+        provider_name_conflict: "provider_name_conflict";
+        provider_not_found: "provider_not_found";
+        provider_required: "provider_required";
+        quota_exceeded: "quota_exceeded";
+        rate_limited: "rate_limited";
+        service_unavailable: "service_unavailable";
+        session_busy: "session_busy";
+        session_version_mismatch: "session_version_mismatch";
+        skill_invalid_archive: "skill_invalid_archive";
+        skill_invalid_markdown: "skill_invalid_markdown";
+        skill_limit_reached: "skill_limit_reached";
+        skill_name_conflict: "skill_name_conflict";
+        skill_not_found: "skill_not_found";
+        skill_too_many_files: "skill_too_many_files";
+        skill_uncompressed_too_large: "skill_uncompressed_too_large";
+        subscription_required: "subscription_required";
+        task_active_run_exists: "task_active_run_exists";
+        tool_approval_continuation_not_found: "tool_approval_continuation_not_found";
+        tool_approval_decision_conflict: "tool_approval_decision_conflict";
+        unauthorized: "unauthorized";
+        usage_credit_required: "usage_credit_required";
+        validation_failed: "validation_failed";
+        workspace_busy: "workspace_busy";
+        workspace_in_use: "workspace_in_use";
+        workspace_not_found: "workspace_not_found";
+    }>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    message: z.ZodString;
+    param: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const apiErrorResponseSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodEnum<{
+            admin_agent_managed: "admin_agent_managed";
+            agent_disabled: "agent_disabled";
+            agent_mcp_connection_not_found: "agent_mcp_connection_not_found";
+            agent_mcp_connections_invalid: "agent_mcp_connections_invalid";
+            agent_name_conflict: "agent_name_conflict";
+            agent_version_not_found: "agent_version_not_found";
+            api_key_limit_reached: "api_key_limit_reached";
+            artifact_session_cap_reached: "artifact_session_cap_reached";
+            checkout_evidence_mismatch: "checkout_evidence_mismatch";
+            internal: "internal";
+            invalid_cursor: "invalid_cursor";
+            invalid_request: "invalid_request";
+            mcp_connection_authentication_failed: "mcp_connection_authentication_failed";
+            mcp_connection_discovery_failed: "mcp_connection_discovery_failed";
+            mcp_connection_in_use: "mcp_connection_in_use";
+            mcp_connection_invalid: "mcp_connection_invalid";
+            mcp_connection_limit_reached: "mcp_connection_limit_reached";
+            mcp_connection_name_conflict: "mcp_connection_name_conflict";
+            mcp_connection_stale_credential_version: "mcp_connection_stale_credential_version";
+            mcp_connection_unreachable: "mcp_connection_unreachable";
+            message_not_found: "message_not_found";
+            model_discovery_unsupported: "model_discovery_unsupported";
+            model_not_found: "model_not_found";
+            model_validation_unavailable: "model_validation_unavailable";
+            not_found: "not_found";
+            prompt_limit_reached: "prompt_limit_reached";
+            prompt_name_conflict: "prompt_name_conflict";
+            prompt_variable_missing: "prompt_variable_missing";
+            prompt_variable_unknown: "prompt_variable_unknown";
+            provider_historical_use: "provider_historical_use";
+            provider_in_use: "provider_in_use";
+            provider_limit_reached: "provider_limit_reached";
+            provider_name_conflict: "provider_name_conflict";
+            provider_not_found: "provider_not_found";
+            provider_required: "provider_required";
+            quota_exceeded: "quota_exceeded";
+            rate_limited: "rate_limited";
+            service_unavailable: "service_unavailable";
+            session_busy: "session_busy";
+            session_version_mismatch: "session_version_mismatch";
+            skill_invalid_archive: "skill_invalid_archive";
+            skill_invalid_markdown: "skill_invalid_markdown";
+            skill_limit_reached: "skill_limit_reached";
+            skill_name_conflict: "skill_name_conflict";
+            skill_not_found: "skill_not_found";
+            skill_too_many_files: "skill_too_many_files";
+            skill_uncompressed_too_large: "skill_uncompressed_too_large";
+            subscription_required: "subscription_required";
+            task_active_run_exists: "task_active_run_exists";
+            tool_approval_continuation_not_found: "tool_approval_continuation_not_found";
+            tool_approval_decision_conflict: "tool_approval_decision_conflict";
+            unauthorized: "unauthorized";
+            usage_credit_required: "usage_credit_required";
+            validation_failed: "validation_failed";
+            workspace_busy: "workspace_busy";
+            workspace_in_use: "workspace_in_use";
+            workspace_not_found: "workspace_not_found";
+        }>;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        message: z.ZodString;
+        param: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+declare const receivedApiErrorCodeSchema: z.ZodString;
+export declare const receivedApiErrorResponseSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        message: z.ZodString;
+        param: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type ApiErrorCode = z.infer<typeof apiErrorCodeSchema>;
+export type ApiError = z.infer<typeof apiErrorSchema>;
+export type ApiErrorResponse = z.infer<typeof apiErrorResponseSchema>;
+export type ReceivedApiErrorCode = z.infer<typeof receivedApiErrorCodeSchema>;
+export interface ApiErrorOptions {
+    details?: Record<string, unknown>;
+    param?: string;
+}
+export declare function apiError(code: ApiErrorCode, message: string, options?: ApiErrorOptions): ApiErrorResponse;
+/**
+ * Cursor pagination — `{ data, nextCursor }` on unbounded list surfaces,
+ * including sessions, transcripts, artifacts, and memories.
+ * `nextCursor` is opaque (base64 of the keyset); `null` means no more pages.
+ */
+export declare function paginatedResponse<T>(data: T[], nextCursor: string | null): {
+    data: T[];
+    nextCursor: string | null;
+};
+export declare const cursorSchema: z.ZodString;
+export declare function paginatedResponseSchema<T extends z.ZodTypeAny>(itemSchema: T): z.ZodObject<{
+    data: z.ZodArray<T>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Opaque keyset cursor helpers. Cursors are base64url-encoded JSON of the
+ * keyset tuple the endpoint paginates by — never a raw value, never a row
+ * id alone. The repo-wide pattern: keyset-backed `{ data, nextCursor }`,
+ * mapping 1:1 onto `useInfiniteQuery`. Decode failures surface as
+ * `INVALID_CURSOR` (the caller wraps the throw).
+ */
+export declare class CursorDecodeError extends Error {
+    readonly errorCode = "INVALID_CURSOR";
+    readonly statusCode = 400;
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function encodeCursor(payload: Record<string, unknown>): string;
+export declare function decodeCursor(cursor: string): Record<string, unknown>;
+export {};

package/dist/contracts/api.js

@@ -0,0 +1,189 @@
+import { z } from "zod";
+export const clientRequestCorrelationSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9._:-]{1,128}$/);
+export const apiErrorIssueSchema = z
+    .object({
+    code: z.string().min(1),
+    location: z.enum(["body", "path", "query", "header"]),
+    message: z.string().min(1),
+    path: z.string(),
+})
+    .strict();
+/**
+ * `/v1` error envelope — see docs/adr/0003-ai-sdk-native-wire-protocol.md.
+ * Closed producer code set; `code` is what SDKs switch on and `message` is
+ * human-only. Resource-specific codes preserve stable product outcomes that
+ * callers need to distinguish.
+ */
+export const apiErrorCodeSchema = z.enum([
+    "invalid_request",
+    "validation_failed",
+    "unauthorized",
+    "not_found",
+    "quota_exceeded",
+    "subscription_required",
+    "usage_credit_required",
+    "rate_limited",
+    "internal",
+    "service_unavailable",
+    "checkout_evidence_mismatch",
+    "agent_disabled",
+    "admin_agent_managed",
+    "agent_version_not_found",
+    "agent_mcp_connection_not_found",
+    "agent_mcp_connections_invalid",
+    "agent_name_conflict",
+    "provider_required",
+    "api_key_limit_reached",
+    "artifact_session_cap_reached",
+    "invalid_cursor",
+    "message_not_found",
+    "prompt_limit_reached",
+    "prompt_name_conflict",
+    "prompt_variable_missing",
+    "prompt_variable_unknown",
+    "provider_in_use",
+    "provider_historical_use",
+    "provider_limit_reached",
+    "provider_name_conflict",
+    "provider_not_found",
+    "model_discovery_unsupported",
+    "model_not_found",
+    "model_validation_unavailable",
+    "mcp_connection_limit_reached",
+    "mcp_connection_name_conflict",
+    "mcp_connection_stale_credential_version",
+    "mcp_connection_invalid",
+    "mcp_connection_authentication_failed",
+    "mcp_connection_in_use",
+    "mcp_connection_unreachable",
+    "mcp_connection_discovery_failed",
+    "workspace_not_found",
+    "workspace_in_use",
+    "workspace_busy",
+    "session_busy",
+    "session_version_mismatch",
+    "tool_approval_continuation_not_found",
+    "tool_approval_decision_conflict",
+    "skill_invalid_archive",
+    "skill_invalid_markdown",
+    "skill_limit_reached",
+    "skill_name_conflict",
+    "skill_not_found",
+    "skill_too_many_files",
+    "skill_uncompressed_too_large",
+    "task_active_run_exists",
+]);
+export const apiErrorSchema = z
+    .object({
+    code: apiErrorCodeSchema,
+    details: z
+        .record(z.string(), z.unknown())
+        .refine((value) => Object.keys(value).length > 0)
+        .optional(),
+    message: z.string().min(1),
+    param: z.string().optional(),
+})
+    .strict();
+export const apiErrorResponseSchema = z
+    .object({
+    error: apiErrorSchema,
+})
+    .strict();
+const receivedApiErrorCodeSchema = z.string().min(1);
+const receivedApiErrorSchema = z
+    .object({
+    code: receivedApiErrorCodeSchema,
+    details: z.record(z.string(), z.unknown()).optional(),
+    message: z.string().min(1),
+    param: z.string().optional(),
+})
+    .passthrough();
+export const receivedApiErrorResponseSchema = z
+    .object({
+    error: receivedApiErrorSchema,
+})
+    .passthrough();
+export function apiError(code, message, options = {}) {
+    return {
+        error: {
+            code,
+            ...(options.details && Object.keys(options.details).length > 0
+                ? { details: options.details }
+                : {}),
+            message,
+            ...(options.param === undefined ? {} : { param: options.param }),
+        },
+    };
+}
+/**
+ * Cursor pagination — `{ data, nextCursor }` on unbounded list surfaces,
+ * including sessions, transcripts, artifacts, and memories.
+ * `nextCursor` is opaque (base64 of the keyset); `null` means no more pages.
+ */
+export function paginatedResponse(data, nextCursor) {
+    return { data, nextCursor };
+}
+export const cursorSchema = z.string().trim().min(1);
+export function paginatedResponseSchema(itemSchema) {
+    return z
+        .object({
+        data: z.array(itemSchema),
+        nextCursor: z.string().nullable(),
+    })
+        .strict();
+}
+/**
+ * Opaque keyset cursor helpers. Cursors are base64url-encoded JSON of the
+ * keyset tuple the endpoint paginates by — never a raw value, never a row
+ * id alone. The repo-wide pattern: keyset-backed `{ data, nextCursor }`,
+ * mapping 1:1 onto `useInfiniteQuery`. Decode failures surface as
+ * `INVALID_CURSOR` (the caller wraps the throw).
+ */
+export class CursorDecodeError extends Error {
+    errorCode = "INVALID_CURSOR";
+    statusCode = 400;
+    constructor(message, options) {
+        super(message, options);
+        this.name = "CursorDecodeError";
+    }
+}
+const BASE64_PLUS = /\+/g;
+const BASE64_SLASH = /\//g;
+const BASE64_PADDING = /[=]+$/;
+const BASE64_DASH = /-/g;
+const BASE64_UNDERSCORE = /_/g;
+export function encodeCursor(payload) {
+    const json = JSON.stringify(payload);
+    const bytes = new TextEncoder().encode(json);
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary)
+        .replace(BASE64_PLUS, "-")
+        .replace(BASE64_SLASH, "_")
+        .replace(BASE64_PADDING, "");
+}
+export function decodeCursor(cursor) {
+    let json;
+    try {
+        const binary = atob(cursor.replace(BASE64_DASH, "+").replace(BASE64_UNDERSCORE, "/"));
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i += 1) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        json = new TextDecoder().decode(bytes);
+        const parsed = JSON.parse(json);
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            Array.isArray(parsed)) {
+            throw new Error("cursor payload is not an object");
+        }
+        return parsed;
+    }
+    catch (cause) {
+        throw new CursorDecodeError("Invalid cursor", { cause });
+    }
+}

package/dist/contracts/entities/agent-tools.d.ts

@@ -0,0 +1,26 @@
+/** Tool groups an Agent can attach. File operations use its durable Workspace. */
+export declare const agentToolGroupIds: readonly ["workspace", "write_todos", "memory"];
+export type AgentToolGroupId = (typeof agentToolGroupIds)[number];
+export interface AgentToolGroup {
+    description: string;
+    id: AgentToolGroupId;
+    name: string;
+    tools: readonly string[];
+}
+export declare const AGENT_TOOL_CATALOG: readonly [{
+    readonly id: "workspace";
+    readonly name: "File operations";
+    readonly description: "Read, write, edit, search, and run shell commands in the attached durable Workspace.";
+    readonly tools: readonly ["read", "write", "edit", "grep", "glob", "bash", "publish_artifacts"];
+}, {
+    readonly id: "write_todos";
+    readonly name: "Task planning";
+    readonly description: "Create and manage a structured todo list to plan and track multi-step work.";
+    readonly tools: readonly ["write_todos"];
+}, {
+    readonly id: "memory";
+    readonly name: "Memory";
+    readonly description: "Save, recall, search, update, and delete durable notes owned by this Agent.";
+    readonly tools: readonly ["save_memory", "get_memory", "search_memories", "update_memory", "delete_memory"];
+}];
+export declare function expandToolGroups(ids: Iterable<string>): Set<string>;

package/dist/contracts/entities/agent-tools.js

@@ -0,0 +1,52 @@
+/** Tool groups an Agent can attach. File operations use its durable Workspace. */
+export const agentToolGroupIds = [
+    "workspace",
+    "write_todos",
+    "memory",
+];
+export const AGENT_TOOL_CATALOG = [
+    {
+        id: "workspace",
+        name: "File operations",
+        description: "Read, write, edit, search, and run shell commands in the attached durable Workspace.",
+        tools: [
+            "read",
+            "write",
+            "edit",
+            "grep",
+            "glob",
+            "bash",
+            "publish_artifacts",
+        ],
+    },
+    {
+        id: "write_todos",
+        name: "Task planning",
+        description: "Create and manage a structured todo list to plan and track multi-step work.",
+        tools: ["write_todos"],
+    },
+    {
+        id: "memory",
+        name: "Memory",
+        description: "Save, recall, search, update, and delete durable notes owned by this Agent.",
+        tools: [
+            "save_memory",
+            "get_memory",
+            "search_memories",
+            "update_memory",
+            "delete_memory",
+        ],
+    },
+];
+export function expandToolGroups(ids) {
+    const result = new Set();
+    for (const id of ids) {
+        const group = AGENT_TOOL_CATALOG.find((candidate) => candidate.id === id);
+        if (group) {
+            for (const tool of group.tools) {
+                result.add(tool);
+            }
+        }
+    }
+    return result;
+}