atris 3.66.0 → 3.67.0

package/README.md

@@ -173,6 +173,33 @@ No proof, no AgentXP. `atris task done --proof` records review/RL context, but
 only human `atris task accept` mints Career XP for the local card or hosted
 leaderboard.
 
+## Agents That Sign In On Their Own
+
+`atris login` signs a person in. An agent can sign itself in with an agent
+client, so no one has to hand it a login token.
+
+The owner makes the client once. The secret is shown one time, or written to a
+private file with `--secret-file`:
+
+```bash
+atris agent-client create --name nightly-bot --scopes mcp:read,x-search --secret-file ./bot.secret
+atris agent-client list
+atris agent-client rotate <client_id>
+atris agent-client revoke <client_id>
+```
+
+The agent signs in with the id and the secret file. Its short token renews on
+its own; the secret and token are never printed:
+
+```bash
+atris login --client-id atc_... --client-secret-file ./bot.secret
+```
+
+Or set `ATRIS_CLIENT_ID` plus `ATRIS_CLIENT_SECRET_FILE` (or
+`ATRIS_CLIENT_SECRET`) and run `atris login` once. It reads them, no flags
+needed, and opens no browser. After that every command renews the token on
+its own. `ATRIS_TOKEN`, when set, still wins.
+
 ## Business Owners
 
 If you want a shared owner for a company, lab, collective, community, artist, team, or project, use the business command instead of raw `atris init`.

package/bin/atris.js

@@ -717,6 +717,7 @@ function showHelpAll() {
   console.log('  balance    - Show credit balance in dollars');
   console.log('  usage      - Show developer API usage');
   console.log('  api-key    - Create, list, rotate, or revoke a developer API key');
+  console.log('  agent-client - Let an agent sign itself in: create, list, revoke, rotate (secret shown once)');
   console.log('  topup      - Buy credits and print a Stripe checkout URL');
   console.log('  buy        - Quote a purchase or stock order; the person approves before anything is charged');
   console.log('  transactions - List what you bought, paid in fees, traded, or sent');
@@ -983,7 +984,7 @@ function showReleaseHelp() {
 
 function showAuthHelp(commandName) {
   const usage = {
-    login: 'Usage: atris login [--token <token>] [--force] [--agent]',
+    login: 'Usage: atris login [--token <token>] [--force] [--agent] [--client-id <atc_...> --client-secret-file <path>]',
     logout: 'Usage: atris logout',
     whoami: 'Usage: atris whoami [--json]',
     switch: 'Usage: atris switch [account] [--global]',
@@ -997,6 +998,8 @@ function showAuthHelp(commandName) {
   if (commandName === 'login') {
     console.log('  Sign in with browser OAuth or a pasted API token.');
     console.log('  --agent mints a scoped agent token from stored credentials. No browser.');
+    console.log('  --client-id signs an agent in by itself with an agent client (see atris agent-client).');
+    console.log('  The token renews on its own; the secret is never printed.');
   } else if (commandName === 'logout') {
     console.log('  Sign out of the current Atris account.');
   } else if (commandName === 'whoami') {
@@ -1019,6 +1022,10 @@ function showAuthHelp(commandName) {
     console.log('  --commerce                Commerce key: scopes commerce:quote,transactions:read. Can quote, never pay.');
     console.log('  --commerce-max-usd <n>    Largest single quote a commerce key may ask for, 1 to 500 (default: 200).');
     console.log('  --print-key               Print the minted key once, for an agent on another machine.');
+    console.log('  --client-id <atc_...>     Sign in as an agent client (no browser, no person).');
+    console.log('  --client-secret-file <p>  File holding the agent client secret (chmod 600).');
+    console.log('  --scope "a b"             Ask for fewer scopes than the client has.');
+    console.log('  Or set ATRIS_CLIENT_ID plus ATRIS_CLIENT_SECRET_FILE or ATRIS_CLIENT_SECRET, then run atris login once.');
   } else if (commandName === 'switch') {
     console.log('  --global, -g     Switch the account for all terminals.');
   }
@@ -2395,6 +2402,11 @@ if (command === 'guide') {
   Promise.resolve(require('../commands/usage').usageCommand(process.argv.slice(3)))
     .then((code) => process.exit(typeof code === 'number' ? code : 0))
     .catch((err) => { console.error(String(err.message || err).replace(/\s+/g, ' ')); process.exit(1); });
+} else if (command === 'agent-client') {
+  // Owner side of agent self-login: create, list, revoke, rotate agent clients.
+  Promise.resolve(require('../commands/agent-client').agentClientCommand(process.argv.slice(3)))
+    .then((code) => process.exit(typeof code === 'number' ? code : 0))
+    .catch((err) => { console.error(require('../utils/agent-client').scrub(err && err.message, [])); process.exit(1); });
 } else if (command === 'api-key') {
   Promise.resolve(require('../commands/api-key').apiKeyCommand(process.argv.slice(3)))
     .then((code) => process.exit(typeof code === 'number' ? code : 0))

package/commands/agent-client.js

@@ -0,0 +1,266 @@
+'use strict';
+
+// Owner side of agent self-login. A person creates an agent client once and
+// hands its id and secret to the agent; the agent then signs itself in with
+// `atris login --client-id ... --client-secret-file ...`.
+//
+// The secret is shown exactly once, at create or rotate, or written to a
+// private file with --secret-file. It never goes to stderr or error text.
+
+const fs = require('fs');
+const path = require('path');
+const { apiRequestJson } = require('../utils/api');
+const { ensureValidCredentials, readActiveCredentials } = require('../utils/auth');
+const agentClient = require('../utils/agent-client');
+const { readFlag } = require('../lib/arg-parser');
+const { wantsJson, wantsHelp, oneLine } = require('../lib/developer-api');
+
+const BASE_PATH = '/auth/agent-clients';
+const ACTIONS = new Set(['create', 'list', 'revoke', 'rotate']);
+const VALUE_FLAGS = ['--name', '--scopes', '--daily-credit-cap', '--ttl', '--secret-file'];
+const SHOWN_ONCE = 'store this secret now, it will not be shown again:';
+const AGENT_CLIENT_CANNOT_MANAGE = 'agent clients are managed with your own login, not an agent client. run: atris switch <you> or atris login --force';
+
+function showAgentClientHelp(log = console.log) {
+  log('usage: atris agent-client create --name <name> --scopes <a,b> [--daily-credit-cap N] [--ttl SECONDS] [--secret-file <path>]');
+  log('       atris agent-client list');
+  log('       atris agent-client revoke <client_id>');
+  log('       atris agent-client rotate <client_id> [--secret-file <path>]');
+  log('');
+  log('an agent client lets an agent sign itself in, with no person in the loop.');
+  log('create and rotate show the secret once. --secret-file writes it to a private file instead.');
+  log('the agent then runs: atris login --client-id <atc_...> --client-secret-file <path>');
+  log('needs your own login. add --json for machine output.');
+}
+
+function positiveInt(raw, label) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) return { error: `${label} must be a positive whole number` };
+  return { value };
+}
+
+function parseAgentClientArgs(args = []) {
+  const positionals = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = String(args[i]);
+    if (arg === '--json') continue;
+    const valueFlag = VALUE_FLAGS.find((flag) => arg === flag || arg.startsWith(`${flag}=`));
+    if (valueFlag) {
+      if (arg === valueFlag) {
+        const next = args[i + 1];
+        if (next == null || String(next).startsWith('--')) return { error: `${valueFlag} needs a value` };
+        i += 1;
+      }
+      continue;
+    }
+    if (arg.startsWith('--')) return { error: `unknown agent-client option: ${arg}` };
+    positionals.push(arg);
+  }
+
+  const parsed = {
+    action: positionals[0] || '',
+    clientId: positionals[1] || '',
+    name: readFlag(args, '--name', ''),
+    scopes: agentClient.scopeList(readFlag(args, '--scopes', '')),
+    secretFile: readFlag(args, '--secret-file', ''),
+    dailyCreditCap: null,
+    ttlSeconds: null,
+  };
+  const cap = readFlag(args, '--daily-credit-cap', '');
+  if (cap) {
+    const checked = positiveInt(cap, '--daily-credit-cap');
+    if (checked.error) return checked;
+    parsed.dailyCreditCap = checked.value;
+  }
+  const ttl = readFlag(args, '--ttl', '');
+  if (ttl) {
+    const checked = positiveInt(ttl, '--ttl');
+    if (checked.error) return checked;
+    parsed.ttlSeconds = checked.value;
+  }
+
+  if (!ACTIONS.has(parsed.action)) return { error: 'usage: atris agent-client create|list|revoke|rotate' };
+  if (parsed.action === 'create') {
+    if (!parsed.name) return { error: 'create needs --name <name>' };
+    if (parsed.scopes.length === 0) return { error: 'create needs --scopes <a,b>' };
+  }
+  if ((parsed.action === 'revoke' || parsed.action === 'rotate') && !parsed.clientId) {
+    return { error: `usage: atris agent-client ${parsed.action} <client_id>` };
+  }
+  if (parsed.clientId && !parsed.clientId.startsWith(agentClient.CLIENT_ID_PREFIX)) {
+    return { error: `client ids start with ${agentClient.CLIENT_ID_PREFIX}` };
+  }
+  if (parsed.secretFile && parsed.action !== 'create' && parsed.action !== 'rotate') {
+    return { error: '--secret-file only works with create and rotate' };
+  }
+  return parsed;
+}
+
+// Check before calling the backend: a secret that cannot be saved is lost.
+function checkSecretFileTarget(filePath) {
+  const resolved = path.resolve(filePath);
+  try {
+    if (fs.statSync(resolved).isDirectory()) return { error: `${resolved} is a folder, not a file` };
+  } catch (error) {
+    if (error.code !== 'ENOENT') return { error: `cannot use ${resolved} (${error.code})` };
+  }
+  const dir = path.dirname(resolved);
+  try {
+    fs.accessSync(dir, fs.constants.W_OK);
+  } catch {
+    return { error: `cannot write to ${dir}` };
+  }
+  return { path: resolved };
+}
+
+function clientsFrom(data) {
+  if (Array.isArray(data)) return data;
+  if (!data || typeof data !== 'object') return [];
+  for (const key of ['clients', 'agent_clients', 'items', 'data']) {
+    if (Array.isArray(data[key])) return data[key];
+  }
+  return [];
+}
+
+function scopesText(scopes) {
+  const list = agentClient.scopeList(scopes);
+  return list.length ? list.join(', ') : 'none';
+}
+
+function listText(data) {
+  const clients = clientsFrom(data);
+  if (clients.length === 0) return 'no agent clients yet. make one: atris agent-client create --name <name> --scopes <a,b>';
+  return clients.map((client) => {
+    const parts = [client.client_id || client.id || '?', client.name || 'unnamed', `scopes: ${scopesText(client.scopes)}`];
+    if (client.revoked_at) parts.push('revoked');
+    else if (client.last_used_at) parts.push(`last used ${client.last_used_at}`);
+    return parts.join('  ');
+  }).join('\n');
+}
+
+// Everything the backend sent, minus the secret.
+function withoutSecret(data) {
+  const { client_secret, ...rest } = data && typeof data === 'object' ? data : {};
+  return rest;
+}
+
+async function agentClientCommand(args = [], deps = {}) {
+  const log = deps.log || console.log;
+  const err = deps.err || console.error;
+  if (args.length === 0 || wantsHelp(args)) {
+    showAgentClientHelp(log);
+    return args.length === 0 ? 1 : 0;
+  }
+
+  const json = wantsJson(args);
+  const fail = (message, extra = {}) => {
+    if (json) log(JSON.stringify({ ok: false, error: message, ...extra }));
+    else err(message);
+    return 1;
+  };
+
+  const parsed = parseAgentClientArgs(args);
+  if (parsed.error) return fail(parsed.error);
+
+  let secretTarget = null;
+  if (parsed.secretFile) {
+    secretTarget = checkSecretFileTarget(parsed.secretFile);
+    if (secretTarget.error) return fail(secretTarget.error);
+  }
+
+  const readActive = deps.readActiveCredentials || readActiveCredentials;
+  if (agentClient.isAgentClientCredential(readActive())) {
+    return fail(AGENT_CLIENT_CANNOT_MANAGE);
+  }
+
+  const request = deps.apiRequestJson || apiRequestJson;
+  const ensure = deps.ensureValidCredentials || ((opts) => ensureValidCredentials(request, opts));
+  const ensured = await ensure();
+  if (!ensured || ensured.error || !ensured.credentials || !ensured.credentials.token) {
+    return fail('not logged in. run: atris login');
+  }
+  if (ensured.source === agentClient.AUTH_TYPE || agentClient.isAgentClientCredential(ensured.credentials)) {
+    return fail(AGENT_CLIENT_CANNOT_MANAGE);
+  }
+  const token = ensured.credentials.token;
+
+  let result;
+  try {
+    if (parsed.action === 'list') {
+      result = await request(BASE_PATH, { method: 'GET', token });
+    } else if (parsed.action === 'create') {
+      const body = { name: parsed.name, scopes: parsed.scopes };
+      if (parsed.dailyCreditCap != null) body.daily_credit_cap = parsed.dailyCreditCap;
+      if (parsed.ttlSeconds != null) body.token_ttl_seconds = parsed.ttlSeconds;
+      result = await request(BASE_PATH, { method: 'POST', token, body, retries: 0 });
+    } else if (parsed.action === 'revoke') {
+      result = await request(`${BASE_PATH}/${encodeURIComponent(parsed.clientId)}`, { method: 'DELETE', token });
+    } else {
+      result = await request(`${BASE_PATH}/${encodeURIComponent(parsed.clientId)}/rotate-secret`, {
+        method: 'POST',
+        token,
+        retries: 0,
+      });
+    }
+  } catch (error) {
+    return fail(agentClient.scrub(error && error.message, [token]));
+  }
+
+  if (!result || !result.ok) {
+    const status = result && result.status;
+    const secret = result && result.data && result.data.client_secret;
+    const message = status === 404 && parsed.action !== 'revoke' && parsed.action !== 'rotate'
+      ? 'agent clients are not live on the server yet. try again after the backend update.'
+      : agentClient.scrub(oneLine(result && (result.data || result.error)), [token, secret]);
+    return fail(message, { status: status || 0 });
+  }
+
+  const data = result.data && typeof result.data === 'object' ? result.data : {};
+
+  if (parsed.action === 'list') {
+    if (json) log(JSON.stringify({ ok: true, clients: clientsFrom(data).map(withoutSecret) }));
+    else log(listText(data));
+    return 0;
+  }
+
+  if (parsed.action === 'revoke') {
+    if (json) log(JSON.stringify({ ok: true, client_id: parsed.clientId, revoked: true, ...withoutSecret(data) }));
+    else log(`revoked ${parsed.clientId}. its tokens stop working now.`);
+    return 0;
+  }
+
+  // create or rotate: the one moment the secret exists outside the server.
+  const secret = typeof data.client_secret === 'string' ? data.client_secret : '';
+  const clientId = data.client_id || parsed.clientId;
+  if (!secret) return fail('the server did not return a client secret');
+
+  if (secretTarget) {
+    try {
+      agentClient.writeFileAtomic(secretTarget.path, `${secret}\n`);
+    } catch (error) {
+      return fail(`could not write ${secretTarget.path}${error.code ? ` (${error.code})` : ''}. run atris agent-client rotate ${clientId} --secret-file <other path> to get a new secret.`);
+    }
+  }
+
+  if (json) {
+    const payload = { ok: true, ...withoutSecret(data), client_id: clientId };
+    if (secretTarget) payload.secret_file = secretTarget.path;
+    else payload.client_secret = secret;
+    log(JSON.stringify(payload));
+    return 0;
+  }
+
+  log(parsed.action === 'create' ? `created agent client ${data.name || parsed.name}` : `new secret for ${clientId}. the old one stops working.`);
+  log(`client id: ${clientId}`);
+  if (data.scopes) log(`scopes: ${scopesText(data.scopes)}`);
+  if (secretTarget) {
+    log(`secret saved to ${secretTarget.path} (only you can read it). it will not be shown again.`);
+  } else {
+    log(SHOWN_ONCE);
+    log(secret);
+  }
+  log(`agent sign-in: atris login --client-id ${clientId} --client-secret-file ${secretTarget ? secretTarget.path : '<file holding the secret>'}`);
+  return 0;
+}
+
+module.exports = { agentClientCommand, parseAgentClientArgs };

package/commands/auth.js

@@ -1,7 +1,8 @@
-const { AGENT_TOKEN_EXPIRED_DETAIL, decodeJwtClaims, loadCredentials, saveCredentials, deleteCredentials, getCredentialsPath, openBrowser, promptUser, displayAccountSummary, ensureValidCredentials, loadProfile, listProfiles, profileNameFromEmail, deleteProfile, saveProfile, getTokenExpiryEpochSeconds, getTerminalSessionId, setSessionProfile, getSessionProfile, clearSessionProfile, cleanStaleSessions, getSessionsDir } = require('../utils/auth');
+const { AGENT_TOKEN_EXPIRED_DETAIL, decodeJwtClaims, loadCredentials, saveCredentials, saveAgentClientCredentials, preserveAgentClientLogin, deleteCredentials, getCredentialsPath, openBrowser, promptUser, displayAccountSummary, ensureValidCredentials, loadProfile, listProfiles, profileNameFromEmail, deleteProfile, saveProfile, getTokenExpiryEpochSeconds, getTerminalSessionId, setSessionProfile, getSessionProfile, clearSessionProfile, cleanStaleSessions, getSessionsDir } = require('../utils/auth');
 const { getAppBaseUrl, apiRequestJson } = require('../utils/api');
 const { isNonInteractive, wantsJson } = require('../lib/noninteractive');
 const { hasFlag, readFlag } = require('../lib/arg-parser');
+const agentClient = require('../utils/agent-client');
 const fs = require('fs');
 const path = require('path');
 
@@ -128,7 +129,8 @@ function isAgentAccessToken(token) {
 function scopedTokenCandidate(credentials = {}) {
   if (credentials.agent_token) return credentials.agent_token;
   if (
-    credentials.source === 'env'
+    credentials.source === agentClient.AUTH_TYPE
+    || credentials.source === 'env'
     || credentials.source === 'agent_token_file'
     || isAgentAccessToken(credentials.token)
   ) {
@@ -290,11 +292,16 @@ async function ensureBilledCommandAuth(scope, deps = {}) {
   const scopes = claims?.scopes || credentials.agent_token_scopes || credentials.scopes || [];
   const expiry = claims?.exp
     ? claims.exp * 1000
-    : Date.parse(credentials.agent_token_expires_at || credentials.expires_at);
+    : Date.parse(credentials.agent_token_expires_at || credentials.expires_at || credentials.token_expires_at);
   if (!deps.forceMint && candidate && Array.isArray(scopes) && scopes.includes(wanted) && Number.isFinite(expiry) && expiry > Date.now()) {
     return { ok: true, token: candidate, minted: false, credentials };
   }
 
+  if (credentials.source === agentClient.AUTH_TYPE) {
+    // An agent client cannot mint itself more scope; the owner grants it.
+    return { ok: false, error: `this agent client does not have the ${wanted} scope. ask its owner to create one that does.` };
+  }
+
   if (!canMintFromLogin(credentials)) {
     return { ok: false, error: NO_STORED_JWT_MESSAGE };
   }
@@ -382,6 +389,26 @@ async function mintAgentToken(args = [], deps = {}) {
 
 async function printWhoamiPayload(asJson) {
   const ensured = await ensureValidCredentials(apiRequestJson);
+  if (!ensured.error && ensured.source === 'agent_client') {
+    const creds = ensured.credentials || {};
+    const payload = {
+      ok: true,
+      logged_in: true,
+      auth_type: agentClient.AUTH_TYPE,
+      client_id: creds.client_id,
+      scopes: creds.scopes || [],
+      token_expires_at: creds.token_expires_at || null,
+    };
+    if (asJson) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      console.log('Status: Logged in ✓ (agent client)');
+      console.log(`Client ID: ${payload.client_id}`);
+      console.log(`Scopes: ${payload.scopes.length ? payload.scopes.join(', ') : 'unknown'}`);
+      if (payload.token_expires_at) console.log(`Token renews before: ${payload.token_expires_at}`);
+    }
+    process.exit(0);
+  }
   if (ensured.error) {
     if (!asJson && ensured.detail === AGENT_TOKEN_EXPIRED_DETAIL) {
       console.error('the agent key expired.');
@@ -430,6 +457,144 @@ async function printWhoamiPayload(asJson) {
   process.exit(0);
 }
 
+function flagPresent(args, name) {
+  return args.some((arg) => arg === name || String(arg).startsWith(`${name}=`));
+}
+
+function envValue(env, name) {
+  return typeof env[name] === 'string' ? env[name].trim() : '';
+}
+
+// Decide whether this `atris login` is an agent client sign-in. Returns null
+// for every other login path so those stay exactly as they were.
+function agentClientLoginRequest(args = [], env = process.env) {
+  if (flagPresent(args, '--client-secret')) {
+    return { error: 'do not put the secret on the command line. use --client-secret-file <path> or ATRIS_CLIENT_SECRET.' };
+  }
+  const usesFlags = flagPresent(args, '--client-id') || flagPresent(args, '--client-secret-file');
+  const envId = envValue(env, 'ATRIS_CLIENT_ID');
+  if (!usesFlags && (!envId || flagPresent(args, '--token') || wantsAgentToken(args))) return null;
+  const clientId = readFlag(args, '--client-id', '') || envId;
+  if (!clientId) return { error: '--client-id needs a client id (atc_...)' };
+  if (!clientId.startsWith(agentClient.CLIENT_ID_PREFIX)) {
+    return { error: `client ids start with ${agentClient.CLIENT_ID_PREFIX}` };
+  }
+  const flagFile = readFlag(args, '--client-secret-file', '');
+  if (flagPresent(args, '--client-secret-file') && !flagFile) {
+    return { error: '--client-secret-file needs a path' };
+  }
+  const secretFile = flagFile || envValue(env, 'ATRIS_CLIENT_SECRET_FILE');
+  if (!secretFile && !envValue(env, 'ATRIS_CLIENT_SECRET')) {
+    return { error: 'no client secret. pass --client-secret-file <path>, or set ATRIS_CLIENT_SECRET_FILE or ATRIS_CLIENT_SECRET.' };
+  }
+  return {
+    clientId,
+    secretFile: secretFile ? path.resolve(secretFile) : null,
+    scope: agentClient.scopeList(readFlag(args, '--scope', '') || readFlag(args, '--scopes', '')).join(' ') || null,
+  };
+}
+
+// Keep the person's own login reachable with `atris switch` after the agent
+// client takes over credentials.json.
+function keepHumanLoginAsProfile(nextClientId) {
+  try {
+    const stored = JSON.parse(fs.readFileSync(getCredentialsPath(), 'utf8'));
+    if (agentClient.isAgentClientCredential(stored)) {
+      // A different agent client was signed in: keep it switchable too.
+      return stored.client_id === nextClientId ? null : preserveAgentClientLogin();
+    }
+    if (!stored || !stored.token) return null;
+    const name = profileNameFromEmail(stored.email);
+    if (!name) return null;
+    if (!loadProfile(name)) saveProfile(name, stored);
+    return name;
+  } catch {
+    return null;
+  }
+}
+
+async function loginAgentClient(request, deps = {}) {
+  const env = deps.env || process.env;
+  const json = Boolean(deps.json);
+  const output = deps.output || console.log;
+  const outputError = deps.outputError || console.error;
+  const fail = (message, code) => {
+    if (json) output(JSON.stringify({ ok: false, logged_in: false, error: code || 'agent_client_login_failed', detail: message }, null, 2));
+    else outputError(message);
+    return 1;
+  };
+
+  const warnings = [];
+  if (request.secretFile) {
+    let stat;
+    try {
+      stat = fs.statSync(request.secretFile);
+    } catch (error) {
+      return fail(`could not read the client secret file ${request.secretFile}${error.code ? ` (${error.code})` : ''}`, 'secret_missing');
+    }
+    if (!stat.isFile()) return fail(`${request.secretFile} is not a file`, 'secret_missing');
+    if (process.platform !== 'win32' && (stat.mode & 0o077)) {
+      warnings.push(`other users on this machine can read ${request.secretFile}. run: chmod 600 ${request.secretFile}`);
+    }
+  }
+
+  const pending = {
+    auth_type: agentClient.AUTH_TYPE,
+    client_id: request.clientId,
+    client_secret_file: request.secretFile,
+    client_secret_env: request.secretFile ? null : 'ATRIS_CLIENT_SECRET',
+    scope: request.scope,
+  };
+
+  let secret;
+  let entry;
+  try {
+    secret = agentClient.readClientSecret(pending, env);
+    entry = await agentClient.requestClientToken({ clientId: request.clientId, secret, scope: request.scope }, deps);
+  } catch (error) {
+    return fail(agentClient.scrub(error && error.message, [secret]), error && error.code);
+  }
+
+  let secretFile = request.secretFile;
+  let copiedSecretTo = null;
+  if (!secretFile) {
+    // The secret came from ATRIS_CLIENT_SECRET. Keep a private copy so later
+    // commands can renew without the variable.
+    secretFile = agentClient.managedSecretPath(request.clientId);
+    agentClient.writeFileAtomic(secretFile, `${secret}\n`);
+    copiedSecretTo = secretFile;
+  }
+
+  const keptProfile = keepHumanLoginAsProfile(request.clientId);
+  saveAgentClientCredentials({ client_id: request.clientId, client_secret_file: secretFile, scope: request.scope });
+  agentClient.writeTokenCache(request.clientId, entry);
+
+  const scopes = agentClient.scopeList(entry.scope);
+  if (envValue(env, 'ATRIS_TOKEN')) {
+    warnings.push('ATRIS_TOKEN is set in this shell and takes priority. unset it to use the agent client.');
+  }
+  if (json) {
+    output(JSON.stringify({
+      ok: true,
+      logged_in: true,
+      auth_type: agentClient.AUTH_TYPE,
+      client_id: request.clientId,
+      scopes,
+      token_expires_at: entry.expires_at,
+      ...(copiedSecretTo ? { secret_copied_to: copiedSecretTo } : {}),
+      warnings,
+    }, null, 2));
+    return 0;
+  }
+  output(`signed in as agent client ${request.clientId}`);
+  output(`scopes: ${scopes.length ? scopes.join(', ') : 'all granted to this client'}`);
+  output('the token renews on its own before it runs out.');
+  if (copiedSecretTo) output(`copied the secret from ATRIS_CLIENT_SECRET to ${copiedSecretTo} (only you can read it).`);
+  if (keptProfile) output(`the previous login is saved. switch back: atris switch ${keptProfile} --global`);
+  warnings.forEach((line) => outputError(line));
+  return 0;
+}
+
 async function loginAtris(options = {}) {
   // Support: atris login --token <token> --force
   const args = process.argv.slice(3);
@@ -440,6 +605,16 @@ async function loginAtris(options = {}) {
   const nonInteractive = isNonInteractive(args);
 
   try {
+    const clientLogin = agentClientLoginRequest(args, process.env);
+    if (clientLogin) {
+      if (clientLogin.error) {
+        if (asJson) console.log(JSON.stringify({ ok: false, logged_in: false, error: clientLogin.error }, null, 2));
+        else console.error(clientLogin.error);
+        process.exit(1);
+      }
+      process.exit(await loginAgentClient(clientLogin, { json: asJson }));
+    }
+
     const existing = loadCredentials();
 
     if (wantsAgentToken(args)) {
@@ -487,12 +662,13 @@ async function loginAtris(options = {}) {
           email,
           user_id: userId,
           provider,
+          ...(existing.client_id ? { auth_type: agentClient.AUTH_TYPE, client_id: existing.client_id } : {}),
           credentials_saved: existing.saved_at || null,
           next: 'atris whoami --json',
         }, null, 2));
         process.exit(0);
       }
-      console.log(`Currently signed in as: ${email || userId || 'unknown'}`);
+      console.log(`Currently signed in as: ${email || userId || (existing.client_id ? `agent client ${existing.client_id}` : 'unknown')}`);
       if (provider) console.log(`Provider: ${provider}`);
       console.log('Next: atris whoami');
       process.exit(0);
@@ -608,11 +784,17 @@ function logoutAtris() {
     process.exit(0);
   }
 
+  if (credentials.from_env) {
+    console.log(`This agent client (${credentials.client_id}) comes from ATRIS_CLIENT_ID in your environment.`);
+    console.log('Unset ATRIS_CLIENT_ID to sign it out.');
+    process.exit(0);
+  }
+
   const profiles = listProfiles();
   const currentName = profileNameFromEmail(credentials?.email);
 
   deleteCredentials();
-  console.log(`✓ Signed out from ${credentials.email || 'current account'}`);
+  console.log(`✓ Signed out from ${credentials.email || (credentials.client_id ? `agent client ${credentials.client_id}` : 'current account')}`);
 
   // Remind about other profiles
   const remaining = profiles.filter(p => p !== currentName);
@@ -658,14 +840,14 @@ async function switchAccount() {
   }
 
   const current = loadCredentials();
-  const currentName = profileNameFromEmail(current?.email);
+  const currentName = activeProfileName(current);
 
   if (!targetName) {
     // Interactive: show list and let user pick
     console.log('Switch account:\n');
     profiles.forEach((name, i) => {
       const profile = loadProfile(name);
-      const email = profile?.email || 'unknown';
+      const email = profile ? profileLabel(profile, 'unknown') : 'unknown';
       const marker = name === currentName ? '  ← active' : '';
       console.log(`  ${i + 1}. ${name}, ${email}${marker}`);
     });
@@ -709,6 +891,32 @@ async function switchAccount() {
   return activateProfile(match, currentName, { global: globalFlag });
 }
 
+// A profile can be switched to if it has a login token or is a saved agent client.
+function usableProfile(profile) {
+  return Boolean(profile && (profile.token || agentClient.isAgentClientCredential(profile)));
+}
+
+function profileLabel(profile, name) {
+  if (profile?.email) return profile.email;
+  if (agentClient.isAgentClientCredential(profile)) return `agent client ${profile.client_id}`;
+  return name;
+}
+
+function activeProfileName(credentials) {
+  if (agentClient.isAgentClientCredential(credentials)) return agentClient.profileNameForClient(credentials.client_id);
+  return profileNameFromEmail(credentials?.email);
+}
+
+// Overwrite credentials.json with a profile. An agent client login there is
+// saved as a profile first, so its token cache and secret file stay reachable.
+function writeGlobalCredentials(profile) {
+  const kept = preserveAgentClientLogin();
+  const credentialsPath = getCredentialsPath();
+  fs.writeFileSync(credentialsPath, JSON.stringify(profile, null, 2));
+  try { fs.chmodSync(credentialsPath, 0o600); } catch {}
+  return kept;
+}
+
 function activateProfile(name, currentName, { global = false } = {}) {
   if (name === currentName) {
     console.log(`Already on "${name}".`);
@@ -716,21 +924,20 @@ function activateProfile(name, currentName, { global = false } = {}) {
   }
 
   const profile = loadProfile(name);
-  if (!profile || !profile.token) {
+  if (!usableProfile(profile)) {
     console.error(`Profile "${name}" is corrupted. Run "atris login" to fix.`);
     process.exit(1);
   }
 
   if (global || !getTerminalSessionId()) {
     // Global switch, write to credentials.json (affects all terminals)
-    const credentialsPath = getCredentialsPath();
-    fs.writeFileSync(credentialsPath, JSON.stringify(profile, null, 2));
-    try { fs.chmodSync(credentialsPath, 0o600); } catch {}
-    console.log(`Switched to ${profile.email || name} (global, all terminals)`);
+    const kept = writeGlobalCredentials(profile);
+    console.log(`Switched to ${profileLabel(profile, name)} (global, all terminals)`);
+    if (kept && kept !== name) console.log(`The agent client login is saved. Switch back: atris switch ${kept} --global`);
   } else {
     // Per-terminal switch, write session file (only this terminal)
     setSessionProfile(name);
-    console.log(`Switched to ${profile.email || name}`);
+    console.log(`Switched to ${profileLabel(profile, name)}`);
   }
 }
 
@@ -958,10 +1165,8 @@ function activateGlobal() {
   const name = process.argv[3];
   if (!name) { process.exit(1); }
   const profile = loadProfile(name);
-  if (!profile || !profile.token) { process.exit(1); }
-  const credentialsPath = getCredentialsPath();
-  fs.writeFileSync(credentialsPath, JSON.stringify(profile, null, 2));
-  try { fs.chmodSync(credentialsPath, 0o600); } catch {}
+  if (!usableProfile(profile)) { process.exit(1); }
+  writeGlobalCredentials(profile);
   process.exit(0);
 }
 
@@ -974,7 +1179,7 @@ function switchSession() {
   if (!name) { process.exit(1); }
 
   const profile = loadProfile(name);
-  if (!profile || !profile.token) { process.exit(1); }
+  if (!usableProfile(profile)) { process.exit(1); }
 
   // Accept explicit session ID from the shell wrapper (more reliable than
   // detecting it from inside a child process where TTY env vars may be missing).
@@ -996,9 +1201,7 @@ function switchSession() {
       setSessionProfile(name);
     } else {
       // No terminal ID, global fallback
-      const credentialsPath = getCredentialsPath();
-      fs.writeFileSync(credentialsPath, JSON.stringify(profile, null, 2));
-      try { fs.chmodSync(credentialsPath, 0o600); } catch {}
+      writeGlobalCredentials(profile);
     }
   }
   process.exit(0);
@@ -1087,4 +1290,5 @@ module.exports = {
   persistMintedAgentToken,
   ensureBilledCommandAuth,
   wantsAgentToken,
+  agentClientLoginRequest,
 };

package/lib/known-commands.js

@@ -4,7 +4,7 @@ const knownCommands = ['init', 'guide', 'doctor', 'doc-health', 'install', 'work
                        'activate', '_activate', 'agent', 'team', 'chat', 'fast', 'ax', 'console', 'serve', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
                        'clean', 'close', 'harvest', 'verify', 'recover', 'search', 'scout', 'skill', 'member', 'codex-goal', 'app', 'apps', 'learn', 'lesson', 'taste', 'teach', 'plugin', 'experiments', 'bench', 'router', 'tree', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'watch', 'cloud', 'live', 'align', 'terminal', 'computer', 'diff', 'business', 'sync', 'youtube', 'x-search',
                        'ingest', 'query', 'lint', 'loop', 'pulse', 'task', 'mission', 'decide', 'agents', 'probe', 'worktree', 'land', 'caretaker', 'autoland', 'drive', 'aeo', 'slop', 'voice', 'strings', 'write', 'security-review', 'secure', 'deck', 'site', 'theme', 'card', 'reel', 'improve', 'study', 'rainmaker', 'xp', 'play', 'gm', 'game', 'x', 'recap', 'report', 'signup', 'clarity', 'interview', 'meet', 'moves', 'unknowns', 'avail', 'sync-checkout',
-                       'ci', 'github', 'vercel', 'supabase', 'linear', 'stripe', 'balance', 'usage', 'api-key', 'topup', 'buy', 'transactions', 'hire', 'hires', 'mail', 'design', 'mcp', 'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
+                       'ci', 'github', 'vercel', 'supabase', 'linear', 'stripe', 'balance', 'usage', 'api-key', 'agent-client', 'topup', 'buy', 'transactions', 'hire', 'hires', 'mail', 'design', 'mcp', 'gmail', 'calendar', 'twitter', 'slack', 'imessage', 'integrations', 'setup', 'clean-workspace', 'cw',
                        'fork', 'browse', 'publish', 'pack', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet', 'fleet-report', 'loops', 'self-improve', 'compile', 'spaceship', 'truth', 'sign', 'engine', 'engines', 'link', 'playbook', 'feed', 'brief', 'social', 'host', 'people', 'follow', 'unfollow', 'friends', 'msg', 'inbox', 'invite', 'join', 'rsi'];
 
 // Damerau-Levenshtein edit distance between two short strings. Counts an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.66.0",
+  "version": "3.67.0",
   "description": "you say what you want in plain words. atris builds it, checks it, and shows you proof.",
   "main": "bin/atris.js",
   "bin": {

package/utils/agent-client.js

@@ -0,0 +1,363 @@
+'use strict';
+
+// Agent clients: an agent signs itself in with a client id and secret
+// (OAuth client_credentials) instead of borrowing a person's login.
+//
+// The owner creates the client once with `atris agent-client create`. The
+// agent runs `atris login --client-id atc_... --client-secret-file <path>`
+// (or sets ATRIS_CLIENT_ID + ATRIS_CLIENT_SECRET / ATRIS_CLIENT_SECRET_FILE).
+// There is no refresh token: when the short token runs out, the CLI asks
+// again with the secret. The secret and tokens never reach stdout, stderr,
+// or error text.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { stateHome } = require('../lib/state-home');
+const { getApiBaseUrl, httpRequest, DEFAULT_CLIENT_ID, DEFAULT_USER_AGENT } = require('./api');
+
+const AUTH_TYPE = 'agent_client';
+const CLIENT_ID_PREFIX = 'atc_';
+const RENEW_BEFORE_EXPIRY_MS = 60 * 1000;
+
+function privateDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(dir, 0o700); } catch {}
+  return dir;
+}
+
+function clientsDir() {
+  return privateDir(path.join(privateDir(path.join(stateHome(), '.atris')), 'agent-clients'));
+}
+
+function safeClientId(clientId) {
+  return String(clientId).replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 96);
+}
+
+// Saved agent client logins live as a profile named after the client id.
+function profileNameForClient(clientId) {
+  return safeClientId(clientId);
+}
+
+function tokenCachePath(clientId) {
+  return path.join(clientsDir(), `${safeClientId(clientId)}.token.json`);
+}
+
+function managedSecretPath(clientId) {
+  return path.join(clientsDir(), `${safeClientId(clientId)}.secret`);
+}
+
+// Write through a private temp file and rename over the target, so a second
+// CLI process never reads half a file and the content is never world readable.
+function writeFileAtomic(filePath, content) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, content, { mode: 0o600, flag: 'wx' });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, filePath);
+  } catch (error) {
+    try { fs.unlinkSync(tmp); } catch {}
+    throw error;
+  }
+  try { fs.chmodSync(filePath, 0o600); } catch {}
+}
+
+function isAgentClientCredential(credentials) {
+  return Boolean(credentials
+    && credentials.auth_type === AUTH_TYPE
+    && typeof credentials.client_id === 'string'
+    && credentials.client_id.trim());
+}
+
+function scopeList(scope) {
+  if (Array.isArray(scope)) return scope.map(String).filter(Boolean);
+  if (typeof scope !== 'string') return [];
+  return scope.split(/[\s,]+/).map((part) => part.trim()).filter(Boolean);
+}
+
+function readTokenCache(clientId) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(tokenCachePath(clientId), 'utf8'));
+    if (!parsed || parsed.client_id !== clientId) return null;
+    if (typeof parsed.access_token !== 'string' || !parsed.access_token) return null;
+    const expiresMs = Date.parse(parsed.expires_at);
+    if (!Number.isFinite(expiresMs)) return null;
+    return { ...parsed, expires_ms: expiresMs };
+  } catch {
+    return null;
+  }
+}
+
+function writeTokenCache(clientId, entry) {
+  writeFileAtomic(tokenCachePath(clientId), JSON.stringify({ client_id: clientId, ...entry }, null, 2));
+}
+
+function deleteAgentClientFiles(clientId) {
+  if (!clientId) return;
+  for (const filePath of [tokenCachePath(clientId), managedSecretPath(clientId)]) {
+    try { fs.unlinkSync(filePath); } catch {}
+  }
+}
+
+// The agent client named by env, if any. ATRIS_TOKEN still wins over this
+// (readCredentials checks it first), so existing headless boxes are unchanged.
+function envAgentClient(env = process.env) {
+  const clientId = typeof env.ATRIS_CLIENT_ID === 'string' ? env.ATRIS_CLIENT_ID.trim() : '';
+  if (!clientId) return null;
+  const secretFile = typeof env.ATRIS_CLIENT_SECRET_FILE === 'string' ? env.ATRIS_CLIENT_SECRET_FILE.trim() : '';
+  return {
+    auth_type: AUTH_TYPE,
+    client_id: clientId,
+    client_secret_file: secretFile ? path.resolve(secretFile) : null,
+    client_secret_env: secretFile ? null : 'ATRIS_CLIENT_SECRET',
+    scope: null,
+    provider: AUTH_TYPE,
+    email: null,
+    user_id: null,
+    from_env: true,
+  };
+}
+
+// Attach the cached token (if any) so sync readers still see `token`.
+function withCachedToken(stored) {
+  const cache = readTokenCache(stored.client_id);
+  return {
+    ...stored,
+    provider: stored.provider || AUTH_TYPE,
+    source: AUTH_TYPE,
+    token: cache ? cache.access_token : null,
+    token_expires_at: cache ? cache.expires_at : null,
+    scopes: cache ? scopeList(cache.scope) : scopeList(stored.scope),
+  };
+}
+
+function needsRenewal(credentials, now = Date.now()) {
+  if (!credentials || !credentials.token) return true;
+  const expiresMs = Date.parse(credentials.token_expires_at);
+  if (!Number.isFinite(expiresMs)) return true;
+  return expiresMs - now <= RENEW_BEFORE_EXPIRY_MS;
+}
+
+class AgentClientError extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.code = code;
+    this.status = status || 0;
+  }
+}
+
+function readClientSecret(client, env = process.env) {
+  if (client.client_secret_file) {
+    let raw;
+    try {
+      raw = fs.readFileSync(client.client_secret_file, 'utf8');
+    } catch (error) {
+      throw new AgentClientError(`could not read the client secret file ${client.client_secret_file}${error.code ? ` (${error.code})` : ''}`, 'secret_missing');
+    }
+    const secret = raw.trim();
+    if (!secret) throw new AgentClientError(`the client secret file ${client.client_secret_file} is empty`, 'secret_missing');
+    return secret;
+  }
+  const envName = client.client_secret_env || 'ATRIS_CLIENT_SECRET';
+  const secret = typeof env[envName] === 'string' ? env[envName].trim() : '';
+  if (!secret) {
+    throw new AgentClientError('no client secret found. set ATRIS_CLIENT_SECRET or ATRIS_CLIENT_SECRET_FILE, or run atris login --client-id <id> --client-secret-file <path>', 'secret_missing');
+  }
+  return secret;
+}
+
+function getOAuthTokenUrl() {
+  // The token endpoint lives at the server root, not under /api.
+  return `${getApiBaseUrl().replace(/\/api$/, '')}/oauth/token`;
+}
+
+function scrub(text, secrets) {
+  let out = String(text == null ? '' : text);
+  for (const secret of secrets) {
+    if (secret) out = out.split(secret).join('[redacted]');
+  }
+  // Belt and braces: anything shaped like a client secret or a JWT goes too.
+  return out
+    .replace(/atcs_[A-Za-z0-9_\-.~+/=]+/g, '[redacted]')
+    .replace(/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/g, '[redacted]')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 300);
+}
+
+// POST /oauth/token with grant_type=client_credentials (client_secret_post).
+async function requestClientToken({ clientId, secret, scope }, deps = {}) {
+  const request = deps.httpRequest || httpRequest;
+  const params = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: clientId,
+    client_secret: secret,
+  });
+  const wantedScope = scopeList(scope).join(' ');
+  if (wantedScope) params.set('scope', wantedScope);
+  const body = params.toString();
+
+  let result;
+  try {
+    result = await request(getOAuthTokenUrl(), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+        'User-Agent': DEFAULT_USER_AGENT,
+        'X-Atris-Client': DEFAULT_CLIENT_ID,
+      },
+      body,
+      timeoutMs: 30000,
+    });
+  } catch (error) {
+    throw new AgentClientError(`could not reach the token endpoint: ${scrub(error && error.message, [secret])}`, 'network');
+  }
+
+  const text = Buffer.isBuffer(result.body) ? result.body.toString('utf8') : String(result.body || '');
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch { data = null; }
+  const status = result.status || 0;
+
+  if (status < 200 || status >= 300 || !data || typeof data.access_token !== 'string' || !data.access_token) {
+    const code = (data && typeof data.error === 'string' && data.error) || (status >= 200 && status < 300 ? 'missing_token' : 'token_request_failed');
+    const leaked = data && typeof data.access_token === 'string' ? data.access_token : null;
+    const detail = data && (data.error_description || data.detail || data.message);
+    const parts = [`agent client sign-in failed (${status || 'no response'}${code ? `, ${code}` : ''})`];
+    if (detail) parts.push(scrub(typeof detail === 'string' ? detail : JSON.stringify(detail), [secret, leaked]));
+    throw new AgentClientError(parts.join(': '), code, status);
+  }
+
+  const expiresIn = Number(data.expires_in);
+  const ttlMs = Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn * 1000 : 0;
+  const now = deps.now ? deps.now() : Date.now();
+  return {
+    access_token: data.access_token,
+    token_type: data.token_type || 'Bearer',
+    scope: typeof data.scope === 'string' ? data.scope : wantedScope,
+    expires_at: new Date(now + ttlMs).toISOString(),
+    obtained_at: new Date(now).toISOString(),
+  };
+}
+
+// Fetch a new token for this client, cache it, and return the credential with
+// the new token attached.
+async function renewAgentClientToken(credentials, deps = {}) {
+  const secret = readClientSecret(credentials, deps.env || process.env);
+  const entry = await requestClientToken({
+    clientId: credentials.client_id,
+    secret,
+    scope: credentials.scope,
+  }, deps);
+  writeTokenCache(credentials.client_id, entry);
+  return {
+    ...credentials,
+    source: AUTH_TYPE,
+    token: entry.access_token,
+    token_expires_at: entry.expires_at,
+    scopes: scopeList(entry.scope),
+  };
+}
+
+// Before a call: renew when the token is missing or within 60s of expiry.
+// Another process may have renewed already, so look at the cache first.
+async function ensureAgentClientToken(credentials, deps = {}) {
+  if (!needsRenewal(credentials)) return credentials;
+  const cached = withCachedToken(credentials);
+  if (!needsRenewal(cached)) return cached;
+  return renewAgentClientToken(credentials, deps);
+}
+
+// Which cached client (if any) issued this exact token. Cheap: one small
+// directory, usually holding zero or one file.
+function cachedClientIdForToken(token) {
+  if (!token) return null;
+  let dir;
+  try {
+    dir = path.join(stateHome(), '.atris', 'agent-clients');
+    if (!fs.existsSync(dir)) return null;
+  } catch {
+    return null;
+  }
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return null; }
+  for (const name of names) {
+    if (!name.endsWith('.token.json')) continue;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+      if (parsed && parsed.access_token === token && typeof parsed.client_id === 'string') return parsed.client_id;
+    } catch {}
+  }
+  return null;
+}
+
+// The active agent client credential for this token, or null when the token
+// belongs to anything else (a person's login, an API key, ATRIS_TOKEN).
+function activeClientForToken(token, readActive) {
+  const clientId = cachedClientIdForToken(token);
+  if (!clientId) return null;
+  const active = readActive();
+  if (!isAgentClientCredential(active) || active.client_id !== clientId) return null;
+  return active;
+}
+
+function defaultReadActive() {
+  return require('./auth').readActiveCredentials();
+}
+
+// Used by the shared API helper right before it sets the Authorization header.
+// Never throws: on any problem the original token goes out unchanged.
+async function freshTokenFor(token, deps = {}) {
+  try {
+    const active = activeClientForToken(token, deps.readActive || defaultReadActive);
+    if (!active || active.token !== token || !needsRenewal(active)) return token;
+    const renewed = await renewAgentClientToken(active, deps);
+    return renewed.token || token;
+  } catch {
+    return token;
+  }
+}
+
+// Used by the shared API helper after a 401. Returns a different token to
+// retry with once, or null. Never throws.
+async function tokenAfterUnauthorized(token, deps = {}) {
+  try {
+    const active = activeClientForToken(token, deps.readActive || defaultReadActive);
+    if (!active) return null;
+    if (active.token && active.token !== token && !needsRenewal(active)) {
+      // Another process already renewed; use its token.
+      return active.token;
+    }
+    const renewed = await renewAgentClientToken(active, deps);
+    return renewed.token && renewed.token !== token ? renewed.token : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  AUTH_TYPE,
+  CLIENT_ID_PREFIX,
+  AgentClientError,
+  isAgentClientCredential,
+  envAgentClient,
+  withCachedToken,
+  needsRenewal,
+  readClientSecret,
+  requestClientToken,
+  renewAgentClientToken,
+  ensureAgentClientToken,
+  freshTokenFor,
+  tokenAfterUnauthorized,
+  writeFileAtomic,
+  writeTokenCache,
+  readTokenCache,
+  managedSecretPath,
+  profileNameForClient,
+  tokenCachePath,
+  deleteAgentClientFiles,
+  scopeList,
+  scrub,
+  getOAuthTokenUrl,
+};

package/utils/api.js

@@ -118,11 +118,21 @@ function httpRequest(urlString, options) {
   });
 }
 
+// Agent client tokens are short and renewed by asking again with the secret.
+// Loaded lazily: ./agent-client requires this file.
+function agentClientRenewal() {
+  return require('./agent-client');
+}
+
 async function apiRequestJson(pathname, options = {}) {
   const url = buildApiUrl(pathname);
   const headers = { ...(options.headers || {}) };
-  if (options.token) {
-    headers.Authorization = `Bearer ${options.token}`;
+  let authToken = options.token;
+  if (authToken) {
+    // Renew first if this is the active agent client's token and it is
+    // missing or within 60 seconds of expiry. Any other token is untouched.
+    authToken = await agentClientRenewal().freshTokenFor(authToken);
+    headers.Authorization = `Bearer ${authToken}`;
   }
   if (!headers['User-Agent'] && !headers['user-agent']) {
     headers['User-Agent'] = DEFAULT_USER_AGENT;
@@ -167,6 +177,14 @@ async function apiRequestJson(pathname, options = {}) {
 
       const ok = result.status >= 200 && result.status < 300;
 
+      // A 401 on an agent client token: fetch a new token once, retry once.
+      if (result.status === 401 && authToken && !options.agentClientRetried) {
+        const renewed = await agentClientRenewal().tokenAfterUnauthorized(authToken);
+        if (renewed) {
+          return apiRequestJson(pathname, { ...options, token: renewed, agentClientRetried: true });
+        }
+      }
+
       // Retry on transient server errors
       if (!ok && retryableStatus.has(result.status) && attempt < maxRetries) {
         await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));

package/utils/auth.js

@@ -4,6 +4,7 @@ const { stateHome } = require('../lib/state-home');
 const fs = require('fs');
 const { exec } = require('child_process');
 const readline = require('readline');
+const agentClient = require('./agent-client');
 
 /**
  * Open a URL in the system's default browser.
@@ -395,10 +396,43 @@ function listProfiles() {
   }
 }
 
+// A saved agent client profile holds only the client id and the secret file
+// path; attach its cached token like the credentials.json path does.
+function activeProfile(profile) {
+  return agentClient.isAgentClientCredential(profile) ? agentClient.withCachedToken(profile) : profile;
+}
+
+function readStoredCredentialsFile() {
+  try {
+    return JSON.parse(fs.readFileSync(getCredentialsPath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Before anything overwrites credentials.json, keep an agent client login as
+// a profile named after its client id, so `atris switch <client_id>` brings
+// it back with its token cache and secret file intact. Returns the name.
+function preserveAgentClientLogin() {
+  const stored = readStoredCredentialsFile();
+  if (!agentClient.isAgentClientCredential(stored)) return null;
+  const name = agentClient.profileNameForClient(stored.client_id);
+  saveProfile(name, stored);
+  return name;
+}
+
 function deleteProfile(name) {
   const profilePath = path.join(getProfilesDir(), `${name}.json`);
   if (fs.existsSync(profilePath)) {
+    const profile = loadProfile(name);
     fs.unlinkSync(profilePath);
+    if (agentClient.isAgentClientCredential(profile)) {
+      // Last reference to this client gone: drop its token cache and secret copy.
+      const stored = readStoredCredentialsFile();
+      if (!agentClient.isAgentClientCredential(stored) || stored.client_id !== profile.client_id) {
+        agentClient.deleteAgentClientFiles(profile.client_id);
+      }
+    }
     return true;
   }
   return false;
@@ -415,6 +449,7 @@ function saveCredentials(token, refreshToken, email, userId, provider, extras =
   if (decodeJwtClaims(token)?.type === 'agent_access') {
     throw new Error('Refusing to save a scoped agent token as the login token; keep it under agent_token');
   }
+  preserveAgentClientLogin();
   const credentialsPath = getCredentialsPath();
   const credentials = {
     ...extras,
@@ -436,6 +471,11 @@ function saveCredentials(token, refreshToken, email, userId, provider, extras =
 // Supplying the auth client enables asynchronous repair. Local-only readers stay synchronous.
 function loadCredentials(apiRequestJson) {
   const credentials = readCredentials();
+  if (agentClient.isAgentClientCredential(credentials)) {
+    // Given the API helper, renew a missing or nearly expired token first.
+    if (!apiRequestJson || !agentClient.needsRenewal(credentials)) return credentials;
+    return agentClient.ensureAgentClientToken(credentials).catch(() => credentials);
+  }
   if (!credentials || credentials.source || decodeJwtClaims(credentials.token)?.type !== 'agent_access') {
     return credentials;
   }
@@ -502,6 +542,13 @@ function readCredentials() {
     return { token: normalizedEnvToken, provider: null, source: 'env' };
   }
 
+  // 0b. Agent client named by env (ATRIS_CLIENT_ID + secret). ATRIS_TOKEN
+  //     above still wins, so boxes that inject a raw token are unchanged.
+  const envClient = agentClient.envAgentClient();
+  if (envClient) {
+    return agentClient.withCachedToken(envClient);
+  }
+
   // 1. Backend-placed key for per-user cloud computers. Missing, malformed,
   //    incomplete, and expired files are ignored so later sources keep their
   //    existing order.
@@ -513,7 +560,7 @@ function readCredentials() {
   const profileOverride = process.env.ATRIS_PROFILE;
   if (profileOverride) {
     const profile = loadProfile(profileOverride);
-    if (profile) return { ...profile, source_profile: profileOverride };
+    if (profile) return { ...activeProfile(profile), source_profile: profileOverride };
     const profiles = listProfiles();
     const q = profileOverride.toLowerCase();
     const match = profiles.find(p => p.toLowerCase() === q)
@@ -521,7 +568,7 @@ function readCredentials() {
       || profiles.find(p => p.toLowerCase().includes(q));
     if (match) {
       const matched = loadProfile(match);
-      if (matched) return { ...matched, source_profile: match };
+      if (matched) return { ...activeProfile(matched), source_profile: match };
     }
   }
 
@@ -529,7 +576,7 @@ function readCredentials() {
   const sessionProfile = getSessionProfile();
   if (sessionProfile) {
     const profile = loadProfile(sessionProfile);
-    if (profile) return { ...profile, source_profile: sessionProfile };
+    if (profile) return { ...activeProfile(profile), source_profile: sessionProfile };
   }
 
   // 4. Global credentials.json
@@ -542,6 +589,10 @@ function readCredentials() {
   try {
     const data = fs.readFileSync(credentialsPath, 'utf8');
     const parsed = JSON.parse(data);
+    if (agentClient.isAgentClientCredential(parsed)) {
+      // Saved by `atris login --client-id`. The token lives in its own cache.
+      return agentClient.withCachedToken(parsed);
+    }
     if (!parsed.provider) {
       parsed.provider = null;
     }
@@ -554,9 +605,32 @@ function readCredentials() {
   }
 }
 
+// Save an agent client as the active login. The secret itself is never
+// written here, only the file that holds it. Atomic, owner-only.
+function saveAgentClientCredentials(record) {
+  const credentialsPath = getCredentialsPath();
+  agentClient.writeFileAtomic(credentialsPath, JSON.stringify({
+    auth_type: agentClient.AUTH_TYPE,
+    client_id: record.client_id,
+    client_secret_file: record.client_secret_file,
+    scope: record.scope || null,
+    provider: agentClient.AUTH_TYPE,
+    email: null,
+    user_id: null,
+    saved_at: new Date().toISOString(),
+  }, null, 2));
+}
+
 function deleteCredentials() {
   const credentialsPath = getCredentialsPath();
 
+  const stored = readStoredCredentialsFile();
+  if (agentClient.isAgentClientCredential(stored)
+    && !loadProfile(agentClient.profileNameForClient(stored.client_id))) {
+    // No saved profile still points at this client, so its files go too.
+    agentClient.deleteAgentClientFiles(stored.client_id);
+  }
+
   if (fs.existsSync(credentialsPath)) {
     fs.unlinkSync(credentialsPath);
   }
@@ -709,6 +783,14 @@ async function performTokenRefresh(credentials, apiRequestJson) {
 
 async function ensureValidCredentials(apiRequestJson, options = {}) {
   let credentials = await loadCredentials(apiRequestJson);
+  if (agentClient.isAgentClientCredential(credentials)) {
+    try {
+      const fresh = await agentClient.ensureAgentClientToken(credentials);
+      return { credentials: fresh, user: null, source: 'agent_client' };
+    } catch (error) {
+      return { error: 'token_invalid', detail: agentClient.scrub(error && error.message, []) };
+    }
+  }
   if (!credentials || !credentials.token) {
     return { error: 'not_logged_in' };
   }
@@ -860,8 +942,11 @@ module.exports = {
   shouldRefreshToken,
   getCredentialsPath,
   saveCredentials,
+  saveAgentClientCredentials,
   loadCredentials,
+  readActiveCredentials: readCredentials,
   deleteCredentials,
+  preserveAgentClientLogin,
   openBrowser,
   promptUser,
   validateAccessToken,