@noodleseed/assistant 1.1.0 → 1.2.0

package/dist/client.cjs

@@ -0,0 +1,662 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  AssistantClientError: () => AssistantClientError,
+  createAssistantClient: () => createAssistantClient
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/events.ts
+function toAssistantClientEvent(event) {
+  const value = event.data;
+  switch (event.event) {
+    case "content":
+      if (typeof value.delta === "string" && hasOptionalTurnId(value)) {
+        return event;
+      }
+      break;
+    case "tool_proposed":
+      if (hasString(value, "id") && hasString(value, "tool") && hasOptionalJson(value.arguments) && hasOptionalString(value.expiresAt) && (value.requiresConfirmation === void 0 || value.requiresConfirmation === true) && hasOptionalTurnId(value)) {
+        return event;
+      }
+      break;
+    case "input_requested":
+      if (hasString(value, "id") && hasString(value, "message") && isRecord(value.requestedSchema) && hasString(value, "expiresAt") && hasOptionalTurnId(value)) {
+        return event;
+      }
+      break;
+    case "interaction_resolved":
+      if (hasString(value, "id") && (value.action === void 0 || isInteractionAction(value.action)) && hasOptionalTurnId(value)) {
+        return event;
+      }
+      break;
+    case "tool_completed":
+      if (hasString(value, "id") && hasString(value, "tool") && isJsonValue(value.result, 0) && (value.replayed === void 0 || value.replayed === true) && hasOptionalTurnId(value)) {
+        return event;
+      }
+      break;
+    case "view_available":
+      if (isViewAvailableDetail(value)) return event;
+      break;
+    case "error":
+      if (hasString(value, "code") && (value.status === void 0 || typeof value.status === "number") && (value.retryable === void 0 || typeof value.retryable === "boolean") && hasOptionalTurnId(value)) {
+        return event;
+      }
+      break;
+    case "done":
+      if (hasOptionalTurnId(value)) return event;
+      break;
+    case "interaction_proposed":
+      if (hasString(value, "id") && (hasString(value, "tool") || hasString(value, "title")) && hasOptionalJson(value.arguments)) {
+        return event;
+      }
+      break;
+  }
+  return { event: "unrecognized", data: { name: event.event, payload: value } };
+}
+function isViewAvailableDetail(value) {
+  return hasString(value, "id") && hasString(value, "tool") && typeof value.resourceUri === "string" && value.resourceUri.startsWith("ui://") && hasOptionalString(value.title) && (value.replayed === void 0 || value.replayed === true) && isJsonValue(value.result, 0) && hasOptionalTurnId(value);
+}
+function hasOptionalTurnId(value) {
+  return hasOptionalString(value.turnId);
+}
+function hasString(value, key) {
+  const entry = value[key];
+  return typeof entry === "string" && entry.length > 0;
+}
+function hasOptionalString(value) {
+  return value === void 0 || typeof value === "string";
+}
+function hasOptionalJson(value) {
+  return value === void 0 || isJsonValue(value, 0);
+}
+function isInteractionAction(value) {
+  return value === "accept" || value === "decline" || value === "cancel";
+}
+function isJsonValue(value, depth) {
+  if (depth > 16) return false;
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) {
+    return value.length <= 256 && value.every((entry) => isJsonValue(entry, depth + 1));
+  }
+  if (!isRecord(value)) return false;
+  const entries = Object.entries(value);
+  return entries.length <= 256 && entries.every(([, entry]) => isJsonValue(entry, depth + 1));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/model-context.ts
+var MAX_BYTES = 16 * 1024;
+var MAX_DEPTH = 8;
+var MAX_ENTRIES = 128;
+var SENSITIVE_KEY = /(?:secret|token|api[-_]?key|password|credential|authorization|cookie)/i;
+var CREDENTIAL_SHAPED_TEXT = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|\bsk-[A-Za-z0-9_-]{20,}\b|\b(?:bearer|basic)\s+[A-Za-z0-9._~+/=-]{20,}\b|\b[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b)/i;
+function copyAssistantModelContext(update) {
+  const copied = copyJsonValue(update, "$", 0, /* @__PURE__ */ new Set());
+  assertModelContextShape(copied);
+  const encoded = JSON.stringify(copied);
+  if (new TextEncoder().encode(encoded).byteLength > MAX_BYTES) {
+    throw new Error("Model context must not exceed 16 KiB");
+  }
+  return copied;
+}
+function assertModelContextShape(value) {
+  if (!isPlainRecord(value)) throw new Error("Model context must be a JSON object");
+  for (const key of Object.keys(value)) {
+    if (key !== "content" && key !== "structuredContent") {
+      throw new Error(`Model context contains unknown field ${key}`);
+    }
+  }
+  if (value.content !== void 0) {
+    if (!Array.isArray(value.content)) throw new Error("Model context content must be an array");
+    for (const part of value.content) {
+      if (!isPlainRecord(part) || Object.keys(part).some((key) => key !== "type" && key !== "text") || part.type !== "text" || typeof part.text !== "string") {
+        throw new Error("Model context content supports text parts only");
+      }
+    }
+  }
+  if (value.structuredContent !== void 0 && !isPlainRecord(value.structuredContent)) {
+    throw new Error("Model context structuredContent must be an object");
+  }
+}
+function copyJsonValue(value, path, depth, ancestors) {
+  if (depth > MAX_DEPTH) throw new Error(`Model context exceeds maximum depth at ${path}`);
+  if (typeof value === "string") {
+    if (CREDENTIAL_SHAPED_TEXT.test(value)) {
+      throw new Error(`Model context contains credential-shaped text at ${path}`);
+    }
+    return value;
+  }
+  if (value === null || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value !== "object") throw new Error(`Model context contains non-JSON data at ${path}`);
+  if (hasToJsonProperty(value)) {
+    throw new Error(`Model context must not define or inherit toJSON at ${path}`);
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (Array.isArray(value)) {
+    if (prototype !== Array.prototype) {
+      throw new Error(`Model context contains a non-JSON object at ${path}`);
+    }
+  } else if (prototype !== Object.prototype && prototype !== null) {
+    throw new Error(`Model context contains a non-JSON object at ${path}`);
+  }
+  if (ancestors.has(value)) throw new Error(`Model context contains a cycle at ${path}`);
+  if (Array.isArray(value)) {
+    if (value.length > MAX_ENTRIES) {
+      throw new Error(`Model context has more than 128 entries at ${path}`);
+    }
+    const copy2 = [];
+    ancestors.add(value);
+    for (let index = 0; index < value.length; index += 1) {
+      const entry = Object.hasOwn(value, index) ? value[index] : null;
+      copy2.push(copyJsonValue(entry, `${path}.${index}`, depth + 1, ancestors));
+    }
+    ancestors.delete(value);
+    return copy2;
+  }
+  const entries = Object.entries(value);
+  if (entries.length > MAX_ENTRIES) {
+    throw new Error(`Model context has more than 128 entries at ${path}`);
+  }
+  const copy = /* @__PURE__ */ Object.create(null);
+  ancestors.add(value);
+  for (const [key, entry] of entries) {
+    if (SENSITIVE_KEY.test(key)) {
+      throw new Error(`Model context contains sensitive key ${path}.${key}`);
+    }
+    copy[key] = copyJsonValue(entry, `${path}.${key}`, depth + 1, ancestors);
+  }
+  ancestors.delete(value);
+  return copy;
+}
+function isPlainRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function hasToJsonProperty(value) {
+  let current = value;
+  const visited = /* @__PURE__ */ new Set();
+  while (current !== null && !visited.has(current)) {
+    visited.add(current);
+    if (Object.getOwnPropertyDescriptor(current, "toJSON") !== void 0) return true;
+    current = Object.getPrototypeOf(current);
+  }
+  return false;
+}
+
+// src/transport.ts
+var AssistantTransportError = class extends Error {
+  code = "invalid_response";
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AssistantTransportError";
+  }
+};
+async function consumeAssistantEvents(response, onEvent) {
+  const stream = new AssistantEventStream(onEvent);
+  if (!response.body) {
+    let text;
+    try {
+      text = await response.text();
+    } catch (error) {
+      if (isAbortError(error)) throw error;
+      throw invalidStream("assistant event stream could not be read", error);
+    }
+    stream.push(text);
+    stream.finish(response.headers.get("content-type") ?? "");
+    return;
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  while (true) {
+    let result;
+    try {
+      result = await reader.read();
+    } catch (error) {
+      if (isAbortError(error)) throw error;
+      throw invalidStream("assistant event stream ended unexpectedly", error);
+    }
+    let chunk;
+    try {
+      chunk = decoder.decode(result.value, { stream: !result.done });
+    } catch (error) {
+      throw invalidStream("assistant event stream contained invalid UTF-8", error);
+    }
+    stream.push(chunk);
+    if (result.done) break;
+  }
+  stream.finish(response.headers.get("content-type") ?? "");
+}
+var AssistantEventStream = class {
+  #onEvent;
+  #pending = "";
+  #terminal;
+  constructor(onEvent) {
+    this.#onEvent = onEvent;
+  }
+  push(chunk) {
+    this.#pending += chunk;
+    const protectedCarriageReturn = this.#pending.endsWith("\r");
+    const normalizable = protectedCarriageReturn ? this.#pending.slice(0, -1) : this.#pending;
+    const frames = normalizeLineEndings(normalizable).split("\n\n");
+    this.#pending = `${frames.pop() ?? ""}${protectedCarriageReturn ? "\r" : ""}`;
+    for (const frame of frames) this.#acceptFrame(frame);
+  }
+  finish(contentType) {
+    if (this.#pending.trim().length > 0) {
+      throw invalidStream("assistant event stream ended with an unterminated frame");
+    }
+    if (!this.#terminal) {
+      throw invalidStream(
+        `assistant response did not contain a terminal done event (content-type: ${contentType || "unknown"})`
+      );
+    }
+    this.#onEvent(this.#terminal);
+  }
+  #acceptFrame(frame) {
+    const event = parseFrame(frame);
+    if (!event) return;
+    if (this.#terminal) {
+      throw invalidStream("assistant event stream contained an event after done");
+    }
+    if (event.event === "done") {
+      this.#terminal = event;
+      return;
+    }
+    this.#onEvent(event);
+  }
+};
+function parseFrame(frame) {
+  let event;
+  const data = [];
+  let hasFields = false;
+  for (const line of frame.split("\n")) {
+    if (!line || line.startsWith(":")) continue;
+    hasFields = true;
+    const separator = line.indexOf(":");
+    const field = separator < 0 ? line : line.slice(0, separator);
+    const value = separator < 0 ? "" : line.slice(separator + 1).replace(/^ /, "");
+    if (field === "event") event = value;
+    if (field === "data") data.push(value);
+  }
+  if (!hasFields) return void 0;
+  if (!event || data.length === 0) {
+    throw invalidStream("assistant event stream contained a malformed frame");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(data.join("\n"));
+  } catch (error) {
+    throw invalidStream("assistant event stream contained malformed JSON", error);
+  }
+  if (event === "done" && !isValidDonePayload(parsed)) {
+    throw invalidStream("assistant event stream contained an invalid done event");
+  }
+  return { event, data: isRecord2(parsed) ? parsed : { value: parsed } };
+}
+function normalizeLineEndings(input) {
+  return input.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+}
+function isValidDonePayload(value) {
+  return isRecord2(value) && (value.turnId === void 0 || typeof value.turnId === "string" && value.turnId.length > 0);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalidStream(message, cause) {
+  return new AssistantTransportError(message, cause === void 0 ? void 0 : { cause });
+}
+function isAbortError(error) {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+// src/client.ts
+var AssistantClientError = class extends Error {
+  detail;
+  constructor(detail, message, options) {
+    super(message, options);
+    this.name = "AssistantClientError";
+    this.detail = detail;
+  }
+};
+var DefaultAssistantClient = class {
+  #sessionEndpoint;
+  #fetch;
+  #listeners = /* @__PURE__ */ new Set();
+  #clientContext;
+  #session;
+  #context;
+  #modelContext;
+  #active;
+  constructor(options) {
+    if (!options.sessionEndpoint) throw new Error("sessionEndpoint is required");
+    this.#sessionEndpoint = options.sessionEndpoint;
+    this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    this.#context = options.context ? { ...options.context } : void 0;
+    this.#modelContext = options.modelContext ? copyAssistantModelContext(options.modelContext) : void 0;
+    this.#clientContext = options.clientContext;
+  }
+  subscribe(listener) {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+  async sendMessage(text) {
+    const message = text.trim();
+    if (!message) return;
+    await this.#singleFlight(async (signal) => {
+      await this.#sendTurn(message, true, signal, this.#modelContext);
+    });
+  }
+  async respond(id, resolution) {
+    if (!id) {
+      throw clientError("invalid_request", "interaction id is required", false);
+    }
+    await this.#singleFlight(async (signal) => {
+      const session = this.#session;
+      if (!session) {
+        throw clientError("confirmation_expired", "assistant session is not active", false);
+      }
+      const modernEndpoint = session.endpoints.interactions;
+      if (!modernEndpoint && resolution.action !== "accept") {
+        throw clientError(
+          "unsupported_service",
+          "the assistant service does not support declining or cancelling interactions",
+          false
+        );
+      }
+      const endpoint = modernEndpoint ?? session.endpoints.toolConfirmations;
+      const body = modernEndpoint ? {
+        id,
+        action: resolution.action,
+        ...resolution.action === "accept" && resolution.content !== void 0 ? { content: resolution.content } : {}
+      } : { id };
+      this.#emit({ event: "interaction_started", data: { id, action: resolution.action } });
+      const response = await this.#request(
+        endpoint,
+        {
+          method: "POST",
+          headers: authorizedHeaders(session.token, "text/event-stream"),
+          body: JSON.stringify(body),
+          signal
+        },
+        "confirmation_failed"
+      );
+      if (response.status === 401) {
+        this.#session = void 0;
+        this.#emit({ event: "session_expired", data: {} });
+      }
+      if (!response.ok) {
+        const serverCode = await readStableErrorCode(response);
+        const expired = response.status === 401 || response.status === 409;
+        throw clientError(
+          serverCode ?? (expired ? "confirmation_expired" : "confirmation_failed"),
+          `Assistant interaction failed (${response.status})`,
+          false,
+          response.status
+        );
+      }
+      await this.#consume(response);
+      this.#emit({ event: "interaction_completed", data: { id, action: resolution.action } });
+    });
+  }
+  updateContext(context) {
+    this.#context = { ...context };
+    this.#emit({ event: "context_changed", data: { context: this.#context } });
+  }
+  updateModelContext(update) {
+    this.#modelContext = copyAssistantModelContext(update);
+    this.#emit({ event: "model_context_changed", data: { modelContext: this.#modelContext } });
+  }
+  resetSession() {
+    this.#session = void 0;
+    this.#emit({ event: "session_reset", data: {} });
+  }
+  abort() {
+    this.#active?.abort();
+  }
+  async #sendTurn(message, mayRetry, signal, modelContext) {
+    const session = this.#session ?? await this.#createSession(signal);
+    if (mayRetry) this.#emit({ event: "message_started", data: { message } });
+    const clientContext = this.#resolveClientContext();
+    const response = await this.#request(
+      session.endpoints.turns,
+      {
+        method: "POST",
+        headers: authorizedHeaders(session.token, "text/event-stream"),
+        body: JSON.stringify({
+          message,
+          ...clientContext ? { clientContext } : {},
+          ...modelContext ? { modelContext } : {}
+        }),
+        signal
+      },
+      "turn_failed"
+    );
+    if (response.status === 401 && mayRetry) {
+      this.#session = void 0;
+      this.#emit({ event: "session_expired", data: {} });
+      await this.#sendTurn(message, false, signal, modelContext);
+      return;
+    }
+    if (!response.ok) {
+      throw clientError(
+        "turn_failed",
+        `Assistant turn failed (${response.status})`,
+        false,
+        response.status
+      );
+    }
+    await this.#consume(response);
+    this.#emit({ event: "message_completed", data: {} });
+  }
+  #resolveClientContext() {
+    let value;
+    try {
+      value = typeof this.#clientContext === "function" ? this.#clientContext() : this.#clientContext;
+    } catch (error) {
+      throw clientError(
+        "turn_failed",
+        "Assistant client context provider failed",
+        false,
+        void 0,
+        {
+          cause: error
+        }
+      );
+    }
+    if (!value) return void 0;
+    const context = {
+      ...typeof value.locale === "string" && value.locale ? { locale: value.locale } : {},
+      ...typeof value.timeZone === "string" && value.timeZone ? { timeZone: value.timeZone } : {}
+    };
+    return Object.keys(context).length > 0 ? context : void 0;
+  }
+  async #createSession(signal) {
+    const response = await this.#request(
+      this.#sessionEndpoint,
+      {
+        method: "POST",
+        headers: { Accept: "application/json", "Content-Type": "application/json" },
+        body: JSON.stringify(this.#context ? { context: this.#context } : {}),
+        credentials: "same-origin",
+        signal
+      },
+      "session_failed"
+    );
+    if (!response.ok) {
+      throw clientError(
+        "session_failed",
+        `Assistant session failed (${response.status})`,
+        true,
+        response.status
+      );
+    }
+    let value;
+    try {
+      value = await response.json();
+    } catch (error) {
+      throw clientError(
+        "session_failed",
+        "Assistant session returned invalid JSON",
+        true,
+        void 0,
+        {
+          cause: error
+        }
+      );
+    }
+    const session = parseSession(value);
+    this.#session = session;
+    this.#emit({
+      event: "session_started",
+      data: {
+        expiresAt: session.expiresAt,
+        ...session.configuration ? { configuration: session.configuration } : {}
+      }
+    });
+    return session;
+  }
+  async #consume(response) {
+    let streamError;
+    try {
+      await consumeAssistantEvents(response, (event) => {
+        const clientEvent = toAssistantClientEvent(event);
+        this.#emit(clientEvent);
+        if (clientEvent.event !== "error" || typeof clientEvent.data.code !== "string") return;
+        streamError = {
+          code: clientEvent.data.code,
+          ...typeof clientEvent.data.status === "number" ? { status: clientEvent.data.status } : {},
+          retryable: clientEvent.data.retryable === true
+        };
+      });
+    } catch (error) {
+      if (error instanceof AssistantTransportError) {
+        throw clientError(error.code, error.message, false, void 0, { cause: error });
+      }
+      throw error;
+    }
+    if (streamError) {
+      throw clientError(
+        streamError.code,
+        `Assistant stream failed (${streamError.code})`,
+        streamError.retryable,
+        streamError.status
+      );
+    }
+  }
+  async #request(input, init, failureCode) {
+    try {
+      return await this.#fetch(input, init);
+    } catch (error) {
+      if (init.signal?.aborted) throw error;
+      throw clientError(failureCode, "Assistant request failed", true, void 0, { cause: error });
+    }
+  }
+  async #singleFlight(operation) {
+    if (this.#active) {
+      throw clientError("request_in_progress", "an assistant request is already in progress", true);
+    }
+    const controller = new AbortController();
+    this.#active = controller;
+    try {
+      await operation(controller.signal);
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw clientError("request_aborted", "assistant request was aborted", true, void 0, {
+          cause: error
+        });
+      }
+      throw error;
+    } finally {
+      this.#active = void 0;
+    }
+  }
+  #emit(event) {
+    for (const listener of this.#listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+};
+function createAssistantClient(options) {
+  return new DefaultAssistantClient(options);
+}
+function authorizedHeaders(token, accept) {
+  return {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+    Accept: accept
+  };
+}
+function parseSession(value) {
+  if (!isRecord3(value) || !isRecord3(value.endpoints)) {
+    throw clientError("session_failed", "Assistant session response is invalid", true);
+  }
+  const interactions = value.endpoints.interactions;
+  if (typeof value.token !== "string" || typeof value.expiresAt !== "string" || typeof value.endpoints.turns !== "string" || typeof value.endpoints.toolConfirmations !== "string" || interactions !== void 0 && typeof interactions !== "string") {
+    throw clientError("session_failed", "Assistant session response is invalid", true);
+  }
+  return {
+    token: value.token,
+    expiresAt: value.expiresAt,
+    endpoints: {
+      turns: value.endpoints.turns,
+      toolConfirmations: value.endpoints.toolConfirmations,
+      ...typeof interactions === "string" ? { interactions } : {}
+    },
+    ...isRecord3(value.configuration) ? { configuration: value.configuration } : {}
+  };
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function readStableErrorCode(response) {
+  let value;
+  try {
+    value = await response.json();
+  } catch {
+    return void 0;
+  }
+  if (!isRecord3(value) || typeof value.code !== "string") return void 0;
+  return /^[A-Za-z0-9_.-]{1,64}$/.test(value.code) ? value.code : void 0;
+}
+function clientError(code, message, retryable, status, options) {
+  return new AssistantClientError(
+    { code, ...status === void 0 ? {} : { status }, retryable },
+    message,
+    options
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AssistantClientError,
+  createAssistantClient
+});
+//# sourceMappingURL=client.cjs.map