@webless/agent 0.6.3 → 0.6.5

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AGENT_TOOL_UI_SCHEMA_VERSION: () => AGENT_TOOL_UI_SCHEMA_VERSION,
   DEFAULT_RUNTIME_ORIGIN: () => DEFAULT_RUNTIME_ORIGIN,
   agentHealthUrl: () => agentHealthUrl,
   buildAgentStorageKeyPrefix: () => buildAgentStorageKeyPrefix,
@@ -30,6 +31,8 @@ __export(index_exports, {
   formatAgentError: () => formatAgentError,
   getOrCreateVisitorSessionId: () => getOrCreateVisitorSessionId,
   loadPersistedAgentSession: () => loadPersistedAgentSession,
+  parseAgentToolResultEnvelope: () => parseAgentToolResultEnvelope,
+  parseAgentToolUiSurface: () => parseAgentToolUiSurface,
   pingAgentHealth: () => pingAgentHealth,
   resolveAgentRuntimeConfig: () => resolveAgentRuntimeConfig,
   savePersistedAgentSession: () => savePersistedAgentSession
@@ -42,6 +45,26 @@ var import_client2 = require("eve/client");
 // src/runtime/capability.ts
 var import_client = require("eve/client");
 var MAX_REFRESH_SKEW_MS = 3e4;
+var LOCAL_LOOPBACK_ORIGINS = [
+  "http://127.0.0.1:3010",
+  "http://127.0.0.1:3001"
+];
+function isLoopbackRuntimeOrigin(origin) {
+  try {
+    const host = new URL(origin).hostname;
+    return host === "127.0.0.1" || host === "localhost";
+  } catch {
+    return false;
+  }
+}
+function localBootstrapOrigins(origin) {
+  const normalized = origin.replace(/\/$/, "");
+  if (!isLoopbackRuntimeOrigin(normalized)) return [normalized];
+  return [
+    normalized,
+    ...LOCAL_LOOPBACK_ORIGINS.filter((candidate) => candidate !== normalized)
+  ];
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -88,20 +111,31 @@ function createAgentRuntimeCapability(options) {
         );
       }
     }
-    const response = await fetchImplementation(
-      `${options.runtimeOrigin}/webless/v1/bootstrap`,
-      {
-        body: JSON.stringify({
-          clientSessionId: options.visitorSessionId,
-          indexId: options.indexId,
-          ...previewBuildId ? { previewBuildId } : {},
-          ...previewGrant ? { previewGrant } : {},
-          version: options.version
-        }),
-        headers: { "content-type": "application/json" },
-        method: "POST"
+    const bootstrapBody = JSON.stringify({
+      clientSessionId: options.visitorSessionId,
+      indexId: options.indexId,
+      ...previewBuildId ? { previewBuildId } : {},
+      ...previewGrant ? { previewGrant } : {},
+      version: options.version
+    });
+    const postBootstrap = (origin) => fetchImplementation(`${origin}/webless/v1/bootstrap`, {
+      body: bootstrapBody,
+      headers: { "content-type": "application/json" },
+      method: "POST"
+    });
+    let response;
+    let lastError;
+    for (const origin of localBootstrapOrigins(options.runtimeOrigin)) {
+      try {
+        response = await postBootstrap(origin);
+        break;
+      } catch (error) {
+        lastError = error;
       }
-    );
+    }
+    if (!response) {
+      throw lastError instanceof Error ? lastError : new Error("Agent Runtime is unavailable.");
+    }
     if (!response.ok) {
       throw new Error(await readBootstrapError(response));
     }
@@ -272,6 +306,226 @@ function clearPersistedAgentSession(visitorSessionId, options) {
   sessionStorage.removeItem(runtimeLastMessageKey(visitorSessionId, prefix));
 }
 
+// src/runtime/tool-ui.ts
+var AGENT_TOOL_UI_SCHEMA_VERSION = "webless.tool-ui.v1";
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isJsonValue(value, seen = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return true;
+  }
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value !== "object") return false;
+  if (seen.has(value)) return false;
+  seen.add(value);
+  const valid = Array.isArray(value) ? value.every((item) => isJsonValue(item, seen)) : Object.entries(value).every(
+    ([key, item]) => typeof key === "string" && isJsonValue(item, seen)
+  );
+  seen.delete(value);
+  return valid;
+}
+function boundedString(value, max) {
+  if (typeof value !== "string" || value.trim().length === 0 || value.length > max) {
+    return void 0;
+  }
+  return value.trim();
+}
+function numberValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function integerValue(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 8e3 ? value : void 0;
+}
+function isFieldKind(value) {
+  return typeof value === "string" && [
+    "text",
+    "textarea",
+    "email",
+    "number",
+    "select",
+    "multi-select",
+    "checkbox",
+    "confirmation",
+    "radio",
+    "date",
+    "time",
+    "date-time",
+    "calendar",
+    "range",
+    "json"
+  ].includes(value);
+}
+function parseField(value) {
+  if (!isRecord2(value)) return null;
+  if (!hasOnlyKeys(value, [
+    "description",
+    "kind",
+    "label",
+    "max",
+    "maxItems",
+    "maxLength",
+    "min",
+    "minLength",
+    "options",
+    "path",
+    "placeholder",
+    "required",
+    "step",
+    "defaultValue"
+  ])) {
+    return null;
+  }
+  if (!isFieldKind(value.kind)) return null;
+  const path = boundedString(value.path, 160);
+  const label = boundedString(value.label, 160);
+  const description = value.description === void 0 ? void 0 : boundedString(value.description, 500);
+  const placeholder = value.placeholder === void 0 || typeof value.placeholder !== "string" ? void 0 : value.placeholder;
+  const required = value.required === void 0 || typeof value.required !== "boolean" ? void 0 : value.required;
+  const min = value.min === void 0 ? void 0 : numberValue(value.min);
+  const max = value.max === void 0 ? void 0 : numberValue(value.max);
+  const maxItems = value.maxItems === void 0 ? void 0 : integerValue(value.maxItems);
+  const step = value.step === void 0 ? void 0 : numberValue(value.step);
+  const minLength = value.minLength === void 0 ? void 0 : integerValue(value.minLength);
+  const maxLength = value.maxLength === void 0 ? void 0 : integerValue(value.maxLength);
+  const defaultValue = value.defaultValue === void 0 || !isJsonValue(value.defaultValue) ? void 0 : value.defaultValue;
+  if (!path || !/^[A-Za-z0-9_.[\]-]+$/u.test(path) || !label) {
+    return null;
+  }
+  if (value.description !== void 0 && !description) return null;
+  if (value.placeholder !== void 0 && placeholder === void 0) return null;
+  if (value.required !== void 0 && required === void 0) return null;
+  if (value.min !== void 0 && min === void 0) return null;
+  if (value.max !== void 0 && max === void 0) return null;
+  if (value.maxItems !== void 0 && (maxItems === void 0 || maxItems < 1 || maxItems > 100))
+    return null;
+  if (value.step !== void 0 && step === void 0) return null;
+  if (value.minLength !== void 0 && minLength === void 0) return null;
+  if (value.maxLength !== void 0 && maxLength === void 0) return null;
+  if (value.defaultValue !== void 0 && defaultValue === void 0)
+    return null;
+  if (value.options !== void 0) {
+    if (!Array.isArray(value.options) || value.options.length > 100)
+      return null;
+    for (const option of value.options) {
+      if (!isRecord2(option) || !boundedString(option.label, 160) || !isJsonValue(option.value)) {
+        return null;
+      }
+    }
+  }
+  return {
+    kind: value.kind,
+    path,
+    label,
+    ...description ? { description } : {},
+    ...placeholder !== void 0 ? { placeholder } : {},
+    ...required !== void 0 ? { required } : {},
+    ...defaultValue !== void 0 ? { defaultValue } : {},
+    ...value.options !== void 0 ? { options: value.options } : {},
+    ...min !== void 0 ? { min } : {},
+    ...max !== void 0 ? { max } : {},
+    ...maxItems !== void 0 ? { maxItems } : {},
+    ...step !== void 0 ? { step } : {},
+    ...minLength !== void 0 ? { minLength } : {},
+    ...maxLength !== void 0 ? { maxLength } : {}
+  };
+}
+function parseStep(value) {
+  if (!isRecord2(value)) return null;
+  if (!hasOnlyKeys(value, ["description", "fieldPaths", "id", "label"])) {
+    return null;
+  }
+  const id = boundedString(value.id, 80);
+  const label = boundedString(value.label, 160);
+  const description = value.description === void 0 ? void 0 : boundedString(value.description, 500);
+  if (!id || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/u.test(id) || !label || value.description !== void 0 && !description || !Array.isArray(value.fieldPaths) || value.fieldPaths.length < 1 || value.fieldPaths.length > 32 || value.fieldPaths.some(
+    (path) => typeof path !== "string" || !/^[A-Za-z0-9_.[\]-]+$/u.test(path) || path.length > 160
+  )) {
+    return null;
+  }
+  return {
+    id,
+    label,
+    fieldPaths: value.fieldPaths,
+    ...description ? { description } : {}
+  };
+}
+function parseAction(value) {
+  if (!isRecord2(value)) return null;
+  if (!hasOnlyKeys(value, ["id", "label"])) return null;
+  const label = boundedString(value.label, 80);
+  if (value.id !== "submit" && value.id !== "back" && value.id !== "next" && value.id !== "reset" || !label) {
+    return null;
+  }
+  return {
+    id: value.id,
+    label
+  };
+}
+function parseAgentToolUiSurface(value) {
+  if (!isRecord2(value) || value.schemaVersion !== AGENT_TOOL_UI_SCHEMA_VERSION)
+    return null;
+  if (!hasOnlyKeys(value, [
+    "actions",
+    "description",
+    "fields",
+    "id",
+    "operationId",
+    "requestId",
+    "schemaVersion",
+    "steps",
+    "submitLabel",
+    "title",
+    "toolSlug",
+    "values"
+  ])) {
+    return null;
+  }
+  const id = boundedString(value.id, 200);
+  const title = boundedString(value.title, 200);
+  const toolSlug = boundedString(value.toolSlug, 200);
+  const description = value.description === void 0 ? void 0 : boundedString(value.description, 800);
+  const operationId = value.operationId === void 0 ? void 0 : boundedString(value.operationId, 200);
+  const requestId = value.requestId === void 0 ? void 0 : boundedString(value.requestId, 200);
+  const submitLabel = value.submitLabel === void 0 ? void 0 : boundedString(value.submitLabel, 80);
+  if (!id || !title || !toolSlug || !Array.isArray(value.fields) || value.fields.length < 1 || value.fields.length > 32) {
+    return null;
+  }
+  const fields = value.fields.map(parseField);
+  if (fields.some((field) => field === null)) return null;
+  const steps = value.steps === void 0 ? void 0 : Array.isArray(value.steps) && value.steps.length <= 8 ? value.steps.map(parseStep) : null;
+  if (steps?.some((step) => step === null)) return null;
+  const actions = value.actions === void 0 ? void 0 : Array.isArray(value.actions) && value.actions.length <= 8 ? value.actions.map(parseAction) : null;
+  if (actions?.some((action) => action === null)) return null;
+  if (value.description !== void 0 && !description) return null;
+  if (value.operationId !== void 0 && !operationId) return null;
+  if (value.requestId !== void 0 && !requestId) return null;
+  if (value.submitLabel !== void 0 && !submitLabel) return null;
+  const values = value.values !== void 0 && isRecord2(value.values) ? value.values : void 0;
+  if (value.values !== void 0) {
+    if (!values || !Object.values(values).every((item) => isJsonValue(item)))
+      return null;
+  }
+  return {
+    schemaVersion: AGENT_TOOL_UI_SCHEMA_VERSION,
+    id,
+    title,
+    toolSlug,
+    fields,
+    ...actions ? { actions } : {},
+    ...description ? { description } : {},
+    ...operationId ? { operationId } : {},
+    ...requestId ? { requestId } : {},
+    ...submitLabel ? { submitLabel } : {},
+    ...steps ? { steps } : {},
+    ...values ? { values } : {}
+  };
+}
+function hasOnlyKeys(value, allowed) {
+  const allowedKeys = new Set(allowed);
+  return Object.keys(value).every((key) => allowedKeys.has(key));
+}
+
 // src/runtime/client.ts
 function isTurnBoundary(event) {
   return event.type === "session.waiting" || event.type === "session.completed" || event.type === "session.failed";
@@ -284,12 +538,8 @@ function applyMessageEvent(event, rendered, handlers, workItems) {
   if (event.type === "message.completed") {
     handlers.onComplete?.();
   }
-  if (event.type === "action.result") {
-    const result = event.data.result;
-    if (result && typeof result === "object" && "output" in result) {
-      handlers.onActionResult?.(result.output);
-    }
-  }
+  if (event.type === "action.result") emitActionResult(event, handlers);
+  if (event.type === "input.requested") emitInputRequests(event, handlers);
   if (event.type !== "message.appended") return rendered;
   const { messageDelta, messageSoFar } = event.data;
   let delta = messageDelta;
@@ -300,9 +550,45 @@ function applyMessageEvent(event, rendered, handlers, workItems) {
   } else if (messageDelta) {
     next += messageDelta;
   }
-  if (delta) handlers.onDelta(delta);
+  if (delta) handlers.onDelta?.(delta);
   return next;
 }
+function emitActionResult(event, handlers) {
+  const result = event.data.result;
+  if (result.kind === "tool-result") {
+    handlers.onToolResult?.({
+      callId: result.callId,
+      toolName: result.toolName,
+      status: event.data.status,
+      output: result.output,
+      ...event.data.error ? { error: event.data.error } : {}
+    });
+  }
+  if ("output" in result) handlers.onActionResult?.(result.output);
+}
+function emitInputRequests(event, handlers) {
+  handlers.onInputRequest?.(
+    event.data.requests.map((request) => {
+      const ui = parseAgentToolUiSurface(
+        request.ui
+      );
+      return {
+        requestId: request.requestId,
+        kind: request.kind,
+        prompt: request.prompt,
+        ...request.display ? { display: request.display } : {},
+        ...request.allowFreeform !== void 0 ? { allowFreeform: request.allowFreeform } : {},
+        ...request.options ? { options: request.options } : {},
+        ...ui ? { ui } : {},
+        action: {
+          callId: request.action.callId,
+          kind: "tool-call",
+          toolName: request.action.toolName
+        }
+      };
+    })
+  );
+}
 function isResumeTurnMessage(received, candidate) {
   if (received === candidate) return true;
   return Boolean(candidate) && received.endsWith(`
@@ -578,9 +864,11 @@ var AgentSession = class {
     let streamIndex = session?.state.streamIndex ?? 0;
     let rendered = "";
     const workItems = /* @__PURE__ */ new Map();
+    let requestedInput = false;
     try {
       for await (const event of response) {
         if (signal.aborted) break;
+        if (event.type === "input.requested") requestedInput = true;
         rendered = applyMessageEvent(event, rendered, handlers, workItems);
         streamIndex += 1;
         if (session) {
@@ -598,7 +886,7 @@ var AgentSession = class {
         this.persistSessionCursor(session);
       }
     }
-    if (!rendered.trim() && !signal.aborted) {
+    if (!rendered.trim() && !signal.aborted && !requestedInput) {
       throw new Error("Empty response from runtime");
     }
     return rendered.trim();
@@ -618,6 +906,9 @@ var AgentSession = class {
       () => attached.snapshot({ signal })
     );
     const turnEvents = latestTurnEvents(snapshot.events);
+    const hasInputRequest = turnEvents.some(
+      (event) => event.type === "input.requested"
+    );
     const received = turnEvents[0];
     const lastSent = persisted.lastMessage;
     const inFlight = !turnEvents.some((event) => isTurnBoundary(event));
@@ -628,6 +919,8 @@ var AgentSession = class {
     const workItems = /* @__PURE__ */ new Map();
     for (const event of turnEvents) {
       applyWorkEvent(event, handlers, workItems);
+      if (event.type === "input.requested") emitInputRequests(event, handlers);
+      if (event.type === "action.result") emitActionResult(event, handlers);
     }
     if (rendered.startsWith(initialText)) {
       const missedText = rendered.slice(initialText.length);
@@ -657,7 +950,9 @@ var AgentSession = class {
         );
       }
       handlers.onComplete?.();
-      if (!rendered.trim()) throw new Error("Empty response from runtime");
+      if (!rendered.trim() && !hasInputRequest) {
+        throw new Error("Empty response from runtime");
+      }
       return rendered.trim();
     }
     let streamIndex = snapshot.session.streamIndex;
@@ -676,7 +971,55 @@ var AgentSession = class {
     session = client.sessions.attach(session.state.sessionId, { streamIndex });
     this.session = session;
     this.persistSessionCursor(session);
-    if (!rendered.trim() && !signal.aborted) {
+    if (!rendered.trim() && !signal.aborted && !hasInputRequest) {
+      throw new Error("Empty response from runtime");
+    }
+    return rendered.trim();
+  }
+  async respondTurn(responses, signal, handlers) {
+    const client = this.ensureClient();
+    const session = this.session ?? this.attachPersistedSession(client);
+    if (!session) {
+      throw new Error("No active session is waiting for input.");
+    }
+    this.session = session;
+    const inputResponses = responses.map(
+      ({ requestId, optionId, text }) => ({
+        requestId,
+        ...optionId ? { optionId } : {},
+        ...text ? { text } : {}
+      })
+    );
+    const response = await withCapabilityRefresh(
+      this.capability,
+      () => session.respond(inputResponses, { signal })
+    );
+    this.activeResponse = response;
+    let streamIndex = session.state.streamIndex;
+    let rendered = "";
+    let requestedInput = false;
+    const workItems = /* @__PURE__ */ new Map();
+    try {
+      for await (const event of response) {
+        if (signal.aborted) break;
+        if (event.type === "input.requested") requestedInput = true;
+        rendered = applyMessageEvent(event, rendered, handlers, workItems);
+        streamIndex += 1;
+        savePersistedAgentSession(
+          this.visitorSessionId,
+          session.state.sessionId,
+          streamIndex,
+          this.storeOptions
+        );
+      }
+    } finally {
+      this.activeResponse = void 0;
+      this.session = client.sessions.attach(session.state.sessionId, {
+        streamIndex
+      });
+      this.persistSessionCursor(this.session);
+    }
+    if (!rendered.trim() && !signal.aborted && !requestedInput) {
       throw new Error("Empty response from runtime");
     }
     return rendered.trim();
@@ -736,6 +1079,11 @@ function createAgentClient(options) {
       resumeOptions.handlers,
       resumeOptions.initialText
     ),
+    respondTurn: (respondOptions) => session.respondTurn(
+      respondOptions.responses,
+      respondOptions.signal ?? new AbortController().signal,
+      respondOptions.handlers
+    ),
     reset: () => session.reset(),
     cancelActive: () => session.cancelActive(),
     getActiveSessionId: () => session.getActiveSessionId()
@@ -785,6 +1133,63 @@ function formatAgentError(error) {
   return TRANSIENT_AGENT_ERROR_MESSAGE;
 }
 
+// src/runtime/tool-result-envelope.ts
+var ENVELOPE_KEYS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "output",
+  "presentationKinds",
+  "ui"
+]);
+function isRecord3(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isJsonValue2(value, seen = /* @__PURE__ */ new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return true;
+  }
+  if (typeof value === "number") return Number.isFinite(value);
+  if (typeof value !== "object") return false;
+  if (seen.has(value)) return false;
+  seen.add(value);
+  const valid = Array.isArray(value) ? value.every((item) => isJsonValue2(item, seen)) : Object.entries(value).every(
+    ([key, item]) => typeof key === "string" && isJsonValue2(item, seen)
+  );
+  seen.delete(value);
+  return valid;
+}
+function decodeEnvelope(value) {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+function parseAgentToolResultEnvelope(value) {
+  const decoded = decodeEnvelope(value);
+  if (!isRecord3(decoded)) return null;
+  const keys = Object.keys(decoded);
+  if (keys.some((key) => !ENVELOPE_KEYS.has(key)) || decoded.schemaVersion !== "webless.tool-result.v1" || !isJsonValue2(decoded.output) || !Array.isArray(decoded.presentationKinds) || decoded.presentationKinds.length < 1 || decoded.presentationKinds.length > 16) {
+    return null;
+  }
+  const presentationKinds = decoded.presentationKinds.flatMap((kind) => {
+    if (typeof kind !== "string") return [];
+    const normalized = kind.trim();
+    return normalized && normalized.length <= 128 ? [normalized] : [];
+  });
+  if (presentationKinds.length !== decoded.presentationKinds.length) {
+    return null;
+  }
+  const ui = decoded.ui === void 0 ? void 0 : parseAgentToolUiSurface(decoded.ui);
+  if (decoded.ui !== void 0 && !ui) return null;
+  return {
+    schemaVersion: "webless.tool-result.v1",
+    output: decoded.output,
+    presentationKinds,
+    ...ui ? { ui } : {}
+  };
+}
+
 // src/runtime/health.ts
 async function pingAgentHealth(runtimeOrigin, fetchImpl = fetch) {
   const healthUrl = agentHealthUrl(runtimeOrigin);
@@ -807,6 +1212,7 @@ async function pingAgentHealth(runtimeOrigin, fetchImpl = fetch) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AGENT_TOOL_UI_SCHEMA_VERSION,
   DEFAULT_RUNTIME_ORIGIN,
   agentHealthUrl,
   buildAgentStorageKeyPrefix,
@@ -817,6 +1223,8 @@ async function pingAgentHealth(runtimeOrigin, fetchImpl = fetch) {
   formatAgentError,
   getOrCreateVisitorSessionId,
   loadPersistedAgentSession,
+  parseAgentToolResultEnvelope,
+  parseAgentToolUiSurface,
   pingAgentHealth,
   resolveAgentRuntimeConfig,
   savePersistedAgentSession