@fastagent-sh/fastagent 0.25.0 → 0.26.0

package/README.md

@@ -152,15 +152,16 @@ The package exports the supported surface only, from one entry per kind of user,
 | The Agent API | `Agent`, `AgentError` ([Agent API](docs/SPEC.md)) | Stable within its version |
 | Directory → agent → service | `openAgent`, `LocalAgent`, `serve()`'s `Service` (`fetch`, `listen`) | Usable now, may tighten before 1.0 |
 | Over HTTP | `connectAgent` (`/client`), the `/v1` routes ([Agent API](docs/SPEC.md) §9) | Stable within its version |
+| A host embedding agents | `createAgent`, `CredentialStore`, `credentialFile`, `signIn`, `signInOptions`, `providerAuth` ([embedding](docs/embedding.md#6-a-desktop-host)) | Usable now, may tighten before 1.0 |
 | Authoring | `defineAgent`, `defineChannel`, `defineSchedule`, `needs`, `sessionIdOf`, `readBodyCapped`, `text`, `secretEquals` | Usable now, may tighten before 1.0 |
-| Not exported | The assembly's parts (`router`, `createScheduler`), content, models and sign-in (the CLI's), harness internals | No compatibility promise |
+| Not exported | The assembly's parts (`router`, `createScheduler`), content editing, the model environment, harness internals | No compatibility promise |
 
 A tool or an extension is pi-durable's own (`defineTool`, `defineExtension` from `@earendil-works/pi-durable`), and a
 custom provider is pi-ai's (`createProvider` from `@earendil-works/pi-ai`): `init` adds both packages to the agent.
 
 Entry points (`./package.json` is also exported, for tools that read the version):
 
-- `@fastagent-sh/fastagent` — the Agent API, `openAgent`, and what an author writes;
+- `@fastagent-sh/fastagent` — the Agent API, `openAgent`, what a host embedding agents needs, and what an author writes;
 - `@fastagent-sh/fastagent/client` — `connectAgent`, the Agent API over HTTP, for a program anywhere `fetch` runs;
 - `@fastagent-sh/fastagent/telegram` — Telegram bot channel;
 - `@fastagent-sh/fastagent/slack` — Slack Events API bot channel;

package/dist/agent-api.d.ts

@@ -50,11 +50,15 @@ declare const AgentInfo_base: Schema.Opaque<AgentInfo, Schema.Struct<{
         readonly name: Schema.String;
         readonly description: Schema.optionalKey<Schema.String>;
     }>>;
-    /** The models a session may name: those whose provider has a credential here. */
+    /**
+     * The models a session may name: those whose provider has a credential here. `contextWindow`, in tokens, is the
+     * window the agent runs the model with, absent when the model declares none.
+     */
     readonly models: Schema.$Array<Schema.Struct<{
         readonly provider: Schema.String;
         readonly modelId: Schema.String;
         readonly name: Schema.optionalKey<Schema.String>;
+        readonly contextWindow: Schema.optionalKey<Schema.Number>;
     }>>;
     readonly defaultModel: Schema.optionalKey<Schema.Struct<{
         readonly provider: Schema.String;
@@ -73,11 +77,15 @@ declare const AgentInfo_base: Schema.Opaque<AgentInfo, Schema.Struct<{
         readonly name: Schema.String;
         readonly description: Schema.optionalKey<Schema.String>;
     }>>;
-    /** The models a session may name: those whose provider has a credential here. */
+    /**
+     * The models a session may name: those whose provider has a credential here. `contextWindow`, in tokens, is the
+     * window the agent runs the model with, absent when the model declares none.
+     */
     readonly models: Schema.$Array<Schema.Struct<{
         readonly provider: Schema.String;
         readonly modelId: Schema.String;
         readonly name: Schema.optionalKey<Schema.String>;
+        readonly contextWindow: Schema.optionalKey<Schema.Number>;
     }>>;
     readonly defaultModel: Schema.optionalKey<Schema.Struct<{
         readonly provider: Schema.String;

package/dist/agent-api.js

@@ -28,8 +28,16 @@ export class AgentInfo extends Schema.Opaque()(Schema.Struct({
     commands: Schema.Array(Named),
     /** The tools a session may enable. */
     tools: Schema.Array(Named),
-    /** The models a session may name: those whose provider has a credential here. */
-    models: Schema.Array(Schema.Struct({ provider: Schema.String, modelId: Schema.String, name: Schema.optionalKey(Schema.String) })),
+    /**
+     * The models a session may name: those whose provider has a credential here. `contextWindow`, in tokens, is the
+     * window the agent runs the model with, absent when the model declares none.
+     */
+    models: Schema.Array(Schema.Struct({
+        provider: Schema.String,
+        modelId: Schema.String,
+        name: Schema.optionalKey(Schema.String),
+        contextWindow: Schema.optionalKey(Schema.Number),
+    })),
     defaultModel: Schema.optionalKey(ModelRef),
 })) {
 }

package/dist/authoring.d.ts

@@ -9,7 +9,7 @@ import type { ContentAddition } from "./content/source.ts";
 export declare class ContentNameError extends Error {
     name: string;
 }
-export interface CreateAgentOptions {
+export interface InitAgentOptions {
     /** What the agent works on and knows: repositories into `context.json`, this machine's directories into
      *  `context.local.json`. */
     content?: ContentAddition[];
@@ -26,8 +26,6 @@ export interface CreatedAgent {
     dir: string;
     /** The files written, relative to `dir`. */
     created: string[];
-    /** The content, resolved for this instance. */
-    content: ResolvedContent[];
     /**
      * What became of the agent's git repository, as a sentence to show: created with the scaffold as its first commit,
      * or why not (inside a repository that tracks it, git missing, no commit identity).
@@ -35,12 +33,18 @@ export interface CreatedAgent {
     repository: string;
 }
 /**
- * Create an agent in `dir`, which must be new or empty. Every content entry is checked before anything is written, and
- * the scaffold is removed again when writing the content fails. The agent is then a git repository whose first commit
- * is what was written:
- * it changes itself, and version control is how its author goes back to a version that worked.
+ * Create an agent in `dir` as `fastagent init` does, which must be new or empty: the whole scaffold, and a git
+ * repository whose first commit is what was written, since the agent changes itself and version control is how its
+ * author goes back to a version that worked. It installs no dependencies; the agent opens without them.
+ */
+export declare function createAgent(dir: string): Promise<CreatedAgent>;
+/**
+ * {@link createAgent} with what `fastagent init` adds: content, and the install. Every content entry is checked before
+ * anything is written, and the scaffold is removed again when writing the content fails.
  */
-export declare function createAgent(dir: string, options?: CreateAgentOptions): Promise<CreatedAgent>;
+export declare function initAgent(dir: string, options?: InitAgentOptions): Promise<CreatedAgent & {
+    content: ResolvedContent[];
+}>;
 /**
  * The agent's content, resolved for this instance (what `fastagent content list` shows), and the directories this
  * machine binds that are not here: the agent is not told of those.

package/dist/authoring.js

@@ -1,8 +1,8 @@
 /**
  * Creating an agent and editing its content: `fastagent init` and `fastagent content` are thin wrappers over these (and
  * `fastagent env` writes its declaration through {@link writeEnvironment}), so the rules live here, not in a command.
- * Nothing here prints or exits; every refusal is thrown with the message the CLI shows. Not exported from the package
- * (#847 decides how a client reaches them).
+ * Nothing here prints or exits; every refusal is thrown with the message the CLI shows. The package exports
+ * {@link createAgent}; the content and environment edits wait for context packages, whose shape they follow.
  */
 import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
 import { rm } from "node:fs/promises";
@@ -25,12 +25,19 @@ export class ContentNameError extends Error {
     name = "ContentNameError";
 }
 /**
- * Create an agent in `dir`, which must be new or empty. Every content entry is checked before anything is written, and
- * the scaffold is removed again when writing the content fails. The agent is then a git repository whose first commit
- * is what was written:
- * it changes itself, and version control is how its author goes back to a version that worked.
+ * Create an agent in `dir` as `fastagent init` does, which must be new or empty: the whole scaffold, and a git
+ * repository whose first commit is what was written, since the agent changes itself and version control is how its
+ * author goes back to a version that worked. It installs no dependencies; the agent opens without them.
  */
-export async function createAgent(dir, options = {}) {
+export async function createAgent(dir) {
+    const { content: _, ...created } = await initAgent(dir);
+    return created;
+}
+/**
+ * {@link createAgent} with what `fastagent init` adds: content, and the install. Every content entry is checked before
+ * anything is written, and the scaffold is removed again when writing the content fails.
+ */
+export async function initAgent(dir, options = {}) {
     const agentDir = resolve(dir);
     const additions = options.content ?? [];
     let maps = { content: {}, bindings: {} };

package/dist/cli/add-feishu.js

@@ -10,7 +10,7 @@ import { cloudFor } from "../channels/feishu/cloud.js";
 import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError, } from "../channels/feishu/feishu-api.js";
 import { registerFeishuApp } from "../channels/feishu/register-app.js";
 import { LARK_CONSOLE_URL, onboardLarkApp } from "../channels/lark/onboard.js";
-import { dotEnvPath, loadEnvValues, parseEnvContent } from "../env.js";
+import { dotEnvPath, loadEnvValues, parseEnvContent } from "../value-file.js";
 import { openExternalUrl } from "../open-url.js";
 import { terminalPerson } from "./person.js";
 import { AGENT_ENVIRONMENT_ENV } from "../paths.js";

package/dist/cli/add-slack.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
-import { dotEnvPath, parseEnvContent } from "../env.js";
+import { dotEnvPath, parseEnvContent } from "../value-file.js";
 import { openExternalUrl } from "../open-url.js";
 import { appendChannelDotEnv } from "../scaffold/add-channel.js";
 import { newSlackOnboardingState, onboardSlackApp } from "../channels/slack/onboard.js";

package/dist/cli/box-login.d.ts

@@ -1,6 +1,7 @@
 import { type BoxShell } from "../deploy/box-shell.ts";
 import type { DeployHost } from "../deploy/hosts.ts";
-import type { LoginIO, LoginMethod } from "../harnesses/models/login.ts";
+import type { LoginIO } from "../harnesses/models/login.ts";
+import type { SignInMethod } from "../sign-in-api.ts";
 import type { TicketStep } from "./ticket.ts";
 export interface BoxLoginRequest {
     host: DeployHost;
@@ -8,7 +9,7 @@ export interface BoxLoginRequest {
     /** Skip the provider menu. */
     provider?: string;
     /** Skip the method menu. */
-    method?: LoginMethod;
+    method?: SignInMethod;
     /** Keep a credential the box already holds for `provider` (a redeploy), instead of replacing it. */
     ifMissing?: boolean;
     /** false: never ask; a box without the credential is a failure naming the command to run in a terminal. */

package/dist/cli/commands/add.js

@@ -13,7 +13,8 @@ import { feishuIngressFor } from "../../channels/feishu/setup-mode.js";
 import { markDevServe, unmarkDevServe } from "../../serving-command.js";
 import { channelIngress } from "../../channels/discover.js";
 import { buildDefinitionShape, prepareDefinition } from "../../harnesses/pi-durable/open.js";
-import { dotEnvPath, enterAgentEnv, loadEnvValues } from "../../env.js";
+import { enterAgentEnv } from "../../env.js";
+import { dotEnvPath, loadEnvValues } from "../../value-file.js";
 import { selectAgentEnvironment, resolveStateRoot, SECRETS_DIRNAME, isUnderDir, displayPath } from "../../paths.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
 import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, scaffoldCompanionTools, } from "../../scaffold/add-channel.js";

package/dist/cli/commands/deploy.js

@@ -6,7 +6,7 @@ import { relative } from "node:path";
 import { cloudFor } from "../../channels/feishu/cloud.js";
 import { FEISHU_INGRESS_SETTINGS } from "../../channels/feishu/setup-mode.js";
 import { assembleSecrets, divergentSettingsGate, missingValuesGate } from "../../deploy/secrets.js";
-import { dotEnvPath, loadEnvValues } from "../../env.js";
+import { dotEnvPath, loadEnvValues } from "../../value-file.js";
 import { unmarkDevServe } from "../../serving-command.js";
 import { assertIndependentFeishuApps, feishuAppSecretNames, larkCredentialsNeeded, prepareFeishuApps, unpreparedFeishuApps, } from "../add-feishu.js";
 import { displayPath, selectAgentEnvironment } from "../../paths.js";

package/dist/cli/commands/env.js

@@ -7,11 +7,12 @@ import { resolve } from "node:path";
 import { loadEnvironment, readContextFile } from "../../content/file.js";
 import { aptAdvice, missingAptPackages } from "../../environment/apt.js";
 import { declareEnvironment, declaredVariables, parsePackageArgument, runtimeAdvice, } from "../../environment/declare.js";
-import { checkPackages, ensureMise, enterEnvironment, installPackages, miseBinary } from "../../environment/mise.js";
+import { checkPackages, ensureMise, installPackages, miseBinary, prepareEnvironment } from "../../environment/mise.js";
 import { writeEnvironment } from "../../authoring.js";
 import { log } from "../../log.js";
 import { agentDirOrExit, failStartup } from "../fail.js";
-import { dotEnvPath, enterAgentEnv } from "../../env.js";
+import { enterAgentEnv } from "../../env.js";
+import { dotEnvPath } from "../../value-file.js";
 import { missingSecrets } from "../../declared-secrets.js";
 const NONE = { packages: {}, aptPackages: [], variables: {} };
 /**
@@ -147,10 +148,10 @@ export async function runEnvInstall() {
 }
 export async function runEnvExec(command) {
     const agentDir = enterAgentHere();
-    await enterEnvironment(agentDir).catch(failStartup);
+    const variables = await prepareEnvironment(agentDir, process.env).catch(failStartup);
     const [program, ...args] = command;
     const code = await new Promise((done, fail) => {
-        const child = spawn(program, args, { stdio: "inherit" });
+        const child = spawn(program, args, { stdio: "inherit", env: { ...process.env, ...variables } });
         child.on("error", fail);
         child.on("close", (exit, signal) => done(exit ?? (signal ? 1 : 0)));
     }).catch((error) => failStartup(error.code === "ENOENT" ? new Error(`${program}: command not found in the environment`) : error));

package/dist/cli/commands/init.js

@@ -2,19 +2,19 @@
 import { spawn } from "node:child_process";
 import { resolve } from "node:path";
 import { displayPath } from "../../paths.js";
-import { createAgent } from "../../authoring.js";
+import { initAgent } from "../../authoring.js";
 import { readContentSource } from "../../content/source.js";
 import { failEdit } from "./content.js";
 import { contentLines } from "../content-view.js";
 import { failStartup } from "../fail.js";
 export async function runInit(dirArg, opts) {
     const dir = resolve(dirArg);
-    // Every source is read, and every entry checked (by createAgent), BEFORE anything is created.
+    // Every source is read, and every entry checked (by initAgent), BEFORE anything is created.
     const read = await Promise.resolve()
         .then(() => opts.content.map((source) => readContentSource(source, process.cwd())))
         .catch(failStartup);
     let installFailed = false;
-    const { created, content, repository } = await createAgent(dir, {
+    const { created, content, repository } = await initAgent(dir, {
         content: read.map((source) => source.addition),
         ...(opts.install
             ? {

package/dist/cli/commands/invoke.js

@@ -5,7 +5,8 @@
  */
 import { join, relative, resolve } from "node:path";
 import { AgentError } from "../../agent-api.js";
-import { dotEnvPath, enterAgentEnv, loadEnvValues } from "../../env.js";
+import { enterAgentEnv } from "../../env.js";
+import { dotEnvPath, loadEnvValues } from "../../value-file.js";
 import { installProxyFetch } from "../../proxy.js";
 import { modelRefOf } from "../../harnesses/pi-durable/open.js";
 import { openServing } from "../../harnesses/pi-durable/serve.js";

package/dist/cli/commands/login.js

@@ -1,9 +1,11 @@
-import { enterAgentEnv, dotEnvPath } from "../../env.js";
+import { enterAgentEnv } from "../../env.js";
+import { dotEnvPath } from "../../value-file.js";
 import { GLOBAL_AUTH_PATH, resolveAuthPath, } from "../../harnesses/models/credentials.js";
 import { modelEnvironment } from "../../harnesses/models/environment.js";
 import { DEPLOY_HOSTS } from "../../deploy/hosts.js";
 import { findAgentDir, globalHome, selectAgentEnvironment } from "../../paths.js";
-import { LoginCancelled, LoginRefused, PI_DEFAULT_MODELS, chooseLogin, loginFlow, loginOptionsOver, loginOver, loginStatusText, } from "../../harnesses/models/login.js";
+import { SignInCancelled } from "../../sign-in-api.js";
+import { LoginRefused, PI_DEFAULT_MODELS, chooseLogin, loginFlow, loginOptionsOver, loginOver, loginStatusText, } from "../../harnesses/models/login.js";
 import { environmentAuth, keyVariables, loginProviders } from "../../harnesses/models/models.js";
 import { definitionProviders, loadConfig, modelSpecFor } from "../../harnesses/pi-durable/open.js";
 import { loginOnBox, ticketLoginIO } from "../box-login.js";
@@ -95,7 +97,7 @@ export async function runLogin(provider, opts) {
     }).catch((error) => {
         if (timeout?.aborted)
             failStartup(new Error(`login timed out after ${givenTimeout}s (--timeout)`));
-        if (error instanceof LoginCancelled) {
+        if (error instanceof SignInCancelled) {
             // A decision, not a failure — neutral wording; non-zero exit because no credential was stored.
             console.error(`[fastagent] login cancelled`);
             process.exit(1);
@@ -470,7 +472,7 @@ async function requestDeploymentLogin(agentDir, host, given, opts, timeoutSecond
  */
 async function runStdioLogin(provider, opts) {
     const wire = stdioLoginIO(process.stdin, process.stdout);
-    const result = await stdioLogin(wire.io, provider, opts).catch((error) => error instanceof LoginCancelled
+    const result = await stdioLogin(wire.io, provider, opts).catch((error) => error instanceof SignInCancelled
         ? { ok: false, reason: "cancelled", message: "cancelled" }
         : { ok: false, reason: "failed", message: error.message });
     wire.result(result);

package/dist/cli/login-relay.d.ts

@@ -1,12 +1,13 @@
 import type { Readable, Writable } from "node:stream";
-import type { LoginIO, LoginMethod } from "../harnesses/models/login.ts";
+import type { LoginIO } from "../harnesses/models/login.ts";
+import type { SignInMethod } from "../sign-in-api.ts";
 /** How a login on the box ended, as the box reports it. */
 export type RelayResult = 
 /** Logged in now: `method` is how, `path` where the box saved it. */
 {
     ok: true;
     provider: string;
-    method: LoginMethod;
+    method: SignInMethod;
     path: string;
 }
 /**
@@ -24,7 +25,7 @@ export type RelayResult =
 };
 /**
  * The box half: a {@link LoginIO} over `input`/`output`. Once `input` ends (the session dropped), every pending and
- * later question reads as backed out, so the flow ends in `LoginCancelled` instead of waiting forever.
+ * later question reads as backed out, so the flow ends in `SignInCancelled` instead of waiting forever.
  */
 export declare function stdioLoginIO(input: Readable, output: Writable): {
     io: LoginIO;

package/dist/cli/login-relay.js

@@ -12,7 +12,7 @@ import { BOX_CLI_PREDATES } from "../deploy/box-shell.js";
 const send = (out, message) => void out.write(`${JSON.stringify(message)}\n`);
 /**
  * The box half: a {@link LoginIO} over `input`/`output`. Once `input` ends (the session dropped), every pending and
- * later question reads as backed out, so the flow ends in `LoginCancelled` instead of waiting forever.
+ * later question reads as backed out, so the flow ends in `SignInCancelled` instead of waiting forever.
  */
 export function stdioLoginIO(input, output) {
     const pending = new Map();

package/dist/cli/shared.js

@@ -5,7 +5,8 @@
 import { resolve } from "node:path";
 import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { buildModelPickerOptions } from "./models-view.js";
-import { LoginCancelled, loginFlow } from "../harnesses/models/login.js";
+import { loginFlow } from "../harnesses/models/login.js";
+import { SignInCancelled } from "../sign-in-api.js";
 import { modelEnvironment } from "../harnesses/models/environment.js";
 import { listModels, providerAuthStatuses, providerOf } from "../harnesses/models/models.js";
 import { definitionProviders, loadConfig, modelSpecFor } from "../harnesses/pi-durable/open.js";
@@ -13,7 +14,8 @@ import { formatAuthReport } from "./auth-view.js";
 import { contentLines } from "./content-view.js";
 import { deployedHost, isDeployedWorkspace } from "../paths.js";
 import { log } from "../log.js";
-import { dotEnvPath, enterAgentEnv } from "../env.js";
+import { enterAgentEnv } from "../env.js";
+import { dotEnvPath } from "../value-file.js";
 import { openExternalUrl } from "../open-url.js";
 import { bindAddress, isBindAddress } from "../bind.js";
 import { agentDirOrExit, failStartup, failUsage } from "./fail.js";
@@ -180,7 +182,7 @@ async function pickWithCredentials(models, authPath, providers) {
         console.error(`[fastagent] logged in to ${provider} — saved to ${authPath}`);
     }
     catch (error) {
-        if (error instanceof LoginCancelled)
+        if (error instanceof SignInCancelled)
             return undefined; // user backed out — discard the choice, like a picker cancel
         // A FAILED login keeps the choice: the pick persists, the startup auth report names the remedy, and a later
         // `fastagent login` fixes auth without re-picking the model.

package/dist/content/git.d.ts

@@ -38,4 +38,4 @@ export type CloneOutcome = {
  * - None yet: cloned beside it and renamed into place. A first clone that fails stops the start.
  * - A clone of another repository there (the entry was renamed or redeclared): refused, naming it.
  */
-export declare function refreshClone(repo: string, ref: string | undefined, dir: string): Promise<CloneOutcome>;
+export declare function refreshClone(repo: string, ref: string | undefined, dir: string, env?: NodeJS.ProcessEnv): Promise<CloneOutcome>;

package/dist/content/git.js

@@ -6,7 +6,8 @@
 import { existsSync, mkdirSync, realpathSync, renameSync, rmSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { gitFor } from "../git.js";
-const { answer: gitAnswer, run: runGit } = gitFor("github content needs it on this machine");
+const WHY = "github content needs it on this machine";
+const { answer: gitAnswer } = gitFor(WHY);
 /** The `owner/repo` a GitHub remote URL names, in any of its spellings (https, ssh, scp-like), or undefined. */
 export function githubRepoOf(url) {
     const match = /^(?:(?:https?|git|ssh):\/\/(?:[^@/]+@)?github\.com\/|(?:[^@/:]+@)?github\.com:)([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/i.exec(url.trim());
@@ -94,14 +95,16 @@ const HELPER_KEY = "credential.https://github.com.helper";
  * - None yet: cloned beside it and renamed into place. A first clone that fails stops the start.
  * - A clone of another repository there (the entry was renamed or redeclared): refused, naming it.
  */
-export async function refreshClone(repo, ref, dir) {
+export async function refreshClone(repo, ref, dir, env = process.env) {
+    // The agent's environment, whose GITHUB_TOKEN the clone's credential helper reads.
+    const { run: runGit } = gitFor(WHY, env);
     // A library caller can hand this anything; git reads a leading "-" as an option, and no repository or ref has one
     // (a declaration with one is refused at load, declare.ts).
     if (repo.startsWith("-") || ref?.startsWith("-")) {
         throw new Error(`github ${repo}${ref !== undefined ? ` at ${ref}` : ""} would reach git as an option`);
     }
     if (!existsSync(dir))
-        return cloneInto(repo, ref, dir);
+        return cloneInto(repo, ref, dir, runGit);
     const origin = gitAnswer(["config", "--get", "remote.origin.url"], dir);
     if (origin === undefined || githubRepoOf(origin)?.toLowerCase() !== repo.toLowerCase()) {
         throw new Error(`${dir} is a clone of ${origin ?? "no repository"}, not of github ${repo}: move it away (push what should last ` +
@@ -162,7 +165,7 @@ function gitReason(error) {
  * process reads no clone or a whole one. When another process put its own there first, that one stands and this one
  * is discarded. Shallow: a starting point to work from; a later fetch brings the history an update needs.
  */
-async function cloneInto(repo, ref, dir) {
+async function cloneInto(repo, ref, dir, runGit) {
     const parent = dirname(dir);
     mkdirSync(parent, { recursive: true });
     const next = join(parent, `.${basename(dir)}.next-${process.pid}-${Date.now()}`);

package/dist/content/resolve.d.ts

@@ -49,4 +49,4 @@ export declare function checkBinding(agentDir: string, name: string, target: str
  */
 export declare function cloneContent(entry: Extract<ResolvedContent, {
     kind: "github";
-}>): Promise<CloneOutcome>;
+}>, env?: NodeJS.ProcessEnv): Promise<CloneOutcome>;

package/dist/content/resolve.js

@@ -103,11 +103,11 @@ export function checkBinding(agentDir, name, target, repository) {
  * agent did in it (git.ts `refreshClone`): what git refuses, or a remote that cannot be reached, keeps it as it is,
  * with the reason. Only a process that runs the agent calls this. A checkout this machine binds is never cloned over.
  */
-export async function cloneContent(entry) {
+export async function cloneContent(entry, env = process.env) {
     if (!entry.clone)
         throw new Error(`content "${entry.name}" is bound to the checkout ${entry.location}, not a clone`);
     ensureContentDir(dirname(entry.location));
-    return refreshClone(entry.repo, entry.ref, entry.location).catch((error) => {
+    return refreshClone(entry.repo, entry.ref, entry.location, env).catch((error) => {
         throw new Error(`content "${entry.name}": ${error.message}`);
     });
 }

package/dist/deploy/preflight.js

@@ -19,7 +19,7 @@ import { RUNTIME_FLOOR, belowFloor, detectRuntime, listsFastagent, readPackageJs
 import { fastagentVersion } from "../version.js";
 import { isGeneratedDockerfile } from "./container.js";
 import { buildContextPaths, checkKeptIgnoreFiles } from "./build-context.js";
-import { dotEnvPath, loadEnvValues } from "../env.js";
+import { dotEnvPath, loadEnvValues } from "../value-file.js";
 import { deploymentSecrets, isEnvKey } from "./secrets.js";
 import { DEFAULT_HTTP_PORT } from "../service.js";
 import { declaredVariables, declaresTool, runtimeAdvice } from "../environment/declare.js";

package/dist/dev-supervisor.js

@@ -6,7 +6,7 @@ import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
 import { AGENT_CONFIG_FILE, CONTEXT_FILE, LOCAL_CONTEXT_FILE, resolveStateRoot, isUnderDir } from "./paths.js";
-import { dotEnvPath } from "./env.js";
+import { dotEnvPath } from "./value-file.js";
 import { log } from "./log.js";
 import { openExternalUrl } from "./open-url.js";
 import { declaredChannels } from "./channels/discover.js";

package/dist/env.d.ts

@@ -4,19 +4,6 @@
  * occurrence wins ({@link parseEnvContent}).
  */
 export declare function applyEnvValues(values: ReadonlyMap<string, string>): void;
-/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). */
-export declare function parseEnvContent(content: string): Map<string, string>;
-/**
- * READ a value file without entering it: the values as data, never `process.env`. This is how code reasons about an
- * environment OTHER than its own — `deploy` resolves configuration in the environment being deployed, which this
- * file declares, and merging it into the running process would put the two environments in one bag. A missing file
- * is no values, which is normal.
- */
-export declare function loadEnvValues(file: string): Map<string, string>;
-/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
-export declare function dotEnvPath(agentDir: string, env?: NodeJS.ProcessEnv): string;
-/** The committable template: `<agentDir>/.secrets/.env.example`. */
-export declare function envExamplePath(agentDir: string): string;
 /**
  * ENTER an agent directory's runtime environment: its `.env` becomes `process.env`, and this process's outbound fetch
  * follows whatever proxy that (or the ambient environment) declares.

package/dist/env.js

@@ -2,7 +2,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { log } from "./log.js";
 import { installProxyFetch } from "./proxy.js";
-import { SECRETS_DIRNAME, resolveSecretsDir } from "./paths.js";
+import { dotEnvPath, loadEnvValues, parseEnvContent } from "./value-file.js";
 /**
  * Write parsed values into `process.env`, matching Node's `--env-file` / `process.loadEnvFile` precedence on BOTH
  * axes (verified against Node in test/env.test.ts): a real env var wins over the file, and within the file the last
@@ -13,49 +13,6 @@ export function applyEnvValues(values) {
         if (!(key in process.env))
             process.env[key] = value;
 }
-/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). */
-export function parseEnvContent(content) {
-    const parsed = new Map();
-    for (const raw of content.split("\n")) {
-        const line = raw.trim();
-        if (!line || line.startsWith("#"))
-            continue;
-        const eq = line.indexOf("=");
-        if (eq < 1)
-            continue; // no `=`, or an empty key
-        const key = line.slice(0, eq).trim();
-        let value = line.slice(eq + 1).trim();
-        const quote = value[0];
-        if ((quote === '"' || quote === "'") && value.at(-1) === quote)
-            value = value.slice(1, -1);
-        parsed.set(key, value); // in-file: last occurrence wins (Map overwrite)
-    }
-    return parsed;
-}
-/**
- * READ a value file without entering it: the values as data, never `process.env`. This is how code reasons about an
- * environment OTHER than its own — `deploy` resolves configuration in the environment being deployed, which this
- * file declares, and merging it into the running process would put the two environments in one bag. A missing file
- * is no values, which is normal.
- */
-export function loadEnvValues(file) {
-    try {
-        return parseEnvContent(readFileSync(file, "utf8"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return new Map();
-        throw error;
-    }
-}
-/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
-export function dotEnvPath(agentDir, env = process.env) {
-    return join(resolveSecretsDir(agentDir, env), ".env");
-}
-/** The committable template: `<agentDir>/.secrets/.env.example`. */
-export function envExamplePath(agentDir) {
-    return join(agentDir, SECRETS_DIRNAME, ".env.example");
-}
 /**
  * ENTER an agent directory's runtime environment: its `.env` becomes `process.env`, and this process's outbound fetch
  * follows whatever proxy that (or the ambient environment) declares.

package/dist/environment/mise.d.ts

@@ -1,4 +1,4 @@
-import { type DeclaredEnvironment, type MissingRuntime } from "./declare.ts";
+import { type MissingRuntime } from "./declare.ts";
 /** Every platform's package: an agent lists them all, so its lockfile has the image's too. */
 export declare const MISE_PACKAGE_NAMES: readonly string[];
 /**
@@ -40,11 +40,12 @@ export declare function checkPackages(agentDir: string, bin: string, packages: R
  * so a start whose packages are installed needs no network and keeps the versions it has. An install that matches may
  * be another project's: mise's data directory is the machine's.
  */
-export declare function installPackages(agentDir: string, bin: string, packages: Record<string, string>, newest?: readonly string[] | "all"): Promise<void>;
+export declare function installPackages(agentDir: string, bin: string, packages: Record<string, string>, newest?: readonly string[] | "all", env?: NodeJS.ProcessEnv): Promise<void>;
 /**
- * Enter the agent's environment, for a process that runs it: install the declared packages that have no install here
- * yet, and put them first on this process's PATH, which every command the agent runs inherits. mise itself is not put
- * on the PATH. An agent without packages borrows the machine's commands. Apt packages are the image's to install; one
- * missing here is said, with how.
+ * The agent's declared environment, for a process that runs it: install the declared packages that have no install
+ * here yet, and answer the variables that put them first on the PATH of the commands the agent runs. mise runs in
+ * `env`, the agent's environment so far, and nothing is written into this process's: a process may run several agents.
+ * mise itself is not put on the PATH. An agent without packages borrows the machine's commands (no variables). Apt
+ * packages are the image's to install; one missing here is said, with how.
  */
-export declare function enterEnvironment(agentDir: string): Promise<DeclaredEnvironment | undefined>;
+export declare function prepareEnvironment(agentDir: string, env: NodeJS.ProcessEnv): Promise<Record<string, string>>;