@sequenceholdings/studio-cli 0.1.18 → 0.1.21

package/dist/agents/source.js

@@ -0,0 +1,121 @@
+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 = [], }) {
+    const manifest = await readManifest(directory);
+    if (!manifest)
+        return compileAgentDirectory({ rootDir: directory });
+    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 entries = selectAgentEntries({
+        manifest,
+        environment: targetEnvironment,
+    });
+    return compileManifestEntries({
+        directory,
+        entries,
+        allowDuplicateIds: targetEnvironment === undefined,
+    });
+}

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
@@ -131,7 +131,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 +142,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 +186,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 +195,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 +233,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 +261,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 +313,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 +341,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 +436,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 +559,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>;

package/dist/functions/commands.js

@@ -15,8 +15,10 @@ import { confirmYes } from '../prompt.js';
 import { collectBundleFiles, isDirectory, validateLocalBundle, } from './bundle.js';
 import { managedFunctionManifestSchema, MF_MANIFEST_FILENAME, manifestEgressHosts, manifestEgressIpRanges, } from './manifest.js';
 import { buildEgressPreviewLines, egressPropagationNote, formatEgressSummary, printFunctionEgressHosts, } from './egress-preview.js';
-import { parseSourceSpec, resolveArtifactSource, } from '@sequenceholdings/artifact-studio/source-resolver';
+import { resolveArtifactSource, } from '@sequenceholdings/artifact-studio/source-resolver';
 import { buildSecretPreviewLines, classifySecrets, } from './secret-reconcile.js';
+import { parseFunctionsSourceSelection, resolveFunctionSourceDir, } from './source-selection.js';
+export { parseFunctionsSourceSelection, parseFunctionsSourceSpec, resolveFunctionSourceDir } from './source-selection.js';
 const execFileAsync = promisify(execFile);
 export const LOG = '[seq-studio]';
 const POLL_INTERVAL_MS = 5_000;
@@ -85,20 +87,6 @@ export function workDir(args) {
     const dir = typeof args.flags.dir === 'string' ? args.flags.dir : '.';
     return resolve(dir);
 }
-/**
- * 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 function parseFunctionsSourceSpec(args) {
-    const dir = typeof args.flags.dir === 'string' ? args.flags.dir : undefined;
-    if (dir !== undefined && (args.flags.repo !== undefined || args.flags['git-url'] !== undefined)) {
-        throw new Error('--dir cannot be combined with --repo / --git-url.');
-    }
-    return parseSourceSpec({ positional: dir === undefined ? [] : [dir], flags: args.flags });
-}
 /** Manifest read with a source-aware error for the missing case. */
 async function readSourceManifest(dir, spec) {
     const manifest = await readManifestOptional(dir);
@@ -106,7 +94,7 @@ async function readSourceManifest(dir, spec) {
         return manifest;
     throw new Error(spec.kind === 'local'
         ? `No ${MF_MANIFEST_FILENAME} in ${dir}. Run \`seq-studio functions init\` to scaffold one, or pass --dir.`
-        : `No ${MF_MANIFEST_FILENAME} at the root of the source repo — a managed-function repo keeps its manifest at the top level.`);
+        : `No ${MF_MANIFEST_FILENAME} in the selected remote source directory — keep it at the repo root or select a function directory with --path.`);
 }
 /**
  * Resolve the target function: --fn <slug> wins, else the manifest in the
@@ -349,14 +337,15 @@ export async function functionsInitCommand(args) {
 // build (local pre-flight)
 // ---------------------------------------------------------------------------
 export async function functionsBuildCommand(args) {
-    const spec = parseFunctionsSourceSpec(args);
+    const { spec, path } = parseFunctionsSourceSelection(args);
     // A public git URL needs no bearer token, but optional auth resolution still
     // identifies a selected M2M principal so policy can reject arbitrary CI
     // input before cloning. Local builds remain completely offline.
     const remote = await buildSourceOptions({ args, spec });
     const source = await resolveArtifactSource(spec, remote);
     try {
-        return await buildFromResolvedSource({ spec, source });
+        const dir = await resolveFunctionSourceDir({ repoDir: source.dir, path });
+        return await buildFromResolvedSource({ spec, source: { ...source, dir } });
     }
     finally {
         await source.cleanup();
@@ -417,7 +406,7 @@ export async function functionsDeployCommand(args) {
         console.error(`${LOG} ${REQUIRE_EXPLICIT_ENV_MESSAGE}`);
         return 1;
     }
-    const spec = parseFunctionsSourceSpec(args);
+    const { spec, path } = parseFunctionsSourceSelection(args);
     // Remote deploys resolve auth up front: --repo needs it to fetch the tree,
     // while --git-url must reject a selected M2M principal before cloning.
     // Local sources still defer auth until after validation so malformed local
@@ -425,7 +414,8 @@ export async function functionsDeployCommand(args) {
     const ctx = spec.kind !== 'local' ? await buildContext(args) : null;
     const source = await resolveArtifactSource(spec, ctx ? sourceClientOptions(ctx) : {});
     try {
-        return await deployFromResolvedSource({ args, spec, ctx, source });
+        const dir = await resolveFunctionSourceDir({ repoDir: source.dir, path });
+        return await deployFromResolvedSource({ args, spec, ctx, source: { ...source, dir } });
     }
     finally {
         await source.cleanup();
@@ -983,17 +973,19 @@ export const FUNCTIONS_USAGE = `usage:
                                                       (version history is retained)
 
   Flags: -e/--env <env|preview:<slug>> (required for network commands; see: seq-studio envs list) · --fn <slug> · --dir <path>
+         --path <repo-subdirectory>  (remote build/deploy only) select one function in a multi-function repo
          --from-env-file <path>  (default: .env) source file for secret values
          --no-wait · --yes
          --no-provision  (deploy) update-only: error instead of registering a new
                          shell, writing secret values, or attaching secrets (CI sweep)
 
   Source for build/deploy: a local --dir (default .), a platform git-service
-  repo (--repo <ns>/<name>), or a public HTTPS git URL (--git-url <url>). --ref selects a
-  branch/tag/commit (default: the repo's default branch). Remote sources record
-  the pinned commit as provenance (never dirty) and NEVER read a repo-committed
-  .env for secret values — provision secrets server-side or pass a local
-  --from-env-file (resolved against your cwd).
+  repo (--repo <ns>/<name>), or a public HTTPS git URL (--git-url <url>). --path selects
+  a function directory within a remote repo; omit it for the existing root-manifest
+  layout. --ref selects a branch/tag/commit (default: the repo's default branch).
+  Remote sources record the pinned commit as provenance (never dirty) and NEVER
+  read a repo-committed .env for secret values — provision secrets server-side
+  or pass a local --from-env-file (resolved against your cwd).
 
   Interactive --repo builds clone over smart-HTTP and require a repo:read git
   PAT in ATLAS_GIT_PAT (\`seq-studio auth pat create --scopes repo:read\`, or

package/dist/functions/source-selection.d.ts

@@ -0,0 +1,24 @@
+import { type SourceSpec } from '@sequenceholdings/artifact-studio/source-resolver';
+import type { ParsedArgs } from '../process/commands.js';
+export interface FunctionsSourceSelection {
+    spec: SourceSpec;
+    path?: string;
+}
+/**
+ * Functions name their local source with --dir rather than a positional, so
+ * map it onto the shared source parser used by other seq-studio primitives.
+ */
+export declare function parseFunctionsSourceSpec(args: ParsedArgs): SourceSpec;
+/**
+ * Select a managed function within a remote repository. Local callers already
+ * select the function root with --dir, so --path is remote-only.
+ */
+export declare function parseFunctionsSourceSelection(args: ParsedArgs): FunctionsSourceSelection;
+/**
+ * Resolve the selected function root after the repository is materialized.
+ * realpath containment prevents a committed symlink from escaping the repo.
+ */
+export declare function resolveFunctionSourceDir({ repoDir, path, }: {
+    repoDir: string;
+    path?: string;
+}): Promise<string>;

package/dist/functions/source-selection.js

@@ -0,0 +1,67 @@
+import { realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { parseSourceSpec, } from '@sequenceholdings/artifact-studio/source-resolver';
+import { isDirectory } from './bundle.js';
+/**
+ * Functions name their local source with --dir rather than a positional, so
+ * map it onto the shared source parser used by other seq-studio primitives.
+ */
+export function parseFunctionsSourceSpec(args) {
+    const dir = typeof args.flags.dir === 'string' ? args.flags.dir : undefined;
+    if (dir !== undefined && (args.flags.repo !== undefined || args.flags['git-url'] !== undefined)) {
+        throw new Error('--dir cannot be combined with --repo / --git-url.');
+    }
+    return parseSourceSpec({ positional: dir === undefined ? [] : [dir], flags: args.flags });
+}
+function validateFunctionRepoPath(path) {
+    const segments = path.split('/');
+    if (path.length === 0 ||
+        path.trim() !== path ||
+        isAbsolute(path) ||
+        path.includes('\\') ||
+        [...path].some((character) => character.charCodeAt(0) < 0x20) ||
+        segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        throw new Error(`--path must be a canonical relative directory within the repository (got ${JSON.stringify(path)}).`);
+    }
+}
+/**
+ * Select a managed function within a remote repository. Local callers already
+ * select the function root with --dir, so --path is remote-only.
+ */
+export function parseFunctionsSourceSelection(args) {
+    const spec = parseFunctionsSourceSpec(args);
+    const pathFlag = args.flags.path;
+    if (pathFlag === true)
+        throw new Error('--path requires a value.');
+    if (pathFlag === undefined)
+        return { spec };
+    if (spec.kind === 'local') {
+        throw new Error('--path only applies together with --repo or --git-url; use --dir for local source.');
+    }
+    validateFunctionRepoPath(pathFlag);
+    return { spec, path: pathFlag };
+}
+/**
+ * Resolve the selected function root after the repository is materialized.
+ * realpath containment prevents a committed symlink from escaping the repo.
+ */
+export async function resolveFunctionSourceDir({ repoDir, path, }) {
+    if (path === undefined)
+        return repoDir;
+    validateFunctionRepoPath(path);
+    const candidate = resolve(repoDir, path);
+    if (!(await isDirectory(candidate))) {
+        throw new Error(`--path does not name a directory in the repository: ${path}`);
+    }
+    const [canonicalRepoDir, canonicalCandidate] = await Promise.all([
+        realpath(repoDir),
+        realpath(candidate),
+    ]);
+    const relativePath = relative(canonicalRepoDir, canonicalCandidate);
+    if (relativePath === '..' ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath)) {
+        throw new Error(`--path must stay within the repository: ${path}`);
+    }
+    return canonicalCandidate;
+}

package/dist/main.d.ts

@@ -5,6 +5,7 @@
  *   seq-studio process <sub>      manage Lattice processes
  *   seq-studio artifact <sub>     manage Artifact Studio apps
  *   seq-studio functions <sub>    manage Managed Functions
+ *   seq-studio agents <sub>       manage typed agent definitions
  *   seq-studio secrets <sub>      manage org-owned Managed Secrets
  *   seq-studio repos <sub>        manage platform git-service repos
  *   seq-studio pipeline <sub>     author + validate Data Pipelines stage specs