@tai42/api-client 0.1.0

package/dist/agents.js

@@ -0,0 +1,200 @@
+/**
+ * The agents transport: the `GET /api/agents` list schema and the
+ * `POST /api/agents/{name}/runs` streaming run, plus the zod discriminated union
+ * over the agent `StreamEvent` taxonomy.
+ *
+ * This is a SELF-CONTAINED api-client module (its own zod, not the shared
+ * `schemas.ts`), so the agents feature owns its wire types end to end. The
+ * `createApiClient` object wires two thin methods onto it (`listAgents`,
+ * `streamAgentRun`) since only it holds the `ApiConfig` (base URL + auth token).
+ *
+ * Frame discriminator: every event carries a stable `type`, which is also the
+ * client's switch. A frame whose `type` is unknown (a newer server event) is
+ * NEVER dropped — it is surfaced as an `unknown` parsed event so the UI can show
+ * it verbatim; a malformed frame is surfaced the same way rather than crashing
+ * the stream.
+ */
+import { z } from 'zod';
+import { ApiError, ApiUnauthorizedError } from './errors';
+import { encodeSegment, extractError } from './http';
+import { SseFrameParser, readSseFrames } from './sse';
+// -- list schema -------------------------------------------------------------
+/** One registered agent as `GET /api/agents` returns it. */
+export const agentSummary = z.object({
+    name: z.string(),
+    description: z.string().default(''),
+    tool_name: z.string(),
+    // The agent's `ToolInput` JSON schema (the same schema its run tool exposes).
+    input_schema: z.record(z.unknown()).default({}),
+    // The agent's own authorability marker (read, never inferred): `true` means its
+    // `ToolInput` accepts the composable spec fields and it can be authored into a
+    // versioned agent. A code role-agent reports `false`. The same item shape is
+    // returned by `GET /api/agents/spec-runnable`, filtered to the `true` rows.
+    spec_runnable: z.boolean().default(false),
+});
+export const agentList = z.object({
+    items: z.array(agentSummary),
+    total: z.number(),
+});
+// -- event union (mirrors the contract StreamEvent taxonomy) -----------------
+const reasoningStep = z.object({
+    type: z.literal('reasoning_step'),
+    final: z.boolean().default(false),
+    text: z.string(),
+});
+const toolCallStep = z.object({
+    type: z.literal('tool_call_step'),
+    final: z.boolean().default(false),
+    tool: z.string(),
+    args: z.record(z.unknown()).default({}),
+    call_id: z.string(),
+});
+const toolResultStep = z.object({
+    type: z.literal('tool_result_step'),
+    final: z.boolean().default(false),
+    tool: z.string(),
+    call_id: z.string(),
+    result: z.unknown(),
+    is_error: z.boolean().default(false),
+});
+const messageDelta = z.object({
+    type: z.literal('message_delta'),
+    final: z.boolean().default(false),
+    text: z.string(),
+});
+const messageFinal = z.object({
+    type: z.literal('message_final'),
+    final: z.boolean().default(true),
+    text: z.string(),
+});
+const runUsage = z.object({
+    type: z.literal('run_usage'),
+    final: z.boolean().default(false),
+    input_tokens: z.number().nullable().default(null),
+    output_tokens: z.number().nullable().default(null),
+    total_tokens: z.number().nullable().default(null),
+    model: z.string().nullable().default(null),
+});
+const structuredFinal = z.object({
+    type: z.literal('structured_final'),
+    final: z.boolean().default(true),
+    data: z.unknown(),
+});
+const interruptFinal = z.object({
+    type: z.literal('interrupt_final'),
+    final: z.boolean().default(true),
+    interrupt_id: z.string(),
+    payload: z.unknown(),
+    reason: z.string().nullable().default(null),
+});
+// The two SSE-layer terminal frames the run route emits (not contract events).
+const streamEnd = z.object({ type: z.literal('stream.end') });
+const streamError = z.object({ type: z.literal('stream.error'), message: z.string() });
+/** The discriminated union of every KNOWN agent frame. */
+export const agentEventSchema = z.discriminatedUnion('type', [
+    reasoningStep,
+    toolCallStep,
+    toolResultStep,
+    messageDelta,
+    messageFinal,
+    runUsage,
+    structuredFinal,
+    interruptFinal,
+    streamEnd,
+    streamError,
+]);
+/**
+ * Parse one SSE frame's `data` into a typed event. Unparseable JSON, a
+ * non-object payload, an unknown `type`, or a payload that fails its schema all
+ * resolve to an `unknown` fallback (visible, never silently skipped) rather than
+ * throwing and tearing down the stream.
+ */
+export function parseAgentFrame(frame) {
+    let payload;
+    try {
+        payload = JSON.parse(frame.data);
+    }
+    catch {
+        return { known: false, unknown: { type: '(unparseable)', raw: frame.data } };
+    }
+    const result = agentEventSchema.safeParse(payload);
+    if (result.success)
+        return { known: true, event: result.data };
+    const rawType = typeof payload === 'object' &&
+        payload !== null &&
+        typeof payload.type === 'string'
+        ? payload.type
+        : '(unknown)';
+    return { known: false, unknown: { type: rawType, raw: payload } };
+}
+// -- streaming run -----------------------------------------------------------
+async function* parseFrames(frames) {
+    for await (const frame of frames) {
+        yield parseAgentFrame(frame);
+    }
+}
+/**
+ * Open an authed agent-run SSE stream over `fetch` + `ReadableStream` (never
+ * `EventSource`, which cannot send the auth header). The POST body is the run
+ * input; a non-2xx open throws loudly (a body that parsed to zero frames would
+ * otherwise look like a silently-empty run). Aborting `signal` closes the stream,
+ * which the server treats as a disconnect and cancels the run. The path is the
+ * ONLY difference between a plain-agent run and an authored-agent run, so both
+ * faces share this opener.
+ */
+async function openAgentStream(config, path, input, signal) {
+    const doFetch = config.fetch ?? globalThis.fetch;
+    const token = config.getToken();
+    const headers = {
+        accept: 'text/event-stream',
+        'content-type': 'application/json',
+    };
+    if (token)
+        headers['x-api-key'] = token;
+    const response = await doFetch(`${config.baseUrl ?? ''}${path}`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(input),
+        signal,
+    });
+    if (response.status === 401)
+        throw new ApiUnauthorizedError();
+    if (!response.ok) {
+        // Read the `{ "error" }` envelope so a load-bearing server message (e.g. an
+        // authored-run "cannot override the fixed field ..." 400) surfaces verbatim
+        // instead of collapsing to the bare status text. Both run doors share this
+        // opener, so both surface the server's message.
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            throw new ApiError(response.statusText || 'agent run failed', response.status);
+        }
+        const { message, code } = extractError(payload);
+        throw new ApiError(message ?? (response.statusText || 'agent run failed'), response.status, code);
+    }
+    return parseFrames(readSseFrames(response, signal));
+}
+/** Stream a plain registered agent's run (`POST /api/agents/{name}/runs`). */
+export async function streamAgentRun(config, name, input, signal) {
+    return openAgentStream(config, `/api/agents/${encodeSegment(name)}/runs`, input, signal);
+}
+/**
+ * Stream an AUTHORED agent's run (`POST /api/agents/authored/{name}/runs`). Same
+ * SSE framing as `streamAgentRun`; the baked spec is resolved server-side, so the
+ * POST body carries ONLY the non-baked `ToolInput` fields (the actual query/user
+ * input). Naming a baked field is a loud server 400, surfaced by the caller.
+ */
+export async function streamAuthoredAgentRun(config, name, input, signal) {
+    return openAgentStream(config, `/api/agents/authored/${encodeSegment(name)}/runs`, input, signal);
+}
+/**
+ * Parse a whole hand-authored SSE transcript into its ordered parsed events.
+ * Reuses the wire `SseFrameParser`, so a test fixture exercises the real
+ * frame-splitting + event-parsing path end to end.
+ */
+export function parseAgentTranscript(transcript) {
+    return new SseFrameParser().push(transcript).map(parseAgentFrame);
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}