@ai-matrx/agents 0.3.0 → 0.5.0

package/dist/index.js

@@ -202,6 +202,68 @@ async function* readMatrxNdjsonStream(body, options = {}) {
   }
 }
 
+// stream/sse.ts
+var FRAME_SEPARATOR = /\r\n\r\n|\n\n|\r\r/;
+var LINE_SEPARATOR = /\r\n|\n|\r/;
+function parseMatrxSseFrame(frame) {
+  let event = "message";
+  let id = null;
+  const dataLines = [];
+  let sawData = false;
+  for (const line of frame.split(LINE_SEPARATOR)) {
+    if (line.startsWith(":")) continue;
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) {
+      sawData = true;
+      dataLines.push(line.slice(5).replace(/^ /, ""));
+    } else if (line.startsWith("id:")) id = line.slice(3).trim();
+  }
+  const seqCandidate = id !== null && id !== "" ? Number(id) : NaN;
+  const seq = Number.isSafeInteger(seqCandidate) && seqCandidate >= 0 ? seqCandidate : null;
+  return { event, id, seq, data: sawData ? dataLines.join("\n") : null };
+}
+function createMatrxSseFramer() {
+  let buffer = "";
+  return {
+    push(chunk) {
+      buffer += chunk;
+      const frames = [];
+      for (; ; ) {
+        const sep = FRAME_SEPARATOR.exec(buffer);
+        if (sep === null) break;
+        const frame = buffer.slice(0, sep.index);
+        buffer = buffer.slice(sep.index + sep[0].length);
+        frames.push(parseMatrxSseFrame(frame));
+      }
+      return frames;
+    },
+    flush() {
+      const rest = buffer;
+      buffer = "";
+      return { incomplete: rest.length > 0 ? rest : null };
+    }
+  };
+}
+async function* readMatrxSseStream(stream, options = {}) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  const framer = createMatrxSseFramer();
+  try {
+    for (; ; ) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      const frames = framer.push(decoder.decode(value, { stream: true }));
+      for (const frame of frames) yield frame;
+    }
+    const tail = framer.push(decoder.decode());
+    for (const frame of tail) yield frame;
+    const { incomplete } = framer.flush();
+    if (incomplete !== null) options.onIncomplete?.(incomplete);
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 // presentation/result.ts
 var PRIVATE_REASONING_TYPES = /* @__PURE__ */ new Set([
   "thinking",
@@ -703,6 +765,460 @@ function projectWorkflowNodeEvent(current, event) {
   }
 }
 
-export { DEFAULT_MATRX_NDJSON_READ_AHEAD, DEFAULT_WORKFLOW_PROJECTION_LIMITS, createAgentRequestProjection, createMatrxNdjsonFramer, createWorkflowNodeProjection, normalizeMatrxStreamEnvelope, projectAgentEvent, projectAgentEvents, projectAgentResultForDisplay, projectWorkflowNodeEvent, readMatrxNdjsonStream };
+// matrx/transport.ts
+var MatrxApiError = class extends Error {
+  name = "MatrxApiError";
+  /** HTTP status of the failed response. */
+  status;
+  /** Machine code from the server body (`code`, or `detail.code`), when present. */
+  code;
+  /** The parsed server error body, verbatim (undefined when unparsable). */
+  serverDetail;
+  /** The request path the failure came from (server-relative). */
+  path;
+  constructor(args) {
+    super(
+      args.message ?? extractMatrxErrorMessage(args.serverDetail) ?? `HTTP ${args.status}`
+    );
+    this.status = args.status;
+    this.path = args.path;
+    this.serverDetail = args.serverDetail;
+    this.code = extractMatrxErrorCode(args.serverDetail);
+  }
+};
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonBlankString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function extractMatrxErrorMessage(serverDetail) {
+  if (!isRecord3(serverDetail)) return void 0;
+  const userMessage = nonBlankString(serverDetail.user_message);
+  if (userMessage) return userMessage;
+  const message = nonBlankString(serverDetail.message);
+  if (message) return message;
+  if (Array.isArray(serverDetail.details)) {
+    const messages = serverDetail.details.map((entry) => {
+      if (!isRecord3(entry)) return void 0;
+      const detailMessage = nonBlankString(entry.message);
+      if (!detailMessage) return void 0;
+      const field = nonBlankString(entry.field);
+      return field ? `${field}: ${detailMessage}` : detailMessage;
+    }).filter((m) => typeof m === "string");
+    if (messages.length > 0) return messages.join("; ");
+  }
+  const detail = serverDetail.detail;
+  if (isRecord3(detail)) {
+    const detailMessage = nonBlankString(detail.message) ?? nonBlankString(detail.user_message);
+    if (detailMessage) return detailMessage;
+  }
+  if (typeof detail === "string" && detail.trim()) return detail;
+  if (Array.isArray(detail)) {
+    const messages = detail.map(
+      (entry) => isRecord3(entry) ? nonBlankString(entry.msg) : void 0
+    ).filter((m) => typeof m === "string");
+    if (messages.length > 0) return messages.join("; ");
+  }
+  return void 0;
+}
+function extractMatrxErrorCode(serverDetail) {
+  if (!isRecord3(serverDetail)) return null;
+  const topLevel = nonBlankString(serverDetail.code);
+  if (topLevel) return topLevel;
+  const detail = serverDetail.detail;
+  if (isRecord3(detail)) {
+    const nested = nonBlankString(detail.code);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+// matrx/conversation.ts
+function mintMatrxConversationId() {
+  return crypto.randomUUID();
+}
+function newStoredConversationStart(conversationId) {
+  return {
+    conversation_id: conversationId ?? mintMatrxConversationId(),
+    is_new: true,
+    store: true
+  };
+}
+function continueStoredConversationStart(conversationId) {
+  return { conversation_id: conversationId, is_new: false, store: true };
+}
+function newEphemeralConversationStart(conversationId) {
+  return {
+    conversation_id: conversationId ?? mintMatrxConversationId(),
+    is_new: true,
+    store: false
+  };
+}
+function continueEphemeralConversationStart(conversationId, priorMessages) {
+  return {
+    conversation_id: conversationId,
+    is_new: false,
+    store: false,
+    prior_messages: priorMessages
+  };
+}
+
+// matrx/internal.ts
+function encodePathSegment(value) {
+  return encodeURIComponent(value);
+}
+function buildQuery(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      for (const entry of value) search.append(key, entry);
+    } else {
+      search.append(key, String(value));
+    }
+  }
+  const encoded = search.toString();
+  return encoded ? `?${encoded}` : "";
+}
+async function readServerDetail(response) {
+  try {
+    return await response.json();
+  } catch {
+    return void 0;
+  }
+}
+async function throwApiError(path, response) {
+  throw new MatrxApiError({
+    status: response.status,
+    path,
+    serverDetail: await readServerDetail(response)
+  });
+}
+async function requestJson(transport, path, options) {
+  const hasBody = options.method !== "GET" && options.body !== void 0;
+  const response = await transport.fetch(path, {
+    method: options.method,
+    headers: hasBody ? { "Content-Type": "application/json" } : {},
+    ...hasBody ? { body: JSON.stringify(options.body) } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  if (!response.ok) return throwApiError(path, response);
+  return await response.json();
+}
+function toRunHandle(response, options) {
+  return {
+    requestId: response.headers.get("X-Request-ID"),
+    conversationId: response.headers.get("X-Conversation-ID"),
+    events: readMatrxNdjsonStream(response.body, {
+      ...options.signal ? { signal: options.signal } : {},
+      ...options.maxReadAhead !== void 0 ? { maxReadAhead: options.maxReadAhead } : {},
+      ...options.onMalformedLine ? { onMalformedLine: options.onMalformedLine } : {},
+      ...options.onUnknownEnvelope ? { onUnknownEnvelope: options.onUnknownEnvelope } : {},
+      ...options.onValidEnvelope ? { onValidEnvelope: options.onValidEnvelope } : {}
+    }),
+    response
+  };
+}
+async function requestStream(transport, path, options) {
+  const hasBody = options.method !== "GET" && options.body !== void 0;
+  const response = await transport.fetch(path, {
+    method: options.method,
+    headers: {
+      ...hasBody ? { "Content-Type": "application/json" } : {},
+      ...options.headers
+    },
+    ...hasBody ? { body: JSON.stringify(options.body) } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  if (!response.ok) return throwApiError(path, response);
+  if (!response.body) {
+    throw new MatrxApiError({
+      status: response.status,
+      path,
+      serverDetail: { code: "missing_response_body" },
+      message: "The streaming response carried no body."
+    });
+  }
+  return response;
+}
+
+// matrx/run.ts
+async function streamCall(transport, path, body, options) {
+  const response = await requestStream(transport, path, {
+    method: "POST",
+    // This client IS the streaming path — `stream: true` always, last so a
+    // caller-supplied value can never flip the response off NDJSON.
+    body: { ...body, stream: true },
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  return toRunHandle(response, options);
+}
+function startAgentRun(transport, agentId, request, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/agents/${encodePathSegment(agentId)}`,
+    request,
+    options
+  );
+}
+function continueAgentConversation(transport, conversationId, request, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}`,
+    request,
+    options
+  );
+}
+function resumeAgentConversation(transport, conversationId, request = {}, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}/resume`,
+    request,
+    options
+  );
+}
+function cancelAgentRun(transport, requestId, options = {}) {
+  const query = buildQuery(
+    options.mode === "interrupt" ? { mode: "interrupt" } : {}
+  );
+  return requestJson(
+    transport,
+    `/ai/cancel/${encodePathSegment(requestId)}${query}`,
+    {
+      method: "POST",
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+var MatrxRunError = class extends Error {
+  name = "MatrxRunError";
+  /** The verbatim `error` event payload, when one fired. */
+  errorPayload;
+  /** The `user_request` completion status (`"failed"` | `"cancelled"`), when that was the trigger. */
+  completionStatus;
+  /** Text streamed before the failure — partial content never vanishes. */
+  partialText;
+  constructor(args) {
+    super(args.message);
+    this.errorPayload = args.errorPayload ?? null;
+    this.completionStatus = args.completionStatus ?? null;
+    this.partialText = args.partialText ?? "";
+  }
+};
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(value, key) {
+  if (!isRecord4(value)) return null;
+  const field = value[key];
+  return typeof field === "string" && field ? field : null;
+}
+async function runAgentToCompletion(transport, agentId, request, options = {}) {
+  const handle = await startAgentRun(transport, agentId, request, options);
+  let text = "";
+  let completion = null;
+  let failure = null;
+  for await (const envelope of handle.events) {
+    options.onEvent?.(envelope);
+    if (envelope.event === "chunk") {
+      const chunk = stringField(envelope.data, "text");
+      if (chunk !== null) {
+        text += chunk;
+        options.onChunk?.(text);
+      }
+      continue;
+    }
+    if (envelope.event === "error" && failure === null) {
+      const payload = isRecord4(envelope.data) ? envelope.data : null;
+      failure = new MatrxRunError({
+        message: stringField(payload, "user_message") ?? stringField(payload, "message") ?? "The agent run failed",
+        errorPayload: payload,
+        partialText: text
+      });
+      continue;
+    }
+    if (envelope.event !== "completion" || !isRecord4(envelope.data)) continue;
+    if (envelope.data.operation !== "user_request") continue;
+    completion = envelope.data;
+    const status = envelope.data.status;
+    if ((status === "failed" || status === "cancelled") && failure === null) {
+      const result = isRecord4(envelope.data.result) ? envelope.data.result : null;
+      failure = new MatrxRunError({
+        message: stringField(result, "error") ?? stringField(result, "user_message") ?? `The agent run ${status}`,
+        completionStatus: status,
+        partialText: text
+      });
+    }
+  }
+  if (failure) throw failure;
+  if (!text && completion) {
+    const result = completion.result;
+    const output = stringField(result, "output");
+    if (output !== null) text = output;
+  }
+  return {
+    text,
+    requestId: handle.requestId,
+    conversationId: handle.conversationId,
+    completion
+  };
+}
+
+// matrx/operations.ts
+var TERMINAL_MATRX_RUNTIME_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+var RUNTIME_STATUSES = /* @__PURE__ */ new Set([
+  "pending",
+  "running",
+  "paused",
+  "waiting_input",
+  "completed",
+  "failed",
+  "cancelled"
+]);
+async function getRuntimeOperationStatus(transport, requestId, options = {}) {
+  try {
+    return await requestJson(
+      transport,
+      `/runtime/operations/${encodePathSegment(requestId)}`,
+      { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+    );
+  } catch (error) {
+    if (error instanceof MatrxApiError && error.status === 404) return null;
+    throw error;
+  }
+}
+async function getRuntimeOperationsByLink(transport, linkKind, linkId, options = {}) {
+  const query = buildQuery(
+    options.limit !== void 0 ? { limit: options.limit } : {}
+  );
+  try {
+    return await requestJson(
+      transport,
+      `/runtime/operations/by-link/${encodePathSegment(linkKind)}/${encodePathSegment(linkId)}${query}`,
+      { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+    );
+  } catch (error) {
+    if (error instanceof MatrxApiError && error.status === 404) return null;
+    throw error;
+  }
+}
+function listRuntimeOperationEvents(transport, executionId, options = {}) {
+  const query = buildQuery({
+    ...options.afterSeq !== void 0 ? { after_seq: options.afterSeq } : {},
+    ...options.limit !== void 0 ? { limit: options.limit } : {},
+    ...options.kinds !== void 0 ? { kind: options.kinds } : {}
+  });
+  return requestJson(
+    transport,
+    `/runtime/executions/${encodePathSegment(executionId)}/events${query}`,
+    { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+  );
+}
+function parseEndStatus(data) {
+  if (data === null) return null;
+  try {
+    const parsed = JSON.parse(data);
+    if (typeof parsed === "object" && parsed !== null && typeof parsed.status === "string") {
+      const status = parsed.status;
+      return RUNTIME_STATUSES.has(status) ? status : null;
+    }
+  } catch {
+  }
+  return null;
+}
+async function* followRuntimeOperationEvents(transport, executionId, options = {}) {
+  let cursor = options.lastEventSeq ?? 0;
+  const headers = { Accept: "text/event-stream" };
+  if (cursor > 0) headers["Last-Event-ID"] = String(cursor);
+  const response = await requestStream(
+    transport,
+    `/runtime/executions/${encodePathSegment(executionId)}/events/stream`,
+    {
+      method: "GET",
+      headers,
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+  const frames = readMatrxSseStream(
+    response.body,
+    options.onIncomplete ? { onIncomplete: options.onIncomplete } : {}
+  );
+  for await (const frame of frames) {
+    if (frame.event === "end") {
+      yield { type: "end", status: parseEndStatus(frame.data), cursor };
+      return;
+    }
+    if (frame.event === "execution_event" && frame.data !== null) {
+      let event;
+      try {
+        event = JSON.parse(frame.data);
+      } catch (error) {
+        options.onMalformedFrame?.(frame, error);
+        yield { type: "liveness", cursor };
+        continue;
+      }
+      if (frame.seq !== null && frame.seq > cursor) cursor = frame.seq;
+      yield { type: "event", event, seq: frame.seq, cursor };
+      continue;
+    }
+    yield { type: "liveness", cursor };
+  }
+}
+async function rejoinRuntimeOperation(transport, requestId, options = {}) {
+  const response = await requestStream(
+    transport,
+    `/runtime/operations/${encodePathSegment(requestId)}/rejoin`,
+    {
+      method: "POST",
+      // The route takes no body model; the reference client posts an empty
+      // JSON object. Match it so proxies see an ordinary JSON POST.
+      body: {},
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+  return toRunHandle(response, options);
+}
+
+// matrx/tools.ts
+function submitAgentToolResults(transport, conversationId, results, options = {}) {
+  return requestJson(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}/tool_results`,
+    {
+      method: "POST",
+      body: {
+        results,
+        ...options.instanceId !== void 0 ? { instance_id: options.instanceId } : {}
+      },
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+function listConversationPendingToolCalls(transport, conversationId, options = {}) {
+  return requestJson(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}/pending_calls`,
+    {
+      method: "GET",
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+function listUserPendingToolCalls(transport, options = {}) {
+  const query = buildQuery(
+    options.instanceId !== void 0 ? { instance_id: options.instanceId } : {}
+  );
+  return requestJson(
+    transport,
+    `/ai/user/pending_calls${query}`,
+    {
+      method: "GET",
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+
+export { DEFAULT_MATRX_NDJSON_READ_AHEAD, DEFAULT_WORKFLOW_PROJECTION_LIMITS, MatrxApiError, MatrxRunError, TERMINAL_MATRX_RUNTIME_STATUSES, cancelAgentRun, continueAgentConversation, continueEphemeralConversationStart, continueStoredConversationStart, createAgentRequestProjection, createMatrxNdjsonFramer, createMatrxSseFramer, createWorkflowNodeProjection, extractMatrxErrorCode, extractMatrxErrorMessage, followRuntimeOperationEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, listConversationPendingToolCalls, listRuntimeOperationEvents, listUserPendingToolCalls, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxStreamEnvelope, parseMatrxSseFrame, projectAgentEvent, projectAgentEvents, projectAgentResultForDisplay, projectWorkflowNodeEvent, readMatrxNdjsonStream, readMatrxSseStream, rejoinRuntimeOperation, resumeAgentConversation, runAgentToCompletion, startAgentRun, submitAgentToolResults };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map