@sequenceholdings/studio-cli 0.1.18 → 0.1.22

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,107 @@ 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>] [--only <id1,id2>]` | Compile and validate locally, without API access |
+| `seq-studio agents plan [--dir <dir>] [--only <id1,id2>]` | Offline compile/hash plan |
+| `seq-studio agents plan [--dir <dir>] -e <env> [--target <APP_ENV>] [--only <id1,id2>]` | Diff creates, updates, and unchanged definitions against an environment |
+| `seq-studio agents apply [--dir <dir>] -e <env> [--target <APP_ENV>] [--only <id1,id2>] [--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 |
+
+For `validate`, `plan`, and `apply`, `--only` accepts a comma-separated list of
+agent IDs after deployment-environment selection; every requested ID must be
+selected.
+
+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, Drizzle-authored read-only views, and policies plus named
+GraphQL documents compiled into persisted operations. Import Drizzle query
+helpers from `@sequenceholdings/orm/drizzle`; managed view builders are
+compiled to canonical SQL before registration.
+
+| 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 +300,81 @@ 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.
+
+### Scaling
+
+Managed functions scale to zero by default. Set a bounded warm pool in
+`managed-function.yml` when first-request latency matters:
+
+```yaml
+limits:
+  min_instances: 1
+  max_instances: 3
+```
+
+`min_instances` defaults to `0`, cannot exceed `max_instances`, and incurs
+Cloud Run idle-instance charges while warm.
+
+### ORM data access
+
+A function declares its ORM Data API reach in `capabilities.data`, grouped by
+namespace: `tables` it may read, v1 `actions` and ORM v2 persisted `operations`
+it may invoke, and whether raw read `query` is allowed. At invoke time the
+platform mints a short-lived data token scoped to exactly these refs — an
+operation is scoped as `<namespace>/ops/<OperationName>` (the GraphQL operation
+name from the namespace's `graphql/` documents, case-sensitive), and anything
+undeclared is denied by the Data API. A function that reaches any namespace
+must also attach a top-level `service_account`:
+
+```yaml
+service_account: lucky-svc
+capabilities:
+  data:
+    lucky:
+      tables: [lucky_draws]
+      operations: [RollLuckyNumber]
+```
+
 ## Artifact commands
 
 `seq-studio artifact <sub>` is the entry point for Artifact Studio. It runs
@@ -205,11 +387,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 +401,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 +424,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
@@ -311,11 +507,34 @@ JSON API — the same repos `--repo <ns>/<name>` sources build from.
 | `seq-studio repos clone <ns>/<name> \| --url <clone-url> \| --id <uuid> -e <env> [--ref <r>] [--out <dir>] [--force]` | smart-HTTP `git clone` when `ATLAS_GIT_PAT` is set (`--url`/`--id` need no seqapi); otherwise JSON materialize + PAT hint |
 | `seq-studio repos pull <ns>/<name> -e <env> [--ref <r>] [--out <dir>] [--force]` | always materialize via JSON API (no `.git` dir); refuses a non-empty destination unless `--force` |
 | `seq-studio repos delete <ns>/<name> -e <env> [--yes]` | delete a repo — interactive confirm unless `--yes` |
+| `seq-studio repos ci show <ns>/<name> -e <env> [--ref <r>]` | preview CI checks discovered from the ref |
+| `seq-studio repos ci require <ns>/<name> --check <name> -e <env>` | reserved for requiring a named CI check; currently refuses to write until the sandboxed runner is live |
+| `seq-studio repos ci import <ns>/<name> -e <env> [--ref <r>]` | reserved for requiring every discovered check; currently refuses to write until the sandboxed runner is live |
 
 `show` prints the smart-HTTP clone URL (`…/repos/<id>/git`). Basic auth:
 any username, PAT as password. Prefer `repos clone` over hand-rolling the
 tree API.
 
+PR CI discovers `ci/check` from the first available `lint`, `typecheck`, or
+`check` script and `ci/test` from `test`. A `.seq/ci.json` takes precedence;
+its `checks` array can declare script/argv checks or be empty to opt out.
+
+For example:
+
+    { "checks": [
+      { "phase": "check", "script": "lint" },
+      { "phase": "test", "command": ["pnpm", "test"] }
+    ] }
+
+Each check needs `phase` (`check` or `test`) and exactly one of `script` or
+`command`; `name` is optional and otherwise defaults to `ci/<phase>`
+(`-2`, etc. for additional checks in that phase).
+Discovery alone never blocks a merge. Until the sandboxed executor is live,
+`repos ci show` is preview-only, Settings controls are disabled, and
+`require`/`import` refuse to write (discovery currently posts `neutral`
+check-runs). Once the executor is live, repo owners can opt in by requiring
+check names in Settings or with `repos ci require`/`repos ci import`.
+
 ## Pipeline commands
 
 `seq-studio pipeline <sub>` authors and validates Data Pipelines **stage
@@ -330,6 +549,8 @@ install it alongside the CLI to use this family.
 | `seq-studio pipeline validate [dir] [--assets <file\|url>] [--json]` | Run the full offline spec gate: envelope + body validation, `schema_ref` resolution, and repo-level graph validation (reference resolution, single-writer, cycles, column subsets, serving projection checks). Exit 0/1 |
 | `seq-studio pipeline plan --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--json]` | Plan a Pipeline deploy (materialize → SDK/`validateSpecGraph` → compile → live-diff → provision findings). Does **not** run Databricks `bundle validate` (that is a Trigger deploy-path hard gate). Exit 1 on destructive findings (CI-safe). `--json` emits the stable plan envelope |
 | `seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha> -e <env> [--approved-by <sub>] [--no-wait]` | Plan then enqueue deploy; Trigger runs `bundle validate` then `bundle deploy` against reviewed bytes. Polls to terminal unless `--no-wait`. Production/banksouth require a pinned 40-hex SHA (client + server) |
+| `seq-studio pipeline adopt --stage <slug> --ref <sha\|branch> -e <env> --native-id <id> --approved-by <you> [--resource-key <key>] [--kind job\|dlt_pipeline] [--old-source-removal-pr <url>] [--repo pipelines/<slug>]` | Bind a live Databricks job/pipeline into the stage without recreation (`bundle deployment bind` on Trigger). Always requires `--approved-by` naming the caller. When the key is still in the monorepo DAB, pass `--old-source-removal-pr` and follow the returned cutover checklist: unbind the old bundle state without deleting the remote, then remove its DAB declaration and add the target-specific adopted-resource entry in the same PR before redeploying. |
+| `seq-studio pipeline unbind --stage <slug> --ref <sha\|branch> -e <env> --approved-by <you> [--resource-key <key>] [--repo pipelines/<slug>]` | Release an adopted binding on Trigger; the remote object stays live (never deleted) |
 | `seq-studio pipeline run-now --stage <slug> -e <env> [--repo pipelines/<slug>] [--json]` | Run the stage's active job or DLT pipeline immediately and print its Databricks run URL |
 | `seq-studio pipeline promote --stage <slug> --version <v> -e <env> [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]` | Promote a validated version to another environment. Prod/banksouth require `--approved-by` naming the authenticated caller (approvals are self-recorded); `--repo` disambiguates a slug that exists in multiple Pipelines |
 | `seq-studio pipeline rollback --stage <slug> -e <env> [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]` | Redeploy the previously retired deployment's version. Prod/banksouth require `--approved-by` — approvals are explicit even for rollbacks |

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] [--only ids] offline compile + validation\n  seq-studio agents plan [--dir d] [-e <env>] [--only ids]          offline bundle plan or live diff\n  seq-studio agents apply [--dir d] -e <env> [--only ids] [--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). --only\n  accepts a comma-separated list of agent IDs after environment selection.\n";
+export declare function runAgentsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;

package/dist/agents/commands.js

@@ -0,0 +1,238 @@
+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]';
+function requestedAgentIds(args) {
+    const only = args.flags.only;
+    if (only === undefined)
+        return undefined;
+    if (typeof only !== 'string') {
+        throw new Error('--only must be a comma-separated list of agent IDs');
+    }
+    const ids = only
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+    if (ids.length === 0) {
+        throw new Error('--only must include at least one agent ID');
+    }
+    return [...new Set(ids)];
+}
+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(),
+            onlyIds: requestedAgentIds(args),
+        });
+        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(),
+        onlyIds: requestedAgentIds(args),
+    });
+}
+/**
+ * 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(),
+                onlyIds: requestedAgentIds(args),
+            });
+            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] [--only ids] offline compile + validation
+  seq-studio agents plan [--dir d] [-e <env>] [--only ids]          offline bundle plan or live diff
+  seq-studio agents apply [--dir d] -e <env> [--only ids] [--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). --only
+  accepts a comma-separated list of agent IDs after environment selection.
+`;
+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>;