@vinaverse/server 0.0.0-stage → 0.1.0-alpha.10

package/dist/index.js

@@ -0,0 +1,948 @@
+export { createFetchToolHandler, createFetchWebhookHandler } from './chunk-NPXO6SMZ.js';
+import './chunk-FEEJNQXV.js';
+import { verifyToolCall } from './chunk-SDJFZPHJ.js';
+export { MemoryNonceStore, NONCE_KEEP_SECONDS, verifyToolCall } from './chunk-SDJFZPHJ.js';
+import { sha256Hex, utf8, checkTolerance, toBytes, webCrypto } from './chunk-GTPMQKGX.js';
+export { SIGNATURE_HEADER, TOLERANCE_SECONDS, WEBHOOK_EVENT_TYPES, WebCryptoUnavailableError, isConversationEvent, parseSignatureHeader, verifyWebhook } from './chunk-GTPMQKGX.js';
+
+// src/contract.ts
+var CONTRACT = {
+  api: "v1-draft.22",
+  commit: "4695e3dc042e6e0cf1936aae24fcb093eacd27c8"
+};
+
+// src/generated/tool-operations.ts
+var TOOL_OPERATIONS = {
+  create_handoff: {
+    id: "create_handoff",
+    method: "POST",
+    path: "/handoffs",
+    effect: "write",
+    maxResultBytes: 16384,
+    successStatus: 201,
+    idempotencyKey: true,
+    body: true,
+    pathParams: {},
+    queryParams: {}
+  },
+  create_proposal: {
+    id: "create_proposal",
+    method: "POST",
+    path: "/proposals",
+    effect: "propose",
+    maxResultBytes: 16384,
+    successStatus: 201,
+    idempotencyKey: true,
+    body: true,
+    pathParams: {},
+    queryParams: {}
+  },
+  get_availability: {
+    id: "get_availability",
+    method: "GET",
+    path: "/availability",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      professional_id: { type: "string", required: true },
+      service_id: { type: "string", required: true },
+      from: { type: "string", required: true },
+      to: { type: "string", required: true },
+      limit: { type: "integer", required: false }
+    }
+  },
+  get_flow_definition: {
+    id: "get_flow_definition",
+    method: "GET",
+    path: "/flows/{flow}/definition",
+    effect: "read",
+    maxResultBytes: 131072,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { flow: { type: "string", required: true } },
+    queryParams: { version: { type: "integer", required: false } }
+  },
+  get_my_booking: {
+    id: "get_my_booking",
+    method: "GET",
+    path: "/me/bookings/{id}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { id: { type: "string", required: true } },
+    queryParams: {}
+  },
+  get_my_kit: {
+    id: "get_my_kit",
+    method: "GET",
+    path: "/me/kits/{id}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { id: { type: "string", required: true } },
+    queryParams: {}
+  },
+  get_my_order: {
+    id: "get_my_order",
+    method: "GET",
+    path: "/me/orders/{id}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { id: { type: "string", required: true } },
+    queryParams: {}
+  },
+  get_policy: {
+    id: "get_policy",
+    method: "GET",
+    path: "/policies/{topic}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { topic: { type: "string", required: true } },
+    queryParams: {}
+  },
+  get_professional: {
+    id: "get_professional",
+    method: "GET",
+    path: "/professionals/{id}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { id: { type: "string", required: true } },
+    queryParams: {}
+  },
+  get_quote: {
+    id: "get_quote",
+    method: "POST",
+    path: "/quotes",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: true,
+    body: true,
+    pathParams: {},
+    queryParams: {}
+  },
+  get_setup_state: {
+    id: "get_setup_state",
+    method: "GET",
+    path: "/business/setup",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {}
+  },
+  get_workspace: {
+    id: "get_workspace",
+    method: "GET",
+    path: "/workspaces/{id}",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: { id: { type: "string", required: true } },
+    queryParams: {}
+  },
+  list_my_bookings: {
+    id: "list_my_bookings",
+    method: "GET",
+    path: "/me/bookings",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      scope: { type: "string", required: false },
+      limit: { type: "integer", required: false }
+    }
+  },
+  list_my_kits: {
+    id: "list_my_kits",
+    method: "GET",
+    path: "/me/kits",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      scope: { type: "string", required: false },
+      limit: { type: "integer", required: false }
+    }
+  },
+  list_my_orders: {
+    id: "list_my_orders",
+    method: "GET",
+    path: "/me/orders",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      kit_id: { type: "string", required: false },
+      limit: { type: "integer", required: false }
+    }
+  },
+  list_services: {
+    id: "list_services",
+    method: "GET",
+    path: "/catalog/services",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      q: { type: "string", required: true },
+      limit: { type: "integer", required: false }
+    }
+  },
+  list_services_in_area: {
+    id: "list_services_in_area",
+    method: "GET",
+    path: "/areas/services",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      lat: { type: "number", required: false },
+      lng: { type: "number", required: false },
+      radius_miles: { type: "integer", required: false }
+    }
+  },
+  resolve_place: {
+    id: "resolve_place",
+    method: "GET",
+    path: "/places/resolve",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      text: { type: "string", required: true },
+      near_lat: { type: "number", required: false },
+      near_lng: { type: "number", required: false }
+    }
+  },
+  search_professionals: {
+    id: "search_professionals",
+    method: "GET",
+    path: "/search/professionals",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      q: { type: "string", required: false },
+      category_id: { type: "string", required: false },
+      service_type_id: { type: "string", required: false },
+      lat: { type: "number", required: false },
+      lng: { type: "number", required: false },
+      radius_miles: { type: "integer", required: false },
+      date: { type: "string", required: false },
+      time_from: { type: "string", required: false },
+      time_to: { type: "string", required: false },
+      max_price: { type: "integer", required: false },
+      min_rating_ppm: { type: "integer", required: false },
+      sort: { type: "string", required: false },
+      limit: { type: "integer", required: false },
+      cursor: { type: "string", required: false }
+    }
+  },
+  search_workspaces: {
+    id: "search_workspaces",
+    method: "GET",
+    path: "/search/workspaces",
+    effect: "read",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: false,
+    pathParams: {},
+    queryParams: {
+      q: { type: "string", required: false },
+      space_category: { type: "string", required: false },
+      lat: { type: "number", required: false },
+      lng: { type: "number", required: false },
+      radius_miles: { type: "integer", required: false },
+      max_price: { type: "integer", required: false },
+      min_rating_ppm: { type: "integer", required: false },
+      sort: { type: "string", required: false },
+      limit: { type: "integer", required: false },
+      cursor: { type: "string", required: false }
+    }
+  },
+  submit_flow: {
+    id: "submit_flow",
+    method: "POST",
+    path: "/flows/{flow}/submissions",
+    effect: "write",
+    maxResultBytes: 16384,
+    successStatus: 200,
+    idempotencyKey: false,
+    body: true,
+    pathParams: { flow: { type: "string", required: true } },
+    queryParams: {}
+  }
+};
+
+// src/tools/idempotency.ts
+var MemoryIdempotencyStore = class {
+  #held = /* @__PURE__ */ new Map();
+  #now;
+  #sweepEvery;
+  #starts = 0;
+  constructor(options = {}) {
+    this.#now = options.now ?? (() => Date.now() / 1e3);
+    this.#sweepEvery = Math.max(1, options.sweepEvery ?? 256);
+  }
+  async start(key, fingerprint2, pendingSeconds, owner) {
+    const now = this.#now();
+    if (++this.#starts % this.#sweepEvery === 0) {
+      for (const [k, h] of this.#held) if (h.until < now) this.#held.delete(k);
+    }
+    const held = this.#live(key);
+    if (held) return held.record;
+    this.#held.set(key, {
+      record: { fingerprint: fingerprint2, state: "pending" },
+      owner,
+      until: now + pendingSeconds
+    });
+    return null;
+  }
+  async finish(key, record, keepSeconds, owner) {
+    const held = this.#live(key);
+    if (held && (held.record.state !== "pending" || held.owner !== owner)) {
+      return false;
+    }
+    this.#held.set(key, {
+      record: { ...record, state: "done" },
+      until: this.#now() + keepSeconds
+    });
+    return true;
+  }
+  async release(key, owner) {
+    const held = this.#live(key);
+    if (held?.record.state === "pending" && held.owner === owner) {
+      this.#held.delete(key);
+    }
+  }
+  /** Records held, expired ones included until a sweep drops them. */
+  get size() {
+    return this.#held.size;
+  }
+  #live(key) {
+    const held = this.#held.get(key);
+    return held && held.until >= this.#now() ? held : void 0;
+  }
+};
+function fingerprint(value) {
+  return sha256Hex(utf8(canonicalJson(value)));
+}
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+// src/tools/refusals.ts
+var FLOW_REFUSAL_CODES = {
+  REQUIRED_MISSING: true,
+  UNKNOWN_VALUE: true,
+  TOO_LONG: true,
+  VERSION_NOT_ACCEPTED: true,
+  TOO_MANY: true,
+  TOO_FEW: true,
+  BAD_DATE: true,
+  UPLOAD_NOT_FOUND: true,
+  OUT_OF_RANGE: true
+};
+function isFlowRefusal(problem2) {
+  return problem2.status === 422 && Object.hasOwn(FLOW_REFUSAL_CODES, problem2.code) && (problem2.code === "VERSION_NOT_ACCEPTED" || !!problem2.question_id);
+}
+var STATUS = {
+  not_found: 404,
+  forbidden: 403,
+  invalid_argument: 422,
+  unavailable: 503,
+  token_expired: 401
+};
+var ToolRefusal = class _ToolRefusal extends Error {
+  problem;
+  constructor(problem2) {
+    super(problem2.detail ?? problem2.code);
+    this.name = "ToolRefusal";
+    this.problem = problem2;
+  }
+  get status() {
+    return this.problem.status;
+  }
+  /** The record does not exist, or the person may not see it (both are the same 404). */
+  static notFound(detail) {
+    return _ToolRefusal.#coded("not_found", detail);
+  }
+  static forbidden(detail) {
+    return _ToolRefusal.#coded("forbidden", detail);
+  }
+  /**
+   * A value the tenant does not accept. `field` is a JSON Pointer into the
+   * body (`/changes/address/postal_code`); `example` is a valid value the
+   * agent offers when it asks again.
+   */
+  static invalidArgument(options = {}) {
+    return new _ToolRefusal({
+      status: 422,
+      code: "invalid_argument",
+      ...clip("detail", options.detail, 300),
+      ...clip("field", options.field, 200),
+      ...clip("example", options.example, 200)
+    });
+  }
+  /** A temporary failure; a read is retried. */
+  static unavailable(detail) {
+    return _ToolRefusal.#coded("unavailable", detail);
+  }
+  /** The delegated token is not valid (expired, revoked, unknown): a 401, which ends the session's tool access. */
+  static tokenExpired(detail) {
+    return _ToolRefusal.#coded("token_expired", detail);
+  }
+  /** `get_flow_definition` with a `version` the tenant no longer accepts: `410 VERSION_GONE`. */
+  static versionGone(detail) {
+    return new _ToolRefusal({
+      status: 410,
+      code: "VERSION_GONE",
+      ...clip("detail", detail, 300)
+    });
+  }
+  /**
+   * `submit_flow` refused: `422` with a flow code and the question to ask
+   * again (none only for `VERSION_NOT_ACCEPTED`). Stored like an acceptance,
+   * so the same submission gets the same refusal again.
+   */
+  static flowRefused(code, questionId, detail) {
+    if (code !== "VERSION_NOT_ACCEPTED" && !questionId) {
+      throw new TypeError(`a ${code} refusal names the question to ask again`);
+    }
+    return new _ToolRefusal({
+      status: 422,
+      code,
+      ...questionId ? { question_id: questionId } : {},
+      ...clip("detail", detail, 300)
+    });
+  }
+  static #coded(code, detail) {
+    return new _ToolRefusal({
+      status: STATUS[code],
+      code,
+      ...clip("detail", detail, 300)
+    });
+  }
+};
+function clip(key, value, max) {
+  if (value === void 0) return {};
+  return { [key]: [...value].slice(0, max).join("") };
+}
+
+// src/tools/provider.ts
+var ACCEPTED = { ok: true };
+var KEEP_SECONDS = {
+  submit_flow: 31 * 86400,
+  // a conversation lives up to 30 days, and a submission is resent in later sessions
+  create_proposal: 8 * 86400,
+  // at least until the proposal expires (at most 7 days)
+  default: 86400,
+  pending: 60
+};
+var MAX_IDEMPOTENCY_KEY = 255;
+var MAX_REQUEST_BYTES = 1024 * 1024;
+var LeaseLostError = class extends Error {
+  constructor(operation, leaseSeconds) {
+    super(
+      `${operation} ran longer than its ${leaseSeconds}-second idempotency lease and another call took the key: the answer was sent but not stored (raise leaseSeconds)`
+    );
+    this.name = "LeaseLostError";
+  }
+};
+var ResultTooLargeError = class extends Error {
+  constructor(operation, bytes, limit) {
+    super(
+      `${operation} returned ${bytes} bytes; the contract allows ${limit}: the runtime would refuse it`
+    );
+    this.name = "ResultTooLargeError";
+  }
+};
+function createToolProvider(options) {
+  const secrets = typeof options.secret === "string" ? [options.secret] : [...options.secret];
+  if (secrets.length === 0 || secrets.some((s) => typeof s !== "string" || !s)) {
+    throw new TypeError("createToolProvider needs the tool signing secret");
+  }
+  checkTolerance(options.toleranceSeconds);
+  const maxRequest = options.maxRequestBytes;
+  if (maxRequest !== void 0 && (!Number.isSafeInteger(maxRequest) || maxRequest <= 0)) {
+    throw new TypeError(
+      `maxRequestBytes must be a positive whole number of bytes, not ${maxRequest}`
+    );
+  }
+  const lease = options.leaseSeconds ?? KEEP_SECONDS.pending;
+  if (!Number.isFinite(lease) || lease <= 0) {
+    throw new TypeError(
+      `leaseSeconds must be a positive number of seconds, not ${options.leaseSeconds}`
+    );
+  }
+  if (typeof options.authenticate !== "function") {
+    throw new TypeError(
+      "createToolProvider needs authenticate: it resolves the delegated token"
+    );
+  }
+  const base = (options.basePath ?? "").replace(/\/+$/, "");
+  const routes = Object.values(TOOL_OPERATIONS).map((o) => ({
+    id: o.id,
+    segments: o.path.split("/").filter(Boolean)
+  }));
+  async function handle(request) {
+    const raw = request.body ?? new Uint8Array(0);
+    const body = toBytes(raw);
+    if (body.length > (options.maxRequestBytes ?? MAX_REQUEST_BYTES)) {
+      return problem({
+        status: 413,
+        code: "invalid_argument",
+        detail: "the request body is too large"
+      });
+    }
+    const token = bearer(request.header("authorization"));
+    if (!token) {
+      return problem({
+        status: 401,
+        code: "token_expired",
+        detail: "no delegated token (Authorization: Bearer)"
+      });
+    }
+    const refused = await verifyToolCall(
+      {
+        method: request.method,
+        target: request.target,
+        token,
+        body,
+        header: request.header("vinaverse-signature")
+      },
+      {
+        secrets,
+        nonces: options.nonces,
+        now: options.now?.() ?? /* @__PURE__ */ new Date(),
+        ...options.toleranceSeconds === void 0 ? {} : { toleranceSeconds: options.toleranceSeconds }
+      }
+    );
+    if (refused) {
+      options.onRefused?.(refused.code, refused.message);
+      return problem({
+        status: 403,
+        code: "forbidden",
+        detail: "the signature was refused"
+      });
+    }
+    const matched = match(request.method, request.target);
+    if (!matched)
+      return problem({
+        status: 404,
+        code: "not_found",
+        detail: "no such tool"
+      });
+    const { id, params, query } = matched;
+    const operation = TOOL_OPERATIONS[id];
+    const handler = options.handlers[id];
+    if (!handler)
+      return problem({
+        status: 404,
+        code: "not_found",
+        detail: `${id} is not served here`
+      });
+    try {
+      const principal = await options.authenticate(token, id);
+      const typedQuery = readQuery(id, query);
+      const parsed = operation.body ? parseBody(body) : void 0;
+      const key = request.header("idempotency-key");
+      if (operation.idempotencyKey && !key) {
+        throw ToolRefusal.invalidArgument({
+          detail: "the Idempotency-Key header is required"
+        });
+      }
+      if (key && key.length > MAX_IDEMPOTENCY_KEY) {
+        throw ToolRefusal.invalidArgument({
+          detail: `the Idempotency-Key is longer than ${MAX_IDEMPOTENCY_KEY} characters`
+        });
+      }
+      const call = {
+        operation: id,
+        principal,
+        token,
+        params,
+        query: typedQuery,
+        body: parsed,
+        session: session(request),
+        ...key ? { idempotencyKey: key } : {}
+      };
+      const run = () => runHandler(id, handler, call);
+      const scope = options.scope?.(principal, id);
+      const keyOf = (...parts) => (scope === void 0 ? parts : [scope, ...parts]).map(encodeURIComponent).join(":");
+      if (id === "submit_flow")
+        return await submission(keyOf, params, parsed, run);
+      if (id === "create_proposal" && key)
+        return await proposal(keyOf(id, key), parsed, principal, run);
+      if (operation.idempotencyKey && key) {
+        return await keyed(
+          id,
+          keyOf(id, key),
+          await fingerprint(parsed),
+          KEEP_SECONDS.default,
+          run,
+          () => problem({
+            status: 409,
+            code: "IDEMPOTENCY_KEY_REUSED",
+            detail: "this Idempotency-Key was used with another body"
+          })
+        );
+      }
+      return await run();
+    } catch (error) {
+      return failure(error, id);
+    }
+  }
+  async function runHandler(id, handler, call) {
+    const result = await handler(call) ?? (id === "submit_flow" ? ACCEPTED : void 0);
+    if (result === void 0) {
+      throw new TypeError(`the ${id} handler returned nothing`);
+    }
+    const text = JSON.stringify(result);
+    const limit = TOOL_OPERATIONS[id].maxResultBytes;
+    const bytes = toBytes(text).length;
+    if (bytes > limit) throw new ResultTooLargeError(id, bytes, limit);
+    return json(TOOL_OPERATIONS[id].successStatus, text);
+  }
+  async function keyed(id, key, print, keepSeconds, run, conflict, replay, keeps = (r) => r.status === 422) {
+    const store = options.idempotency;
+    const owner = await ownerToken();
+    const held = await store.start(key, print, lease, owner);
+    if (held) {
+      if (held.state === "pending") {
+        return problem({
+          status: 503,
+          code: "unavailable",
+          detail: "the same call is still running"
+        });
+      }
+      if (held.fingerprint !== print) return conflict(held);
+      return replay ? replay(held) : stored(held);
+    }
+    let response;
+    try {
+      response = await run();
+    } catch (error) {
+      if (!(error instanceof ToolRefusal && keeps(error))) {
+        await store.release(key, owner);
+        throw error;
+      }
+      response = problem(error.problem);
+    }
+    try {
+      const kept = await store.finish(
+        key,
+        { fingerprint: print, status: response.status, body: response.body },
+        keepSeconds,
+        owner
+      );
+      if (!kept) options.onError?.(new LeaseLostError(id, lease), id);
+    } catch (error) {
+      options.onError?.(error, id);
+    }
+    return response;
+  }
+  async function submission(keyOf, params, body, run) {
+    const submissionId = body?.submission_id;
+    if (typeof submissionId !== "string" || submissionId === "") {
+      throw ToolRefusal.invalidArgument({
+        field: "/submission_id",
+        detail: "a submission needs its submission_id"
+      });
+    }
+    const refused = async () => {
+      try {
+        return await run();
+      } catch (error) {
+        if (error instanceof ToolRefusal && error.status === 422 && !isFlowRefusal(error.problem)) {
+          throw new TypeError(
+            `submit_flow refused with ${error.problem.code}: a submission is refused only with ToolRefusal.flowRefused (a flow code and the question to ask again)`
+          );
+        }
+        throw error;
+      }
+    };
+    return keyed(
+      "submit_flow",
+      keyOf("submit_flow", params.flow ?? "", submissionId),
+      await fingerprint(body),
+      KEEP_SECONDS.submit_flow,
+      refused,
+      (held) => {
+        const was = held.body ? JSON.parse(held.body) : {};
+        const storedResult = held.status === 200 ? { result: "accepted" } : {
+          result: "refused",
+          ...was.code ? { code: was.code } : {},
+          ...was.question_id ? { question_id: was.question_id } : {}
+        };
+        return json(
+          409,
+          JSON.stringify({
+            status: 409,
+            code: "SUBMISSION_ID_REUSED",
+            stored: storedResult
+          }),
+          "application/problem+json"
+        );
+      },
+      void 0,
+      (r) => isFlowRefusal(r.problem)
+    );
+  }
+  async function proposal(key, body, principal, run) {
+    const { topic, changes } = body ?? {};
+    const current = async (held) => {
+      const storedProposal = JSON.parse(
+        held.body ?? "null"
+      );
+      return options.currentProposal ? await options.currentProposal(storedProposal, principal) : storedProposal;
+    };
+    return keyed(
+      "create_proposal",
+      key,
+      await fingerprint({ topic, changes }),
+      KEEP_SECONDS.create_proposal,
+      run,
+      async (held) => held.status === 201 ? json(
+        409,
+        JSON.stringify({
+          status: 409,
+          code: "IDEMPOTENCY_KEY_REUSED",
+          proposal: await current(held)
+        }),
+        "application/problem+json"
+      ) : stored(held),
+      async (held) => held.status === 201 ? json(201, JSON.stringify(await current(held))) : stored(held)
+    );
+  }
+  function match(method, target) {
+    const at = target.indexOf("?");
+    const path = at < 0 ? target : target.slice(0, at);
+    const query = new URLSearchParams(at < 0 ? "" : target.slice(at + 1));
+    if (base && path !== base && !path.startsWith(`${base}/`)) return void 0;
+    const segments = path.slice(base.length).split("/").filter(Boolean);
+    for (const route of routes) {
+      if (TOOL_OPERATIONS[route.id].method !== method.toUpperCase()) continue;
+      if (route.segments.length !== segments.length) continue;
+      const params = {};
+      let ok = true;
+      for (const [i, part] of route.segments.entries()) {
+        const actual = segments[i];
+        if (part.startsWith("{") && part.endsWith("}")) {
+          try {
+            params[part.slice(1, -1)] = decodeURIComponent(actual);
+          } catch {
+            ok = false;
+          }
+        } else if (part !== actual) {
+          ok = false;
+        }
+        if (!ok) break;
+      }
+      if (ok) return { id: route.id, params, query };
+    }
+    return void 0;
+  }
+  function failure(error, id) {
+    if (error instanceof ToolRefusal) return problem(error.problem);
+    options.onError?.(error, id);
+    return problem({
+      status: 500,
+      code: "unavailable",
+      detail: "the tool failed"
+    });
+  }
+  return { handle };
+}
+function readQuery(id, query) {
+  const declared = TOOL_OPERATIONS[id].queryParams;
+  const out = {};
+  for (const [name, spec] of Object.entries(declared)) {
+    const value = query.get(name);
+    if (value === null) {
+      if (spec.required)
+        throw ToolRefusal.invalidArgument({
+          detail: `the query parameter ${name} is required`
+        });
+      continue;
+    }
+    if (spec.type === "integer" || spec.type === "number") {
+      const n = Number(value);
+      if (value.trim() === "" || !Number.isFinite(n) || spec.type === "integer" && !Number.isInteger(n)) {
+        throw ToolRefusal.invalidArgument({
+          detail: `the query parameter ${name} must be ${spec.type === "integer" ? "an integer" : "a number"}`
+        });
+      }
+      out[name] = n;
+    } else {
+      out[name] = value;
+    }
+  }
+  return out;
+}
+function parseBody(body) {
+  if (body.length === 0)
+    throw ToolRefusal.invalidArgument({
+      detail: "the request needs a JSON body"
+    });
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body));
+  } catch {
+    throw ToolRefusal.invalidArgument({
+      detail: "the request body is not JSON"
+    });
+  }
+}
+function bearer(value) {
+  const m = /^Bearer\s+(\S+)\s*$/i.exec(value ?? "");
+  return m?.[1];
+}
+function session(request) {
+  const pick = (name) => request.header(name);
+  const entries = {
+    id: pick("vinaverse-session") ?? pick("vinaverse-session-id"),
+    conversationId: pick("vinaverse-conversation"),
+    toolCallId: pick("vinaverse-tool-call-id"),
+    requestId: pick("vinaverse-request-id")
+  };
+  return Object.fromEntries(
+    Object.entries(entries).filter(([, v]) => v !== void 0)
+  );
+}
+async function ownerToken() {
+  const bytes = (await webCrypto()).getRandomValues(new Uint8Array(16));
+  return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function json(status, body, type = "application/json") {
+  return { status, headers: { "content-type": type }, body };
+}
+function problem(body) {
+  return json(body.status, JSON.stringify(body), "application/problem+json");
+}
+function stored(held) {
+  const status = held.status ?? 200;
+  return json(
+    status,
+    held.body ?? "",
+    status >= 400 ? "application/problem+json" : "application/json"
+  );
+}
+
+// src/webhooks/sequence.ts
+function sequenceVerdict(held, incoming) {
+  if (held && held.conversation_id !== incoming.conversation_id) {
+    throw new TypeError(
+      `the states belong to different conversations (${held.conversation_id}, ${incoming.conversation_id})`
+    );
+  }
+  return held && incoming.sequence <= held.sequence ? "stale" : "apply";
+}
+function applyConversationState(record, incoming) {
+  const action = sequenceVerdict(record?.state, incoming);
+  const seen = record?.seen.includes(incoming.sequence) ? record.seen : [...record?.seen ?? [], incoming.sequence].sort((a, b) => a - b);
+  if (action === "stale" && record)
+    return { record: { ...record, seen }, action };
+  if (incoming.answers_omitted === true) {
+    const { answers_omitted: _omitted, ...rest } = incoming;
+    const state = {
+      ...rest,
+      answers: record?.state.answers ?? [],
+      remarks: record?.state.remarks ?? {}
+    };
+    return { record: { state, seen, fullReadNeeded: true }, action };
+  }
+  return { record: { state: incoming, seen, fullReadNeeded: false }, action };
+}
+function missingSequences(record) {
+  const [lowest] = record.seen;
+  if (lowest === void 0) return [];
+  const missing = [];
+  for (let s = lowest + 1; s < record.state.sequence; s++) {
+    if (!record.seen.includes(s)) missing.push(s);
+  }
+  return missing;
+}
+var ConversationReceiver = class {
+  #ids = /* @__PURE__ */ new Set();
+  #records = /* @__PURE__ */ new Map();
+  /**
+   * One verified delivery (an event, or a Studio test delivery's envelope):
+   * what to do with it. The record for its conversation is then `record(id)`.
+   */
+  receive(delivery) {
+    if (this.#ids.has(delivery.id)) return "duplicate";
+    this.#ids.add(delivery.id);
+    const data = delivery.data;
+    if (data?.test === true) return "skip_test";
+    if (typeof data?.conversation_id !== "string") {
+      throw new TypeError(`${delivery.id} carries no conversation state`);
+    }
+    const state = data;
+    const { record, action } = applyConversationState(
+      this.#records.get(state.conversation_id),
+      state
+    );
+    this.#records.set(state.conversation_id, record);
+    return action;
+  }
+  record(conversationId) {
+    return this.#records.get(conversationId);
+  }
+  conversations() {
+    return [...this.#records.keys()].sort();
+  }
+};
+
+export { CONTRACT, ConversationReceiver, KEEP_SECONDS, LeaseLostError, MAX_REQUEST_BYTES, MemoryIdempotencyStore, ResultTooLargeError, TOOL_OPERATIONS, ToolRefusal, applyConversationState, canonicalJson, createToolProvider, fingerprint, missingSequences, sequenceVerdict };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map