@sequenceholdings/studio-cli 0.1.18 → 0.1.22

package/dist/agents/scaffold.js

@@ -0,0 +1,77 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { currentVersion } from '../update-check.js';
+const LOG = '[seq-studio]';
+const scaffoldSource = ({ id, name, }) => `import { defineAgent } from '@sequenceholdings/agent-spec'
+
+export const agent = defineAgent({
+  id: '${id}',
+  name: '${name}',
+  model: {
+    provider: 'anthropic',
+    name: 'claude-sonnet-4-6',
+  },
+  systemPrompt: 'Describe the agent role and operating instructions.',
+})
+`;
+export async function agentsInitCommand(args) {
+    const target = args.positional[0];
+    if (!target) {
+        console.error('usage: seq-studio agents init <dir>');
+        return 1;
+    }
+    const directory = resolve(target);
+    const file = join(directory, 'agent.ts');
+    if (existsSync(file)) {
+        console.error(`${LOG} ${file} already exists`);
+        return 1;
+    }
+    const name = basename(directory)
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map((part) => `${part[0]?.toUpperCase() ?? ''}${part.slice(1)}`)
+        .join(' ');
+    await mkdir(directory, { recursive: true });
+    await writeFile(file, scaffoldSource({ id: randomBytes(12).toString('hex'), name }));
+    await writeFile(join(directory, 'package.json'), `${JSON.stringify({
+        name: basename(directory),
+        version: '0.0.1',
+        private: true,
+        type: 'module',
+        scripts: { validate: 'seq-studio agents validate' },
+        dependencies: { '@sequenceholdings/agent-spec': '^0.1.0' },
+        devDependencies: {
+            '@sequenceholdings/studio-cli': `^${currentVersion()}`,
+        },
+    }, null, 2)}\n`);
+    await writeFile(join(directory, 'tsconfig.json'), `${JSON.stringify({
+        compilerOptions: {
+            target: 'ES2022',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            strict: true,
+            noEmit: true,
+        },
+        include: ['agent.ts'],
+    }, null, 2)}\n`);
+    await writeFile(join(directory, 'pnpm-workspace.yaml'), `packages:
+  - '.'
+
+minimumReleaseAge: 10080
+minimumReleaseAgeExclude:
+  - '@sequenceholdings/agent-spec'
+  - '@sequenceholdings/atlas-ui'
+  - '@sequenceholdings/lattice-form-renderer'
+  - '@sequenceholdings/artifact-studio'
+  - '@sequenceholdings/lattice'
+  - '@sequenceholdings/studio-cli'
+strictDepBuilds: true
+allowBuilds:
+  esbuild: true
+`);
+    console.log(`${LOG} scaffolded typed agent in ${directory}`);
+    console.log('Next: pnpm install && seq-studio agents validate');
+    return 0;
+}

package/dist/agents/source.d.ts

@@ -0,0 +1,20 @@
+import { type CompiledAgentBundle } from '@sequenceholdings/agent-spec/compiler';
+import { type ResolvedSource, type SourceSpec } from '@sequenceholdings/artifact-studio/source-resolver';
+import type { ParsedArgs } from '../process/commands.js';
+import { type CommandContext } from '../functions/commands.js';
+export declare function materializeAgentSource({ args, requireEnvironment, }: {
+    args: ParsedArgs;
+    requireEnvironment: boolean;
+}): Promise<{
+    spec: SourceSpec;
+    source: ResolvedSource;
+    context: CommandContext | null;
+}>;
+export declare function compileAgentSource({ directory, targetEnvironment, deployEnvironments, onlyIds, }: {
+    directory: string;
+    targetEnvironment?: string;
+    /** Registered deployment environments, so a real env absent from the manifest is not read as a typo. */
+    deployEnvironments?: readonly string[];
+    /** Restrict a plan or apply to explicit agent IDs after environment selection. */
+    onlyIds?: readonly string[];
+}): Promise<CompiledAgentBundle>;

package/dist/agents/source.js

@@ -0,0 +1,144 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hashAgentBundle, } from '@sequenceholdings/agent-spec';
+import { agentDeployManifestSchema, assertKnownTargetEnvironment, compileAgentDirectory, selectAgentEntries, selectionStats, } from '@sequenceholdings/agent-spec/compiler';
+import { parseSourceSpec, resolveArtifactSource, } from '@sequenceholdings/artifact-studio/source-resolver';
+import { buildContext, clientOptions, requestedEnvironment, } from '../functions/commands.js';
+const MANIFEST = 'deploy-manifest.json';
+function sourceSpec(args) {
+    const dir = typeof args.flags.dir === 'string' ? args.flags.dir : undefined;
+    if (dir &&
+        (args.flags.repo !== undefined || args.flags['git-url'] !== undefined)) {
+        throw new Error('--dir cannot be combined with --repo / --git-url.');
+    }
+    return parseSourceSpec({
+        positional: dir ? [dir] : [],
+        flags: args.flags,
+    });
+}
+function sourceOptions(context) {
+    return {
+        ...(context.authMode ? { authMode: context.authMode } : {}),
+        ...clientOptions(context),
+    };
+}
+export async function materializeAgentSource({ args, requireEnvironment, }) {
+    const spec = sourceSpec(args);
+    const needsAuth = spec.kind !== 'local';
+    if (requireEnvironment && !requestedEnvironment(args)) {
+        throw new Error('Network commands require an explicit -e/--env.');
+    }
+    const context = needsAuth || requireEnvironment ? await buildContext(args) : null;
+    const source = await resolveArtifactSource(spec, context ? sourceOptions(context) : {});
+    return { spec, source, context };
+}
+async function readManifest(directory) {
+    const path = join(directory, MANIFEST);
+    if (!existsSync(path))
+        return null;
+    return agentDeployManifestSchema.parse(JSON.parse(await readFile(path, 'utf8')));
+}
+/**
+ * Refuse to deploy when a compiled export's id does not match the id the
+ * manifest keyed the environment override on. Without that check a mis-labeled
+ * agent.ts would silently deploy under a different identity and defeat tenant
+ * overrides.
+ *
+ * Every selected path is parsed in one pass. Compiling them one file at a
+ * time previously re-parsed each agent separately and dominated validate
+ * latency on a large fleet — paid again on plan, and twice more on apply,
+ * since apply plans before it writes.
+ */
+async function compileManifestEntries({ directory, entries, allowDuplicateIds = false, }) {
+    if (entries.length === 0) {
+        return { definitions: [], files: [], hash: hashAgentBundle({ definitions: [] }), sources: [] };
+    }
+    const compiled = await compileAgentDirectory({
+        rootDir: directory,
+        filePaths: entries.map((entry) => entry.path),
+        allowDuplicateIds,
+    });
+    const byFile = new Map();
+    for (const source of compiled.sources) {
+        const list = byFile.get(source.file) ?? [];
+        list.push(source.definition);
+        byFile.set(source.file, list);
+    }
+    const definitions = [];
+    for (const entry of entries) {
+        const exported = byFile.get(entry.path) ?? [];
+        if (exported.length !== 1) {
+            throw new Error(`Expected exactly one agent export in ${entry.path}, found ${exported.length}`);
+        }
+        const definition = exported[0];
+        if (!definition) {
+            throw new Error(`Expected exactly one agent export in ${entry.path}, found 0`);
+        }
+        if (definition.id !== entry.id) {
+            throw new Error(`Manifest id "${entry.id}" for ${entry.path} does not match exported id "${definition.id}"`);
+        }
+        definitions.push(definition);
+    }
+    return {
+        definitions,
+        files: compiled.files,
+        hash: hashAgentBundle({ definitions }),
+        sources: compiled.sources,
+    };
+}
+export async function compileAgentSource({ directory, targetEnvironment, deployEnvironments = [], onlyIds, }) {
+    const manifest = await readManifest(directory);
+    if (!manifest) {
+        const compiled = await compileAgentDirectory({ rootDir: directory });
+        if (!onlyIds || onlyIds.length === 0)
+            return compiled;
+        const requested = new Set(onlyIds);
+        const definitions = compiled.definitions.filter((definition) => requested.has(definition.id));
+        const missing = [...requested].filter((id) => !definitions.some((definition) => definition.id === id));
+        if (missing.length > 0) {
+            throw new Error(`Requested agent IDs were not selected: ${missing.join(', ')}`);
+        }
+        return {
+            ...compiled,
+            definitions,
+            hash: hashAgentBundle({ definitions }),
+            sources: compiled.sources.filter((source) => requested.has(source.definition.id)),
+        };
+    }
+    if (targetEnvironment !== undefined) {
+        assertKnownTargetEnvironment({
+            manifest,
+            environment: targetEnvironment,
+            deployEnvironments,
+        });
+        // Selection is silent, so a target that matches nothing looks identical to
+        // a full deploy. Name the drop before the operator confirms an apply.
+        const { selected, skipped, total } = selectionStats({
+            manifest,
+            environment: targetEnvironment,
+        });
+        if (skipped > 0) {
+            console.log(`[seq-studio] target ${targetEnvironment}: ${selected} of ${total} agents selected, ${skipped} scoped to other environments`);
+        }
+    }
+    // With a target: last-wins by id (tenant overrides). Without: every distinct
+    // path, so validate still compiles override sources that lose a collapse.
+    const selectedEntries = selectAgentEntries({
+        manifest,
+        environment: targetEnvironment,
+    });
+    const requested = new Set(onlyIds);
+    const entries = requested.size === 0
+        ? selectedEntries
+        : selectedEntries.filter((entry) => requested.has(entry.id));
+    const missing = [...requested].filter((id) => !entries.some((entry) => entry.id === id));
+    if (missing.length > 0) {
+        throw new Error(`Requested agent IDs were not selected: ${missing.join(', ')}`);
+    }
+    return compileManifestEntries({
+        directory,
+        entries,
+        allowDuplicateIds: targetEnvironment === undefined,
+    });
+}

package/dist/atlas-client.js

@@ -9,6 +9,7 @@ import { PREVIEW_DOMAIN } from './preview.js';
 const MAX_503_RETRIES = 5;
 const DEFAULT_RETRY_AFTER_SECONDS = 2;
 const LOG_PREFIX = '[seq-studio]';
+const CF_ACCESS_DOMAIN = 'seqholdings.com';
 export class AtlasApiError extends Error {
     status;
     path;
@@ -42,6 +43,7 @@ async function authenticatedFetch({ baseUrl, init = {}, path, token, }) {
         redirect: 'manual',
         headers: {
             ...previewAccessHeaders(baseUrl),
+            ...cfAccessHeaders(baseUrl),
             ...init.headers,
             Authorization: `Bearer ${token}`,
         },
@@ -63,6 +65,33 @@ function previewAccessHeaders(baseUrl) {
         return {};
     }
 }
+/**
+ * Cloudflare Access fronts *.seqholdings.com and only bypasses the company
+ * network, so a CI runner is turned away at the edge with an HTML "Access
+ * Restricted" page before Atlas ever sees the bearer token. A service token
+ * gets through the edge; the bearer still authenticates at the app.
+ *
+ * Scoped to seqholdings.com so the token is never sent to localhost, a tenant
+ * domain, or any other host the CLI can be pointed at.
+ */
+function cfAccessHeaders(baseUrl) {
+    const clientId = process.env.CF_ACCESS_CLIENT_ID?.trim();
+    const clientSecret = process.env.CF_ACCESS_CLIENT_SECRET?.trim();
+    if (!clientId || !clientSecret)
+        return {};
+    try {
+        const parsed = new URL(baseUrl);
+        if (parsed.protocol !== 'https:')
+            return {};
+        const hostname = parsed.hostname.toLowerCase();
+        if (hostname !== CF_ACCESS_DOMAIN && !hostname.endsWith(`.${CF_ACCESS_DOMAIN}`))
+            return {};
+        return { 'CF-Access-Client-Id': clientId, 'CF-Access-Client-Secret': clientSecret };
+    }
+    catch {
+        return {};
+    }
+}
 function messageFromBody(body, status, statusText) {
     if (body && typeof body === 'object') {
         const record = body;

package/dist/auth.d.ts

@@ -5,18 +5,18 @@
  *
  * Two token sources, in the SAME precedence order as seqapi's
  * `get_access_token` (`shared/seqapi/seqapi/auth.py`):
- *   1. M2M service account — Auth0 client-credentials grant, used when
- *      `AUTH0_M2M_CLIENT_SECRET` is set. This is the headless path: CI /
- *      cloud agents with no interactive login can still push.
+ *   1. Cached user access token — read from the seqapi token file. When it
+ *      expires, an interactive session performs a bounded PKCE login again.
+ *   2. M2M service account — Auth0 client-credentials grant when the realm's
+ *      `AUTH0_M2M_CLIENT_SECRET` (or suffixed OpCo variant) is set. Used when
+ *      no valid user session exists, or when `SEQAPI_AUTH_MODE=m2m` forces it.
  *      (M2M carries app scopes but NO user identity / workspace membership
  *      — see the `atlas-test-access` rule.)
- *   2. Cached user access token — read from the seqapi token file. When it
- *      expires, an interactive session performs a bounded PKCE login again.
  *
- * Login writes the shared file. This mirrors
- * `seqapi._save_tokens` exactly:
+ * Login writes the shared file. This mirrors `seqapi._save_tokens` exactly:
  * same fields, same shape, same 0o600 permissions, atomic write via
- * tmpfile + rename. The M2M token is in-memory only (never persisted).
+ * tmpfile + rename. M2M tokens are cached in-process and also under the
+ * token file's `m2m` key so short-lived CLI processes reuse a grant.
  */
 export declare const AUTH0_DOMAIN = "dev-n1t8ts403fp8oyxp.us.auth0.com";
 export declare const AUTH0_CLIENT_ID = "GD9riCDWocfc66odpWBjwBiX43qqAX8r";
@@ -80,13 +80,15 @@ export declare class NotLoggedInError extends Error {
     constructor(realmName?: string, reason?: string);
 }
 /**
- * Return a valid access token for an environment's auth realm. Tries the
- * realm's M2M service account first (secret env var), then falls back to the
- * cached user access token. Expired user sessions perform bounded PKCE login
- * when browser auto-login is enabled. Same precedence and token file as seqapi's
- * `get_access_token`, so both CLIs resolve the same identity for the same
- * environment. No `env` (or a built-in Sequence env) means the shared
- * Sequence realm — the legacy behavior every existing caller gets unchanged.
+ * Return a valid access token for an environment's auth realm.
+ *
+ * Precedence (default `SEQAPI_AUTH_MODE=auto`), matching seqapi:
+ *   1. Valid cached user access token
+ *   2. M2M client-credentials when the realm's secret env var is set
+ *   3. Bounded PKCE login when browser auto-login is enabled
+ *
+ * Set `SEQAPI_AUTH_MODE=m2m` to skip the user token. No `env` (or a built-in
+ * Sequence env) means the shared Sequence realm.
  */
 export declare class UnsafeAuthTargetError extends Error {
 }
@@ -142,8 +144,8 @@ export declare function verifyTokenMatchesRealm({ accessToken, realm, requireOrg
 export declare function decodeJwtSub(token: string): string | null;
 /**
  * The Auth0 subject the CLI would authenticate as right now, without any
- * network call: the requested realm's M2M client subject when its secret is
- * configured, else the `sub` of that realm's cached user token, else null.
+ * network call. Matches token resolution precedence: a valid user session
+ * wins over an ambient M2M secret unless `SEQAPI_AUTH_MODE=m2m`.
  */
 export declare function currentIdentitySubject(options?: {
     env?: string;

package/dist/auth.js

@@ -15,18 +15,18 @@ function hasErrorCode(error, code) {
  *
  * Two token sources, in the SAME precedence order as seqapi's
  * `get_access_token` (`shared/seqapi/seqapi/auth.py`):
- *   1. M2M service account — Auth0 client-credentials grant, used when
- *      `AUTH0_M2M_CLIENT_SECRET` is set. This is the headless path: CI /
- *      cloud agents with no interactive login can still push.
+ *   1. Cached user access token — read from the seqapi token file. When it
+ *      expires, an interactive session performs a bounded PKCE login again.
+ *   2. M2M service account — Auth0 client-credentials grant when the realm's
+ *      `AUTH0_M2M_CLIENT_SECRET` (or suffixed OpCo variant) is set. Used when
+ *      no valid user session exists, or when `SEQAPI_AUTH_MODE=m2m` forces it.
  *      (M2M carries app scopes but NO user identity / workspace membership
  *      — see the `atlas-test-access` rule.)
- *   2. Cached user access token — read from the seqapi token file. When it
- *      expires, an interactive session performs a bounded PKCE login again.
  *
- * Login writes the shared file. This mirrors
- * `seqapi._save_tokens` exactly:
+ * Login writes the shared file. This mirrors `seqapi._save_tokens` exactly:
  * same fields, same shape, same 0o600 permissions, atomic write via
- * tmpfile + rename. The M2M token is in-memory only (never persisted).
+ * tmpfile + rename. M2M tokens are cached in-process and also under the
+ * token file's `m2m` key so short-lived CLI processes reuse a grant.
  */
 // Match `shared/seqapi/seqapi/config.py`. Hard-coded because the seqapi
 // CLI also hard-codes them — there's a single Sequence Auth0 tenant for
@@ -43,6 +43,8 @@ const SEQUENCE_BUILTIN_ENVS = new Set(['local', 'staging', 'production', 'bankso
 export function isSequenceAuthEnvName(envName) {
     return (envName === SEQUENCE_REALM ||
         SEQUENCE_BUILTIN_ENVS.has(envName) ||
+        envName === 'worktree' ||
+        envName.startsWith('local:') ||
         envName === 'preview' ||
         envName.startsWith('preview:'));
 }
@@ -131,7 +133,8 @@ export function m2mSecretEnvName(realm) {
 }
 // In-memory per-realm cache for M2M tokens (seconds-based, mirrors seqapi's
 // `_m2m_cache`). Reused while > 60s from expiry to avoid re-minting on every
-// call within a single process (e.g. a long `artifact dev` watch).
+// call within a single process (e.g. a long `artifact dev` watch). Disk
+// persistence under tokens.json `m2m` covers cross-process reuse.
 const m2mCache = new Map();
 /**
  * A configured M2M credential failed to mint a token. Typed so callers that
@@ -141,11 +144,41 @@ const m2mCache = new Map();
 export class M2mTokenError extends Error {
     name = 'M2mTokenError';
 }
+function authModePrefersM2m() {
+    const value = process.env.SEQAPI_AUTH_MODE?.trim().toLowerCase() ?? 'auto';
+    return value === 'm2m';
+}
+function tokenStillValid(entry) {
+    const now = Date.now() / 1000;
+    return Boolean(entry?.accessToken && (entry.expiresAt ?? 0) > now + 60);
+}
+async function loadPersistedM2m(realmName) {
+    if (!existsSync(seqapiTokenPath()))
+        return null;
+    return withTokenFileLock(async () => {
+        const file = await readTokenFile();
+        const entry = file?.m2m?.[realmName];
+        if (!entry?.access_token)
+            return null;
+        return {
+            accessToken: entry.access_token,
+            expiresAt: entry.expires_at ?? 0,
+        };
+    });
+}
+async function persistM2m({ realmName, accessToken, expiresAt, }) {
+    await withTokenFileLock(async () => {
+        const existing = (await readTokenFile()) ?? {};
+        stripPersistedRefreshTokens(existing);
+        const m2m = { ...existing.m2m, [realmName]: { access_token: accessToken, expires_at: expiresAt } };
+        await writeTokenFile({ ...existing, m2m });
+    });
+}
 /**
  * Mint an M2M access token via the Auth0 client-credentials grant when the
- * realm's secret env var is set. Returns null when the secret is unset
- * (so the caller falls back to the user token). Throws on a configured-but-
- * rejected secret, mirroring seqapi's `_get_m2m_token` (`raise_for_status`).
+ * realm's secret env var is set. Returns null when the secret is unset.
+ * Throws on a configured-but-rejected secret, mirroring seqapi's
+ * `_get_m2m_token`. Cache order: in-process → shared token file → Auth0.
  * The realm's own secret var is required — a Sequence secret in the shell is
  * never sent to a tenant's Auth0 client.
  */
@@ -155,9 +188,8 @@ async function getM2mToken(realm = SEQUENCE_AUTH_REALM) {
     const clientSecret = process.env[m2mSecretEnvName(realm)];
     if (!clientSecret)
         return null;
-    const now = Date.now() / 1000;
     const cached = m2mCache.get(realm.name);
-    if (cached && cached.expiresAt > now + 60) {
+    if (cached && tokenStillValid(cached)) {
         verifyTokenMatchesRealm({
             accessToken: cached.accessToken,
             realm,
@@ -165,6 +197,16 @@ async function getM2mToken(realm = SEQUENCE_AUTH_REALM) {
         });
         return cached.accessToken;
     }
+    const persisted = await loadPersistedM2m(realm.name);
+    if (persisted && tokenStillValid(persisted)) {
+        verifyTokenMatchesRealm({
+            accessToken: persisted.accessToken,
+            realm,
+            requireOrganization: false,
+        });
+        m2mCache.set(realm.name, persisted);
+        return persisted.accessToken;
+    }
     const response = await fetch(`https://${realm.domain}/oauth/token`, {
         method: 'POST',
         redirect: 'manual',
@@ -193,6 +235,11 @@ async function getM2mToken(realm = SEQUENCE_AUTH_REALM) {
         expiresAt: Date.now() / 1000 + (data.expires_in ?? 7200),
     };
     m2mCache.set(realm.name, entry);
+    await persistM2m({
+        realmName: realm.name,
+        accessToken: entry.accessToken,
+        expiresAt: entry.expiresAt,
+    });
     return entry.accessToken;
 }
 export function seqapiTokenDir() {
@@ -216,13 +263,15 @@ export class NotLoggedInError extends Error {
     }
 }
 /**
- * Return a valid access token for an environment's auth realm. Tries the
- * realm's M2M service account first (secret env var), then falls back to the
- * cached user access token. Expired user sessions perform bounded PKCE login
- * when browser auto-login is enabled. Same precedence and token file as seqapi's
- * `get_access_token`, so both CLIs resolve the same identity for the same
- * environment. No `env` (or a built-in Sequence env) means the shared
- * Sequence realm — the legacy behavior every existing caller gets unchanged.
+ * Return a valid access token for an environment's auth realm.
+ *
+ * Precedence (default `SEQAPI_AUTH_MODE=auto`), matching seqapi:
+ *   1. Valid cached user access token
+ *   2. M2M client-credentials when the realm's secret env var is set
+ *   3. Bounded PKCE login when browser auto-login is enabled
+ *
+ * Set `SEQAPI_AUTH_MODE=m2m` to skip the user token. No `env` (or a built-in
+ * Sequence env) means the shared Sequence realm.
  */
 export class UnsafeAuthTargetError extends Error {
 }
@@ -266,9 +315,21 @@ export async function getAccessTokenWithMode(options) {
     const realm = await realmForEnv(options?.env);
     if (options?.targetUrl)
         validateRealmTarget({ realm, targetUrl: options.targetUrl });
+    const forceM2m = authModePrefersM2m();
+    if (!forceM2m) {
+        const tokens = await loadCachedUserTokens(realm.name);
+        const now = Date.now() / 1000;
+        if (tokens?.access_token && (tokens.expires_at ?? 0) > now + 60) {
+            verifyTokenMatchesRealm({ accessToken: tokens.access_token, realm });
+            return { authMode: 'user', token: tokens.access_token };
+        }
+    }
     const m2m = await getM2mToken(realm);
     if (m2m)
         return { authMode: 'm2m', token: m2m };
+    if (forceM2m) {
+        throw new NotLoggedInError(realm.name, `SEQAPI_AUTH_MODE=m2m but no M2M credentials for [${realm.name}].`);
+    }
     const tokens = await loadCachedUserTokens(realm.name);
     if (!tokens) {
         if (options?.allowInteractiveLogin === false) {
@@ -282,11 +343,6 @@ export async function getAccessTokenWithMode(options) {
             }),
         };
     }
-    const now = Date.now() / 1000;
-    if (tokens.access_token && (tokens.expires_at ?? 0) > now + 60) {
-        verifyTokenMatchesRealm({ accessToken: tokens.access_token, realm });
-        return { authMode: 'user', token: tokens.access_token };
-    }
     if (options?.allowInteractiveLogin === false) {
         throw new NotLoggedInError(realm.name, `Access token expired [${realm.name}].`);
     }
@@ -382,19 +438,24 @@ export function decodeJwtSub(token) {
 }
 /**
  * The Auth0 subject the CLI would authenticate as right now, without any
- * network call: the requested realm's M2M client subject when its secret is
- * configured, else the `sub` of that realm's cached user token, else null.
+ * network call. Matches token resolution precedence: a valid user session
+ * wins over an ambient M2M secret unless `SEQAPI_AUTH_MODE=m2m`.
  */
 export async function currentIdentitySubject(options = {}) {
     const realm = await realmForEnv(options.env);
+    const forceM2m = authModePrefersM2m();
+    if (!forceM2m) {
+        const tokens = await loadCachedUserTokens(realm.name);
+        const now = Date.now() / 1000;
+        if (tokens?.access_token && (tokens.expires_at ?? 0) > now + 60) {
+            verifyTokenMatchesRealm({ accessToken: tokens.access_token, realm });
+            return decodeJwtSub(tokens.access_token);
+        }
+    }
     if (realm.m2mClientId && process.env[m2mSecretEnvName(realm)]?.trim()) {
         return `${realm.m2mClientId}@clients`;
     }
-    const tokens = await loadCachedUserTokens(realm.name);
-    if (!tokens?.access_token)
-        return null;
-    verifyTokenMatchesRealm({ accessToken: tokens.access_token, realm });
-    return decodeJwtSub(tokens.access_token);
+    return null;
 }
 async function readTokenFile() {
     const path = seqapiTokenPath();
@@ -500,6 +561,14 @@ export async function deleteRealmTokens(realmName) {
                 delete updated.realms;
             }
         }
+        const m2m = { ...existing.m2m };
+        delete m2m[realmName];
+        if (Object.keys(m2m).length > 0) {
+            updated.m2m = m2m;
+        }
+        else {
+            delete updated.m2m;
+        }
         await writeTokenFile(updated);
     });
 }

package/dist/functions/commands.d.ts

@@ -2,7 +2,7 @@ import { type AuthMode } from '../auth.js';
 import { type ResolvedEnv } from '../config.js';
 import type { ParsedArgs } from '../process/commands.js';
 import { type ManagedFunctionManifest } from './manifest.js';
-import { type SourceSpec } from '@sequenceholdings/artifact-studio/source-resolver';
+export { parseFunctionsSourceSelection, parseFunctionsSourceSpec, resolveFunctionSourceDir } from './source-selection.js';
 export declare const LOG = "[seq-studio]";
 export interface FunctionSummary {
     id: string;
@@ -50,14 +50,6 @@ export declare function clientOptions(ctx: CommandContext): {
 };
 export declare function readManifestOptional(dir: string): Promise<ManagedFunctionManifest | null>;
 export declare function workDir(args: ParsedArgs): string;
-/**
- * Source selection for build/deploy: --dir (local, default '.'), a platform
- * git-service repo (--repo <ns>/<name>), or any git URL (--git-url <url>);
- * --ref picks a branch/tag/commit. Reuses the artifact-studio resolver —
- * functions name their local dir with --dir rather than a positional, so map
- * it onto the spec parser's positional slot.
- */
-export declare function parseFunctionsSourceSpec(args: ParsedArgs): SourceSpec;
 export declare function resolveOrRegisterFunction({ ctx, slug, title, description, }: {
     ctx: CommandContext;
     slug: string;
@@ -90,5 +82,5 @@ export declare function functionsRollbackCommand(args: ParsedArgs): Promise<numb
 /** Minimal dotenv parser — KEY=VALUE lines, quotes stripped, comments skipped. */
 export declare function parseDotenv(content: string): Record<string, string>;
 export declare function functionsDeleteCommand(args: ParsedArgs): Promise<number>;
-export declare const FUNCTIONS_USAGE = "usage:\n  seq-studio functions init <dir>                     scaffold manifest + TypeScript hello-world handler\n  seq-studio functions build [--dir d]                local pre-flight (manifest, lockfile, size)\n  seq-studio functions deploy -e <env> [-m msg]       preview + confirm secrets + upload and deploy\n  seq-studio functions list -e <env> [--match-local]  functions visible on the environment\n  seq-studio functions show -e <env> [--fn slug]      detail for one function (versions, secrets)\n  seq-studio functions logs -e <env> [--limit N] [--since t]  Cloud Logging snapshot (reader-gated)\n  seq-studio functions promote <version> -e <env>     make a version live\n  seq-studio functions rollback [<version>] -e <env>  redeploy a prior version\n  seq-studio functions delete -e <env> [--yes]        archive function + tear down GCP resources\n                                                      (version history is retained)\n\n  Flags: -e/--env <env|preview:<slug>> (required for network commands; see: seq-studio envs list) \u00B7 --fn <slug> \u00B7 --dir <path>\n         --from-env-file <path>  (default: .env) source file for secret values\n         --no-wait \u00B7 --yes\n         --no-provision  (deploy) update-only: error instead of registering a new\n                         shell, writing secret values, or attaching secrets (CI sweep)\n\n  Source for build/deploy: a local --dir (default .), a platform git-service\n  repo (--repo <ns>/<name>), or a public HTTPS git URL (--git-url <url>). --ref selects a\n  branch/tag/commit (default: the repo's default branch). Remote sources record\n  the pinned commit as provenance (never dirty) and NEVER read a repo-committed\n  .env for secret values \u2014 provision secrets server-side or pass a local\n  --from-env-file (resolved against your cwd).\n\n  Interactive --repo builds clone over smart-HTTP and require a repo:read git\n  PAT in ATLAS_GIT_PAT (`seq-studio auth pat create --scopes repo:read`, or\n  Atlas \u2192 Settings \u2192 Tokens). Headless M2M builds use JSON materialize and\n  accept only platform-managed --repo sources. Interactive builds also need\n  --env + seq-studio login to resolve the repo and deploy.\n";
+export declare const FUNCTIONS_USAGE = "usage:\n  seq-studio functions init <dir>                     scaffold manifest + TypeScript hello-world handler\n  seq-studio functions build [--dir d]                local pre-flight (manifest, lockfile, size)\n  seq-studio functions deploy -e <env> [-m msg]       preview + confirm secrets + upload and deploy\n  seq-studio functions list -e <env> [--match-local]  functions visible on the environment\n  seq-studio functions show -e <env> [--fn slug]      detail for one function (versions, secrets)\n  seq-studio functions logs -e <env> [--limit N] [--since t]  Cloud Logging snapshot (reader-gated)\n  seq-studio functions promote <version> -e <env>     make a version live\n  seq-studio functions rollback [<version>] -e <env>  redeploy a prior version\n  seq-studio functions delete -e <env> [--yes]        archive function + tear down GCP resources\n                                                      (version history is retained)\n\n  Flags: -e/--env <env|preview:<slug>> (required for network commands; see: seq-studio envs list) \u00B7 --fn <slug> \u00B7 --dir <path>\n         --path <repo-subdirectory>  (remote build/deploy only) select one function in a multi-function repo\n         --from-env-file <path>  (default: .env) source file for secret values\n         --no-wait \u00B7 --yes\n         --no-provision  (deploy) update-only: error instead of registering a new\n                         shell, writing secret values, or attaching secrets (CI sweep)\n\n  Source for build/deploy: a local --dir (default .), a platform git-service\n  repo (--repo <ns>/<name>), or a public HTTPS git URL (--git-url <url>). --path selects\n  a function directory within a remote repo; omit it for the existing root-manifest\n  layout. --ref selects a branch/tag/commit (default: the repo's default branch).\n  Remote sources record the pinned commit as provenance (never dirty) and NEVER\n  read a repo-committed .env for secret values \u2014 provision secrets server-side\n  or pass a local --from-env-file (resolved against your cwd).\n\n  Interactive --repo builds clone over smart-HTTP and require a repo:read git\n  PAT in ATLAS_GIT_PAT (`seq-studio auth pat create --scopes repo:read`, or\n  Atlas \u2192 Settings \u2192 Tokens). Headless M2M builds use JSON materialize and\n  accept only platform-managed --repo sources. Interactive builds also need\n  --env + seq-studio login to resolve the repo and deploy.\n";
 export declare function runFunctionsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;