@realtimex/sdk 1.3.4 → 1.3.5-rc.2

package/dist/index.mjs

@@ -228,6 +228,204 @@ var ActivitiesModule = class {
   }
 };
 
+// src/modules/contract.ts
+import { createHash, createHmac, randomUUID } from "crypto";
+var LOCAL_APP_CONTRACT_VERSION = "local-app-contract/v1";
+var CONTRACT_SIGNATURE_HEADER = "x-rtx-contract-signature";
+var CONTRACT_EVENT_ID_HEADER = "x-rtx-event-id";
+var CONTRACT_SIGNATURE_ALGORITHM = "sha256";
+var CONTRACT_ATTEMPT_PREFIX = "run-";
+var CONTRACT_EVENT_ALIASES = {
+  "trigger-agent": "task.trigger",
+  "task.trigger": "task.trigger",
+  ping: "system.ping",
+  "system.ping": "system.ping",
+  claim: "task.claimed",
+  claimed: "task.claimed",
+  "task.claimed": "task.claimed",
+  "task-start": "task.started",
+  start: "task.started",
+  "task.started": "task.started",
+  "task-progress": "task.progress",
+  progress: "task.progress",
+  processing: "task.progress",
+  "task.progress": "task.progress",
+  "task-complete": "task.completed",
+  complete: "task.completed",
+  completed: "task.completed",
+  "task.completed": "task.completed",
+  "task-fail": "task.failed",
+  fail: "task.failed",
+  failed: "task.failed",
+  "task.failed": "task.failed",
+  "task-cancel": "task.canceled",
+  "task-cancelled": "task.canceled",
+  "task-canceled": "task.canceled",
+  cancel: "task.canceled",
+  cancelled: "task.canceled",
+  canceled: "task.canceled",
+  "task.canceled": "task.canceled"
+};
+var CONTRACT_LEGACY_ACTIONS = {
+  "task.trigger": "trigger-agent",
+  "system.ping": "ping",
+  "task.claimed": "claim",
+  "task.started": "start",
+  "task.progress": "progress",
+  "task.completed": "complete",
+  "task.failed": "fail",
+  "task.canceled": "cancel"
+};
+function normalizeContractEvent(eventLike) {
+  if (!eventLike || typeof eventLike !== "string") return null;
+  const normalized = CONTRACT_EVENT_ALIASES[eventLike.trim().toLowerCase()];
+  return normalized || null;
+}
+function normalizeAttemptId(attemptLike) {
+  if (attemptLike === null || attemptLike === void 0) return void 0;
+  if (typeof attemptLike === "number" && Number.isInteger(attemptLike) && attemptLike > 0) {
+    return `${CONTRACT_ATTEMPT_PREFIX}${attemptLike}`;
+  }
+  if (typeof attemptLike !== "string") return void 0;
+  const trimmed = attemptLike.trim();
+  if (!trimmed) return void 0;
+  if (trimmed.startsWith(CONTRACT_ATTEMPT_PREFIX)) return trimmed;
+  if (/^\d+$/.test(trimmed)) return `${CONTRACT_ATTEMPT_PREFIX}${trimmed}`;
+  return trimmed;
+}
+function parseAttemptRunId(attemptLike) {
+  const attemptId = normalizeAttemptId(attemptLike);
+  if (!attemptId) return null;
+  const matched = attemptId.match(/^run[-_:]?(\d+)$/i);
+  if (!matched) return null;
+  const value = Number(matched[1]);
+  return Number.isInteger(value) && value > 0 ? value : null;
+}
+function hashContractPayload(payload) {
+  const normalized = payload && typeof payload === "object" ? payload : { value: payload ?? null };
+  return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+}
+function createContractEventId() {
+  return randomUUID();
+}
+function buildContractSignatureMessage({
+  eventId,
+  eventType,
+  taskId,
+  attemptId,
+  timestamp,
+  payload
+}) {
+  return [
+    String(eventId || ""),
+    String(normalizeContractEvent(String(eventType || "")) || eventType || ""),
+    String(taskId || ""),
+    String(normalizeAttemptId(attemptId) || ""),
+    String(timestamp || ""),
+    hashContractPayload(payload ?? {})
+  ].join(".");
+}
+function signContractEvent(input) {
+  const signatureMessage = buildContractSignatureMessage(input);
+  const digest = createHmac(CONTRACT_SIGNATURE_ALGORITHM, input.secret).update(signatureMessage).digest("hex");
+  return `${CONTRACT_SIGNATURE_ALGORITHM}=${digest}`;
+}
+function canonicalEventToLegacyAction(eventLike) {
+  const normalized = normalizeContractEvent(eventLike);
+  if (!normalized) return null;
+  return CONTRACT_LEGACY_ACTIONS[normalized] || null;
+}
+function buildContractIdempotencyKey({
+  taskId,
+  eventType,
+  eventId,
+  attemptId,
+  machineId,
+  timestamp,
+  payload
+}) {
+  const canonicalEvent = normalizeContractEvent(eventType) || eventType;
+  if (eventId) {
+    const eventToken = createHash("sha256").update(String(eventId)).digest("hex");
+    return `${taskId}:${canonicalEvent}:event:${eventToken}`;
+  }
+  const hashInput = {
+    task_id: taskId,
+    event_type: canonicalEvent,
+    attempt_id: normalizeAttemptId(attemptId),
+    machine_id: machineId || null,
+    timestamp: timestamp || null,
+    payload_hash: hashContractPayload(payload ?? {})
+  };
+  const token = createHash("sha256").update(JSON.stringify(hashInput)).digest("hex");
+  return `${taskId}:${canonicalEvent}:hash:${token}`;
+}
+var ContractModule = class {
+  constructor(realtimexUrl, appName, appId, apiKey) {
+    this.cachedContract = null;
+    this.realtimexUrl = realtimexUrl.replace(/\/$/, "");
+    this.appName = appName;
+    this.appId = appId;
+    this.apiKey = apiKey;
+  }
+  async requestPermission(permission) {
+    try {
+      const response = await fetch(`${this.realtimexUrl}/api/local-apps/request-permission`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          app_id: this.appId,
+          app_name: this.appName,
+          permission
+        })
+      });
+      const data = await response.json();
+      return data.granted === true;
+    } catch {
+      return false;
+    }
+  }
+  async request(path) {
+    const url = `${this.realtimexUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+    if (this.appId) headers["x-app-id"] = this.appId;
+    const response = await fetch(url, {
+      method: "GET",
+      headers
+    });
+    const data = await response.json();
+    if (response.status === 403) {
+      const errorCode = data.error;
+      const permission = data.permission;
+      const message = data.message;
+      if (errorCode === "PERMISSION_REQUIRED" && permission) {
+        const granted = await this.requestPermission(permission);
+        if (granted) return this.request(path);
+        throw new PermissionDeniedError(permission, message);
+      }
+      if (errorCode === "PERMISSION_DENIED") {
+        throw new PermissionDeniedError(permission, message);
+      }
+    }
+    if (!response.ok) {
+      throw new Error(data.error || `Request failed: ${response.status}`);
+    }
+    return data;
+  }
+  async getLocalAppV1(forceRefresh = false) {
+    if (!forceRefresh && this.cachedContract) return this.cachedContract;
+    const data = await this.request("/contracts/local-app/v1");
+    this.cachedContract = data.contract;
+    return data.contract;
+  }
+  clearCache() {
+    this.cachedContract = null;
+  }
+};
+
 // src/modules/webhook.ts
 var WebhookModule = class {
   constructor(realtimexUrl, appName, appId, apiKey) {
@@ -304,7 +502,9 @@ var WebhookModule = class {
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
-        event: "trigger-agent",
+        event: "task.trigger",
+        event_id: payload.event_id || createContractEventId(),
+        attempt_id: normalizeAttemptId(payload.attempt_id),
         payload: {
           raw_data: payload.raw_data,
           auto_run: payload.auto_run ?? false,
@@ -322,7 +522,8 @@ var WebhookModule = class {
       body: JSON.stringify({
         app_name: this.appName,
         app_id: this.appId,
-        event: "ping"
+        event: "system.ping",
+        event_id: createContractEventId()
       })
     });
   }
@@ -335,49 +536,148 @@ var TaskModule = class {
     this.appName = appName;
     this.appId = appId;
     this.apiKey = apiKey;
+    this.callbackSecret = process.env.RTX_CONTRACT_CALLBACK_SECRET;
+    this.signCallbacksByDefault = process.env.RTX_CONTRACT_SIGN_CALLBACKS === "true";
+  }
+  /**
+   * Configure callback signing behavior.
+   */
+  configureContract(config) {
+    if (typeof config.callbackSecret === "string") {
+      this.callbackSecret = config.callbackSecret;
+    }
+    if (typeof config.signCallbacksByDefault === "boolean") {
+      this.signCallbacksByDefault = config.signCallbacksByDefault;
+    }
+  }
+  /**
+   * Claim a task before processing.
+   */
+  async claim(taskUuid, options = {}) {
+    return this._sendEvent("task.claimed", taskUuid, {}, options);
+  }
+  /**
+   * Alias for claim()
+   */
+  async claimed(taskUuid, options = {}) {
+    return this.claim(taskUuid, options);
+  }
+  /**
+   * Mark task as processing.
+   * Backward compatible signature: start(taskUuid, machineId?)
+   */
+  async start(taskUuid, machineIdOrOptions) {
+    return this._sendEvent("task.started", taskUuid, {}, this._normalizeOptions(machineIdOrOptions));
   }
   /**
-   * Mark task as processing
+   * Report incremental task progress.
    */
-  async start(taskUuid, machineId) {
-    return this._sendEvent("task-start", taskUuid, { machine_id: machineId });
+  async progress(taskUuid, progressData = {}, options = {}) {
+    return this._sendEvent("task.progress", taskUuid, progressData, options);
   }
   /**
-   * Mark task as completed with result
+   * Mark task as completed with result.
+   * Backward compatible signature: complete(taskUuid, result?, machineId?)
    */
-  async complete(taskUuid, result, machineId) {
-    return this._sendEvent("task-complete", taskUuid, { result, machine_id: machineId });
+  async complete(taskUuid, result = {}, machineIdOrOptions) {
+    return this._sendEvent("task.completed", taskUuid, { result }, this._normalizeOptions(machineIdOrOptions));
   }
   /**
-   * Mark task as failed with error
+   * Mark task as failed with error.
+   * Backward compatible signature: fail(taskUuid, error, machineId?)
    */
-  async fail(taskUuid, error, machineId) {
-    return this._sendEvent("task-fail", taskUuid, { error, machine_id: machineId });
+  async fail(taskUuid, error, machineIdOrOptions) {
+    return this._sendEvent("task.failed", taskUuid, { error }, this._normalizeOptions(machineIdOrOptions));
   }
-  async _sendEvent(event, taskUuid, extra) {
+  /**
+   * Mark task as canceled.
+   */
+  async cancel(taskUuid, reason, options = {}) {
+    const payload = reason ? { error: reason } : {};
+    return this._sendEvent("task.canceled", taskUuid, payload, options);
+  }
+  _normalizeOptions(machineIdOrOptions) {
+    if (!machineIdOrOptions) return {};
+    if (typeof machineIdOrOptions === "string") {
+      return { machineId: machineIdOrOptions };
+    }
+    return machineIdOrOptions;
+  }
+  async _sendEvent(event, taskUuid, eventData = {}, options = {}) {
+    if (!taskUuid || !taskUuid.trim()) {
+      throw new Error("taskUuid is required");
+    }
+    const attemptId = normalizeAttemptId(options.attemptId);
+    const timestamp = options.timestamp || (/* @__PURE__ */ new Date()).toISOString();
+    const eventId = options.eventId || createContractEventId();
+    const callbackUrl = options.callbackUrl;
+    const targetUrl = callbackUrl || `${this.realtimexUrl}/webhooks/realtimex`;
+    const sendingToMainWebhook = !callbackUrl;
+    const includeAppAuth = sendingToMainWebhook || targetUrl.startsWith(this.realtimexUrl);
+    const payloadData = eventData && typeof eventData === "object" ? eventData : {};
     const headers = { "Content-Type": "application/json" };
-    if (this.apiKey) {
-      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    headers[CONTRACT_EVENT_ID_HEADER] = eventId;
+    if (includeAppAuth) {
+      if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+      if (this.appId) headers["x-app-id"] = this.appId;
     }
-    if (this.appId) {
-      headers["x-app-id"] = this.appId;
+    const callbackSecret = options.callbackSecret || this.callbackSecret;
+    const shouldSign = options.sign ?? this.signCallbacksByDefault;
+    if (shouldSign) {
+      if (!callbackSecret) {
+        throw new Error(
+          "Callback signing is enabled but no callbackSecret is configured. Use task.configureContract({ callbackSecret }) or pass options.callbackSecret."
+        );
+      }
+      headers[CONTRACT_SIGNATURE_HEADER] = signContractEvent({
+        secret: callbackSecret,
+        eventId,
+        eventType: event,
+        taskId: taskUuid,
+        attemptId,
+        timestamp,
+        payload: payloadData
+      });
     }
-    const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+    const requestBody = sendingToMainWebhook ? {
+      app_name: this.appName,
+      app_id: this.appId,
+      event,
+      event_id: eventId,
+      attempt_id: attemptId,
+      payload: {
+        task_uuid: taskUuid,
+        machine_id: options.machineId,
+        timestamp,
+        attempt_id: attemptId,
+        ...payloadData
+      }
+    } : {
+      event,
+      action: canonicalEventToLegacyAction(event),
+      event_id: eventId,
+      attempt_id: attemptId,
+      machine_id: options.machineId,
+      user_email: options.userEmail,
+      activity_id: options.activityId,
+      table_name: options.tableName,
+      timestamp,
+      data: payloadData
+    };
+    const response = await fetch(targetUrl, {
       method: "POST",
       headers,
-      body: JSON.stringify({
-        app_name: this.appName,
-        app_id: this.appId,
-        event,
-        payload: {
-          task_uuid: taskUuid,
-          ...extra
-        }
-      })
+      body: JSON.stringify(requestBody)
     });
-    const data = await response.json();
-    if (!response.ok) throw new Error(data.error || `Failed to ${event}`);
-    return data;
+    const responseData = await response.json();
+    if (!response.ok) throw new Error(responseData.error || `Failed to ${event}`);
+    return {
+      ...responseData,
+      task_uuid: responseData.task_uuid || responseData.task_id || taskUuid,
+      event_id: responseData.event_id || eventId,
+      attempt_id: responseData.attempt_id || attemptId,
+      event_type: responseData.event_type || event
+    };
   }
 };
 
@@ -1413,6 +1713,1485 @@ var HttpClient = class {
   }
 };
 
+// src/core/errors/ContractErrors.ts
+var ContractError = class extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.details = details;
+  }
+};
+var ContractValidationError = class extends ContractError {
+  constructor(message, details) {
+    super("contract_validation_error", message, details);
+  }
+};
+var ToolValidationError = class extends ContractError {
+  constructor(message, details) {
+    super("tool_validation_error", message, details);
+  }
+};
+var ToolNotFoundError = class extends ContractError {
+  constructor(toolName, details) {
+    super("tool_not_found", `Tool not found: ${toolName}`, details);
+  }
+};
+var ScopeDeniedError = class extends ContractError {
+  constructor(permission, details) {
+    super("scope_denied", `Missing required permission: ${permission}`, details);
+  }
+};
+var RuntimeTransportError = class extends ContractError {
+  constructor(message, statusCode, details) {
+    super("runtime_transport_error", message, details);
+    this.statusCode = statusCode;
+  }
+};
+
+// src/core/auth/ScopeGuard.ts
+var ScopeGuard = class {
+  constructor(scopes = []) {
+    this.scopes = new Set(scopes.filter((scope) => scope.trim().length > 0));
+  }
+  can(permission) {
+    if (!permission) return true;
+    if (this.scopes.size === 0) return true;
+    return this.scopes.has(permission);
+  }
+  assert(permission) {
+    if (!permission) return;
+    if (!this.can(permission)) {
+      throw new ScopeDeniedError(permission);
+    }
+  }
+};
+
+// src/core/contract/ContractCache.ts
+var ContractCache = class {
+  constructor(ttlMs = 3e4) {
+    this.entries = /* @__PURE__ */ new Map();
+    this.ttlMs = ttlMs > 0 ? ttlMs : null;
+  }
+  get(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== null && entry.expiresAt <= Date.now()) {
+      this.entries.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  set(key, value) {
+    const expiresAt = this.ttlMs === null ? null : Date.now() + this.ttlMs;
+    this.entries.set(key, { value, expiresAt });
+  }
+  clear(key) {
+    if (key) {
+      this.entries.delete(key);
+      return;
+    }
+    this.entries.clear();
+  }
+};
+
+// src/core/contract/ContractValidator.ts
+var LOCAL_APP_CONTRACT_VERSION2 = "local-app-contract/v1";
+var DEFAULT_SUPPORTED_EVENTS = [
+  "task.trigger",
+  "system.ping",
+  "task.claimed",
+  "task.started",
+  "task.progress",
+  "task.completed",
+  "task.failed",
+  "task.canceled"
+];
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item) => typeof item === "string" && item.trim().length > 0);
+}
+function asStringRecord(value) {
+  if (!isRecord(value)) return void 0;
+  const entries = Object.entries(value).filter(
+    ([key, item]) => key.trim().length > 0 && typeof item === "string"
+  );
+  if (entries.length === 0) return void 0;
+  return entries.reduce((accumulator, [key, item]) => {
+    accumulator[key] = item;
+    return accumulator;
+  }, {});
+}
+function normalizeStrictness(value) {
+  return value === "strict" ? "strict" : "compatible";
+}
+function normalizeCallbackRules(value) {
+  if (!isRecord(value)) return void 0;
+  const callback = {};
+  if (typeof value.event_id_header === "string") callback.event_id_header = value.event_id_header;
+  if (typeof value.signature_header === "string") callback.signature_header = value.signature_header;
+  if (typeof value.signature_algorithm === "string") callback.signature_algorithm = value.signature_algorithm;
+  if (typeof value.signature_message === "string") callback.signature_message = value.signature_message;
+  if (typeof value.attempt_id_format === "string") callback.attempt_id_format = value.attempt_id_format;
+  if (typeof value.idempotency === "string") callback.idempotency = value.idempotency;
+  return Object.keys(callback).length > 0 ? callback : void 0;
+}
+function normalizeTrigger(value) {
+  if (!isRecord(value)) {
+    return { event: "task.trigger" };
+  }
+  const event = value.event === "task.trigger" ? "task.trigger" : "task.trigger";
+  const route = typeof value.route === "string" && value.route.trim().length > 0 ? value.route : void 0;
+  const payloadTemplate = isRecord(value.payload_template) ? value.payload_template : void 0;
+  return {
+    event,
+    route,
+    payload_template: payloadTemplate
+  };
+}
+function normalizeCapability(value) {
+  if (!isRecord(value)) {
+    throw new ContractValidationError("Invalid capability: expected object");
+  }
+  const capabilityId = typeof value.capability_id === "string" ? value.capability_id.trim() : "";
+  const name = typeof value.name === "string" ? value.name.trim() : "";
+  const description = typeof value.description === "string" ? value.description.trim() : "";
+  const permission = typeof value.permission === "string" ? value.permission.trim() : "";
+  if (!capabilityId || !name || !description || !permission) {
+    throw new ContractValidationError("Invalid capability: missing required fields", { capability: value });
+  }
+  if (!isRecord(value.input_schema)) {
+    throw new ContractValidationError("Invalid capability input_schema: expected JSON schema object", {
+      capability_id: capabilityId
+    });
+  }
+  return {
+    capability_id: capabilityId,
+    name,
+    description,
+    input_schema: value.input_schema,
+    output_schema: isRecord(value.output_schema) ? value.output_schema : void 0,
+    permission,
+    trigger: normalizeTrigger(value.trigger)
+  };
+}
+function normalizeCapabilities(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (!Array.isArray(value)) {
+    throw new ContractValidationError("Invalid capabilities: expected array");
+  }
+  return value.map(normalizeCapability);
+}
+function extractContractRecord(payload) {
+  if (!isRecord(payload)) {
+    throw new ContractValidationError("Invalid contract response: expected object payload");
+  }
+  if (isRecord(payload.contract)) {
+    return payload.contract;
+  }
+  return payload;
+}
+function resolveContractVersion(contract) {
+  if (typeof contract.contract_version === "string") return contract.contract_version;
+  if (typeof contract.version === "string") return contract.version;
+  if (typeof contract.id === "string") return contract.id;
+  return "";
+}
+function normalizeLocalAppContractV1(payload) {
+  const contract = extractContractRecord(payload);
+  const version = resolveContractVersion(contract);
+  if (!version) {
+    throw new ContractValidationError("Missing contract version in discovery response");
+  }
+  if (version !== LOCAL_APP_CONTRACT_VERSION2) {
+    throw new ContractValidationError("Unsupported contract version", {
+      expected: LOCAL_APP_CONTRACT_VERSION2,
+      received: version
+    });
+  }
+  const supportedContractEvents = asStringArray(contract.supported_contract_events).length > 0 ? asStringArray(contract.supported_contract_events) : asStringArray(contract.supported_events).length > 0 ? asStringArray(contract.supported_events) : DEFAULT_SUPPORTED_EVENTS;
+  return {
+    contract_version: LOCAL_APP_CONTRACT_VERSION2,
+    strictness: normalizeStrictness(contract.strictness),
+    supported_contract_events: supportedContractEvents,
+    supported_legacy_events: asStringArray(contract.supported_legacy_events),
+    aliases: asStringRecord(contract.aliases),
+    status_map: asStringRecord(contract.status_map),
+    legacy_action_map: asStringRecord(contract.legacy_action_map),
+    callback: normalizeCallbackRules(contract.callback),
+    capabilities: normalizeCapabilities(contract.capabilities)
+  };
+}
+
+// src/core/contract/ContractClient.ts
+var ContractClient = class {
+  constructor(httpClient, options = {}) {
+    this.httpClient = httpClient;
+    this.cache = options.cache || new ContractCache();
+    this.cacheKey = options.cacheKey || "local-app-contract/v1";
+  }
+  async getLocalAppV1(forceRefresh = false) {
+    if (!forceRefresh) {
+      const cached = this.cache.get(this.cacheKey);
+      if (cached) return cached;
+    }
+    const response = await this.httpClient.get("/contracts/local-app/v1");
+    const normalized = normalizeLocalAppContractV1(response);
+    this.cache.set(this.cacheKey, normalized);
+    return normalized;
+  }
+  clearCache() {
+    this.cache.clear(this.cacheKey);
+  }
+};
+
+// src/core/transport/HttpClient.ts
+function toRecordHeaders(input = {}) {
+  if (input instanceof Headers) {
+    const normalized = {};
+    input.forEach((value, key) => {
+      normalized[key] = value;
+    });
+    return normalized;
+  }
+  if (Array.isArray(input)) {
+    return Object.fromEntries(input);
+  }
+  return { ...input };
+}
+var ContractHttpClient = class {
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.appId = config.appId;
+    this.appName = config.appName;
+    this.apiKey = config.apiKey;
+    this.fetchImpl = config.fetchImpl || fetch;
+  }
+  async get(path, headers = {}) {
+    return this.request(path, {
+      method: "GET",
+      headers
+    });
+  }
+  async post(path, body, headers = {}) {
+    return this.request(path, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+  }
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = this.buildHeaders(options.headers);
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        ...options,
+        headers
+      });
+    } catch (error) {
+      throw new RuntimeTransportError("Failed to reach RealtimeX server", void 0, {
+        cause: error,
+        url
+      });
+    }
+    const payload = await this.parseResponse(response);
+    if (!response.ok) {
+      const errorMessage = payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string" ? payload.error : `Request failed with status ${response.status}`;
+      throw new RuntimeTransportError(errorMessage, response.status, payload);
+    }
+    return payload;
+  }
+  buildHeaders(extraHeaders = {}) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...toRecordHeaders(extraHeaders)
+    };
+    if (this.apiKey) {
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+    if (this.appId) {
+      headers["x-app-id"] = this.appId;
+    }
+    if (this.appName) {
+      headers["x-app-name"] = this.appName;
+    }
+    return headers;
+  }
+  async parseResponse(response) {
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+      try {
+        return await response.json();
+      } catch {
+        return {};
+      }
+    }
+    const text = await response.text();
+    if (!text) return {};
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { text };
+    }
+  }
+};
+
+// src/core/tooling/SchemaNormalizer.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function normalizeSchema(schema) {
+  if (!schema || !isRecord2(schema)) {
+    return {
+      type: "object",
+      properties: {},
+      additionalProperties: true
+    };
+  }
+  const normalized = deepClone(schema);
+  if (typeof normalized.type !== "string" && !Array.isArray(normalized.type)) {
+    normalized.type = "object";
+  }
+  if (normalized.type === "object" && !isRecord2(normalized.properties)) {
+    normalized.properties = {};
+  }
+  if (Array.isArray(normalized.required)) {
+    normalized.required = normalized.required.filter(
+      (field) => typeof field === "string" && field.trim().length > 0
+    );
+  }
+  return normalized;
+}
+
+// src/core/tooling/ToolNamePolicy.ts
+function normalizeToken(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function toStableToolName(capabilityId, namespace) {
+  const normalizedCapability = normalizeToken(capabilityId.replace(/\./g, "_"));
+  const normalizedNamespace = namespace ? normalizeToken(namespace) : "";
+  if (!normalizedCapability) {
+    return normalizedNamespace ? `${normalizedNamespace}_tool` : "tool";
+  }
+  const combined = normalizedNamespace && !normalizedCapability.startsWith(`${normalizedNamespace}_`) ? `${normalizedNamespace}_${normalizedCapability}` : normalizedCapability;
+  return /^[a-z]/.test(combined) ? combined : `tool_${combined}`;
+}
+
+// src/core/tooling/ToolProjector.ts
+var ToolProjector = class {
+  project(input) {
+    const capabilities = input.contract.capabilities || [];
+    const names = /* @__PURE__ */ new Set();
+    return capabilities.map((capability) => {
+      const baseName = toStableToolName(capability.capability_id, input.namespace || input.appId);
+      const uniqueName = this.ensureUniqueToolName(baseName, names);
+      return {
+        tool_name: uniqueName,
+        title: capability.name,
+        description: capability.description,
+        input_schema: normalizeSchema(capability.input_schema),
+        output_schema: capability.output_schema,
+        permission: capability.permission,
+        capability_id: capability.capability_id,
+        trigger: capability.trigger
+      };
+    });
+  }
+  ensureUniqueToolName(baseName, names) {
+    if (!names.has(baseName)) {
+      names.add(baseName);
+      return baseName;
+    }
+    let index = 2;
+    while (names.has(`${baseName}_${index}`)) {
+      index += 1;
+    }
+    const uniqueName = `${baseName}_${index}`;
+    names.add(uniqueName);
+    return uniqueName;
+  }
+};
+
+// src/core/runtime/ExecutionStore.ts
+var ExecutionStore = class {
+  constructor() {
+    this.registries = /* @__PURE__ */ new Map();
+  }
+  registerTools(registryKey, tools) {
+    const registry = /* @__PURE__ */ new Map();
+    for (const tool of tools) {
+      registry.set(tool.tool_name, tool);
+    }
+    this.registries.set(registryKey, registry);
+  }
+  hasRegistry(registryKey) {
+    return this.registries.has(registryKey);
+  }
+  getTool(registryKey, toolName) {
+    return this.registries.get(registryKey)?.get(toolName);
+  }
+  clear(registryKey) {
+    if (registryKey) {
+      this.registries.delete(registryKey);
+      return;
+    }
+    this.registries.clear();
+  }
+};
+
+// src/core/runtime/LifecycleReporter.ts
+var LifecycleReporter = class {
+  constructor() {
+    this.handlers = /* @__PURE__ */ new Set();
+  }
+  onEvent(handler) {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+  emit(event) {
+    for (const handler of this.handlers) {
+      try {
+        handler(event);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/core/runtime/RetryPolicy.ts
+function defaultShouldRetry(error) {
+  if (error && typeof error === "object") {
+    const status = error.statusCode;
+    if (typeof status === "number") {
+      return status >= 500 || status === 429;
+    }
+  }
+  return true;
+}
+var RetryPolicy = class {
+  constructor(options = {}) {
+    this.maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+    this.baseDelayMs = Math.max(0, options.baseDelayMs ?? 150);
+    this.maxDelayMs = Math.max(this.baseDelayMs, options.maxDelayMs ?? 2e3);
+    this.shouldRetry = options.shouldRetry || ((error) => defaultShouldRetry(error));
+  }
+  async execute(operation) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= this.maxAttempts; attempt += 1) {
+      try {
+        return await operation(attempt);
+      } catch (error) {
+        lastError = error;
+        const canRetry = attempt < this.maxAttempts && this.shouldRetry(error, attempt);
+        if (!canRetry) throw error;
+        const delayMs = Math.min(this.maxDelayMs, this.baseDelayMs * 2 ** (attempt - 1));
+        if (delayMs > 0) {
+          await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+      }
+    }
+    throw lastError instanceof Error ? lastError : new Error("Retry operation failed");
+  }
+};
+
+// src/core/runtime/ContractRuntime.ts
+var LIFECYCLE_EVENTS = /* @__PURE__ */ new Set([
+  "task.claimed",
+  "task.started",
+  "task.progress",
+  "task.completed",
+  "task.failed",
+  "task.canceled"
+]);
+var DEFAULT_PROVIDER = "gemini";
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toRecord(value) {
+  return isRecord3(value) ? value : {};
+}
+function resolveToolCallId(input) {
+  if (typeof input.tool_call_id === "string" && input.tool_call_id.trim().length > 0) {
+    return input.tool_call_id;
+  }
+  const payload = isRecord3(input.payload) ? input.payload : void 0;
+  if (payload && typeof payload.tool_call_id === "string" && payload.tool_call_id.trim().length > 0) {
+    return payload.tool_call_id;
+  }
+  const data = isRecord3(input.data) ? input.data : void 0;
+  if (data && typeof data.tool_call_id === "string" && data.tool_call_id.trim().length > 0) {
+    return data.tool_call_id;
+  }
+  return void 0;
+}
+var ContractRuntime = class {
+  constructor(options) {
+    if (!options.baseUrl) {
+      throw new ContractValidationError("ContractRuntime requires baseUrl");
+    }
+    this.appId = options.appId;
+    this.appName = options.appName;
+    this.defaultNamespace = options.namespace;
+    this.httpClient = new ContractHttpClient({
+      baseUrl: options.baseUrl,
+      appId: options.appId,
+      appName: options.appName,
+      apiKey: options.apiKey,
+      fetchImpl: options.fetchImpl
+    });
+    this.contractClient = new ContractClient(this.httpClient, {
+      cache: new ContractCache(options.cacheTtlMs ?? 3e4)
+    });
+    this.toolProjector = new ToolProjector();
+    this.executionStore = new ExecutionStore();
+    this.lifecycleReporter = new LifecycleReporter();
+    this.scopeGuard = new ScopeGuard(options.permissions || []);
+    this.retryPolicy = new RetryPolicy(options.retry);
+  }
+  async getContract(appId) {
+    this.assertAppContext(appId);
+    return this.contractClient.getLocalAppV1(false);
+  }
+  async getTools(input) {
+    this.assertAppContext(input.appId);
+    const contract = await this.contractClient.getLocalAppV1(false);
+    const tools = this.toolProjector.project({
+      contract,
+      provider: input.provider,
+      appId: input.appId,
+      namespace: input.namespace || this.defaultNamespace || input.appId
+    });
+    this.executionStore.registerTools(
+      this.buildRegistryKey(input.appId, input.provider, input.namespace),
+      tools
+    );
+    return tools;
+  }
+  async executeToolCall(call, context) {
+    try {
+      this.assertAppContext(context.appId);
+      const provider = context.provider || DEFAULT_PROVIDER;
+      const namespace = context.namespace || this.defaultNamespace || context.appId;
+      const registryKey = this.buildRegistryKey(context.appId, provider, namespace);
+      if (!this.executionStore.hasRegistry(registryKey)) {
+        await this.getTools({
+          appId: context.appId,
+          provider,
+          namespace
+        });
+      }
+      const tool = this.executionStore.getTool(registryKey, call.tool_name);
+      if (!tool) {
+        throw new ToolNotFoundError(call.tool_name, {
+          registryKey
+        });
+      }
+      this.scopeGuard.assert(tool.permission);
+      const validationErrors = this.validateToolArgs(tool, call.args);
+      if (validationErrors.length > 0) {
+        throw new ToolValidationError("Tool input validation failed", {
+          tool_name: call.tool_name,
+          errors: validationErrors
+        });
+      }
+      const eventId = context.idempotencyKey || call.tool_call_id;
+      const requestBody = this.buildTriggerRequestBody(call, context, tool, eventId);
+      const response = await this.retryPolicy.execute(
+        () => this.httpClient.post(tool.trigger.route || "/webhooks/realtimex", requestBody)
+      );
+      if (response.success === false) {
+        throw new RuntimeTransportError(response.error || "Failed to trigger task", void 0, response);
+      }
+      const taskId = this.resolveTaskId(response);
+      const attemptId = normalizeAttemptId(response.attempt_id);
+      this.tryEmitLifecycleEvent({
+        tool_call_id: call.tool_call_id,
+        task_id: taskId,
+        attempt_id: attemptId,
+        event_type: response.event_type,
+        event_id: response.event_id,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        payload: toRecord(response)
+      });
+      if (taskId) {
+        return {
+          status: "queued",
+          tool_call_id: call.tool_call_id,
+          task_id: taskId,
+          attempt_id: attemptId,
+          output: {
+            message: response.message || "Task accepted"
+          }
+        };
+      }
+      return {
+        status: "completed",
+        tool_call_id: call.tool_call_id,
+        output: toRecord(response)
+      };
+    } catch (error) {
+      return this.toFailedResult(call.tool_call_id, error);
+    }
+  }
+  onExecutionEvent(handler) {
+    return this.lifecycleReporter.onEvent(handler);
+  }
+  ingestExecutionEvent(input) {
+    const eventTypeRaw = typeof input.event_type === "string" && input.event_type || typeof input.event === "string" && input.event || "";
+    const normalized = normalizeContractEvent(eventTypeRaw);
+    if (!normalized || !LIFECYCLE_EVENTS.has(normalized)) {
+      return null;
+    }
+    const taskId = typeof input.task_id === "string" && input.task_id || typeof input.task_uuid === "string" && input.task_uuid || "";
+    if (!taskId) return null;
+    const event = {
+      tool_call_id: resolveToolCallId(input) || taskId,
+      task_id: taskId,
+      attempt_id: normalizeAttemptId(input.attempt_id),
+      event_type: normalized,
+      event_id: typeof input.event_id === "string" && input.event_id || `${taskId}:${normalized}:${Date.now()}`,
+      timestamp: typeof input.timestamp === "string" && input.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+      payload: toRecord(input.payload || input.data)
+    };
+    this.lifecycleReporter.emit(event);
+    return event;
+  }
+  clearCache() {
+    this.contractClient.clearCache();
+    this.executionStore.clear();
+  }
+  assertAppContext(appId) {
+    if (!appId || appId.trim().length === 0) {
+      throw new ContractValidationError("appId is required");
+    }
+    if (this.appId && this.appId !== appId) {
+      throw new ContractValidationError("Runtime appId mismatch", {
+        runtime_app_id: this.appId,
+        requested_app_id: appId
+      });
+    }
+  }
+  buildRegistryKey(appId, provider, namespace) {
+    const resolvedNamespace = namespace || this.defaultNamespace || appId;
+    return `${appId}:${provider}:${resolvedNamespace}`;
+  }
+  resolveTaskId(response) {
+    if (typeof response.task_uuid === "string" && response.task_uuid.trim().length > 0) {
+      return response.task_uuid;
+    }
+    if (typeof response.task_id === "string" && response.task_id.trim().length > 0) {
+      return response.task_id;
+    }
+    return void 0;
+  }
+  buildTriggerRequestBody(call, context, tool, eventId) {
+    const payloadTemplate = isRecord3(tool.trigger.payload_template) ? tool.trigger.payload_template : {};
+    const templateRawData = isRecord3(payloadTemplate.raw_data) ? payloadTemplate.raw_data : {};
+    const payload = {
+      ...payloadTemplate,
+      raw_data: {
+        ...templateRawData,
+        capability_id: tool.capability_id,
+        tool_name: call.tool_name,
+        tool_call_id: call.tool_call_id,
+        args: call.args,
+        context: {
+          user_id: context.userId,
+          workspace_id: context.workspaceId || null,
+          request_id: context.requestId || null,
+          metadata: context.metadata || null
+        }
+      }
+    };
+    if (typeof payload.auto_run !== "boolean") {
+      payload.auto_run = false;
+    }
+    return {
+      app_name: this.appName,
+      app_id: this.appId || context.appId,
+      event: tool.trigger.event,
+      event_id: eventId,
+      payload
+    };
+  }
+  validateToolArgs(tool, args) {
+    const errors = [];
+    if (!isRecord3(args)) {
+      errors.push("args must be an object");
+      return errors;
+    }
+    const requiredFields = Array.isArray(tool.input_schema.required) ? tool.input_schema.required.filter((field) => typeof field === "string") : [];
+    for (const field of requiredFields) {
+      const value = args[field];
+      if (value === void 0 || value === null || typeof value === "string" && value.trim().length === 0) {
+        errors.push(`Missing required field: ${field}`);
+      }
+    }
+    const properties = isRecord3(tool.input_schema.properties) ? tool.input_schema.properties : {};
+    for (const [field, schemaValue] of Object.entries(properties)) {
+      if (!(field in args)) continue;
+      if (!isRecord3(schemaValue)) continue;
+      const typeValue = schemaValue.type;
+      if (typeof typeValue === "string") {
+        if (!this.matchesType(args[field], typeValue)) {
+          errors.push(`Invalid type for ${field}: expected ${typeValue}`);
+        }
+      }
+      if (Array.isArray(typeValue)) {
+        const valid = typeValue.some(
+          (item) => typeof item === "string" && this.matchesType(args[field], item)
+        );
+        if (!valid) {
+          errors.push(
+            `Invalid type for ${field}: expected one of ${typeValue.filter((item) => typeof item === "string").join(", ")}`
+          );
+        }
+      }
+    }
+    return errors;
+  }
+  matchesType(value, expectedType) {
+    switch (expectedType) {
+      case "string":
+        return typeof value === "string";
+      case "number":
+        return typeof value === "number" && Number.isFinite(value);
+      case "integer":
+        return typeof value === "number" && Number.isInteger(value);
+      case "boolean":
+        return typeof value === "boolean";
+      case "object":
+        return isRecord3(value);
+      case "array":
+        return Array.isArray(value);
+      case "null":
+        return value === null;
+      default:
+        return true;
+    }
+  }
+  tryEmitLifecycleEvent(input) {
+    if (!input.task_id || !input.event_type) return;
+    const normalized = normalizeContractEvent(input.event_type);
+    if (!normalized || !LIFECYCLE_EVENTS.has(normalized)) {
+      return;
+    }
+    this.lifecycleReporter.emit({
+      tool_call_id: input.tool_call_id,
+      task_id: input.task_id,
+      attempt_id: normalizeAttemptId(input.attempt_id),
+      event_type: normalized,
+      event_id: input.event_id || `${input.task_id}:${normalized}:${Date.now()}`,
+      timestamp: input.timestamp,
+      payload: input.payload
+    });
+  }
+  toFailedResult(toolCallId, error) {
+    if (error instanceof ContractError) {
+      const retryable = error instanceof RuntimeTransportError ? error.statusCode === void 0 || error.statusCode >= 500 || error.statusCode === 429 : false;
+      return {
+        status: "failed",
+        tool_call_id: toolCallId,
+        error: {
+          code: error.code,
+          message: error.message,
+          retryable
+        }
+      };
+    }
+    if (error instanceof Error) {
+      return {
+        status: "failed",
+        tool_call_id: toolCallId,
+        error: {
+          code: "runtime_error",
+          message: error.message,
+          retryable: true
+        }
+      };
+    }
+    return {
+      status: "failed",
+      tool_call_id: toolCallId,
+      error: {
+        code: "runtime_error",
+        message: "Unknown runtime error",
+        retryable: true
+      }
+    };
+  }
+};
+
+// src/core/auth/AuthProvider.ts
+var StaticAuthProvider = class {
+  constructor(options = {}) {
+    this.appId = options.appId;
+    this.appName = options.appName;
+    this.apiKey = options.apiKey;
+  }
+  buildHeaders(baseHeaders = {}) {
+    const headers = { ...baseHeaders };
+    if (this.apiKey) {
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+    if (this.appId) {
+      headers["x-app-id"] = this.appId;
+    }
+    if (this.appName) {
+      headers["x-app-name"] = this.appName;
+    }
+    return headers;
+  }
+};
+
+// src/adapters/gemini/GeminiToolAdapter.ts
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseArgs(value) {
+  if (isRecord4(value)) return value;
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return isRecord4(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+var GeminiToolAdapter = class {
+  toProviderTools(tools) {
+    return tools.map((tool) => ({
+      name: tool.tool_name,
+      description: tool.description,
+      parameters: tool.input_schema
+    }));
+  }
+  fromProviderToolCall(call) {
+    return {
+      tool_call_id: call.id,
+      tool_name: call.name,
+      args: parseArgs(call.args)
+    };
+  }
+  toProviderResult(result) {
+    return {
+      tool_call_id: result.tool_call_id || result.task_id || "unknown",
+      status: result.status,
+      payload: result.status === "failed" ? { error: result.error } : {
+        ...result.output || {},
+        task_id: result.task_id,
+        attempt_id: result.attempt_id
+      }
+    };
+  }
+};
+
+// src/adapters/claude/ClaudeToolAdapter.ts
+var ClaudeToolAdapter = class {
+  toProviderTools(tools) {
+    return tools.map((tool) => ({
+      name: tool.tool_name,
+      description: tool.description,
+      input_schema: tool.input_schema
+    }));
+  }
+  fromProviderToolCall(call) {
+    return {
+      tool_call_id: call.id,
+      tool_name: call.name,
+      args: call.input || {}
+    };
+  }
+  toProviderResult(result) {
+    const contentPayload = result.status === "failed" ? { error: result.error } : {
+      ...result.output || {},
+      task_id: result.task_id,
+      attempt_id: result.attempt_id
+    };
+    return {
+      type: "tool_result",
+      tool_use_id: result.tool_call_id || result.task_id || "unknown",
+      content: JSON.stringify(contentPayload),
+      is_error: result.status === "failed" ? true : void 0
+    };
+  }
+};
+
+// src/adapters/codex/CodexToolAdapter.ts
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseArguments(value) {
+  if (isRecord5(value)) return value;
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return isRecord5(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+var CodexToolAdapter = class {
+  toProviderTools(tools) {
+    return tools.map((tool) => ({
+      type: "function",
+      function: {
+        name: tool.tool_name,
+        description: tool.description,
+        parameters: tool.input_schema
+      }
+    }));
+  }
+  fromProviderToolCall(call) {
+    return {
+      tool_call_id: call.id,
+      tool_name: call.function.name,
+      args: parseArguments(call.function.arguments)
+    };
+  }
+  toProviderResult(result) {
+    const outputPayload = result.status === "failed" ? { error: result.error } : {
+      ...result.output || {},
+      task_id: result.task_id,
+      attempt_id: result.attempt_id
+    };
+    return {
+      tool_call_id: result.tool_call_id || result.task_id || "unknown",
+      output: JSON.stringify(outputPayload),
+      is_error: result.status === "failed" ? true : void 0
+    };
+  }
+};
+
+// src/acp/ACPEventMapper.ts
+function getErrorMessage(error) {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  return "Unknown error";
+}
+function buildRealtimeXMeta(input) {
+  return {
+    realtimex: {
+      tool_call_id: input.reference.toolCallId,
+      task_id: input.taskId,
+      attempt_id: input.attemptId,
+      event_id: input.eventId,
+      contract_version: "local-app-contract/v1",
+      contract_event: input.contractEvent,
+      cancelled: input.cancelled === true ? true : void 0,
+      app_id: input.reference.appId,
+      user_id: input.reference.userId,
+      workspace_id: input.reference.workspaceId,
+      provider: input.reference.provider,
+      namespace: input.reference.namespace
+    }
+  };
+}
+var ACPEventMapper = class {
+  createReference(invocation, context) {
+    return {
+      sessionId: context.sessionId,
+      toolCallId: invocation.toolCallId,
+      appId: context.appId,
+      userId: context.userId,
+      workspaceId: context.workspaceId,
+      provider: context.provider,
+      namespace: context.namespace,
+      title: invocation.title || invocation.toolName,
+      kind: invocation.kind || "execute"
+    };
+  }
+  buildPendingUpdate(invocation, reference) {
+    return {
+      sessionId: reference.sessionId,
+      update: {
+        type: "tool_call",
+        toolCallId: invocation.toolCallId,
+        title: reference.title,
+        kind: reference.kind,
+        status: "pending",
+        rawInput: invocation.args,
+        _meta: buildRealtimeXMeta({
+          reference,
+          contractEvent: "task.trigger"
+        })
+      }
+    };
+  }
+  buildResultUpdate(result, reference) {
+    const status = this.mapExecutionResultStatus(result);
+    const taskId = result.task_id;
+    const attemptId = result.attempt_id;
+    const contractEvent = status === "completed" ? "task.completed" : status === "failed" ? "task.failed" : "task.started";
+    const rawOutput = status === "failed" ? {
+      error: result.error || {
+        code: "runtime_error",
+        message: "Unknown runtime error",
+        retryable: true
+      }
+    } : {
+      ...result.output || {},
+      task_id: taskId,
+      attempt_id: attemptId
+    };
+    return {
+      sessionId: reference.sessionId,
+      update: {
+        type: "tool_call_update",
+        toolCallId: reference.toolCallId,
+        status,
+        content: [
+          {
+            type: "text",
+            text: status === "in_progress" ? "Task queued" : status === "completed" ? "Task completed" : "Task failed"
+          }
+        ],
+        rawOutput,
+        _meta: buildRealtimeXMeta({
+          reference,
+          taskId,
+          attemptId,
+          contractEvent
+        })
+      }
+    };
+  }
+  buildLifecycleUpdate(event, reference) {
+    const status = this.mapContractEventStatus(event.event_type);
+    if (!status) return null;
+    const payload = event.payload || {};
+    const progressText = this.resolveEventText(event.event_type, payload);
+    const cancelled = event.event_type === "task.canceled";
+    return {
+      sessionId: reference.sessionId,
+      update: {
+        type: "tool_call_update",
+        toolCallId: reference.toolCallId,
+        status,
+        content: progressText ? [
+          {
+            type: "text",
+            text: progressText
+          }
+        ] : void 0,
+        rawOutput: payload,
+        _meta: buildRealtimeXMeta({
+          reference,
+          taskId: event.task_id,
+          attemptId: event.attempt_id,
+          eventId: event.event_id,
+          contractEvent: event.event_type,
+          cancelled
+        })
+      }
+    };
+  }
+  buildNotifyFailureUpdate(reference, error) {
+    return {
+      sessionId: reference.sessionId,
+      update: {
+        type: "tool_call_update",
+        toolCallId: reference.toolCallId,
+        status: "failed",
+        content: [
+          {
+            type: "text",
+            text: `Adapter notify failed: ${getErrorMessage(error)}`
+          }
+        ],
+        rawOutput: {
+          error: {
+            code: "acp_notify_failed",
+            message: getErrorMessage(error)
+          }
+        },
+        _meta: buildRealtimeXMeta({
+          reference,
+          contractEvent: "adapter.notify_failed"
+        })
+      }
+    };
+  }
+  mapContractEventStatus(eventType) {
+    switch (eventType) {
+      case "task.claimed":
+      case "task.started":
+      case "task.progress":
+        return "in_progress";
+      case "task.completed":
+        return "completed";
+      case "task.failed":
+      case "task.canceled":
+        return "failed";
+      default:
+        return null;
+    }
+  }
+  mapExecutionResultStatus(result) {
+    switch (result.status) {
+      case "completed":
+        return "completed";
+      case "failed":
+        return "failed";
+      case "queued":
+        return "in_progress";
+      default:
+        return "failed";
+    }
+  }
+  resolveEventText(eventType, payload) {
+    const payloadMessage = typeof payload.message === "string" ? payload.message : typeof payload.error === "string" ? payload.error : void 0;
+    if (payloadMessage) return payloadMessage;
+    switch (eventType) {
+      case "task.claimed":
+        return "Task claimed";
+      case "task.started":
+        return "Task started";
+      case "task.progress":
+        return "Task in progress";
+      case "task.completed":
+        return "Task completed";
+      case "task.failed":
+        return "Task failed";
+      case "task.canceled":
+        return "Task canceled";
+      default:
+        return void 0;
+    }
+  }
+};
+
+// src/acp/ACPPermissionBridge.ts
+function isRecord6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizePermissionOptions(invocation, buildPermissionOptions) {
+  const built = buildPermissionOptions ? buildPermissionOptions(invocation) : void 0;
+  if (built && built.length > 0) return built;
+  return [
+    {
+      id: "allow_once",
+      label: "Allow once",
+      kind: "allow_once"
+    },
+    {
+      id: "deny_once",
+      label: "Deny",
+      kind: "deny_once"
+    }
+  ];
+}
+function parseDecision(response) {
+  if (typeof response === "boolean") return response;
+  if (!isRecord6(response)) return false;
+  if (typeof response.allow === "boolean") return response.allow;
+  const decision = typeof response.decision === "string" && response.decision || typeof response.outcome === "string" && response.outcome || typeof response.selected === "string" && response.selected || "";
+  const normalized = decision.trim().toLowerCase();
+  if (!normalized) return false;
+  return normalized === "allow" || normalized === "allow_once" || normalized === "allow_always" || normalized === "approved" || normalized === "granted";
+}
+var ACPPermissionBridge = class {
+  constructor(options) {
+    this.notifier = options.notifier;
+    this.enabled = options.enabled;
+    this.buildPermissionOptions = options.buildPermissionOptions;
+  }
+  async requestToolPermission(invocation, context) {
+    if (!this.enabled) return true;
+    if (!this.notifier.request) {
+      return false;
+    }
+    const options = normalizePermissionOptions(invocation, this.buildPermissionOptions);
+    try {
+      const response = await this.notifier.request("session/request_permission", {
+        sessionId: context.sessionId,
+        title: invocation.title || invocation.toolName,
+        description: `Allow tool ${invocation.toolName} to run?`,
+        options,
+        metadata: {
+          tool_call_id: invocation.toolCallId,
+          tool_name: invocation.toolName,
+          app_id: context.appId
+        }
+      });
+      return parseDecision(response);
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/acp/ACPTelemetry.ts
+var ACPTelemetry = class {
+  constructor(sink) {
+    this.sink = sink;
+  }
+  emit(event) {
+    if (!this.sink) return;
+    try {
+      const output = this.sink.emit(event);
+      if (output && typeof output.then === "function") {
+        void output.catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
+};
+
+// src/acp/ACPContractAdapter.ts
+function isRecord7(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function resolveTaskId(payload) {
+  return getString(payload.task_id) || getString(payload.task_uuid);
+}
+function resolveToolCallId2(payload) {
+  const direct = getString(payload.tool_call_id);
+  if (direct) return direct;
+  if (isRecord7(payload.payload)) {
+    const nestedPayload = getString(payload.payload.tool_call_id);
+    if (nestedPayload) return nestedPayload;
+  }
+  if (isRecord7(payload.data)) {
+    const nestedData = getString(payload.data.tool_call_id);
+    if (nestedData) return nestedData;
+  }
+  return void 0;
+}
+function isTerminalStatus(status) {
+  return status === "completed" || status === "failed";
+}
+var ACPContractAdapter = class {
+  constructor(options) {
+    this.taskReferences = /* @__PURE__ */ new Map();
+    this.toolCallReferences = /* @__PURE__ */ new Map();
+    this.runtime = options.runtime;
+    this.notifier = options.notifier;
+    this.mapper = new ACPEventMapper();
+    this.permissionBridge = new ACPPermissionBridge({
+      notifier: options.notifier,
+      enabled: options.requestPermission === true,
+      buildPermissionOptions: options.buildPermissionOptions
+    });
+    this.telemetry = new ACPTelemetry(options.telemetry);
+    this.runtimeUnsubscribe = this.runtime.onExecutionEvent((event) => {
+      void this.handleRuntimeEvent(event);
+    });
+  }
+  dispose() {
+    this.runtimeUnsubscribe();
+    this.taskReferences.clear();
+    this.toolCallReferences.clear();
+  }
+  async executeTool(invocation, context) {
+    const reference = this.mapper.createReference(invocation, context);
+    this.rememberReference(reference);
+    await this.notify(this.mapper.buildPendingUpdate(invocation, reference));
+    const permissionGranted = await this.permissionBridge.requestToolPermission(
+      invocation,
+      context
+    );
+    this.telemetry.emit({
+      phase: "permission",
+      result: permissionGranted ? "ok" : "failed",
+      sessionId: context.sessionId,
+      toolCallId: invocation.toolCallId,
+      toolName: invocation.toolName
+    });
+    if (!permissionGranted) {
+      const result2 = {
+        status: "failed",
+        tool_call_id: invocation.toolCallId,
+        error: {
+          code: "permission_denied",
+          message: `Permission denied for ${invocation.toolName}`,
+          retryable: false
+        }
+      };
+      await this.notify(this.mapper.buildResultUpdate(result2, reference));
+      this.cleanupReference(reference, result2);
+      return result2;
+    }
+    const result = await this.runtime.executeToolCall(
+      {
+        tool_call_id: invocation.toolCallId,
+        tool_name: invocation.toolName,
+        args: invocation.args
+      },
+      {
+        appId: context.appId,
+        userId: context.userId,
+        workspaceId: context.workspaceId,
+        provider: context.provider,
+        namespace: context.namespace
+      }
+    );
+    const normalizedResult = {
+      ...result,
+      tool_call_id: result.tool_call_id || invocation.toolCallId
+    };
+    if (normalizedResult.task_id) {
+      this.taskReferences.set(normalizedResult.task_id, reference);
+    }
+    await this.notify(this.mapper.buildResultUpdate(normalizedResult, reference));
+    this.telemetry.emit({
+      phase: "execute",
+      result: normalizedResult.status === "failed" ? "failed" : "ok",
+      sessionId: reference.sessionId,
+      toolCallId: reference.toolCallId,
+      toolName: invocation.toolName,
+      taskId: normalizedResult.task_id,
+      attemptId: normalizedResult.attempt_id,
+      status: normalizedResult.status === "queued" ? "in_progress" : normalizedResult.status === "completed" ? "completed" : normalizedResult.status === "failed" ? "failed" : void 0,
+      error: normalizedResult.error?.message
+    });
+    this.cleanupReference(reference, normalizedResult);
+    return normalizedResult;
+  }
+  ingestContractCallback(payload, context) {
+    const initialTaskId = resolveTaskId(payload);
+    const initialToolCallId = resolveToolCallId2(payload);
+    if (initialTaskId) {
+      const existingByTask = this.taskReferences.get(initialTaskId);
+      const existingByCall = initialToolCallId ? this.toolCallReferences.get(initialToolCallId) : void 0;
+      const reference = existingByTask || existingByCall || {
+        sessionId: context.sessionId,
+        toolCallId: initialToolCallId || initialTaskId,
+        appId: "unknown",
+        userId: "unknown",
+        title: initialToolCallId || initialTaskId,
+        kind: "other"
+      };
+      this.taskReferences.set(initialTaskId, reference);
+      this.toolCallReferences.set(reference.toolCallId, reference);
+    }
+    const event = this.runtime.ingestExecutionEvent(payload);
+    this.telemetry.emit({
+      phase: "ingest",
+      result: event ? "ok" : "skipped",
+      sessionId: context.sessionId,
+      toolCallId: event?.tool_call_id,
+      taskId: event?.task_id,
+      attemptId: event?.attempt_id,
+      eventId: event?.event_id,
+      eventType: event?.event_type
+    });
+    return event;
+  }
+  async handleRuntimeEvent(event) {
+    const reference = this.resolveReferenceForEvent(event);
+    if (!reference) {
+      this.telemetry.emit({
+        phase: "runtime_event",
+        result: "skipped",
+        toolCallId: event.tool_call_id,
+        taskId: event.task_id,
+        attemptId: event.attempt_id,
+        eventId: event.event_id,
+        eventType: event.event_type
+      });
+      return;
+    }
+    this.taskReferences.set(event.task_id, reference);
+    const update = this.mapper.buildLifecycleUpdate(event, reference);
+    if (!update) {
+      this.telemetry.emit({
+        phase: "runtime_event",
+        result: "skipped",
+        sessionId: reference.sessionId,
+        toolCallId: reference.toolCallId,
+        taskId: event.task_id,
+        attemptId: event.attempt_id,
+        eventId: event.event_id,
+        eventType: event.event_type
+      });
+      return;
+    }
+    await this.notify(update);
+    this.telemetry.emit({
+      phase: "runtime_event",
+      result: "ok",
+      sessionId: reference.sessionId,
+      toolCallId: reference.toolCallId,
+      taskId: event.task_id,
+      attemptId: event.attempt_id,
+      eventId: event.event_id,
+      eventType: event.event_type,
+      status: update.update.status
+    });
+    if (isTerminalStatus(update.update.status)) {
+      this.taskReferences.delete(event.task_id);
+      this.toolCallReferences.delete(reference.toolCallId);
+    }
+  }
+  resolveReferenceForEvent(event) {
+    const byTask = this.taskReferences.get(event.task_id);
+    if (byTask) return byTask;
+    const byToolCall = this.toolCallReferences.get(event.tool_call_id);
+    if (byToolCall) return byToolCall;
+    return void 0;
+  }
+  rememberReference(reference) {
+    this.toolCallReferences.set(reference.toolCallId, reference);
+  }
+  cleanupReference(reference, result) {
+    const status = result.status === "queued" ? "in_progress" : result.status === "completed" ? "completed" : result.status === "failed" ? "failed" : "failed";
+    if (!isTerminalStatus(status)) return;
+    this.toolCallReferences.delete(reference.toolCallId);
+    if (result.task_id) {
+      this.taskReferences.delete(result.task_id);
+    }
+  }
+  async notify(update) {
+    try {
+      await this.notifier.notify("session/update", update);
+      this.telemetry.emit({
+        phase: "notify",
+        result: "ok",
+        sessionId: update.sessionId,
+        toolCallId: update.update.toolCallId,
+        status: update.update.status,
+        metadata: {
+          type: update.update.type
+        }
+      });
+    } catch (error) {
+      const reference = this.toolCallReferences.get(update.update.toolCallId);
+      this.telemetry.emit({
+        phase: "notify",
+        result: "failed",
+        sessionId: update.sessionId,
+        toolCallId: update.update.toolCallId,
+        status: update.update.status,
+        error: error instanceof Error ? error.message : "Unknown notify error"
+      });
+      if (!reference) return;
+      const failureUpdate = this.mapper.buildNotifyFailureUpdate(reference, error);
+      try {
+        await this.notifier.notify("session/update", failureUpdate);
+      } catch {
+      }
+    }
+  }
+};
+
 // src/index.ts
 var _RealtimeXSDK = class _RealtimeXSDK {
   constructor(config = {}) {
@@ -1429,12 +3208,23 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     this.webhook = new WebhookModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
     this.api = new ApiModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.task = new TaskModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
+    if (config.contract) {
+      this.task.configureContract(config.contract);
+    }
     this.port = new PortModule(config.defaultPort);
     this.llm = new LLMModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.tts = new TTSModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.stt = new STTModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
     this.agent = new AgentModule(this.httpClient);
     this.mcp = new MCPModule(this.realtimexUrl, this.appId, this.appName, this.apiKey);
+    this.contract = new ContractModule(this.realtimexUrl, this.appName, this.appId, this.apiKey);
+    this.contractRuntime = new ContractRuntime({
+      baseUrl: this.realtimexUrl,
+      appId: this.appId || void 0,
+      appName: this.appName,
+      apiKey: this.apiKey,
+      permissions: this.permissions
+    });
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);
@@ -1535,20 +3325,59 @@ var _RealtimeXSDK = class _RealtimeXSDK {
 _RealtimeXSDK.DEFAULT_REALTIMEX_URL = "http://localhost:3001";
 var RealtimeXSDK = _RealtimeXSDK;
 export {
+  ACPContractAdapter,
+  ACPEventMapper,
+  ACPPermissionBridge,
+  ACPTelemetry,
   ActivitiesModule,
   AgentModule,
   ApiModule,
+  CONTRACT_ATTEMPT_PREFIX,
+  CONTRACT_EVENT_ID_HEADER,
+  CONTRACT_SIGNATURE_ALGORITHM,
+  CONTRACT_SIGNATURE_HEADER,
+  ClaudeToolAdapter,
+  CodexToolAdapter,
+  ContractCache,
+  ContractClient,
+  ContractError,
+  ContractHttpClient,
+  ContractModule,
+  ContractRuntime,
+  ContractValidationError,
+  GeminiToolAdapter,
   LLMModule,
   LLMPermissionError,
   LLMProviderError,
+  LOCAL_APP_CONTRACT_VERSION,
   MCPModule,
   PermissionDeniedError,
   PermissionRequiredError,
   PortModule,
   RealtimeXSDK,
+  RetryPolicy,
+  RuntimeTransportError,
   STTModule,
+  ScopeDeniedError,
+  ScopeGuard,
+  StaticAuthProvider,
   TTSModule,
   TaskModule,
+  ToolNotFoundError,
+  ToolProjector,
+  ToolValidationError,
   VectorStore,
-  WebhookModule
+  WebhookModule,
+  buildContractIdempotencyKey,
+  buildContractSignatureMessage,
+  canonicalEventToLegacyAction,
+  createContractEventId,
+  hashContractPayload,
+  normalizeAttemptId,
+  normalizeContractEvent,
+  normalizeLocalAppContractV1,
+  normalizeSchema,
+  parseAttemptRunId,
+  signContractEvent,
+  toStableToolName
 };