agency-lang 0.11.0 → 0.12.0

package/dist/lib/agents/agency-agent/lib/models.js

@@ -326,7 +326,7 @@ async function __missingProviderEnvVar_impl(provider) {
       });
       await runner.ifElse(4, [
         {
-          condition: async () => !__eq(__stack.locals.baseVar, void 0) && (__eq(await __call(env, {
+          condition: async () => !__eq(__stack.locals.baseVar, null) && (__eq(await __call(env, {
             type: "positional",
             args: [__stack.locals.baseVar]
           }), null) || __eq(await __call(env, {
@@ -948,7 +948,7 @@ async function __resolveDetected_impl(model, fast, slow, provider) {
             });
             await runner2.ifElse(1, [
               {
-                condition: async () => __eq(__nn(__readStatic(MODELS, "MODELS", "dist/lib/agents/agency-agent/lib/models.agency")[__stack.args.provider]), void 0) && (__stack.locals.needFast || __stack.locals.needSlow),
+                condition: async () => __eq(__nn(__readStatic(MODELS, "MODELS", "dist/lib/agents/agency-agent/lib/models.agency")[__stack.args.provider]), null) && (__stack.locals.needFast || __stack.locals.needSlow),
                 body: async (runner3) => {
                   await runner3.step(0, async (runner4) => {
                     __stack.locals.known = await __callMethod(Object, "keys", {

package/dist/lib/agents/agency-agent/lib/repl.js

@@ -441,7 +441,7 @@ async function __searchSlashCommand_impl() {
       });
       await runner.ifElse(4, [
         {
-          condition: async () => !__eq(__stack.locals.choice, ``) && !__eq(__stack.locals.choice, null) && !__eq(__stack.locals.choice, void 0),
+          condition: async () => !__eq(__stack.locals.choice, ``) && !__eq(__stack.locals.choice, null) && !__eq(__stack.locals.choice, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               const __funcResult = await __call(setSearchBackend, {

package/dist/lib/agents/agency-agent/lib/search.js

@@ -2047,7 +2047,7 @@ async function __appendTool_impl(opts, tool) {
       });
       await runner.ifElse(2, [
         {
-          condition: async () => __eq(__stack.locals.base, null) || __eq(__stack.locals.base, void 0),
+          condition: async () => __eq(__stack.locals.base, null) || __eq(__stack.locals.base, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               __stack.locals.base = [];
@@ -2196,7 +2196,7 @@ async function __withWebSearch_impl(opts) {
       });
       await runner.ifElse(3, [
         {
-          condition: async () => !__eq(__stack.locals.tool, null) && !__eq(__stack.locals.tool, void 0),
+          condition: async () => !__eq(__stack.locals.tool, null) && !__eq(__stack.locals.tool, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               const __funcResult = await __call(appendTool, {
@@ -2221,7 +2221,7 @@ async function __withWebSearch_impl(opts) {
       });
       await runner.ifElse(5, [
         {
-          condition: async () => !__eq(__stack.locals.hosted, null) && !__eq(__stack.locals.hosted, void 0),
+          condition: async () => !__eq(__stack.locals.hosted, null) && !__eq(__stack.locals.hosted, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               __stack.args.opts.hostedTools = __stack.locals.hosted;
@@ -2558,7 +2558,7 @@ async function __configureSearch_impl(isLocal) {
       });
       await runner.ifElse(5, [
         {
-          condition: async () => !__eq(__stack.locals.settings.search, null) && !__eq(__stack.locals.settings.search, void 0),
+          condition: async () => !__eq(__stack.locals.settings.search, null) && !__eq(__stack.locals.settings.search, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               __stack.locals.saved = __stack.locals.settings.search.backend ?? ``;

package/dist/lib/agents/agency-agent/lib/utils/renderLLMCallResponse.js

@@ -233,7 +233,7 @@ async function __renderLLMCallResponse_impl(data) {
       });
       await runner.ifElse(2, [
         {
-          condition: async () => !__eq(__stack.args.data.output, ``) && !__eq(__stack.args.data.output, null) && !__eq(__stack.args.data.output, void 0),
+          condition: async () => !__eq(__stack.args.data.output, ``) && !__eq(__stack.args.data.output, null) && !__eq(__stack.args.data.output, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               await __callMethod(__stack.locals.response, "push", {

package/dist/lib/agents/agency-agent/tests/search.js

@@ -1912,7 +1912,7 @@ graph.node("tavilyBackendAppendsOneSearchTool", async (__state) => {
         }
       });
       await runner.step(3, async (runner2) => {
-        __stack.locals.hostedSet = !__eq(__stack.locals.opts.hostedTools, null) && !__eq(__stack.locals.opts.hostedTools, void 0);
+        __stack.locals.hostedSet = !__eq(__stack.locals.opts.hostedTools, null) && !__eq(__stack.locals.opts.hostedTools, null);
       });
       await runner.step(4, async (runner2) => {
         __stack.locals.__hoist_0 = await __call(toolCount, {
@@ -2043,7 +2043,7 @@ graph.node("offBackendLeavesOptsUnchanged", async (__state) => {
         }
       });
       await runner.step(3, async (runner2) => {
-        __stack.locals.hostedSet = !__eq(__stack.locals.opts.hostedTools, null) && !__eq(__stack.locals.opts.hostedTools, void 0);
+        __stack.locals.hostedSet = !__eq(__stack.locals.opts.hostedTools, null) && !__eq(__stack.locals.opts.hostedTools, null);
       });
       await runner.step(4, async (runner2) => {
         __stack.locals.__hoist_0 = await __call(toolCount, {

package/dist/lib/agents/agency-agent/tests/settings.js

@@ -393,7 +393,7 @@ graph.node("missingFileLoadsAsEmpty", async (__state) => {
       });
       await runner.ifElse(4, [
         {
-          condition: async () => __eq(__stack.locals.loaded.search, null) || __eq(__stack.locals.loaded.search, void 0),
+          condition: async () => __eq(__stack.locals.loaded.search, null) || __eq(__stack.locals.loaded.search, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               runner3.halt({
@@ -521,7 +521,7 @@ graph.node("corruptFileLoadsAsEmpty", async (__state) => {
       });
       await runner.ifElse(4, [
         {
-          condition: async () => __eq(__stack.locals.loaded.search, null) || __eq(__stack.locals.loaded.search, void 0),
+          condition: async () => __eq(__stack.locals.loaded.search, null) || __eq(__stack.locals.loaded.search, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               runner3.halt({

package/dist/lib/agents/eval/goalJudge.js

@@ -194,7 +194,7 @@ graph.node("main", async (__state) => {
   if (!__state.isResume) {
     __stack.args["goal"] = __state.data.goal;
     __stack.args["output"] = __state.data.output;
-    __stack.args["expected"] = __state.data.expected;
+    __stack.args["expected"] = __state.data.expected === void 0 ? `` : __state.data.expected;
   }
   try {
     await agencyStore.run({
@@ -298,7 +298,7 @@ Reserve scores above 0.5 for outputs that a careful human would accept as a corr
     };
   }
 });
-async function main(goal, output, expected, { messages, callbacks } = {}) {
+async function main(goal, output, expected = ``, { messages, callbacks } = {}) {
   return runNode({
     ctx: __globalCtx,
     nodeName: "main",

package/dist/lib/agents/optimize/mutatePrompt.js

@@ -194,7 +194,7 @@ graph.node("mutatePrompt", async (__state) => {
     __stack.args["goals"] = __state.data.goals;
     __stack.args["feedback"] = __state.data.feedback;
     __stack.args["history"] = __state.data.history;
-    __stack.args["diagnostics"] = __state.data.diagnostics;
+    __stack.args["diagnostics"] = __state.data.diagnostics === void 0 ? `` : __state.data.diagnostics;
   }
   try {
     await agencyStore.run({
@@ -306,7 +306,7 @@ graph.node("mutatePrompt", async (__state) => {
     };
   }
 });
-async function mutatePrompt(targets, goals, feedback, history, diagnostics, { messages, callbacks } = {}) {
+async function mutatePrompt(targets, goals, feedback, history, diagnostics = ``, { messages, callbacks } = {}) {
   return runNode({
     ctx: __globalCtx,
     nodeName: "mutatePrompt",

package/dist/lib/backends/typescriptBuilder/nodeWrapperParams.d.ts

@@ -0,0 +1,26 @@
+import type { TsNode } from "../../ir/tsIR.js";
+import type { FunctionParameter } from "../../types.js";
+/**
+ * The exported node wrapper's parameter list — what
+ * `async function main(name = \`fallback\`, { messages, callbacks } = {})`
+ * is built from: the node's own parameters, with their defaults so TS
+ * callers can omit them, plus the trailing options object.
+ *
+ * Emitting the parsed default straight into a parameter list is safe
+ * only because parameter defaults are LITERAL-ONLY — the AST type pins
+ * it (`defaultValue?: Literal | AgencyArray | AgencyObject`,
+ * lib/types/function.ts), and the parser rejects calls and identifiers.
+ * If defaults were ever relaxed to allow expressions, the processed
+ * default could reference runtime scope (or become an await) and this
+ * would have to switch to optional parameters resolved in the body.
+ *
+ * Note the interplay with the body-site default: on this wrapper path JS
+ * fills the parameter before `data` is built, so the body's
+ * undefined-check never fires here — it exists for goto transitions and
+ * anything else that feeds `__state.data` directly.
+ */
+export declare function nodeWrapperParams(args: FunctionParameter[], processNode: (node: NonNullable<FunctionParameter["defaultValue"]>) => TsNode): {
+    name: string;
+    typeAnnotation?: string;
+    defaultValue?: TsNode;
+}[];

package/dist/lib/backends/typescriptBuilder/nodeWrapperParams.js

@@ -0,0 +1,34 @@
+import { formatTypeHintTs } from "../../utils/formatType.js";
+import { ts } from "../../ir/builders.js";
+/**
+ * The exported node wrapper's parameter list — what
+ * `async function main(name = \`fallback\`, { messages, callbacks } = {})`
+ * is built from: the node's own parameters, with their defaults so TS
+ * callers can omit them, plus the trailing options object.
+ *
+ * Emitting the parsed default straight into a parameter list is safe
+ * only because parameter defaults are LITERAL-ONLY — the AST type pins
+ * it (`defaultValue?: Literal | AgencyArray | AgencyObject`,
+ * lib/types/function.ts), and the parser rejects calls and identifiers.
+ * If defaults were ever relaxed to allow expressions, the processed
+ * default could reference runtime scope (or become an await) and this
+ * would have to switch to optional parameters resolved in the body.
+ *
+ * Note the interplay with the body-site default: on this wrapper path JS
+ * fills the parameter before `data` is built, so the body's
+ * undefined-check never fires here — it exists for goto transitions and
+ * anything else that feeds `__state.data` directly.
+ */
+export function nodeWrapperParams(args, processNode) {
+    const params = args.map((arg) => ({
+        name: arg.name,
+        typeAnnotation: arg.typeHint ? formatTypeHintTs(arg.typeHint) : "any",
+        defaultValue: arg.defaultValue ? processNode(arg.defaultValue) : undefined,
+    }));
+    params.push({
+        name: "{ messages, callbacks }",
+        typeAnnotation: "{ messages?: any; callbacks?: any }",
+        defaultValue: ts.obj({}),
+    });
+    return params;
+}

package/dist/lib/backends/typescriptBuilder.js

@@ -57,6 +57,7 @@ function coarseKindFor(typeHint) {
 import { printTs } from "../ir/prettyPrint.js";
 import { SourceMapBuilder } from "./sourceMap.js";
 import { directRunExtraArgsCheck } from "./typescriptBuilder/directRunArgsCheck.js";
+import { nodeWrapperParams } from "./typescriptBuilder/nodeWrapperParams.js";
 import { ScopeManager } from "./typescriptBuilder/scopeManager.js";
 import { StepPathTracker } from "./typescriptBuilder/stepPathTracker.js";
 import { NameClassifier } from "./typescriptBuilder/nameClassifier.js";
@@ -2423,7 +2424,15 @@ export class TypeScriptBuilder {
         if (targetNode && targetNode.parameters.length > 0) {
             const entries = {};
             targetNode.parameters.forEach((p, i) => {
-                entries[p.name] = argNodes[i];
+                // A goto may omit trailing arguments: leave the key out of data
+                // so the node body sees undefined and applies its default.
+                // (Emitting argNodes[i] blindly put undefined into the IR and
+                // crashed the printer.) Only TRAILING omissions can reach here —
+                // AG6039 rejects a required parameter after a defaulted one, so
+                // a missing slot always belongs to a defaulted parameter.
+                if (argNodes[i] !== undefined) {
+                    entries[p.name] = argNodes[i];
+                }
             });
             dataNode = ts.obj(entries);
         }
@@ -2500,9 +2509,29 @@ export class TypeScriptBuilder {
             ts.raw(`const runner = new Runner(__ctx, __stack, { nodeContext: true, state: __stack, moduleId: ${JSON.stringify(this.moduleId)}, scopeName: ${JSON.stringify(nodeName)}, threads: __setupData.threads });`),
             ...hoistedAliases,
         ];
-        // Param assignments (only when not resuming)
+        // Param assignments (only when not resuming). A parameter default
+        // applies whenever the incoming data slot is undefined — this is the
+        // ONE site every invocation path funnels through (the exported
+        // wrapper, direct runs, and graph transitions all deliver arguments
+        // via __state.data), so defaults work identically for all of them.
+        // (On the wrapper path the wrapper's own TS default fills data first,
+        // so this ternary is a no-op there; it is what makes goto work.)
+        //
+        // Deliberately `undefined`, NOT the __UNSET sentinel def functions
+        // use: node arguments cross a serialization boundary (checkpoints,
+        // resume) where a module-level sentinel would not survive, and a
+        // missing object key reads as undefined naturally. Edge-semantic
+        // consequence, matching JS default parameters: explicitly passing
+        // undefined/omitting both take the default, whereas a def's __UNSET
+        // preserves an explicit undefined. null does NOT take the default.
         if (parameters.length > 0) {
-            const paramStmts = parameters.map((p) => ts.assign($(ts.stack("args")).index(ts.str(p.name)).done(), $(ts.runtime.state).prop("data").prop(p.name).done()));
+            const paramStmts = parameters.map((p) => {
+                const incoming = $(ts.runtime.state).prop("data").prop(p.name).done();
+                const value = p.defaultValue
+                    ? ts.ternary(ts.binOp(incoming, "===", ts.id("undefined")), this.processNode(p.defaultValue), incoming)
+                    : incoming;
+                return ts.assign($(ts.stack("args")).index(ts.str(p.name)).done(), value);
+            });
             stmts.push(ts.if(ts.raw("!__state.isResume"), ts.statements(paramStmts)));
         }
         // Body wrapped in try-catch so node errors return failure instead
@@ -3617,20 +3646,7 @@ export class TypeScriptBuilder {
         });
         for (const node of this.compilationUnit.graphNodes) {
             const args = node.parameters;
-            const fnParams = [];
-            if (args.length > 0) {
-                for (const arg of args) {
-                    const typeHint = arg.typeHint
-                        ? formatTypeHintTs(arg.typeHint)
-                        : "any";
-                    fnParams.push({ name: arg.name, typeAnnotation: typeHint });
-                }
-            }
-            fnParams.push({
-                name: "{ messages, callbacks }",
-                typeAnnotation: "{ messages?: any; callbacks?: any }",
-                defaultValue: ts.obj({}),
-            });
+            const fnParams = nodeWrapperParams(args, (n) => this.processNode(n));
             const dataObj = {};
             for (const arg of args) {
                 dataObj[arg.name] = ts.id(arg.name);

package/dist/lib/cli/deploy/bundle.d.ts

@@ -0,0 +1,37 @@
+import type { AgencyConfig } from "../../config.js";
+export type BundleFile = {
+    /** Upload key — the basename, which is all statelog's flat store keeps. */
+    name: string;
+    contents: string;
+};
+export type AgencyBundle = {
+    /** Basename of the entrypoint file, echoed as the upload's `entrypoint`. */
+    entrypoint: string;
+    files: BundleFile[];
+};
+export type CollectBundleResult = {
+    ok: true;
+    bundle: AgencyBundle;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Collect the single-file bundle for an entrypoint. Refuses agents statelog
+ * cannot host: local TypeScript/JavaScript interop imports (the server only
+ * compiles `.agency` source), and — for now — any local `.agency` import
+ * (multi-file hosting is blocked on statelog#9).
+ */
+export declare function collectAgencyBundle(entrypointPath: string, config: AgencyConfig): CollectBundleResult;
+export type ValidateResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Compile each bundle file locally for fast feedback before the upload, mirroring
+ * statelog's per-file server compile. A pass here is a pre-flight, not a
+ * guarantee the server — which may run a different agency-lang — accepts it.
+ */
+export declare function validateBundleCompiles(bundle: AgencyBundle, config: AgencyConfig): ValidateResult;

package/dist/lib/cli/deploy/bundle.js

@@ -0,0 +1,65 @@
+// Turning an entrypoint into the `.agency` source to upload, and checking it
+// compiles. Deploy is single-file for now: statelog compiles each uploaded file
+// in isolation (agencyCompiler/serveHost both use `compileSource`, which loses
+// the file's location and so can't resolve relative imports), so an agent that
+// imports another local `.agency` file cannot be hosted yet. This module refuses
+// what statelog can't serve. Multi-file is tracked in statelog#9.
+import fs from "fs";
+import path from "path";
+import { parseAgency } from "../../parser.js";
+import { compileSource } from "../../compiler/compile.js";
+import { agencyImportTargets, nonAgencyLocalImportTargets, } from "../../importPaths.js";
+/**
+ * Collect the single-file bundle for an entrypoint. Refuses agents statelog
+ * cannot host: local TypeScript/JavaScript interop imports (the server only
+ * compiles `.agency` source), and — for now — any local `.agency` import
+ * (multi-file hosting is blocked on statelog#9).
+ */
+export function collectAgencyBundle(entrypointPath, config) {
+    const entrypointAbs = path.resolve(entrypointPath);
+    if (!fs.existsSync(entrypointAbs)) {
+        return { ok: false, error: `File not found: ${entrypointAbs}` };
+    }
+    const name = path.basename(entrypointAbs);
+    const contents = fs.readFileSync(entrypointAbs, "utf-8");
+    const parsed = parseAgency(contents, config);
+    if (!parsed.success) {
+        return { ok: false, error: `Parse error in ${name}: ${parsed.message ?? "invalid Agency source"}` };
+    }
+    const interop = nonAgencyLocalImportTargets(parsed.result);
+    if (interop.length > 0) {
+        return {
+            ok: false,
+            error: `${name} imports local code ${interop.map((target) => `"${target}"`).join(", ")}. ` +
+                `Hosted agents can only use .agency files (statelog compiles the source it hosts); ` +
+                `local TypeScript/JavaScript interop can't be deployed.`,
+        };
+    }
+    const localAgencyImports = agencyImportTargets(parsed.result, { localOnly: true });
+    if (localAgencyImports.length > 0) {
+        return {
+            ok: false,
+            error: `${name} imports ${localAgencyImports.map((target) => `"${target}"`).join(", ")}. ` +
+                `Deploy is single-file for now — hosted multi-file agents aren't supported yet ` +
+                `(statelog compiles each file in isolation). Tracking: statelog#9.`,
+        };
+    }
+    return { ok: true, bundle: { entrypoint: name, files: [{ name, contents }] } };
+}
+/**
+ * Compile each bundle file locally for fast feedback before the upload, mirroring
+ * statelog's per-file server compile. A pass here is a pre-flight, not a
+ * guarantee the server — which may run a different agency-lang — accepts it.
+ */
+export function validateBundleCompiles(bundle, config) {
+    const failures = bundle.files
+        .map((file) => ({ file, result: compileSource(file.contents, config) }))
+        .filter((entry) => !entry.result.success);
+    if (failures.length === 0) {
+        return { ok: true };
+    }
+    const detail = failures
+        .map(({ file, result }) => `  ${file.name}: ${result.errors.join("; ")}`)
+        .join("\n");
+    return { ok: false, error: `Compilation failed before upload:\n${detail}` };
+}

package/dist/lib/cli/deploy/curlExamples.d.ts

@@ -0,0 +1,11 @@
+import type { Manifest } from "./uploadClient.js";
+export type CurlExample = {
+    label: string;
+    command: string;
+};
+/**
+ * One curl per endpoint: the manifest (GET), each node (POST with a body
+ * templated from its parameters), and each function (POST). Functions get an
+ * empty `{}` body because the manifest does not yet expose their parameters.
+ */
+export declare function curlExamples(serveBase: string, manifest: Manifest): CurlExample[];

package/dist/lib/cli/deploy/curlExamples.js

@@ -0,0 +1,32 @@
+// Ready-to-run curl commands for a deployed agent. Pure: manifest in, command
+// strings out. Uses a `$KEY` placeholder — never the real API key.
+const AUTH = `-H "Authorization: Bearer $KEY"`;
+const JSON_HEADER = `-H "Content-Type: application/json"`;
+/**
+ * One curl per endpoint: the manifest (GET), each node (POST with a body
+ * templated from its parameters), and each function (POST). Functions get an
+ * empty `{}` body because the manifest does not yet expose their parameters.
+ */
+export function curlExamples(serveBase, manifest) {
+    const manifestExample = {
+        label: "manifest",
+        command: `curl -s ${AUTH} "${serveBase}/list"`,
+    };
+    const nodeExamples = manifest.nodes.map((node) => ({
+        label: `node ${node.name}`,
+        command: post(`${serveBase}/node/${node.name}`, bodyTemplate(node.parameters)),
+    }));
+    const functionExamples = manifest.functions.map((fn) => ({
+        label: `function ${fn.name}`,
+        command: post(`${serveBase}/function/${fn.name}`, "{}"),
+    }));
+    return [manifestExample, ...nodeExamples, ...functionExamples];
+}
+function post(url, body) {
+    return `curl -s -X POST "${url}" ${AUTH} ${JSON_HEADER} -d '${body}'`;
+}
+/** A JSON body with one placeholder per parameter, or `{}` when there are none. */
+function bodyTemplate(parameters) {
+    const fields = parameters.map((name) => `"${name}":"…"`).join(",");
+    return `{${fields}}`;
+}

package/dist/lib/cli/deploy/deploy.d.ts

@@ -0,0 +1,29 @@
+import type { AgencyConfig } from "../../config.js";
+import type { DeployTarget, TargetProvenance } from "./target.js";
+import type { AgencyBundle } from "./bundle.js";
+import type { Manifest } from "./uploadClient.js";
+export type DeployOptions = {
+    host?: string;
+    project?: string;
+    apiKeyEnv?: string;
+    /** Preview the plan without uploading. */
+    dryRun?: boolean;
+};
+export type DeployPlan = {
+    target: DeployTarget;
+    provenance: TargetProvenance;
+    bundle: AgencyBundle;
+};
+export type DeployOutcome = {
+    kind: "error";
+    error: string;
+} | {
+    kind: "preview";
+    plan: DeployPlan;
+} | {
+    kind: "deployed";
+    plan: DeployPlan;
+    endpointUrls: string[];
+    manifest?: Manifest;
+};
+export declare function deploy(entrypointPath: string, config: AgencyConfig, options: DeployOptions): Promise<DeployOutcome>;

package/dist/lib/cli/deploy/deploy.js

@@ -0,0 +1,38 @@
+// Deploying an agent, top to bottom. This reads as the "what": resolve the
+// target, gather the source bundle, check it compiles, then upload. Each step's
+// "how" lives in its own module.
+import { resolveDeployTarget } from "./target.js";
+import { collectAgencyBundle, validateBundleCompiles } from "./bundle.js";
+import { uploadBundle } from "./uploadClient.js";
+export async function deploy(entrypointPath, config, options) {
+    const target = resolveDeployTarget(config.log, options, process.env);
+    if (!target.ok) {
+        return { kind: "error", error: target.error };
+    }
+    const bundle = collectAgencyBundle(entrypointPath, config);
+    if (!bundle.ok) {
+        return { kind: "error", error: bundle.error };
+    }
+    const compiles = validateBundleCompiles(bundle.bundle, config);
+    if (!compiles.ok) {
+        return { kind: "error", error: compiles.error };
+    }
+    const plan = {
+        target: target.target,
+        provenance: target.provenance,
+        bundle: bundle.bundle,
+    };
+    if (options.dryRun) {
+        return { kind: "preview", plan };
+    }
+    const uploaded = await uploadBundle(target.target, bundle.bundle);
+    if (!uploaded.ok) {
+        return { kind: "error", error: uploaded.error };
+    }
+    return {
+        kind: "deployed",
+        plan,
+        endpointUrls: uploaded.endpointUrls,
+        manifest: uploaded.manifest,
+    };
+}

package/dist/lib/cli/deploy/render.d.ts

@@ -0,0 +1,2 @@
+import type { DeployOutcome } from "./deploy.js";
+export declare function renderOutcome(outcome: DeployOutcome): void;

package/dist/lib/cli/deploy/render.js

@@ -0,0 +1,83 @@
+// Turning a DeployOutcome into terminal output. Presentation only: it builds the
+// coloured blocks and hands them to the deployReport template, which owns the
+// dry-run vs deployed branch. No deploy logic lives here. Each block carries its
+// own leading blank line, so the template concatenates them without whitespace
+// fiddling.
+import { color } from "../../utils/termcolors.js";
+import renderDeployReport from "../../templates/cli/deployReport.js";
+import { serveBaseUrl } from "./uploadClient.js";
+import { curlExamples } from "./curlExamples.js";
+export function renderOutcome(outcome) {
+    if (outcome.kind === "error") {
+        console.error(`\n${color.red("✗")} ${outcome.error}\n`);
+        return;
+    }
+    const deployed = outcome.kind === "deployed";
+    console.log(renderDeployReport({
+        targetBlock: targetBlock(outcome.plan),
+        filesBlock: filesBlock(outcome.plan),
+        dryRun: outcome.kind === "preview",
+        dryRunNote: `\n\n${color.yellow("dry run")} — nothing uploaded. Re-run without ${color.bold("--dry-run")} to deploy.`,
+        deployed,
+        deployedBody: deployed ? deployedBody(outcome.endpointUrls, outcome.manifest) : "",
+    }));
+}
+function targetBlock(plan) {
+    const { target, provenance } = plan;
+    const rows = [
+        targetRow("host   ", target.host, provenance.host),
+        targetRow("project", target.projectId, provenance.projectId),
+        targetRow("api key", redactKey(target.apiKey), provenance.apiKey),
+    ];
+    // Single leading blank line (it's the first block); the rest use section().
+    return "\n" + [color.bold("Deploy target"), ...rows].join("\n");
+}
+function targetRow(label, value, from) {
+    return `  ${color.dim(label)} ${value}   ${color.dim(from)}`;
+}
+function filesBlock(plan) {
+    const { bundle } = plan;
+    const header = `${color.bold(`Files (${bundle.files.length})`)}   ${color.dim(`entrypoint: ${bundle.entrypoint}`)}`;
+    const rows = bundle.files.map((file) => `  ${color.cyan(file.name)}   ${color.dim(`${Buffer.byteLength(file.contents)} bytes`)}`);
+    return section(header, rows);
+}
+/** Banner + serve endpoints + (when a manifest was fetched) curl examples. */
+function deployedBody(endpointUrls, manifest) {
+    const endpoints = section(color.bold("Serve endpoints"), endpointRows(endpointUrls));
+    const banner = `\n\n${color.green("✓ deployed")}`;
+    return banner + endpoints + curlSection(endpointUrls, manifest);
+}
+function endpointRows(endpointUrls) {
+    return endpointUrls.map((url) => `  ${color.dim(endpointLabel(url))} ${url}`);
+}
+function endpointLabel(url) {
+    if (url.includes("/node/")) {
+        return "node";
+    }
+    if (url.includes("/function/")) {
+        return "function";
+    }
+    if (url.endsWith("/list")) {
+        return "manifest";
+    }
+    return "endpoint";
+}
+function curlSection(endpointUrls, manifest) {
+    const base = serveBaseUrl(endpointUrls);
+    if (!base || !manifest) {
+        return "";
+    }
+    const header = `${color.bold("Try it")}   ${color.dim("(export KEY=<your-api-key> first)")}`;
+    const rows = curlExamples(base, manifest).flatMap((example) => [
+        `  ${color.dim(example.label)}`,
+        `    ${example.command}`,
+    ]);
+    return section(header, rows);
+}
+/** A titled block with a leading blank line, ready to concatenate. */
+function section(header, rows) {
+    return "\n\n" + [header, ...rows].join("\n");
+}
+function redactKey(apiKey) {
+    return apiKey.length <= 4 ? "••••" : `••••${apiKey.slice(-4)}`;
+}

package/dist/lib/cli/deploy/target.d.ts

@@ -0,0 +1,37 @@
+export type DeployTarget = {
+    host: string;
+    projectId: string;
+    apiKey: string;
+};
+/** Human-readable origin of each resolved field, for the deploy summary. */
+export type TargetProvenance = {
+    host: string;
+    projectId: string;
+    apiKey: string;
+};
+export type TargetOverrides = {
+    host?: string;
+    project?: string;
+    /** Name of the env var to read the API key from (never the key itself). */
+    apiKeyEnv?: string;
+};
+/** The `log` section of AgencyConfig, narrowed to the fields deploy needs. */
+export type LogConfig = {
+    host?: string;
+    projectId?: string;
+};
+export type ResolveTargetResult = {
+    ok: true;
+    target: DeployTarget;
+    provenance: TargetProvenance;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve the deploy target. Host and project come from a flag or agency.json
+ * `log.*`; the API key is read from an environment variable (the `--api-key-env`
+ * one, or `STATELOG_API_KEY` by default). Fails with everything that's missing
+ * or malformed rather than one problem at a time.
+ */
+export declare function resolveDeployTarget(log: LogConfig | undefined, overrides: TargetOverrides, env: NodeJS.ProcessEnv): ResolveTargetResult;