@webless/agent 0.11.0 → 0.12.0

package/dist/embed.d.cts

@@ -1,6 +1,7 @@
 import { Root } from 'react-dom/client';
-import { u as AgentTagManifest, N as NormalizedAgentTagManifest } from './panel-controller-rxR75tRa.cjs';
-export { e as AgentIndexVersion, j as AgentMountStrategy, k as AgentPanelSubmitOptions, l as AgentPlacementConfig, s as AgentTabSide, t as AgentTabVariant, J as DEFAULT_AGENT_PLACEMENT, a1 as normalizeAgentPlacement, a2 as normalizeAgentTagManifest, a4 as resetAgentPanel, a5 as submitAgentPanel } from './panel-controller-rxR75tRa.cjs';
+import { w as AgentTagManifest, O as NormalizedAgentTagManifest } from './panel-controller-CYoivbYB.cjs';
+export { f as AgentIndexVersion, k as AgentMountStrategy, l as AgentPanelSubmitOptions, m as AgentPlacementConfig, u as AgentTabSide, v as AgentTabVariant, L as DEFAULT_AGENT_PLACEMENT, a3 as normalizeAgentPlacement, a4 as normalizeAgentTagManifest, a6 as resetAgentPanel, a7 as submitAgentPanel } from './panel-controller-CYoivbYB.cjs';
+import 'zod';
 import 'react';
 
 type AgentRuntimeHandle = {

package/dist/embed.d.ts

@@ -1,6 +1,7 @@
 import { Root } from 'react-dom/client';
-import { u as AgentTagManifest, N as NormalizedAgentTagManifest } from './panel-controller-rxR75tRa.js';
-export { e as AgentIndexVersion, j as AgentMountStrategy, k as AgentPanelSubmitOptions, l as AgentPlacementConfig, s as AgentTabSide, t as AgentTabVariant, J as DEFAULT_AGENT_PLACEMENT, a1 as normalizeAgentPlacement, a2 as normalizeAgentTagManifest, a4 as resetAgentPanel, a5 as submitAgentPanel } from './panel-controller-rxR75tRa.js';
+import { w as AgentTagManifest, O as NormalizedAgentTagManifest } from './panel-controller-CYoivbYB.js';
+export { f as AgentIndexVersion, k as AgentMountStrategy, l as AgentPanelSubmitOptions, m as AgentPlacementConfig, u as AgentTabSide, v as AgentTabVariant, L as DEFAULT_AGENT_PLACEMENT, a3 as normalizeAgentPlacement, a4 as normalizeAgentTagManifest, a6 as resetAgentPanel, a7 as submitAgentPanel } from './panel-controller-CYoivbYB.js';
+import 'zod';
 import 'react';
 
 type AgentRuntimeHandle = {

package/dist/embed.js

@@ -9,7 +9,7 @@ import {
   resetAgentPanel,
   resolveAgentRuntimeConfig,
   submitAgentPanel
-} from "./chunk-NW37MHU7.js";
+} from "./chunk-EVWZF34F.js";
 
 // src/embed/mount.tsx
 import { createRoot } from "react-dom/client";

package/dist/index.cjs

@@ -182,16 +182,16 @@ function parseStep(value) {
   if (!hasOnlyKeys(value, ["description", "fieldPaths", "id", "label"])) {
     return null;
   }
-  const id = boundedString(value.id, 80);
+  const id2 = 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(
+  if (!id2 || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/u.test(id2) || !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,
+    id: id2,
     label,
     fieldPaths: value.fieldPaths,
     ...description ? { description } : {}
@@ -228,14 +228,14 @@ function parseAgentToolUiSurface(value) {
   ])) {
     return null;
   }
-  const id = boundedString(value.id, 200);
+  const id2 = 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) {
+  if (!id2 || !title || !toolSlug || !Array.isArray(value.fields) || value.fields.length < 1 || value.fields.length > 32) {
     return null;
   }
   const fields = value.fields.map(parseField);
@@ -255,7 +255,7 @@ function parseAgentToolUiSurface(value) {
   }
   return {
     schemaVersion: AGENT_TOOL_UI_SCHEMA_VERSION,
-    id,
+    id: id2,
     title,
     toolSlug,
     fields,
@@ -366,8 +366,203 @@ function completeConnectedToolWork(item, result) {
 }
 
 // src/runtime/client.ts
+var import_client3 = require("eve/client");
+
+// src/runtime/handoff.ts
 var import_client2 = require("eve/client");
 
+// src/runtime/generated/handoff-contract.ts
+var import_zod = require("zod");
+var id = import_zod.z.string().min(1).max(200);
+var sequence = import_zod.z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+var text = import_zod.z.string().trim().min(1).max(16e3);
+var agentRuntimeHandoffVersion = "webless.ai/agent-runtime-handoff/v1";
+var agentRuntimeHandoffStatusSchema = import_zod.z.enum([
+  "ai",
+  "requesting",
+  "queued",
+  "human",
+  "resolved",
+  "failed"
+]);
+var agentRuntimeHandoffActorSchema = import_zod.z.strictObject({
+  id,
+  name: import_zod.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: import_zod.z.iso.datetime()
+};
+var agentRuntimeHandoffEventSchema = import_zod.z.discriminatedUnion("type", [
+  import_zod.z.strictObject({
+    ...eventBase,
+    type: import_zod.z.literal("status"),
+    status: agentRuntimeHandoffStatusSchema,
+    actor: agentRuntimeHandoffActorSchema.nullable()
+  }),
+  import_zod.z.strictObject({
+    ...eventBase,
+    type: import_zod.z.literal("visitor.message"),
+    message: text,
+    operationId: id
+  }),
+  import_zod.z.strictObject({
+    ...eventBase,
+    type: import_zod.z.literal("human.message"),
+    message: text,
+    actor: agentRuntimeHandoffActorSchema
+  })
+]);
+var agentRuntimeHandoffReadRequestSchema = import_zod.z.strictObject({
+  after: sequence.default(0)
+});
+var agentRuntimeHandoffPageSchema = import_zod.z.strictObject({
+  apiVersion: import_zod.z.literal(agentRuntimeHandoffVersion),
+  sessionId: id,
+  enabled: import_zod.z.boolean(),
+  status: agentRuntimeHandoffStatusSchema,
+  handoffId: id.nullable(),
+  epoch: sequence,
+  after: sequence,
+  cursor: sequence,
+  hasMore: import_zod.z.boolean(),
+  events: import_zod.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 = import_zod.z.strictObject({
+  operationId: id
+});
+var agentRuntimeHandoffCommandSchema = import_zod.z.strictObject({
+  operationId: id,
+  handoffId: id,
+  epoch: sequence.refine((value) => value > 0)
+});
+var agentRuntimeHandoffMessageSchema = agentRuntimeHandoffCommandSchema.extend({ message: text });
+var agentRuntimeHandoffBindingSchema = import_zod.z.strictObject({
+  tenantId: id,
+  indexId: id,
+  visitorSubject: id,
+  sessionId: id,
+  handoffId: id,
+  epoch: sequence.refine((value) => value > 0)
+});
+var providerEventBase = {
+  apiVersion: import_zod.z.literal(agentRuntimeHandoffVersion),
+  binding: agentRuntimeHandoffBindingSchema,
+  eventId: id,
+  sequence: sequence.refine((value) => value > 0)
+};
+var agentRuntimeHandoffProviderEventSchema = import_zod.z.discriminatedUnion(
+  "type",
+  [
+    import_zod.z.strictObject({ ...providerEventBase, type: import_zod.z.literal("queued") }),
+    import_zod.z.strictObject({
+      ...providerEventBase,
+      type: import_zod.z.literal("assigned"),
+      actor: agentRuntimeHandoffActorSchema
+    }),
+    import_zod.z.strictObject({
+      ...providerEventBase,
+      type: import_zod.z.literal("human.message"),
+      actor: agentRuntimeHandoffActorSchema,
+      message: text
+    }),
+    import_zod.z.strictObject({ ...providerEventBase, type: import_zod.z.literal("resolved") }),
+    import_zod.z.strictObject({ ...providerEventBase, type: import_zod.z.literal("failed") })
+  ]
+);
+
 // src/runtime/capability.ts
 var import_client = require("eve/client");
 var MAX_REFRESH_SKEW_MS = 3e4;
@@ -522,6 +717,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 import_client2.ClientError(
+        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(/\/+$/, "");
@@ -1121,6 +1385,11 @@ var AgentSession = class {
       version,
       visitorSessionId
     });
+    this.handoff = createHandoffClient({
+      getClient: () => this.ensureClient(),
+      getSessionId: () => this.getActiveSessionId(),
+      capability: this.capability
+    });
   }
   indexId;
   version;
@@ -1133,6 +1402,7 @@ var AgentSession = class {
   activeResponse;
   childStreams;
   capability;
+  handoff;
   getActiveSessionId() {
     return this.session?.state.sessionId ?? loadPersistedAgentSession(this.visitorSessionId, this.storeOptions)?.sessionId;
   }
@@ -1207,7 +1477,7 @@ var AgentSession = class {
     }
     this.activeResponse = void 0;
     this.session = void 0;
-    this.client = new import_client2.Client({
+    this.client = new import_client3.Client({
       auth: { bearer: () => this.capability.getAccessToken() },
       host: config.host,
       redirect: "error"
@@ -1243,7 +1513,7 @@ var AgentSession = class {
           () => activeSession.send(message, { signal })
         );
       } catch (error) {
-        if (error instanceof import_client2.ClientError && error.status === 409 && error.code === "session_not_active") {
+        if (error instanceof import_client3.ClientError && error.status === 409 && error.code === "session_not_active") {
           clearPersistedAgentSession(this.visitorSessionId, this.storeOptions);
           this.session = void 0;
           session = void 0;
@@ -1417,10 +1687,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(
@@ -1510,6 +1780,7 @@ function createAgentClient(options) {
   );
   return {
     indexId,
+    handoff: session.handoff,
     version,
     runtimeOrigin,
     visitorSessionId,
@@ -1541,7 +1812,7 @@ function createAgentClient(options) {
 }
 
 // src/runtime/errors.ts
-var import_client3 = require("eve/client");
+var import_client4 = require("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) {
@@ -1553,7 +1824,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 import_client3.ClientError) {
+  if (error instanceof import_client4.ClientError) {
     if (error.status === 401 && error.code === "index_required") {
       return "Missing indexId \u2014 pass a published index id to createAgentClient().";
     }