@covia/covia-sdk 1.6.0 → 1.7.0

package/dist/index.js

@@ -8,18 +8,18 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // src/types.ts
-var RunStatus = /* @__PURE__ */ ((RunStatus2) => {
-  RunStatus2["COMPLETE"] = "COMPLETE";
-  RunStatus2["FAILED"] = "FAILED";
-  RunStatus2["PENDING"] = "PENDING";
-  RunStatus2["STARTED"] = "STARTED";
-  RunStatus2["CANCELLED"] = "CANCELLED";
-  RunStatus2["TIMEOUT"] = "TIMEOUT";
-  RunStatus2["REJECTED"] = "REJECTED";
-  RunStatus2["INPUT_REQUIRED"] = "INPUT_REQUIRED";
-  RunStatus2["AUTH_REQUIRED"] = "AUTH_REQUIRED";
-  RunStatus2["PAUSED"] = "PAUSED";
-  return RunStatus2;
+var RunStatus = /* @__PURE__ */ ((RunStatus3) => {
+  RunStatus3["COMPLETE"] = "COMPLETE";
+  RunStatus3["FAILED"] = "FAILED";
+  RunStatus3["PENDING"] = "PENDING";
+  RunStatus3["STARTED"] = "STARTED";
+  RunStatus3["CANCELLED"] = "CANCELLED";
+  RunStatus3["TIMEOUT"] = "TIMEOUT";
+  RunStatus3["REJECTED"] = "REJECTED";
+  RunStatus3["INPUT_REQUIRED"] = "INPUT_REQUIRED";
+  RunStatus3["AUTH_REQUIRED"] = "AUTH_REQUIRED";
+  RunStatus3["PAUSED"] = "PAUSED";
+  return RunStatus3;
 })(RunStatus || {});
 var JobStatus = RunStatus;
 var AgentStatus = /* @__PURE__ */ ((AgentStatus2) => {
@@ -72,6 +72,13 @@ var JobFailedError = class extends CoviaError {
     this.jobData = jobData;
   }
 };
+var RateLimitError = class extends GridError {
+  constructor(message, retryAfterSeconds, body) {
+    super(429, message, body);
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.name = "RateLimitError";
+  }
+};
 var NotFoundError = class extends GridError {
   constructor(message) {
     super(404, message);
@@ -1309,22 +1316,55 @@ function wrapError(error) {
   }
   return new CoviaError(`Request failed: ${msg}`);
 }
+var RETRY_MAX_ATTEMPTS = 4;
+var RETRY_BASE_MS = 200;
+var RETRY_MAX_DELAY_MS = 1e4;
+var RETRY_BUDGET_MS = 3e4;
+function parseRetryAfterMs(header, nowMs) {
+  if (!header) return 0;
+  const secs = Number(header);
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1e3);
+  const date = Date.parse(header);
+  return Number.isFinite(date) ? Math.max(0, date - nowMs) : 0;
+}
+function retryDelayMs(attempt, retryAfterMs, remainingBudgetMs, random) {
+  if (attempt >= RETRY_MAX_ATTEMPTS) return -1;
+  const backoff = Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_MS * 2 ** (attempt - 1));
+  const delay = Math.max(retryAfterMs, Math.floor(random * backoff));
+  return delay > remainingBudgetMs ? -1 : delay;
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function fetchWithError(url, options) {
   const method = options?.method ?? "GET";
-  logger.debug(`${method} ${url}`);
-  let response;
-  try {
-    response = await fetch(url, options);
-  } catch (error) {
-    const msg = error.message ?? String(error);
-    logger.debug(`Connection failed: ${method} ${url} \u2014 ${msg}`);
-    throw wrapError(error);
-  }
-  logger.debug(`${method} ${url} \u2192 ${response.status}`);
-  if (!response.ok) {
-    await throwHttpError(response);
+  const deadline = Date.now() + RETRY_BUDGET_MS;
+  for (let attempt = 1; ; attempt++) {
+    logger.debug(`${method} ${url}`);
+    let response;
+    try {
+      response = await fetch(url, options);
+    } catch (error) {
+      const msg = error.message ?? String(error);
+      logger.debug(`Connection failed: ${method} ${url} \u2014 ${msg}`);
+      throw wrapError(error);
+    }
+    logger.debug(`${method} ${url} \u2192 ${response.status}`);
+    if (response.status === 429) {
+      const now = Date.now();
+      const retryAfterMs = parseRetryAfterMs(response.headers?.get?.("Retry-After") ?? null, now);
+      const delay = retryDelayMs(attempt, retryAfterMs, deadline - now, Math.random());
+      if (delay < 0) {
+        const { message, body } = await parseErrorBody(response);
+        throw new RateLimitError(message, Math.max(1, Math.ceil(retryAfterMs / 1e3)), body);
+      }
+      logger.debug(`429 from ${url}; retrying in ${delay}ms (attempt ${attempt})`);
+      await sleep(delay);
+      continue;
+    }
+    if (!response.ok) {
+      await throwHttpError(response);
+    }
+    return response.json();
   }
-  return response.json();
 }
 async function fetchStreamWithError(url, options) {
   const method = options?.method ?? "GET";
@@ -1459,10 +1499,96 @@ async function* parseSSEStream(response) {
   }
 }
 
+// src/AdapterManager.ts
+var ADAPTERS_PATH = "v/info/adapters";
+var LIST_LIMIT = 1e3;
+function toAdapterInfo(name, value) {
+  return {
+    name: value?.name ?? name ?? "",
+    description: value?.description,
+    operations: Array.isArray(value?.operations) ? value.operations : []
+  };
+}
+var AdapterManager = class {
+  constructor(venue) {
+    this.venue = venue;
+  }
+  /**
+   * List the adapters registered on the venue, with their descriptions and
+   * invocable operation catalog paths. Registered-but-inactive or zero-op
+   * adapters are included — this is the true registry, not an inference
+   * from the operations catalog.
+   */
+  async list() {
+    const r = await this.venue.workspace.slice(ADAPTERS_PATH, 0, LIST_LIMIT);
+    if (!r.exists || !Array.isArray(r.values)) return [];
+    const out = [];
+    for (const entry of r.values) {
+      if (!entry || typeof entry !== "object") continue;
+      const key = "key" in entry && typeof entry.key === "string" ? entry.key : void 0;
+      const value = "value" in entry ? entry.value : entry;
+      out.push(toAdapterInfo(key, value));
+    }
+    return out;
+  }
+  /**
+   * Get a single adapter's summary by name.
+   * @param name - Adapter name, e.g. "mcp"
+   * @returns {Promise<AdapterInfo | null>} `null` if no adapter with that name is registered
+   */
+  async get(name) {
+    const r = await this.venue.workspace.read(`${ADAPTERS_PATH}/${encodeURIComponent(name)}`);
+    if (!r.exists) return null;
+    return toAdapterInfo(name, r.value);
+  }
+};
+
 // src/AgentManager.ts
+function versionAtLeast(version, major, minor) {
+  const m = version?.match(/^(\d+)\.(\d+)/);
+  if (!m) return true;
+  const [maj, min] = [Number(m[1]), Number(m[2])];
+  return maj > major || maj === major && min >= minor;
+}
 var AgentManager = class {
   constructor(venue) {
     this.venue = venue;
+    // Whether this venue serves GET /api/v1/agents — flipped on the first 404 so
+    // pre-0.4 venues pay the probe once, not one failed GET per read (covia#180).
+    this.agentsGetSupported = true;
+  }
+  _headers() {
+    const headers = { "Content-Type": "application/json" };
+    this.venue.auth.apply(headers, this.venue.venueId);
+    return headers;
+  }
+  /** Whether the venue serves `GET /api/v1/agents`: no if a probe already
+   *  404'd, or if the venue's last known status identifies it as pre-0.4. */
+  supportsAgentsGet() {
+    if (!this.agentsGetSupported) return false;
+    const status = this.venue.lastKnownStatus;
+    if (status && (!status.version || !versionAtLeast(status.version, 0, 4))) {
+      this.agentsGetSupported = false;
+    }
+    return this.agentsGetSupported;
+  }
+  /** A job-free agents GET, falling back to the invoke path on pre-0.4 venues. */
+  async _agentsOr(path, params, fallback) {
+    if (this.supportsAgentsGet()) {
+      try {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(params)) if (v !== void 0) qs.set(k, String(v));
+        const q = qs.toString();
+        return await fetchWithError(
+          `${this.venue.baseUrl}/api/v1/agents${path}${q ? `?${q}` : ""}`,
+          { headers: this._headers() }
+        );
+      } catch (e) {
+        if (!(e instanceof NotFoundError)) throw e;
+        this.agentsGetSupported = false;
+      }
+    }
+    return fallback();
   }
   async create(input) {
     return this.venue.operations.run("v/ops/agent/create", input);
@@ -1495,8 +1621,13 @@ var AgentManager = class {
   async trigger(agentId) {
     return this.venue.operations.run("v/ops/agent/trigger", { agentId });
   }
+  /**
+   * List the caller's agents. **Job-free** on covia ≥ 0.4: goes through
+   * `GET /api/v1/agents` (covia#180) — synchronous, no Job persisted. Older
+   * venues transparently fall back to the invoke path (one probe, remembered).
+   */
   async list(includeTerminated) {
-    return this.venue.operations.run("v/ops/agent/list", { includeTerminated });
+    return this._agentsOr("", { includeTerminated }, () => this.venue.operations.run("v/ops/agent/list", { includeTerminated }));
   }
   async delete(agentId, remove) {
     return this.venue.operations.run("v/ops/agent/delete", { agentId, remove });
@@ -1513,8 +1644,10 @@ var AgentManager = class {
   async cancelTask(agentId, taskId) {
     return this.venue.operations.run("v/ops/agent/cancel-task", { agentId, taskId });
   }
+  /** Agent info. **Job-free** on covia ≥ 0.4 (`GET /api/v1/agents/{id}`,
+   *  covia#180); older venues fall back to the invoke path. */
   async info(agentId) {
-    return this.venue.operations.run("v/ops/agent/info", { agentId });
+    return this._agentsOr(`/${encodeURIComponent(agentId)}`, {}, () => this.venue.operations.run("v/ops/agent/info", { agentId }));
   }
   async fork(input) {
     return this.venue.operations.run("v/ops/agent/fork", input);
@@ -2015,9 +2148,47 @@ var OperationManager = class {
    * @param options - Invoke options (e.g., ucans)
    */
   async run(assetId, input, options) {
+    if (this.venue.privateJobs) {
+      return this._runPrivate(assetId, input, options);
+    }
     const job = await this.invoke(assetId, input, options);
     return await job.result();
   }
+  /**
+   * Private-mode execution (covia #192): a memory-only job whose result is
+   * collected through the invoke `wait` window — a completed private job is
+   * immediately forgotten by the venue, so polling cannot be used. If the
+   * operation outlives the venue's wait cap, polling continues while the job
+   * runs; a job that completes between polls is unobservable and surfaces as
+   * a clear error rather than a confusing 404.
+   */
+  async _runPrivate(assetId, input, options) {
+    const payload = {
+      operation: assetId,
+      input,
+      private: true,
+      wait: true
+    };
+    if (options?.ucans) payload.ucans = options.ucans;
+    const rec = await fetchWithError(`${this.venue.baseUrl}/api/v1/invoke`, {
+      method: "POST",
+      headers: this._buildHeaders(),
+      body: JSON.stringify(payload)
+    });
+    const status = rec.status;
+    if (isJobComplete(status)) return rec.output;
+    if (isJobFinished(status)) {
+      throw new JobFailedError(rec);
+    }
+    try {
+      const job = new Job(rec.id ?? "", this.venue, rec);
+      return await job.result();
+    } catch (e) {
+      throw new CoviaError(
+        `Private job completed while unobserved \u2014 its record is already forgotten, so the result could not be collected. Private jobs that outlive the venue wait window cannot be reliably collected; consider a non-private run for long operations. (${e.message})`
+      );
+    }
+  }
   /**
    * Execute an operation and return a Job for tracking
    * @param assetId - Operation asset ID or named operation
@@ -2025,6 +2196,11 @@ var OperationManager = class {
    * @param options - Invoke options (e.g., ucans)
    */
   async invoke(assetId, input, options) {
+    if (this.venue.privateJobs) {
+      throw new CoviaError(
+        "Private-jobs mode requires run(): a completed private job is immediately forgotten by the venue, so a poll-style Job cannot collect its result."
+      );
+    }
     const payload = {
       operation: assetId,
       input
@@ -2047,7 +2223,7 @@ var OperationManager = class {
 };
 
 // src/WorkspaceManager.ts
-function versionAtLeast(version, major, minor) {
+function versionAtLeast2(version, major, minor) {
   const m = version?.match(/^(\d+)\.(\d+)/);
   if (!m) return true;
   const [maj, min] = [Number(m[1]), Number(m[2])];
@@ -2080,7 +2256,7 @@ var WorkspaceManager = class {
   supportsValues() {
     if (!this.valuesSupported) return false;
     const status = this.venue.lastKnownStatus;
-    if (status && (!status.version || !versionAtLeast(status.version, 0, 3))) {
+    if (status && (!status.version || !versionAtLeast2(status.version, 0, 3))) {
       this.valuesSupported = false;
     }
     return this.valuesSupported;
@@ -2163,6 +2339,16 @@ var UCANManager = class {
   async issue(aud, att, exp) {
     return this.venue.operations.run("v/ops/ucan/issue", { aud, att, exp });
   }
+  /**
+   * Verify a UCAN against the venue's trust policy and get the verdict
+   * explained — validity with a diagnosable reason, chain depth and root
+   * issuer, per-capability root-authority (owner / venue / refused), and,
+   * when `check` is supplied, whether the token would authorise that request
+   * here. The diagnostic counterpart to an enforcement "Access denied".
+   */
+  async verify(token, check) {
+    return this.venue.operations.run("v/ops/ucan/verify", { token, ...check });
+  }
 };
 
 // src/SecretManager.ts
@@ -2299,6 +2485,34 @@ function venueBaseUrlCandidates(venueId) {
   return schemelessVenueCandidates(venueId);
 }
 var Venue = class _Venue {
+  constructor(options = {}) {
+    /** Connection-level private-jobs mode — see {@link setPrivate}. */
+    this.privateJobs = false;
+    this.baseUrl = options.baseUrl || "";
+    this.venueId = options.venueId || "";
+    this.auth = options.auth || new NoAuth();
+    this.lastKnownStatus = options.status;
+    this.metadata = {
+      name: options.name || "default",
+      description: options.description || ""
+    };
+  }
+  /**
+   * Puts this connection in **private-jobs mode**: every subsequent
+   * `operations.run(...)` executes as a memory-only job (covia #192) — never
+   * persisted to the venue's job index, no durable record, gone on venue
+   * restart. Requires `enablePrivateJobs` on the venue.
+   *
+   * Because a completed private job is immediately forgotten, results are
+   * collected through the invoke `wait` window rather than polling — so
+   * private mode works with `run()`; a poll-style `invoke()` throws.
+   */
+  setPrivate(enabled) {
+    this.privateJobs = enabled;
+  }
+  get adapters() {
+    return this._adapters ?? (this._adapters = new AdapterManager(this));
+  }
   get agents() {
     return this._agents ?? (this._agents = new AgentManager(this));
   }
@@ -2320,16 +2534,6 @@ var Venue = class _Venue {
   get secrets() {
     return this._secrets ?? (this._secrets = new SecretManager(this));
   }
-  constructor(options = {}) {
-    this.baseUrl = options.baseUrl || "";
-    this.venueId = options.venueId || "";
-    this.auth = options.auth || new NoAuth();
-    this.lastKnownStatus = options.status;
-    this.metadata = {
-      name: options.name || "default",
-      description: options.description || ""
-    };
-  }
   /**
    * Connect to a venue, validating it with `GET {base}/api/v1/status`. If the
    * venue is auth-gated (status answers 401/403 — public access disabled), the
@@ -2561,12 +2765,45 @@ var Grid = class {
     return connectedVenue;
   }
 };
+
+// src/crypto/ucan.ts
+var encoder2 = new TextEncoder();
+var VENUE_RELAY = "venue/relay";
+function didFor(privateKey) {
+  return `did:key:${encodePublicKey(getPublicKey2(privateKey))}`;
+}
+function createUCANJWT(privateKey, audienceDID, att, lifetimeSeconds, proofs = []) {
+  const multikey = encodePublicKey(getPublicKey2(privateKey));
+  const nowSecs = Math.floor(Date.now() / 1e3);
+  const header = JSON.stringify({ alg: "EdDSA", typ: "JWT", kid: multikey });
+  const claims = {
+    iss: `did:key:${multikey}`,
+    aud: audienceDID,
+    att,
+    exp: nowSecs + lifetimeSeconds
+  };
+  if (proofs.length) claims.prf = proofs;
+  const signingInput = `${base64UrlEncode(encoder2.encode(header))}.${base64UrlEncode(encoder2.encode(JSON.stringify(claims)))}`;
+  const signature = sign(encoder2.encode(signingInput), privateKey);
+  return `${signingInput}.${base64UrlEncode(signature)}`;
+}
+function identityToken(privateKey, venueDID, lifetimeSeconds = 300) {
+  return createUCANJWT(privateKey, venueDID, [], lifetimeSeconds);
+}
+function grant(ownerPrivateKey, audienceDID, withResource, can, lifetimeSeconds) {
+  return createUCANJWT(ownerPrivateKey, audienceDID, [{ with: withResource, can }], lifetimeSeconds);
+}
+function relayDelegation(privateKey, venueDID, lifetimeSeconds, caps = []) {
+  const att = [{ with: didFor(privateKey), can: VENUE_RELAY }, ...caps];
+  return createUCANJWT(privateKey, venueDID, att, lifetimeSeconds);
+}
 /*! Bundled license information:
 
 @noble/ed25519/index.js:
   (*! noble-ed25519 - MIT License (c) 2019 Paul Miller (paulmillr.com) *)
 */
 
+exports.AdapterManager = AdapterManager;
 exports.Agent = Agent;
 exports.AgentManager = AgentManager;
 exports.AgentStatus = AgentStatus;
@@ -2596,14 +2833,18 @@ exports.NoAuth = NoAuth;
 exports.NotFoundError = NotFoundError;
 exports.Operation = Operation;
 exports.OperationManager = OperationManager;
+exports.RateLimitError = RateLimitError;
 exports.RunStatus = RunStatus;
 exports.SecretManager = SecretManager;
 exports.UCANManager = UCANManager;
+exports.VENUE_RELAY = VENUE_RELAY;
 exports.Venue = Venue;
 exports.WorkspaceManager = WorkspaceManager;
 exports.assetHash = assetHash;
 exports.createSSEEvent = createSSEEvent;
+exports.createUCANJWT = createUCANJWT;
 exports.decodePublicKey = decodePublicKey;
+exports.didFor = didFor;
 exports.didFromPublicKey = didFromPublicKey;
 exports.didMethod = didMethod;
 exports.didUrl = didUrl;
@@ -2614,13 +2855,18 @@ exports.generateKeyPair = generateKeyPair;
 exports.getAssetIdFromPath = getAssetIdFromPath;
 exports.getAssetIdFromVenueId = getAssetIdFromVenueId;
 exports.getParsedAssetId = getParsedAssetId;
+exports.grant = grant;
 exports.hexToPrivateKey = hexToPrivateKey;
+exports.identityToken = identityToken;
 exports.isDid = isDid;
 exports.isJobComplete = isJobComplete;
 exports.isJobFinished = isJobFinished;
 exports.isJobPaused = isJobPaused;
 exports.logger = logger;
 exports.parseDidUrl = parseDidUrl;
+exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.parseSSEStream = parseSSEStream;
 exports.privateKeyToHex = privateKeyToHex;
+exports.relayDelegation = relayDelegation;
+exports.retryDelayMs = retryDelayMs;
 exports.venueBaseUrlCandidates = venueBaseUrlCandidates;