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

package/src/client.mjs

@@ -0,0 +1,95 @@
+import { fail } from './errors.mjs';
+
+export function credentials(result, origin, now = Date.now()) {
+  const token = (value, kind) => typeof value === 'string' && new RegExp(`^gta1\\.[a-f0-9]{64}\\.wd${kind}_[A-Za-z0-9_-]{43}$`).test(value);
+  if (!token(result?.access_token, 'a') || !token(result?.refresh_token, 'r') || result.token_type !== 'Bearer' ||
+      !Number.isSafeInteger(result.expires_in) || result.expires_in < 1 || result.expires_in > 3600 ||
+      ['connection_id', 'profile_id', 'session_id'].some(key => typeof result[key] !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(result[key])))
+    fail('invalid_response', 'The authorization response was invalid.', { remediation: 'Revoke the new session in Account → Agents and retry login.' });
+  return { formatVersion: 1, origin, clientId: 'geniustasker-cli',
+    access_token: result.access_token, refresh_token: result.refresh_token, token_type: 'Bearer', expires_in: result.expires_in,
+    connection_id: result.connection_id, profile_id: result.profile_id, session_id: result.session_id,
+    expiresAt: now + result.expires_in * 1000, refreshPending: false };
+}
+
+export class AgentClient {
+  constructor(transport, store) { this.transport = transport; this.store = store; }
+  async session() {
+    const session = await this.store.read();
+    if (!session) fail('not_authenticated', 'This context is not connected.', { remediation: 'Run auth login with this context and environment.' });
+    if (session.formatVersion !== 1 || session.origin !== this.transport.origin || session.clientId !== 'geniustasker-cli')
+      fail('credential_origin_mismatch', 'This context belongs to another API environment.', { remediation: 'Select its original environment, or use a different --context for the new environment.' });
+    // Validate private storage before ever sending any token to the network.
+    credentials(session, session.origin);
+    if (!Number.isSafeInteger(session.expiresAt)) fail('invalid_credential_store', 'The session expiry is invalid.');
+    return session;
+  }
+  async authorizedSession() {
+    return this.store.locked(async () => {
+      const session = await this.session();
+      if (session.refreshPending) fail('reauthentication_required', 'The previous renewal outcome is unknown.', { remediation: 'Run auth logout, then auth login. Do not replay the previous refresh token.' });
+      if (session.expiresAt > Date.now() + 30000) return session;
+      return this.renewLocked(session);
+    }, this.transport.signal);
+  }
+  /** Only called while holding the credential store lock. Selection rotates
+   * access and refresh together so an in-flight old command cannot acquire the
+   * new profile's identity. It never extends the server's absolute lifetime. */
+  async renewLocked(session, selection) {
+    await this.store.write({ ...session, refreshPending: true });
+    let result;
+    try {
+      result = await this.transport.oauth('token', { grant_type: 'refresh_token', refresh_token: session.refresh_token,
+        ...(selection ? { profile_id: selection.profileId, profile_revision: String(selection.expectedRevision), source_revision: String(selection.expectedSourceRevision) } : {}) });
+    } catch (error) {
+      // These two server outcomes happen before token consumption/rotation.
+      // Every other refusal or lost reply retains the uncertainty marker.
+      if (selection && error?.status === 400 && ['profile_selection_conflict', 'profile_selection_denied'].includes(error.code)) {
+        await this.store.write(session);
+        error.remediation = 'List profiles again. Only a human can approve broader access; a changed profile requires a fresh selection.';
+      }
+      throw error;
+    }
+    const next = credentials(result, this.transport.origin);
+    if (next.connection_id !== session.connection_id || next.profile_id !== (selection?.profileId ?? session.profile_id) || next.session_id !== session.session_id)
+      fail('invalid_response', 'Renewal returned an unexpected identity.');
+    await this.store.write(next);
+    return next;
+  }
+  async selectProfile(selection) {
+    return this.store.locked(async () => {
+      const session = await this.session();
+      if (session.refreshPending) fail('reauthentication_required', 'The previous renewal outcome is unknown.', { remediation: 'Run auth logout, then auth login; do not replay the previous refresh token.' });
+      if (selection.sourceProfileId !== session.profile_id || selection.connectionId !== session.connection_id)
+        fail('profile_selection_conflict', 'Another process changed this context.', { status: 409, remediation: 'Read profiles again. Use separate --context names for independent terminals.' });
+      const next = await this.renewLocked(session, selection);
+      return { connected: true, connectionId: next.connection_id, profileId: next.profile_id, sessionId: next.session_id };
+    }, this.transport.signal);
+  }
+  async accessToken() { return (await this.authorizedSession()).access_token; }
+  async get(resource, query) {
+    if (!['me', 'capabilities', 'projects', 'memories', 'resources', 'profiles', 'answers', 'changes'].includes(resource)) fail('invalid_arguments', 'Unknown delegated resource.');
+    const token = await this.accessToken();
+    // No blanket retries, no automatic writes. Revocation and ACL errors remain
+    // visible to the agent. A caller chooses how to recover using the envelope.
+    return this.transport.request(`/api/agents/v1/${resource}`, { token, query });
+  }
+  async logout() {
+    return this.store.locked(async () => {
+      if (!await this.store.read()) return { connected: false, alreadyDisconnected: true };
+      const session = await this.session();
+      // Keep credentials on failure so revocation can be retried. A used refresh
+      // token can revoke a family whose rotation response was lost.
+      await this.transport.oauth('revoke', { token: session.refresh_token, token_type_hint: 'refresh_token' });
+      await this.store.remove();
+      return { connected: false, revoked: true };
+    }, this.transport.signal);
+  }
+  async doctor() {
+    const session = await this.store.read();
+    return { node: process.versions.node, origin: this.transport.origin, connectedLocally: Boolean(session),
+      sameEnvironment: session ? session.origin === this.transport.origin : null,
+      needsLogin: session ? session.refreshPending === true : true, storage: 'private OS-user file',
+      publication: 'CLI installation does not grant service access; this beta requires an admitted account.', writes: 'Discover server capabilities before attempting changes.' };
+  }
+}

package/src/command-catalog.mjs

@@ -0,0 +1,287 @@
+// Generated from contracts/agents.tsp. Do not edit by hand.
+export default {
+  "maxCommandBytes": 32768,
+  "commands": {
+    "approval.cancel": {
+      "fields": [
+        "requestVersion"
+      ],
+      "module": "Project/ProjectTaskComment",
+      "permission": "approvals:write"
+    },
+    "approval.consume": {
+      "fields": [
+        "requestVersion",
+        "actionJson"
+      ],
+      "module": "Project/ProjectTaskComment",
+      "permission": "approvals:write"
+    },
+    "approval.request": {
+      "create": true,
+      "fields": [
+        "task",
+        "taskRevision",
+        "title",
+        "summary",
+        "actionJson",
+        "approver",
+        "expiresAt"
+      ],
+      "module": "Project/ProjectTaskComment",
+      "permission": "approvals:write"
+    },
+    "comment.create": {
+      "create": true,
+      "fields": [
+        "task",
+        "text",
+        "mentions"
+      ],
+      "module": "Project/ProjectTaskComment",
+      "permission": "comments:write"
+    },
+    "comment.delete": {
+      "delete": true,
+      "fields": [],
+      "module": "Project/ProjectTaskComment",
+      "permission": "comments:write"
+    },
+    "comment.update": {
+      "fields": [
+        "text",
+        "mentions"
+      ],
+      "module": "Project/ProjectTaskComment",
+      "permission": "comments:write"
+    },
+    "goal.create": {
+      "create": true,
+      "fields": [
+        "title",
+        "owner",
+        "isTeamOwner",
+        "period",
+        "interval",
+        "startTime",
+        "taskNumber",
+        "scheduleTaskOnly",
+        "notification",
+        "alertNotification"
+      ],
+      "module": "Project/ProjectMemberGoals",
+      "permission": "goals:write"
+    },
+    "goal.delete": {
+      "delete": true,
+      "fields": [],
+      "module": "Project/ProjectMemberGoals",
+      "permission": "goals:write"
+    },
+    "goal.update": {
+      "fields": [
+        "title",
+        "owner",
+        "isTeamOwner",
+        "period",
+        "interval",
+        "startTime",
+        "taskNumber",
+        "scheduleTaskOnly",
+        "notification",
+        "alertNotification"
+      ],
+      "module": "Project/ProjectMemberGoals",
+      "permission": "goals:write"
+    },
+    "memory.create": {
+      "create": true,
+      "fields": [
+        "title",
+        "productKey",
+        "summary",
+        "instructions",
+        "color"
+      ],
+      "module": "Memory/$",
+      "permission": "memory:write"
+    },
+    "memory.delete": {
+      "delete": true,
+      "fields": [],
+      "module": "Memory/$",
+      "permission": "memory:write"
+    },
+    "memory.page.create": {
+      "create": true,
+      "fields": [
+        "title",
+        "path",
+        "summary",
+        "blocks",
+        "tags",
+        "provenance"
+      ],
+      "module": "Memory/MemoryPage",
+      "permission": "memory:write"
+    },
+    "memory.page.delete": {
+      "delete": true,
+      "fields": [],
+      "module": "Memory/MemoryPage",
+      "permission": "memory:write"
+    },
+    "memory.page.update": {
+      "fields": [
+        "title",
+        "path",
+        "summary",
+        "blocks",
+        "tags",
+        "provenance"
+      ],
+      "module": "Memory/MemoryPage",
+      "permission": "memory:write"
+    },
+    "memory.update": {
+      "fields": [
+        "title",
+        "productKey",
+        "summary",
+        "instructions",
+        "color"
+      ],
+      "module": "Memory/$",
+      "permission": "memory:write"
+    },
+    "question.close": {
+      "fields": [],
+      "module": "Project/ProjectVote",
+      "permission": "questions:write"
+    },
+    "question.create": {
+      "create": true,
+      "fields": [
+        "task",
+        "question",
+        "description",
+        "answerKind",
+        "options",
+        "selection",
+        "anonymous",
+        "eligibleUsers",
+        "closesAt"
+      ],
+      "module": "$private/VoteDraft",
+      "permission": "questions:write"
+    },
+    "task.archive": {
+      "fields": [],
+      "module": "Project/ProjectTask",
+      "permission": "tasks:write"
+    },
+    "task.create": {
+      "create": true,
+      "fields": [
+        "title",
+        "description",
+        "type",
+        "owner",
+        "status",
+        "enableDueDate",
+        "dueDate",
+        "estimateDays",
+        "quantity",
+        "quantityUnit",
+        "autoArchive",
+        "autoArchiveDays",
+        "autoArchiveHours",
+        "dependencies",
+        "tags"
+      ],
+      "module": "Project/ProjectTask",
+      "permission": "tasks:write"
+    },
+    "task.report": {
+      "fields": [
+        "phase",
+        "summary",
+        "nextSteps",
+        "evidence",
+        "mentions"
+      ],
+      "module": "Project/ProjectTask",
+      "permission": "tasks:write"
+    },
+    "task.restore": {
+      "fields": [],
+      "module": "Project/ProjectTask",
+      "permission": "tasks:write"
+    },
+    "task.update": {
+      "fields": [
+        "title",
+        "description",
+        "type",
+        "owner",
+        "status",
+        "enableDueDate",
+        "dueDate",
+        "estimateDays",
+        "quantity",
+        "quantityUnit",
+        "autoArchive",
+        "autoArchiveDays",
+        "autoArchiveHours",
+        "dependencies",
+        "tags"
+      ],
+      "module": "Project/ProjectTask",
+      "permission": "tasks:write"
+    },
+    "ticket.create": {
+      "create": true,
+      "fields": [
+        "title",
+        "description",
+        "kind",
+        "placement",
+        "sprint",
+        "parent",
+        "details",
+        "planning"
+      ],
+      "module": "Project/ProjectTask",
+      "permission": "tasks:write"
+    },
+    "ticket.plan": {
+      "fields": [
+        "changes"
+      ],
+      "module": "Project/$",
+      "permission": "tasks:write"
+    }
+  },
+  "changes": {
+    "pollIntervalSeconds": 5,
+    "maxWatchSeconds": 60
+  },
+  "grants": {
+    "permissions": [
+      "projects:read",
+      "tasks:read",
+      "tasks:write",
+      "comments:write",
+      "questions:write",
+      "approvals:write",
+      "goals:read",
+      "goals:write",
+      "memory:read",
+      "memory:write",
+      "media:read",
+      "media:write"
+    ],
+    "maxResources": 200,
+    "maxProfilesPerConnection": 20
+  }
+};

package/src/commands.mjs

@@ -0,0 +1,114 @@
+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).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 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;
+};
+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 (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 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 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.');
+    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/errors.mjs

@@ -0,0 +1,22 @@
+/** 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;
+  }
+  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 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.' });
+}
+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;
+  return 1;
+}

package/src/login.mjs

@@ -0,0 +1,115 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { setTimeout as delay } from 'node:timers/promises';
+import { credentials } from './client.mjs';
+import { fail, AgentError } from './errors.mjs';
+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>`);
+}
+
+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.' }); }
+      fail('credential_save_failed', 'Local storage failed. The new server session was revoked.');
+    }
+    return loginResult(session);
+  }, client.transport.signal);
+}
+
+/** 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)))
+    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 } = {}) {
+  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)
+      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 });
+    await openBrowser?.(url);
+    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; }
+        // 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.' });
+  });
+}
+
+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; });
+    // 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('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; }
+      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 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);
+    });
+    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); });
+      redirect = `http://127.0.0.1:${server.address().port}/callback`;
+      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();
+      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();
+      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 });
+    } finally {
+      clearTimeout(timer); client.transport.signal?.removeEventListener('abort', abort);
+      server.closeAllConnections(); await new Promise(resolve => server.close(resolve));
+    }
+  });
+}