@agent-native/core 0.158.9 → 0.159.0

package/corpus/templates/clips/app/components/recorder/recording-toolbar.tsx

@@ -3,7 +3,7 @@ import {
   IconPlayerPause,
   IconPlayerPlay,
   IconPlayerStop,
-  IconX,
+  IconTrash,
 } from "@tabler/icons-react";
 import { useEffect, useRef, useState } from "react";
 
@@ -223,7 +223,7 @@ export function RecordingToolbar({
             className="flex h-9 w-9 items-center justify-center rounded-full hover:bg-white/15"
             aria-label={t("recordingToolbar.cancel")}
           >
-            <IconX className="h-4 w-4" />
+            <IconTrash className="h-4 w-4" />
           </button>
         </TooltipTrigger>
         <TooltipContent>{t("recordingToolbar.cancelShortcut")}</TooltipContent>

package/corpus/templates/clips/app/i18n/en-US.ts

@@ -1031,8 +1031,13 @@ All notable user-facing changes to Clips are documented here. Open it any time f
     pauseShortcut: "Pause (⌥⇧P)",
     stop: "Stop recording",
     elapsed: "Elapsed time",
-    cancel: "Cancel recording",
-    cancelShortcut: "Cancel (⌥⇧C)",
+    cancel: "Discard recording",
+    cancelShortcut: "Discard (⌥⇧C)",
+    discardConfirmTitle: "Discard this recording?",
+    discardConfirmDescription:
+      "This can't be undone. Your recording so far will be permanently deleted.",
+    resume: "Resume",
+    discardRecording: "Discard recording",
   },
   countdownOverlay: {
     startsIn: "Recording starts in {{count}}",

package/corpus/templates/clips/app/routes/record.tsx

@@ -119,6 +119,16 @@ import {
 } from "@/components/recorder/recorder-engine";
 import { RecordingToolbar } from "@/components/recorder/recording-toolbar";
 import { StorageSetupCard } from "@/components/recorder/storage-setup-card";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
 import { Button } from "@/components/ui/button";
 import { Spinner } from "@/components/ui/spinner";
 
@@ -787,6 +797,12 @@ export default function RecordRoute() {
   const [error, setError] = useState<string | null>(null);
   const [isPaused, setIsPaused] = useState(false);
   const visibilityAutoPausedRef = useRef(false);
+  const [discardConfirmOpen, setDiscardConfirmOpen] = useState(false);
+  // Tracks whether opening the discard-confirm dialog paused the recording
+  // itself (vs. the user having already paused) — so "Resume" only resumes
+  // when we're the ones who paused it, and the dialog never gets captured in
+  // the recorded screen.
+  const discardAutoPausedRef = useRef(false);
   const [cameraStream, setCameraStream] = useState<MediaStream | null>(null);
   const [cameraSize, setCameraSize] = useState<CameraBubbleSize>(
     () => loadRecorderPreferences().cameraSize ?? "md",
@@ -940,6 +956,10 @@ export default function RecordRoute() {
   } | null>(null);
   const previewVideoRef = useRef<HTMLVideoElement>(null);
   const fileUploadAbortRef = useRef<AbortController | null>(null);
+  // Set to the recording row created by uploadFile() for the duration of
+  // that upload, so doCancel() can trash it directly — createdId otherwise
+  // only lives in uploadFile's own closure and never reaches pendingRef.
+  const fileUploadRecordingIdRef = useRef<string | null>(null);
   const browserDiagnosticsRef = useRef<BrowserDiagnosticsCapture | null>(null);
   // Bumped by doCancel() to invalidate any in-flight startFlow().
   const startSessionRef = useRef(0);
@@ -1558,6 +1578,7 @@ export default function RecordRoute() {
           throw new Error("create-recording did not return an id");
         }
         createdId = info.id;
+        fileUploadRecordingIdRef.current = createdId;
         await saveBugReportContextRef.current(info.id);
         if (isStale()) throw makeAbortError("Upload cancelled");
         const uploadBase = `${appBasePath()}${info.uploadChunkUrl}`;
@@ -1817,6 +1838,9 @@ export default function RecordRoute() {
         if (fileUploadAbortRef.current === abort) {
           fileUploadAbortRef.current = null;
         }
+        if (fileUploadRecordingIdRef.current === createdId) {
+          fileUploadRecordingIdRef.current = null;
+        }
         setCompressionProgress(null);
         setUploadProgress(null);
       }
@@ -2163,10 +2187,12 @@ export default function RecordRoute() {
     startSessionRef.current += 1;
     countdownAudioCueRef.current?.cleanup();
     countdownAudioCueRef.current = null;
+    const uploadRecordingId = fileUploadRecordingIdRef.current;
     if (fileUploadAbortRef.current) {
       fileUploadAbortRef.current.abort(makeAbortError("Upload cancelled"));
       fileUploadAbortRef.current = null;
     }
+    fileUploadRecordingIdRef.current = null;
     const engine = engineRef.current;
     const pendingId = pendingRef.current?.id;
     liveTranscription.stop();
@@ -2198,6 +2224,18 @@ export default function RecordRoute() {
         body: JSON.stringify({ id: pendingId, skipIfReady: true }),
       }).catch(() => {});
     }
+    if (uploadRecordingId) {
+      // A local file import (as opposed to a live recording) never
+      // populates pendingRef — its row id only exists in uploadFile's own
+      // closure. Without this, discarding mid-upload aborts the transfer
+      // but leaves the row merely marked "failed" instead of trashed, which
+      // contradicts the confirmation dialog's "permanently deleted" copy.
+      fetch(agentNativePath("/_agent-native/actions/trash-recording"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ id: uploadRecordingId, skipIfReady: true }),
+      }).catch(() => {});
+    }
     setCameraStream(null);
     setPreviewStream(null);
     setIsPaused(false);
@@ -2229,6 +2267,56 @@ export default function RecordRoute() {
     }
   }, [liveTranscription]);
 
+  // Discarding an in-progress recording is permanent (see doCancel — it
+  // trashes the pending row with no recovery), so route it through a confirm
+  // dialog instead of firing immediately. While live, pause capture first so
+  // the confirmation itself never ends up in the recorded video.
+  const requestDiscard = useCallback(() => {
+    const engine = engineRef.current;
+    if (uiState === "recording" && engine && engine.getState() !== "paused") {
+      engine.pause();
+      liveTranscription.pause();
+      setIsPaused(true);
+      discardAutoPausedRef.current = true;
+    }
+    setDiscardConfirmOpen(true);
+  }, [uiState, liveTranscription]);
+
+  const resumeFromDiscardPrompt = useCallback(() => {
+    setDiscardConfirmOpen(false);
+    if (!discardAutoPausedRef.current) return;
+    discardAutoPausedRef.current = false;
+    const engine = engineRef.current;
+    if (!engine) return;
+    engine.resume();
+    liveTranscription.resume();
+    setIsPaused(false);
+  }, [liveTranscription]);
+
+  const confirmDiscard = useCallback(() => {
+    discardAutoPausedRef.current = false;
+    setDiscardConfirmOpen(false);
+    void doCancel();
+  }, [doCancel]);
+
+  // A background upload (e.g. importing a local video file) can finish
+  // independently of user interaction while this dialog is open -- it isn't
+  // gated behind uiState. Once the recording leaves a discardable state,
+  // Discard would be a no-op (there's nothing left for doCancel to abort or
+  // trash), so close the prompt rather than leave a misleading control open.
+  useEffect(() => {
+    if (!discardConfirmOpen) return;
+    if (
+      uiState === "recording" ||
+      uiState === "uploading" ||
+      uiState === "compressing"
+    ) {
+      return;
+    }
+    discardAutoPausedRef.current = false;
+    setDiscardConfirmOpen(false);
+  }, [uiState, discardConfirmOpen]);
+
   useEffect(() => {
     if (typeof navigator === "undefined") return;
     if (!isMobileRecorderRuntime(navigator)) return;
@@ -2299,6 +2387,7 @@ export default function RecordRoute() {
   // -------------------------------------------------------------------------
   useEffect(() => {
     function onKey(e: KeyboardEvent) {
+      if (discardConfirmOpen) return;
       const alt = e.altKey;
       const shift = e.shiftKey;
       const meta = e.metaKey;
@@ -2331,8 +2420,20 @@ export default function RecordRoute() {
         }
       }
 
-      // Opt/Alt+Shift+C — cancel
+      // Opt/Alt+Shift+C -- cancel. Route the same states that show a
+      // discard/cancel control (the recording toolbar and the
+      // uploading/compressing overlay) through the confirm dialog, so the
+      // shortcut can't bypass what the equivalent on-screen button requires.
       if (alt && shift && k === "c") {
+        if (
+          uiState === "recording" ||
+          uiState === "uploading" ||
+          uiState === "compressing"
+        ) {
+          e.preventDefault();
+          requestDiscard();
+          return;
+        }
         if (uiState !== "idle") {
           e.preventDefault();
           void doCancel();
@@ -2360,7 +2461,16 @@ export default function RecordRoute() {
     }
     window.addEventListener("keydown", onKey);
     return () => window.removeEventListener("keydown", onKey);
-  }, [uiState, togglePause, doCancel, doStop, restart, fireConfetti]);
+  }, [
+    uiState,
+    discardConfirmOpen,
+    togglePause,
+    doCancel,
+    requestDiscard,
+    doStop,
+    restart,
+    fireConfetti,
+  ]);
 
   // Query params can preselect recorder controls, but browser capture must
   // still start from the user's Start click. Calling getDisplayMedia from an
@@ -2594,10 +2704,42 @@ export default function RecordRoute() {
           isPaused={isPaused}
           onTogglePause={togglePause}
           onStop={() => void doStop()}
-          onCancel={() => void doCancel()}
+          onCancel={requestDiscard}
         />
       )}
 
+      <AlertDialog
+        open={discardConfirmOpen}
+        onOpenChange={(open) => {
+          if (!open) resumeFromDiscardPrompt();
+        }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>
+              {t("recordingToolbar.discardConfirmTitle")}
+            </AlertDialogTitle>
+            <AlertDialogDescription>
+              {t("recordingToolbar.discardConfirmDescription")}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>
+              {t("recordingToolbar.resume")}
+            </AlertDialogCancel>
+            <AlertDialogAction
+              onClick={(event) => {
+                event.preventDefault();
+                confirmDiscard();
+              }}
+              className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+            >
+              {t("recordingToolbar.discardRecording")}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+
       {/* Uploading overlay (also covers the compressing pass which can run
           for several minutes on long recordings — without a distinct copy
           users wonder if the app froze). */}
@@ -2639,10 +2781,10 @@ export default function RecordRoute() {
             </>
           )}
           <button
-            onClick={doCancel}
+            onClick={requestDiscard}
             className="mt-1 text-xs text-white/50 underline-offset-2 hover:text-white/80 hover:underline"
           >
-            Cancel
+            {t("recordingToolbar.cancel")}
           </button>
         </div>
       )}

package/dist/a2a/auth-policy.d.ts

@@ -1,9 +1,3 @@
-/**
- * A2A auth policy helpers shared by discovery, the JSON-RPC gate, and task
- * handlers. Serverless providers do not always expose `NODE_ENV=production`
- * consistently at runtime, so production-like A2A checks also look at the
- * provider flags those platforms set in deployed functions.
- */
 export declare function isA2AProductionRuntime(): boolean;
 export declare function hasConfiguredA2ASecret(): boolean;
 export declare function shouldAdvertiseJwtA2AAuth(): boolean;

package/dist/a2a/auth-policy.js

@@ -4,6 +4,7 @@
  * consistently at runtime, so production-like A2A checks also look at the
  * provider flags those platforms set in deployed functions.
  */
+import { getAppConfig } from "../app-config/index.js";
 export function isA2AProductionRuntime() {
     if (process.env.NODE_ENV === "production")
         return true;
@@ -48,7 +49,7 @@ export function shouldAdvertiseJwtA2AAuth() {
 export function isTrustedLocalRuntime(opts) {
     if (isA2AProductionRuntime())
         return false;
-    if (process.env.A2A_ALLOW_UNSIGNED_INTERNAL === "1")
+    if (getAppConfig().a2a.allowUnsignedInternal)
         return true;
     return opts.loopback === true;
 }

package/dist/a2a/client.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import * as jose from "jose";
+import { getAppConfig } from "../app-config/index.js";
 import { ssrfSafeFetch } from "../extensions/url-safety.js";
 import { canonicalA2AAudience } from "./audience.js";
 /**
@@ -9,16 +10,15 @@ import { canonicalA2AAudience } from "./audience.js";
  * itself — never a value that arrived on a request.
  */
 function workspacePrivateOrigins() {
+    const config = getAppConfig();
+    // No trimming or blank-dropping here: the config layer trims string values
+    // and `a2a.allowedOrigins` rejects empty entries, so the only thing left to
+    // drop is an unset optional.
     const origins = [
-        process.env.WORKSPACE_GATEWAY_URL,
-        process.env.APP_URL,
-        process.env.BETTER_AUTH_URL,
-        // Escape hatch for contexts that never receive the gateway manifest (the
-        // action CLI, one-off scripts). Comma-separated origins.
-        ...(process.env.AGENT_NATIVE_A2A_ALLOWED_ORIGINS ?? "").split(","),
-    ]
-        .map((value) => value?.trim())
-        .filter((value) => !!value);
+        config.workspace.gatewayUrl,
+        config.app.url,
+        ...config.a2a.allowedOrigins,
+    ].filter((value) => value !== undefined);
     // The gateway also hands each child the sibling manifest, and siblings are
     // reached on their own loopback ports rather than through the gateway.
     const raw = process.env.AGENT_NATIVE_WORKSPACE_APPS_JSON;
@@ -118,9 +118,7 @@ export async function signA2AToken(email, orgDomain, orgSecret, options) {
         throw new Error("No A2A secret available. Set an org-level A2A secret in Team settings, " +
             "or set A2A_SECRET as an environment variable on all apps that need to verify identity.");
     }
-    const appUrl = process.env.APP_URL ||
-        process.env.BETTER_AUTH_URL ||
-        "http://localhost:3000";
+    const appUrl = getAppConfig().app.url ?? "http://localhost:3000";
     const jwt = new jose.SignJWT({
         ...(options?.extraClaims ?? {}),
         // `sub` / `org_domain` are spread AFTER extraClaims so a caller-supplied

package/dist/agent/durable-background.js

@@ -38,6 +38,7 @@
  * 15-min budget.
  */
 import { hasConfiguredA2ASecret, isTrustedLocalRuntime, } from "../a2a/auth-policy.js";
+import { getAppConfig } from "../app-config/index.js";
 import { extractBearerToken, verifyInternalToken, } from "../integrations/internal-token.js";
 /**
  * Framework route the background function actually runs — sibling to
@@ -87,8 +88,8 @@ export const AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD = "__agentNativeProcessorRou
  * app id is configured (single-template deploy).
  */
 function resolveWorkspaceBackgroundFunctionUrlPath() {
-    const raw = process.env.AGENT_NATIVE_WORKSPACE_APP_ID;
-    if (typeof raw !== "string")
+    const raw = getAppConfig().app.workspaceId;
+    if (raw === undefined)
         return null;
     // Mirror the workspace app-id normalization (resources/store.ts): take the
     // first path segment and accept only the safe slug shape used for function

package/dist/agent/engine/registry.js

@@ -8,6 +8,7 @@
  * Built-in engines (anthropic, ai-sdk) are auto-registered by builtin.ts.
  */
 import { createRequire } from "node:module";
+import { getAppConfig } from "../../app-config/index.js";
 import { assertCredentialStoreReadable, canUseDeployCredentialFallbackForRequest, getBuilderCredentialAuthFailure, getProviderCredentialAuthFailure, readDeployCredentialEnv, resolveBuilderCredentialsDetailed, resolveSecret, } from "../../server/credential-provider.js";
 import { getSetting } from "../../settings/store.js";
 import { getAgentAppModelDefaultForCurrentRequest } from "../app-model-defaults.js";
@@ -281,7 +282,7 @@ function assertAgentEnginePackageInstalled(entry) {
  * markers can skip rejected deploy keys.
  */
 export function detectEngineFromEnv() {
-    const preferByo = /^(1|true)$/i.test(process.env.AGENT_ENGINE_PREFER_BYO_KEY ?? "");
+    const preferByo = getAppConfig().agent.preferBringYourOwnKey;
     if (preferByo) {
         for (const entry of _registry.values()) {
             if (entry.name === "builder")
@@ -359,7 +360,7 @@ async function hasUsableEnvKeys(entry) {
  * on `missing_credentials`.
  */
 export async function detectEngineFromEnvForRequest() {
-    const preferByo = /^(1|true)$/i.test(process.env.AGENT_ENGINE_PREFER_BYO_KEY ?? "");
+    const preferByo = getAppConfig().agent.preferBringYourOwnKey;
     if (preferByo) {
         for (const entry of _registry.values()) {
             if (entry.name === "builder")
@@ -445,7 +446,7 @@ export async function detectEngineFromUserSecrets(identity) {
         }
         return true;
     };
-    const preferByo = /^(1|true)$/i.test(process.env.AGENT_ENGINE_PREFER_BYO_KEY ?? "");
+    const preferByo = getAppConfig().agent.preferBringYourOwnKey;
     if (preferByo) {
         for (const entry of _registry.values()) {
             if (entry.name === "builder")
@@ -836,7 +837,7 @@ export async function resolveEngine(config) {
         return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, "explicit", apiKeyEnvVar, credentialIdentity));
     }
     // 4. Env var — explicit engine name override
-    const envEngine = process.env.AGENT_ENGINE;
+    const envEngine = getAppConfig().agent.engine;
     if (envEngine) {
         const entry = _registry.get(envEngine);
         if (entry) {

package/dist/agent/run-manager.js

@@ -1,3 +1,4 @@
+import { getAppConfig } from "../app-config/index.js";
 import { captureError } from "../server/capture-error.js";
 import { isLlmCredentialError, LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, } from "./engine/credential-errors.js";
 import { classifyTerminalErrorCode, describeErrorWithCauses, isProviderConnectionError, } from "./engine/error-detail.js";
@@ -376,12 +377,9 @@ export function resolveRunSoftTimeoutMs(overrideMs, options) {
     if (typeof overrideMs === "number" && Number.isFinite(overrideMs)) {
         return clampHosted(Math.max(0, overrideMs));
     }
-    const envValue = process.env.AGENT_RUN_SOFT_TIMEOUT_MS;
-    if (envValue !== undefined) {
-        const raw = Number(envValue);
-        if (Number.isFinite(raw) && raw >= 0)
-            return clampHosted(raw);
-    }
+    const configured = getAppConfig().agent.runSoftTimeoutMs;
+    if (configured !== undefined)
+        return clampHosted(configured);
     // A background-function run uses the full background budget by default; the
     // foreground default (40s) is unchanged.
     if (background) {
@@ -392,22 +390,12 @@ export function resolveRunSoftTimeoutMs(overrideMs, options) {
         : 0;
 }
 export function resolveCompletedRunRetentionMs() {
-    const envValue = process.env.AGENT_RUN_RETENTION_MS;
-    if (envValue !== undefined) {
-        const raw = Number(envValue);
-        if (Number.isFinite(raw) && raw >= 0)
-            return raw;
-    }
-    return DEFAULT_COMPLETED_RUN_RETENTION_MS;
+    return (getAppConfig().agent.completedRunRetentionMs ??
+        DEFAULT_COMPLETED_RUN_RETENTION_MS);
 }
 export function resolveErroredRunRetentionMs() {
-    const envValue = process.env.AGENT_ERRORED_RUN_RETENTION_MS;
-    if (envValue !== undefined) {
-        const raw = Number(envValue);
-        if (Number.isFinite(raw) && raw >= 0)
-            return raw;
-    }
-    return DEFAULT_ERRORED_RUN_RETENTION_MS;
+    return (getAppConfig().agent.erroredRunRetentionMs ??
+        DEFAULT_ERRORED_RUN_RETENTION_MS);
 }
 function isTerminalRunEvent(event) {
     return (event.type === "done" ||

package/dist/app-config/a2a.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+/**
+ * A2A transport policy.
+ *
+ * Deliberately does not carry `A2A_SECRET`. That value is a secret, and it is
+ * also the key-derivation root the secrets vault uses to decrypt its own rows
+ * (`secrets/crypto.ts`) — so it is read below this layer, before configuration
+ * is available. Secrets resolve through `readDeployCredentialEnv` and the
+ * vault; this domain holds only the policy toggles around them.
+ */
+export declare const a2aConfig: z.ZodObject<{
+    allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    allowUnsignedInternal: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;

package/dist/app-config/a2a.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+/**
+ * A2A transport policy.
+ *
+ * Deliberately does not carry `A2A_SECRET`. That value is a secret, and it is
+ * also the key-derivation root the secrets vault uses to decrypt its own rows
+ * (`secrets/crypto.ts`) — so it is read below this layer, before configuration
+ * is available. Secrets resolve through `readDeployCredentialEnv` and the
+ * vault; this domain holds only the policy toggles around them.
+ */
+export const a2aConfig = z.object({
+    /**
+     * Extra origins this deployment will treat as its own private siblings.
+     *
+     * Escape hatch for contexts that never receive the gateway manifest — the
+     * action CLI and one-off scripts. Only origins the deployment configured for
+     * itself belong here; a value that arrived on a request must never reach it,
+     * because these bypass the SSRF guard by construction.
+     *
+     * Entries are checked for non-emptiness but not parsed as URLs here. A
+     * validation failure in this schema throws out of `getAppConfig()`, which
+     * every config read shares — so one typo in an allow-list would stop the
+     * process booting at all rather than making one sibling unreachable.
+     * `normalizeAllowedPrivateOriginKeys` parses each entry, requires http/https,
+     * and matches on exact `hostname:port`, so a malformed entry is skipped and
+     * the private-IP guard stays closed.
+     */
+    allowedOrigins: z
+        .array(z.string().min(1))
+        .default([])
+        .meta({
+        env: ["AGENT_NATIVE_A2A_ALLOWED_ORIGINS"],
+        doc: "Comma-separated extra origins trusted as private A2A siblings.",
+    }),
+    allowUnsignedInternal: z
+        .boolean()
+        .default(false)
+        .meta({
+        env: ["A2A_ALLOW_UNSIGNED_INTERNAL"],
+        doc: "Trust unsigned internal self-dispatch on an unrecognized non-production host. Never grants trust in production.",
+    }),
+});

package/dist/app-config/agent.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/**
+ * Agent engine and model selection.
+ *
+ * These are the values `resolveEngine()` already resolves through a documented
+ * seven-step ladder. The declared field replaces step 2 of that ladder only —
+ * the explicit `engineOption` argument stays a function parameter and stays
+ * above it, because it is per-call rather than per-process.
+ */
+export declare const agentConfig: z.ZodObject<{
+    engine: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodString>;
+    preferBringYourOwnKey: z.ZodDefault<z.ZodBoolean>;
+    runSoftTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    completedRunRetentionMs: z.ZodOptional<z.ZodNumber>;
+    erroredRunRetentionMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;

package/dist/app-config/agent.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+/**
+ * Agent engine and model selection.
+ *
+ * These are the values `resolveEngine()` already resolves through a documented
+ * seven-step ladder. The declared field replaces step 2 of that ladder only —
+ * the explicit `engineOption` argument stays a function parameter and stays
+ * above it, because it is per-call rather than per-process.
+ */
+export const agentConfig = z.object({
+    engine: z
+        .string()
+        .min(1)
+        .optional()
+        .meta({
+        env: ["AGENT_ENGINE"],
+        doc: "Name of the registered agent engine to use.",
+    }),
+    model: z
+        .string()
+        .min(1)
+        .optional()
+        .meta({
+        env: ["AGENT_MODEL"],
+        doc: "Model the agent runs with, when the caller does not pass one.",
+    }),
+    mode: z
+        .string()
+        .min(1)
+        .optional()
+        .meta({
+        env: ["AGENT_MODE"],
+        doc: 'Runtime mode. "production" turns off development-only agent behavior.',
+    }),
+    preferBringYourOwnKey: z
+        .boolean()
+        .default(false)
+        .meta({
+        env: ["AGENT_ENGINE_PREFER_BYO_KEY"],
+        doc: "Skip the Builder-managed engine and select a directly configured provider key first.",
+    }),
+    // These three stay `.optional()` rather than carrying a default: the value
+    // that applies when they are unset depends on whether the run is hosted and
+    // whether it is a background function, so it belongs to the resolver.
+    runSoftTimeoutMs: z
+        .number()
+        .nonnegative()
+        .optional()
+        .meta({
+        env: ["AGENT_RUN_SOFT_TIMEOUT_MS"],
+        doc: "Soft timeout for an agent run, in milliseconds. 0 disables it.",
+    }),
+    completedRunRetentionMs: z
+        .number()
+        .nonnegative()
+        .optional()
+        .meta({
+        env: ["AGENT_RUN_RETENTION_MS"],
+        doc: "How long a completed agent run row is kept, in milliseconds.",
+    }),
+    erroredRunRetentionMs: z
+        .number()
+        .nonnegative()
+        .optional()
+        .meta({
+        env: ["AGENT_ERRORED_RUN_RETENTION_MS"],
+        doc: "How long an errored agent run row is kept, in milliseconds.",
+    }),
+});

package/dist/app-config/app.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+/**
+ * App identity.
+ *
+ * Three fields, not one, because the eight environment keys that spell "which
+ * app is this" were never all the same question:
+ *
+ * - `id` is this deployment's own identity — data programs, onboarding, the
+ *   CLI, and agent model defaults scope by it.
+ * - `workspaceId` is the identity a workspace deploy assigns. `vault_grants`
+ *   rows are written with it, so credential scoping must prefer it over `id`
+ *   or an app would look up grants under a name nobody granted.
+ * - `name` is the user-facing display name ("Acme"), used in transactional
+ *   emails and page titles. It is not an identifier, and only leaks into
+ *   identity resolution as a last-resort fallback in readers that had nothing
+ *   better.
+ *
+ * Collapsing these into one field is the tempting simplification and it is
+ * wrong: it would silently repoint credential grant lookups.
+ *
+ * None of them has a default. `credentialProvider` denies access when no app
+ * identity is configured, and a default of `"app"` would turn that denial into
+ * a lookup scoped to an app literally named `app`. Readers that want a
+ * placeholder apply it themselves, where it is visible.
+ */
+export declare const appConfig: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    workspaceId: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    packageName: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;