@pulsarinteractive/geniustasker 0.1.0-beta.3 → 0.1.0-beta.5

package/src/read-cache.mjs

@@ -0,0 +1,111 @@
+import { fail } from './errors.mjs';
+
+/**
+ * Bounded process-local LRU for conditional resource reads. Every access calls
+ * the server; TTL controls retention only, never permission freshness. Document
+ * data is neither persisted to disk nor served as an offline fallback.
+ */
+export class ConditionalReadCache {
+  constructor({
+    maxBytes = 8 * 1024 * 1024,
+    maxEntries = 64,
+    maxAgeMs = 900000,
+    now = Date.now,
+  } = {}) {
+    for (const value of [maxBytes, maxEntries, maxAgeMs]) {
+      if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError('Read cache limits must be positive integers.');
+      }
+    }
+    this.maxBytes = maxBytes;
+    this.maxEntries = maxEntries;
+    this.maxAgeMs = maxAgeMs;
+    this.now = now;
+    this.entries = new Map();
+    this.pending = new Map();
+    this.bytes = 0;
+    this.generation = 0;
+  }
+
+  clear() {
+    this.generation++;
+    this.entries.clear();
+    this.pending.clear();
+    this.bytes = 0;
+  }
+
+  remove(key) {
+    const old = this.entries.get(key);
+    if (old) {
+      this.bytes -= old.bytes;
+      this.entries.delete(key);
+    }
+  }
+
+  async read(key, load) {
+    const existing = this.pending.get(key);
+    if (existing) {
+      return structuredClone(await existing);
+    }
+    const generation = this.generation;
+    for (const [entryKey, entry] of this.entries) {
+      if (this.now() - entry.at >= this.maxAgeMs) {
+        this.remove(entryKey);
+      }
+    }
+    const cached = this.entries.get(key);
+    const pending = (async () => {
+      const received = await load(cached?.value.etag);
+      if (generation !== this.generation) {
+        fail('read_context_changed', 'The read context changed while this request was running.', {
+          retryable: true,
+          remediation: 'Read again in the currently selected account and profile.',
+        });
+      }
+      if (!received || typeof received !== 'object' || Array.isArray(received)) {
+        fail('invalid_response', 'The resource response was invalid.');
+      }
+      let value = received;
+      if (received?.notModified === true) {
+        if (
+          !cached ||
+          received.etag !== cached.value.etag ||
+          received.scope !== cached.value.scope ||
+          received.collection !== cached.value.collection ||
+          received.epoch !== cached.value.epoch ||
+          received.checkpoint !== cached.value.checkpoint ||
+          !Array.isArray(received.items) ||
+          received.items.length !== 0
+        ) {
+          fail('invalid_response', 'A conditional response did not match the cached resource.');
+        }
+        value = cached.value;
+      }
+      this.remove(key);
+      const size = Buffer.byteLength(JSON.stringify(value));
+      if (typeof value?.etag === 'string' && value.etag.length <= 8192 && size <= this.maxBytes) {
+        this.entries.set(key, { value: structuredClone(value), bytes: size, at: this.now() });
+        this.bytes += size;
+        while (this.entries.size > this.maxEntries || this.bytes > this.maxBytes) {
+          this.remove(this.entries.keys().next().value);
+        }
+      }
+      return value;
+    })();
+    this.pending.set(key, pending);
+    try {
+      return structuredClone(await pending);
+    } catch (error) {
+      // A permission, authentication, network or schema failure can never turn
+      // into stale private success, or let another in-flight read refill it.
+      if (generation === this.generation) {
+        this.clear();
+      }
+      throw error;
+    } finally {
+      if (this.pending.get(key) === pending) {
+        this.pending.delete(key);
+      }
+    }
+  }
+}

package/src/transport.mjs

@@ -1,4 +1,5 @@
 import { AgentError, fail } from './errors.mjs';
+import catalog from './command-catalog.mjs';
 
 export const ORIGINS = Object.freeze({
   production: 'https://api-geniustasker.pulsarinteractive.cloud',
@@ -54,7 +55,7 @@ export class Transport {
     this.timeoutMs = timeoutMs;
     this.signal = signal;
   }
-  async request(path, { method = 'GET', form, json, token, query } = {}) {
+  async request(path, { method = 'GET', form, json, token, query, bytes, binary = false } = {}) {
     if (
       !(path.startsWith('/api/agents/') || path === '/.well-known/oauth-authorization-server') ||
       path.startsWith('//')
@@ -78,12 +79,23 @@ export class Transport {
         }
       }
     }
+    if (
+      (bytes !== undefined || binary) &&
+      (url.pathname !== '/api/agents/v1/media/content' ||
+        (bytes !== undefined && (!Buffer.isBuffer(bytes) || bytes.length > 15000000)) ||
+        (bytes !== undefined && (json !== undefined || form)))
+    ) {
+      fail('invalid_arguments', 'Binary transfer requires the bounded delegated media endpoint.');
+    }
     if (form && json !== undefined) {
       fail('invalid_arguments', 'Choose one request body format.');
     }
     const jsonBody = json === undefined ? undefined : JSON.stringify(json);
-    if (jsonBody && Buffer.byteLength(jsonBody) > 32768) {
-      fail('invalid_arguments', 'Command exceeds the 32 KiB request limit.');
+    if (jsonBody && Buffer.byteLength(jsonBody) > catalog.maxCommandBytes) {
+      fail(
+        'invalid_arguments',
+        `Command exceeds the ${catalog.maxCommandBytes} byte request limit.`,
+      );
     }
     let response;
     const timeout = AbortSignal.timeout(this.timeoutMs);
@@ -94,15 +106,23 @@ export class Transport {
         redirect: 'error',
         signal,
         headers: {
-          Accept: 'application/json',
+          Accept: binary ? 'application/octet-stream' : 'application/json',
           ...(token ? { Authorization: `Bearer ${token}` } : {}),
-          ...(form
-            ? { 'Content-Type': 'application/x-www-form-urlencoded' }
+          ...(bytes !== undefined
+            ? { 'Content-Type': 'application/octet-stream', 'Content-Length': String(bytes.length) }
+            : form
+              ? { 'Content-Type': 'application/x-www-form-urlencoded' }
+              : jsonBody
+                ? { 'Content-Type': 'application/json' }
+                : {}),
+        },
+        ...(bytes !== undefined
+          ? { body: bytes }
+          : form
+            ? { body: new URLSearchParams(form) }
             : jsonBody
-              ? { 'Content-Type': 'application/json' }
+              ? { body: jsonBody }
               : {}),
-        },
-        ...(form ? { body: new URLSearchParams(form) } : jsonBody ? { body: jsonBody } : {}),
       });
     } catch {
       throw new AgentError('network_unavailable', 'The API did not return a usable response.', {
@@ -118,7 +138,7 @@ export class Transport {
       if (response.body) {
         for await (const chunk of response.body) {
           size += chunk.length;
-          if (size > 262144) {
+          if (size > (binary && response.ok ? 15000000 : 262144)) {
             fail('invalid_response', 'The API response exceeded the size limit.');
           }
           chunks.push(chunk);
@@ -133,6 +153,9 @@ export class Transport {
         execution: method === 'GET' ? 'not_applicable' : 'unknown',
       });
     }
+    if (binary && response.ok) {
+      return Buffer.concat(chunks);
+    }
     let data;
     try {
       data = size ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : null;