@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/deploy/hosts.js

@@ -1,4 +1,25 @@
-/** The deploy targets, as a value: the CLI's `<host>` choices and the host-only-flag table's
- *  exhaustiveness check both read it. Dependency-free, so `cli/program.ts` can import it at load
- *  time without pulling a command module. */
+/**
+ * The deploy targets, as a value: the CLI's `<host>` choices and the host-only-flag table's
+ * exhaustiveness check both read it. Dependency-free, so `cli/program.ts` can import it at load
+ * time without pulling a command module.
+ *
+ * ── ADDING A HOST ───────────────────────────────────────────────────────────
+ *
+ * Three edits: a directory beside this file (copy `fly/`: `plan.ts` pure, `run.ts` driving the host
+ * CLI behind the runner seam), its `HostDeploy` in `cli/commands/deploy/<host>.ts` (kept-file
+ * semantics, gates, the drive glue — the half that may exit the process), and its name in the array
+ * below. `deploy/` itself is a neutral kernel plus one directory per host; nothing host-specific
+ * belongs in the kernel, and no host may hold a fact about another one (a host-only flag is a row in
+ * `HOST_ONLY_FLAGS` in `cli/commands/deploy.ts`, warning elsewhere; `--tunnel` stays a usage GATE in `runDeploy`
+ * because a refusal is not a row).
+ *
+ * BEFORE writing one, read that host's docs for what it does NOT do implicitly — above all, whether
+ * a created resource is REACHABLE without a further step. On Fly, `[http_service]` declares a service and allocates
+ * no address, and v4 and v6 are separate commands, so an app with only v6 is unreachable from an IPv4-only webhook
+ * sender. The host's own docs and CLI source usually say so; read them before a real deploy has to.
+ *
+ * And when a driver PARSES what a host CLI printed: the judgement must match the GRANULARITY of the
+ * action it drives (one question per command), and "we could not read the host" is a third answer,
+ * never "absent".
+ */
 export const DEPLOY_HOSTS = ["docker", "fly", "railway", "agentcore"];

package/dist/deploy/preflight.d.ts

@@ -1,8 +1,10 @@
 import { type FastagentConfig } from "../engines/pi/config.ts";
 import { type ResolvedPlacement } from "../paths.ts";
 import { type DeclaredChannel } from "../channels/discover.ts";
+import { type DeclaredSecret } from "../declared-secrets.ts";
 import { type ContainerInput } from "./container.ts";
-/** A stderr line the CLI prints (`[fastagent] warn: …` / `[fastagent] note: …`). Host-neutral advisories. */
+import { type DeploymentSecret } from "./secrets.ts";
+/** A stderr line the CLI prints (`[fastagent] warn: …` / `[fastagent] note: …`). */
 interface DeployMessage {
     level: "warn" | "note";
     text: string;
@@ -10,29 +12,37 @@ interface DeployMessage {
 /** The resolved facts every host plan needs (the container shape, channels, model auth, ports/secrets). */
 interface DeployFacts {
     messages: DeployMessage[];
-    /** Every declared channel with the ingress its module shape says it has, custom ones included. The
-     *  ONE channel fact the plans and drivers read: a consumer that needs a subset derives it (see
-     *  {@link webhookKinds}) rather than receiving a list someone else already filtered. */
+    /** Every declared channel with the ingress its module shape says it has, custom ones included. */
     channels: DeclaredChannel[];
-    /** Whether the agent has TIME triggers — `schedules/` files or `selfSchedule` (the wake tool). Cron/wake
-     *  has no external wake-up, so the deployment must keep one machine running: the fly plan forces
-     *  `min_machines_running=1`, the railway runbook forbids App Sleeping. */
-    hasTimeTriggers: boolean;
-    /** What satisfies model auth locally — an env-var name, an OAuth/stored label, or undefined. Drives the
-     *  runbook's secret guidance and `--run`'s credential carry. For a models.json endpoint keyed from the
-     *  environment this is the VARIABLE NAME (see {@link modelCredentialCarry}), not the display label, so
-     *  the value carries like any provider key. */
+    /**
+     * `routines/` declares at least one cron — the one residency reason with an external substitute: `POST /run` lets
+     * someone else's clock run a declared routine, so an operator who wants scale-to-zero has an option here.
+     */
+    hasCron: boolean;
+    /**
+     * The deployed environment's declaration, read ONCE here so the plan side and the run side cannot disagree about
+     * what this deployment carries. The environment running `deploy` is deliberately absent from it (§9).
+     */
+    values: ReadonlyMap<string, string>;
+    /** That file, workspace-relative — the name every "set it here" message must use. */
+    valueFile: string;
+    /** What satisfies model auth locally — an env-var name, an OAuth/stored label, or undefined. */
     modelAuth: string | undefined;
-    /** The definition itself carries the model key (a models.json literal `apiKey`, or a `!command` run on
-     *  the host), so there is nothing for `--run` to carry AND nothing to gate: `fastagent login` cannot
-     *  serve a custom provider, so gating on it would strand a correctly configured agent. */
+    /**
+     * The definition itself carries the model key (a models.json literal `apiKey`, or a `!command` run on the host), so
+     * there is nothing for `--run` to carry AND nothing to gate: `fastagent login` cannot serve a custom provider, so
+     * gating on it would strand a correctly configured agent.
+     */
     modelKeyInDefinition: boolean;
+    /** Every tool/routine/channel declaration — the names the value file must supply, by declaring file. */
+    declaredSecrets: DeclaredSecret[];
+    /** The runbook's variable list: the declared names, then everything else the value file carries. */
+    secrets: DeploymentSecret[];
     /** The project-level auth file `--run` reads to carry the credential (probed with the same path). */
     authPath: string;
     /** Container facts shared by the plan and the generated Dockerfile — ONE source, so they can't drift. */
     container: ContainerInput;
     port: number;
-    extraSecrets: string[];
 }
 /** Done (facts for the host branch), or a hard gate the CLI stops on (a model that won't reach the box). */
 export type DeployPreflight = {
@@ -42,35 +52,31 @@ export type DeployPreflight = {
     ok: true;
 } & DeployFacts);
 /**
- * Run the host-neutral pre-flight. Throws on a real fault (an unreadable channels/ dir, a throwing
- * provider) — the CLI wraps the call in its `failStartup` so the fault surfaces and exits, never silently.
+ * Where a check says what it found. An ISSUE is what would crash-loop the deployed box: under `--run` the first one
+ * stops the pre-flight as its gate, generate-only prints it as a warning and goes on.
  */
-export declare function preflightDeploy(input: {
-    /** The resolved placement. `agentDir` is where channels/schedules are discovered and where the
-     *  container facts (package.json/lockfile) are read — the AGENT's manifest drives the image's install
-     *  step, never the workspace's (whose manifest belongs to its own deploy); `workspace` is the build
-     *  context (the whole tree is baked). One value, because one derives from the other: two loose
-     *  strings could be handed in disagreeing, and nothing would notice. */
+export interface DeployReport {
+    note(text: string): void;
+    warn(text: string): void;
+    issue(text: string): void;
+}
+interface PreflightInput {
     placement: ResolvedPlacement;
     config: FastagentConfig;
-    modelSpec: string | undefined;
-    /** `--run` fully deploys, so a model that won't travel is a GATE (a known crash-loop); else it warns. */
+    /** `--run` fully deploys, so a definition that resolves NO model is a GATE (a known crash-loop); else it warns. */
     run: boolean;
-    /** `--force` regenerates artifacts, so the kept-hand-written-Dockerfile apt warning does not apply. */
+    /** `--force` regenerates the artifacts fastagent OWNS, so a kept `.dockerignore`'s content checks do not apply. */
     force: boolean;
-    /** The target delivers cron slots from an external clock and holds no resident process (AgentCore):
-     *  resident-host keep-alive notes do not apply; the host branch owns its capability gates. */
+    /** The target delivers cron slots from an external clock and holds no resident process (AgentCore). */
     externalClock?: boolean;
-    /** The raw `--auth-path` flag; the chain (flag > FASTAGENT_AUTH_PATH > `<agentDir>/.secrets/auth.json`)
-     *  is resolved HERE via {@link resolveAuthPath} — the one owner, same as every serving command. */
-    authPathFlag: string | undefined;
-}): Promise<DeployPreflight>;
-/**
- * Why the resolved model won't reach the deployed box, or undefined if it will — host-neutral. `fastagent.config.ts`
- * is the model's committed home (config's charter: model / tools / http) and the only source deploy ships:
- * a `--model`/`FASTAGENT_MODEL`/`.env` value is builder-local and doesn't travel (`.env` is dockerignored),
- * so a model NOT in config crash-loops the box with "missing model". The pre-flight warns (runbook) or gates
- * (`--run`). Single source on purpose — a host env block (fly.toml `[env]`) is NOT advertised as a second home.
- */
-export declare function modelTravelIssue(configModel: string | undefined, modelSpec: string | undefined): string | undefined;
+    /**
+     * Does this target publish the serve at a URL anyone can dial? True for every host that mints one (Fly, Railway,
+     * a Docker box); false for AgentCore, where the container is reachable only through the Runtime's IAM and the
+     * forwarder's shared secret. Kept apart from {@link externalClock} on purpose — they happen to agree on AgentCore
+     * today, and answering two questions with one boolean is how the answer to one of them goes wrong later.
+     */
+    publicUrl?: boolean;
+}
+/** Run the host-neutral pre-flight. */
+export declare function preflightDeploy(input: PreflightInput): Promise<DeployPreflight>;
 export {};