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

package/src/client.mjs

@@ -1,34 +1,87 @@
 import { fail } from './errors.mjs';
 
+/** Validate a token response before it can replace an origin-bound local session. */
 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 };
+  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,
+  };
 }
 
+/**
+ * Shared delegated client for CLI and MCP operations.
+ * Renewal and profile selection serialize on the context lock; domain writes
+ * use CommandJournal so their identity and immutable request survive failures.
+ */
 export class AgentClient {
-  constructor(transport, store) { this.transport = transport; this.store = store; }
+  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.' });
+    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.');
+    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;
+      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);
   }
@@ -39,36 +92,88 @@ export class AgentClient {
     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) } : {}) });
+      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)) {
+      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.';
+        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)
+    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.' });
+      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 };
+      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 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.');
+    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.
@@ -76,20 +181,32 @@ export class AgentClient {
   }
   async logout() {
     return this.store.locked(async () => {
-      if (!await this.store.read()) return { connected: false, alreadyDisconnected: true };
+      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.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),
+    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.' };
+      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/commands.mjs

@@ -7,102 +7,250 @@ 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 === '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 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;
+    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 +258,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;
 }