@pulsarinteractive/geniustasker 0.0.0-stage → 0.1.0-beta.10

package/src/profiles.mjs

@@ -0,0 +1,154 @@
+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)
+  // 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;
+};
+
+/** 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;
+  }
+  async list() {
+    const result = choicesSchema.safeParse(await this.client.get('profiles'));
+    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 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.',
+      });
+    }
+    try {
+      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)
+      ) {
+        fail('invalid_response', 'The profile change could not be confirmed.');
+      }
+      return parsed.data;
+    } catch (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.';
+      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,
+    });
+  }
+}

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/store.mjs

@@ -0,0 +1,141 @@
+import { constants } from 'node:fs';
+import { mkdir, lstat, open, rename, unlink, rmdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fail } from './errors.mjs';
+
+/** Dedicated directory only: do not point at a repository or a shared folder.
+ * File permissions protect against other OS users, not processes of this user.
+ * A hard crash deliberately leaves a lock/refresh marker rather than risking a
+ * second use of a rotated refresh token. Doctor explains recovery. */
+export class CredentialStore {
+  constructor({
+    directory = join(homedir(), '.geniustasker'),
+    context = 'default',
+    lockTimeoutMs = 20000,
+    maxBytes = 16384,
+  } = {}) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,47}$/.test(context)) {
+      fail('invalid_arguments', 'Context names use 1–48 letters, numbers, underscores or hyphens.');
+    }
+    this.context = context;
+    this.maxBytes = maxBytes;
+    this.directory = resolve(directory);
+    this.path = join(this.directory, `${context}.json`);
+    this.lockPath = `${this.path}.lock`;
+    this.lockTimeoutMs = lockTimeoutMs;
+  }
+  async prepare() {
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const stat = await lstat(this.directory);
+    if (
+      !stat.isDirectory() ||
+      stat.isSymbolicLink() ||
+      (process.getuid && stat.uid !== process.getuid()) ||
+      (process.platform !== 'win32' && stat.mode & 0o077)
+    ) {
+      fail(
+        'unsafe_credential_store',
+        'The credential directory must be private and owned by you.',
+        { remediation: 'Use a dedicated directory with permissions 0700.' },
+      );
+    }
+  }
+  async read() {
+    await this.prepare();
+    let handle;
+    try {
+      handle = await open(this.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        return null;
+      }
+      fail('unsafe_credential_store', 'The credential file could not be opened safely.');
+    }
+    try {
+      const stat = await handle.stat();
+      if (
+        !stat.isFile() ||
+        stat.nlink !== 1 ||
+        stat.size > this.maxBytes ||
+        (process.platform !== 'win32' && stat.mode & 0o077) ||
+        (process.getuid && stat.uid !== process.getuid())
+      ) {
+        fail('unsafe_credential_store', 'The credential file must be private and owned by you.');
+      }
+      try {
+        return JSON.parse(await handle.readFile('utf8'));
+      } catch {
+        fail('invalid_credential_store', 'The credential file is damaged.', {
+          remediation:
+            'Revoke the session in Account → Agents, then remove this context and log in again.',
+        });
+      }
+    } finally {
+      await handle.close();
+    }
+  }
+  async write(data) {
+    const temporary = `${this.path}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+      await handle.writeFile(JSON.stringify(data));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    try {
+      await rename(temporary, this.path);
+      if (process.platform !== 'win32') {
+        const directory = await open(this.directory, constants.O_RDONLY);
+        try {
+          await directory.sync();
+        } finally {
+          await directory.close();
+        }
+      }
+    } finally {
+      await unlink(temporary).catch((error) => {
+        if (error.code !== 'ENOENT') {
+          throw error;
+        }
+      });
+    }
+  }
+  async remove() {
+    await unlink(this.path).catch((error) => {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    });
+  }
+  async locked(callback, signal) {
+    await this.prepare();
+    const deadline = Date.now() + this.lockTimeoutMs;
+    while (true) {
+      try {
+        await mkdir(this.lockPath, { mode: 0o700 });
+        break;
+      } catch (error) {
+        if (error.code !== 'EEXIST') {
+          throw error;
+        }
+        if (Date.now() >= deadline) {
+          fail('credential_store_busy', 'Another command owns this credential context.', {
+            retryable: true,
+            remediation:
+              'Wait for that command. After a crash, stop all clients using this context, then remove its empty .lock directory.',
+          });
+        }
+        await delay(50, undefined, { signal });
+      }
+    }
+    try {
+      return await callback();
+    } finally {
+      await rmdir(this.lockPath);
+    }
+  }
+}

package/src/transport.mjs

@@ -0,0 +1,201 @@
+import { AgentError, fail } from './errors.mjs';
+import catalog from './command-catalog.mjs';
+
+export const ORIGINS = Object.freeze({
+  production: 'https://api-geniustasker.pulsarinteractive.cloud',
+  development: 'https://dev-api-geniustasker.pulsarinteractive.cloud',
+});
+export const CLIENT_ID = 'geniustasker-cli';
+/** Resolve an approved API origin; loopback is available only by explicit opt-in. */
+export function originOf(value = ORIGINS.production, allowLocal = false) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    fail('invalid_origin', 'An absolute API origin is required.');
+  }
+  if (
+    url.username ||
+    url.password ||
+    url.pathname !== '/' ||
+    url.search ||
+    url.hash ||
+    !(
+      Object.values(ORIGINS).includes(url.origin) ||
+      (allowLocal && url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname))
+    )
+  ) {
+    fail(
+      'invalid_origin',
+      'Use a GeniusTasker API origin or an explicit loopback origin with --allow-local.',
+    );
+  }
+  return url.origin;
+}
+
+const identifier = (value) =>
+  typeof value === 'string' && /^[a-zA-Z0-9_.:-]{1,100}$/.test(value) ? value : undefined;
+const boundedText = (value) =>
+  typeof value === 'string' &&
+  value.length <= 500 &&
+  // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
+  !/[\u0000-\u001f\u007f]/u.test(value) &&
+  !/gta1\.|wd[ar]_|sk-proj-/u.test(value)
+    ? value
+    : undefined;
+/**
+ * Bounded HTTP transport for delegated endpoints, with no implicit retries.
+ * Call originOf before construction; inject fetch/signal for controlled tests
+ * and operation-level cancellation. Error serialization excludes raw responses.
+ */
+export class Transport {
+  constructor(origin, { fetchImpl = fetch, timeoutMs = 15000, signal } = {}) {
+    this.origin = origin;
+    this.fetch = fetchImpl;
+    this.timeoutMs = timeoutMs;
+    this.signal = signal;
+  }
+  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('//')
+    ) {
+      fail('invalid_arguments', 'Only delegated endpoints are available.');
+    }
+    const url = new URL(path, this.origin);
+    if (
+      url.origin !== this.origin ||
+      !(
+        url.pathname.startsWith('/api/agents/') ||
+        url.pathname === '/.well-known/oauth-authorization-server'
+      )
+    ) {
+      fail('invalid_origin', 'Cross-origin or non-delegated requests are refused.');
+    }
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    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) > catalog.maxCommandBytes) {
+      fail(
+        'invalid_arguments',
+        `Command exceeds the ${catalog.maxCommandBytes} byte request limit.`,
+      );
+    }
+    let response;
+    const timeout = AbortSignal.timeout(this.timeoutMs);
+    const signal = this.signal ? AbortSignal.any([timeout, this.signal]) : timeout;
+    try {
+      response = await this.fetch(url, {
+        method,
+        redirect: 'error',
+        signal,
+        headers: {
+          Accept: binary ? 'application/octet-stream' : 'application/json',
+          ...(token ? { Authorization: `Bearer ${token}` } : {}),
+          ...(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
+              ? { body: jsonBody }
+              : {}),
+      });
+    } catch {
+      throw new AgentError('network_unavailable', 'The API did not return a usable response.', {
+        retryable: true,
+        remediation:
+          'Check connectivity. Authentication exchanges are never retried automatically.',
+        execution: method === 'GET' ? 'not_applicable' : 'unknown',
+      });
+    }
+    const chunks = [];
+    let size = 0;
+    try {
+      if (response.body) {
+        for await (const chunk of response.body) {
+          size += chunk.length;
+          if (size > (binary && response.ok ? 15000000 : 262144)) {
+            fail('invalid_response', 'The API response exceeded the size limit.');
+          }
+          chunks.push(chunk);
+        }
+      }
+    } catch (error) {
+      if (error instanceof AgentError) {
+        throw error;
+      }
+      fail('network_unavailable', 'The API response was interrupted.', {
+        retryable: true,
+        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;
+    } catch {
+      fail('invalid_response', 'The API returned an unexpected format.', {
+        status: response.status,
+      });
+    }
+    if (!response.ok) {
+      const e = data?.error;
+      const code = identifier(typeof e === 'string' ? e : e?.code) ?? 'api_error';
+      const retry = Number(response.headers.get('Retry-After') ?? e?.retryAfterSeconds);
+      throw new AgentError(code, boundedText(e?.message) ?? 'The API refused the request.', {
+        status: response.status,
+        retryable:
+          typeof e?.retryable === 'boolean'
+            ? e.retryable
+            : response.status === 429 || response.status === 503,
+        remediation:
+          boundedText(e?.remediation) ??
+          (response.status === 401
+            ? 'Run auth login again; check the connection in Account → Agents.'
+            : 'Check permissions, availability and command help.'),
+        ...(identifier(e?.requestId) ? { requestId: e.requestId } : {}),
+        ...(Number.isFinite(retry) && retry >= 0 && retry <= 86400
+          ? { retryAfterSeconds: retry }
+          : {}),
+        ...(Number.isSafeInteger(data?.interval) && data.interval > 0
+          ? { interval: data.interval }
+          : {}),
+        ...(identifier(e?.execution) ? { execution: e.execution } : {}),
+        ...(Number.isSafeInteger(e?.resetAt) && e.resetAt > 0 ? { resetAt: e.resetAt } : {}),
+      });
+    }
+    return data;
+  }
+  oauth(endpoint, form) {
+    return this.request(`/api/agents/oauth/${endpoint}`, {
+      method: 'POST',
+      form: { client_id: CLIENT_ID, ...form },
+    });
+  }
+}

package/src/workflows.mjs

@@ -0,0 +1,9 @@
+import * as z from 'zod/v4';
+import guides from '../remote/workflows.json' with { type: 'json' };
+
+/** Reviewed static guidance, shared with the hosted connector. No account data. */
+export const workflowSchema = z.object({ topic: z.enum(Object.keys(guides.topics)) }).strict();
+export function workflow(input) {
+  const { topic } = workflowSchema.parse(input);
+  return { version: guides.version, topic, ...guides.topics[topic] };
+}