langwatch 1.19.0 → 1.20.0

package/dist/agent/index.js

@@ -32,9 +32,11 @@ var agent_exports = {};
 __export(agent_exports, {
   AGENT_TRANSPORTS: () => AGENT_TRANSPORTS,
   AgentParameterError: () => AgentParameterError,
+  AgentStateError: () => AgentStateError,
   DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
   MAX_TIMEOUT_MS: () => MAX_TIMEOUT_MS,
   PROTOCOL_VERSION: () => PROTOCOL_VERSION,
+  STATE_MAX_BYTES: () => STATE_MAX_BYTES,
   connectAgent: () => connectAgent,
   normalizeReply: () => normalizeReply,
   parameterSpecsFromSchema: () => parameterSpecsFromSchema,
@@ -83,11 +85,11 @@ var ConsoleLogger = class {
 var import_api = require("@opentelemetry/api");
 
 // src/agent/identity.ts
-var os = __toESM(require("os"));
 var import_node_crypto = require("crypto");
+var os = __toESM(require("os"));
 
 // package.json
-var version = "1.19.0";
+var version = "1.20.0";
 
 // src/internal/constants.ts
 var LANGWATCH_SDK_VERSION = version;
@@ -145,7 +147,9 @@ function resolveEnabled({
   env = process.env
 }) {
   const flag = env.LANGWATCH_AGENT_CONNECT;
-  if (isSet2(flag) && !isTruthy(flag)) return false;
+  if (isSet2(flag)) {
+    if (!isTruthy(flag)) return false;
+  }
   if (explicit !== void 0) return explicit;
   return !isTruthy(env.CI);
 }
@@ -228,24 +232,37 @@ var isStringList = (value) => Array.isArray(value) && value.every(isString);
 var readScope = (value) => {
   if (!isRecord(value)) return { kind: "shared" };
   if (value.kind === "owner") return { kind: "owner" };
-  if (value.kind === "host" && isString(value.hostLabel)) return { kind: "host", hostLabel: value.hostLabel };
+  if (value.kind === "host" && isString(value.hostLabel))
+    return { kind: "host", hostLabel: value.hostLabel };
   return { kind: "shared" };
 };
+var readRegisteredAgent = (entry) => {
+  if (!isRecord(entry)) return null;
+  if (!isString(entry.name)) return null;
+  let id = null;
+  if (isString(entry.id)) {
+    id = entry.id;
+  } else if (isString(entry.agentId)) {
+    id = entry.agentId;
+  }
+  if (id === null) return null;
+  return {
+    name: entry.name,
+    environment: isString(entry.environment) ? entry.environment : "",
+    id,
+    url: isString(entry.url) ? entry.url : "",
+    parameterNotes: isStringList(entry.parameterNotes) ? entry.parameterNotes : [],
+    scope: readScope(entry.scope)
+  };
+};
 var readRegistered = (frame) => {
-  if (!Array.isArray(frame.agents) || !isString(frame.instanceId)) return null;
+  if (!Array.isArray(frame.agents)) return null;
+  if (!isString(frame.instanceId)) return null;
   const agents = [];
   for (const entry of frame.agents) {
-    if (!isRecord(entry) || !isString(entry.name)) return null;
-    const id = isString(entry.id) ? entry.id : isString(entry.agentId) ? entry.agentId : null;
-    if (id === null) return null;
-    agents.push({
-      name: entry.name,
-      environment: isString(entry.environment) ? entry.environment : "",
-      id,
-      url: isString(entry.url) ? entry.url : "",
-      parameterNotes: isStringList(entry.parameterNotes) ? entry.parameterNotes : [],
-      scope: readScope(entry.scope)
-    });
+    const agent = readRegisteredAgent(entry);
+    if (agent === null) return null;
+    agents.push(agent);
   }
   return {
     type: "registered",
@@ -281,12 +298,15 @@ var readDeadline = (value) => {
   return null;
 };
 var readCall = (frame) => {
-  if (!isString(frame.callId) || !isString(frame.agentId)) return null;
+  if (!isString(frame.callId)) return null;
+  if (!isString(frame.agentId)) return null;
   const messages = isMessageList(frame.messages) ? frame.messages : [];
   const run = isRecord(frame.run) ? frame.run : {};
   return {
     type: "call",
     protocol: typeof frame.protocol === "number" ? frame.protocol : PROTOCOL_VERSION,
+    // A platform that predates hooks sends no kind: every call is a turn.
+    kind: isString(frame.kind) ? frame.kind : "turn",
     callId: frame.callId,
     agentId: frame.agentId,
     threadId: isString(frame.threadId) ? frame.threadId : "",
@@ -294,6 +314,7 @@ var readCall = (frame) => {
     newMessages: isMessageList(frame.newMessages) ? frame.newMessages : messages,
     params: readParams(frame.params),
     session: frame.session === void 0 ? null : frame.session,
+    state: isRecord(frame.state) ? frame.state : null,
     traceparent: isString(frame.traceparent) ? frame.traceparent : null,
     deadlineAt: readDeadline(frame.deadlineAt),
     run: {
@@ -310,7 +331,8 @@ function parseServerFrame(raw) {
   } catch {
     return null;
   }
-  if (!isRecord(parsed) || !isString(parsed.type)) return null;
+  if (!isRecord(parsed)) return null;
+  if (!isString(parsed.type)) return null;
   switch (parsed.type) {
     case "registered":
       return readRegistered(parsed);
@@ -339,164 +361,6 @@ function traceIdFromTraceparent(traceparent) {
   return traceId.toLowerCase();
 }
 
-// src/agent/schema.ts
-var AgentParameterError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.code = "agent_parameter_invalid";
-    this.name = "AgentParameterError";
-  }
-};
-var ACCEPTED_FORMS = `parameters must be a definition map ({ model: { options: [...], default: '...' } }), a Standard JSON Schema object (one with "~standard".jsonSchema), or a JSON Schema object ({ type: 'object', properties })`;
-var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-var isStandardJsonSchema = (value) => {
-  if (!isRecord2(value)) return false;
-  const standard = value["~standard"];
-  return isRecord2(standard) && isRecord2(standard.jsonSchema);
-};
-var isJsonSchemaObject = (value) => isRecord2(value) && value.type === "object" && isRecord2(value.properties);
-var isDefinitionMap = (value) => isRecord2(value) && Object.values(value).every(isRecord2);
-var definitionType = (definition) => {
-  if (definition.type) return definition.type;
-  if (definition.options) return "string";
-  const value = definition.default;
-  if (typeof value === "number") return "number";
-  if (typeof value === "boolean") return "boolean";
-  return "string";
-};
-var definitionMapToSchema = (definitions) => {
-  const properties = {};
-  const required = [];
-  for (const [name, definition] of Object.entries(definitions)) {
-    const property = { type: definitionType(definition) };
-    if (definition.options) property.enum = [...definition.options];
-    if (definition.default !== void 0) property.default = definition.default;
-    else required.push(name);
-    if (definition.description !== void 0) property.description = definition.description;
-    properties[name] = property;
-  }
-  const schema = { type: "object", properties };
-  if (required.length > 0) schema.required = required;
-  return schema;
-};
-var readStandardJsonSchema = (input) => {
-  const converter = input["~standard"].jsonSchema;
-  const options = { target: "draft-2020-12" };
-  const schema = converter.input?.(options) ?? converter.output?.(options);
-  if (schema === void 0) {
-    throw new AgentParameterError(`the "~standard".jsonSchema converter has no input function; ${ACCEPTED_FORMS}`);
-  }
-  if (!isRecord2(schema)) {
-    throw new AgentParameterError(`the "~standard".jsonSchema converter returned no object; ${ACCEPTED_FORMS}`);
-  }
-  return schema;
-};
-function toParameterSchema(input) {
-  if (input === void 0) return { type: "object", properties: {} };
-  if (isStandardJsonSchema(input)) return readStandardJsonSchema(input);
-  if (isJsonSchemaObject(input)) return input;
-  if (isDefinitionMap(input)) return definitionMapToSchema(input);
-  throw new AgentParameterError(ACCEPTED_FORMS);
-}
-var specType = (property) => {
-  const type = Array.isArray(property.type) ? property.type.find((item) => item !== "null") : property.type;
-  if (type === "number" || type === "integer") return "number";
-  if (type === "boolean") return "boolean";
-  return "string";
-};
-var scalar = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : void 0;
-function parameterSpecsFromSchema(schema) {
-  const properties = isRecord2(schema.properties) ? schema.properties : {};
-  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
-  const specs = [];
-  for (const [name, raw] of Object.entries(properties)) {
-    const property = isRecord2(raw) ? raw : {};
-    const spec = { name, type: specType(property) };
-    const options = Array.isArray(property.enum) ? property.enum.filter((item) => typeof item === "string") : void 0;
-    if (options && options.length > 0) spec.options = options;
-    const fallback = scalar(property.default);
-    if (fallback !== void 0) spec.default = fallback;
-    if (typeof property.description === "string") spec.description = property.description;
-    spec.required = fallback === void 0 && required.has(name);
-    specs.push(spec);
-  }
-  return specs;
-}
-var coerce = ({
-  spec,
-  value
-}) => {
-  if (spec.type === "number") {
-    const asNumber = typeof value === "number" ? value : Number(value);
-    if (typeof value === "boolean" || !Number.isFinite(asNumber) || String(value).trim() === "") {
-      throw new AgentParameterError(`parameter "${spec.name}" must be a number, got ${JSON.stringify(value)}`);
-    }
-    return asNumber;
-  }
-  if (spec.type === "boolean") {
-    if (typeof value === "boolean") return value;
-    if (value === "true") return true;
-    if (value === "false") return false;
-    throw new AgentParameterError(`parameter "${spec.name}" must be true or false, got ${JSON.stringify(value)}`);
-  }
-  const asString = typeof value === "string" ? value : String(value);
-  if (spec.options && !spec.options.includes(asString)) {
-    throw new AgentParameterError(
-      `parameter "${spec.name}" must be one of ${spec.options.join(", ")}, got ${JSON.stringify(value)}`
-    );
-  }
-  return asString;
-};
-function resolveParameterValues({
-  specs,
-  supplied
-}) {
-  const values = { ...supplied ?? {} };
-  for (const spec of specs) {
-    const value = values[spec.name];
-    if (value === void 0) {
-      if (spec.default !== void 0) {
-        values[spec.name] = spec.default;
-        continue;
-      }
-      if (!spec.required) continue;
-      throw new AgentParameterError(`parameter "${spec.name}" is required and the run did not supply it`);
-    }
-    values[spec.name] = coerce({ spec, value });
-  }
-  return values;
-}
-var issuePath = (issue) => (issue.path ?? []).map(
-  (segment) => typeof segment === "object" && segment !== null ? String(segment.key) : String(segment)
-).join(".");
-async function validateParameterValues({
-  schema,
-  values
-}) {
-  const standard = schema["~standard"];
-  const result = await standard.validate?.(values);
-  if (result === void 0) return values;
-  if (result.issues) {
-    const detail = result.issues.map((issue) => {
-      const path = issuePath(issue);
-      return path ? `${path}: ${issue.message}` : issue.message;
-    }).join("; ");
-    throw new AgentParameterError(`parameters refused by the schema: ${detail}`);
-  }
-  const parsed = isRecord2(result.value) ? result.value : {};
-  return { ...values, ...parsed };
-}
-function createParameterReader({
-  input,
-  specs
-}) {
-  const schema = isStandardJsonSchema(input) ? input : void 0;
-  return async (supplied) => {
-    const values = resolveParameterValues({ specs, supplied });
-    return schema ? validateParameterValues({ schema, values }) : values;
-  };
-}
-
 // src/agent/transport.ts
 var import_node_module = require("module");
 
@@ -513,11 +377,7 @@ var CREDENTIAL_HEADERS = [
   "x-project-id"
 ];
 var LangWatchRedirectError = class extends Error {
-  constructor({
-    url,
-    location,
-    status
-  }) {
+  constructor({ url, location, status }) {
     super(
       `LangWatch refused to follow a redirect from ${url} to ${location ?? "an unknown location"} (HTTP ${status}). Set the endpoint to the final URL.`
     );
@@ -664,7 +524,19 @@ var upgrade = async ({
   const location = first.headers.get("location");
   const refused = refusalOf({ url, response: first });
   const target = location === null ? null : schemeUpgradeTarget({ url, location });
-  if (location === null || first.status === 303 || target === null || isStream(init?.body)) {
+  if (location === null) {
+    discard(spare);
+    throw refused;
+  }
+  if (first.status === 303) {
+    discard(spare);
+    throw refused;
+  }
+  if (target === null) {
+    discard(spare);
+    throw refused;
+  }
+  if (isStream(init?.body)) {
     discard(spare);
     throw refused;
   }
@@ -714,7 +586,10 @@ function resolveTransport({
   env = process.env
 }) {
   const candidate = isSet3(explicit) ? explicit : env.LANGWATCH_AGENT_TRANSPORT;
-  return isSet3(candidate) && candidate.trim().toLowerCase() === "http" ? "http" : "websocket";
+  if (!isSet3(candidate)) return "websocket";
+  const normalized = candidate.trim().toLowerCase();
+  if (normalized === "http") return "http";
+  return "websocket";
 }
 var NoWebSocketError = class extends Error {
   constructor() {
@@ -811,14 +686,14 @@ var HttpLongPollSocket = class {
       return;
     }
     if (frame.type === "ack" && typeof frame.callId === "string") this.inFlight.add(frame.callId);
-    if (frame.type === "result" && typeof frame.callId === "string") this.inFlight.delete(frame.callId);
+    if (frame.type === "result" && typeof frame.callId === "string")
+      this.inFlight.delete(frame.callId);
     this.outbox = this.outbox.then(() => this.registered).then(() => this.post(data)).catch(() => void 0);
   }
   /**
-   * Stops polling, lets the frames already queued go out, then reports the
-   * close. The wait is bounded: on the deadline the frame requests are aborted
-   * and the close is reported anyway, so a request that never answers cannot
-   * hold the connection open.
+   * Stops polling, lets queued frames go out, then reports close. Bounded: on
+   * the deadline the frame requests are aborted and close is reported anyway,
+   * so an unanswering request cannot hold the connection open.
    */
   close(code = 1e3) {
     this.closed = true;
@@ -873,7 +748,8 @@ var HttpLongPollSocket = class {
         signal: this.polls.signal
       });
     } catch (error) {
-      if (!this.closed) this.fail(`could not reach ${this.url}/register (${describe(error)})`, 1006);
+      if (!this.closed)
+        this.fail(`could not reach ${this.url}/register (${describe(error)})`, 1006);
       return;
     }
     const body = await this.jsonOf(response);
@@ -894,46 +770,66 @@ var HttpLongPollSocket = class {
   }
   async pollLoop() {
     while (!this.closed && this.token) {
-      const query = this.inFlight.size > 0 ? `?inFlight=${encodeURIComponent([...this.inFlight].join(","))}` : "";
-      const startedAt = Date.now();
-      let response;
-      try {
-        response = await this.fetchImpl(`${this.url}/poll${query}`, {
-          method: "GET",
-          headers: this.requestHeaders(),
-          signal: this.polls.signal
-        });
-      } catch (error) {
-        if (!this.closed) this.fail(`the poll failed (${describe(error)})`, 1006);
-        return;
-      }
-      if (this.closed) return;
-      if (response.status === 410) {
-        this.fail("the platform no longer knows this instance, registering again", SESSION_LOST_CLOSE_CODE);
-        return;
-      }
-      const body = await this.jsonOf(response);
-      if (!response.ok) {
-        const answered = body && typeof body.frame === "object" && body.frame !== null ? body.frame : null;
-        if (answered) this.emitMessage(JSON.stringify(answered));
-        if (answered?.type === "refused") {
-          return;
-        }
-        this.fail(`the poll was answered with HTTP ${response.status}`, 1006);
-        return;
-      }
-      const frames = Array.isArray(body?.frames) ? body.frames : [];
-      for (const frame of frames) {
-        const entry = frame;
-        if (entry.type === "cancel" && typeof entry.callId === "string") this.inFlight.delete(entry.callId);
-        this.emitMessage(JSON.stringify(frame));
-      }
-      for (const listener of this.pingListeners) listener();
-      if (frames.length === 0) {
-        const elapsedMs = Date.now() - startedAt;
-        if (elapsedMs < EMPTY_POLL_FLOOR_MS) await wait(EMPTY_POLL_FLOOR_MS - elapsedMs);
-      }
+      if (!await this.pollOnce()) return;
+    }
+  }
+  /** One long poll: delivers what it answered, and says whether polling goes on. */
+  async pollOnce() {
+    const query = this.inFlight.size > 0 ? `?inFlight=${encodeURIComponent([...this.inFlight].join(","))}` : "";
+    const startedAt = Date.now();
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.url}/poll${query}`, {
+        method: "GET",
+        headers: this.requestHeaders(),
+        signal: this.polls.signal
+      });
+    } catch (error) {
+      if (!this.closed) this.fail(`the poll failed (${describe(error)})`, 1006);
+      return false;
+    }
+    if (this.closed) return false;
+    if (response.status === 410) {
+      this.fail(
+        "the platform no longer knows this instance, registering again",
+        SESSION_LOST_CLOSE_CODE
+      );
+      return false;
     }
+    const body = await this.jsonOf(response);
+    if (!response.ok) {
+      this.refusePoll({ status: response.status, body });
+      return false;
+    }
+    const delivered = this.deliverFrames(body);
+    for (const listener of this.pingListeners) listener();
+    if (delivered === 0) {
+      const elapsedMs = Date.now() - startedAt;
+      if (elapsedMs < EMPTY_POLL_FLOOR_MS) await wait(EMPTY_POLL_FLOOR_MS - elapsedMs);
+    }
+    return true;
+  }
+  refusePoll({
+    status,
+    body
+  }) {
+    const answered = body && typeof body.frame === "object" && body.frame !== null ? body.frame : null;
+    if (answered) this.emitMessage(JSON.stringify(answered));
+    if (answered?.type === "refused") {
+      return;
+    }
+    this.fail(`the poll was answered with HTTP ${status}`, 1006);
+  }
+  /** Emits every frame a poll answered and returns how many there were. */
+  deliverFrames(body) {
+    const frames = Array.isArray(body?.frames) ? body.frames : [];
+    for (const frame of frames) {
+      const entry = frame;
+      if (entry.type === "cancel" && typeof entry.callId === "string")
+        this.inFlight.delete(entry.callId);
+      this.emitMessage(JSON.stringify(frame));
+    }
+    return frames.length;
   }
   async post(data) {
     if (!this.token) return;
@@ -951,12 +847,7 @@ var HttpLongPollSocket = class {
         if (this.frames.signal.aborted) return;
         response = null;
       }
-      if (response?.ok) return;
-      if (response?.status === 410) {
-        this.fail("the platform no longer knows this instance, registering again", SESSION_LOST_CLOSE_CODE);
-        return;
-      }
-      if (response && response.status < 500) return;
+      if (this.postSettled(response)) return;
       const delay = POST_RETRY_DELAYS_MS[attempt];
       if (delay === void 0) {
         this.fail(`a frame could not be posted after ${attempt} retries`, 1006);
@@ -965,6 +856,18 @@ var HttpLongPollSocket = class {
       await wait(delay);
     }
   }
+  /** Whether a post's response ends its retries: delivered, refused, or the session lost. */
+  postSettled(response) {
+    if (response?.ok) return true;
+    if (response?.status === 410) {
+      this.fail(
+        "the platform no longer knows this instance, registering again",
+        SESSION_LOST_CLOSE_CODE
+      );
+      return true;
+    }
+    return response !== null && response.status < 500;
+  }
   async jsonOf(response) {
     try {
       const parsed = await response.json();
@@ -1018,19 +921,257 @@ function openTransportSocket({
   return transport === "http" ? new HttpLongPollSocket({ url: httpUrl, headers }) : socketFactory({ url: websocketUrl, headers });
 }
 
+// src/agent/schema.ts
+var AgentParameterError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "agent_parameter_invalid";
+    this.name = "AgentParameterError";
+  }
+};
+var ACCEPTED_FORMS = `parameters must be a definition map ({ model: { options: [...], default: '...' } }), a Standard JSON Schema object (one with "~standard".jsonSchema), or a JSON Schema object ({ type: 'object', properties })`;
+var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isStandardJsonSchema = (value) => {
+  if (!isRecord2(value)) return false;
+  const standard = value["~standard"];
+  return isRecord2(standard) && isRecord2(standard.jsonSchema);
+};
+var isJsonSchemaObject = (value) => isRecord2(value) && value.type === "object" && isRecord2(value.properties);
+var isDefinitionMap = (value) => isRecord2(value) && Object.values(value).every(isRecord2);
+var definitionType = (definition) => {
+  if (definition.type) return definition.type;
+  if (definition.options) return "string";
+  const value = definition.default;
+  if (typeof value === "number") return "number";
+  if (typeof value === "boolean") return "boolean";
+  return "string";
+};
+var definitionMapToSchema = (definitions) => {
+  const properties = {};
+  const required = [];
+  for (const [name, definition] of Object.entries(definitions)) {
+    const property = { type: definitionType(definition) };
+    if (definition.options) property.enum = [...definition.options];
+    if (definition.default !== void 0) property.default = definition.default;
+    else required.push(name);
+    if (definition.description !== void 0) property.description = definition.description;
+    properties[name] = property;
+  }
+  const schema = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+};
+var readStandardJsonSchema = (input) => {
+  const converter = input["~standard"].jsonSchema;
+  const options = { target: "draft-2020-12" };
+  const schema = converter.input?.(options) ?? converter.output?.(options);
+  if (schema === void 0) {
+    throw new AgentParameterError(
+      `the "~standard".jsonSchema converter has no input function; ${ACCEPTED_FORMS}`
+    );
+  }
+  if (!isRecord2(schema)) {
+    throw new AgentParameterError(
+      `the "~standard".jsonSchema converter returned no object; ${ACCEPTED_FORMS}`
+    );
+  }
+  return schema;
+};
+function toParameterSchema(input) {
+  if (input === void 0) return { type: "object", properties: {} };
+  if (isStandardJsonSchema(input)) return readStandardJsonSchema(input);
+  if (isJsonSchemaObject(input)) return input;
+  if (isDefinitionMap(input)) return definitionMapToSchema(input);
+  throw new AgentParameterError(ACCEPTED_FORMS);
+}
+var specType = (property) => {
+  const type = Array.isArray(property.type) ? property.type.find((item) => item !== "null") : property.type;
+  if (type === "number" || type === "integer") return "number";
+  if (type === "boolean") return "boolean";
+  return "string";
+};
+var scalar = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : void 0;
+function parameterSpecsFromSchema(schema) {
+  const properties = isRecord2(schema.properties) ? schema.properties : {};
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const specs = [];
+  for (const [name, raw] of Object.entries(properties)) {
+    const property = isRecord2(raw) ? raw : {};
+    const spec = { name, type: specType(property) };
+    const options = Array.isArray(property.enum) ? property.enum.filter((item) => typeof item === "string") : void 0;
+    if (options && options.length > 0) spec.options = options;
+    const fallback = scalar(property.default);
+    if (fallback !== void 0) spec.default = fallback;
+    if (typeof property.description === "string") spec.description = property.description;
+    spec.required = fallback === void 0 && required.has(name);
+    specs.push(spec);
+  }
+  return specs;
+}
+var coerce = ({
+  spec,
+  value
+}) => {
+  if (spec.type === "number") {
+    return coerceNumber(spec.name, value);
+  }
+  if (spec.type === "boolean") {
+    if (typeof value === "boolean") return value;
+    if (value === "true") return true;
+    if (value === "false") return false;
+    throw new AgentParameterError(
+      `parameter "${spec.name}" must be true or false, got ${JSON.stringify(value)}`
+    );
+  }
+  const asString = typeof value === "string" ? value : String(value);
+  if (spec.options && !spec.options.includes(asString)) {
+    throw new AgentParameterError(
+      `parameter "${spec.name}" must be one of ${spec.options.join(", ")}, got ${JSON.stringify(value)}`
+    );
+  }
+  return asString;
+};
+function resolveParameterValues({
+  specs,
+  supplied
+}) {
+  const values = { ...supplied };
+  for (const spec of specs) {
+    const value = values[spec.name];
+    if (value === void 0) {
+      if (spec.default !== void 0) {
+        values[spec.name] = spec.default;
+        continue;
+      }
+      if (!spec.required) continue;
+      throw new AgentParameterError(
+        `parameter "${spec.name}" is required and the run did not supply it`
+      );
+    }
+    values[spec.name] = coerce({ spec, value });
+  }
+  return values;
+}
+var issuePath = (issue) => (issue.path ?? []).map(
+  (segment) => typeof segment === "object" && segment !== null ? String(segment.key) : String(segment)
+).join(".");
+async function validateParameterValues({
+  schema,
+  values
+}) {
+  const standard = schema["~standard"];
+  const result = await standard.validate?.(values);
+  if (result === void 0) return values;
+  if (result.issues) {
+    const detail = result.issues.map((issue) => {
+      const path = issuePath(issue);
+      return path ? `${path}: ${issue.message}` : issue.message;
+    }).join("; ");
+    throw new AgentParameterError(`parameters refused by the schema: ${detail}`);
+  }
+  const parsed = isRecord2(result.value) ? result.value : {};
+  return { ...values, ...parsed };
+}
+function createParameterReader({
+  input,
+  specs
+}) {
+  const schema = isStandardJsonSchema(input) ? input : void 0;
+  return async (supplied) => {
+    const values = resolveParameterValues({ specs, supplied });
+    return schema ? validateParameterValues({ schema, values }) : values;
+  };
+}
+function coerceNumber(name, value) {
+  const asNumber = typeof value === "number" ? value : Number(value);
+  if (typeof value === "boolean") {
+    throw new AgentParameterError(
+      `parameter "${name}" must be a number, got ${JSON.stringify(value)}`
+    );
+  }
+  if (!Number.isFinite(asNumber)) {
+    throw new AgentParameterError(
+      `parameter "${name}" must be a number, got ${JSON.stringify(value)}`
+    );
+  }
+  const stringValue2 = String(value).trim();
+  if (stringValue2 === "") {
+    throw new AgentParameterError(
+      `parameter "${name}" must be a number, got ${JSON.stringify(value)}`
+    );
+  }
+  return asNumber;
+}
+
+// src/agent/state.ts
+var STATE_MAX_BYTES = 64 * 1024;
+var AgentStateError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AgentStateError";
+  }
+};
+var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function checkState(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (!isPlainObject(value)) {
+    throw new AgentStateError(
+      "agent_call_failed",
+      `the state must be a JSON object, got ${Array.isArray(value) ? "an array" : typeof value}`
+    );
+  }
+  let encoded;
+  try {
+    encoded = JSON.stringify(value);
+  } catch (error) {
+    throw new AgentStateError(
+      "agent_call_failed",
+      `the state is not JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const sizeBytes = Buffer.byteLength(encoded, "utf8");
+  if (sizeBytes > STATE_MAX_BYTES) {
+    throw new AgentStateError(
+      "agent_payload_too_large",
+      `The state is ${sizeBytes} bytes, above the limit of ${STATE_MAX_BYTES} bytes.`
+    );
+  }
+  return value;
+}
+
 // src/agent/client.ts
+var kindRefusal = (runtime, kind) => {
+  if (kind === "turn") return null;
+  if (kind !== "setup" && kind !== "teardown") {
+    return { code: "agent_call_failed", message: `unknown call kind "${kind}"` };
+  }
+  if (runtime.hooks[kind]) return null;
+  return {
+    code: "hook_not_declared",
+    message: `agent "${runtime.name}" declares no ${kind} hook`
+  };
+};
+var errorCodeOf = (error) => error instanceof AgentParameterError || error instanceof AgentStateError ? error.code : "agent_call_failed";
+var answerCall = async ({
+  runtime,
+  frame,
+  call
+}) => {
+  const hook = frame.kind === "setup" || frame.kind === "teardown" ? runtime.hooks[frame.kind] : void 0;
+  if (!hook) {
+    const result = await runtime.run(call);
+    return { ...result, state: checkState(result.state) };
+  }
+  const state = await hook({ run: frame.run, state: frame.state, params: call.params });
+  return { state: checkState(frame.kind === "setup" ? state ?? {} : state) };
+};
 var FAILURE_NOTICE_INTERVAL_MS = 5 * 6e4;
 var NOT_CONNECTED = "not connected to LangWatch";
 function refusalAdvice(frame) {
   switch (frame.code) {
     case "project_required": {
-      const projects = Array.isArray(frame.meta?.projects) ? frame.meta.projects : [];
-      const listed = projects.map((project) => {
-        const entry = project;
-        const id = typeof entry.id === "string" ? entry.id : "";
-        const name = typeof entry.name === "string" ? entry.name : "";
-        return name && id ? `${name} (${id})` : id || name;
-      }).filter((line) => line !== "");
+      const listed = projectNames(frame.meta?.projects);
       return `the API key reaches more than one project. Set LANGWATCH_PROJECT_ID to one of: ${listed.length > 0 ? listed.join(", ") : "the projects the key reaches"}.`;
     }
     case "api_key_invalid":
@@ -1050,8 +1191,30 @@ function refusalAdvice(frame) {
       return `${frame.message} (${frame.code})`;
   }
 }
+function projectNames(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map(projectName).filter((name) => name !== "");
+}
+function projectName(value) {
+  if (!isRecord3(value)) return "";
+  const id = stringValue(value.id);
+  const name = stringValue(value.name);
+  if (name && id) return `${name} (${id})`;
+  return id || name;
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null;
+}
+function stringValue(value) {
+  return typeof value === "string" ? value : "";
+}
 var SHUTDOWN_SIGNALS = ["SIGINT", "SIGTERM"];
 var CLOSE_GRACE_MS = 500;
+var readCallTraceContext = (frame) => {
+  const parent = frame.traceparent ? import_api.propagation.extract(import_api.context.active(), { traceparent: frame.traceparent }) : import_api.context.active();
+  const traceId = import_api.trace.getSpanContext(parent)?.traceId ?? traceIdFromTraceparent(frame.traceparent) ?? "";
+  return { parent, traceId };
+};
 var AgentClient = class {
   constructor(config) {
     this.agents = [];
@@ -1092,7 +1255,7 @@ var AgentClient = class {
   get isRegistered() {
     return this.registered;
   }
-  /** True once the client gave up: refused, or no socket implementation. No timer is left behind. */
+  /** True once the client gave up: refused, or no socket implementation available. */
   get isStopped() {
     return this.stopped;
   }
@@ -1109,7 +1272,9 @@ var AgentClient = class {
   addAgent(runtime) {
     this.agents.push(runtime);
     if (this.gaveUp) {
-      this.logger.debug(`agent "${runtime.name}" ${NOT_CONNECTED}: the connection gave up earlier in this process`);
+      this.logger.debug(
+        `agent "${runtime.name}" ${NOT_CONNECTED}: the connection gave up earlier in this process`
+      );
       return;
     }
     this.stopped = false;
@@ -1119,6 +1284,10 @@ var AgentClient = class {
     }
     this.scheduleConnect(0);
   }
+  /** Registers the agents again after one changed: a hook declared once the socket opened. */
+  refreshAgents() {
+    if (this.socket) this.restartSocket();
+  }
   /** Closes the socket and connects again at once, keeping the reconnect loop. */
   restartSocket() {
     const socket = this.socket;
@@ -1278,7 +1447,10 @@ var AgentClient = class {
    * connection is lost, and silence while the retries run: the same notice
    * repeats only after the notice interval, and a reconnect resets it.
    */
-  noteDisconnected({ wasRegistered, code }) {
+  noteDisconnected({
+    wasRegistered,
+    code
+  }) {
     const now = Date.now();
     if (wasRegistered) {
       this.logger.warn(
@@ -1371,7 +1543,8 @@ var AgentClient = class {
       this.logger.info(`connected to LangWatch over HTTP long polling at ${this.httpUrl}`);
     }
     this.heartbeatIntervalMs = frame.heartbeatIntervalMs;
-    if (frame.instanceId && frame.instanceId !== this.instance.id) this.instance.id = frame.instanceId;
+    if (frame.instanceId && frame.instanceId !== this.instance.id)
+      this.instance.id = frame.instanceId;
     this.byId.clear();
     for (const entry of frame.agents) {
       const runtime = this.agents.find(
@@ -1398,21 +1571,9 @@ var AgentClient = class {
       });
       return;
     }
-    const busy = [...this.inFlight.values()].filter((call2) => call2.runtime === runtime).length;
-    if (busy >= runtime.concurrency) {
-      this.sendError({
-        callId: frame.callId,
-        code: "agent_busy",
-        message: `agent "${runtime.name}" has ${busy} call${busy === 1 ? "" : "s"} in flight, its limit`
-      });
-      return;
-    }
-    if (frame.deadlineAt !== null && frame.deadlineAt <= Date.now()) {
-      this.sendError({
-        callId: frame.callId,
-        code: "agent_call_timeout",
-        message: "the call deadline passed before it started"
-      });
+    const refusal = this.callRefusal({ frame, runtime });
+    if (refusal) {
+      this.sendError({ callId: frame.callId, ...refusal });
       return;
     }
     const entry = { runtime, cancelled: false, timer: null };
@@ -1435,18 +1596,18 @@ var AgentClient = class {
     }
     this.send({ type: "ack", protocol: PROTOCOL_VERSION, callId: frame.callId });
     this.armCallDeadline({ frame, entry, runtime });
-    const parent = frame.traceparent ? import_api.propagation.extract(import_api.context.active(), { traceparent: frame.traceparent }) : import_api.context.active();
-    const traceId = import_api.trace.getSpanContext(parent)?.traceId ?? traceIdFromTraceparent(frame.traceparent) ?? "";
+    const { parent, traceId } = readCallTraceContext(frame);
     const call = {
       messages: frame.messages,
       newMessages: frame.newMessages,
       threadId: frame.threadId,
       session: frame.session,
+      state: frame.state,
       params,
       traceId
     };
     try {
-      const result = await import_api.context.with(parent, () => runtime.run(call));
+      const result = await import_api.context.with(parent, () => answerCall({ runtime, frame, call }));
       if (entry.cancelled) return;
       this.releaseCall({ callId: frame.callId, entry });
       await this.flushSpans();
@@ -1454,12 +1615,13 @@ var AgentClient = class {
         type: "result",
         protocol: PROTOCOL_VERSION,
         callId: frame.callId,
-        output: result.output,
-        ...result.session === void 0 ? {} : { session: result.session }
+        ...result.output === void 0 ? {} : { output: result.output },
+        ...result.session === void 0 ? {} : { session: result.session },
+        ...result.state === void 0 ? {} : { state: result.state }
       });
     } catch (error) {
       if (entry.cancelled) return;
-      const code = error instanceof AgentParameterError ? error.code : "agent_call_failed";
+      const code = errorCodeOf(error);
       const message = describeError(error);
       this.logger.warn(`agent "${runtime.name}" call ${frame.callId} failed: ${message}`);
       this.releaseCall({ callId: frame.callId, entry });
@@ -1469,15 +1631,32 @@ var AgentClient = class {
       this.releaseCall({ callId: frame.callId, entry });
     }
   }
+  /** Why the runtime cannot take this call now, or null when it can. */
+  callRefusal({
+    frame,
+    runtime
+  }) {
+    const kind = kindRefusal(runtime, frame.kind);
+    if (kind) return kind;
+    const busy = [...this.inFlight.values()].filter((call) => call.runtime === runtime).length;
+    if (busy >= runtime.concurrency) {
+      return {
+        code: "agent_busy",
+        message: `agent "${runtime.name}" has ${busy} call${busy === 1 ? "" : "s"} in flight, its limit`
+      };
+    }
+    if (frame.deadlineAt !== null && frame.deadlineAt <= Date.now()) {
+      return {
+        code: "agent_call_timeout",
+        message: "the call deadline passed before it started"
+      };
+    }
+    return null;
+  }
   /**
-   * Exports the spans of the call now instead of at the exporter's next
-   * schedule. The judge reads the agent's spans right after the last turn,
-   * and a batch exporter would otherwise hold them for seconds, which is what
-   * made the judge report the spans missing.
-   *
-   * The call awaits this before it sends its result or its error: the frame is
-   * what tells the platform the turn is over, so a frame that goes out first
-   * lets the judge read the call while its spans are still in the exporter.
+   * Exports the spans of the call now, since a batch exporter would
+   * otherwise hold them for seconds after the judge reads them. Awaited
+   * before the result or error frame goes out.
    */
   async flushSpans() {
     const provider = import_api.trace.getTracerProvider();
@@ -1509,26 +1688,33 @@ var AgentClient = class {
     runtime
   }) {
     const fromDeadline = frame.deadlineAt === null ? Infinity : frame.deadlineAt - Date.now();
-    const limit = Math.min(fromDeadline, runtime.timeoutMs);
+    const limit = frame.kind !== "turn" && frame.deadlineAt !== null ? fromDeadline : Math.min(fromDeadline, runtime.timeoutMs);
     if (!Number.isFinite(limit)) return;
-    const timer = setTimeout(() => {
-      entry.timer = null;
-      if (entry.cancelled) return;
-      entry.cancelled = true;
-      this.releaseCall({ callId: frame.callId, entry });
-      this.logger.warn(
-        `agent "${runtime.name}" call ${frame.callId} passed its ${limit} ms limit`
-      );
-      this.sendError({
-        callId: frame.callId,
-        code: "agent_call_timeout",
-        message: `the call passed the ${limit} ms limit of agent "${runtime.name}"`
-      });
-    }, Math.max(0, limit));
+    const timer = setTimeout(
+      () => {
+        entry.timer = null;
+        if (entry.cancelled) return;
+        entry.cancelled = true;
+        this.releaseCall({ callId: frame.callId, entry });
+        this.logger.warn(
+          `agent "${runtime.name}" call ${frame.callId} passed its ${limit} ms limit`
+        );
+        this.sendError({
+          callId: frame.callId,
+          code: "agent_call_timeout",
+          message: `the call passed the ${limit} ms limit of agent "${runtime.name}"`
+        });
+      },
+      Math.max(0, limit)
+    );
     timer.unref();
     entry.timer = timer;
   }
-  sendError({ callId, code, message }) {
+  sendError({
+    callId,
+    code,
+    message
+  }) {
     this.send({ type: "result", protocol: PROTOCOL_VERSION, callId, error: { code, message } });
   }
   guard(action) {
@@ -1571,7 +1757,11 @@ var installShutdownHooks = () => {
   }
   process.on("beforeExit", onBeforeExit);
 };
-function warnOnce2({ logger, key, message }) {
+function warnOnce2({
+  logger,
+  key,
+  message
+}) {
   if (noticesGiven.has(key)) {
     logger.debug(message);
     return;
@@ -1614,22 +1804,33 @@ var DEFAULT_CONCURRENCY = 10;
 var isMessage = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.role === "string";
 function normalizeReply(reply) {
   if (typeof reply === "string") return { output: reply };
-  if (Array.isArray(reply) && reply.every(isMessage)) return { output: reply };
+  if (Array.isArray(reply)) {
+    if (reply.every(isMessage)) return { output: reply };
+  }
   if (isMessage(reply)) return { output: reply };
   if (typeof reply === "object" && reply !== null && "output" in reply) {
-    const { output, session } = reply;
-    const normalized = normalizeReply(output);
-    return session === void 0 ? normalized : { output: normalized.output, session };
+    const { output, session, state } = reply;
+    return {
+      output: normalizeReply(output).output,
+      ...session === void 0 ? {} : { session },
+      ...state === void 0 ? {} : { state }
+    };
   }
   throw new Error(
-    "the agent handler must return a string, a message, a list of messages, or { output, session }"
+    "the agent handler must return a string, a message, a list of messages, or { output, session, state }"
   );
 }
-var clampTimeout = ({ timeoutMs, logger, name }) => {
+var clampTimeout = ({
+  timeoutMs,
+  logger,
+  name
+}) => {
   if (timeoutMs === void 0) return DEFAULT_TIMEOUT_MS;
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return DEFAULT_TIMEOUT_MS;
   if (timeoutMs > MAX_TIMEOUT_MS) {
-    logger.warn(`agent "${name}": timeoutMs ${timeoutMs} is above the ${MAX_TIMEOUT_MS} cap, using the cap`);
+    logger.warn(
+      `agent "${name}": timeoutMs ${timeoutMs} is above the ${MAX_TIMEOUT_MS} cap, using the cap`
+    );
     return MAX_TIMEOUT_MS;
   }
   return Math.floor(timeoutMs);
@@ -1660,10 +1861,12 @@ function connectAgent(options, handler) {
       newMessages: call.newMessages ?? call.messages,
       threadId: call.threadId ?? `local_${Date.now().toString(36)}`,
       session: call.session ?? null,
+      state: call.state ?? null,
       params,
       traceId: call.traceId ?? ""
     });
   };
+  const hooks = {};
   const runtime = {
     name,
     environment,
@@ -1673,14 +1876,29 @@ function connectAgent(options, handler) {
       parameters,
       concurrency,
       timeoutMs,
-      ...options.sticky ? { sticky: true } : {}
+      ...options.sticky ? { sticky: true } : {},
+      hooks: { setup: false, teardown: false }
     },
     readParams: readParams2,
     concurrency,
     timeoutMs,
-    run: runHandler
+    run: runHandler,
+    hooks
   };
   let detach;
+  let refresh;
+  const scenario = {
+    setup: (hook) => {
+      hooks.setup = async ({ run, params }) => hook(run, params);
+      runtime.register.hooks = { setup: true, teardown: Boolean(hooks.teardown) };
+      refresh?.();
+    },
+    teardown: (hook) => {
+      hooks.teardown = async ({ run, state, params }) => hook(run, state, params);
+      runtime.register.hooks = { setup: Boolean(hooks.setup), teardown: true };
+      refresh?.();
+    }
+  };
   if (!resolveEnabled({ explicit: options.enabled })) {
     logger.debug(`agent "${name}" not connected to LangWatch: the connection is disabled`);
   } else {
@@ -1702,15 +1920,18 @@ function connectAgent(options, handler) {
       });
       client.addAgent(runtime);
       detach = () => client.removeAgent(runtime);
+      refresh = () => client.refreshAgents();
     }
   }
   const connected = Object.assign(invoke, {
     environment,
     parameters,
+    scenario,
     disconnect: async () => {
       if (!detach) return;
       const release = detach;
       detach = void 0;
+      refresh = void 0;
       await release();
     }
   });
@@ -1721,9 +1942,11 @@ function connectAgent(options, handler) {
 0 && (module.exports = {
   AGENT_TRANSPORTS,
   AgentParameterError,
+  AgentStateError,
   DEFAULT_TIMEOUT_MS,
   MAX_TIMEOUT_MS,
   PROTOCOL_VERSION,
+  STATE_MAX_BYTES,
   connectAgent,
   normalizeReply,
   parameterSpecsFromSchema,