@pliuz/sdk 0.1.0

package/dist/adapters/ai.cjs

@@ -0,0 +1,578 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/gated.ts
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/errors.ts
+var PliuzError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PliuzError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PliuzNetworkError = class extends PliuzError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "PliuzNetworkError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  cause;
+};
+var PliuzTimeoutError = class extends PliuzError {
+  constructor(message) {
+    super(message);
+    this.name = "PliuzTimeoutError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PliuzApiError = class extends PliuzError {
+  constructor(statusCode, errorCode, message, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+    this.details = details;
+    this.name = "PliuzApiError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  statusCode;
+  errorCode;
+  details;
+};
+var PliuzValidationError = class extends PliuzApiError {
+  constructor(statusCode, errorCode, message, details) {
+    super(statusCode, errorCode, message, details);
+    this.name = "PliuzValidationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PliuzAuthError = class extends PliuzApiError {
+  constructor(statusCode, errorCode, message, details) {
+    super(statusCode, errorCode, message, details);
+    this.name = "PliuzAuthError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PliuzForbiddenError = class extends PliuzApiError {
+  constructor(statusCode, errorCode, message, details) {
+    super(statusCode, errorCode, message, details);
+    this.name = "PliuzForbiddenError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PliuzNotFoundError = class extends PliuzApiError {
+  constructor(statusCode, errorCode, message, details) {
+    super(statusCode, errorCode, message, details);
+    this.name = "PliuzNotFoundError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PliuzConflictError = class extends PliuzApiError {
+  constructor(statusCode, errorCode, message, details) {
+    super(statusCode, errorCode, message, details);
+    this.name = "PliuzConflictError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PliuzPolicyError = class extends PliuzApiError {
+  constructor(statusCode, errorCode, message, details) {
+    super(statusCode, errorCode, message, details);
+    this.name = "PliuzPolicyError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PliuzRateLimitError = class extends PliuzApiError {
+  constructor(statusCode, errorCode, message, details) {
+    super(statusCode, errorCode, message, details);
+    this.name = "PliuzRateLimitError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PliuzServerError = class extends PliuzApiError {
+  constructor(statusCode, errorCode, message, details) {
+    super(statusCode, errorCode, message, details);
+    this.name = "PliuzServerError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var PliuzRejectedError = class extends PliuzError {
+  constructor(approvalId, reason) {
+    const msg = reason ? `approval ${approvalId} was rejected: ${reason}` : `approval ${approvalId} was rejected`;
+    super(msg);
+    this.approvalId = approvalId;
+    this.reason = reason;
+    this.name = "PliuzRejectedError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  approvalId;
+  reason;
+};
+var PliuzApprovalExpiredError = class extends PliuzError {
+  constructor(approvalId) {
+    super(`approval ${approvalId} expired before a human decided`);
+    this.approvalId = approvalId;
+    this.name = "PliuzApprovalExpiredError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  approvalId;
+};
+var PliuzApprovalTimeoutError = class extends PliuzError {
+  constructor(approvalId, timeoutMs) {
+    super(
+      `approval ${approvalId} did not resolve within ${timeoutMs}ms (SDK polling timeout \u2014 approval may still be pending server-side)`
+    );
+    this.approvalId = approvalId;
+    this.timeoutMs = timeoutMs;
+    this.name = "PliuzApprovalTimeoutError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  approvalId;
+  timeoutMs;
+};
+var STATUS_TO_ERROR = {
+  400: PliuzValidationError,
+  401: PliuzAuthError,
+  403: PliuzForbiddenError,
+  404: PliuzNotFoundError,
+  409: PliuzConflictError,
+  422: PliuzPolicyError,
+  429: PliuzRateLimitError
+};
+function errorForStatus(statusCode, errorCode, message, details) {
+  if (statusCode >= 500 && statusCode < 600) {
+    return new PliuzServerError(statusCode, errorCode, message, details);
+  }
+  const Cls = STATUS_TO_ERROR[statusCode] ?? PliuzApiError;
+  return new Cls(statusCode, errorCode, message, details);
+}
+
+// src/_http.ts
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]);
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+function userAgent() {
+  return `pliuz-typescript/${VERSION}`;
+}
+function buildHeaders(apiKey) {
+  return {
+    "X-Pliuz-Api-Key": apiKey,
+    "User-Agent": userAgent(),
+    Accept: "application/json",
+    "Content-Type": "application/json"
+  };
+}
+function backoffMs(attempt, baseMs = 500, capMs = 8e3) {
+  const expo = Math.min(capMs, baseMs * 2 ** (attempt - 1));
+  return Math.floor(Math.random() * expo);
+}
+function isRetryable(method, status, retryOnPost) {
+  if (!RETRYABLE_STATUS.has(status)) return false;
+  if (IDEMPOTENT_METHODS.has(method)) return true;
+  if (method === "POST" && retryOnPost) return true;
+  return false;
+}
+async function parseError(response) {
+  let body = {};
+  try {
+    body = await response.json();
+  } catch {
+  }
+  const errorCode = body.error ?? "unknown_error";
+  const message = body.message ?? response.statusText ?? "Pliuz API error";
+  const details = body.details;
+  return errorForStatus(response.status, errorCode, message, details);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function request(opts) {
+  const { method, url, apiKey, body, timeoutMs, maxRetries, retryOnPost = false, fetchImpl } = opts;
+  const headers = buildHeaders(apiKey);
+  let lastError = null;
+  for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        method,
+        headers,
+        body: body == null ? void 0 : JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (e) {
+      clearTimeout(timer);
+      const isTimeout = e instanceof Error && (e.name === "AbortError" || /abort|timeout/i.test(e.message));
+      lastError = isTimeout ? new PliuzTimeoutError(`Pliuz request timed out after ${timeoutMs}ms`) : new PliuzNetworkError(
+        `Pliuz network error: ${e instanceof Error ? e.message : String(e)}`,
+        e
+      );
+      if (attempt > maxRetries) throw lastError;
+      await sleep(backoffMs(attempt));
+      continue;
+    }
+    clearTimeout(timer);
+    if (response.status >= 200 && response.status < 300) {
+      try {
+        return await response.json();
+      } catch (e) {
+        throw new PliuzApiError(
+          response.status,
+          "invalid_json",
+          `Pliuz returned non-JSON 2xx body: ${e instanceof Error ? e.message : String(e)}`
+        );
+      }
+    }
+    if (isRetryable(method, response.status, retryOnPost)) {
+      if (attempt > maxRetries) {
+        throw await parseError(response);
+      }
+      await sleep(backoffMs(attempt));
+      continue;
+    }
+    throw await parseError(response);
+  }
+  throw lastError ?? new PliuzApiError(0, "exhausted", "retry loop exhausted unexpectedly");
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://pliuz-dev.vercel.app";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var ENV_API_KEY = "PLIUZ_API_KEY";
+var ENV_BASE_URL = "PLIUZ_BASE_URL";
+function resolveApiKey(explicit) {
+  if (explicit) return explicit;
+  if (typeof process !== "undefined" && process.env?.[ENV_API_KEY]) {
+    return process.env[ENV_API_KEY];
+  }
+  throw new Error(`Pliuz API key not provided. Pass apiKey or set $${ENV_API_KEY}.`);
+}
+function resolveBaseUrl(explicit) {
+  if (explicit) return explicit.replace(/\/+$/, "");
+  if (typeof process !== "undefined" && process.env?.[ENV_BASE_URL]) {
+    return process.env[ENV_BASE_URL].replace(/\/+$/, "");
+  }
+  return DEFAULT_BASE_URL;
+}
+function approvalUrl(baseUrl, approvalId, suffix) {
+  let path = "/api/v1/approvals";
+  if (approvalId) path += `/${encodeURIComponent(approvalId)}`;
+  if (suffix) path += `/${suffix}`;
+  return baseUrl + path;
+}
+var PliuzClient = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  maxRetries;
+  fetchImpl;
+  constructor(options = {}) {
+    this.apiKey = resolveApiKey(options.apiKey);
+    this.baseUrl = resolveBaseUrl(options.baseUrl);
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new Error(
+        "No fetch implementation available. Pliuz requires Node \u226518 or a polyfill."
+      );
+    }
+    this.fetchImpl = fetchImpl;
+  }
+  /**
+   * Create (or idempotently replay) an approval request.
+   *
+   * With `idempotency_key`, the call retries on network failure without
+   * risk of duplicates (backend dedupes within 24h).
+   */
+  async createApproval(input) {
+    const body = {
+      tool_name: input.tool_name,
+      tool_args: input.tool_args,
+      context_messages: input.context_messages ?? null,
+      originator: input.originator ?? { type: "system" },
+      session_id: input.session_id ?? null,
+      client_metadata: input.client_metadata ?? null,
+      idempotency_key: input.idempotency_key ?? null
+    };
+    return request({
+      method: "POST",
+      url: approvalUrl(this.baseUrl),
+      apiKey: this.apiKey,
+      body,
+      timeoutMs: this.timeoutMs,
+      maxRetries: this.maxRetries,
+      retryOnPost: Boolean(input.idempotency_key),
+      fetchImpl: this.fetchImpl
+    });
+  }
+  /**
+   * Fetch the current state of an approval request.
+   * Used by polling in `gated()` to detect status transitions.
+   */
+  async getApproval(approvalId) {
+    return request({
+      method: "GET",
+      url: approvalUrl(this.baseUrl, approvalId),
+      apiKey: this.apiKey,
+      timeoutMs: this.timeoutMs,
+      maxRetries: this.maxRetries,
+      fetchImpl: this.fetchImpl
+    });
+  }
+  /**
+   * Close the audit loop by reporting the outcome of the gated action.
+   *
+   * Single-shot: a second call returns 409 (PliuzConflictError).
+   * Only the originating agent can report — others get 403 (PliuzForbiddenError).
+   */
+  async reportExecution(approvalId, input) {
+    const body = {
+      status: input.status,
+      error: input.error ?? null,
+      latency_ms: input.latency_ms ?? null,
+      target_response_excerpt: input.target_response_excerpt ?? null
+    };
+    return request({
+      method: "POST",
+      url: approvalUrl(this.baseUrl, approvalId, "execution"),
+      apiKey: this.apiKey,
+      body,
+      timeoutMs: this.timeoutMs,
+      maxRetries: this.maxRetries,
+      retryOnPost: false,
+      fetchImpl: this.fetchImpl
+    });
+  }
+};
+
+// src/redaction.ts
+var REDACTED_PLACEHOLDER = "<redacted>";
+function applyRedaction(payload, paths) {
+  if (!paths || paths.length === 0) {
+    return deepClone(payload);
+  }
+  const result = deepClone(payload);
+  for (const path of paths) {
+    redactPath(result, parsePath(path));
+  }
+  return result;
+}
+function parsePath(path) {
+  if (!path) {
+    throw new Error("redaction path cannot be empty");
+  }
+  const segments = [];
+  for (const raw of path.split(".")) {
+    if (raw.endsWith("[*]")) {
+      const key = raw.slice(0, -3);
+      if (!key) {
+        throw new Error(`redaction path segment before [*] cannot be empty: ${path}`);
+      }
+      segments.push({ key, isArrayWildcard: true });
+    } else if (raw.includes("[") || raw.includes("]")) {
+      throw new Error(`unsupported redaction syntax in '${path}' \u2014 only [*] is allowed`);
+    } else {
+      if (!raw) {
+        throw new Error(`redaction path has empty segment: ${path}`);
+      }
+      segments.push({ key: raw, isArrayWildcard: false });
+    }
+  }
+  return segments;
+}
+function redactPath(node, segments) {
+  if (segments.length === 0) return;
+  if (!isPlainObject(node)) return;
+  const [head, ...rest] = segments;
+  if (!head) return;
+  const { key, isArrayWildcard } = head;
+  if (!(key in node)) return;
+  if (isArrayWildcard) {
+    const target = node[key];
+    if (!Array.isArray(target)) return;
+    if (rest.length === 0) {
+      node[key] = target.map(() => REDACTED_PLACEHOLDER);
+      return;
+    }
+    for (const item of target) {
+      redactPath(item, rest);
+    }
+  } else {
+    if (rest.length === 0) {
+      node[key] = REDACTED_PLACEHOLDER;
+    } else {
+      redactPath(node[key], rest);
+    }
+  }
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function deepClone(v) {
+  if (typeof structuredClone === "function") {
+    return structuredClone(v);
+  }
+  return JSON.parse(JSON.stringify(v));
+}
+
+// src/gated.ts
+var DEFAULT_GATED_TIMEOUT_MS = 3e5;
+var DEFAULT_GATED_POLL_INTERVAL_MS = 2e3;
+var TERMINAL_OK = /* @__PURE__ */ new Set(["approved"]);
+var TERMINAL_REJECT = /* @__PURE__ */ new Set(["rejected"]);
+var TERMINAL_EXPIRED = /* @__PURE__ */ new Set(["expired"]);
+function gated(options, fn) {
+  const toolName = options.toolName ?? (fn.name || "anonymous");
+  const toolArgsMapper = options.toolArgs ?? ((...args) => ({ args }));
+  const timeoutMs = options.timeoutMs ?? DEFAULT_GATED_TIMEOUT_MS;
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_GATED_POLL_INTERVAL_MS;
+  const redactPaths = options.redact;
+  return async (...args) => {
+    const activeClient = options.client ?? new PliuzClient();
+    const rawArgs = toolArgsMapper(...args);
+    const sendArgs = redactPaths && redactPaths.length > 0 ? applyRedaction(rawArgs, redactPaths) : rawArgs;
+    const idempotencyKey = idempotencyKeyFor(toolName, sendArgs, options.sessionId);
+    const metadata = {};
+    if (options.policy) metadata.policy = options.policy;
+    const response = await activeClient.createApproval({
+      tool_name: toolName,
+      tool_args: sendArgs,
+      context_messages: options.contextMessages ?? null,
+      originator: options.originator,
+      session_id: options.sessionId ?? null,
+      client_metadata: Object.keys(metadata).length > 0 ? metadata : null,
+      idempotency_key: idempotencyKey
+    });
+    const approvalId = response.id;
+    if (TERMINAL_REJECT.has(response.status)) {
+      throw new PliuzRejectedError(approvalId, response.message ?? null);
+    }
+    if (TERMINAL_EXPIRED.has(response.status)) {
+      throw new PliuzApprovalExpiredError(approvalId);
+    }
+    if (!TERMINAL_OK.has(response.status)) {
+      const deadline = Date.now() + timeoutMs;
+      while (true) {
+        if (Date.now() >= deadline) {
+          throw new PliuzApprovalTimeoutError(approvalId, timeoutMs);
+        }
+        await sleep2(pollIntervalMs);
+        const approval = await activeClient.getApproval(approvalId);
+        if (terminalOrThrow(approval)) break;
+      }
+    }
+    const started = Date.now();
+    try {
+      const result = await fn(...args);
+      const latencyMs = Date.now() - started;
+      void safeReport(activeClient, approvalId, "success", null, latencyMs, result);
+      return result;
+    } catch (e) {
+      const latencyMs = Date.now() - started;
+      const errMsg = e instanceof Error ? e.message : String(e);
+      void safeReport(activeClient, approvalId, "error", errMsg.slice(0, 2e3), latencyMs, null);
+      throw e;
+    }
+  };
+}
+function idempotencyKeyFor(toolName, toolArgs, sessionId) {
+  JSON.stringify(
+    { tool: toolName, args: toolArgs, session: sessionId ?? null },
+    Object.keys({ tool: 0, args: 0, session: 0 }).sort()
+  );
+  const canonical = canonicalJSON({ tool: toolName, args: toolArgs, session: sessionId ?? null });
+  return "g_" + crypto.createHash("sha256").update(canonical).digest("hex").slice(0, 30);
+}
+function canonicalJSON(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalJSON).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalJSON(obj[k])).join(",") + "}";
+}
+function terminalOrThrow(approval) {
+  if (TERMINAL_OK.has(approval.status)) return true;
+  if (TERMINAL_REJECT.has(approval.status)) {
+    throw new PliuzRejectedError(approval.id, approval.decision_reason);
+  }
+  if (TERMINAL_EXPIRED.has(approval.status)) {
+    throw new PliuzApprovalExpiredError(approval.id);
+  }
+  return false;
+}
+async function safeReport(client, approvalId, status, errorMessage, latencyMs, result) {
+  let excerpt = null;
+  if (result != null) {
+    try {
+      excerpt = JSON.stringify(result).slice(0, 2e3);
+    } catch {
+      excerpt = String(result).slice(0, 2e3);
+    }
+  }
+  try {
+    await client.reportExecution(approvalId, {
+      status,
+      error: errorMessage,
+      latency_ms: latencyMs,
+      target_response_excerpt: excerpt
+    });
+  } catch {
+  }
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/adapters/ai.ts
+var ADAPTER_NAME = "vercel-ai";
+function gatedTool(options, tool) {
+  if (typeof tool.execute !== "function") {
+    return tool;
+  }
+  const toolName = options.toolName ?? (typeof tool.description === "string" ? tool.description.slice(0, 64) : "ai_tool");
+  const originalExecute = tool.execute;
+  let pendingOptions = void 0;
+  const gatedExecute1Arg = gated(
+    {
+      policy: options.policy,
+      redact: options.redact,
+      timeoutMs: options.timeoutMs,
+      pollIntervalMs: options.pollIntervalMs,
+      client: options.client,
+      contextMessages: options.contextMessages,
+      sessionId: options.sessionId,
+      originator: options.originator,
+      toolName,
+      // Surface the Vercel-AI input dict directly as Pliuz tool_args
+      // instead of wrapping in `{ args: [input] }` for cleaner audit logs.
+      toolArgs: (input) => isPlainObject2(input) ? input : { input }
+    },
+    async (input) => originalExecute(input, pendingOptions)
+  );
+  const wrappedExecute = async (input, opts) => {
+    pendingOptions = opts;
+    return gatedExecute1Arg(input);
+  };
+  return {
+    ...tool,
+    execute: wrappedExecute
+  };
+}
+function isPlainObject2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+exports.ADAPTER_NAME = ADAPTER_NAME;
+exports.gatedTool = gatedTool;
+//# sourceMappingURL=ai.cjs.map
+//# sourceMappingURL=ai.cjs.map