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

package/src/commands.mjs

@@ -7,102 +7,263 @@ 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).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).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 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 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.');
+  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 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 (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.');
+  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 (
+    command.kind === 'memory.create' &&
+    (!/^[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 Memory with a UUID v4 as id, the same initial epoch, and scope memory:<id>. 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.' }; }
+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.');
+  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 32 KiB.');
-    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 32 KiB.');
+    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;
+    if (error instanceof AgentError) {
+      throw error;
+    }
     fail('invalid_arguments', 'Could not read a regular, valid JSON command file.');
-  } finally { await handle?.close(); }
+  } 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();
+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; }
+  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 });
+    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);
+    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 } : {}) };
+    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);
+    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);
+      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 };
+      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.' });
+        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 });
+        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(() => {});
@@ -110,5 +271,7 @@ export class CommandJournal {
       }
     }, this.client.transport.signal);
   }
-  async retry(id) { return this.execute((await this.inspect(id)).request); }
+  async retry(id) {
+    return this.execute((await this.inspect(id)).request);
+  }
 }

package/src/errors.mjs

@@ -1,22 +1,65 @@
 /** Never forward raw network exceptions: URLs, HTML and provider diagnostics
  * can contain credentials. API messages are data, never terminal control. */
 export class AgentError extends Error {
-  constructor(code, message, { status = 0, retryable = false, remediation = 'Check help and retry.', ...details } = {}) {
-    super(message); this.code = code; this.status = status; this.retryable = retryable;
-    this.remediation = remediation; this.details = details;
+  constructor(
+    code,
+    message,
+    { status = 0, retryable = false, remediation = 'Check help and retry.', ...details } = {},
+  ) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.retryable = retryable;
+    this.remediation = remediation;
+    this.details = details;
+  }
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+      remediation: this.remediation,
+      ...this.details,
+    };
   }
-  toJSON() { return { code: this.code, message: this.message, retryable: this.retryable, remediation: this.remediation, ...this.details }; }
 }
-export const fail = (code, message, options) => { throw new AgentError(code, message, options); };
+export const fail = (code, message, options) => {
+  throw new AgentError(code, message, options);
+};
 export function safeError(error) {
-  return error instanceof AgentError ? error : new AgentError('internal_error', 'The command could not complete.', { remediation: 'Retry once; run doctor if the problem persists.' });
+  return error instanceof AgentError
+    ? error
+    : new AgentError('internal_error', 'The command could not complete.', {
+        remediation: 'Retry once; run doctor if the problem persists.',
+      });
 }
 export function exitCode(error) {
-  if (['invalid_arguments', 'invalid_origin'].includes(error.code)) return 2;
-  if (error.status === 401 || ['not_authenticated', 'reauthentication_required', 'access_denied', 'expired_token', 'invalid_grant'].includes(error.code)) return 3;
-  if (error.status === 403 || error.code === 'profile_selection_denied') return 4;
-  if (error.status === 409 || error.code === 'profile_selection_conflict') return 5;
-  if (error.status === 429) return 6;
-  if (error.retryable) return 7;
+  if (['invalid_arguments', 'invalid_origin'].includes(error.code)) {
+    return 2;
+  }
+  if (
+    error.status === 401 ||
+    [
+      'not_authenticated',
+      'reauthentication_required',
+      'access_denied',
+      'expired_token',
+      'invalid_grant',
+    ].includes(error.code)
+  ) {
+    return 3;
+  }
+  if (error.status === 403 || error.code === 'profile_selection_denied') {
+    return 4;
+  }
+  if (error.status === 409 || error.code === 'profile_selection_conflict') {
+    return 5;
+  }
+  if (error.status === 429) {
+    return 6;
+  }
+  if (error.retryable) {
+    return 7;
+  }
   return 1;
 }

package/src/knowledge.mjs

@@ -0,0 +1,109 @@
+import * as z from 'zod/v4';
+import { fail } from './errors.mjs';
+
+const id = z.string().regex(/^[a-zA-Z0-9_-]{1,128}$/);
+const scope = z.string().regex(/^memory:[a-zA-Z0-9_-]{1,128}$/);
+const cursor = {
+  epoch: z.string().min(1).max(128).optional(),
+  checkpoint: z
+    .string()
+    .regex(/^(0|[1-9][0-9]*)$/)
+    .max(32)
+    .optional(),
+};
+export const searchSchema = z
+  .object({
+    scope,
+    query: z.string().trim().min(1).max(200),
+    collection: z.enum(['pages', 'nodes']).optional(),
+    after: id.optional(),
+    ...cursor,
+  })
+  .strict()
+  .refine((value) => !value.after || !!(value.epoch && value.checkpoint), {
+    message: 'Continuation needs epoch and checkpoint.',
+  });
+export const graphSchema = z
+  .object({ scope, center: id, depth: z.number().int().min(0).max(3).optional(), ...cursor })
+  .strict();
+export const referenceSchema = z
+  .object({
+    scope,
+    pageId: id,
+    blockId: z
+      .string()
+      .regex(/^[a-zA-Z0-9_-]{1,80}$/)
+      .optional(),
+  })
+  .strict();
+
+function input(schema, value) {
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) {
+    fail(
+      'invalid_arguments',
+      'Use a memory scope and the documented search, Graph or reference parameters.',
+    );
+  }
+  return parsed.data;
+}
+
+/** Query one bounded page without following cursors or retrying automatically. */
+export async function searchMemory(client, value) {
+  const query = input(searchSchema, value);
+  const result = await client.get('knowledge', { ...query, mode: 'search' });
+  if (
+    result?.scope !== query.scope ||
+    result.mode !== 'search' ||
+    !Array.isArray(result.items) ||
+    result.items.length > 25
+  ) {
+    fail('invalid_response', 'The search response does not match the requested scope.');
+  }
+  return result;
+}
+
+/** Read a compact neighborhood; full node text remains a separate resource read. */
+export async function exploreGraph(client, value) {
+  const query = input(graphSchema, value);
+  const result = await client.get('knowledge', { ...query, mode: 'graph' });
+  if (
+    result?.scope !== query.scope ||
+    result.mode !== 'graph' ||
+    !Array.isArray(result.nodes) ||
+    !Array.isArray(result.edges) ||
+    result.nodes.length > 80 ||
+    result.edges.length > 160
+  ) {
+    fail('invalid_response', 'The Graph response does not match the requested scope or bounds.');
+  }
+  const ids = new Set(result.nodes.map((node) => node.id));
+  if (
+    !ids.has(query.center) ||
+    result.edges.some((edge) => !ids.has(edge.data?.source) || !ids.has(edge.data?.target))
+  ) {
+    fail('invalid_response', 'The Graph response contains unresolved endpoints.');
+  }
+  return result;
+}
+
+/** Linked content is never persisted by this client. Resolve again after access
+ * changes; unavailable content must not delete the user's node or relations. */
+export async function resolveMemory(client, value) {
+  const query = input(referenceSchema, value);
+  const result = await client.get('reference', query);
+  if (
+    result?.scope !== query.scope ||
+    result.pageId !== query.pageId ||
+    result.blockId !== (query.blockId ?? null) ||
+    !['available', 'unavailable', 'missing'].includes(result.status) ||
+    (result.status === 'available' ? result.page?.id !== query.pageId : result.page !== null) ||
+    (result.status === 'unavailable' && (result.epoch !== null || result.accessRevision !== null))
+  ) {
+    fail(
+      'invalid_response',
+      'The reference response does not match the requested target or current access.',
+    );
+  }
+  return result;
+}