@sequenceholdings/studio-cli 0.1.18 → 0.1.21

package/README.md

@@ -1,14 +1,18 @@
 # `@sequenceholdings/studio-cli` — `seq-studio`
 
-Standalone CLI for the Sequence platform: Lattice processes, Artifact Studio
-apps, Managed Functions, Managed Secrets, Data Pipelines stage specs, and platform git repos. Runs from
-any repo against the platform over HTTP — no monorepo checkout required.
+Standalone CLI for the Sequence platform: typed agents, Lattice processes, Artifact Studio
+apps, Managed Functions, Managed Secrets, ORM namespaces, Data Pipelines stage
+specs, and platform git repos. Runs from any repo against the platform over
+HTTP — no monorepo checkout required.
 
 ```
 seq-studio process lint
 seq-studio process plan -e <env>
 seq-studio process apply -e <env>
+seq-studio agents validate
+seq-studio agents plan -e <env>
 seq-studio artifact deploy -e <env>
+seq-studio orm init lending
 seq-studio pipeline validate
 seq-studio envs list
 seq-studio doctor
@@ -16,8 +20,8 @@ seq-studio doctor
 
 > **Note:** all network commands require a Sequence platform account with the
 > appropriate permissions. Without one, only the offline commands
-> (`init`, `lint`, `simulate`, `build`, `bundle inspect`, `pipeline init`,
-> `pipeline validate`) work.
+> (`init`, `lint`, `simulate`, `build`, `bundle inspect`, `agents init`,
+> `agents validate`, offline `agents plan`, `pipeline init`, `pipeline validate`) work.
 > Sequence-internal contributors: see `INTERNAL.md` in the monorepo for
 > rollout SOPs, preview environments, and publishing docs.
 
@@ -64,12 +68,14 @@ Use `seq-studio logout` to remove the shared Sequence session, or
 ### Headless auth (CI) — M2M
 
 When there's no interactive login (CI, automation), set the service-account
-secret and `seq-studio` mints a token via the Auth0 client-credentials grant
-(M2M wins when the secret is set, otherwise the cached user token is used):
+secret and `seq-studio` mints a token via the Auth0 client-credentials grant.
+A valid cached user session wins over an ambient M2M secret (common under
+Doppler `atlas/dev`); force the service account with `SEQAPI_AUTH_MODE=m2m`:
 
 ```bash
 export AUTH0_M2M_CLIENT_SECRET=...              # built-in Sequence environments
 export AUTH0_M2M_CLIENT_SECRET_BSM_STAGING=...  # registered bsm-staging realm
+export SEQAPI_AUTH_MODE=m2m                     # optional: ignore a leftover user session
 seq-studio artifact deploy -e <env>
 ```
 
@@ -128,6 +134,101 @@ Pass `--env <name>` (or `-e <name>`) on commands that talk to the platform.
 the artifact folder's `.artifact-studio/config.json` `defaultEnv` (set by
 `artifact link` / `artifact env use`).
 
+## Agent commands
+
+Typed agent repositories export one or more `defineAgent(...)` values from files
+named `agent.ts`. Definitions are compiled in a credential-scrubbed child process,
+validated with the published `@sequenceholdings/agent-spec` contract, normalized,
+and hashed before deployment. Apply creates or updates only the definitions in the
+bundle; it never implicitly deletes agents.
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio agents init <dir>` | Scaffold a standalone typed agent repository |
+| `seq-studio agents validate [--dir <dir>] [--target <APP_ENV>]` | Compile and validate locally, without API access |
+| `seq-studio agents plan [--dir <dir>]` | Offline compile/hash plan |
+| `seq-studio agents plan [--dir <dir>] -e <env> [--target <APP_ENV>]` | Diff creates, updates, and unchanged definitions against an environment |
+| `seq-studio agents apply [--dir <dir>] -e <env> [--target <APP_ENV>] [--yes]` | Apply creates and updates after showing the plan |
+| `seq-studio agents list -e <env>` | List visible runtime agents |
+| `seq-studio agents show <id> -e <env>` | Show one runtime agent |
+
+An optional `deploy-manifest.json` targets definitions by deployment identity:
+
+```json
+{
+  "schemaVersion": 1,
+  "definitions": [
+    {
+      "id": "680000000000000000000001",
+      "path": "support/agent.ts",
+      "environments": ["local", "staging", "production"]
+    }
+  ]
+}
+```
+
+Standalone workflow:
+
+```bash
+pnpm dlx @sequenceholdings/studio-cli agents init support-agent
+cd support-agent
+pnpm install
+pnpm exec seq-studio agents validate
+pnpm exec seq-studio agents plan
+# Authenticate only when ready to inspect or apply an environment:
+pnpm exec seq-studio login
+pnpm exec seq-studio agents plan -e <env>
+pnpm exec seq-studio agents apply -e <env>
+```
+
+Use `--repo agents/<name> [--ref <ref>]` or `--git-url <url>` instead of
+`--dir` to materialize reviewed source from the platform git service.
+
+## ORM commands
+
+`seq-studio orm` authors and deploys governed ORM v2 namespaces: TypeScript
+table definitions and policies plus named GraphQL documents compiled into
+persisted operations.
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio orm init <dir>` | Scaffold one v2 namespace package (`sequence.config.ts`, `schema/*.ts`, `graphql/**`, and codegen config). |
+| `seq-studio orm generate [dir]` | Generate `schema.graphql`, `operations.manifest.json`, `typePolicies.gen.ts`, and consumer codegen when `codegen.ts` is present. |
+| `seq-studio orm validate [dir]` | Parse and compile the namespace, then verify its committed migration chain is current. |
+| `seq-studio orm plan [dir] -e <env>` | Compare the compiled namespace with registry state without applying database changes. |
+| `seq-studio orm diff [dir] [--check]` | Author the next committed migration, or verify the migration/snapshot chain offline for CI. |
+| `seq-studio orm apply [dir] -e <env>` | Author a migration if needed, register/apply the namespace, activate its operation set, publish roles/capabilities, and refresh generated outputs. |
+| `seq-studio orm migrate-from-yaml <dir>` | Convert a legacy YAML namespace to TypeScript authoring while preserving its committed migrations. |
+
+The everyday loop is:
+
+```bash
+seq-studio orm init lending
+cd lending
+pnpm install
+
+# Edit sequence.config.ts, schema/*.ts, and graphql/**/*.ts.
+seq-studio orm generate .
+seq-studio orm plan . -e local
+seq-studio orm apply . -e local
+seq-studio orm validate .
+```
+
+`apply --dry-run` rehearses a migration against a disposable branch copy of
+the target environment's data. `apply --no-create` is the CI guard that refuses
+to provision a missing namespace. Destructive DDL requires explicit
+`--allow-destructive` consent.
+
+> **ORM v2 branch status:** the scaffold currently depends on
+> `@sequenceholdings/orm@^2.0.0`, which is not published yet; the registry's
+> latest release is the v1 `0.1.1` package. A clean standalone scaffold cannot
+> complete `pnpm install` until the v2 ORM dependency chain is released. Do not
+> use monorepo workspace links as evidence that the external workflow is ready.
+> Sequence contributors should see
+> [`docs/platform/orm-v2.md`](../../../docs/platform/orm-v2.md) for the branch
+> architecture, internal verification workflow, demo, and remaining rollout
+> gates.
+
 ## Process commands
 
 | Command | What it does |
@@ -193,6 +294,47 @@ cd my-processes
 seq-studio process lint     # finds both processes
 ```
 
+## Managed Function commands
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio functions init <dir>` | Scaffold one standalone TypeScript managed function |
+| `seq-studio functions build [--dir <dir>]` | Validate a local manifest, bundle, lockfile, and size |
+| `seq-studio functions deploy --dir <dir> -e <env>` | Preview secrets and deploy a local function |
+| `seq-studio functions build --repo managed-functions/<name> [--path <dir>] -e <env>` | Materialize and validate a function from the platform Git Service |
+| `seq-studio functions deploy --repo managed-functions/<name> [--path <dir>] -e <env>` | Materialize and deploy a function from the platform Git Service |
+
+A normal function repo keeps `managed-function.yml` at its root and omits
+`--path`. A repo may also contain related, independently deployed functions:
+
+```text
+functions/
+  get-loan/
+    managed-function.yml
+    package.json
+    pnpm-lock.yaml
+    index.ts
+  update-loan/
+    managed-function.yml
+    package.json
+    pnpm-lock.yaml
+    index.ts
+```
+
+Select exactly one function directory for each build or deploy:
+
+```bash
+seq-studio functions build --repo managed-functions/encompass \
+  --path functions/get-loan -e staging
+seq-studio functions deploy --repo managed-functions/encompass \
+  --path functions/get-loan -e staging
+```
+
+Each selected directory is a self-contained function package. Functions in the
+same repo share Git review and commit provenance, but keep separate manifests,
+versions, runtime resources, secrets, and permissions. `--path` accepts only a
+canonical relative directory inside a remote repo; use `--dir` for local source.
+
 ## Artifact commands
 
 `seq-studio artifact <sub>` is the entry point for Artifact Studio. It runs
@@ -205,11 +347,11 @@ routed through `~/.config/lattice/config.toml` and the shared seqapi token.
 | `seq-studio artifact link [dir] -e <env> [--project <id>]` | `link [dir] --env <env>` |
 | `seq-studio artifact build [dir]` | `build [dir]` |
 | `seq-studio artifact plan [dir] -e <env>` | `plan [dir] --env <env>` |
-| `seq-studio artifact deploy [dir] -e <env> [--skip-unchanged] [--no-create] [--project <id>]` | `deploy [dir] --env <env>` — `--skip-unchanged` no-ops (before building) when the remote active deployment's `sourceHash` already matches the local source; `--no-create` errors instead of creating a missing project; `--project <id>` targets a project directly when duplicate slugs make the lookup ambiguous (slug must still match the manifest) |
+| `seq-studio artifact deploy [dir] -e <env> [--skip-unchanged] [--no-create] [--project <id>]` | `deploy [dir] --env <env>` — `--skip-unchanged` no-ops (before building) when the remote active deployment's `sourceHash` **and** CLI/atlas-ui peer versions already match; `--no-create` errors instead of creating a missing project; `--project <id>` targets a project directly when duplicate slugs make the lookup ambiguous (slug must still match the manifest) |
 | `seq-studio artifact dev [dir] -e <env>` | `dev [dir] --env <env>` |
 | `seq-studio artifact pull <project-id> -e <env> [--out <dir>]` | `pull <project-id> --env <env> [--out <dir>]` |
 | `seq-studio artifact list -e <env>` | `list --env <env>` — projects visible on the environment (slug, id, active version, visibility) |
-| `seq-studio artifact show <slug-or-id> -e <env>` | `show <slug-or-id> --env <env>` — one project's detail incl. active deployment + git provenance |
+| `seq-studio artifact show <slug-or-id> -e <env>` | `show <slug-or-id> --env <env>` — one project's detail incl. active deployment, git provenance, and (for newer deployments) the building `artifact-studio` / force-aliased `atlas-ui` versions |
 | `seq-studio artifact promote <deployment-id> -e <env>` | `promote <deployment-id> --env <env>` |
 | `seq-studio artifact rollback <deployment-id> -e <env>` | `rollback <deployment-id> --env <env>` |
 
@@ -219,6 +361,18 @@ routed through `~/.config/lattice/config.toml` and the shared seqapi token.
 directory's `.artifact-studio/config.json` — run them from the linked artifact
 folder (or run `seq-studio artifact link` first).
 
+**Active (official) deploys require a clean `main` checkout with a resolved
+git commit** for both Git Service (`--repo`) and local sources. Feature
+branches, dirty trees, non-git sources, and detached checkouts that cannot be
+attributed to `main` are preview-only
+(`seq-studio artifact dev` / preview channel); promotion applies the same
+provenance check.
+
+**CLI atlas-ui stamp (DES-254):** builds force-alias `@sequenceholdings/atlas-ui`
+to the CLI's copy — not the artifact's declared semver. Deployments record
+`cliVersion` + `atlasUiVersion`. Contract:
+`@sequenceholdings/artifact-studio` → `VERSION-PIN.md`.
+
 ### Source for `build` / `plan` / `deploy`
 
 These three commands read their source tree from one of three places — the rest
@@ -230,8 +384,10 @@ of the pipeline (build → upload) is identical regardless of origin:
 | `--repo <ns>/<name>` | a repo in the platform Git Service, e.g. `--repo artifacts/accounts` |
 | `--git-url <url>` | a public, credential-free HTTPS git URL (cloned to a temp dir) |
 
-`--ref <branch\|tag\|commit>` selects the revision (default: the repo's default
-branch). A remote source is materialized to a temp dir, built, and torn down;
+`--ref <branch\|tag\|commit>` selects the revision for `build` and `plan`
+(default: the repo's default branch). Active `deploy` requires `main`; other
+refs are preview-only. A remote source is materialized to a temp dir, built,
+and torn down;
 the target project is resolved from the source's `artifact.bundle.yml`
 `project_id`. The deployment records the resolved commit as its `git_commit`
 provenance. `--repo` needs `-e <env>` + a platform login. M2M/CI builds accept

package/dist/agents/apply-chunks.d.ts

@@ -0,0 +1,13 @@
+import { type AgentDefinition } from '@sequenceholdings/agent-spec';
+import { type CommandContext } from '../functions/commands.js';
+export interface ApplySummary {
+    created: number;
+    updated: number;
+    unchanged: number;
+}
+/** Each chunk is hashed over its own definitions — the apply route validates the body it received. */
+export declare function applyInChunks({ context, definitions, source, }: {
+    context: CommandContext;
+    definitions: AgentDefinition[];
+    source: string;
+}): Promise<ApplySummary>;

package/dist/agents/apply-chunks.js

@@ -0,0 +1,43 @@
+import { hashAgentBundle, } from '@sequenceholdings/agent-spec';
+import { postJson } from '../atlas-client.js';
+import { clientOptions } from '../functions/commands.js';
+const LOG = '[seq-studio]';
+// Chunked to stay inside the HTTP client's timeout; each agent commits independently anyway.
+const APPLY_CHUNK_SIZE = 20;
+/** Each chunk is hashed over its own definitions — the apply route validates the body it received. */
+export async function applyInChunks({ context, definitions, source, }) {
+    const chunks = [];
+    for (let i = 0; i < definitions.length; i += APPLY_CHUNK_SIZE) {
+        chunks.push(definitions.slice(i, i + APPLY_CHUNK_SIZE));
+    }
+    const total = { created: 0, updated: 0, unchanged: 0 };
+    let applied = 0;
+    for (const [index, chunk] of chunks.entries()) {
+        try {
+            const result = await postJson({
+                ...clientOptions(context),
+                path: '/api/agents/deploy/apply',
+                body: {
+                    definitions: chunk,
+                    bundleHash: hashAgentBundle({ definitions: chunk }),
+                    source,
+                },
+            });
+            total.created += result.summary.created;
+            total.updated += result.summary.updated;
+            total.unchanged += result.summary.unchanged;
+            applied += chunk.length;
+            if (chunks.length > 1) {
+                console.log(`${LOG} batch ${index + 1}/${chunks.length}: ${applied} of ${definitions.length} agents`);
+            }
+        }
+        catch (error) {
+            // Name what already landed. Without it a mid-run failure reads as a total
+            // failure, and the operator cannot tell which agents are already on the
+            // new definition.
+            console.error(`${LOG} batch ${index + 1}/${chunks.length} failed after ${applied} of ${definitions.length} agents applied — re-run to resume`);
+            throw error;
+        }
+    }
+    return total;
+}

package/dist/agents/commands.d.ts

@@ -0,0 +1,10 @@
+import type { ParsedArgs } from '../process/commands.js';
+import { agentsInitCommand } from './scaffold.js';
+export { agentsInitCommand };
+export declare function agentsValidateCommand(args: ParsedArgs): Promise<number>;
+export declare function agentsPlanCommand(args: ParsedArgs): Promise<number>;
+export declare function agentsApplyCommand(args: ParsedArgs): Promise<number>;
+export declare function agentsListCommand(args: ParsedArgs): Promise<number>;
+export declare function agentsShowCommand(args: ParsedArgs): Promise<number>;
+export declare const AGENTS_USAGE = "usage:\n  seq-studio agents init <dir>                         scaffold a typed agent\n  seq-studio agents validate [--dir d] [--target app] offline compile + validation\n  seq-studio agents plan [--dir d] [-e <env>]          offline bundle plan or live diff\n  seq-studio agents apply [--dir d] -e <env> [--yes]  apply creates/updates; never deletes\n  seq-studio agents list -e <env>                      list visible agents\n  seq-studio agents show <id> -e <env>                 show one agent\n\n  Source: local --dir (default .), --repo agents/<name>, or --git-url <url>.\n  Use --ref for remote sources. --target selects the deployment APP_ENV when it\n  differs from the CLI environment alias (notably OpCo registrations).\n";
+export declare function runAgentsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;

package/dist/agents/commands.js

@@ -0,0 +1,218 @@
+import { getJson, postJson } from '../atlas-client.js';
+import { readConfig } from '../config.js';
+import { applyInChunks } from './apply-chunks.js';
+import { confirmYes } from '../prompt.js';
+import { buildContext, clientOptions, flagBool, printError, requestedEnvironment, } from '../functions/commands.js';
+import { compileAgentSource as compileSource, materializeAgentSource as materialize, } from './source.js';
+import { agentsInitCommand } from './scaffold.js';
+export { agentsInitCommand };
+const LOG = '[seq-studio]';
+export async function agentsValidateCommand(args) {
+    const { source } = await materialize({ args, requireEnvironment: false });
+    try {
+        const target = typeof args.flags.target === 'string' ? args.flags.target : undefined;
+        const bundle = await compileSource({
+            directory: source.dir,
+            targetEnvironment: target,
+            deployEnvironments: await deployEnvironmentNames(),
+        });
+        if (bundle.definitions.length === 0) {
+            console.error(`${LOG} no named agent.ts definitions found`);
+            return 1;
+        }
+        console.log(`${LOG} valid: ${bundle.definitions.length} definition${bundle.definitions.length === 1 ? '' : 's'}, bundle ${bundle.hash}`);
+        return 0;
+    }
+    finally {
+        await source.cleanup();
+    }
+}
+async function deploymentBundle({ args, source, context, }) {
+    const target = (typeof args.flags.target === 'string' ? args.flags.target : undefined) ??
+        context.env.name;
+    return compileSource({
+        directory: source.dir,
+        targetEnvironment: target,
+        deployEnvironments: await deployEnvironmentNames(),
+    });
+}
+/**
+ * Names the CLI can actually deploy to. A target outside both this set and the
+ * manifest's own vocabulary is a typo, not a selection.
+ */
+async function deployEnvironmentNames() {
+    try {
+        return Object.keys((await readConfig()).envs);
+    }
+    catch {
+        // Never let an unreadable config block a deploy — the guard is a safety
+        // net, and the manifest's own vocabulary still constrains the target.
+        return [];
+    }
+}
+function printPlan(plan) {
+    for (const entry of plan.entries) {
+        const marker = entry.action === 'create' ? '+' : entry.action === 'update' ? '~' : '=';
+        // Name the fields an update would rewrite, so an operator can tell an
+        // intended edit from unexpected drift before confirming an apply.
+        const fields = entry.changedFields?.length
+            ? `: ${entry.changedFields.join(', ')}`
+            : '';
+        console.log(`  ${marker} ${entry.name} (${entry.id}) ${entry.action}${fields}`);
+    }
+    console.log(`${LOG} plan: ${plan.summary.creates} create, ${plan.summary.updates} update, ${plan.summary.unchanged} unchanged`);
+}
+export async function agentsPlanCommand(args) {
+    const environment = requestedEnvironment(args);
+    if (!environment) {
+        const { source } = await materialize({ args, requireEnvironment: false });
+        try {
+            // Honor --target the same way validate does. Without this, offline plan
+            // silently compiles the unfiltered manifest set even when the caller
+            // asked for a specific environment's overrides.
+            const target = typeof args.flags.target === 'string' ? args.flags.target : undefined;
+            const bundle = await compileSource({
+                directory: source.dir,
+                targetEnvironment: target,
+                deployEnvironments: await deployEnvironmentNames(),
+            });
+            console.log(`${LOG} offline plan: ${bundle.definitions.length} valid definition${bundle.definitions.length === 1 ? '' : 's'}, bundle ${bundle.hash}`);
+            console.log(`${LOG} pass -e <env> for create/update/unchanged live diff`);
+            return bundle.definitions.length > 0 ? 0 : 1;
+        }
+        finally {
+            await source.cleanup();
+        }
+    }
+    const { source, context } = await materialize({
+        args,
+        requireEnvironment: true,
+    });
+    if (!context)
+        throw new Error('Missing deployment context');
+    try {
+        const bundle = await deploymentBundle({ args, source, context });
+        const plan = await postJson({
+            ...clientOptions(context),
+            path: '/api/agents/deploy/plan',
+            body: {
+                definitions: bundle.definitions,
+                bundleHash: bundle.hash,
+                source: source.provenance.gitCommit ?? 'local',
+            },
+        });
+        printPlan(plan);
+        return 0;
+    }
+    finally {
+        await source.cleanup();
+    }
+}
+export async function agentsApplyCommand(args) {
+    const { source, context } = await materialize({
+        args,
+        requireEnvironment: true,
+    });
+    if (!context)
+        throw new Error('Missing deployment context');
+    try {
+        const bundle = await deploymentBundle({ args, source, context });
+        const plan = await postJson({
+            ...clientOptions(context),
+            path: '/api/agents/deploy/plan',
+            body: {
+                definitions: bundle.definitions,
+                bundleHash: bundle.hash,
+                source: source.provenance.gitCommit ?? 'local',
+            },
+        });
+        printPlan(plan);
+        const preview = [
+            `${LOG} apply ${bundle.definitions.length} agent definitions to ${context.env.name}`,
+            `${LOG} bundle ${bundle.hash}`,
+            `${LOG} no agents will be deleted`,
+        ];
+        if (!(await confirmYes({ preview, confirmed: flagBool(args.flags, 'yes') }))) {
+            return 1;
+        }
+        const summary = await applyInChunks({
+            context,
+            definitions: bundle.definitions,
+            source: source.provenance.gitCommit ?? 'local',
+        });
+        console.log(`${LOG} applied: ${summary.created} created, ${summary.updated} updated, ${summary.unchanged} unchanged`);
+        return 0;
+    }
+    finally {
+        await source.cleanup();
+    }
+}
+export async function agentsListCommand(args) {
+    const context = await buildContext(args);
+    const agents = await getJson({
+        ...clientOptions(context),
+        path: '/api/agents/agents?view=list',
+    });
+    for (const agent of agents) {
+        console.log(`${agent.id}  ${agent.name}  managed=${agent.managedBy ?? 'user'}`);
+    }
+    return 0;
+}
+export async function agentsShowCommand(args) {
+    const id = args.positional[0];
+    if (!id) {
+        console.error('usage: seq-studio agents show <id> -e <env>');
+        return 1;
+    }
+    const context = await buildContext(args);
+    const agent = await getJson({
+        ...clientOptions(context),
+        path: `/api/agents/agents/${encodeURIComponent(id)}`,
+    });
+    console.log(JSON.stringify(agent, null, 2));
+    return 0;
+}
+export const AGENTS_USAGE = `usage:
+  seq-studio agents init <dir>                         scaffold a typed agent
+  seq-studio agents validate [--dir d] [--target app] offline compile + validation
+  seq-studio agents plan [--dir d] [-e <env>]          offline bundle plan or live diff
+  seq-studio agents apply [--dir d] -e <env> [--yes]  apply creates/updates; never deletes
+  seq-studio agents list -e <env>                      list visible agents
+  seq-studio agents show <id> -e <env>                 show one agent
+
+  Source: local --dir (default .), --repo agents/<name>, or --git-url <url>.
+  Use --ref for remote sources. --target selects the deployment APP_ENV when it
+  differs from the CLI environment alias (notably OpCo registrations).
+`;
+export async function runAgentsCommand(sub, args) {
+    try {
+        switch (sub) {
+            case 'init':
+                return await agentsInitCommand(args);
+            case 'validate':
+                return await agentsValidateCommand(args);
+            case 'plan':
+                return await agentsPlanCommand(args);
+            case 'apply':
+                return await agentsApplyCommand(args);
+            case 'list':
+                return await agentsListCommand(args);
+            case 'show':
+                return await agentsShowCommand(args);
+            case 'help':
+            case '--help':
+            case '-h':
+            case undefined:
+                console.log(AGENTS_USAGE);
+                return sub ? 0 : 1;
+            default:
+                console.error(`unknown agents command: ${sub}`);
+                console.error(AGENTS_USAGE);
+                return 1;
+        }
+    }
+    catch (error) {
+        printError(error);
+        return 1;
+    }
+}

package/dist/agents/scaffold.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from '../process/commands.js';
+export declare function agentsInitCommand(args: ParsedArgs): Promise<number>;

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,18 @@
+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, }: {
+    directory: string;
+    targetEnvironment?: string;
+    /** Registered deployment environments, so a real env absent from the manifest is not read as a typo. */
+    deployEnvironments?: readonly string[];
+}): Promise<CompiledAgentBundle>;