@octavus/server-sdk 2.18.0 → 2.20.0

package/dist/index.cjs

@@ -0,0 +1,1109 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentSession: () => AgentSession,
+  AgentSessionsApi: () => AgentSessionsApi,
+  AgentsApi: () => AgentsApi,
+  ApiError: () => ApiError,
+  AppError: () => import_core5.AppError,
+  ConflictError: () => import_core5.ConflictError,
+  FilesApi: () => FilesApi,
+  ForbiddenError: () => import_core5.ForbiddenError,
+  MAIN_THREAD: () => import_core5.MAIN_THREAD,
+  NotFoundError: () => import_core5.NotFoundError,
+  OCTAVUS_SKILL_TOOLS: () => import_core5.OCTAVUS_SKILL_TOOLS,
+  OctavusClient: () => OctavusClient,
+  OctavusError: () => import_core5.OctavusError,
+  Resource: () => Resource,
+  ValidationError: () => import_core5.ValidationError,
+  WorkerError: () => WorkerError,
+  WorkersApi: () => WorkersApi,
+  createApiErrorEvent: () => import_core5.createApiErrorEvent,
+  createErrorEvent: () => import_core5.createErrorEvent,
+  createInternalErrorEvent: () => import_core5.createInternalErrorEvent,
+  errorToStreamEvent: () => import_core5.errorToStreamEvent,
+  generateId: () => import_core5.generateId,
+  getSkillSlugFromToolCall: () => import_core5.getSkillSlugFromToolCall,
+  isAbortError: () => import_core5.isAbortError,
+  isAuthenticationError: () => import_core5.isAuthenticationError,
+  isFileReference: () => import_core5.isFileReference,
+  isFileReferenceArray: () => import_core5.isFileReferenceArray,
+  isMainThread: () => import_core5.isMainThread,
+  isOctavusSkillTool: () => import_core5.isOctavusSkillTool,
+  isOtherThread: () => import_core5.isOtherThread,
+  isProviderError: () => import_core5.isProviderError,
+  isRateLimitError: () => import_core5.isRateLimitError,
+  isRetryableError: () => import_core5.isRetryableError,
+  isToolError: () => import_core5.isToolError,
+  isValidationError: () => import_core5.isValidationError,
+  normalizeToolResultImages: () => normalizeToolResultImages,
+  resolveThread: () => import_core5.resolveThread,
+  safeParseStreamEvent: () => import_core5.safeParseStreamEvent,
+  safeParseUIMessage: () => import_core5.safeParseUIMessage,
+  safeParseUIMessages: () => import_core5.safeParseUIMessages,
+  threadForPart: () => import_core5.threadForPart,
+  toSSEStream: () => toSSEStream
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/api-error.ts
+var import_zod = require("zod");
+var ApiErrorResponseSchema = import_zod.z.object({
+  error: import_zod.z.string().optional(),
+  message: import_zod.z.string().optional(),
+  code: import_zod.z.string().optional()
+});
+var ApiError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "ApiError";
+  }
+};
+async function parseApiError(response, defaultMessage) {
+  const fallbackMessage = `${defaultMessage}: ${response.statusText}`;
+  try {
+    const json = await response.json();
+    const parsed = ApiErrorResponseSchema.safeParse(json);
+    if (parsed.success) {
+      return {
+        message: parsed.data.error ?? parsed.data.message ?? fallbackMessage,
+        code: parsed.data.code
+      };
+    }
+  } catch {
+  }
+  return { message: fallbackMessage };
+}
+async function throwApiError(response, defaultMessage) {
+  const { message, code } = await parseApiError(response, defaultMessage);
+  throw new ApiError(message, response.status, code);
+}
+
+// src/base-api-client.ts
+var BaseApiClient = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  async httpGet(path, schema) {
+    const response = await fetch(`${this.config.baseUrl}${path}`, {
+      method: "GET",
+      headers: this.config.getHeaders()
+    });
+    if (!response.ok) {
+      await throwApiError(response, "Request failed");
+    }
+    const data = await response.json();
+    return schema.parse(data);
+  }
+  async httpPost(path, body, schema) {
+    const response = await fetch(`${this.config.baseUrl}${path}`, {
+      method: "POST",
+      headers: this.config.getHeaders(),
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      await throwApiError(response, "Request failed");
+    }
+    const data = await response.json();
+    return schema.parse(data);
+  }
+  async httpPatch(path, body, schema) {
+    const response = await fetch(`${this.config.baseUrl}${path}`, {
+      method: "PATCH",
+      headers: this.config.getHeaders(),
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      await throwApiError(response, "Request failed");
+    }
+    const data = await response.json();
+    return schema.parse(data);
+  }
+  async httpDelete(path, schema) {
+    const response = await fetch(`${this.config.baseUrl}${path}`, {
+      method: "DELETE",
+      headers: this.config.getHeaders()
+    });
+    if (!response.ok) {
+      await throwApiError(response, "Request failed");
+    }
+    const data = await response.json();
+    return schema.parse(data);
+  }
+};
+
+// src/agent-types.ts
+var import_zod2 = require("zod");
+var agentFormatSchema = import_zod2.z.enum(["interactive", "worker"]);
+var agentSettingsSchema = import_zod2.z.object({
+  slug: import_zod2.z.string(),
+  name: import_zod2.z.string(),
+  description: import_zod2.z.string().optional(),
+  format: agentFormatSchema
+});
+var agentPromptSchema = import_zod2.z.object({
+  name: import_zod2.z.string(),
+  content: import_zod2.z.string()
+});
+var agentSchema = import_zod2.z.object({
+  slug: import_zod2.z.string(),
+  id: import_zod2.z.string(),
+  name: import_zod2.z.string(),
+  description: import_zod2.z.string().nullable(),
+  format: agentFormatSchema,
+  createdAt: import_zod2.z.string(),
+  updatedAt: import_zod2.z.string(),
+  projectId: import_zod2.z.string()
+});
+var agentsResponseSchema = import_zod2.z.object({
+  agents: import_zod2.z.array(agentSchema)
+});
+var agentDefinitionSchema = import_zod2.z.object({
+  settings: agentSettingsSchema,
+  protocol: import_zod2.z.string(),
+  prompts: import_zod2.z.array(agentPromptSchema),
+  id: import_zod2.z.string()
+});
+
+// src/agents.ts
+var AgentsApi = class extends BaseApiClient {
+  /** List all agents in the project */
+  async list() {
+    const response = await this.httpGet("/api/agents", agentsResponseSchema);
+    return response.agents;
+  }
+  /** Get a single agent by ID */
+  async get(agentId) {
+    return await this.httpGet(`/api/agents/${agentId}`, agentDefinitionSchema);
+  }
+};
+
+// src/agent-sessions.ts
+var import_zod3 = require("zod");
+var import_core3 = require("@octavus/core");
+
+// src/session.ts
+var import_core2 = require("@octavus/core");
+
+// src/streaming.ts
+var import_core = require("@octavus/core");
+async function* executeStream(config, payload, signal) {
+  let toolResults = payload.toolResults;
+  let executionId = payload.executionId;
+  let continueLoop = true;
+  while (continueLoop) {
+    if (signal?.aborted) {
+      yield { type: "finish", finishReason: "stop" };
+      return;
+    }
+    const body = config.buildBody({ executionId, toolResults });
+    let response;
+    try {
+      response = await fetch(config.url, {
+        method: "POST",
+        headers: config.config.getHeaders(),
+        body: JSON.stringify(body),
+        signal
+      });
+    } catch (err) {
+      if ((0, import_core.isAbortError)(err)) {
+        yield { type: "finish", finishReason: "stop" };
+        return;
+      }
+      throw err;
+    }
+    if (!response.ok) {
+      const { message } = await parseApiError(response, config.errorContext ?? "Request failed");
+      yield (0, import_core.createApiErrorEvent)(response.status, message);
+      return;
+    }
+    if (!response.body) {
+      yield (0, import_core.createInternalErrorEvent)("Response body is not readable");
+      return;
+    }
+    toolResults = void 0;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let pendingToolCalls = null;
+    let streamDone = false;
+    while (!streamDone) {
+      if (signal?.aborted) {
+        reader.releaseLock();
+        yield { type: "finish", finishReason: "stop" };
+        return;
+      }
+      let readResult;
+      try {
+        readResult = await reader.read();
+      } catch (err) {
+        if ((0, import_core.isAbortError)(err)) {
+          reader.releaseLock();
+          yield { type: "finish", finishReason: "stop" };
+          return;
+        }
+        throw err;
+      }
+      const { done, value } = readResult;
+      if (done) {
+        streamDone = true;
+        continue;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.startsWith("data: ") && line !== "data: [DONE]") {
+          try {
+            const parsed = (0, import_core.safeParseStreamEvent)(JSON.parse(line.slice(6)));
+            if (!parsed.success) {
+              continue;
+            }
+            const event = parsed.data;
+            if (event.type === "start" && event.executionId) {
+              executionId = event.executionId;
+            }
+            if (event.type === "tool-request") {
+              pendingToolCalls = event.toolCalls;
+              continue;
+            }
+            if (event.type === "finish") {
+              if (event.finishReason === "tool-calls" && pendingToolCalls) {
+                continue;
+              }
+              yield event;
+              continueLoop = false;
+              continue;
+            }
+            if (event.type === "resource-update" && config.onResourceUpdate) {
+              config.onResourceUpdate(event.name, event.value);
+            }
+            yield event;
+          } catch {
+          }
+        }
+      }
+    }
+    if (signal?.aborted) {
+      yield { type: "finish", finishReason: "stop" };
+      return;
+    }
+    if (pendingToolCalls && pendingToolCalls.length > 0) {
+      const serverTools = pendingToolCalls.filter((tc) => config.toolHandlers[tc.toolName]);
+      const clientTools = pendingToolCalls.filter((tc) => !config.toolHandlers[tc.toolName]);
+      const serverResults = await Promise.all(
+        serverTools.map(async (tc) => {
+          const handler = config.toolHandlers[tc.toolName];
+          try {
+            const result = await handler(tc.args);
+            return {
+              toolCallId: tc.toolCallId,
+              toolName: tc.toolName,
+              result,
+              outputVariable: tc.outputVariable,
+              blockIndex: tc.blockIndex,
+              thread: tc.thread,
+              workerId: tc.workerId
+            };
+          } catch (err) {
+            return {
+              toolCallId: tc.toolCallId,
+              toolName: tc.toolName,
+              error: err instanceof Error ? err.message : "Tool execution failed",
+              outputVariable: tc.outputVariable,
+              blockIndex: tc.blockIndex,
+              thread: tc.thread,
+              workerId: tc.workerId
+            };
+          }
+        })
+      );
+      if (config.onToolResults && serverResults.length > 0) {
+        await config.onToolResults(serverResults);
+      }
+      for (const tr of serverResults) {
+        if (tr.error) {
+          yield { type: "tool-output-error", toolCallId: tr.toolCallId, error: tr.error };
+        } else {
+          yield { type: "tool-output-available", toolCallId: tr.toolCallId, output: tr.result };
+        }
+      }
+      if (clientTools.length > 0) {
+        if (config.rejectClientToolCalls) {
+          const rejectedResults = clientTools.map((tc) => ({
+            toolCallId: tc.toolCallId,
+            toolName: tc.toolName,
+            error: `Tool "${tc.toolName}" is not available. No handler is registered for this tool.`,
+            outputVariable: tc.outputVariable,
+            blockIndex: tc.blockIndex,
+            thread: tc.thread,
+            workerId: tc.workerId
+          }));
+          for (const tr of rejectedResults) {
+            yield { type: "tool-output-error", toolCallId: tr.toolCallId, error: tr.error };
+          }
+          toolResults = [...serverResults, ...rejectedResults];
+        } else {
+          if (!executionId) {
+            yield (0, import_core.createInternalErrorEvent)("Missing executionId for client-tool-request");
+            return;
+          }
+          yield {
+            type: "client-tool-request",
+            executionId,
+            toolCalls: clientTools,
+            serverToolResults: serverResults.length > 0 ? serverResults : void 0
+          };
+          yield { type: "finish", finishReason: "client-tool-calls", executionId };
+          continueLoop = false;
+        }
+      } else {
+        toolResults = serverResults;
+      }
+    } else {
+      continueLoop = false;
+    }
+  }
+}
+
+// src/session.ts
+var SSE_HEARTBEAT_INTERVAL_MS = 15e3;
+function toSSEStream(events) {
+  const encoder = new TextEncoder();
+  const heartbeatBytes = encoder.encode(": heartbeat\n\n");
+  return new ReadableStream({
+    async start(controller) {
+      const heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(heartbeatBytes);
+        } catch {
+          clearInterval(heartbeat);
+        }
+      }, SSE_HEARTBEAT_INTERVAL_MS);
+      try {
+        for await (const event of events) {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}
+
+`));
+        }
+        controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+        controller.close();
+      } catch (err) {
+        const errorEvent = (0, import_core2.createInternalErrorEvent)(
+          err instanceof Error ? err.message : "Unknown error"
+        );
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(errorEvent)}
+
+`));
+        controller.close();
+      } finally {
+        clearInterval(heartbeat);
+      }
+    }
+  });
+}
+var AgentSession = class {
+  sessionId;
+  config;
+  toolHandlers;
+  resourceMap;
+  additionalToolSchemas;
+  additionalToolSchemasSent = false;
+  socketAbortController = null;
+  onToolResults;
+  rejectClientToolCalls;
+  constructor(sessionConfig) {
+    this.sessionId = sessionConfig.sessionId;
+    this.config = sessionConfig.config;
+    this.toolHandlers = sessionConfig.tools ?? {};
+    this.additionalToolSchemas = sessionConfig.additionalToolSchemas;
+    this.onToolResults = sessionConfig.onToolResults;
+    this.rejectClientToolCalls = sessionConfig.rejectClientToolCalls ?? false;
+    this.resourceMap = /* @__PURE__ */ new Map();
+    for (const resource of sessionConfig.resources ?? []) {
+      this.resourceMap.set(resource.name, resource);
+    }
+  }
+  /**
+   * Execute a session request and stream the response.
+   *
+   * This is the unified method that handles both triggers and continuations.
+   * Use this when you want to pass through requests from the client directly.
+   *
+   * @param request - The request (check `request.type` for the kind)
+   * @param options - Optional configuration including abort signal
+   *
+   * @example HTTP route (simple passthrough)
+   * ```typescript
+   * const events = session.execute(body, { signal: request.signal });
+   * return new Response(toSSEStream(events));
+   * ```
+   *
+   * @example WebSocket handler
+   * ```typescript
+   * socket.on('message', (data) => {
+   *   const events = session.execute(data);
+   *   for await (const event of events) {
+   *     socket.send(JSON.stringify(event));
+   *   }
+   * });
+   * ```
+   */
+  async *execute(request, options) {
+    if (request.type === "continue") {
+      yield* this.executeStream(
+        { executionId: request.executionId, toolResults: request.toolResults },
+        options?.signal
+      );
+    } else {
+      yield* this.executeStream(
+        {
+          triggerName: request.triggerName,
+          input: request.input,
+          rollbackAfterMessageId: request.rollbackAfterMessageId
+        },
+        options?.signal
+      );
+    }
+  }
+  getSessionId() {
+    return this.sessionId;
+  }
+  /**
+   * Handle a WebSocket protocol message (trigger, continue, or stop).
+   * Manages abort controller lifecycle internally.
+   *
+   * @example
+   * ```typescript
+   * conn.on('data', (raw) => {
+   *   session.handleSocketMessage(JSON.parse(raw), {
+   *     onEvent: (event) => conn.write(JSON.stringify(event)),
+   *     onFinish: async () => {
+   *       // Fetch messages and persist to your database for restoration
+   *     },
+   *   });
+   * });
+   * ```
+   */
+  async handleSocketMessage(message, handlers) {
+    if (message.type === "stop") {
+      this.socketAbortController?.abort();
+      return;
+    }
+    this.socketAbortController?.abort();
+    this.socketAbortController = new AbortController();
+    const localController = this.socketAbortController;
+    try {
+      const events = this.execute(message, { signal: localController.signal });
+      for await (const event of events) {
+        if (localController.signal.aborted) break;
+        handlers.onEvent(event);
+      }
+      if (!localController.signal.aborted && handlers.onFinish) {
+        await handlers.onFinish();
+      }
+    } catch (err) {
+      if (!localController.signal.aborted) {
+        const errorEvent = (0, import_core2.createInternalErrorEvent)(
+          err instanceof Error ? err.message : "Unknown error"
+        );
+        handlers.onEvent(errorEvent);
+      }
+    }
+  }
+  async *executeStream(payload, signal) {
+    yield* executeStream(
+      {
+        config: this.config,
+        toolHandlers: this.toolHandlers,
+        url: `${this.config.baseUrl}/api/agent-sessions/${this.sessionId}/trigger`,
+        buildBody: ({ executionId, toolResults }) => {
+          const body = {};
+          if (payload.triggerName !== void 0) body.triggerName = payload.triggerName;
+          if (payload.input !== void 0) body.input = payload.input;
+          if (payload.rollbackAfterMessageId !== void 0)
+            body.rollbackAfterMessageId = payload.rollbackAfterMessageId;
+          if (executionId !== void 0) body.executionId = executionId;
+          if (toolResults !== void 0) body.toolResults = toolResults;
+          if (!this.additionalToolSchemasSent && (this.additionalToolSchemas?.length ?? 0) > 0) {
+            body.additionalToolSchemas = this.additionalToolSchemas;
+            this.additionalToolSchemasSent = true;
+          }
+          return body;
+        },
+        onResourceUpdate: (name, value) => this.handleResourceUpdate(name, value),
+        onToolResults: this.onToolResults,
+        rejectClientToolCalls: this.rejectClientToolCalls,
+        errorContext: "Failed to trigger"
+      },
+      { executionId: payload.executionId, toolResults: payload.toolResults },
+      signal
+    );
+  }
+  handleResourceUpdate(name, value) {
+    const resource = this.resourceMap.get(name);
+    if (resource) {
+      void resource.onUpdate(value);
+    }
+  }
+};
+
+// src/agent-sessions.ts
+var createSessionResponseSchema = import_zod3.z.object({
+  sessionId: import_zod3.z.string()
+});
+var sessionStateSchema = import_zod3.z.object({
+  id: import_zod3.z.string(),
+  agentId: import_zod3.z.string(),
+  input: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown()),
+  variables: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown()),
+  resources: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown()),
+  messages: import_zod3.z.array(import_core3.chatMessageSchema),
+  status: import_zod3.z.literal("active").optional(),
+  createdAt: import_zod3.z.string(),
+  updatedAt: import_zod3.z.string()
+});
+var uiSessionResponseSchema = import_zod3.z.object({
+  sessionId: import_zod3.z.string(),
+  agentId: import_zod3.z.string(),
+  messages: import_zod3.z.array(import_core3.uiMessageSchema),
+  status: import_zod3.z.literal("active").optional()
+});
+var expiredSessionResponseSchema = import_zod3.z.object({
+  sessionId: import_zod3.z.string(),
+  agentId: import_zod3.z.string(),
+  status: import_zod3.z.literal("expired"),
+  createdAt: import_zod3.z.string()
+});
+var restoreSessionResponseSchema = import_zod3.z.object({
+  sessionId: import_zod3.z.string(),
+  restored: import_zod3.z.boolean()
+});
+var clearSessionResponseSchema = import_zod3.z.object({
+  sessionId: import_zod3.z.string(),
+  cleared: import_zod3.z.boolean()
+});
+var AgentSessionsApi = class extends BaseApiClient {
+  /** Create a new session for an agent */
+  async create(agentId, input) {
+    const response = await this.httpPost(
+      "/api/agent-sessions",
+      { agentId, input },
+      createSessionResponseSchema
+    );
+    return response.sessionId;
+  }
+  /**
+   * Get full session state (for internal/debug use)
+   * Note: Contains all messages including hidden content
+   *
+   * Returns SessionState for active sessions, ExpiredSessionState for expired sessions.
+   * Check `status` field to determine which type was returned.
+   */
+  async get(sessionId) {
+    const response = await fetch(`${this.config.baseUrl}/api/agent-sessions/${sessionId}`, {
+      method: "GET",
+      headers: this.config.getHeaders()
+    });
+    if (!response.ok) {
+      await throwApiError(response, "Request failed");
+    }
+    const data = await response.json();
+    const expiredResult = expiredSessionResponseSchema.safeParse(data);
+    if (expiredResult.success) {
+      return expiredResult.data;
+    }
+    return sessionStateSchema.parse(data);
+  }
+  /**
+   * Get UI-ready session messages (for client display)
+   * Returns only visible messages with hidden content filtered out.
+   *
+   * For expired sessions, returns status: 'expired' without messages.
+   * Use restore() to restore from stored messages before continuing.
+   */
+  async getMessages(sessionId) {
+    const response = await fetch(
+      `${this.config.baseUrl}/api/agent-sessions/${sessionId}?format=ui`,
+      {
+        method: "GET",
+        headers: this.config.getHeaders()
+      }
+    );
+    if (!response.ok) {
+      await throwApiError(response, "Request failed");
+    }
+    const data = await response.json();
+    const expiredResult = expiredSessionResponseSchema.safeParse(data);
+    if (expiredResult.success) {
+      return expiredResult.data;
+    }
+    return uiSessionResponseSchema.parse(data);
+  }
+  /**
+   * Restore an expired session from stored messages.
+   *
+   * Use this to restore a session after its state has expired.
+   * The consumer should have stored the UIMessage[] array from previous interactions.
+   *
+   * @param sessionId - The session ID to restore
+   * @param messages - Previously stored UIMessage[] array
+   * @param input - Optional session input for system prompt interpolation (same as create)
+   * @returns { sessionId, restored: true } if restored, { sessionId, restored: false } if already active
+   */
+  async restore(sessionId, messages, input) {
+    return await this.httpPost(
+      `/api/agent-sessions/${sessionId}/restore`,
+      { messages, input },
+      restoreSessionResponseSchema
+    );
+  }
+  /**
+   * Clear session state from the server.
+   * The session will transition to 'expired' status and can be restored with restore().
+   * Idempotent: succeeds even if state was already cleared/expired.
+   */
+  async clear(sessionId) {
+    return await this.httpDelete(`/api/agent-sessions/${sessionId}`, clearSessionResponseSchema);
+  }
+  /** Attach to an existing session for triggering events */
+  attach(sessionId, options = {}) {
+    const computerHandlers = options.computer?.toolHandlers() ?? {};
+    const mergedTools = { ...computerHandlers, ...options.tools };
+    return new AgentSession({
+      sessionId,
+      config: this.config,
+      tools: mergedTools,
+      resources: options.resources,
+      additionalToolSchemas: options.computer?.toolSchemas(),
+      onToolResults: options.onToolResults,
+      rejectClientToolCalls: options.rejectClientToolCalls
+    });
+  }
+};
+
+// src/files.ts
+var import_zod4 = require("zod");
+var fileUploadRequestSchema = import_zod4.z.object({
+  filename: import_zod4.z.string().min(1).max(255),
+  mediaType: import_zod4.z.string().min(1),
+  size: import_zod4.z.number().int().positive()
+});
+var fileUploadInfoSchema = import_zod4.z.object({
+  /** File ID to reference in messages */
+  id: import_zod4.z.string(),
+  /** Presigned PUT URL for uploading to S3 */
+  uploadUrl: import_zod4.z.url(),
+  /** Presigned GET URL for downloading after upload */
+  downloadUrl: import_zod4.z.url()
+});
+var uploadUrlsResponseSchema = import_zod4.z.object({
+  files: import_zod4.z.array(fileUploadInfoSchema)
+});
+var FilesApi = class extends BaseApiClient {
+  /**
+   * Get presigned URLs for uploading files to a session.
+   *
+   * Returns upload URLs (PUT) and download URLs (GET) for each file.
+   * Upload URLs expire in 15 minutes, download URLs match session TTL (24 hours).
+   *
+   * @param sessionId - The session ID to associate files with
+   * @param files - Array of file metadata (filename, mediaType, size)
+   * @returns Upload info with presigned URLs for each file
+   *
+   * @throws ApiError if session doesn't exist or validation fails
+   *
+   * @example
+   * ```typescript
+   * const { files } = await client.files.getUploadUrls(sessionId, [
+   *   { filename: 'photo.jpg', mediaType: 'image/jpeg', size: 102400 },
+   *   { filename: 'doc.pdf', mediaType: 'application/pdf', size: 204800 },
+   * ]);
+   *
+   * // files[0].id - Use in FileReference
+   * // files[0].uploadUrl - PUT to this URL
+   * // files[0].downloadUrl - Use as FileReference.url
+   * ```
+   */
+  async getUploadUrls(sessionId, files) {
+    return await this.httpPost(
+      "/api/files/upload-urls",
+      { sessionId, files },
+      uploadUrlsResponseSchema
+    );
+  }
+};
+
+// src/worker-error.ts
+var WorkerError = class extends Error {
+  constructor(message, sessionId) {
+    super(message);
+    this.sessionId = sessionId;
+    this.name = "WorkerError";
+  }
+};
+
+// src/workers.ts
+var WorkersApi = class extends BaseApiClient {
+  /**
+   * Execute a worker agent and stream the response.
+   *
+   * Worker agents execute steps sequentially and return an output value.
+   * Unlike interactive sessions, workers don't maintain persistent state.
+   *
+   * The execution handles the tool continuation pattern automatically:
+   * - Server tools (with handlers provided) are executed automatically
+   * - Client tools (without handlers) emit a client-tool-request event
+   *
+   * @param agentId - The worker agent ID
+   * @param input - Input values for the worker
+   * @param options - Optional configuration including tools and abort signal
+   * @returns An async generator of stream events
+   *
+   * @example Basic execution
+   * ```typescript
+   * const events = client.workers.execute(agentId, { TOPIC: 'AI safety' });
+   * for await (const event of events) {
+   *   if (event.type === 'worker-start') {
+   *     console.log(`Worker ${event.workerSlug} started (${event.workerId})`);
+   *   }
+   *   if (event.type === 'worker-result') {
+   *     if (event.error) {
+   *       console.error('Worker failed:', event.error);
+   *     } else {
+   *       console.log('Output:', event.output);
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * @example With tool handlers
+   * ```typescript
+   * const events = client.workers.execute(agentId, { TOPIC: 'AI safety' }, {
+   *   tools: {
+   *     'web-search': async (args) => {
+   *       return await searchWeb(args.query);
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  async *execute(agentId, input, options = {}) {
+    yield* executeStream(
+      {
+        config: this.config,
+        toolHandlers: options.tools ?? {},
+        url: `${this.config.baseUrl}/api/agents/${agentId}/execute`,
+        buildBody: ({ executionId, toolResults }) => !executionId ? { type: "start", input } : { type: "continue", executionId, toolResults },
+        errorContext: "Failed to execute worker"
+      },
+      {},
+      options.signal
+    );
+  }
+  /**
+   * Execute a worker agent and return the final output.
+   *
+   * Non-streaming equivalent of `execute()` — runs the worker to completion
+   * and returns the output value directly. Use this when you don't need to
+   * observe intermediate streaming events.
+   *
+   * @param agentId - The worker agent ID
+   * @param input - Input values for the worker
+   * @param options - Optional configuration including tools and abort signal
+   * @returns The worker output and session ID
+   * @throws {WorkerError} If the worker fails or completes without output
+   *
+   * @example Basic usage
+   * ```typescript
+   * const { output, sessionId } = await client.workers.generate(agentId, {
+   *   TOPIC: 'AI safety',
+   * });
+   * console.log(output);
+   * console.log(`Debug: ${client.baseUrl}/platform/sessions/${sessionId}`);
+   * ```
+   *
+   * @example With timeout
+   * ```typescript
+   * const { output } = await client.workers.generate(agentId, input, {
+   *   signal: AbortSignal.timeout(120_000),
+   * });
+   * ```
+   */
+  async generate(agentId, input, options = {}) {
+    let sessionId;
+    for await (const event of this.execute(agentId, input, options)) {
+      if (event.type === "start" && event.executionId) {
+        sessionId = event.executionId;
+      } else if (event.type === "error") {
+        throw new WorkerError(event.message, sessionId);
+      } else if (event.type === "worker-result") {
+        if (event.error) {
+          throw new WorkerError(event.error, sessionId ?? event.workerId);
+        }
+        return {
+          output: event.output,
+          sessionId: sessionId ?? event.workerId
+        };
+      }
+    }
+    throw new WorkerError("Worker completed without producing a result", sessionId);
+  }
+  /**
+   * Continue a worker execution after client-side tool handling.
+   *
+   * Use this when your worker has tools without server-side handlers.
+   * The execution returns a client-tool-request event with an executionId.
+   * Execute the tools client-side, then call this method to continue.
+   *
+   * @param agentId - The worker agent ID
+   * @param executionId - The execution ID from the client-tool-request event
+   * @param toolResults - Results from client-side tool execution
+   * @param options - Optional configuration including tools and abort signal
+   * @returns An async generator of stream events
+   *
+   * @example
+   * ```typescript
+   * // Start execution
+   * for await (const event of client.workers.execute(agentId, input)) {
+   *   if (event.type === 'client-tool-request') {
+   *     // Execute tools client-side
+   *     const results = await executeToolsClientSide(event.toolCalls);
+   *     // Continue execution
+   *     for await (const ev of client.workers.continue(agentId, event.executionId, results)) {
+   *       // Handle remaining events
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  async *continue(agentId, executionId, toolResults, options = {}) {
+    yield* executeStream(
+      {
+        config: this.config,
+        toolHandlers: options.tools ?? {},
+        url: `${this.config.baseUrl}/api/agents/${agentId}/execute`,
+        buildBody: ({ executionId: execId, toolResults: results }) => ({
+          type: "continue",
+          executionId: execId ?? executionId,
+          toolResults: results ?? toolResults
+        }),
+        errorContext: "Failed to continue worker"
+      },
+      { executionId, toolResults },
+      options.signal
+    );
+  }
+};
+
+// src/client.ts
+var OctavusClient = class {
+  agents;
+  agentSessions;
+  files;
+  workers;
+  baseUrl;
+  apiKey;
+  traceModelRequests;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.traceModelRequests = config.traceModelRequests ?? false;
+    const apiConfig = {
+      baseUrl: this.baseUrl,
+      getHeaders: () => this.getHeaders()
+    };
+    this.agents = new AgentsApi(apiConfig);
+    this.agentSessions = new AgentSessionsApi(apiConfig);
+    this.files = new FilesApi(apiConfig);
+    this.workers = new WorkersApi(apiConfig);
+  }
+  getHeaders() {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+    if (this.traceModelRequests) {
+      headers["X-Octavus-Trace"] = "true";
+    }
+    return headers;
+  }
+};
+
+// src/resource.ts
+var Resource = class {
+};
+
+// src/normalize-images.ts
+var import_core4 = require("@octavus/core");
+var IMAGE_EXTENSIONS = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "image/svg+xml": "svg"
+};
+function getExtensionFromMediaType(mediaType) {
+  return IMAGE_EXTENSIONS[mediaType] ?? "png";
+}
+function isImagePart(part) {
+  return typeof part === "object" && part !== null && part.type === "image" && typeof part.data === "string";
+}
+function hasImageParts(value) {
+  return Array.isArray(value) && value.some(isImagePart);
+}
+function base64ToArrayBuffer(base64) {
+  const binary = atob(base64);
+  const buffer = new ArrayBuffer(binary.length);
+  const view = new Uint8Array(buffer);
+  for (let i = 0; i < binary.length; i++) {
+    view[i] = binary.charCodeAt(i);
+  }
+  return buffer;
+}
+async function normalizeToolResultImages(toolResults, filesApi, sessionId) {
+  for (const toolResult of toolResults) {
+    if (toolResult.outputVariable) continue;
+    if (!hasImageParts(toolResult.result)) continue;
+    const parts = toolResult.result;
+    const files = toolResult.files ? [...toolResult.files] : [];
+    const imageIndices = [];
+    const imageBuffers = [];
+    const uploadRequests = [];
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      if (!isImagePart(part)) continue;
+      const buffer = base64ToArrayBuffer(part.data);
+      const mimeType = part.mimeType || "image/png";
+      imageIndices.push(i);
+      imageBuffers.push(buffer);
+      uploadRequests.push({
+        filename: `image-${(0, import_core4.generateId)()}.${getExtensionFromMediaType(mimeType)}`,
+        mediaType: mimeType,
+        size: buffer.byteLength
+      });
+    }
+    if (uploadRequests.length === 0) continue;
+    let uploadInfos;
+    try {
+      const response = await filesApi.getUploadUrls(sessionId, uploadRequests);
+      uploadInfos = response.files;
+    } catch {
+      continue;
+    }
+    const uploadResults = await Promise.allSettled(
+      uploadInfos.map(
+        (info, i) => fetch(info.uploadUrl, {
+          method: "PUT",
+          body: imageBuffers[i],
+          headers: { "Content-Type": uploadRequests[i].mediaType }
+        })
+      )
+    );
+    const summaryParts = [];
+    let imageIdx = 0;
+    for (let i = 0; i < parts.length; i++) {
+      if (imageIdx < imageIndices.length && imageIndices[imageIdx] === i) {
+        const uploadResult = uploadResults[imageIdx];
+        const info = uploadInfos[imageIdx];
+        const request = uploadRequests[imageIdx];
+        const buf = imageBuffers[imageIdx];
+        if (uploadResult.status === "fulfilled" && uploadResult.value.ok) {
+          files.push({
+            id: info.id,
+            mediaType: request.mediaType,
+            url: info.downloadUrl,
+            filename: request.filename,
+            size: buf.byteLength
+          });
+          summaryParts.push({
+            type: "image",
+            mediaType: request.mediaType,
+            size: buf.byteLength,
+            url: info.downloadUrl
+          });
+        } else {
+          summaryParts.push(parts[i]);
+        }
+        imageIdx += 1;
+      } else {
+        summaryParts.push(parts[i]);
+      }
+    }
+    toolResult.files = files;
+    toolResult.result = summaryParts;
+  }
+}
+
+// src/index.ts
+var import_core5 = require("@octavus/core");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentSession,
+  AgentSessionsApi,
+  AgentsApi,
+  ApiError,
+  AppError,
+  ConflictError,
+  FilesApi,
+  ForbiddenError,
+  MAIN_THREAD,
+  NotFoundError,
+  OCTAVUS_SKILL_TOOLS,
+  OctavusClient,
+  OctavusError,
+  Resource,
+  ValidationError,
+  WorkerError,
+  WorkersApi,
+  createApiErrorEvent,
+  createErrorEvent,
+  createInternalErrorEvent,
+  errorToStreamEvent,
+  generateId,
+  getSkillSlugFromToolCall,
+  isAbortError,
+  isAuthenticationError,
+  isFileReference,
+  isFileReferenceArray,
+  isMainThread,
+  isOctavusSkillTool,
+  isOtherThread,
+  isProviderError,
+  isRateLimitError,
+  isRetryableError,
+  isToolError,
+  isValidationError,
+  normalizeToolResultImages,
+  resolveThread,
+  safeParseStreamEvent,
+  safeParseUIMessage,
+  safeParseUIMessages,
+  threadForPart,
+  toSSEStream
+});
+//# sourceMappingURL=index.cjs.map