@pulsarinteractive/geniustasker 0.1.0-beta.2 → 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/profiles.mjs

@@ -2,62 +2,153 @@ import * as z from 'zod/v4';
 import { AgentError, fail } from './errors.mjs';
 import catalog from './command-catalog.mjs';
 
-const name = z.string().trim().min(1).max(80).regex(/^[^\u0000-\u001f\u007f]+$/u);
-const unique = values => new Set(values).size === values.length;
-export const grantSchema = z.object({
-  allResources: z.boolean(),
-  resourceIds: z.array(z.string().min(1).max(256)).max(catalog.grants.maxResources).refine(unique),
-  permissions: z.array(z.enum(catalog.grants.permissions)).max(catalog.grants.permissions.length).refine(unique),
-}).strict().refine(grant => !grant.allResources || grant.resourceIds.length === 0);
+const name = z
+  .string()
+  .trim()
+  .min(1)
+  .max(80)
+  // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
+  .regex(/^[^\u0000-\u001f\u007f]+$/u);
+const unique = (values) => new Set(values).size === values.length;
+export const grantSchema = z
+  .object({
+    allResources: z.boolean(),
+    resourceIds: z
+      .array(z.string().min(1).max(256))
+      .max(catalog.grants.maxResources)
+      .refine(unique),
+    permissions: z
+      .array(z.enum(catalog.grants.permissions))
+      .max(catalog.grants.permissions.length)
+      .refine(unique),
+  })
+  .strict()
+  .refine((grant) => !grant.allResources || grant.resourceIds.length === 0);
 export const profileCreateSchema = z.object({ id: z.uuid(), name, grant: grantSchema }).strict();
-export const profileRestrictSchema = z.object({ profileId: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/), name, expectedRevision: z.number().int().min(1), grant: grantSchema }).strict();
-export const profileSelectSchema = z.object({ profileId: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/) }).strict();
-const choiceSchema = z.object({ id: z.string(), name, revision: z.number().int().min(1), current: z.boolean(),
-  permissions: z.array(z.string()), allResources: z.boolean(), resourceCount: z.number().int().min(0) }).strict();
-const choicesSchema = z.object({ connectionId: z.string(), currentProfileId: z.string(), items: z.array(choiceSchema).max(catalog.grants.maxProfilesPerConnection) }).strict();
-const profileSchema = z.object({ id: z.string(), connectionId: z.string(), name, revision: z.number().int().min(1), grant: grantSchema, disabledAt: z.number().nullable() }).strict();
-const input = (schema, value) => { const result = schema.safeParse(value); if (!result.success) fail('invalid_arguments', 'Use the declared profile fields, a valid name and a bounded grant.'); return result.data; };
+export const profileRestrictSchema = z
+  .object({
+    profileId: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/),
+    name,
+    expectedRevision: z.number().int().min(1),
+    grant: grantSchema,
+  })
+  .strict();
+export const profileSelectSchema = z
+  .object({ profileId: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/) })
+  .strict();
+const choiceSchema = z
+  .object({
+    id: z.string(),
+    name,
+    revision: z.number().int().min(1),
+    current: z.boolean(),
+    permissions: z.array(z.string()),
+    allResources: z.boolean(),
+    resourceCount: z.number().int().min(0),
+  })
+  .strict();
+const choicesSchema = z
+  .object({
+    connectionId: z.string(),
+    currentProfileId: z.string(),
+    items: z.array(choiceSchema).max(catalog.grants.maxProfilesPerConnection),
+  })
+  .strict();
+const profileSchema = z
+  .object({
+    id: z.string(),
+    connectionId: z.string(),
+    name,
+    revision: z.number().int().min(1),
+    grant: grantSchema,
+    disabledAt: z.number().nullable(),
+  })
+  .strict();
+const input = (schema, value) => {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    fail('invalid_arguments', 'Use the declared profile fields, a valid name and a bounded grant.');
+  }
+  return result.data;
+};
 
 /** Profile management is separate from domain-operation journals: creation has
  * an explicit UUID retained in the caller's file, restriction a live revision,
  * and selection rotates the credential family under the credential-store lock. */
 export class AgentProfiles {
-  constructor(client) { this.client = client; }
+  constructor(client) {
+    this.client = client;
+  }
   async list() {
     const result = choicesSchema.safeParse(await this.client.get('profiles'));
-    if (!result.success) fail('invalid_response', 'The profile list was invalid.');
+    if (!result.success) {
+      fail('invalid_response', 'The profile list was invalid.');
+    }
     return result.data;
   }
-  async create(value) { return this.write('profiles', 'POST', input(profileCreateSchema, value)); }
-  async restrict(value) { return this.write('profile', 'PUT', input(profileRestrictSchema, value)); }
+  async create(value) {
+    return this.write('profiles', 'POST', input(profileCreateSchema, value));
+  }
+  async restrict(value) {
+    return this.write('profile', 'PUT', input(profileRestrictSchema, value));
+  }
   async write(resource, method, value) {
     const session = await this.client.authorizedSession();
-    if (method === 'PUT' && value.profileId !== session.profile_id)
-      fail('profile_selection_conflict', 'This draft belongs to another profile.', { status: 409, remediation: 'Read whoami and prepare a fresh restriction for the intended profile.' });
+    if (method === 'PUT' && value.profileId !== session.profile_id) {
+      fail('profile_selection_conflict', 'This draft belongs to another profile.', {
+        status: 409,
+        remediation: 'Read whoami and prepare a fresh restriction for the intended profile.',
+      });
+    }
     try {
-      const result = await this.client.transport.request(`/api/agents/v1/${resource}`, { method, token: session.access_token, json: value });
+      const result = await this.client.transport.request(`/api/agents/v1/${resource}`, {
+        method,
+        token: session.access_token,
+        json: value,
+      });
       const parsed = profileSchema.safeParse(result);
-      if (!parsed.success || parsed.data.connectionId !== session.connection_id ||
-          parsed.data.id !== (method === 'POST' ? value.id : session.profile_id))
+      if (
+        !parsed.success ||
+        parsed.data.connectionId !== session.connection_id ||
+        parsed.data.id !== (method === 'POST' ? value.id : session.profile_id)
+      ) {
         fail('invalid_response', 'The profile change could not be confirmed.');
+      }
       return parsed.data;
     } catch (error) {
-      if (!(error instanceof AgentError)) throw error;
+      if (!(error instanceof AgentError)) {
+        throw error;
+      }
       error.details.profileId = method === 'POST' ? value.id : session.profile_id;
       error.details.execution ??= 'unknown';
-      error.remediation = method === 'POST'
-        ? 'List profiles and reconcile this profileId. Keep the same UUID on retry; do not create a replacement after an uncertain reply.'
-        : 'Read whoami to see the current profile and revision before preparing another restriction.';
+      error.remediation =
+        method === 'POST'
+          ? 'List profiles and reconcile this profileId. Keep the same UUID on retry; do not create a replacement after an uncertain reply.'
+          : 'Read whoami to see the current profile and revision before preparing another restriction.';
       throw error;
     }
   }
   async select(value) {
     const { profileId } = input(profileSelectSchema, value);
     const choices = await this.list();
-    const source = choices.items.find(p => p.id === choices.currentProfileId && p.current);
-    const target = choices.items.find(p => p.id === profileId);
-    if (!source || !target) fail('profile_selection_denied', 'This profile is not available within the current connection and permissions.', { status: 403, remediation: 'Run profiles list. An agent cannot switch back to broader permissions.' });
-    return this.client.selectProfile({ profileId, expectedRevision: target.revision, expectedSourceRevision: source.revision,
-      sourceProfileId: source.id, connectionId: choices.connectionId });
+    const source = choices.items.find((p) => p.id === choices.currentProfileId && p.current);
+    const target = choices.items.find((p) => p.id === profileId);
+    if (!source || !target) {
+      fail(
+        'profile_selection_denied',
+        'This profile is not available within the current connection and permissions.',
+        {
+          status: 403,
+          remediation: 'Run profiles list. An agent cannot switch back to broader permissions.',
+        },
+      );
+    }
+    return this.client.selectProfile({
+      profileId,
+      expectedRevision: target.revision,
+      expectedSourceRevision: source.revision,
+      sourceProfileId: source.id,
+      connectionId: choices.connectionId,
+    });
   }
 }

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);
+      }
+    }
+  }
+}