@meistrari/agent-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+UNLICENSED
+
+Copyright (c) Meistrari.
+
+This package is proprietary. No license is granted to use, copy, modify, publish,
+distribute, sublicense, or sell this package except under a separate written agreement
+with Meistrari.

package/README.md

@@ -0,0 +1,68 @@
+# @meistrari/agent-sdk
+
+A small, publishable client for the **agent-api** sandbox execution path. It owns the
+HTTP contract so consumers (tela, chat-app, tela-dock) don't re-implement the execute
+request, the SSE session parser, and `vault://` reference resolution by hand.
+
+## Install
+
+```bash
+bun add @meistrari/agent-sdk
+```
+
+## Usage
+
+```ts
+import { agentClient, DataTokenAuthStrategy } from '@meistrari/agent-sdk'
+
+const client = agentClient({
+    baseUrl: 'https://agent-api.example.com',
+    authStrategy: new DataTokenAuthStrategy(dataToken),
+    vaultUrl: 'https://vault.example.com', // required only for resolveReference
+})
+
+// 1) Execute an agent
+const { success, sessionId, error } = await client.executeAgent({
+    organizationName: 'acme',
+    repository: 'support-bot',
+    message: 'Summarize the latest tickets',
+    inputs: [{ vaultRef: 'vault://...', filename: 'tickets.csv' }],
+})
+
+// 2) Consume the session as a typed async-iterable.
+//    The server already inlines step/result Vault bytes into the stream.
+if (success && sessionId) {
+    for await (const event of client.streamSession(sessionId, { signal })) {
+        switch (event.kind) {
+            case 'status': // pending | running | completed | failed | waiting_messages | cancelled
+                break
+            case 'steps': // live step tail
+                break
+            case 'result': // final accumulated result
+                break
+            case 'error':
+                throw new Error(event.error)
+        }
+    }
+}
+
+// 3) Resolve a vault:// reference (e.g. an output file ref found in a result)
+const bytes = await client.resolveReference('vault://...')
+const stream = await client.resolveReference('vault://...', { as: 'stream' })
+const json = await client.resolveReference<MyShape>('vault://...', { as: 'json' })
+```
+
+## Auth
+
+`DataTokenAuthStrategy` sends `x-data-token` — accepted by both agent-api and Vault, so a
+single strategy covers `executeAgent`/`streamSession` and `resolveReference`.
+`APIKeyAuthStrategy` sends `Authorization: Bearer <apiKey>` for agent-api-only use.
+
+## License
+
+This package mirrors `@meistrari/vault-sdk` and is published as `UNLICENSED`.
+
+## Scope
+
+Focused on sandbox execution: `executeAgent`, `streamSession`, and `resolveReference`.
+Agent CRUD, legacy polling, and timelines are intentionally out of scope.

package/dist/index.cjs

@@ -0,0 +1,316 @@
+'use strict';
+
+const vaultSdk = require('@meistrari/vault-sdk');
+const zod = require('zod');
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class DataTokenAuthStrategy {
+  constructor(dataToken) {
+    __publicField(this, "dataToken");
+    this.dataToken = dataToken;
+  }
+  getHeaders() {
+    return new Headers({
+      "x-data-token": this.dataToken
+    });
+  }
+}
+class APIKeyAuthStrategy {
+  constructor(apiKey) {
+    __publicField(this, "apiKey");
+    this.apiKey = apiKey;
+  }
+  getHeaders() {
+    return new Headers({
+      Authorization: `Bearer ${this.apiKey}`
+    });
+  }
+}
+
+class FetchError extends Error {
+  constructor(message, url, method, response) {
+    super(message);
+    this.message = message;
+    this.url = url;
+    this.method = method;
+    this.response = response;
+    this.name = "FetchError";
+  }
+  static async from(url, method, response) {
+    const jsonResponse = response.clone();
+    const textResponse = response.clone();
+    const text = await jsonResponse.json().then((json) => JSON.stringify(json, null, 2)).catch(() => textResponse.text());
+    return new FetchError(
+      `Failed to ${method} ${url}: ${response.status} ${response.statusText}:
+${text}`,
+      url,
+      method,
+      response
+    );
+  }
+}
+
+const sessionStatusSchema = zod.z.enum([
+  "pending",
+  "running",
+  "completed",
+  "failed",
+  "waiting_messages",
+  "cancelled"
+]);
+const vaultReferenceSchema = zod.z.string().regex(/^vault:\/\/\S+$/, "vaultRef must start with vault:// and cannot contain whitespace");
+const agentInputSchema = zod.z.object({
+  vaultRef: vaultReferenceSchema,
+  filename: zod.z.string().min(1, "Filename is required").max(255, "Filename must be 255 characters or less"),
+  metadata: zod.z.string().max(16384, "Metadata must be 16,384 characters or less").optional()
+}).strict();
+const executeAgentRequestSchema = zod.z.object({
+  sessionId: zod.z.string().uuid().optional(),
+  organizationName: zod.z.string().min(1).max(200).optional(),
+  repository: zod.z.string().min(1).max(200).optional(),
+  ref: zod.z.string().max(200).optional(),
+  message: zod.z.string().min(1).max(8e5).optional(),
+  inputs: zod.z.array(agentInputSchema).optional(),
+  environmentVariables: zod.z.record(zod.z.string(), zod.z.string()).optional(),
+  recover: zod.z.boolean().optional()
+}).strict().superRefine((data, ctx) => {
+  if (!data.sessionId) {
+    if (!data.organizationName) {
+      ctx.addIssue({ code: "custom", message: "organizationName is required for new sessions", path: ["organizationName"] });
+    }
+    if (!data.repository) {
+      ctx.addIssue({ code: "custom", message: "repository is required for new sessions", path: ["repository"] });
+    }
+    if (!data.message) {
+      ctx.addIssue({ code: "custom", message: "message is required for new sessions", path: ["message"] });
+    }
+  }
+  if (data.recover && !data.sessionId) {
+    ctx.addIssue({ code: "custom", message: "sessionId is required when recover is true", path: ["sessionId"] });
+  }
+});
+const executeAgentResponseSchema = zod.z.object({
+  success: zod.z.boolean(),
+  sessionId: zod.z.string().optional(),
+  error: zod.z.string().optional()
+});
+const sessionStatusEventSchema = zod.z.object({
+  kind: zod.z.literal("status"),
+  sessionId: zod.z.string(),
+  status: sessionStatusSchema,
+  error: zod.z.string().optional(),
+  createdAt: zod.z.number(),
+  updatedAt: zod.z.number()
+});
+const sessionStepsEventSchema = zod.z.object({
+  kind: zod.z.literal("steps"),
+  sessionId: zod.z.string(),
+  status: sessionStatusSchema,
+  steps: zod.z.array(zod.z.record(zod.z.string(), zod.z.unknown())),
+  nextCursor: zod.z.number().nullable(),
+  createdAt: zod.z.number(),
+  updatedAt: zod.z.number()
+});
+const sessionResultEventSchema = zod.z.object({
+  kind: zod.z.literal("result"),
+  sessionId: zod.z.string(),
+  status: zod.z.enum(["completed", "waiting_messages"]),
+  result: zod.z.record(zod.z.string(), zod.z.unknown()),
+  nextCursor: zod.z.number().nullable(),
+  createdAt: zod.z.number(),
+  updatedAt: zod.z.number()
+});
+const sessionErrorEventSchema = zod.z.object({
+  kind: zod.z.literal("error"),
+  sessionId: zod.z.string(),
+  error: zod.z.string()
+});
+const sessionStreamEventSchema = zod.z.discriminatedUnion("kind", [
+  sessionStatusEventSchema,
+  sessionStepsEventSchema,
+  sessionResultEventSchema,
+  sessionErrorEventSchema
+]);
+const SESSION_STREAM_EVENT_KINDS = /* @__PURE__ */ new Set(["status", "steps", "result", "error"]);
+
+function normalizeStreamBuffer(buffer) {
+  return buffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function isControlPayload(data) {
+  return data === "[DONE]" || data === "Stream complete";
+}
+function parseSseFrame(frame) {
+  let data = "";
+  let hasData = false;
+  let lineStart = 0;
+  while (lineStart <= frame.length) {
+    const lineEnd = frame.indexOf("\n", lineStart);
+    const line = lineEnd === -1 ? frame.slice(lineStart) : frame.slice(lineStart, lineEnd);
+    lineStart = lineEnd === -1 ? frame.length + 1 : lineEnd + 1;
+    if (!line || line.startsWith(":"))
+      continue;
+    const separatorIndex = line.indexOf(":");
+    const field = separatorIndex === -1 ? line : line.slice(0, separatorIndex);
+    let value = separatorIndex === -1 ? "" : line.slice(separatorIndex + 1);
+    if (value.startsWith(" "))
+      value = value.slice(1);
+    if (field === "data") {
+      data = hasData ? `${data}
+${value}` : value;
+      hasData = true;
+    }
+  }
+  if (!hasData)
+    return void 0;
+  if (!data || isControlPayload(data))
+    return void 0;
+  try {
+    return JSON.parse(data);
+  } catch {
+    return void 0;
+  }
+}
+function getEventKind(event) {
+  if (!event || typeof event !== "object" || !("kind" in event))
+    return null;
+  const kind = event.kind;
+  return typeof kind === "string" ? kind : null;
+}
+function parseKnownEvent(event) {
+  const eventKind = getEventKind(event);
+  if (!eventKind || !SESSION_STREAM_EVENT_KINDS.has(eventKind))
+    return void 0;
+  const parsed = sessionStreamEventSchema.safeParse(event);
+  if (!parsed.success)
+    throw new Error(parsed.error.message);
+  return parsed.data;
+}
+async function* parseSessionStream(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  function* drainBuffer() {
+    let consumedIndex = 0;
+    while (true) {
+      const frameBoundary = buffer.indexOf("\n\n", consumedIndex);
+      if (frameBoundary === -1)
+        break;
+      const event = parseSseFrame(buffer.slice(consumedIndex, frameBoundary));
+      consumedIndex = frameBoundary + 2;
+      if (event === void 0)
+        continue;
+      const parsed = parseKnownEvent(event);
+      if (parsed)
+        yield parsed;
+    }
+    if (consumedIndex > 0)
+      buffer = buffer.slice(consumedIndex);
+  }
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      buffer += normalizeStreamBuffer(decoder.decode(value, { stream: true }));
+      yield* drainBuffer();
+    }
+    buffer += normalizeStreamBuffer(decoder.decode());
+    if (buffer.trim()) {
+      const event = parseSseFrame(buffer);
+      if (event !== void 0) {
+        const parsed = parseKnownEvent(event);
+        if (parsed)
+          yield parsed;
+      }
+    }
+    buffer = "";
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function agentClient(config) {
+  const baseUrl = config.baseUrl.replace(/\/+$/, "");
+  async function request(params) {
+    const url = new URL(`${baseUrl}${params.path}`);
+    if (params.query) {
+      for (const [key, value] of Object.entries(params.query))
+        url.searchParams.set(key, value);
+    }
+    const headers = new Headers(config.authStrategy.getHeaders());
+    headers.set("Accept", params.accept ?? "application/json");
+    if (params.body !== void 0)
+      headers.set("Content-Type", "application/json");
+    const response = await fetch(url, {
+      method: params.method,
+      headers,
+      body: params.body !== void 0 ? JSON.stringify(params.body) : void 0,
+      signal: params.signal
+    });
+    if (!response.ok)
+      throw await FetchError.from(url.toString(), params.method, response);
+    return response;
+  }
+  async function executeAgent(input) {
+    const body = executeAgentRequestSchema.parse(input);
+    const response = await request({
+      method: "POST",
+      path: "/v4/agents/execute",
+      body
+    });
+    return executeAgentResponseSchema.parse(await response.json());
+  }
+  async function streamSession(sessionId, options) {
+    const response = await request({
+      method: "GET",
+      path: `/v4/sessions/${encodeURIComponent(sessionId)}`,
+      query: options?.cursor !== void 0 ? { cursor: String(options.cursor) } : void 0,
+      accept: "text/event-stream, application/json",
+      signal: options?.signal
+    });
+    if (!response.body)
+      throw new Error("Agent session stream response body is missing");
+    return parseSessionStream(response.body);
+  }
+  async function resolveReference(reference, options) {
+    if (!config.vaultUrl)
+      throw new Error("vaultUrl is required in AgentClientConfig to resolve references");
+    if (!reference.startsWith("vault://"))
+      throw new Error(`Unsupported vault reference: ${reference}`);
+    const vaultConfig = { vaultUrl: config.vaultUrl, authStrategy: config.authStrategy };
+    const as = options?.as ?? "bytes";
+    if (as === "stream") {
+      const vaultFile2 = await vaultSdk.VaultFile.fromVaultReference(
+        { reference, config: vaultConfig, download: false },
+        { signal: options?.signal }
+      );
+      return vaultFile2.downloadStream({ signal: options?.signal });
+    }
+    const vaultFile = await vaultSdk.VaultFile.fromVaultReference(
+      { reference, config: vaultConfig, download: true },
+      { signal: options?.signal }
+    );
+    if (!vaultFile.content)
+      throw new Error(`Vault content missing for ${reference}`);
+    if (as === "json")
+      return JSON.parse(await vaultFile.content.text());
+    return vaultFile.content.arrayBuffer();
+  }
+  return { executeAgent, streamSession, resolveReference };
+}
+
+exports.APIKeyAuthStrategy = APIKeyAuthStrategy;
+exports.DataTokenAuthStrategy = DataTokenAuthStrategy;
+exports.FetchError = FetchError;
+exports.agentClient = agentClient;
+exports.agentInputSchema = agentInputSchema;
+exports.executeAgentRequestSchema = executeAgentRequestSchema;
+exports.executeAgentResponseSchema = executeAgentResponseSchema;
+exports.parseSessionStream = parseSessionStream;
+exports.sessionStatusSchema = sessionStatusSchema;
+exports.sessionStreamEventSchema = sessionStreamEventSchema;

package/dist/index.d.cts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+
+interface AuthStrategy {
+    getHeaders: () => Headers;
+}
+declare class DataTokenAuthStrategy implements AuthStrategy {
+    dataToken: string;
+    constructor(dataToken: string);
+    getHeaders(): Headers;
+}
+declare class APIKeyAuthStrategy implements AuthStrategy {
+    apiKey: string;
+    constructor(apiKey: string);
+    getHeaders(): Headers;
+}
+
+declare const sessionStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    waiting_messages: "waiting_messages";
+    cancelled: "cancelled";
+}>;
+type SessionStatus = z.infer<typeof sessionStatusSchema>;
+declare const agentInputSchema: z.ZodObject<{
+    vaultRef: z.ZodString;
+    filename: z.ZodString;
+    metadata: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type AgentInput = z.infer<typeof agentInputSchema>;
+declare const executeAgentRequestSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    organizationName: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        vaultRef: z.ZodString;
+        filename: z.ZodString;
+        metadata: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    recover: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+type ExecuteAgentRequest = z.infer<typeof executeAgentRequestSchema>;
+declare const executeAgentResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    sessionId: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ExecuteAgentResponse = z.infer<typeof executeAgentResponseSchema>;
+declare const sessionStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"status">;
+    sessionId: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        waiting_messages: "waiting_messages";
+        cancelled: "cancelled";
+    }>;
+    error: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"steps">;
+    sessionId: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        waiting_messages: "waiting_messages";
+        cancelled: "cancelled";
+    }>;
+    steps: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    nextCursor: z.ZodNullable<z.ZodNumber>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"result">;
+    sessionId: z.ZodString;
+    status: z.ZodEnum<{
+        completed: "completed";
+        waiting_messages: "waiting_messages";
+    }>;
+    result: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    nextCursor: z.ZodNullable<z.ZodNumber>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"error">;
+    sessionId: z.ZodString;
+    error: z.ZodString;
+}, z.core.$strip>], "kind">;
+type SessionStreamEvent = z.infer<typeof sessionStreamEventSchema>;
+
+interface AgentClientConfig {
+    baseUrl: string;
+    authStrategy: AuthStrategy;
+    vaultUrl?: string;
+}
+interface StreamSessionOptions {
+    cursor?: number;
+    signal?: AbortSignal;
+}
+type ResolveReferenceAs = 'bytes' | 'stream' | 'json';
+interface ResolveReferenceOptions {
+    as?: ResolveReferenceAs;
+    signal?: AbortSignal;
+}
+
+declare function agentClient(config: AgentClientConfig): {
+    executeAgent: (input: ExecuteAgentRequest) => Promise<ExecuteAgentResponse>;
+    streamSession: (sessionId: string, options?: StreamSessionOptions) => Promise<AsyncIterable<SessionStreamEvent>>;
+    resolveReference: {
+        (reference: string, options?: {
+            as?: "bytes";
+            signal?: AbortSignal;
+        }): Promise<ArrayBuffer>;
+        (reference: string, options: {
+            as: "stream";
+            signal?: AbortSignal;
+        }): Promise<ReadableStream<Uint8Array>>;
+        <T = unknown>(reference: string, options: {
+            as: "json";
+            signal?: AbortSignal;
+        }): Promise<T>;
+    };
+};
+type AgentClient = ReturnType<typeof agentClient>;
+
+declare class FetchError extends Error {
+    readonly message: string;
+    readonly url: string;
+    readonly method: string;
+    readonly response: Response;
+    constructor(message: string, url: string, method: string, response: Response);
+    static from(url: string, method: string, response: Response): Promise<FetchError>;
+}
+
+declare function parseSessionStream(stream: ReadableStream<Uint8Array>): AsyncIterable<SessionStreamEvent>;
+
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, agentClient, agentInputSchema, executeAgentRequestSchema, executeAgentResponseSchema, parseSessionStream, sessionStatusSchema, sessionStreamEventSchema };
+export type { AgentClient, AgentClientConfig, AgentInput, AuthStrategy, ExecuteAgentRequest, ExecuteAgentResponse, ResolveReferenceAs, ResolveReferenceOptions, SessionStatus, SessionStreamEvent, StreamSessionOptions };

package/dist/index.d.mts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+
+interface AuthStrategy {
+    getHeaders: () => Headers;
+}
+declare class DataTokenAuthStrategy implements AuthStrategy {
+    dataToken: string;
+    constructor(dataToken: string);
+    getHeaders(): Headers;
+}
+declare class APIKeyAuthStrategy implements AuthStrategy {
+    apiKey: string;
+    constructor(apiKey: string);
+    getHeaders(): Headers;
+}
+
+declare const sessionStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    waiting_messages: "waiting_messages";
+    cancelled: "cancelled";
+}>;
+type SessionStatus = z.infer<typeof sessionStatusSchema>;
+declare const agentInputSchema: z.ZodObject<{
+    vaultRef: z.ZodString;
+    filename: z.ZodString;
+    metadata: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type AgentInput = z.infer<typeof agentInputSchema>;
+declare const executeAgentRequestSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    organizationName: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        vaultRef: z.ZodString;
+        filename: z.ZodString;
+        metadata: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    recover: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+type ExecuteAgentRequest = z.infer<typeof executeAgentRequestSchema>;
+declare const executeAgentResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    sessionId: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ExecuteAgentResponse = z.infer<typeof executeAgentResponseSchema>;
+declare const sessionStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"status">;
+    sessionId: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        waiting_messages: "waiting_messages";
+        cancelled: "cancelled";
+    }>;
+    error: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"steps">;
+    sessionId: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        waiting_messages: "waiting_messages";
+        cancelled: "cancelled";
+    }>;
+    steps: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    nextCursor: z.ZodNullable<z.ZodNumber>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"result">;
+    sessionId: z.ZodString;
+    status: z.ZodEnum<{
+        completed: "completed";
+        waiting_messages: "waiting_messages";
+    }>;
+    result: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    nextCursor: z.ZodNullable<z.ZodNumber>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"error">;
+    sessionId: z.ZodString;
+    error: z.ZodString;
+}, z.core.$strip>], "kind">;
+type SessionStreamEvent = z.infer<typeof sessionStreamEventSchema>;
+
+interface AgentClientConfig {
+    baseUrl: string;
+    authStrategy: AuthStrategy;
+    vaultUrl?: string;
+}
+interface StreamSessionOptions {
+    cursor?: number;
+    signal?: AbortSignal;
+}
+type ResolveReferenceAs = 'bytes' | 'stream' | 'json';
+interface ResolveReferenceOptions {
+    as?: ResolveReferenceAs;
+    signal?: AbortSignal;
+}
+
+declare function agentClient(config: AgentClientConfig): {
+    executeAgent: (input: ExecuteAgentRequest) => Promise<ExecuteAgentResponse>;
+    streamSession: (sessionId: string, options?: StreamSessionOptions) => Promise<AsyncIterable<SessionStreamEvent>>;
+    resolveReference: {
+        (reference: string, options?: {
+            as?: "bytes";
+            signal?: AbortSignal;
+        }): Promise<ArrayBuffer>;
+        (reference: string, options: {
+            as: "stream";
+            signal?: AbortSignal;
+        }): Promise<ReadableStream<Uint8Array>>;
+        <T = unknown>(reference: string, options: {
+            as: "json";
+            signal?: AbortSignal;
+        }): Promise<T>;
+    };
+};
+type AgentClient = ReturnType<typeof agentClient>;
+
+declare class FetchError extends Error {
+    readonly message: string;
+    readonly url: string;
+    readonly method: string;
+    readonly response: Response;
+    constructor(message: string, url: string, method: string, response: Response);
+    static from(url: string, method: string, response: Response): Promise<FetchError>;
+}
+
+declare function parseSessionStream(stream: ReadableStream<Uint8Array>): AsyncIterable<SessionStreamEvent>;
+
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, agentClient, agentInputSchema, executeAgentRequestSchema, executeAgentResponseSchema, parseSessionStream, sessionStatusSchema, sessionStreamEventSchema };
+export type { AgentClient, AgentClientConfig, AgentInput, AuthStrategy, ExecuteAgentRequest, ExecuteAgentResponse, ResolveReferenceAs, ResolveReferenceOptions, SessionStatus, SessionStreamEvent, StreamSessionOptions };

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+
+interface AuthStrategy {
+    getHeaders: () => Headers;
+}
+declare class DataTokenAuthStrategy implements AuthStrategy {
+    dataToken: string;
+    constructor(dataToken: string);
+    getHeaders(): Headers;
+}
+declare class APIKeyAuthStrategy implements AuthStrategy {
+    apiKey: string;
+    constructor(apiKey: string);
+    getHeaders(): Headers;
+}
+
+declare const sessionStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    running: "running";
+    completed: "completed";
+    failed: "failed";
+    waiting_messages: "waiting_messages";
+    cancelled: "cancelled";
+}>;
+type SessionStatus = z.infer<typeof sessionStatusSchema>;
+declare const agentInputSchema: z.ZodObject<{
+    vaultRef: z.ZodString;
+    filename: z.ZodString;
+    metadata: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type AgentInput = z.infer<typeof agentInputSchema>;
+declare const executeAgentRequestSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    organizationName: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        vaultRef: z.ZodString;
+        filename: z.ZodString;
+        metadata: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    recover: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+type ExecuteAgentRequest = z.infer<typeof executeAgentRequestSchema>;
+declare const executeAgentResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    sessionId: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ExecuteAgentResponse = z.infer<typeof executeAgentResponseSchema>;
+declare const sessionStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"status">;
+    sessionId: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        waiting_messages: "waiting_messages";
+        cancelled: "cancelled";
+    }>;
+    error: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"steps">;
+    sessionId: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        waiting_messages: "waiting_messages";
+        cancelled: "cancelled";
+    }>;
+    steps: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    nextCursor: z.ZodNullable<z.ZodNumber>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"result">;
+    sessionId: z.ZodString;
+    status: z.ZodEnum<{
+        completed: "completed";
+        waiting_messages: "waiting_messages";
+    }>;
+    result: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    nextCursor: z.ZodNullable<z.ZodNumber>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"error">;
+    sessionId: z.ZodString;
+    error: z.ZodString;
+}, z.core.$strip>], "kind">;
+type SessionStreamEvent = z.infer<typeof sessionStreamEventSchema>;
+
+interface AgentClientConfig {
+    baseUrl: string;
+    authStrategy: AuthStrategy;
+    vaultUrl?: string;
+}
+interface StreamSessionOptions {
+    cursor?: number;
+    signal?: AbortSignal;
+}
+type ResolveReferenceAs = 'bytes' | 'stream' | 'json';
+interface ResolveReferenceOptions {
+    as?: ResolveReferenceAs;
+    signal?: AbortSignal;
+}
+
+declare function agentClient(config: AgentClientConfig): {
+    executeAgent: (input: ExecuteAgentRequest) => Promise<ExecuteAgentResponse>;
+    streamSession: (sessionId: string, options?: StreamSessionOptions) => Promise<AsyncIterable<SessionStreamEvent>>;
+    resolveReference: {
+        (reference: string, options?: {
+            as?: "bytes";
+            signal?: AbortSignal;
+        }): Promise<ArrayBuffer>;
+        (reference: string, options: {
+            as: "stream";
+            signal?: AbortSignal;
+        }): Promise<ReadableStream<Uint8Array>>;
+        <T = unknown>(reference: string, options: {
+            as: "json";
+            signal?: AbortSignal;
+        }): Promise<T>;
+    };
+};
+type AgentClient = ReturnType<typeof agentClient>;
+
+declare class FetchError extends Error {
+    readonly message: string;
+    readonly url: string;
+    readonly method: string;
+    readonly response: Response;
+    constructor(message: string, url: string, method: string, response: Response);
+    static from(url: string, method: string, response: Response): Promise<FetchError>;
+}
+
+declare function parseSessionStream(stream: ReadableStream<Uint8Array>): AsyncIterable<SessionStreamEvent>;
+
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, agentClient, agentInputSchema, executeAgentRequestSchema, executeAgentResponseSchema, parseSessionStream, sessionStatusSchema, sessionStreamEventSchema };
+export type { AgentClient, AgentClientConfig, AgentInput, AuthStrategy, ExecuteAgentRequest, ExecuteAgentResponse, ResolveReferenceAs, ResolveReferenceOptions, SessionStatus, SessionStreamEvent, StreamSessionOptions };

package/dist/index.mjs

@@ -0,0 +1,305 @@
+import { VaultFile } from '@meistrari/vault-sdk';
+import { z } from 'zod';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class DataTokenAuthStrategy {
+  constructor(dataToken) {
+    __publicField(this, "dataToken");
+    this.dataToken = dataToken;
+  }
+  getHeaders() {
+    return new Headers({
+      "x-data-token": this.dataToken
+    });
+  }
+}
+class APIKeyAuthStrategy {
+  constructor(apiKey) {
+    __publicField(this, "apiKey");
+    this.apiKey = apiKey;
+  }
+  getHeaders() {
+    return new Headers({
+      Authorization: `Bearer ${this.apiKey}`
+    });
+  }
+}
+
+class FetchError extends Error {
+  constructor(message, url, method, response) {
+    super(message);
+    this.message = message;
+    this.url = url;
+    this.method = method;
+    this.response = response;
+    this.name = "FetchError";
+  }
+  static async from(url, method, response) {
+    const jsonResponse = response.clone();
+    const textResponse = response.clone();
+    const text = await jsonResponse.json().then((json) => JSON.stringify(json, null, 2)).catch(() => textResponse.text());
+    return new FetchError(
+      `Failed to ${method} ${url}: ${response.status} ${response.statusText}:
+${text}`,
+      url,
+      method,
+      response
+    );
+  }
+}
+
+const sessionStatusSchema = z.enum([
+  "pending",
+  "running",
+  "completed",
+  "failed",
+  "waiting_messages",
+  "cancelled"
+]);
+const vaultReferenceSchema = z.string().regex(/^vault:\/\/\S+$/, "vaultRef must start with vault:// and cannot contain whitespace");
+const agentInputSchema = z.object({
+  vaultRef: vaultReferenceSchema,
+  filename: z.string().min(1, "Filename is required").max(255, "Filename must be 255 characters or less"),
+  metadata: z.string().max(16384, "Metadata must be 16,384 characters or less").optional()
+}).strict();
+const executeAgentRequestSchema = z.object({
+  sessionId: z.string().uuid().optional(),
+  organizationName: z.string().min(1).max(200).optional(),
+  repository: z.string().min(1).max(200).optional(),
+  ref: z.string().max(200).optional(),
+  message: z.string().min(1).max(8e5).optional(),
+  inputs: z.array(agentInputSchema).optional(),
+  environmentVariables: z.record(z.string(), z.string()).optional(),
+  recover: z.boolean().optional()
+}).strict().superRefine((data, ctx) => {
+  if (!data.sessionId) {
+    if (!data.organizationName) {
+      ctx.addIssue({ code: "custom", message: "organizationName is required for new sessions", path: ["organizationName"] });
+    }
+    if (!data.repository) {
+      ctx.addIssue({ code: "custom", message: "repository is required for new sessions", path: ["repository"] });
+    }
+    if (!data.message) {
+      ctx.addIssue({ code: "custom", message: "message is required for new sessions", path: ["message"] });
+    }
+  }
+  if (data.recover && !data.sessionId) {
+    ctx.addIssue({ code: "custom", message: "sessionId is required when recover is true", path: ["sessionId"] });
+  }
+});
+const executeAgentResponseSchema = z.object({
+  success: z.boolean(),
+  sessionId: z.string().optional(),
+  error: z.string().optional()
+});
+const sessionStatusEventSchema = z.object({
+  kind: z.literal("status"),
+  sessionId: z.string(),
+  status: sessionStatusSchema,
+  error: z.string().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number()
+});
+const sessionStepsEventSchema = z.object({
+  kind: z.literal("steps"),
+  sessionId: z.string(),
+  status: sessionStatusSchema,
+  steps: z.array(z.record(z.string(), z.unknown())),
+  nextCursor: z.number().nullable(),
+  createdAt: z.number(),
+  updatedAt: z.number()
+});
+const sessionResultEventSchema = z.object({
+  kind: z.literal("result"),
+  sessionId: z.string(),
+  status: z.enum(["completed", "waiting_messages"]),
+  result: z.record(z.string(), z.unknown()),
+  nextCursor: z.number().nullable(),
+  createdAt: z.number(),
+  updatedAt: z.number()
+});
+const sessionErrorEventSchema = z.object({
+  kind: z.literal("error"),
+  sessionId: z.string(),
+  error: z.string()
+});
+const sessionStreamEventSchema = z.discriminatedUnion("kind", [
+  sessionStatusEventSchema,
+  sessionStepsEventSchema,
+  sessionResultEventSchema,
+  sessionErrorEventSchema
+]);
+const SESSION_STREAM_EVENT_KINDS = /* @__PURE__ */ new Set(["status", "steps", "result", "error"]);
+
+function normalizeStreamBuffer(buffer) {
+  return buffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function isControlPayload(data) {
+  return data === "[DONE]" || data === "Stream complete";
+}
+function parseSseFrame(frame) {
+  let data = "";
+  let hasData = false;
+  let lineStart = 0;
+  while (lineStart <= frame.length) {
+    const lineEnd = frame.indexOf("\n", lineStart);
+    const line = lineEnd === -1 ? frame.slice(lineStart) : frame.slice(lineStart, lineEnd);
+    lineStart = lineEnd === -1 ? frame.length + 1 : lineEnd + 1;
+    if (!line || line.startsWith(":"))
+      continue;
+    const separatorIndex = line.indexOf(":");
+    const field = separatorIndex === -1 ? line : line.slice(0, separatorIndex);
+    let value = separatorIndex === -1 ? "" : line.slice(separatorIndex + 1);
+    if (value.startsWith(" "))
+      value = value.slice(1);
+    if (field === "data") {
+      data = hasData ? `${data}
+${value}` : value;
+      hasData = true;
+    }
+  }
+  if (!hasData)
+    return void 0;
+  if (!data || isControlPayload(data))
+    return void 0;
+  try {
+    return JSON.parse(data);
+  } catch {
+    return void 0;
+  }
+}
+function getEventKind(event) {
+  if (!event || typeof event !== "object" || !("kind" in event))
+    return null;
+  const kind = event.kind;
+  return typeof kind === "string" ? kind : null;
+}
+function parseKnownEvent(event) {
+  const eventKind = getEventKind(event);
+  if (!eventKind || !SESSION_STREAM_EVENT_KINDS.has(eventKind))
+    return void 0;
+  const parsed = sessionStreamEventSchema.safeParse(event);
+  if (!parsed.success)
+    throw new Error(parsed.error.message);
+  return parsed.data;
+}
+async function* parseSessionStream(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  function* drainBuffer() {
+    let consumedIndex = 0;
+    while (true) {
+      const frameBoundary = buffer.indexOf("\n\n", consumedIndex);
+      if (frameBoundary === -1)
+        break;
+      const event = parseSseFrame(buffer.slice(consumedIndex, frameBoundary));
+      consumedIndex = frameBoundary + 2;
+      if (event === void 0)
+        continue;
+      const parsed = parseKnownEvent(event);
+      if (parsed)
+        yield parsed;
+    }
+    if (consumedIndex > 0)
+      buffer = buffer.slice(consumedIndex);
+  }
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      buffer += normalizeStreamBuffer(decoder.decode(value, { stream: true }));
+      yield* drainBuffer();
+    }
+    buffer += normalizeStreamBuffer(decoder.decode());
+    if (buffer.trim()) {
+      const event = parseSseFrame(buffer);
+      if (event !== void 0) {
+        const parsed = parseKnownEvent(event);
+        if (parsed)
+          yield parsed;
+      }
+    }
+    buffer = "";
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function agentClient(config) {
+  const baseUrl = config.baseUrl.replace(/\/+$/, "");
+  async function request(params) {
+    const url = new URL(`${baseUrl}${params.path}`);
+    if (params.query) {
+      for (const [key, value] of Object.entries(params.query))
+        url.searchParams.set(key, value);
+    }
+    const headers = new Headers(config.authStrategy.getHeaders());
+    headers.set("Accept", params.accept ?? "application/json");
+    if (params.body !== void 0)
+      headers.set("Content-Type", "application/json");
+    const response = await fetch(url, {
+      method: params.method,
+      headers,
+      body: params.body !== void 0 ? JSON.stringify(params.body) : void 0,
+      signal: params.signal
+    });
+    if (!response.ok)
+      throw await FetchError.from(url.toString(), params.method, response);
+    return response;
+  }
+  async function executeAgent(input) {
+    const body = executeAgentRequestSchema.parse(input);
+    const response = await request({
+      method: "POST",
+      path: "/v4/agents/execute",
+      body
+    });
+    return executeAgentResponseSchema.parse(await response.json());
+  }
+  async function streamSession(sessionId, options) {
+    const response = await request({
+      method: "GET",
+      path: `/v4/sessions/${encodeURIComponent(sessionId)}`,
+      query: options?.cursor !== void 0 ? { cursor: String(options.cursor) } : void 0,
+      accept: "text/event-stream, application/json",
+      signal: options?.signal
+    });
+    if (!response.body)
+      throw new Error("Agent session stream response body is missing");
+    return parseSessionStream(response.body);
+  }
+  async function resolveReference(reference, options) {
+    if (!config.vaultUrl)
+      throw new Error("vaultUrl is required in AgentClientConfig to resolve references");
+    if (!reference.startsWith("vault://"))
+      throw new Error(`Unsupported vault reference: ${reference}`);
+    const vaultConfig = { vaultUrl: config.vaultUrl, authStrategy: config.authStrategy };
+    const as = options?.as ?? "bytes";
+    if (as === "stream") {
+      const vaultFile2 = await VaultFile.fromVaultReference(
+        { reference, config: vaultConfig, download: false },
+        { signal: options?.signal }
+      );
+      return vaultFile2.downloadStream({ signal: options?.signal });
+    }
+    const vaultFile = await VaultFile.fromVaultReference(
+      { reference, config: vaultConfig, download: true },
+      { signal: options?.signal }
+    );
+    if (!vaultFile.content)
+      throw new Error(`Vault content missing for ${reference}`);
+    if (as === "json")
+      return JSON.parse(await vaultFile.content.text());
+    return vaultFile.content.arrayBuffer();
+  }
+  return { executeAgent, streamSession, resolveReference };
+}
+
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, agentClient, agentInputSchema, executeAgentRequestSchema, executeAgentResponseSchema, parseSessionStream, sessionStatusSchema, sessionStreamEventSchema };

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@meistrari/agent-sdk",
+    "type": "module",
+    "version": "0.1.0",
+    "license": "UNLICENSED",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/meistrari/agent-api.git",
+        "directory": "packages/agent-sdk"
+    },
+    "exports": {
+        ".": {
+            "bun": "./src/index.ts",
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.cjs"
+        }
+    },
+    "main": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "unbuild",
+        "typecheck": "bunx tsc --noEmit",
+        "test:unit": "bun test test/",
+        "lint": "eslint ."
+    },
+    "peerDependencies": {
+        "typescript": "^5.0.0"
+    },
+    "dependencies": {
+        "@meistrari/vault-sdk": "1.9.0",
+        "zod": "4.1.12"
+    },
+    "devDependencies": {
+        "@types/bun": "latest",
+        "unbuild": "2.0.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}