fjall 0.96.0 → 0.99.1

package/bin/assets/src/util/agent/agentInit.js

@@ -0,0 +1,288 @@
+import{existsSync as h,mkdirSync as m,readFileSync as g}from"node:fs";import{join as y,relative as w}from"node:path";import{maskSensitiveOutput as j}from"@fjall/util";import{atomicWrite as f}from"@fjall/util/fsHelpers";import{DEFAULT_BASE_URL as k}from"../api/FjallApiClient.types.js";import{logger as d}from"../logger/index.js";const u=e=>{d.debug("AgentInit","tmp cleanup failed",{error:e instanceof Error?e.message:String(e)})},l="<!-- fjall:managed:start -->",p="<!-- fjall:managed:end -->",v=`---
+name: fjall
+description: Deploy applications to AWS via Fjall CLI. Use when the user asks to deploy, connect AWS, manage secrets, or provision infrastructure.
+---
+
+`;function E(e){const c=[],o=[],t=[],n=y(e,"SKILL.md"),a=w(process.cwd(),n)||"SKILL.md",i=S();try{if(m(e,{recursive:!0}),h(n)){const r=g(n,"utf-8");if(r.includes(l)){const s=A(r,i);s.kind==="corrupt"?(d.warn("AgentInit","MANAGED markers are corrupt \u2014 leaving file untouched",{relPath:a}),t.push(`${a} (corrupt managed markers \u2014 repair manually)`)):s.kind==="unchanged"?t.push(`${a} (no changes)`):(f(n,s.content,{onCleanupError:u}),o.push(a))}else t.push(`${a} (exists, no managed section \u2014 add manually)`)}else f(n,v+b(i),{onCleanupError:u}),c.push(a)}catch(r){const s=j(r instanceof Error?r.message:String(r));d.debug("AgentInit","Skill file write failed",{relPath:a,error:s}),t.push(`${a} (error: ${s})`)}return{created:c,updated:o,skipped:t}}function b(e){return`${l}
+${e}
+${p}
+`}function A(e,c){const o=e.indexOf(l),t=e.indexOf(p);if(o===-1||t===-1||t<o)return{kind:"corrupt"};if(e.lastIndexOf(l)!==o||e.lastIndexOf(p)!==t)return{kind:"corrupt"};const n=e.slice(0,o),a=e.slice(t+p.length),i=`${n}${l}
+${c}
+${p}${a}`;return i===e?{kind:"unchanged"}:{kind:"replaced",content:i}}function S(){return`# Fjall \u2014 Skill for AI Agents
+
+You have the Fjall CLI available. Fjall deploys applications to AWS via
+infrastructure-as-code. Always pass \`--agent\` for structured TOON output.
+
+## Before You Start
+- Confirm \`FJALL_API_KEY\` is set. If not, tell the user to sign up at
+  ${k} and run \`fjall login --api-key <key>\`.
+  Alternatively, run \`fjall login --device --agent\` to initiate a
+  browser-based device-code flow.
+- All Fjall terminology is British English: "organisation", "authorise", "colour".
+- Each \`--agent\` output is **authoritative** \u2014 its \`status\`, \`error\`, and
+  \`help[]\` fields tell you what happened and what to do next. You do not
+  need to poll a separate state command between steps.
+- **Always run \`fjall\` from the project root.** Scaffolding commands
+  (e.g. \`create account\`, \`create org\`) create subdirectories like
+  \`fjall/account/\` \u2014 do not \`cd\` into them. All subsequent commands
+  (\`connect\`, \`deploy\`, \`target list\`, etc.) expect the project root.
+- Do **not** hand-roll AWS CLI, CDK, or Terraform \u2014 Fjall owns the
+  infrastructure graph and will diverge from manual edits.
+
+## What Fjall Owns
+
+Fjall manages two layers per application:
+1. **Infrastructure** \u2014 CDK-generated AWS resources (ECS, RDS, ALB, S3, Lambda).
+2. **Code** \u2014 container images and Lambda bundles from the source tree.
+
+Both deploy via \`fjall deploy\`. Use \`--infra-only\` or \`--deploy-only\` to split.
+
+\`fjall deploy <org>\` cascades: organisation \u2192 platform \u2192 accounts \u2192 applications.
+Use \`--no-cascade\` to deploy a single level.
+
+## Recipe: Onboard a New User
+
+**First, ask the user which path they want:**
+- **Single account** \u2014 one AWS account, no shared governance.
+- **Organisation** \u2014 multi-account with governance and shared infrastructure.
+
+### Path A: Single Account
+1. \`fjall login --device --agent\`   (skip if authenticated)
+2. Ask which region. Default to **us-east-2** if no preference.
+   Common regions: us-east-2, us-west-2, eu-west-1, ap-southeast-2.
+3. \`fjall create account --primary-region <region> --agent\`
+   -> Scaffolds \`fjall/account/\` infrastructure-as-code.
+   -> Confirm the user is in the correct project directory first.
+4. \`fjall connect --environment production --region <region> --agent\`
+   -> Opens the CloudFormation URL in the user's browser and polls for
+      completion. **This command blocks** until the stack finishes (~3 min).
+      If the browser doesn't open, the URL is printed \u2014 show it to the user.
+   -> Run with a **10-minute timeout** (the stack takes ~3 minutes).
+   -> On success, the connection is fully registered and targets are available.
+5. \`fjall deploy account --agent\`
+   -> Deploys the scaffolded account infrastructure to AWS.
+6. Now the base infrastructure is live. Ask if they want to create an app
+   (see **Recipe: Create and Deploy an Application** below).
+
+### Path B: Organisation
+1. \`fjall login --device --agent\`   (skip if authenticated)
+2. Ask for: organisation name, admin email, and primary region.
+3. \`fjall create org --name "<name>" --email "<email>" --primary-region <region> --agent\`
+   -> Scaffolds \`fjall/organisation/\`, \`fjall/platform/\`, \`fjall/account/\`.
+   -> Confirm the user is in the correct project directory first.
+4. \`fjall connect --environment production --region <region> --agent\`
+   -> Same blocking CloudFormation flow as Path A (see step 4 above).
+5. \`fjall deploy organisation --agent\`
+   -> Cascades: organisation \u2192 platform \u2192 accounts. This is a single
+      command \u2014 do NOT deploy each level separately.
+6. Now the base infrastructure is live. Ask if they want to create an app
+   (see **Recipe: Create and Deploy an Application** below).
+
+### Recipe: Create and Deploy an Application
+
+Walk the decision tree below. **Do not skip steps** \u2014 each resolves
+information the next step needs. Skipping detect or dry-run is the #1
+cause of scaffold failures.
+
+**Common mistakes to avoid:**
+
+- \`--pattern\` is the **framework** (\`nextjs\`, \`payload\`), NOT the compute
+  model. There is no \`--pattern ecs\`. ECS vs Lambda is determined by the
+  pattern + tier combination.
+- \`--tier\` sets the **infrastructure tier** (\`tinkerer\`,
+  \`lightweight\`, \`standard\`, \`resilient\`, \`enterprise\`). Do NOT pass
+  these values via \`--type\` \u2014 that flag is for legacy template mode only.
+- \`--into <path>\` sets the repo root the scaffold writes into. The output
+  lands at \`<into>/fjall/<app-name>/\`. **You must also \`cd\` to the
+  \`--into\` path** (or its parent) before running the command \u2014 the CLI
+  resolves the config root from cwd, and a cwd mismatch causes files to
+  land in the wrong project.
+- \`--dockerfile <path>\` is resolved relative to the \`--into\` directory
+  (or cwd if no \`--into\`), NOT relative to the agent's working directory.
+  Use a path relative to the target repo root, e.g. \`apps/website/Dockerfile\`.
+
+**Step 1 \u2014 Detect the repo (MANDATORY for existing repos).** Run:
+\`fjall apps detect <path> --output json --agent\`
+
+This returns the framework, monorepo tool, Dockerfile presence, inferred
+port, and \`suggestedConfigPath\` for each app. Use these values to seed
+\`--pattern\` and \`--name\` in the create command. Do NOT guess the pattern
+from the user's description \u2014 always use what detect reports.
+
+**Step 2 \u2014 Pick the tier.** Tier governs blast radius and cost.
+- \`tinkerer\` \u2014 smallest viable; single-AZ, no LB.
+- \`lightweight\` \u2014 LB-only validation env. **Default for "is this app
+  deployable?" smoke tests.**
+- \`standard\` \u2014 typical production profile.
+- \`resilient\` / \`enterprise\` \u2014 multi-AZ, multi-region.
+
+Pass via \`--tier <tier>\`. Use \`--pattern-domain <domain>\` for a
+custom domain or omit for none.
+
+**Step 3 \u2014 Pick the target account.** If more than one provider account
+is connected, the scaffold needs to know which one will deploy this app.
+- \`fjall accounts list --output json --agent\` \u2014 see candidates.
+- Pass \`--target <account-name>\` to \`apps create\`.
+- If only one candidate exists, the CLI auto-resolves it.
+
+**Step 4 \u2014 Optional: pick a network preset.**
+\`--network <lightweight|standard|resilient|enterprise|none>\`. Most apps
+inherit from the tier; only set this when an app needs different network
+topology from its tier default.
+
+**Step 5 \u2014 Preview the scaffold (MANDATORY).** Before writing anything,
+run with \`--dry-run\` to get a TOON preview of the planned files, npm
+packages, and registry actions. Nothing is written, no API call is made,
+no dependencies are installed. **Never skip this step.**
+
+When using \`--into\`, \`cd\` to the target repo root first:
+
+\`\`\`bash
+cd <repo-path>
+fjall apps create \\
+  --name <app> \\
+  --pattern <nextjs|payload|...> \\
+  --tier <tier> \\
+  [--pattern-domain <domain>] \\
+  [--network <preset>] \\
+  [--database] \\
+  [--dockerfile <relative-path-from-repo-root>] \\
+  [--container-port <port>] \\
+  [--container <monorepo-subdir>] \\
+  --into <repo-path> \\
+  [--target <account>] \\
+  --dry-run --agent
+\`\`\`
+
+Scaffold paths follow the \`fjall/\` marker convention \u2014 \`fjall/<name>/infrastructure.ts\`
+at the repo root by default, or \`<container>/fjall/<name>/infrastructure.ts\` when the
+optional \`--container\` flag is supplied (useful in monorepos where infrastructure
+lives under a workspace directory like \`services/\` or \`apps/\`).
+
+The TOON output includes \`fileCount\`, a \`files[]\` list with paths and
+sizes, \`npmPackages[]\`, and \`registryActions[]\`. **Verify that \`path\`
+in the output points inside the target repo**, not somewhere else. If
+it doesn't, the cwd is wrong. Review files against the user's intent.
+If anything looks wrong (file would clobber an existing path, wrong
+tier, missing service), refine the flags and re-run \`--dry-run\` until
+the preview matches.
+
+If the output contains \`patternUnsupportedForDryRun: true\`, the
+scaffold relies on a registry clone whose file list is only available
+after apply \u2014 confirm the high-level shape (\`mode\`, \`pattern\`,
+\`registryActions\`) and proceed.
+
+**Step 6 \u2014 Apply.** Drop \`--dry-run\` and run again with the same flags
+(same cwd) to write the scaffold, register the application, and install
+dependencies.
+
+For a fresh-start single-template app the older form still works:
+\`fjall apps create --name <app> --template <template> --agent\`.
+
+**Step 7 \u2014 Deploy:** \`fjall deploy <app> --agent\`.
+
+**Worked example \u2014 "point at ansa, scaffold a lightweight LB-only env":**
+1. \`fjall apps detect /Users/paul/Code/fjall/ansa --output json --agent\`
+   \u2192 reports \`monorepo: npm-workspaces\`, \`apps/website\` is
+   \`nextjs+payload\` with Dockerfile at \`apps/website/Dockerfile\`,
+   port 3000.
+2. \`fjall accounts list --output json --agent\` \u2192 one candidate,
+   auto-resolved.
+3. \`cd /Users/paul/Code/fjall/ansa\` \u2190 **must cd to the --into target**
+4. \`fjall apps create --name ansa-web --pattern payload --tier lightweight --database --dockerfile apps/website/Dockerfile --container-port 3000 --into /Users/paul/Code/fjall/ansa --dry-run --agent\`
+   \u2192 review TOON: verify \`path\` is inside ansa repo, check \`fileCount\`,
+   \`registryActions[]\`. Confirm with the user.
+5. Same command without \`--dry-run\` \u2192 scaffold writes to
+   \`ansa/fjall/ansa-web/\` (or pass \`--container apps\` to land
+   under \`ansa/apps/fjall/ansa-web/\` to match the existing
+   monorepo layout).
+6. \`fjall deploy ansa-web --agent\`
+
+After each step, summarise the TOON \`status\` and any \`help[]\` hints for the
+user. On a non-zero exit, quote the \`error\` field and offer the suggested fix.
+
+If you lose context mid-recipe, run:
+- \`fjall list --agent\`           (what resources exist?)
+- \`fjall target list --agent\`    (what AWS accounts are connected?)
+
+## Recipe: Deploy Changes
+1. \`fjall status <app> --agent\`
+2. \`fjall deploy <app> --agent\`
+
+## Recipe: Manage Secrets
+1. \`fjall secrets list --app <app> --agent\`
+2. \`fjall secrets set KEY=value --app <app> --agent\`
+3. \`fjall deploy <app> --agent\`      (secrets injected on next deploy)
+
+## Recipe: Add a Database
+1. \`fjall add database --app <app> --agent\`
+2. \`fjall deploy <app> --agent\`
+
+## Recipe: Recover from a Failed Deploy
+1. \`fjall status <app> --agent\`                 (which step failed?)
+2. \`fjall deploy logs --deployment-id <id> --agent\`   (recent events \u2014 id from \`fjall status\`)
+3. Ask the user: retry, rollback (\`fjall destroy\` + redeploy), or investigate.
+
+## Global Flags
+- \`--agent\` \u2014 TOON output (always use for parsing).
+- \`--budget compact|minimal|<tokens>\` \u2014 cap output size.
+- \`--fields <csv>\` \u2014 select specific fields.
+- \`--verbose\` \u2014 diagnostic output (masks credentials).
+
+## Flags Appendix (for composition beyond recipes)
+When the user asks for something outside these recipes, compose from these
+primitives. Always pass \`--agent\`.
+
+| Command | Key flags |
+|---------|-----------|
+| \`fjall create org\` | \`--name\`, \`--email\`, \`--primary-region\`, \`--secondary-regions\`, \`--disaster-recovery-region\`, \`--security <foundation\\|compliance\\|hardened>\` |
+| \`fjall create account\` | \`--primary-region\` |
+| \`fjall connect\` | \`--region\`, \`--environment <production\\|staging\\|development\\|platform\\|compliance>\`, \`--name\` |
+| \`fjall apps create\` | \`--name\`, \`--type\`, \`--template <nextjs\\|payload\\|dockerfile\\|api>\`, \`--pattern\`, \`--tier <tinkerer\\|lightweight\\|standard\\|resilient\\|enterprise>\`, \`--pattern-domain\`, \`--network <lightweight\\|standard\\|resilient\\|enterprise\\|none>\`, \`--into <repo-path>\`, \`--target <account-name>\`, \`--file-override <path>=<base64>\`, \`--dry-run\`, \`--database\`, \`--git\`, \`--github\`, \`--repo-visibility\` |
+| \`fjall apps detect\` | (positional path), \`--output json\` |
+| \`fjall accounts list\` | \`--output json\` |
+| \`fjall deploy\` | \`--infra-only\`, \`--deploy-only\`, \`--skip-build\`, \`--environment\`, \`--target\`, \`--region\`, \`--all-regions\`, \`--no-cascade\` |
+| \`fjall secrets set\` | \`--app\`, \`--cluster\`, \`--service\`, \`--lambda\`, \`--from-file\` |
+| \`fjall add <type>\` | \`--app\`, \`--name\`, variadic \`--<property> <value>\` |
+| \`fjall target set\` | (positional name) |
+
+## Environment Detection
+Fjall auto-detects these agent environments:
+
+| Agent | Env Var |
+|-------|---------|
+| Claude Code | \`CLAUDECODE\` |
+| Codex | \`CODEX_SANDBOX\` |
+| Cursor | \`CURSOR_AGENT\` |
+| GitHub Copilot | \`COPILOT_MODEL\` |
+| Generic | \`AI_AGENT\` |
+
+The \`--agent\` flag is still recommended for explicitness and portability.
+
+## Session Hooks
+
+\`\`\`bash
+fjall agent install-hooks    # Install ambient-context hooks
+fjall agent uninstall-hooks  # Remove hooks
+\`\`\`
+
+## If your host doesn't load SKILL files
+
+This SKILL is the primary, validated agent surface. If your host (Claude
+Desktop, Cursor, Cline, Continue, Zed, etc.) cannot load skill files,
+Fjall ships a beta MCP server (\`@fjall/mcp\`, \`fjall-mcp\` binary,
+\`0.1.0-beta.1\`) that exposes 9 production tools that map to the same
+CLI commands: \`create_organisation\`, \`add_resource\`, \`deploy\`,
+\`destroy\`, \`list_resources\`, \`manage_profile\`, \`detect_app_framework\`,
+\`plan_app_scaffold\`, \`apply_app_scaffold\`. The MCP shells out to the
+same \`fjall\` CLI, so authentication, masking, and exit-code semantics
+are identical.
+
+The scaffold trio (\`detect_app_framework\` \u2192 \`plan_app_scaffold\` \u2192
+\`apply_app_scaffold\`) supports the same plan\u2192review\u2192apply loop the
+SKILL recipe teaches above, with \`fjall://plans/{planId}\` resources,
+elicitation for ambiguous target accounts, and \`notifications/progress\`
+streaming during apply. Use the SKILL+CLI path above when available;
+fall back to the MCP only when the host lacks SKILL support.
+See \`mcp/README.md\` for the beta surface and known gaps.
+`}export{E as generateAgentFiles};

package/bin/assets/src/util/agent/agentOutput.d.ts

@@ -0,0 +1,61 @@
+/**
+ * AgentOutputWriter — the sole stdout-facing adapter for AXI agent mode.
+ *
+ * This class owns ALL TOON writes to stdout. It is the SINGLE masking
+ * boundary (synthesis §1.11): every public method masks string data via
+ * `maskSensitiveOutput` before passing it to the formatter. Neither the
+ * formatter nor the callback layer performs masking.
+ *
+ * Diagnostics go to stderr via `logDiagnostic`, never stdout.
+ */
+import type { AgentError, AgentSchema, ActionRequired, StreamEvent, TabularSchema } from "./schemas/types.js";
+import { type SuggestionContext } from "./suggestions.js";
+export interface AgentOutputWriterOptions {
+    readonly command: string;
+    readonly flags: Readonly<Record<string, string>>;
+    readonly verbose?: boolean;
+    readonly full?: boolean;
+    readonly writeFn?: (chunk: string) => void;
+}
+/**
+ * Severity levels understood by `logDiagnostic`. Mirrors the logger's
+ * leveled methods; unspecified level defaults to `debug` to preserve the
+ * existing noise floor.
+ */
+export type DiagnosticLevel = "debug" | "info" | "warn" | "error";
+export declare class AgentOutputWriter {
+    private readonly write;
+    private readonly resolver;
+    private readonly verbose;
+    private readonly full;
+    constructor(options: AgentOutputWriterOptions);
+    /** Whether `--full` was set, disabling content truncation. */
+    get isFullOutput(): boolean;
+    renderResult<T>(data: T, options?: {
+        schema?: AgentSchema;
+        suggestionContext?: SuggestionContext;
+    }): void;
+    renderListResult<T>(items: readonly T[], tabular: TabularSchema<T>, meta: {
+        entity: string;
+        aggregates?: Record<string, number | string>;
+        suggestionContext?: SuggestionContext;
+        fields?: readonly string[];
+    }): void;
+    renderEvent(event: StreamEvent): void;
+    emitEventSeparator(): void;
+    renderError(error: AgentError, suggestionContext?: SuggestionContext): void;
+    renderActionRequired(action: ActionRequired, suggestionContext?: SuggestionContext): void;
+    /**
+     * Write a diagnostic message to stderr. Never writes to stdout.
+     *
+     * When verbose is true, output is unmasked (debug mode per
+     * security-standards). When verbose is false, strings are masked.
+     *
+     * Severity defaults to `debug` to match the Phase 0 noise floor. Callers
+     * with explicit severity (e.g. build errors, warn-level callbacks) pass
+     * `level` so the message routes to the correct logger method.
+     */
+    logDiagnostic(component: string, message: string, data?: Record<string, unknown>, level?: DiagnosticLevel): void;
+    renderHelpLines(lines: readonly string[]): void;
+    private resolveHelp;
+}

package/bin/assets/src/util/agent/agentOutput.js

@@ -0,0 +1,8 @@
+import{maskSensitiveOutput as f}from"@fjall/util";import{logger as l}from"../logger/index.js";import{BLOCK_SEPARATOR as w,renderActionRequired as b,renderError as v,renderEvent as k,renderHelp as h,renderList as E,renderObject as R}from"./toonFormatter.js";import{SuggestionResolver as A}from"./suggestions.js";function d(n){if(typeof n=="string")return f(n);if(n==null||typeof n!="object")return n;if(Array.isArray(n))return n.map(t=>d(t));if(n instanceof Date||n instanceof RegExp)return n;const e={};for(const[t,r]of Object.entries(n))e[t]=d(r);return e}class q{write;resolver;verbose;full;constructor(e){this.write=e.writeFn??(t=>{process.stdout.write(t)}),this.resolver=new A(e.command,e.flags),this.verbose=e.verbose??!1,this.full=e.full??!1}get isFullOutput(){return this.full}renderResult(e,t){const r=d(e),i=R(r),s=this.resolveHelp(t?.suggestionContext);this.write(i+s+`
+`)}renderListResult(e,t,r){const i=e.map(c=>d(c)),s=r.fields,o=s!==void 0&&s.length>0?{fields:s,project:c=>{const a=t.project(c),g={};for(const u of s)u in a&&(g[u]=a[u]);return g}}:t,m=E(i,o,{entity:r.entity,aggregates:r.aggregates}),p=this.resolveHelp(r.suggestionContext);this.write(m+p+`
+`)}renderEvent(e){const t=d(e),r=k(t);this.write(r)}emitEventSeparator(){this.write(w+`
+`)}renderError(e,t){const r={...e,message:f(e.message),...e.details!==void 0?{details:d(e.details)}:{}},i=v(r),s=this.resolveHelp(t);this.write(i+s+`
+`)}renderActionRequired(e,t){const r={...e,message:f(e.message),action:f(e.action),...e.details!==void 0?{details:d(e.details)}:{},...e.choices!==void 0?{choices:e.choices.map(o=>f(o))}:{}},i=b(r),s=this.resolveHelp(t);this.write(i+s+`
+`)}logDiagnostic(e,t,r,i="debug"){const s=this.verbose?t:f(t),o=this.verbose||r===void 0?r:d(r);switch(i){case"error":l.error(e,s,o);return;case"warn":l.warn(e,s,o);return;case"info":l.info(e,s,o);return;default:l.debug(e,s,o);return}}renderHelpLines(e){if(e.length===0)return;const t=e.map(r=>f(r));this.write(h(t)+`
+`)}resolveHelp(e){if(e===void 0)return"";const t=this.resolver.resolve(e);return t.length===0?"":`
+`+h(t)}}export{q as AgentOutputWriter};

package/bin/assets/src/util/agent/budget.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Progressive budget reducer for AXI agent output.
+ *
+ * Works on the already-rendered TOON string, stripping content until
+ * the output fits within the requested budget.
+ *
+ * Budget modes:
+ * - `minimal`  — entity count + status summary only (no list items)
+ * - `compact`  — list items with first 2 fields per row + aggregates
+ * - `<number>` — approximate token target via progressive reduction
+ */
+/**
+ * Apply a budget constraint to a rendered TOON string.
+ *
+ * @param output - The fully rendered TOON string
+ * @param budget - One of `"minimal"`, `"compact"`, or a numeric string
+ * @returns The reduced output string
+ */
+export declare function applyBudget(output: string, budget: string | undefined): string;

package/bin/assets/src/util/agent/budget.js

@@ -0,0 +1,4 @@
+function a(n){return Math.ceil(n.length/4)}const i=/^ {2,}\S.*$/gm,s=/^help\[\d+\]:.*(?:\n {2,}.*$)*/gm,o=/^[a-zA-Z][a-zA-Z0-9_]*: \S.*$/gm,m=/^[a-zA-Z][a-zA-Z0-9_]*\[\d+\]:.*$/gm;function E(n){let r=n.replace(s,"");return r=r.replace(i,""),c(r)}function d(n){let r=n.replace(s,"");return r=r.replace(i,e=>p(e,2)),c(r)}function p(n,r){const e=n.match(/^(\s*)/)?.[1]??"",t=n.trimStart().split(",").map(u=>u.trim());if(t.length<=r)return n;const f=t.slice(0,r).join(", ");return`${e}${f}`}function h(n,r){if(a(n)<=r)return n;let e=n.replace(s,"");if(e=c(e),a(e)<=r)return e;const l=new Set;for(const t of e.matchAll(m))l.add(t[0]);return e=e.replace(o,t=>l.has(t)?t:""),e=c(e),a(e)<=r||(e=e.replace(i,t=>p(t,2)),e=c(e),a(e)<=r)?e:(e=e.replace(i,""),c(e))}function c(n){return n.replace(/\n{3,}/g,`
+
+`).replace(/^\n+/,"").replace(/\n+$/,`
+`)}function _(n,r){if(r===void 0)return n;if(r==="minimal")return E(n);if(r==="compact")return d(n);const e=parseInt(r,10);return Number.isNaN(e)||e<=0?n:h(n,e)}export{_ as applyBudget};

package/bin/assets/src/util/agent/detectAgent.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Agent environment detection.
+ *
+ * Detects known AI agent environments (Claude Code, Cursor, Codex, Copilot,
+ * etc.) via environment variables and filesystem markers. Pure, side-effect
+ * free except for a cached filesystem check and a result cache.
+ *
+ * Priority ordering is load-bearing: `generic` (AI_AGENT env var) must be
+ * checked LAST so that specific agent signals take precedence. Tests assert
+ * the ordering with an explicit case for CLAUDECODE + AI_AGENT both set.
+ *
+ * TTY gate: when auto-detecting, requires `!process.stdout.isTTY`. This is
+ * deliberate and matches `isNonInteractiveMode` which gates on stdout too.
+ * Reviewer feedback flagged stdin-based gating as inconsistent. Explicit
+ * `--agent` / `--no-agent` flags bypass the TTY check.
+ */
+export interface DetectedAgent {
+    readonly name: string;
+    readonly detected: true;
+}
+/**
+ * Returns the first matching agent signal, or `undefined` if none matches.
+ * Memoised — call `resetDetectAgentCache()` in test `beforeEach` to clear.
+ */
+export declare function detectAgent(): DetectedAgent | undefined;
+/**
+ * Resets the memoisation cache. Call this in `beforeEach` in tests that
+ * manipulate `process.env` via `vi.stubEnv`. Production code should never
+ * call this.
+ */
+export declare function resetDetectAgentCache(): void;
+/**
+ * Options that influence agent-mode activation. Explicit `options.agent`
+ * (true or false) is a hard override — detection is not consulted.
+ */
+export interface AgentModeOptions {
+    readonly agent?: boolean;
+}
+/**
+ * Returns true when the CLI should activate agent output mode.
+ *
+ * Priority (reviewer-confirmed):
+ * 1. Explicit `options.agent === true` → always on, regardless of TTY
+ * 2. Explicit `options.agent === false` → always off, hard override
+ * 3. Auto-detection: an agent signal is present AND `stdout` is not a TTY
+ *
+ * Stdout-based (not stdin-based) TTY gate matches `isNonInteractiveMode`
+ * for consistency. A developer running with `CLAUDECODE=1` in a real
+ * terminal does NOT auto-enter agent mode — `stdout.isTTY` is true.
+ */
+export declare function isAgentMode(options?: AgentModeOptions): boolean;

package/bin/assets/src/util/agent/detectAgent.js

@@ -0,0 +1 @@
+import{existsSync as r}from"node:fs";import{logger as s}from"../logger/index.js";function c(e){try{return r(e)}catch(t){return s.debug("Agent","safeExistsSync swallowed error",{path:e,error:t instanceof Error?t.message:String(t)}),!1}}const o=[{name:"claude-code",detect:()=>!!process.env.CLAUDECODE||!!process.env.CLAUDE_CODE},{name:"cowork",detect:()=>!!process.env.CLAUDE_CODE_IS_COWORK},{name:"codex",detect:()=>!!process.env.CODEX_SANDBOX||!!process.env.CODEX_CI||!!process.env.CODEX_THREAD_ID},{name:"cursor",detect:()=>!!process.env.CURSOR_TRACE_ID||!!process.env.CURSOR_AGENT||process.env.CURSOR_EXTENSION_HOST_ROLE==="agent-exec"},{name:"gemini",detect:()=>!!process.env.GEMINI_CLI},{name:"copilot",detect:()=>!!process.env.COPILOT_MODEL||!!process.env.COPILOT_ALLOW_ALL||!!process.env.COPILOT_GITHUB_TOKEN},{name:"devin",detect:()=>c("/opt/.devin")},{name:"replit",detect:()=>!!process.env.REPL_ID},{name:"augment",detect:()=>!!process.env.AUGMENT_AGENT},{name:"opencode",detect:()=>!!process.env.OPENCODE_CLIENT},{name:"generic",detect:()=>!!process.env.AI_AGENT}];let n=null;function d(){if(n!==null)return n;for(const e of o)if(e.detect())return n={name:e.name,detected:!0},n;n=void 0}function i(){n=null}function u(e){return e?.agent===!0?!0:e?.agent===!1||d()===void 0?!1:!process.stdout.isTTY}export{d as detectAgent,u as isAgentMode,i as resetDetectAgentCache};

package/bin/assets/src/util/agent/errorCodeMap.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Maps known service error classes to agent error codes. This provides
+ * deterministic error classification for typed service errors, bypassing
+ * the regex fallback in `errorCodes.ts`.
+ *
+ * The regex fallback still runs for unrecognised error classes and for
+ * raw string errors. This map simply short-circuits the lookup for known
+ * types, improving accuracy and avoiding false matches.
+ */
+import type { AgentErrorCode } from "./errorCodes.js";
+/**
+ * Attempt to map an error to an agent error code via its class name.
+ * Returns `undefined` if the error class is not in the map, signalling
+ * the caller should fall through to the regex path.
+ */
+export declare function mapErrorClassToCode(error: unknown): AgentErrorCode | undefined;

package/bin/assets/src/util/agent/errorCodeMap.js

@@ -0,0 +1 @@
+const E={AppQueryError:"NOT_FOUND",SecretsError:"VALIDATION_ERROR",UserError:"VALIDATION_ERROR",ApiError:"UNKNOWN",AuthenticationError:"AUTH_REQUIRED",CloudFormationError:"AWS_ERROR",CredentialError:"AUTH_REQUIRED",DeploymentError:"DEPLOY_FAILED",ValidationError:"VALIDATION_ERROR",ZodError:"VALIDATION_ERROR",DomainError:"NOT_FOUND",CreateError:"VALIDATION_ERROR",RestoreError:"AWS_ERROR",ImportError:"NOT_FOUND",MonitoringMetadataError:"UNKNOWN"},O={AppQueryError:{not_found:"NOT_FOUND",api_error:"NETWORK_ERROR",credential_error:"AUTH_REQUIRED",general:"UNKNOWN"},SecretsError:{not_found:"NOT_FOUND",invalid_namespace:"VALIDATION_ERROR",general:"UNKNOWN"},UserError:{not_found:"NOT_FOUND",already_exists:"CONFLICT",general:"UNKNOWN"},DomainError:{not_found:"NOT_FOUND",already_exists:"CONFLICT",parse_error:"VALIDATION_ERROR",deploy_error:"DEPLOY_FAILED",verification_error:"TIMEOUT",validation_error:"VALIDATION_ERROR",import_error:"AWS_ERROR",export_error:"AWS_ERROR"},CreateError:{already_exists:"CONFLICT",not_found:"NOT_FOUND",generation_error:"UNKNOWN",dependency_error:"UNKNOWN",validation_error:"VALIDATION_ERROR",authentication_error:"AUTH_REQUIRED"},RestoreError:{not_found:"NOT_FOUND",permission_denied:"FORBIDDEN",validation_error:"VALIDATION_ERROR",aws_error:"AWS_ERROR",no_recovery_points:"NOT_FOUND"},ImportError:{APP_NOT_FOUND:"NOT_FOUND",MISSING_INFRASTRUCTURE_FILE:"NOT_FOUND",NO_RESOURCES:"NOT_FOUND",NO_RESOURCES_SELECTED:"VALIDATION_ERROR",MULTIPLE_RESOURCES:"VALIDATION_ERROR",DISCOVERY_FAILED:"AWS_ERROR",GENERATION_FAILED:"AWS_ERROR",SYNTHESIS_FAILED:"AWS_ERROR",MAPPING_FAILED:"AWS_ERROR",CDK_IMPORT_FAILED:"AWS_ERROR",IMPORT_FAILED:"AWS_ERROR"},MonitoringMetadataError:{captureMonitoringMetadata:"AWS_ERROR",sendMonitoringMetadata:"NETWORK_ERROR"}};function _(r){if(r==null||typeof r!="object")return;const e=("name"in r&&typeof r.name=="string"?r.name:void 0)??r.constructor?.name;if(e===void 0||e==="Error")return;const o=E[e];if(o===void 0)return;const R=O[e];if(R!==void 0){const n="errorType"in r&&typeof r.errorType=="string"?r.errorType:"code"in r&&typeof r.code=="string"?r.code:"operation"in r&&typeof r.operation=="string"?r.operation:void 0;if(n!==void 0&&R[n]!==void 0)return R[n]}return o}export{_ as mapErrorClassToCode};

package/bin/assets/src/util/agent/errorCodes.d.ts

@@ -0,0 +1,48 @@
+/**
+ * AXI agent error codes — stable machine-readable strings returned to agents
+ * in TOON error blocks. Never leaks internal error class names.
+ *
+ * Pattern ordering is load-bearing: most-specific patterns FIRST, so that
+ * messages like "CloudFormation update failed: Parameter validation failed"
+ * resolve to AWS_ERROR rather than VALIDATION_ERROR. Run
+ * `errorCodes.test.ts` after any change to confirm the golden fixtures still
+ * resolve to their expected codes.
+ *
+ * Rationale for single closed enum: agents branch on these codes, so they
+ * must be stable across releases. New codes are additive only. Removing or
+ * renaming a code is a breaking change.
+ */
+export declare const AGENT_ERROR_CODES: {
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    readonly AUTH_EXPIRED: "AUTH_EXPIRED";
+    readonly NO_AWS_ACCOUNT: "NO_AWS_ACCOUNT";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly DEPLOY_FAILED: "DEPLOY_FAILED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly AWS_ERROR: "AWS_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly CONFLICT: "CONFLICT";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly BUILDX_UNAVAILABLE: "BUILDX_UNAVAILABLE";
+    readonly UNKNOWN: "UNKNOWN";
+};
+export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[keyof typeof AGENT_ERROR_CODES];
+/**
+ * Maps an arbitrary error-shaped value to a stable agent error code.
+ * Accepts `unknown` because callback-surfaced errors are sometimes strings
+ * or shaped objects, not `Error` instances.
+ *
+ * Pattern matching order: explicit class-name checks first (via
+ * `errorCodeMap.ts`), then message regex fallback. Never throws; returns
+ * `UNKNOWN` on non-matching input.
+ */
+export declare function mapErrorToCode(error: unknown): AgentErrorCode;
+/**
+ * Indicates whether an agent error represents a state the agent cannot
+ * resolve without human intervention. Used by the TOON `action_required`
+ * block to set `userActionRequired`.
+ */
+export declare function isUserActionRequired(code: AgentErrorCode): boolean;
+export declare function extractMessage(error: unknown): string;

package/bin/assets/src/util/agent/errorCodes.js

@@ -0,0 +1 @@
+import{mapErrorClassToCode as E}from"./errorCodeMap.js";const r={AUTH_REQUIRED:"AUTH_REQUIRED",AUTH_EXPIRED:"AUTH_EXPIRED",NO_AWS_ACCOUNT:"NO_AWS_ACCOUNT",NOT_FOUND:"NOT_FOUND",VALIDATION_ERROR:"VALIDATION_ERROR",DEPLOY_FAILED:"DEPLOY_FAILED",NETWORK_ERROR:"NETWORK_ERROR",AWS_ERROR:"AWS_ERROR",TIMEOUT:"TIMEOUT",CONFLICT:"CONFLICT",RATE_LIMITED:"RATE_LIMITED",FORBIDDEN:"FORBIDDEN",BUILDX_UNAVAILABLE:"BUILDX_UNAVAILABLE",UNKNOWN:"UNKNOWN"},R=[{pattern:/throttl|rate.?limit/i,code:"RATE_LIMITED"},{pattern:/buildx (?:unavailable|not (?:installed|found))|docker buildx version/i,code:"BUILDX_UNAVAILABLE"},{pattern:/token.+(expired|invalid)|session.+expired/i,code:"AUTH_EXPIRED"},{pattern:/already authenticated/i,code:"CONFLICT"},{pattern:/not.?logged.?in|no.+credentials|authenticat/i,code:"AUTH_REQUIRED"},{pattern:/access.?denied|not authorized to|forbidden/i,code:"FORBIDDEN"},{pattern:/no.+aws.+account/i,code:"NO_AWS_ACCOUNT"},{pattern:/network|econnrefused|etimedout|enotfound/i,code:"NETWORK_ERROR"},{pattern:/timed.?out|timeout/i,code:"TIMEOUT"},{pattern:/already exists/i,code:"CONFLICT"},{pattern:/not.?found|does not exist/i,code:"NOT_FOUND"},{pattern:/cloudformation|cfn|^aws\.|aws::|resourcenotready/i,code:"AWS_ERROR"},{pattern:/validation failed|invalid parameter|is required/i,code:"VALIDATION_ERROR"}],a=new Set(["AUTH_REQUIRED","AUTH_EXPIRED","FORBIDDEN","BUILDX_UNAVAILABLE"]);function s(e){const t=E(e);if(t!==void 0)return t;const n=d(e);if(n==="")return"UNKNOWN";for(const{pattern:o,code:i}of R)if(o.test(n))return i;return"UNKNOWN"}function N(e){return a.has(e)}function d(e){if(e==null)return"";if(typeof e=="string")return e;if(e instanceof Error)return e.message;if(typeof e=="object"&&"message"in e){const t=e.message;return typeof t=="string"?t:String(t)}return String(e)}export{r as AGENT_ERROR_CODES,d as extractMessage,N as isUserActionRequired,s as mapErrorToCode};

package/bin/assets/src/util/agent/fieldSelection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Field selection parser for AXI `--fields` flag.
+ *
+ * Parses a comma-separated field list, validates each field against the
+ * command's AgentSchema, and merges with the schema's defaultFields.
+ */
+import type { AgentSchema } from "./schemas/types.js";
+/**
+ * Parse and resolve a `--fields` argument against an AgentSchema.
+ *
+ * When `fieldsArg` is undefined, returns the schema's `defaultFields`.
+ * When provided, validates each requested field exists in either
+ * `defaultFields` or `extraFields`, then returns the union of
+ * `defaultFields` and the valid requested fields. Invalid fields are
+ * silently dropped — the agent can inspect the returned list to see
+ * what was resolved.
+ *
+ * @param fieldsArg - Comma-separated field list from `--fields`, or undefined
+ * @param schema - The command's AgentSchema describing available fields
+ * @returns Resolved field list (defaults + validated extras), deduplicated
+ */
+export declare function parseFieldSelection(fieldsArg: string | undefined, schema: AgentSchema): string[];

package/bin/assets/src/util/agent/fieldSelection.js

@@ -0,0 +1 @@
+function o(n,t){const l=[...t.defaultFields];if(n===void 0)return l;const i=n.split(",").map(e=>e.trim()).filter(e=>e.length>0),s=new Set([...t.defaultFields,...Object.keys(t.extraFields)]),d=new Set(l);for(const e of i)s.has(e)&&d.add(e);return[...d]}export{o as parseFieldSelection};

package/bin/assets/src/util/agent/getSurface.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Surface classifier for prerequisite-gate routing.
+ *
+ * Different CLI surfaces consume the same prerequisite failure (e.g. buildx
+ * not installed) in different shapes:
+ *   - interactive  → render an Ink screen with [Retry] [Cancel]
+ *   - non-interactive → write a human-readable error to stderr, exit 64
+ *   - ci           → same as non-interactive (no TTY → no Ink screen)
+ *   - agent        → emit a TOON error block via AgentOutputWriter
+ *
+ * Precedence (most-specific-first; deliberately does not match
+ * `isNonInteractiveMode` which collapses agent into non-interactive):
+ *   1. agent            — `isAgentMode()` true
+ *   2. non-interactive  — explicit `--non-interactive` flag
+ *   3. ci               — `process.env.CI` non-empty OR `!process.stdout.isTTY`
+ *   4. interactive      — default
+ *
+ * Empty-string `CI` env is rejected per `robustness-standards.md` § "Environment
+ * Variable Truthy Checks" — Kubernetes ConfigMaps and compose env-files can
+ * legitimately export `CI=""` for an inherited-and-cleared variable.
+ */
+export type Surface = "interactive" | "non-interactive" | "ci" | "agent";
+export interface GetSurfaceOptions {
+    readonly nonInteractive?: boolean;
+    readonly agent?: boolean;
+}
+export declare function getSurface(opts?: GetSurfaceOptions): Surface;

package/bin/assets/src/util/agent/getSurface.js

@@ -0,0 +1 @@
+import{isAgentMode as t}from"./detectAgent.js";function c(e){if(t({agent:e?.agent}))return"agent";if(e?.nonInteractive===!0)return"non-interactive";const n=process.env.CI;return n!==void 0&&n!==""||!process.stdout.isTTY?"ci":"interactive"}export{c as getSurface};

package/bin/assets/src/util/agent/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Public API barrel for the AXI agent output layer.
+ *
+ * This module is CLI-internal. It MUST NOT be imported by the webapp
+ * package — `detectAgent.ts` uses `node:fs` directly, and several future
+ * submodules will use other Node-only APIs. The webapp consumes agent
+ * output contracts via the operations layer and TOON-formatted API
+ * responses, not by importing this barrel.
+ *
+ * Phase 0: detection + error codes + schema types.
+ * Phase 1: TOON formatter, suggestion resolver, AgentOutputWriter.
+ * Phase 1 (remaining): agent callback factory, CLI wiring.
+ */
+export { AGENT_ERROR_CODES, type AgentErrorCode, extractMessage, isUserActionRequired, mapErrorToCode } from "./errorCodes.js";
+export { type AgentModeOptions, type DetectedAgent, detectAgent, isAgentMode, resetDetectAgentCache } from "./detectAgent.js";
+export { SuggestionResolver, type SuggestionContext } from "./suggestions.js";
+export { AgentOutputWriter, type AgentOutputWriterOptions, type DiagnosticLevel } from "./agentOutput.js";
+export { createAgentOutput, type AgentCallbacksOutput } from "./agentCallbacks.js";
+export type { ActionRequired, Aggregate, AgentError, AgentSchema, FieldSource, StreamEvent, TabularSchema, TransformName } from "./schemas/index.js";
+export { mapErrorClassToCode } from "./errorCodeMap.js";
+export { getRequiredScopes, type TokenScope } from "./tokenScopes.js";
+export { applyBudget } from "./budget.js";
+export { parseFieldSelection } from "./fieldSelection.js";
+export { StreamingToonWriter } from "./streaming.js";
+export { destructiveGate, missingFlagGate, authRequiredGate, ssoGate, awsAccountGate, driftConflictGate, type DriftConflictDelta } from "./actionRequired.js";
+export { installHooks, uninstallHooks, isHookInstallDisabled, hasOptOutSentinel } from "./sessionHooks.js";
+export { generateAgentFiles } from "./agentInit.js";

package/bin/assets/src/util/agent/index.js

@@ -0,0 +1 @@
+import{AGENT_ERROR_CODES as o,extractMessage as r,isUserActionRequired as s,mapErrorToCode as a}from"./errorCodes.js";import{detectAgent as p,isAgentMode as n,resetDetectAgentCache as m}from"./detectAgent.js";import{SuggestionResolver as f}from"./suggestions.js";import{AgentOutputWriter as u}from"./agentOutput.js";import{createAgentOutput as c}from"./agentCallbacks.js";import{mapErrorClassToCode as A}from"./errorCodeMap.js";import{getRequiredScopes as R}from"./tokenScopes.js";import{applyBudget as O}from"./budget.js";import{parseFieldSelection as E}from"./fieldSelection.js";import{StreamingToonWriter as h}from"./streaming.js";import{destructiveGate as q,missingFlagGate as D,authRequiredGate as F,ssoGate as H,awsAccountGate as v,driftConflictGate as M}from"./actionRequired.js";import{installHooks as _,uninstallHooks as b,isHookInstallDisabled as w,hasOptOutSentinel as y}from"./sessionHooks.js";import{generateAgentFiles as I}from"./agentInit.js";export{o as AGENT_ERROR_CODES,u as AgentOutputWriter,h as StreamingToonWriter,f as SuggestionResolver,O as applyBudget,F as authRequiredGate,v as awsAccountGate,c as createAgentOutput,q as destructiveGate,p as detectAgent,M as driftConflictGate,r as extractMessage,I as generateAgentFiles,R as getRequiredScopes,y as hasOptOutSentinel,_ as installHooks,n as isAgentMode,w as isHookInstallDisabled,s as isUserActionRequired,A as mapErrorClassToCode,a as mapErrorToCode,D as missingFlagGate,E as parseFieldSelection,m as resetDetectAgentCache,H as ssoGate,b as uninstallHooks};