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

package/src/commands.mjs

@@ -0,0 +1,277 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as z from 'zod/v4';
+import catalog from './command-catalog.mjs';
+import { CredentialStore } from './store.mjs';
+import { AgentError, fail, safeError } from './errors.mjs';
+
+export const operationIdSchema = z
+  .string()
+  .regex(/^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$/);
+const identifier = z
+  .string()
+  .min(1)
+  .max(128)
+  // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
+  .regex(/^[^\u0000-\u001f]+$/u);
+export const commandSchema = z
+  .object({
+    operationId: operationIdSchema,
+    issuedAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    scope: z
+      .string()
+      .max(256)
+      // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
+      .regex(/^(project|memory):[^\u0000-\u001f]+$/u),
+    epoch: identifier,
+    id: identifier,
+    expectedRevision: z
+      .string()
+      .regex(/^[1-9][0-9]{0,15}$/)
+      .nullable(),
+    kind: z.enum(Object.keys(catalog.commands)),
+    data: z.record(z.string(), z.json()),
+  })
+  .strict();
+export const draftSchema = commandSchema.omit({ operationId: true, issuedAt: true });
+const canonical = (value) =>
+  JSON.stringify(value, (_, item) =>
+    item && typeof item === 'object' && !Array.isArray(item)
+      ? Object.fromEntries(
+          Object.keys(item)
+            .sort()
+            .map((key) => [key, item[key]]),
+        )
+      : item,
+  );
+const checked = (schema, value) => {
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) {
+    fail(
+      'invalid_arguments',
+      'The command does not match its schema. Use commands describe; do not supply credentials or server-owned fields.',
+    );
+  }
+  return parsed.data;
+};
+/** Validate the public envelope, generated field allowlist and resource scope. */
+export function validateCommand(value) {
+  const command = checked(commandSchema, value),
+    definition = catalog.commands[command.kind];
+  if (
+    Buffer.byteLength(JSON.stringify(command)) > catalog.maxCommandBytes ||
+    Object.keys(command.data).some((key) => !definition.fields.includes(key)) ||
+    (definition.create ? command.expectedRevision !== null : command.expectedRevision === null)
+  ) {
+    fail(
+      'invalid_arguments',
+      'Use the declared command fields and size limit. Creation requires a null revision; other commands require the current record revision.',
+    );
+  }
+  const prefix = definition.module.startsWith('Memory/') ? 'memory:' : 'project:';
+  if (
+    !command.scope.startsWith(prefix) ||
+    (definition.module.endsWith('/$') && command.id !== command.scope.slice(prefix.length))
+  ) {
+    fail('invalid_arguments', 'The command must target the matching project or memory scope.');
+  }
+  if (
+    ['memory.create', 'project.create'].includes(command.kind) &&
+    (!/^[a-f\d]{8}-[a-f\d]{4}-4[a-f\d]{3}-[89ab][a-f\d]{3}-[a-f\d]{12}$/i.test(command.id) ||
+      command.epoch !== command.id)
+  ) {
+    fail(
+      'invalid_arguments',
+      'Create a space with a UUID v4 as id and the same initial epoch. Use project:<id> or memory:<id> as appropriate; keep source identifiers in page sourceId.',
+    );
+  }
+  if (command.kind === 'ticket.plan' && command.id !== command.scope.slice(8)) {
+    fail(
+      'invalid_arguments',
+      'ticket.plan targets the project ID and root revision; changes carry each task expectedVersion.',
+    );
+  }
+  return command;
+}
+export function describeCommands() {
+  return {
+    ...catalog,
+    envelope: z.toJSONSchema(commandSchema),
+    draft: z.toJSONSchema(draftSchema),
+    recovery:
+      'Retain operationId, issuedAt and the complete body. Retry an uncertain write unchanged; reread before creating a new edit after a conflict.',
+  };
+}
+/** Read one bounded regular JSON file, rejecting symlinks and non-file inputs. */
+export async function readCommandFile(path) {
+  if (typeof path !== 'string') {
+    fail('invalid_arguments', 'Supply --file with a JSON command or draft.');
+  }
+  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 > catalog.maxCommandBytes) {
+      fail(
+        'invalid_arguments',
+        `Use a regular JSON file no larger than ${catalog.maxCommandBytes} bytes.`,
+      );
+    }
+    const bytes = Buffer.alloc(catalog.maxCommandBytes + 1),
+      result = await handle.read(bytes, 0, bytes.length, 0);
+    if (result.bytesRead > catalog.maxCommandBytes) {
+      fail('invalid_arguments', `Command file exceeds ${catalog.maxCommandBytes} bytes.`);
+    }
+    return JSON.parse(bytes.subarray(0, result.bytesRead).toString('utf8'));
+  } catch (error) {
+    if (error instanceof AgentError) {
+      throw error;
+    }
+    fail('invalid_arguments', 'Could not read a regular, valid JSON command file.');
+  } finally {
+    await handle?.close();
+  }
+}
+const binding = (session) => ({
+  origin: session.origin,
+  connectionId: session.connection_id,
+  profileId: session.profile_id,
+  sessionId: session.session_id,
+});
+const receiptSchema = z
+  .object({
+    operationId: operationIdSchema,
+    scope: z.string(),
+    kind: z.string(),
+    epoch: z.string(),
+    cursor: z.string(),
+    items: z.array(
+      z
+        .object({
+          id: z.string(),
+          revision: z.string(),
+          collection: z.string(),
+          deleted: z.boolean(),
+        })
+        .strict(),
+    ),
+    affectedCollections: z.array(z.string()),
+  })
+  .strict();
+
+/** A journal is bound to one authenticated terminal identity. Persist the full
+ * request before the network call, never regenerate a UUID after a timeout.
+ * It contains private project text but no access/refresh tokens. A process crash
+ * leaves its operation lock for explicit recovery after all clients stop. */
+export class CommandJournal {
+  constructor(client) {
+    this.client = client;
+  }
+  store(id) {
+    checked(operationIdSchema, id);
+    return new CredentialStore({
+      directory: join(this.client.store.directory, 'operations', this.client.store.context),
+      context: id,
+      maxBytes: 524288,
+    });
+  }
+  async prepare(draft) {
+    const input = validateCommand({
+      ...checked(draftSchema, draft),
+      operationId: randomUUID(),
+      issuedAt: Date.now(),
+    });
+    const identity = binding(await this.client.session()),
+      store = this.store(input.operationId);
+    await store.locked(
+      () => store.write({ formatVersion: 1, binding: identity, input, state: 'prepared' }),
+      this.client.transport.signal,
+    );
+    return { operationId: input.operationId, state: 'prepared', request: input };
+  }
+  async inspect(id) {
+    const row = await this.store(id).read();
+    if (!row || row.formatVersion !== 1 || row.input?.operationId !== id) {
+      fail('operation_not_found', 'This context has no valid local operation with that ID.');
+    }
+    return {
+      operationId: id,
+      source: 'local_journal',
+      state: row.state,
+      request: row.input,
+      ...(row.receipt ? { receipt: row.receipt } : {}),
+      ...(row.error ? { error: row.error } : {}),
+    };
+  }
+  async execute(value) {
+    const input = validateCommand(value),
+      store = this.store(input.operationId);
+    return store.locked(async () => {
+      // Capture token and identity together under the refresh lock. A later
+      // logout/login cannot turn this pending operation into another profile.
+      const session = await this.client.authorizedSession(),
+        identity = binding(session);
+      let row = await store.read();
+      if (row && (row.formatVersion !== 1 || canonical(row.binding) !== canonical(identity))) {
+        fail(
+          'operation_identity_mismatch',
+          'This operation belongs to another connection, profile, session or environment.',
+          {
+            remediation:
+              'Inspect it locally and reread current records. Do not replay it through a replacement login.',
+          },
+        );
+      }
+      if (row && canonical(row.input) !== canonical(input)) {
+        fail(
+          'idempotency_mismatch',
+          'The operation ID already belongs to a different immutable request.',
+          { status: 409, remediation: 'Use commands inspect, then retry the saved operation.' },
+        );
+      }
+      if (row?.state === 'confirmed') {
+        return { source: 'local_receipt', receipt: row.receipt };
+      }
+      row = { formatVersion: 1, binding: identity, input, state: 'uncertain' };
+      await store.write(row);
+      try {
+        const receipt = await this.client.transport.request('/api/agents/v1/commands', {
+          method: 'POST',
+          json: input,
+          token: session.access_token,
+        });
+        if (
+          !receiptSchema.safeParse(receipt).success ||
+          ['operationId', 'scope', 'kind', 'epoch'].some((key) => receipt[key] !== input[key])
+        ) {
+          fail(
+            'invalid_response',
+            'The command receipt was invalid. The server may have committed.',
+            { execution: 'unknown', remediation: 'Retry the identical saved operation.' },
+          );
+        }
+        await store.write({ ...row, state: 'confirmed', receipt });
+        return { source: 'server', receipt };
+      } catch (error) {
+        const safe = safeError(error);
+        const result = new AgentError(safe.code, safe.message, {
+          status: safe.status,
+          retryable: safe.retryable,
+          remediation: safe.remediation,
+          execution: 'unknown',
+          ...safe.details,
+          operationId: input.operationId,
+        });
+        // The uncertainty marker is already durable. Preserve the useful original
+        // error/operation ID even if disk pressure prevents saving diagnostics.
+        await store.write({ ...row, error: result.toJSON() }).catch(() => {});
+        throw result;
+      }
+    }, this.client.transport.signal);
+  }
+  async retry(id) {
+    return this.execute((await this.inspect(id)).request);
+  }
+}

package/src/documentation-graph.mjs

@@ -0,0 +1,251 @@
+import * as z from 'zod/v4';
+import { readChanges } from './changes.mjs';
+import { fail } from './errors.mjs';
+const id = z.string().regex(/^[a-zA-Z0-9_-]{1,128}$/);
+const recordSchema = z.object({
+  id,
+  revision: z.string().regex(/^[0-9]+$/),
+  data: z.record(z.string(), z.unknown()),
+});
+const parse = (schema, value) => {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    fail('invalid_response', 'The Graph source format is invalid.');
+  }
+  return result.data;
+};
+const contextOf = (tree) => ({ epoch: tree.epoch, checkpoint: tree.checkpoint });
+const equivalentAccess = (before, tree) =>
+  before?.epoch === tree.epoch && before.accessRevision === tree.accessRevision;
+const escape = (value) =>
+  String(value)
+    .replace(/[\r\n]/g, ' ')
+    .replace(/[\\`*_[\]<>|]/g, '\\$&');
+
+async function graphCollection(client, scope, collection, tree, previous, cursor, downloads) {
+  const records = new Map((previous ?? []).map((record) => [record.id, record]));
+  if (cursor) {
+    try {
+      for (let count = 0; count < 1000; count++) {
+        const page = await readChanges(client, { scope, collection, cursor });
+        if (page.epoch !== tree.epoch || page.omittedIds.length) {
+          fail('incomplete_documentation', 'The Graph change response is incomplete.');
+        }
+        for (const item of page.items) {
+          if (item.kind === 'remove') {
+            records.delete(item.id);
+          } else {
+            records.set(
+              item.id,
+              parse(recordSchema, { id: item.id, revision: item.revision, data: item.data }),
+            );
+          }
+        }
+        cursor = page.nextCursor;
+        if (!page.hasMore) {
+          return { items: [...records.values()], cursor };
+        }
+      }
+      fail('documentation_capacity', 'The Graph change window exceeds its request budget.');
+    } catch (error) {
+      if (!['reset_required', 'agent_change_history_expired'].includes(error.code)) {
+        throw error;
+      }
+      records.clear(); // Explicit server reset: replace from a fresh bounded inventory.
+    }
+  }
+  let after;
+  for (let count = 0; count < 1000; count++) {
+    const query = { scope, collection, after, ...contextOf(tree) };
+    const key = JSON.stringify(query),
+      bucket = downloads.graphBucket(tree);
+    const cached = await downloads.read(scope, bucket, key, 8388608);
+    const page = cached
+      ? JSON.parse(cached.toString('utf8'))
+      : await client.get('resources', query);
+    if (
+      page.scope !== scope ||
+      page.collection !== collection ||
+      page.epoch !== tree.epoch ||
+      page.checkpoint !== tree.checkpoint ||
+      !Array.isArray(page.items) ||
+      page.items.length > 50 ||
+      !Array.isArray(page.omittedIds) ||
+      page.omittedIds.length
+    ) {
+      fail('incomplete_documentation', 'The Graph inventory is incomplete.');
+    }
+    for (const item of page.items) {
+      const record = parse(recordSchema, item);
+      if (records.has(record.id)) {
+        fail('invalid_response', 'The Graph inventory repeated an item.');
+      }
+      records.set(record.id, record);
+    }
+    if (!cached) {
+      await downloads.put(scope, bucket, key, Buffer.from(JSON.stringify(page)));
+    }
+    if (!page.nextAfter) {
+      if (!page.changeCursor) {
+        fail('invalid_response', 'The Graph inventory has no incremental cursor.');
+      }
+      return { items: [...records.values()], cursor: page.changeCursor };
+    }
+    if (page.nextAfter === after || page.nextAfter !== page.items.at(-1)?.id) {
+      fail('invalid_response', 'The Graph inventory cursor did not advance.');
+    }
+    after = page.nextAfter;
+  }
+  fail('documentation_capacity', 'The Graph inventory exceeds its request budget.');
+}
+
+export async function exportGraph(client, store, source, tree, previous, state, assets, downloads) {
+  if (!source.graph) {
+    return;
+  }
+  const file = `${source.scope.replace(':', '-')}/graph.json`;
+  const oldBytes =
+    previous?.graph && equivalentAccess(previous, tree)
+      ? await store.readPrevious(previous.graph.file)
+      : null;
+  const oldIndex = oldBytes ? JSON.parse(oldBytes.toString('utf8')) : null;
+  let old = oldIndex;
+  if (oldIndex?.formatVersion === 2) {
+    old = { nodes: [], edges: [] };
+    for (const collection of ['nodes', 'edges']) {
+      const chunks = oldIndex.chunks?.[collection];
+      if (!Array.isArray(chunks) || chunks.length > 300) {
+        fail('invalid_documentation_manifest', 'The Graph chunk index is invalid.');
+      }
+      for (const path of chunks) {
+        const bytes = await store.readPrevious(path);
+        if (!bytes) {
+          fail('invalid_documentation_manifest', 'A tracked Graph chunk is missing.');
+        }
+        const chunk = JSON.parse(bytes.toString('utf8'));
+        if (!Array.isArray(chunk) || chunk.length > 100) {
+          fail('invalid_documentation_manifest', 'A Graph chunk exceeds its bound.');
+        }
+        old[collection].push(...chunk.map((record) => parse(recordSchema, record)));
+      }
+    }
+  }
+  const nodes = await graphCollection(
+    client,
+    source.scope,
+    'nodes',
+    tree,
+    old?.nodes,
+    old && previous.graph.nodesCursor,
+    downloads,
+  );
+  const edges = await graphCollection(
+    client,
+    source.scope,
+    'edges',
+    tree,
+    old?.edges,
+    old && previous.graph.edgesCursor,
+    downloads,
+  );
+  if (nodes.items.length > 10000 || edges.items.length > 30000) {
+    fail('documentation_capacity', 'The Graph exceeds its source capacity.');
+  }
+  const ids = new Set(nodes.items.map((node) => node.id));
+  if (edges.items.some((edge) => !ids.has(edge.data.source) || !ids.has(edge.data.target))) {
+    fail(
+      'read_context_changed',
+      'The Graph has missing endpoints; refresh its source before exporting.',
+    );
+  }
+  for (const node of nodes.items) {
+    if (node.data.imageAssetId) {
+      assets.add(parse(id, node.data.imageAssetId));
+    }
+  }
+  // Bounded portable chunks keep large Graphs out of one enormous JSON/Markdown
+  // file. Borrowed references remain identities, never cached source bodies.
+  const notice =
+    '> Automatically generated from GeniusTasker. Edit through the [MCP](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/DOCUMENTATION_SYNC.md), then sync again.';
+  const footer = `Source scope: \`${source.scope}\` · Epoch: \`${tree.epoch}\` · Checkpoint: \`${tree.checkpoint}\``;
+  const overview = [
+    notice,
+    '',
+    `# ${escape(tree.title)} — Graph`,
+    '',
+    'Linked Memory content is resolved online with current permissions. These files preserve this Graph’s own notes and qualified relations.',
+    '',
+  ];
+  const chunks = { nodes: [], edges: [] };
+  for (const [collection, records] of [
+    ['nodes', nodes.items],
+    ['edges', edges.items],
+  ]) {
+    records.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    for (let offset = 0; offset < records.length; offset += 100) {
+      const part = records.slice(offset, offset + 100),
+        name = `graph/${collection}-${String(offset / 100).padStart(4, '0')}`;
+      const path = `${source.scope.replace(':', '-')}/${name}`;
+      chunks[collection].push(path + '.json');
+      await store.put(path + '.json', JSON.stringify(part, null, 2) + '\n');
+      const text = [
+        notice,
+        '',
+        `# ${collection === 'nodes' ? 'Nodes' : 'Relations'} ${offset + 1}–${offset + part.length}`,
+        '',
+      ];
+      for (const record of part) {
+        if (collection === 'nodes') {
+          text.push(
+            `## ${escape(record.data.title ?? record.id)}`,
+            '',
+            String(record.data.text ?? record.data.summary ?? ''),
+            '',
+          );
+          for (const ref of record.data.references ?? []) {
+            text.push(
+              `- Memory reference: \`${escape(ref.scope)}\` / \`${escape(ref.pageId)}\`${ref.blockId ? ' / `' + escape(ref.blockId) + '`' : ''} (resolve current access)`,
+            );
+          }
+        } else {
+          text.push(
+            `## ${escape(record.data.label || record.data.relation)}`,
+            '',
+            `\`${escape(record.data.source)}\` → \`${escape(record.data.target)}\` · ${escape(record.data.certainty)}`,
+            '',
+            String(record.data.note ?? ''),
+            '',
+          );
+        }
+        text.push(
+          `Source ID: \`${record.id}\` · Revision: \`${record.revision}\` · Updated: ${escape(record.data.updated ?? 'unknown')} · Author: ${escape(record.data.lastEditor ?? record.data.creator ?? 'unknown')}`,
+          '',
+        );
+      }
+      text.push('', '---', '', footer, '');
+      await store.put(path + '.md', text.join('\n'));
+      overview.push(
+        `- [${collection === 'nodes' ? 'Nodes' : 'Relations'} ${offset + 1}–${offset + part.length}](${name}.md) · [JSON](${name}.json)`,
+      );
+    }
+  }
+  overview.push('', '---', '', footer, '');
+  await store.put(file.replace('.json', '.md'), overview.join('\n'));
+  await store.put(
+    file,
+    JSON.stringify(
+      {
+        formatVersion: 2,
+        scope: source.scope,
+        epoch: tree.epoch,
+        counts: { nodes: nodes.items.length, edges: edges.items.length },
+        chunks,
+        referencePolicy:
+          'Resolve linked Memory content online with current access. Unavailable targets do not remove nodes.',
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+  state.graph = { file, nodesCursor: nodes.cursor, edgesCursor: edges.cursor };
+}