@agentstep/agent-sdk 0.1.0

package/src/sprite/client.ts

@@ -0,0 +1,294 @@
+/**
+ * sprites.dev REST client.
+ *
+ * All endpoints Bearer-authenticated. Per-operation timeouts via AbortSignal.
+ * Checkpoint/restore consume the NDJSON progress stream and reject on an
+ * `error` event. See https://docs.sprites.dev/api/v001-rc30/ for the spec.
+ *
+ * URL/auth pattern inspired by
+ * 
+ */
+import { getConfig } from "../config";
+import { ApiError } from "../errors";
+
+export interface Sprite {
+  name: string;
+  status: "cold" | "warm" | "running";
+  http_endpoint?: string;
+  url_settings?: { auth: "public" | "sprite" };
+  created_at?: string;
+  updated_at?: string;
+  last_started_at?: string | null;
+  last_active_at?: string | null;
+}
+
+export interface ListSpritesResponse {
+  sprites: Sprite[];
+  has_more: boolean;
+  next_continuation_token?: string | null;
+}
+
+export interface Checkpoint {
+  id: string;
+  comment?: string | null;
+  created_at?: string;
+}
+
+function authHeaders(): Record<string, string> {
+  const cfg = getConfig();
+  if (!cfg.spriteToken) {
+    throw new ApiError(
+      500,
+      "server_error",
+      "SPRITE_TOKEN is not configured (set env var or settings.sprite_token)",
+    );
+  }
+  return { Authorization: `Bearer ${cfg.spriteToken}` };
+}
+
+function api(): string {
+  return getConfig().spriteApi.replace(/\/+$/, "");
+}
+
+function signalFor(timeoutMs?: number): AbortSignal | undefined {
+  const t = timeoutMs ?? getConfig().spriteTimeoutMs;
+  if (!t) return undefined;
+  return AbortSignal.timeout(t);
+}
+
+async function handleJson<T>(res: Response, op: string): Promise<T> {
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new ApiError(
+      res.status >= 500 ? 502 : 500,
+      "server_error",
+      `sprites.dev ${op} failed (${res.status}): ${text.slice(0, 500)}`,
+    );
+  }
+  return (await res.json()) as T;
+}
+
+async function consumeNdjsonProgress(res: Response, op: string): Promise<void> {
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new ApiError(
+      res.status >= 500 ? 502 : 500,
+      "server_error",
+      `sprites.dev ${op} failed (${res.status}): ${text.slice(0, 500)}`,
+    );
+  }
+  if (!res.body) return;
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    let nl = buf.indexOf("\n");
+    while (nl !== -1) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      nl = buf.indexOf("\n");
+      if (!line) continue;
+      try {
+        const evt = JSON.parse(line) as { type?: string; message?: string; error?: string };
+        if (evt.type === "error") {
+          throw new ApiError(502, "server_error", `${op}: ${evt.message || evt.error || "error"}`);
+        }
+      } catch (err) {
+        if (err instanceof ApiError) throw err;
+        // ignore non-JSON progress lines
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Sprite CRUD
+// ---------------------------------------------------------------------------
+
+export async function createSprite(input: {
+  name: string;
+  wait_for_capacity?: boolean;
+  url_settings?: { auth?: "public" | "sprite" };
+}): Promise<Sprite> {
+  const res = await fetch(`${api()}/v1/sprites`, {
+    method: "POST",
+    headers: { ...authHeaders(), "content-type": "application/json" },
+    body: JSON.stringify(input),
+    signal: signalFor(),
+  });
+  return handleJson<Sprite>(res, "createSprite");
+}
+
+export async function getSprite(name: string): Promise<Sprite | null> {
+  const res = await fetch(
+    `${api()}/v1/sprites/${encodeURIComponent(name)}`,
+    { headers: authHeaders(), signal: signalFor() },
+  );
+  if (res.status === 404) return null;
+  return handleJson<Sprite>(res, "getSprite");
+}
+
+export async function deleteSprite(name: string): Promise<void> {
+  const res = await fetch(
+    `${api()}/v1/sprites/${encodeURIComponent(name)}`,
+    { method: "DELETE", headers: authHeaders(), signal: signalFor() },
+  );
+  if (!res.ok && res.status !== 404) {
+    const text = await res.text().catch(() => "");
+    throw new ApiError(502, "server_error", `deleteSprite: ${res.status} ${text.slice(0, 200)}`);
+  }
+}
+
+export async function listSprites(opts: {
+  prefix?: string;
+  max_results?: number;
+  continuation_token?: string;
+} = {}): Promise<ListSpritesResponse> {
+  const params = new URLSearchParams();
+  if (opts.prefix) params.set("prefix", opts.prefix);
+  if (opts.max_results != null) params.set("max_results", String(opts.max_results));
+  if (opts.continuation_token) params.set("continuation_token", opts.continuation_token);
+  const res = await fetch(
+    `${api()}/v1/sprites?${params.toString()}`,
+    { headers: authHeaders(), signal: signalFor() },
+  );
+  return handleJson<ListSpritesResponse>(res, "listSprites");
+}
+
+// ---------------------------------------------------------------------------
+// Checkpoints
+// ---------------------------------------------------------------------------
+
+export async function createCheckpoint(name: string, comment?: string): Promise<Checkpoint> {
+  // create returns streaming NDJSON progress; the final message carries the id.
+  const res = await fetch(
+    `${api()}/v1/sprites/${encodeURIComponent(name)}/checkpoint`,
+    {
+      method: "POST",
+      headers: { ...authHeaders(), "content-type": "application/json" },
+      body: JSON.stringify({ comment: comment ?? null }),
+      signal: signalFor(getConfig().agentTimeoutMs),
+    },
+  );
+  if (!res.ok || !res.body) {
+    const text = await res.text().catch(() => "");
+    throw new ApiError(502, "server_error", `createCheckpoint: ${res.status} ${text.slice(0, 200)}`);
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  let id: string | null = null;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    let nl = buf.indexOf("\n");
+    while (nl !== -1) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      nl = buf.indexOf("\n");
+      if (!line) continue;
+      try {
+        const evt = JSON.parse(line) as {
+          type?: string;
+          data?: string;
+          message?: string;
+          checkpoint_id?: string;
+          id?: string;
+        };
+        if (evt.type === "error") {
+          throw new ApiError(502, "server_error", `createCheckpoint: ${evt.data || evt.message || "error"}`);
+        }
+        // The API embeds the checkpoint ID in multiple places:
+        //   - complete event: "Checkpoint v1 created successfully"
+        //   - info event: "  ID: v1"
+        // Try structured fields first, then parse from data strings.
+        if (evt.checkpoint_id || evt.id) {
+          id = evt.checkpoint_id || evt.id || null;
+        }
+        if (!id && evt.type === "info" && evt.data) {
+          const idMatch = evt.data.match(/^\s*ID:\s*(.+)$/);
+          if (idMatch) id = idMatch[1].trim();
+        }
+        if (!id && evt.type === "complete" && evt.data) {
+          const ckptMatch = evt.data.match(/Checkpoint\s+(\S+)/);
+          if (ckptMatch) id = ckptMatch[1];
+        }
+      } catch (err) {
+        if (err instanceof ApiError) throw err;
+        // ignore non-JSON
+      }
+    }
+  }
+  if (!id) {
+    throw new ApiError(502, "server_error", "createCheckpoint: no checkpoint id in progress stream");
+  }
+  return { id };
+}
+
+export async function restoreCheckpoint(name: string, checkpointId: string): Promise<void> {
+  const res = await fetch(
+    `${api()}/v1/sprites/${encodeURIComponent(name)}/checkpoints/${encodeURIComponent(checkpointId)}/restore`,
+    {
+      method: "POST",
+      headers: authHeaders(),
+      signal: signalFor(getConfig().agentTimeoutMs),
+    },
+  );
+  await consumeNdjsonProgress(res, "restoreCheckpoint");
+}
+
+// ---------------------------------------------------------------------------
+// Exec (HTTP variant — for one-shot setup commands only)
+// ---------------------------------------------------------------------------
+
+/**
+ * HTTP POST exec variant. Suitable only for non-streaming, non-interruptible
+ * operations like setup-script execution. For normal turns and anything that
+ * might be killed, use `lib/sprite/exec.ts` (WebSocket) instead.
+ */
+export async function httpExec(
+  name: string,
+  argv: string[],
+  opts: { stdin?: string; timeoutMs?: number } = {},
+): Promise<{ stdout: string; stderr: string; exit_code: number }> {
+  const params = new URLSearchParams();
+  for (const c of argv) params.append("cmd", c);
+  if (opts.stdin != null) params.set("stdin", "true");
+  const res = await fetch(
+    `${api()}/v1/sprites/${encodeURIComponent(name)}/exec?${params.toString()}`,
+    {
+      method: "POST",
+      headers: authHeaders(),
+      body: opts.stdin ?? undefined,
+      signal: signalFor(opts.timeoutMs ?? getConfig().agentTimeoutMs),
+    },
+  );
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new ApiError(502, "server_error", `httpExec: ${res.status} ${text.slice(0, 300)}`);
+  }
+  const ct = res.headers.get("content-type") || "";
+  if (ct.includes("application/json")) {
+    return (await res.json()) as { stdout: string; stderr: string; exit_code: number };
+  }
+  const text = await res.text();
+  return { stdout: text, stderr: "", exit_code: 0 };
+}
+
+export async function killExecSession(spriteName: string, execSessionId: string): Promise<void> {
+  const res = await fetch(
+    `${api()}/v1/sprites/${encodeURIComponent(spriteName)}/exec/${encodeURIComponent(execSessionId)}/kill`,
+    { method: "POST", headers: authHeaders(), signal: signalFor() },
+  );
+  if (!res.ok && res.status !== 404) {
+    const text = await res.text().catch(() => "");
+    throw new ApiError(502, "server_error", `killExecSession: ${res.status} ${text.slice(0, 200)}`);
+  }
+  // The kill endpoint also streams NDJSON progress; consume and discard.
+  await consumeNdjsonProgress(res, "killExecSession").catch(() => {});
+}

package/src/sprite/exec.ts

@@ -0,0 +1,161 @@
+/**
+ * sprites.dev exec client.
+ *
+ * HISTORY:
+ *   The plan called for WebSocket exec from M1 so we could use the
+ *   `POST /v1/sprites/{name}/exec/{session_id}/kill` endpoint for clean
+ *   interrupts. Spike S4 decoded the WS protocol (session_info JSON,
+ *   \x01-prefixed stdout frames, \x03 exit marker) but a follow-up probe
+ *   revealed that **WS stdin delivery does not work for processes that
+ *   read to EOF** — claude hangs indefinitely waiting for input even after
+ *   we send the stdin text frame, and no EOF-signaling mechanism we tried
+ *   (empty frame, \x04 EOT, JSON control, socket close) delivered stdin
+ *   cleanly. See /tmp/ca-ws-test2.mjs for the probe matrix.
+ *
+ *   HTTP POST exec handles stdin cleanly — the request body is the stdin
+ *   and the connection close signals EOF. So we use HTTP exec here, and
+ *   implement interrupt as an abort on the HTTP fetch. That gives us
+ *   clean *client-visible* semantics (session.status_idle{stop_reason:
+ *   interrupted} is emitted within milliseconds of the interrupt) even
+ *   though the sprite-side process may run to its natural completion.
+ *
+ *   If sprites.dev later publishes the WS stdin protocol or a kill-by-name
+ *   HTTP endpoint, the kill path can be upgraded without touching the
+ *   driver — it's all behind the ExecSession interface.
+ */
+import { getConfig } from "../config";
+import { ApiError } from "../errors";
+
+export interface ExecResult {
+  code: number;
+}
+
+export interface ExecSession {
+  /** Readable stream of raw stdout bytes (HTTP streaming body) */
+  stdout: ReadableStream<Uint8Array>;
+  /** Resolves when the exec finishes */
+  exit: Promise<ExecResult>;
+  /** Best-effort kill — aborts the HTTP fetch */
+  kill(): Promise<void>;
+  /** Server-issued exec session id (not available for HTTP exec) */
+  execSessionId?: string;
+}
+
+export interface ExecOptions {
+  argv: string[];
+  stdin?: string;
+  /** Signal that, when aborted, cancels the exec */
+  signal?: AbortSignal;
+  /** Timeout in ms for the whole exec (defaults to config.agentTimeoutMs) */
+  timeoutMs?: number;
+}
+
+function api(): string {
+  return getConfig().spriteApi.replace(/\/+$/, "");
+}
+
+function authHeaders(): Record<string, string> {
+  const cfg = getConfig();
+  if (!cfg.spriteToken) {
+    throw new ApiError(500, "server_error", "SPRITE_TOKEN is not configured");
+  }
+  return { Authorization: `Bearer ${cfg.spriteToken}` };
+}
+
+/**
+ * Start a streaming HTTP exec on a sprite. The `argv` becomes `?cmd=a&cmd=b...`
+ * query params; stdin (if any) is posted as the request body; the response
+ * body is the streamed stdout.
+ *
+ * When the AbortSignal fires, the underlying fetch is aborted — the HTTP
+ * connection closes from our side, which the driver treats as an interrupted
+ * turn. The sprite-side process is unaffected; it will finish naturally.
+ */
+export async function startExec(
+  spriteName: string,
+  opts: ExecOptions,
+): Promise<ExecSession> {
+  const params = new URLSearchParams();
+  for (const c of opts.argv) params.append("cmd", c);
+  if (opts.stdin != null) params.set("stdin", "true");
+
+  const localAbort = new AbortController();
+  const timeoutMs = opts.timeoutMs ?? getConfig().agentTimeoutMs;
+  const timeoutId = setTimeout(
+    () => localAbort.abort(new DOMException("exec timeout", "AbortError")),
+    timeoutMs,
+  );
+
+  // Link caller's signal to our internal abort
+  if (opts.signal) {
+    if (opts.signal.aborted) localAbort.abort(opts.signal.reason);
+    else opts.signal.addEventListener("abort", () => localAbort.abort(opts.signal!.reason));
+  }
+
+  const res = await fetch(
+    `${api()}/v1/sprites/${encodeURIComponent(spriteName)}/exec?${params.toString()}`,
+    {
+      method: "POST",
+      headers: authHeaders(),
+      body: opts.stdin ?? undefined,
+      signal: localAbort.signal,
+    },
+  );
+
+  if (!res.ok) {
+    clearTimeout(timeoutId);
+    const text = await res.text().catch(() => "");
+    throw new ApiError(
+      502,
+      "server_error",
+      `sprite exec failed (${res.status}): ${text.slice(0, 300)}`,
+    );
+  }
+  if (!res.body) {
+    clearTimeout(timeoutId);
+    throw new ApiError(502, "server_error", "sprite exec returned no body");
+  }
+
+  let exitResolve: (v: ExecResult) => void = () => {};
+  let exitReject: (e: unknown) => void = () => {};
+  const exit = new Promise<ExecResult>((resolve, reject) => {
+    exitResolve = resolve;
+    exitReject = reject;
+  });
+
+  // Tee the body: one side goes to the consumer, the other is a watcher that
+  // resolves `exit` when the stream ends or rejects on abort.
+  const [consumerStream, watchStream] = res.body.tee();
+
+  (async () => {
+    const reader = watchStream.getReader();
+    try {
+      for (;;) {
+        const { done } = await reader.read();
+        if (done) break;
+      }
+      exitResolve({ code: 0 });
+    } catch (err) {
+      if (localAbort.signal.aborted) {
+        exitReject(new DOMException("aborted", "AbortError"));
+      } else {
+        exitReject(err);
+      }
+    } finally {
+      clearTimeout(timeoutId);
+      try {
+        reader.releaseLock();
+      } catch {
+        /* ignore */
+      }
+    }
+  })();
+
+  return {
+    stdout: consumerStream,
+    exit,
+    async kill() {
+      localAbort.abort(new DOMException("killed", "AbortError"));
+    },
+  };
+}