@webless/agent 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { d as AgentClientOptions, c as AgentClient, f as AgentIndexVersion, l as AgentRuntimeConfig, e as AgentHealthResult, P as PersistedAgentSession } from './types-B2j6hbI5.js';
-export { A as AGENT_STRUCTURED_TOOL_INPUT_HEADER, a as AGENT_STRUCTURED_TOOL_INPUT_SCHEMA_VERSION, b as AGENT_TOOL_UI_SCHEMA_VERSION, g as AgentInputOption, h as AgentInputRequest, i as AgentInputResponse, j as AgentRespondTurnOptions, k as AgentResumeTurnOptions, m as AgentSendTurnOptions, n as AgentStreamHandlers, o as AgentStructuredToolInput, p as AgentToolResult, q as AgentToolResultEnvelope, r as AgentToolResultJsonValue, s as AgentToolUiAction, t as AgentToolUiField, u as AgentToolUiFieldKind, v as AgentToolUiOption, w as AgentToolUiStep, x as AgentToolUiSurface, y as AgentWorkItem, z as formatAgentStructuredToolInput, B as parseAgentToolResultEnvelope, C as parseAgentToolUiSurface } from './types-B2j6hbI5.js';
+import { d as AgentClientOptions, c as AgentClient, h as AgentIndexVersion, n as AgentRuntimeConfig, g as AgentHealthResult, P as PersistedAgentSession } from './types-4lTJW5mp.js';
+export { A as AGENT_STRUCTURED_TOOL_INPUT_HEADER, a as AGENT_STRUCTURED_TOOL_INPUT_SCHEMA_VERSION, b as AGENT_TOOL_UI_SCHEMA_VERSION, e as AgentHandoffClient, f as AgentHandoffCommand, o as AgentHandoffEvent, p as AgentHandoffPage, q as AgentHandoffStatus, i as AgentInputOption, j as AgentInputRequest, k as AgentInputResponse, l as AgentRespondTurnOptions, m as AgentResumeTurnOptions, r as AgentSendTurnOptions, s as AgentStreamHandlers, t as AgentStructuredToolInput, u as AgentToolResult, v as AgentToolResultEnvelope, w as AgentToolResultJsonValue, x as AgentToolUiAction, y as AgentToolUiField, z as AgentToolUiFieldKind, B as AgentToolUiOption, C as AgentToolUiStep, D as AgentToolUiSurface, E as AgentWorkItem, F as formatAgentStructuredToolInput, G as parseAgentToolResultEnvelope, H as parseAgentToolUiSurface } from './types-4lTJW5mp.js';
+import 'zod';
 
 declare function createAgentClient(options: AgentClientOptions): AgentClient;
 

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;
@@ -169,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(/\/+$/, "");
@@ -768,6 +1032,11 @@ var AgentSession = class {
       version,
       visitorSessionId
     });
+    this.handoff = createHandoffClient({
+      getClient: () => this.ensureClient(),
+      getSessionId: () => this.getActiveSessionId(),
+      capability: this.capability
+    });
   }
   indexId;
   version;
@@ -780,6 +1049,7 @@ var AgentSession = class {
   activeResponse;
   childStreams;
   capability;
+  handoff;
   getActiveSessionId() {
     return this.session?.state.sessionId ?? loadPersistedAgentSession(this.visitorSessionId, this.storeOptions)?.sessionId;
   }
@@ -890,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;
@@ -1064,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(
@@ -1157,6 +1427,7 @@ function createAgentClient(options) {
   );
   return {
     indexId,
+    handoff: session.handoff,
     version,
     runtimeOrigin,
     visitorSessionId,
@@ -1188,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) {
@@ -1200,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().";
     }