@tai42/api-client 0.1.0

package/src/sse.ts

@@ -0,0 +1,90 @@
+/**
+ * A manual SSE frame parser over `fetch` + `ReadableStream` — never the
+ * `EventSource` API, which cannot send the auth header. Handles frames
+ * split across stream chunks and multi-line `data:` fields.
+ */
+export interface SseFrame {
+  readonly event: string;
+  /** The concatenated `data:` lines (joined by "\n"). */
+  readonly data: string;
+}
+
+/**
+ * Incrementally parse SSE text. Feed it chunks; it yields complete frames and
+ * retains any partial trailing frame across calls. A frame ends on a blank line.
+ */
+export class SseFrameParser {
+  private buffer = '';
+
+  /** Push a decoded text chunk; return every complete frame it now contains. */
+  push(chunk: string): SseFrame[] {
+    this.buffer += chunk;
+    const frames: SseFrame[] = [];
+    let sep = this.findSeparator();
+    while (sep !== -1) {
+      const raw = this.buffer.slice(0, sep.index);
+      this.buffer = this.buffer.slice(sep.index + sep.length);
+      const frame = parseFrame(raw);
+      if (frame) frames.push(frame);
+      sep = this.findSeparator();
+    }
+    return frames;
+  }
+
+  private findSeparator(): { index: number; length: number } | -1 {
+    const lf = this.buffer.indexOf('\n\n');
+    const crlf = this.buffer.indexOf('\r\n\r\n');
+    if (crlf !== -1 && (lf === -1 || crlf < lf)) return { index: crlf, length: 4 };
+    if (lf !== -1) return { index: lf, length: 2 };
+    return -1;
+  }
+}
+
+function parseFrame(raw: string): SseFrame | null {
+  let event = 'message';
+  const dataLines: string[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.startsWith(':')) continue; // comment
+    const colon = line.indexOf(':');
+    const field = colon === -1 ? line : line.slice(0, colon);
+    // A single leading space after the colon is stripped per the SSE spec.
+    let value = colon === -1 ? '' : line.slice(colon + 1);
+    if (value.startsWith(' ')) value = value.slice(1);
+    if (field === 'event') event = value;
+    else if (field === 'data') dataLines.push(value);
+  }
+  if (dataLines.length === 0 && event === 'message') return null;
+  return { event, data: dataLines.join('\n') };
+}
+
+/**
+ * Consume an authed SSE endpoint as an async iterator of frames. The caller
+ * supplies the fetch (with the auth header + abort signal) and handles
+ * reconnect/backlog-replay semantics.
+ */
+export async function* readSseFrames(
+  response: Response,
+  signal?: AbortSignal,
+): AsyncGenerator<SseFrame> {
+  if (!response.body) throw new Error('SSE response has no body');
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const parser = new SseFrameParser();
+  try {
+    for (;;) {
+      // An abort is a loud termination, never a silent iterator end: surface the
+      // signal's AbortError so the caller can tell a cancelled stream apart from a
+      // clean close. This matches fetch/ReadableStream, which reject an in-flight
+      // read on abort; the caller's own abort guard swallows it where cancellation
+      // is the expected outcome.
+      signal?.throwIfAborted();
+      const { value, done } = await reader.read();
+      if (done) break;
+      for (const frame of parser.push(decoder.decode(value, { stream: true }))) {
+        yield frame;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/tool-runs.ts

@@ -0,0 +1,103 @@
+/**
+ * Background tool-runs transport — the `/api/tool-runs*` surface.
+ *
+ * This is a SELF-CONTAINED api-client module (its own zod, not the shared
+ * `schemas.ts`), so the tools feature owns these wire types end to end. The
+ * `createApiClient` object wires three thin methods onto it (`submitToolRun`,
+ * `getToolRun`, `listToolRuns`) since only it holds the `ApiConfig` (base URL +
+ * auth token).
+ *
+ * The background surface detaches a run from its HTTP request: submit returns a
+ * `run_id` immediately (202), then the caller POLLS the single-run GET until the
+ * status is terminal (`succeeded | failed | lost`). The list GET returns the
+ * recent runs for one tool — id/status/timestamps only, never `result`/`error`.
+ */
+import { z } from 'zod';
+
+import { apiRequest, encodeSegment } from './http';
+import type { ApiConfig } from './http';
+
+/** A run's lifecycle state. `lost` = the server restarted mid-run; the result is
+ * unrecoverable. `running` is the only non-terminal state. */
+export const toolRunStatus = z.enum(['running', 'succeeded', 'failed', 'lost']);
+
+/** `POST /api/tool-runs` → the handle for the detached run. */
+export const toolRunSubmitResult = z.object({
+  run_id: z.string(),
+});
+
+/** `GET /api/tool-runs/{run_id}` → the full record. `result` is arbitrary JSON
+ * (present only on `succeeded`); `error` is present only on `failed`. */
+export const toolRunRecord = z.object({
+  run_id: z.string(),
+  tool_name: z.string(),
+  status: toolRunStatus,
+  started_at: z.string(),
+  finished_at: z.string().optional(),
+  result: z.unknown().optional(),
+  error: z.string().optional(),
+});
+
+/** One entry of `GET /api/tool-runs?tool_name=...` — id/status/timestamps only,
+ * deliberately carrying NO `result`/`error` (the list is not secret-bearing). */
+export const toolRunListItem = z.object({
+  run_id: z.string(),
+  tool_name: z.string(),
+  status: toolRunStatus,
+  started_at: z.string(),
+  finished_at: z.string().optional(),
+});
+
+export const toolRunList = z.array(toolRunListItem);
+
+export type ToolRunStatus = z.infer<typeof toolRunStatus>;
+export type ToolRunSubmitResult = z.infer<typeof toolRunSubmitResult>;
+export type ToolRunRecord = z.infer<typeof toolRunRecord>;
+export type ToolRunListItem = z.infer<typeof toolRunListItem>;
+
+/** Body for `POST /api/tool-runs`. */
+export interface SubmitToolRunArgs {
+  readonly tool_name: string;
+  readonly arguments?: Record<string, unknown>;
+}
+
+/** Submit a tool for detached background execution; resolves with its `run_id`. */
+export function submitToolRun(
+  config: ApiConfig,
+  args: SubmitToolRunArgs,
+  signal?: AbortSignal,
+): Promise<ToolRunSubmitResult> {
+  return apiRequest(config, '/api/tool-runs', toolRunSubmitResult, {
+    method: 'POST',
+    body: { tool_name: args.tool_name, arguments: args.arguments ?? {} },
+    signal,
+  });
+}
+
+/** Read one background run's current record (the poll target). */
+export function getToolRun(
+  config: ApiConfig,
+  runId: string,
+  signal?: AbortSignal,
+): Promise<ToolRunRecord> {
+  return apiRequest(config, `/api/tool-runs/${encodeSegment(runId)}`, toolRunRecord, {
+    signal,
+  });
+}
+
+/** List the recent background runs for one tool (newest first). */
+export function listToolRuns(
+  config: ApiConfig,
+  toolName: string,
+  signal?: AbortSignal,
+): Promise<ToolRunListItem[]> {
+  return apiRequest(config, '/api/tool-runs', toolRunList, {
+    query: { tool_name: toolName },
+    signal,
+  });
+}
+
+/** Whether a run has reached a terminal state (polling stops here). */
+export function isTerminalRunStatus(status: ToolRunStatus): boolean {
+  return status !== 'running';
+}