agi 0.3.0 → 0.4.1

package/dist/index.mjs

@@ -1,4 +1,12 @@
 import { createParser } from 'eventsource-parser';
+import { spawn } from 'child_process';
+import { EventEmitter } from 'events';
+import { createInterface } from 'readline';
+import { existsSync } from 'fs';
+import { dirname, join, delimiter } from 'path';
+import { fileURLToPath } from 'url';
+import { platform, arch } from 'os';
+import { createRequire } from 'module';
 
 // src/http.ts
 
@@ -112,6 +120,43 @@ var HTTPClient = class {
     }
     throw lastError || new AGIError("Request failed after retries");
   }
+  /**
+   * Make an HTTP request to an absolute URL with retries and error handling
+   */
+  async requestUrl(method, url, options) {
+    const headers = this.buildHeaders(options?.headers);
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: options?.json ? JSON.stringify(options.json) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+          await this.handleErrorResponse(response);
+        }
+        const data = await response.json();
+        return data;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof AGIError && error.statusCode && error.statusCode < 500) {
+          if (error.statusCode !== 429) {
+            throw error;
+          }
+        }
+        if (attempt === this.maxRetries) {
+          break;
+        }
+        await this.sleep(Math.pow(2, attempt) * 1e3);
+      }
+    }
+    throw lastError || new AGIError("Request failed after retries");
+  }
   /**
    * Stream Server-Sent Events from an endpoint
    */
@@ -192,10 +237,11 @@ var HTTPClient = class {
   }
   async handleErrorResponse(response) {
     let errorData;
+    const text = await response.text();
     try {
-      errorData = await response.json();
+      errorData = JSON.parse(text);
     } catch {
-      errorData = await response.text();
+      errorData = text;
     }
     const errorMessage = typeof errorData === "object" && errorData.message ? errorData.message : typeof errorData === "string" ? errorData : `HTTP ${response.status}: ${response.statusText}`;
     switch (response.status) {
@@ -577,7 +623,8 @@ function normalizeSessionResponse(data) {
     status: data.status,
     createdAt: data.created_at ?? data.createdAt,
     environmentId: data.environment_id ?? data.environmentId,
-    goal: data.goal
+    goal: data.goal,
+    agentSessionType: data.agent_session_type ?? data.agentSessionType
   };
 }
 
@@ -590,16 +637,24 @@ var SessionsResource = class {
   /**
    * Create a new agent session
    *
-   * @param agentName - Agent model to use (e.g., "agi-0", "agi-0-fast", "agi-1")
+   * @param agentName - Agent model to use (e.g., "agi-0", "agi-2-claude")
    * @param options - Session creation options
-   * @returns SessionResponse with session_id, vnc_url, status, etc.
+   * @returns SessionResponse with sessionId, vncUrl, agentUrl, status, etc.
    *
    * @example
    * ```typescript
+   * // Standard browser session
    * const session = await client.sessions.create('agi-0', {
    *   webhookUrl: 'https://yourapp.com/webhook',
    *   maxSteps: 200
    * });
+   *
+   * // Desktop session (client-managed)
+   * const session = await client.sessions.create('agi-2-claude', {
+   *   agentSessionType: 'desktop',
+   *   goal: 'Open calculator and compute 2+2'
+   * });
+   * console.log(session.agentUrl); // Use with client.desktop.step()
    * ```
    */
   async create(agentName = "agi-0", options) {
@@ -612,6 +667,11 @@ var SessionsResource = class {
     if (options?.restoreFromEnvironmentId) {
       payload.restore_from_environment_id = options.restoreFromEnvironmentId;
     }
+    if (options?.agentSessionType) {
+      payload.agent_session_type = options.agentSessionType;
+    }
+    if (options?.cdpUrl) payload.cdp_url = options.cdpUrl;
+    if (options?.environmentType) payload.environment_type = options.environmentType;
     const response = await this.http.request("POST", "/v1/sessions", {
       json: payload
     });
@@ -876,6 +936,90 @@ var SessionsResource = class {
   async screenshot(sessionId) {
     return this.http.request("GET", `/v1/sessions/${sessionId}/screenshot`);
   }
+  // ===== CLIENT-DRIVEN SESSION CONTROL =====
+  /**
+   * Execute a single step for client-driven sessions (desktop mode).
+   *
+   * In desktop mode (agentSessionType="desktop"), the client manages the
+   * execution loop. This method sends a screenshot to the agent and receives
+   * actions to execute locally.
+   *
+   * @param agentUrl - Agent service URL from session.agentUrl
+   * @param sessionId - Session ID (required for routing in shared sandbox)
+   * @param screenshot - Base64-encoded screenshot (full resolution, JPEG or PNG)
+   * @param message - Optional user message (goal on first call, or follow-up instruction)
+   * @returns StepDesktopResponse with actions, thinking, finished, askUser, and step
+   *
+   * @example
+   * ```typescript
+   * // Create a desktop session
+   * const session = await client.sessions.create('agi-2-claude', {
+   *   agentSessionType: 'desktop',
+   *   goal: 'Open calculator and compute 2+2'
+   * });
+   *
+   * // Client-managed loop
+   * let finished = false;
+   * while (!finished) {
+   *   const screenshot = captureScreenshot(); // Client captures
+   *   const result = await client.sessions.step(
+   *     session.agentUrl!,
+   *     session.sessionId,
+   *     screenshot
+   *   );
+   *   executeActions(result.actions); // Client executes
+   *   finished = result.finished;
+   *   if (result.askUser) {
+   *     const answer = await promptUser(result.askUser);
+   *     // Send answer in next step
+   *   }
+   * }
+   * ```
+   */
+  async step(agentUrl, sessionId, screenshot, message) {
+    const url = `${agentUrl.replace(/\/$/, "")}/step_desktop`;
+    const payload = { screenshot, session_id: sessionId };
+    if (message !== void 0) {
+      payload.message = message;
+    }
+    const response = await this.http.requestUrl("POST", url, {
+      json: payload
+    });
+    return {
+      actions: response.actions || [],
+      thinking: response.thinking,
+      finished: response.finished ?? false,
+      askUser: response.ask_user ?? response.askUser,
+      step: response.step ?? 0
+    };
+  }
+  // ===== MODELS =====
+  /**
+   * List available agent models.
+   *
+   * @param filter - Optional filter: "cdp" for browser agents, "desktop" for
+   *                 desktop agents
+   * @returns ModelsResponse with list of available model names
+   *
+   * @example
+   * ```typescript
+   * // List all models
+   * const models = await client.sessions.listModels();
+   * console.log(models.models);
+   *
+   * // List only desktop-compatible models
+   * const desktopModels = await client.sessions.listModels('desktop');
+   * console.log(desktopModels.models);
+   * // ['agi-2-claude', 'agi-2-qwen']
+   * ```
+   */
+  async listModels(filter) {
+    const query = {};
+    if (filter) {
+      query.filter = filter;
+    }
+    return this.http.request("GET", "/v1/models", { query });
+  }
 };
 
 // src/client.ts
@@ -941,6 +1085,615 @@ var AGIClient = class {
   }
 };
 
-export { AGIClient, AGIError, APIError, AgentExecutionError, AuthenticationError, NotFoundError, PermissionError, RateLimitError, Screenshot, SessionContext, SessionsResource, ValidationError };
+// src/loop.ts
+var AgentLoop = class {
+  client;
+  agentUrl;
+  sessionId;
+  captureScreenshot;
+  executeActions;
+  onThinking;
+  onAskUser;
+  onStep;
+  stepDelay;
+  _state = "idle";
+  _lastResult = null;
+  _currentStep = 0;
+  // Pause control using Promise-based approach
+  pauseResolve = null;
+  pausePromise = null;
+  constructor(options) {
+    this.client = options.client;
+    this.agentUrl = options.agentUrl;
+    this.sessionId = options.sessionId;
+    this.captureScreenshot = options.captureScreenshot;
+    this.executeActions = options.executeActions;
+    this.onThinking = options.onThinking;
+    this.onAskUser = options.onAskUser;
+    this.onStep = options.onStep;
+    this.stepDelay = options.stepDelay ?? 0;
+  }
+  /** Current state of the loop. */
+  get state() {
+    return this._state;
+  }
+  /** Current step number. */
+  get currentStep() {
+    return this._currentStep;
+  }
+  /** Last step result, if any. */
+  get lastResult() {
+    return this._lastResult;
+  }
+  /**
+   * Start the execution loop.
+   *
+   * Runs the loop until the task is finished, stopped, or an unhandled
+   * ask_user question is encountered.
+   *
+   * @param message - Optional initial message (goal or instruction).
+   *   Usually not needed if goal was set during session creation.
+   * @returns The final StepDesktopResponse
+   * @throws Error if loop is already running
+   */
+  async start(message) {
+    if (this._state === "running") {
+      throw new Error("Loop is already running");
+    }
+    this._state = "running";
+    let currentMessage = message;
+    let result = null;
+    try {
+      while (true) {
+        if (this.pausePromise) {
+          await this.pausePromise;
+        }
+        const currentState = this._state;
+        if (currentState === "paused") {
+          continue;
+        }
+        if (currentState !== "running") {
+          break;
+        }
+        const screenshot = await this.captureScreenshot();
+        result = await this.client.sessions.step(
+          this.agentUrl,
+          this.sessionId,
+          screenshot,
+          currentMessage
+        );
+        currentMessage = void 0;
+        this._lastResult = result;
+        this._currentStep = result.step;
+        if (result.thinking && this.onThinking) {
+          this.onThinking(result.thinking);
+        }
+        if (this.onStep) {
+          this.onStep(result.step, result);
+        }
+        if (result.askUser) {
+          if (this.onAskUser) {
+            const answer = await this.onAskUser(result.askUser);
+            currentMessage = answer;
+          } else {
+            this._state = "stopped";
+            return result;
+          }
+        }
+        if (result.actions.length > 0) {
+          await this.executeActions(result.actions);
+        }
+        if (result.finished) {
+          this._state = "finished";
+          return result;
+        }
+        if (this.stepDelay > 0) {
+          await new Promise((resolve) => setTimeout(resolve, this.stepDelay));
+        }
+      }
+    } catch (error) {
+      this._state = "stopped";
+      throw error;
+    }
+    if (result === null) {
+      result = {
+        actions: [],
+        thinking: void 0,
+        finished: true,
+        askUser: void 0,
+        step: this._currentStep
+      };
+    }
+    return result;
+  }
+  /**
+   * Pause the execution loop.
+   *
+   * The loop will complete the current step before pausing.
+   * Call resume() to continue.
+   */
+  pause() {
+    if (this._state !== "running") {
+      return;
+    }
+    this._state = "paused";
+    this.pausePromise = new Promise((resolve) => {
+      this.pauseResolve = resolve;
+    });
+  }
+  /**
+   * Resume a paused loop.
+   */
+  resume() {
+    if (this._state !== "paused") {
+      return;
+    }
+    this._state = "running";
+    if (this.pauseResolve) {
+      this.pauseResolve();
+      this.pauseResolve = null;
+      this.pausePromise = null;
+    }
+  }
+  /**
+   * Stop the execution loop.
+   *
+   * The loop will complete the current step before stopping.
+   */
+  stop() {
+    this._state = "stopped";
+    if (this.pauseResolve) {
+      this.pauseResolve();
+      this.pauseResolve = null;
+      this.pausePromise = null;
+    }
+  }
+  /** Check if the loop is currently running. */
+  isRunning() {
+    return this._state === "running";
+  }
+  /** Check if the loop is currently paused. */
+  isPaused() {
+    return this._state === "paused";
+  }
+  /** Check if the loop has finished successfully. */
+  isFinished() {
+    return this._state === "finished";
+  }
+};
+var __filename$1 = fileURLToPath(import.meta.url);
+var __dirname$1 = dirname(__filename$1);
+var require2 = createRequire(import.meta.url);
+function getPlatformId() {
+  const os = platform();
+  const cpu = arch();
+  if (os === "darwin") {
+    return cpu === "arm64" ? "darwin-arm64" : "darwin-x64";
+  } else if (os === "linux") {
+    return "linux-x64";
+  } else if (os === "win32") {
+    return "win32-x64";
+  }
+  throw new Error(`Unsupported platform: ${os}-${cpu}`);
+}
+function getBinaryFilename(platformId) {
+  const id = platformId ?? getPlatformId();
+  if (id === "win32-x64") {
+    return "agi-driver.exe";
+  }
+  return "agi-driver";
+}
+function getSearchPaths(platformId) {
+  const filename = getBinaryFilename(platformId);
+  const paths = [];
+  const packageName = `@agi/agi-${platformId}`;
+  try {
+    const packagePath = require2.resolve(`${packageName}/package.json`);
+    const packageDir = dirname(packagePath);
+    paths.push(join(packageDir, filename));
+  } catch {
+  }
+  paths.push(join(__dirname$1, "..", "..", "bin", filename));
+  paths.push(join(__dirname$1, "..", "..", "..", "bin", filename));
+  const envPath = process.env.PATH || "";
+  for (const dir of envPath.split(delimiter)) {
+    if (dir) {
+      paths.push(join(dir, filename));
+    }
+  }
+  return paths;
+}
+function findBinaryPath() {
+  const platformId = getPlatformId();
+  const searchPaths = getSearchPaths(platformId);
+  for (const path of searchPaths) {
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+  throw new Error(
+    `Could not find agi-driver binary for ${platformId}. Searched: ${searchPaths.join(", ")}. Install the optional dependency @agi/agi-${platformId} or ensure agi-driver is in PATH.`
+  );
+}
+function isBinaryAvailable() {
+  try {
+    findBinaryPath();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/driver/protocol.ts
+function parseEvent(line) {
+  const data = JSON.parse(line);
+  return data;
+}
+function serializeCommand(command) {
+  return JSON.stringify(command);
+}
+
+// src/driver/driver.ts
+var AgentDriver = class extends EventEmitter {
+  binaryPath;
+  model;
+  platform;
+  mode;
+  agentName;
+  apiUrl;
+  environmentType;
+  env;
+  process = null;
+  readline = null;
+  state = "idle";
+  step = 0;
+  sessionId = "";
+  screenWidth = 0;
+  screenHeight = 0;
+  resolveStart = null;
+  rejectStart = null;
+  // Pending callbacks for user interaction
+  pendingConfirm = null;
+  pendingAnswer = null;
+  constructor(options = {}) {
+    super();
+    this.binaryPath = options.binaryPath ?? findBinaryPath();
+    this.model = options.model ?? "claude-sonnet";
+    this.platform = options.platform ?? "desktop";
+    this.mode = options.mode ?? "";
+    this.agentName = options.agentName ?? "";
+    this.apiUrl = options.apiUrl ?? "";
+    this.environmentType = options.environmentType ?? "";
+    this.env = options.env ?? {};
+  }
+  /**
+   * Get the current state of the driver.
+   */
+  get currentState() {
+    return this.state;
+  }
+  /**
+   * Get the current step number.
+   */
+  get currentStep() {
+    return this.step;
+  }
+  /**
+   * Check if the driver is running.
+   */
+  get isRunning() {
+    return this.state === "running";
+  }
+  /**
+   * Check if the driver is waiting for user input.
+   */
+  get isWaiting() {
+    return this.state === "waiting_confirmation" || this.state === "waiting_answer";
+  }
+  /**
+   * Start the agent with a goal.
+   *
+   * @param goal - The task for the agent to accomplish
+   * @param screenshot - Initial screenshot (base64-encoded). Not needed in local mode.
+   * @param screenWidth - Screen width in pixels. Not needed in local mode.
+   * @param screenHeight - Screen height in pixels. Not needed in local mode.
+   * @param mode - Override the mode set in DriverOptions.
+   * @returns Promise that resolves when the agent finishes
+   */
+  async start(goal, screenshot = "", screenWidth = 0, screenHeight = 0, mode) {
+    if (this.process) {
+      throw new Error("Driver is already running");
+    }
+    this.sessionId = `session_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    this.screenWidth = screenWidth;
+    this.screenHeight = screenHeight;
+    return new Promise((resolve, reject) => {
+      this.resolveStart = resolve;
+      this.rejectStart = reject;
+      this.process = spawn(this.binaryPath, [], {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          ...this.env
+        }
+      });
+      this.process.on("error", (err) => {
+        this.cleanup();
+        if (this.rejectStart) {
+          this.rejectStart(err);
+          this.rejectStart = null;
+          this.resolveStart = null;
+        }
+      });
+      this.process.on("exit", (code) => {
+        this.cleanup();
+        if (this.rejectStart) {
+          this.rejectStart(new Error(`Driver exited with code ${code}`));
+          this.rejectStart = null;
+          this.resolveStart = null;
+        }
+      });
+      this.readline = createInterface({
+        input: this.process.stdout,
+        crlfDelay: Infinity
+      });
+      this.readline.on("line", (line) => {
+        this.handleLine(line).catch((err) => {
+          this.emit("error", {
+            event: "error",
+            message: `Error handling line: ${err.message}`,
+            code: "parse_error",
+            recoverable: false,
+            step: this.step
+          });
+        });
+      });
+      this.process.stderr?.on("data", (data) => {
+        this.emit("stderr", data.toString());
+      });
+      this.once("ready", () => {
+        const startCmd = {
+          command: "start",
+          session_id: this.sessionId,
+          goal,
+          screenshot,
+          screen_width: screenWidth,
+          screen_height: screenHeight,
+          platform: this.platform,
+          model: this.model,
+          mode: mode ?? this.mode,
+          agent_name: this.agentName || void 0,
+          api_url: this.apiUrl || void 0,
+          environment_type: this.environmentType || void 0
+        };
+        this.sendCommand(startCmd);
+      });
+    });
+  }
+  /**
+   * Send a new screenshot to the driver.
+   *
+   * @param screenshot - Base64-encoded screenshot
+   * @param screenWidth - Screen width in pixels
+   * @param screenHeight - Screen height in pixels
+   */
+  sendScreenshot(screenshot, screenWidth, screenHeight) {
+    if (!this.process) {
+      throw new Error("Driver is not running");
+    }
+    const cmd = {
+      command: "screenshot",
+      data: screenshot,
+      screen_width: screenWidth ?? this.screenWidth,
+      screen_height: screenHeight ?? this.screenHeight
+    };
+    this.sendCommand(cmd);
+  }
+  /**
+   * Pause the driver.
+   */
+  pause() {
+    if (!this.process) return;
+    this.sendCommand({ command: "pause" });
+  }
+  /**
+   * Resume the driver.
+   */
+  resume() {
+    if (!this.process) return;
+    this.sendCommand({ command: "resume" });
+  }
+  /**
+   * Stop the driver.
+   *
+   * @param reason - Reason for stopping
+   */
+  async stop(reason) {
+    if (!this.process) return;
+    const cmd = {
+      command: "stop",
+      reason
+    };
+    this.sendCommand(cmd);
+    await new Promise((resolve) => {
+      if (!this.process) {
+        resolve();
+        return;
+      }
+      this.process.once("exit", () => resolve());
+      setTimeout(() => {
+        if (this.process) {
+          this.process.kill();
+        }
+        resolve();
+      }, 1e3);
+    });
+    this.cleanup();
+  }
+  /**
+   * Respond to a confirmation request.
+   *
+   * @param approved - Whether the action is approved
+   * @param message - Optional message to send with the response
+   */
+  respondConfirm(approved, message) {
+    if (!this.process || this.state !== "waiting_confirmation") {
+      throw new Error("Not waiting for confirmation");
+    }
+    const cmd = {
+      command: "confirm",
+      approved,
+      message
+    };
+    this.sendCommand(cmd);
+    if (this.pendingConfirm) {
+      this.pendingConfirm(approved, message);
+      this.pendingConfirm = null;
+    }
+  }
+  /**
+   * Respond to a question.
+   *
+   * @param text - The answer text
+   * @param questionId - Optional question ID
+   */
+  respondAnswer(text, questionId) {
+    if (!this.process || this.state !== "waiting_answer") {
+      throw new Error("Not waiting for answer");
+    }
+    const cmd = {
+      command: "answer",
+      text,
+      question_id: questionId
+    };
+    this.sendCommand(cmd);
+    if (this.pendingAnswer) {
+      this.pendingAnswer(text);
+      this.pendingAnswer = null;
+    }
+  }
+  sendCommand(cmd) {
+    if (!this.process?.stdin) return;
+    const line = serializeCommand(cmd) + "\n";
+    this.process.stdin.write(line);
+  }
+  async handleLine(line) {
+    if (!line.trim()) return;
+    let event;
+    try {
+      event = parseEvent(line);
+    } catch (e) {
+      console.error("Failed to parse event:", line);
+      return;
+    }
+    this.step = event.step;
+    this.emit("event", event);
+    switch (event.event) {
+      case "ready":
+        this.emit("ready", event);
+        break;
+      case "state_change":
+        this.state = event.state;
+        this.emit("state_change", event.state, event);
+        break;
+      case "thinking":
+        this.emit("thinking", event.text, event);
+        break;
+      case "action":
+        this.emit("action", event.action, event);
+        break;
+      case "confirm": {
+        this.state = "waiting_confirmation";
+        const confirmListeners = this.rawListeners("confirm");
+        let confirmHandled = false;
+        for (const listener of confirmListeners) {
+          try {
+            const approved = await listener(event.reason, event);
+            if (typeof approved === "boolean" && !confirmHandled) {
+              this.respondConfirm(approved);
+              confirmHandled = true;
+            }
+          } catch {
+          }
+        }
+        break;
+      }
+      case "ask_question": {
+        this.state = "waiting_answer";
+        const questionListeners = this.rawListeners("ask_question");
+        let questionHandled = false;
+        for (const listener of questionListeners) {
+          try {
+            const answer = await listener(event.question, event);
+            if (typeof answer === "string" && !questionHandled) {
+              this.respondAnswer(answer, event.question_id);
+              questionHandled = true;
+            }
+          } catch {
+          }
+        }
+        break;
+      }
+      case "screenshot_captured":
+        this.emit("screenshot_captured", event);
+        break;
+      case "session_created":
+        this.emit("session_created", event);
+        break;
+      case "finished":
+        this.handleFinished(event);
+        break;
+      case "error":
+        this.handleError(event);
+        break;
+    }
+  }
+  handleFinished(event) {
+    this.state = "finished";
+    this.emit("finished", event);
+    if (this.resolveStart) {
+      this.resolveStart({
+        success: event.success,
+        reason: event.reason,
+        summary: event.summary,
+        step: event.step
+      });
+      this.resolveStart = null;
+      this.rejectStart = null;
+    }
+    this.cleanup();
+  }
+  handleError(event) {
+    this.emit("error", event);
+    if (!event.recoverable) {
+      this.state = "error";
+      if (this.rejectStart) {
+        this.rejectStart(new Error(`${event.code}: ${event.message}`));
+        this.rejectStart = null;
+        this.resolveStart = null;
+      }
+      this.cleanup();
+    }
+  }
+  cleanup() {
+    if (this.readline) {
+      this.readline.close();
+      this.readline = null;
+    }
+    if (this.rejectStart) {
+      this.rejectStart(new Error("Driver stopped"));
+      this.rejectStart = null;
+      this.resolveStart = null;
+    }
+    if (this.process) {
+      this.process.kill();
+      this.process = null;
+    }
+    this.pendingConfirm = null;
+    this.pendingAnswer = null;
+  }
+};
+
+export { AGIClient, AGIError, APIError, AgentDriver, AgentExecutionError, AgentLoop, AuthenticationError, NotFoundError, PermissionError, RateLimitError, Screenshot, SessionContext, SessionsResource, ValidationError, findBinaryPath, getPlatformId, isBinaryAvailable };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map