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

package/src/media.mjs

@@ -0,0 +1,242 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import * as z from 'zod/v4';
+import { CredentialStore } from './store.mjs';
+import { operationIdSchema } from './commands.mjs';
+import { AgentError, fail } from './errors.mjs';
+
+const mediaScope = z.string().regex(/^memory:[a-zA-Z0-9_-]{1,128}$/);
+const types = [
+  'image/png',
+  'image/jpeg',
+  'image/webp',
+  'image/gif',
+  'image/avif',
+  'application/pdf',
+  'text/plain',
+];
+export const mediaPrepareSchema = z
+  .object({
+    scope: mediaScope,
+    file: z.string().min(1).max(4096),
+    contentType: z.enum(types),
+    epoch: z.string().min(1).max(128),
+  })
+  .strict();
+export const mediaActionSchema = z
+  .object({
+    scope: mediaScope,
+    ownerId: z.string().regex(/^[a-zA-Z0-9_-]{1,128}$/),
+    id: operationIdSchema,
+    action: z.enum(['inspect', 'publish', 'cancel', 'remove']),
+  })
+  .strict();
+export const mediaDownloadSchema = mediaActionSchema
+  .omit({ action: true })
+  .extend({ file: z.string().min(1).max(4096) })
+  .strict();
+const parse = (schema, value) => {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    fail(
+      'invalid_arguments',
+      'Invalid media arguments. Supply the Memory scope, epoch and a supported private file.',
+    );
+  }
+  return result.data;
+};
+async function fileBytes(path) {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size < 1 || stat.size > 15000000) {
+      fail('invalid_arguments', 'Use a regular file between 1 and 15,000,000 bytes.');
+    }
+    const bytes = Buffer.alloc(15000001);
+    let size = 0;
+    while (size < bytes.length) {
+      const result = await handle.read(bytes, size, bytes.length - size, size);
+      if (!result.bytesRead) {
+        break;
+      }
+      size += result.bytesRead;
+    }
+    if (size > 15000000 || size !== stat.size) {
+      fail('file_changed', 'The file changed while reading. Prepare it again.');
+    }
+    return bytes.subarray(0, size);
+  } catch (error) {
+    if (error instanceof AgentError) {
+      throw error;
+    }
+    fail('invalid_arguments', 'Could not read a regular local media file.');
+  } finally {
+    await handle?.close();
+  }
+}
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const binding = (session) => ({
+  origin: session.origin,
+  connectionId: session.connection_id,
+  profileId: session.profile_id,
+  sessionId: session.session_id,
+});
+function sessionView(value, id, size) {
+  if (
+    !value ||
+    value.id !== id ||
+    typeof value.ownerId !== 'string' ||
+    !/^[a-zA-Z0-9_-]{1,128}$/.test(value.ownerId) ||
+    value.size !== size ||
+    typeof value.published !== 'boolean'
+  ) {
+    fail('invalid_response', 'The attachment session did not match the prepared file.');
+  }
+  return value;
+}
+/** Private immutable local journal: retries reuse the same blob ID and digest.
+ * No binary data, credentials or remote response text are written to this file.
+ */
+export class MediaJournal {
+  constructor(client) {
+    this.client = client;
+  }
+  store(id) {
+    parse(operationIdSchema, id);
+    return new CredentialStore({
+      directory: join(this.client.store.directory, 'media', this.client.store.context),
+      context: id,
+    });
+  }
+  async prepare(value) {
+    const input = parse(mediaPrepareSchema, value),
+      session = await this.client.authorizedSession();
+    const path = resolve(input.file),
+      bytes = await fileBytes(path),
+      id = randomUUID(),
+      store = this.store(id);
+    const fileName = basename(path);
+    if (fileName.length > 200) {
+      fail('invalid_arguments', 'Use a filename of at most 200 characters.');
+    }
+    await store.locked(() =>
+      store.write({
+        formatVersion: 1,
+        binding: binding(session),
+        path,
+        input: {
+          id,
+          issuedAt: Date.now(),
+          scope: input.scope,
+          expectedEpoch: input.epoch,
+          size: bytes.length,
+          sha256: digest(bytes),
+          contentType: input.contentType,
+          fileName,
+          kind: 'memory',
+        },
+      }),
+    );
+    return {
+      operationId: id,
+      scope: input.scope,
+      fileName,
+      size: bytes.length,
+      sha256: digest(bytes),
+      prepared: true,
+    };
+  }
+  async upload(id) {
+    const store = this.store(id);
+    return store.locked(async () => {
+      const value = await store.read(),
+        session = await this.client.authorizedSession();
+      if (
+        !value ||
+        value.formatVersion !== 1 ||
+        value.input?.id !== id ||
+        JSON.stringify(value.binding) !== JSON.stringify(binding(session))
+      ) {
+        fail('media_context_changed', 'Prepare a new upload in this authenticated context.');
+      }
+      const bytes = await fileBytes(value.path);
+      if (bytes.length !== value.input.size || digest(bytes) !== value.input.sha256) {
+        fail('file_changed', 'The prepared file changed; prepare a new operation.');
+      }
+      const transport = this.client.transport,
+        token = session.access_token;
+      const opened = sessionView(
+        await transport.request('/api/agents/v1/media/sessions', {
+          method: 'POST',
+          json: value.input,
+          token,
+        }),
+        id,
+        bytes.length,
+      );
+      const query = { scope: value.input.scope, ownerId: opened.ownerId, id };
+      if (!opened.published) {
+        await transport.request('/api/agents/v1/media/content', {
+          method: 'PUT',
+          query,
+          bytes,
+          token,
+        });
+        const published = sessionView(
+          await transport.request('/api/agents/v1/media/actions', {
+            method: 'POST',
+            json: { ...query, action: 'publish' },
+            token,
+          }),
+          id,
+          bytes.length,
+        );
+        if (!published.published) {
+          fail(
+            'media_not_published',
+            'Upload is not published; inspect its state before retrying.',
+          );
+        }
+      }
+      return {
+        operationId: id,
+        assetId: id,
+        ownerId: opened.ownerId,
+        scope: value.input.scope,
+        published: true,
+        fileName: value.input.fileName,
+        size: bytes.length,
+        sha256: value.input.sha256,
+      };
+    }, this.client.transport.signal);
+  }
+}
+export async function mediaAction(client, value) {
+  const input = parse(mediaActionSchema, value);
+  return client.transport.request('/api/agents/v1/media/actions', {
+    method: 'POST',
+    json: input,
+    token: await client.accessToken(),
+  });
+}
+/** Explicit destination only. Exclusive creation never overwrites existing files. */
+export async function downloadMedia(client, value) {
+  const { file, ...query } = parse(mediaDownloadSchema, value);
+  const bytes = await client.transport.request('/api/agents/v1/media/content', {
+    query,
+    binary: true,
+    token: await client.accessToken(),
+  });
+  const path = resolve(file);
+  const handle = await open(path, 'wx', 0o600);
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  return { file: path, size: bytes.length, sha256: digest(bytes) };
+}

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;