@pulsarinteractive/geniustasker 0.1.0-beta.1 → 0.1.0-beta.10

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

package/src/login.mjs

@@ -8,21 +8,47 @@ import { CLIENT_ID, ORIGINS } from './transport.mjs';
 // Fixed copy only: callback codes, state and private account data never enter HTML.
 function callbackPage(response, approved) {
   response.setHeader('Content-Type', 'text/html; charset=utf-8');
-  response.setHeader('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'");
-  response.end(`<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="light dark"><title>GeniusTasker · ${approved ? 'Authorization received' : 'Access declined'}</title><style>:root{font-family:system-ui,sans-serif;color:#18232b;background:#f4f6f7}body{margin:0;padding:80px 20px}main{max-width:440px;margin:auto;padding:36px;border:1px solid #d5dde2;border-radius:22px;background:#fff}b{color:#6139d7;font-size:14px}h1{font-size:26px;line-height:1.3;margin:28px 0 12px;letter-spacing:-.6px}p{font-size:15px;line-height:1.7;color:#52616b}small{display:block;margin-top:28px;color:#52616b}@media(prefers-color-scheme:dark){:root{background:#080b10;color:#edf1f3}main{background:#12171f;border-color:#303b47}p,small{color:#a7b3bd}b{color:#b19aff}}</style><main><b>GeniusTasker</b><h1>${approved ? 'Authorization received.' : 'Access declined.'}</h1><p>${approved ? 'Return to your terminal. It is securely completing the connection with the access you chose.' : 'This request has no access to your account. You can return to your terminal.'}</p><small>You can close this tab.</small></main></html>`);
+  response.setHeader(
+    'Content-Security-Policy',
+    "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
+  );
+  response.end(
+    `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="light dark"><title>GeniusTasker · ${approved ? 'Authorization received' : 'Access declined'}</title><style>:root{font-family:system-ui,sans-serif;color:#18232b;background:#f4f6f7}body{margin:0;padding:80px 20px}main{max-width:440px;margin:auto;padding:36px;border:1px solid #d5dde2;border-radius:22px;background:#fff}b{color:#6139d7;font-size:14px}h1{font-size:26px;line-height:1.3;margin:28px 0 12px;letter-spacing:-.6px}p{font-size:15px;line-height:1.7;color:#52616b}small{display:block;margin-top:28px;color:#52616b}@media(prefers-color-scheme:dark){:root{background:#080b10;color:#edf1f3}main{background:#12171f;border-color:#303b47}p,small{color:#a7b3bd}b{color:#b19aff}}</style><main><b>GeniusTasker</b><h1>${approved ? 'Authorization received.' : 'Access declined.'}</h1><p>${approved ? 'Return to your terminal. It is securely completing the connection with the access you chose.' : 'This request has no access to your account. You can return to your terminal.'}</p><small>You can close this tab.</small></main></html>`,
+  );
 }
 
-function loginResult(session) { return { connected: true, origin: session.origin, connectionId: session.connection_id, profileId: session.profile_id, sessionId: session.session_id }; }
+function loginResult(session) {
+  return {
+    connected: true,
+    origin: session.origin,
+    connectionId: session.connection_id,
+    profileId: session.profile_id,
+    sessionId: session.session_id,
+  };
+}
 async function saveLogin(client, exchange) {
   // Hold the context lock throughout consent so two terminals cannot overwrite
   // independent connections and leave an inaccessible active session behind.
   return client.store.locked(async () => {
-    if (await client.store.read()) fail('already_authenticated', 'This context already has a session.', { remediation: 'Run auth logout first, or choose another --context.' });
-    const result = await exchange(); const session = credentials(result, client.transport.origin);
-    try { await client.store.write(session); }
-    catch {
-      try { await client.transport.oauth('revoke', { token: session.refresh_token }); }
-      catch { fail('credential_save_failed', 'Login succeeded but local storage failed; server revocation could not be confirmed.', { remediation: 'Revoke the new connection in Account → Agents before trying again.' }); }
+    if (await client.store.read()) {
+      fail('already_authenticated', 'This context already has a session.', {
+        remediation: 'Run auth logout first, or choose another --context.',
+      });
+    }
+    const result = await exchange();
+    const session = credentials(result, client.transport.origin);
+    try {
+      await client.store.write(session);
+    } catch {
+      try {
+        await client.transport.oauth('revoke', { token: session.refresh_token });
+      } catch {
+        fail(
+          'credential_save_failed',
+          'Login succeeded but local storage failed; server revocation could not be confirmed.',
+          { remediation: 'Revoke the new connection in Account → Agents before trying again.' },
+        );
+      }
       fail('credential_save_failed', 'Local storage failed. The new server session was revoked.');
     }
     return loginResult(session);
@@ -32,84 +58,201 @@ async function saveLogin(client, exchange) {
 /** Consent URLs are server data. Restrict automatic navigation to the product
  * app paired with this API (or the explicitly opted-in local development app). */
 export function consentUrl(value, origin) {
-  let url; try { url = new URL(value); } catch { fail('invalid_response', 'Invalid consent URL.'); }
-  const expected = origin === ORIGINS.production ? 'https://app-geniustasker.pulsarinteractive.cloud' :
-    origin === ORIGINS.development ? 'https://dev-app-geniustasker.pulsarinteractive.cloud' : null;
-  if (url.username || url.password || url.hash || url.pathname !== '/agents/connect' ||
-      (expected ? url.origin !== expected : url.protocol !== 'http:' || !['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)))
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    fail('invalid_response', 'Invalid consent URL.');
+  }
+  const expected =
+    origin === ORIGINS.production
+      ? 'https://app-geniustasker.pulsarinteractive.cloud'
+      : origin === ORIGINS.development
+        ? 'https://dev-app-geniustasker.pulsarinteractive.cloud'
+        : null;
+  if (
+    url.username ||
+    url.password ||
+    url.hash ||
+    url.pathname !== '/agents/connect' ||
+    (expected
+      ? url.origin !== expected
+      : url.protocol !== 'http:' || !['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname))
+  ) {
     fail('invalid_response', 'The consent URL is not a trusted GeniusTasker application.');
+  }
   return url.href;
 }
 
-export function deviceLogin(client, { scope, notify, openBrowser, wait = delay, now = Date.now } = {}) {
+/**
+ * Complete device consent within the server's expiry and polling bounds.
+ * The context lock covers the full exchange; credentials are saved only after
+ * a validated response. notify/openBrowser are presentation callbacks.
+ */
+export function deviceLogin(
+  client,
+  { scope, notify, openBrowser, wait = delay, now = Date.now } = {},
+) {
   return saveLogin(client, async () => {
     const startedAt = now();
     const device = await client.transport.oauth('device', scope ? { scope } : {});
-    if (!device || typeof device.device_code !== 'string' || device.device_code.length > 256 ||
-        !/^[0-9A-F]{2}-[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}$/.test(device.user_code) ||
-        !Number.isSafeInteger(device.expires_in) || device.expires_in < 1 || device.expires_in > 900 ||
-        !Number.isSafeInteger(device.interval) || device.interval < 1 || device.interval > 60)
+    if (
+      !device ||
+      typeof device.device_code !== 'string' ||
+      device.device_code.length > 256 ||
+      !/^[0-9A-F]{2}-[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}$/.test(device.user_code) ||
+      !Number.isSafeInteger(device.expires_in) ||
+      device.expires_in < 1 ||
+      device.expires_in > 900 ||
+      !Number.isSafeInteger(device.interval) ||
+      device.interval < 1 ||
+      device.interval > 60
+    ) {
       fail('invalid_response', 'The device authorization response was invalid.');
+    }
     const url = consentUrl(device.verification_uri_complete, client.transport.origin);
-    notify?.({ event: 'consent_required', url, userCode: device.user_code, expiresIn: device.expires_in });
+    notify?.({
+      event: 'consent_required',
+      url,
+      userCode: device.user_code,
+      expiresIn: device.expires_in,
+    });
     await openBrowser?.(url);
-    const deadline = startedAt + device.expires_in * 1000; let interval = device.interval;
+    const deadline = startedAt + device.expires_in * 1000;
+    let interval = device.interval;
     while (now() + interval * 1000 < deadline) {
       await wait(interval * 1000, undefined, { signal: client.transport.signal });
-      try { return await client.transport.oauth('token', { grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: device.device_code }); }
-      catch (error) {
-        if (!(error instanceof AgentError)) throw error;
-        if (error.code === 'authorization_pending') continue;
-        if (error.code === 'slow_down') { interval = Math.max(interval + 5, error.details.interval ?? 0); continue; }
+      try {
+        return await client.transport.oauth('token', {
+          grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+          device_code: device.device_code,
+        });
+      } catch (error) {
+        if (!(error instanceof AgentError)) {
+          throw error;
+        }
+        if (error.code === 'authorization_pending') {
+          continue;
+        }
+        if (error.code === 'slow_down') {
+          interval = Math.max(interval + 5, error.details.interval ?? 0);
+          continue;
+        }
         // Rate limits are explicit; no endless polling or accidental login loop.
         throw error;
       }
     }
-    fail('expired_token', 'The authorization request expired.', { remediation: 'Start auth login again and confirm it in the application.' });
+    fail('expired_token', 'The authorization request expired.', {
+      remediation: 'Start auth login again and confirm it in the application.',
+    });
   });
 }
 
+/**
+ * Complete browser PKCE consent through one validated loopback callback.
+ * The ephemeral listener closes on success, denial, cancellation or expiry.
+ * Authentication codes and tokens never enter the callback's HTML response.
+ */
 export function browserLogin(client, { scope, notify, openBrowser, lifetimeMs = 600000 } = {}) {
   return saveLogin(client, async () => {
-    const verifier = randomBytes(48).toString('base64url'), state = randomBytes(32).toString('base64url');
-    let resolveCode, rejectCode, used = false, redirect;
-    const codePromise = new Promise((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
+    const verifier = randomBytes(48).toString('base64url'),
+      state = randomBytes(32).toString('base64url');
+    let resolveCode,
+      rejectCode,
+      used = false,
+      redirect;
+    const codePromise = new Promise((resolve, reject) => {
+      resolveCode = resolve;
+      rejectCode = reject;
+    });
     // Attach immediately so abort during navigation cannot become unhandled.
     codePromise.catch(() => {});
     const server = createServer((request, response) => {
-      response.setHeader('Cache-Control', 'no-store'); response.setHeader('Referrer-Policy', 'no-referrer');
+      response.setHeader('Cache-Control', 'no-store');
+      response.setHeader('Referrer-Policy', 'no-referrer');
       response.setHeader('Content-Security-Policy', "default-src 'none'; frame-ancestors 'none'");
       response.setHeader('Content-Type', 'text/plain; charset=utf-8');
-      let url; try { url = new URL(request.url, redirect); } catch { response.writeHead(400).end('Invalid callback.'); return; }
+      let url;
+      try {
+        url = new URL(request.url, redirect);
+      } catch {
+        response.writeHead(400).end('Invalid callback.');
+        return;
+      }
       const received = url.searchParams.get('state') ?? '';
-      const validState = Buffer.byteLength(received) === Buffer.byteLength(state) && timingSafeEqual(Buffer.from(received), Buffer.from(state));
-      if (used || request.method !== 'GET' || request.headers.host !== new URL(redirect).host || url.origin !== new URL(redirect).origin || url.pathname !== '/callback' || !validState ||
-          [...url.searchParams.keys()].some(key => !['state', 'code', 'error'].includes(key) || url.searchParams.getAll(key).length !== 1)) {
-        response.writeHead(400).end('Invalid callback. Return to your terminal.'); return;
+      const validState =
+        Buffer.byteLength(received) === Buffer.byteLength(state) &&
+        timingSafeEqual(Buffer.from(received), Buffer.from(state));
+      if (
+        used ||
+        request.method !== 'GET' ||
+        request.headers.host !== new URL(redirect).host ||
+        url.origin !== new URL(redirect).origin ||
+        url.pathname !== '/callback' ||
+        !validState ||
+        [...url.searchParams.keys()].some(
+          (key) =>
+            !['state', 'code', 'error'].includes(key) || url.searchParams.getAll(key).length !== 1,
+        )
+      ) {
+        response.writeHead(400).end('Invalid callback. Return to your terminal.');
+        return;
       }
       const code = url.searchParams.get('code');
-      if (url.searchParams.has('error')) { used = true; callbackPage(response, false); rejectCode(new AgentError('access_denied', 'Connection declined.')); return; }
-      if (!code || !/^[A-Za-z0-9_.-]{1,256}$/.test(code)) { response.writeHead(400).end('Invalid callback.'); return; }
-      used = true; callbackPage(response, true); resolveCode(code);
+      if (url.searchParams.has('error')) {
+        used = true;
+        callbackPage(response, false);
+        rejectCode(new AgentError('access_denied', 'Connection declined.'));
+        return;
+      }
+      if (!code || !/^[A-Za-z0-9_.-]{1,256}$/.test(code)) {
+        response.writeHead(400).end('Invalid callback.');
+        return;
+      }
+      used = true;
+      callbackPage(response, true);
+      resolveCode(code);
     });
     const abort = () => rejectCode(new AgentError('login_cancelled', 'Login was cancelled.'));
     let timer;
     try {
-      await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+      await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+      });
       redirect = `http://127.0.0.1:${server.address().port}/callback`;
-      timer = setTimeout(() => rejectCode(new AgentError('expired_token', 'The authorization request expired.')), lifetimeMs);
+      timer = setTimeout(
+        () => rejectCode(new AgentError('expired_token', 'The authorization request expired.')),
+        lifetimeMs,
+      );
       client.transport.signal?.addEventListener('abort', abort, { once: true });
-      if (client.transport.signal?.aborted) abort();
+      if (client.transport.signal?.aborted) {
+        abort();
+      }
       const url = new URL('/api/agents/oauth/authorize', client.transport.origin);
-      url.search = new URLSearchParams({ client_id: CLIENT_ID, response_type: 'code', redirect_uri: redirect, state,
-        code_challenge_method: 'S256', code_challenge: createHash('sha256').update(verifier).digest('base64url'), ...(scope ? { scope } : {}) }).toString();
+      url.search = new URLSearchParams({
+        client_id: CLIENT_ID,
+        response_type: 'code',
+        redirect_uri: redirect,
+        state,
+        code_challenge_method: 'S256',
+        code_challenge: createHash('sha256').update(verifier).digest('base64url'),
+        ...(scope ? { scope } : {}),
+      }).toString();
       notify?.({ event: 'consent_required', url: url.href, expiresIn: lifetimeMs / 1000 });
       await openBrowser?.(url.href);
       const code = await codePromise;
-      return await client.transport.oauth('token', { grant_type: 'authorization_code', code, redirect_uri: redirect, code_verifier: verifier });
+      return await client.transport.oauth('token', {
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: redirect,
+        code_verifier: verifier,
+      });
     } finally {
-      clearTimeout(timer); client.transport.signal?.removeEventListener('abort', abort);
-      server.closeAllConnections(); await new Promise(resolve => server.close(resolve));
+      clearTimeout(timer);
+      client.transport.signal?.removeEventListener('abort', abort);
+      server.closeAllConnections();
+      await new Promise((resolve) => server.close(resolve));
     }
   });
 }