@webless/agent 0.10.4 → 0.12.0

package/dist/index.js

@@ -12,9 +12,204 @@ import {
 // src/runtime/client.ts
 import {
   Client,
-  ClientError as ClientError2
+  ClientError as ClientError3
 } from "eve/client";
 
+// src/runtime/handoff.ts
+import { ClientError as ClientError2 } from "eve/client";
+
+// src/runtime/generated/handoff-contract.ts
+import { z } from "zod";
+var id = z.string().min(1).max(200);
+var sequence = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+var text = z.string().trim().min(1).max(16e3);
+var agentRuntimeHandoffVersion = "webless.ai/agent-runtime-handoff/v1";
+var agentRuntimeHandoffStatusSchema = z.enum([
+  "ai",
+  "requesting",
+  "queued",
+  "human",
+  "resolved",
+  "failed"
+]);
+var agentRuntimeHandoffActorSchema = z.strictObject({
+  id,
+  name: z.string().trim().min(1).max(200)
+});
+var eventBase = {
+  id,
+  sequence: sequence.refine((value) => value > 0),
+  handoffId: id,
+  epoch: sequence.refine((value) => value > 0),
+  createdAt: z.iso.datetime()
+};
+var agentRuntimeHandoffEventSchema = z.discriminatedUnion("type", [
+  z.strictObject({
+    ...eventBase,
+    type: z.literal("status"),
+    status: agentRuntimeHandoffStatusSchema,
+    actor: agentRuntimeHandoffActorSchema.nullable()
+  }),
+  z.strictObject({
+    ...eventBase,
+    type: z.literal("visitor.message"),
+    message: text,
+    operationId: id
+  }),
+  z.strictObject({
+    ...eventBase,
+    type: z.literal("human.message"),
+    message: text,
+    actor: agentRuntimeHandoffActorSchema
+  })
+]);
+var agentRuntimeHandoffReadRequestSchema = z.strictObject({
+  after: sequence.default(0)
+});
+var agentRuntimeHandoffPageSchema = z.strictObject({
+  apiVersion: z.literal(agentRuntimeHandoffVersion),
+  sessionId: id,
+  enabled: z.boolean(),
+  status: agentRuntimeHandoffStatusSchema,
+  handoffId: id.nullable(),
+  epoch: sequence,
+  after: sequence,
+  cursor: sequence,
+  hasMore: z.boolean(),
+  events: z.array(agentRuntimeHandoffEventSchema).max(100)
+}).superRefine((page, ctx) => {
+  let cursor = page.after;
+  let previousEpoch = 0;
+  const statuses = /* @__PURE__ */ new Map();
+  const ids = /* @__PURE__ */ new Set();
+  const handoffs = /* @__PURE__ */ new Map();
+  const terminalEpochs = /* @__PURE__ */ new Set();
+  let currentStatus;
+  for (const event of page.events) {
+    if (event.epoch < previousEpoch)
+      ctx.addIssue({
+        code: "custom",
+        message: "Handoff epochs cannot decrease."
+      });
+    previousEpoch = event.epoch;
+    if (ids.has(event.id))
+      ctx.addIssue({
+        code: "custom",
+        message: "Duplicate handoff event ID."
+      });
+    ids.add(event.id);
+    const handoffId = handoffs.get(event.epoch);
+    if (handoffId !== void 0 && handoffId !== event.handoffId || event.epoch === page.epoch && event.handoffId !== page.handoffId)
+      ctx.addIssue({
+        code: "custom",
+        message: "Inconsistent handoff epoch identity."
+      });
+    handoffs.set(event.epoch, event.handoffId);
+    if (terminalEpochs.has(event.epoch) && (event.type !== "status" || event.status !== "ai"))
+      ctx.addIssue({
+        code: "custom",
+        message: "Handoff event follows resolution."
+      });
+    if (event.type === "status") {
+      if (event.status === "human" && event.actor === null)
+        ctx.addIssue({
+          code: "custom",
+          message: "Human ownership requires a representative."
+        });
+      const previous = statuses.get(event.epoch);
+      const transitions = {
+        ai: [],
+        requesting: ["queued", "resolved", "failed"],
+        queued: ["human", "resolved", "failed"],
+        human: ["resolved", "failed"],
+        resolved: ["ai"],
+        failed: []
+      };
+      if (previous !== void 0 && !transitions[previous].includes(event.status))
+        ctx.addIssue({
+          code: "custom",
+          message: "Invalid handoff ownership transition."
+        });
+      statuses.set(event.epoch, event.status);
+      if (["resolved", "failed", "ai"].includes(event.status))
+        terminalEpochs.add(event.epoch);
+      if (event.epoch === page.epoch) currentStatus = event.status;
+    }
+    if (event.sequence !== cursor + 1) {
+      ctx.addIssue({
+        code: "custom",
+        message: "Handoff event gap or replay."
+      });
+    }
+    cursor = event.sequence;
+    if (event.epoch > page.epoch) {
+      ctx.addIssue({
+        code: "custom",
+        message: "Event exceeds current epoch."
+      });
+    }
+  }
+  if (!page.hasMore && currentStatus !== void 0 && currentStatus !== page.status)
+    ctx.addIssue({
+      code: "custom",
+      message: "Handoff ownership contradicts its final status event."
+    });
+  if (page.cursor !== cursor || page.hasMore && page.events.length === 0) {
+    ctx.addIssue({ code: "custom", message: "Invalid handoff page cursor." });
+  }
+  if (page.epoch === 0 !== (page.handoffId === null)) {
+    ctx.addIssue({ code: "custom", message: "Invalid handoff identity." });
+  }
+  if (page.handoffId === null && page.status !== "ai") {
+    ctx.addIssue({
+      code: "custom",
+      message: "Handoff identity is required."
+    });
+  }
+});
+var agentRuntimeHandoffStartSchema = z.strictObject({
+  operationId: id
+});
+var agentRuntimeHandoffCommandSchema = z.strictObject({
+  operationId: id,
+  handoffId: id,
+  epoch: sequence.refine((value) => value > 0)
+});
+var agentRuntimeHandoffMessageSchema = agentRuntimeHandoffCommandSchema.extend({ message: text });
+var agentRuntimeHandoffBindingSchema = z.strictObject({
+  tenantId: id,
+  indexId: id,
+  visitorSubject: id,
+  sessionId: id,
+  handoffId: id,
+  epoch: sequence.refine((value) => value > 0)
+});
+var providerEventBase = {
+  apiVersion: z.literal(agentRuntimeHandoffVersion),
+  binding: agentRuntimeHandoffBindingSchema,
+  eventId: id,
+  sequence: sequence.refine((value) => value > 0)
+};
+var agentRuntimeHandoffProviderEventSchema = z.discriminatedUnion(
+  "type",
+  [
+    z.strictObject({ ...providerEventBase, type: z.literal("queued") }),
+    z.strictObject({
+      ...providerEventBase,
+      type: z.literal("assigned"),
+      actor: agentRuntimeHandoffActorSchema
+    }),
+    z.strictObject({
+      ...providerEventBase,
+      type: z.literal("human.message"),
+      actor: agentRuntimeHandoffActorSchema,
+      message: text
+    }),
+    z.strictObject({ ...providerEventBase, type: z.literal("resolved") }),
+    z.strictObject({ ...providerEventBase, type: z.literal("failed") })
+  ]
+);
+
 // src/runtime/capability.ts
 import { ClientError } from "eve/client";
 var MAX_REFRESH_SKEW_MS = 3e4;
@@ -84,18 +279,26 @@ function createAgentRuntimeCapability(options) {
         );
       }
     }
-    const bootstrapBody = JSON.stringify({
+    const bootstrapBody = {
       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"
-    });
+    };
+    const postBootstrap = async (origin) => {
+      const send = (advertiseLocation) => fetchImplementation(`${origin}/webless/v1/bootstrap`, {
+        body: JSON.stringify({ ...bootstrapBody, ...advertiseLocation ? { locationConsent: "v1" } : {} }),
+        headers: { "content-type": "application/json" },
+        method: "POST"
+      });
+      const response2 = await send(Boolean(options.locationConsent));
+      if (options.locationConsent && response2.status === 400) {
+        const error = await response2.clone().json().catch(() => null);
+        if (isRecord(error) && error.code === "invalid_request") return send(false);
+      }
+      return response2;
+    };
     let response;
     let lastError;
     for (const origin of localBootstrapOrigins(options.runtimeOrigin)) {
@@ -161,6 +364,75 @@ async function withCapabilityRefresh(capability, request) {
   }
 }
 
+// src/runtime/handoff.ts
+function createHandoffClient(options) {
+  const target = () => {
+    const sessionId = options.getSessionId();
+    if (!sessionId)
+      throw new Error(
+        "Start a conversation before requesting a representative."
+      );
+    return {
+      sessionId,
+      path: `/webless/v1/session/${encodeURIComponent(sessionId)}/handoff`
+    };
+  };
+  const request = (path, init) => withCapabilityRefresh(options.capability, async () => {
+    const response = await options.getClient().fetch(path, {
+      ...init,
+      cache: "no-store",
+      redirect: "error"
+    });
+    if (!response.ok) {
+      throw new ClientError2(
+        response.status,
+        await response.text(),
+        response.headers
+      );
+    }
+    return response;
+  });
+  const command = async (suffix, body, signal) => {
+    const { path } = target();
+    await request(path + suffix, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal
+    });
+  };
+  return {
+    async read(input = {}) {
+      const { after } = agentRuntimeHandoffReadRequestSchema.parse({
+        after: input.after
+      });
+      const { sessionId, path } = target();
+      const response = await request(`${path}?after=${after}`, {
+        signal: input.signal
+      });
+      const value = await response.json();
+      const page = agentRuntimeHandoffPageSchema.parse(value);
+      if (page.sessionId !== sessionId || page.after !== after) {
+        throw new Error(
+          "The handoff response does not belong to this conversation or cursor."
+        );
+      }
+      return page;
+    },
+    start: (operationId, signal) => command(
+      "",
+      agentRuntimeHandoffStartSchema.parse({ operationId }),
+      signal
+    ),
+    send: (input, signal) => command(
+      "/messages",
+      agentRuntimeHandoffMessageSchema.parse(input),
+      signal
+    ),
+    returnToAI: (input, signal) => command("/return", agentRuntimeHandoffCommandSchema.parse(input), signal)
+  };
+}
+
 // src/runtime/config.ts
 var DEFAULT_RUNTIME_ORIGIN = "https://runtime.staging.webless.ai";
 var trimTrailingSlash = (value) => value.replace(/\/+$/, "");
@@ -639,6 +911,7 @@ function specialistNameFromInput(input) {
   return match?.[1]?.trim() || void 0;
 }
 function requestedWorkItem(action) {
+  if (action.kind === "tool-call" && action.toolName === "request_location") return null;
   if (action.kind === "tool-call" && action.toolName === "search_discovery") {
     return {
       id: action.callId,
@@ -744,13 +1017,14 @@ function applyWorkEvent(event, handlers, workItems) {
   );
 }
 var AgentSession = class {
-  constructor(indexId, version, runtimeOrigin, visitorSessionId, storeOptions, previewBuildId, getUnpublishedPreviewGrant) {
+  constructor(indexId, version, runtimeOrigin, visitorSessionId, storeOptions, previewBuildId, getUnpublishedPreviewGrant, locationConsent) {
     this.indexId = indexId;
     this.version = version;
     this.runtimeOrigin = runtimeOrigin;
     this.visitorSessionId = visitorSessionId;
     this.storeOptions = storeOptions;
     this.capability = createAgentRuntimeCapability({
+      locationConsent,
       getUnpublishedPreviewGrant,
       indexId,
       previewBuildId,
@@ -758,6 +1032,11 @@ var AgentSession = class {
       version,
       visitorSessionId
     });
+    this.handoff = createHandoffClient({
+      getClient: () => this.ensureClient(),
+      getSessionId: () => this.getActiveSessionId(),
+      capability: this.capability
+    });
   }
   indexId;
   version;
@@ -770,6 +1049,7 @@ var AgentSession = class {
   activeResponse;
   childStreams;
   capability;
+  handoff;
   getActiveSessionId() {
     return this.session?.state.sessionId ?? loadPersistedAgentSession(this.visitorSessionId, this.storeOptions)?.sessionId;
   }
@@ -880,7 +1160,7 @@ var AgentSession = class {
           () => activeSession.send(message, { signal })
         );
       } catch (error) {
-        if (error instanceof ClientError2 && error.status === 409 && error.code === "session_not_active") {
+        if (error instanceof ClientError3 && error.status === 409 && error.code === "session_not_active") {
           clearPersistedAgentSession(this.visitorSessionId, this.storeOptions);
           this.session = void 0;
           session = void 0;
@@ -1054,10 +1334,10 @@ var AgentSession = class {
     }
     this.session = session;
     const inputResponses = responses.map(
-      ({ requestId, optionId, text }) => ({
+      ({ requestId, optionId, text: text2 }) => ({
         requestId,
         ...optionId ? { optionId } : {},
-        ...text ? { text } : {}
+        ...text2 ? { text: text2 } : {}
       })
     );
     const response = await withCapabilityRefresh(
@@ -1142,10 +1422,12 @@ function createAgentClient(options) {
     visitorSessionId,
     storeOptions,
     options.previewBuildId,
-    options.getUnpublishedPreviewGrant
+    options.getUnpublishedPreviewGrant,
+    options.locationConsent
   );
   return {
     indexId,
+    handoff: session.handoff,
     version,
     runtimeOrigin,
     visitorSessionId,
@@ -1177,7 +1459,7 @@ function createAgentClient(options) {
 }
 
 // src/runtime/errors.ts
-import { ClientError as ClientError3 } from "eve/client";
+import { ClientError as ClientError4 } from "eve/client";
 var TRANSIENT_AGENT_ERROR_MESSAGE = "The agent run stopped before the action finished. Please try again.";
 var PREVIEW_AUTHORIZATION_ERROR_MESSAGE = "This preview could not be authorized. Open the latest preview from Webless.";
 function isTransientRuntimeMessage(message) {
@@ -1189,7 +1471,7 @@ function isPreviewAuthorizationMessage(message) {
   return normalized.includes("unpublished preview authorization") || normalized.includes("unpublished preview grant") || normalized.includes("agent studio preview grant") || normalized.includes("preview authorization");
 }
 function formatAgentError(error) {
-  if (error instanceof ClientError3) {
+  if (error instanceof ClientError4) {
     if (error.status === 401 && error.code === "index_required") {
       return "Missing indexId \u2014 pass a published index id to createAgentClient().";
     }