@fastagent-sh/fastagent 0.25.0 → 0.26.0

package/dist/harnesses/models/login.js

@@ -1,20 +1,19 @@
 /**
- * Signing in to a MODEL PROVIDER, for any front end: {@link login} runs one provider's flow over pi-ai's own
+ * Signing in to a MODEL PROVIDER, for any front end: {@link loginOver} runs one provider's flow over pi-ai's own
  * `AuthInteraction` and persists the credential through the same {@link fastagentCredentialStore} the runtime reads
- * (one writer, one lock/corruption semantics); {@link loginOptions} is the list a picker offers. `fastagent login` is
- * one front end ({@link loginFlow}: terminal menus, then {@link login}); `login --deployment` drives the same flow on a
- * deployed box over a relay (cli/login-relay.ts).
+ * (one writer, one lock/corruption semantics); {@link loginOptionsOver} is the list a picker offers. An embedding host
+ * reaches both through host.ts (`signIn`, `signInOptions`); `fastagent login` is a front end of its own
+ * ({@link loginFlow}: terminal menus, then {@link loginOver}); `login --deployment` drives the same flow on a deployed
+ * box over a relay (cli/login-relay.ts).
  */
 import { InMemoryCredentialStore, } from "@earendil-works/pi-ai";
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { writeFileAtomic } from "../../atomic-write.js";
+import { SignInCancelled } from "../../sign-in-api.js";
 import { assertOneCredentialSource, fastagentCredentialStore } from "./credentials.js";
 import { UNNAMED_AUTH_SOURCE, interactiveAuth, loginProviders, modelsOver, probeApiKey } from "./models.js";
-/** The user backed out of a prompt/menu, or the flow was aborted — a decision, not a failure. */
-export class LoginCancelled extends Error {
-}
 /** A sign-in that cannot start as asked: an unknown provider, or a choice a caller without menus did not make. */
 export class LoginRefused extends Error {
     /** The sign-ins it could be instead, for a caller to choose from. */
@@ -26,17 +25,13 @@ export class LoginRefused extends Error {
 }
 const ACCOUNT_LABEL = "Sign in with an account";
 const API_KEY_LABEL = "Sign in with an API key";
-/**
- * Every sign-in of pi's built-in providers, sorted by name as pi's `/login` lists them, with what authenticates each
- * one here: a credential `credentials` (a credentials file, or the caller's own store) holds, else this process's
- * environment, which a stored credential outranks.
- */
-export function loginOptions(credentials) {
-    return loginOptionsOver(credentials);
-}
 /** A credentials file path names fastagent's store over it; a store is used as given. */
 const storeOf = (credentials) => typeof credentials === "string" ? fastagentCredentialStore(credentials) : credentials;
-/** {@link loginOptions} over pi's built-ins plus `providers` (a same id replaces one). Not public: a test seam. */
+/**
+ * Every sign-in of pi's built-in providers plus `providers` (a same id replaces one), sorted by name as pi's `/login`
+ * lists them, with what authenticates each one here: a credential `credentials` (a credentials file, or a store) holds,
+ * else this process's environment, which a stored credential outranks.
+ */
 export async function loginOptionsOver(credentials, providers) {
     // ONE read of the store: `list` is metadata only, and reading per provider would repeat a corrupt file's warning for
     // every provider.
@@ -49,21 +44,17 @@ export async function loginOptionsOver(credentials, providers) {
         if (methods.length === 0)
             continue;
         const stored = held.get(provider.id);
-        let status;
+        let ambient;
         let problem;
-        if (stored !== undefined) {
-            status = { type: stored, source: stored === "oauth" ? "OAuth" : "stored credential" };
+        try {
+            const found = await environment.checkAuth(provider.id);
+            if (found !== undefined)
+                ambient = { type: found.type, source: found.source ?? UNNAMED_AUTH_SOURCE };
         }
-        else {
-            try {
-                const found = await environment.checkAuth(provider.id);
-                if (found !== undefined)
-                    status = { type: found.type, source: found.source ?? UNNAMED_AUTH_SOURCE };
-            }
-            catch (error) {
-                problem = error.message;
-            }
+        catch (error) {
+            problem = error.message;
         }
+        const status = stored === undefined ? ambient : { type: stored, source: stored === "oauth" ? "OAuth" : "stored credential" };
         for (const method of methods) {
             offered.push({
                 provider: provider.id,
@@ -73,6 +64,7 @@ export async function loginOptionsOver(credentials, providers) {
                 subscription: method === "oauth" && provider.auth.oauth?.isSubscription === true,
                 external: interactiveAuth(provider, method) === undefined,
                 ...(status ? { status } : {}),
+                ...(ambient ? { environment: ambient.source } : {}),
                 ...(problem ? { problem } : {}),
             });
         }
@@ -87,11 +79,10 @@ function credentialKind(type, subscription) {
 }
 /** An option's status as pi's picker writes it after the provider's name. */
 export function loginStatusText(option) {
-    if (option.problem !== undefined)
-        return `auth check failed: ${option.problem}`;
     const { status } = option;
+    // A stored credential outranks the environment, so a failed check of the environment does not decide it.
     if (status === undefined)
-        return "not configured";
+        return option.problem === undefined ? "not configured" : `auth check failed: ${option.problem}`;
     if (status.type !== option.method)
         return `${credentialKind(status.type, option.subscription)} configured`;
     if (status.source === "OAuth" || status.source === "stored credential")
@@ -106,8 +97,8 @@ function anySignal(...signals) {
     return present.length === 0 ? undefined : present.length === 1 ? present[0] : AbortSignal.any(present);
 }
 /**
- * Sign in to one of pi's built-in providers and persist the credential to `authPath`, or to the caller's
- * `credentialStore`.
+ * Sign in to one of pi's built-in providers (plus the definition's) and persist the credential to `authPath`, or to
+ * the caller's `credentialStore`.
  *
  * The store is checked FIRST (a no-op write runs the file store's refuse-corrupt and writability checks, or whatever
  * the caller's store does on a write), so a flow never runs toward a credential that could not be saved. An entered API key is verified with one minimal request to pi's
@@ -116,14 +107,11 @@ function anySignal(...signals) {
  * the provider refuse the key, HTTP 401); a key the provider rejects is never stored, and the provider's key flow runs
  * again (the provider and method were not the mistake). Progress and outcome go out through `interaction.notify`.
  *
- * Aborting `interaction.signal` at any point, the verification included, rejects with {@link LoginCancelled} and
- * writes no credential (an OAuth device ID, the installation's identity, is kept once created). Every prompt carries a signal that aborts on it, on the prompt's own signal (a callback server
- * beating a `manual_code` prompt), and when the flow settles with a prompt still pending.
+ * Aborting `interaction.signal` at any point, the verification included, rejects with {@link SignInCancelled} and
+ * writes no credential (an OAuth device ID, the installation's identity, is kept once created). Every prompt carries a
+ * signal that aborts on it, on the prompt's own signal (a callback server beating a `manual_code` prompt), and when the
+ * flow settles with a prompt still pending.
  */
-export function login(request) {
-    return loginOver(request);
-}
-/** {@link login}, plus {@link LoginInternals}. */
 export async function loginOver(request, internals = {}) {
     const { providers, verifyWith } = internals;
     const { method, interaction } = request;
@@ -158,7 +146,7 @@ export async function loginOver(request, internals = {}) {
             await trial.modify(provider.id, async () => credential);
             const verdict = await verifyApiKey(models, provider.id, verifyWith, notify, signal);
             if (signal.aborted)
-                throw new LoginCancelled("cancelled");
+                throw new SignInCancelled("cancelled");
             if (verdict === "rejected")
                 continue;
             verified = verdict;
@@ -202,20 +190,32 @@ async function readOrCreateDeviceId(path) {
 }
 async function runFlow(flow, interaction, signal) {
     if (signal.aborted)
-        throw new LoginCancelled("cancelled");
+        throw new SignInCancelled("cancelled");
     const done = new AbortController();
+    let backedOut;
     let credential;
     try {
         credential = await flow({
             signal,
-            prompt: (prompt) => interaction.prompt({ ...prompt, signal: anySignal(prompt.signal, signal, done.signal) }),
+            prompt: (prompt) => {
+                const asked = anySignal(prompt.signal, signal, done.signal);
+                return interaction.prompt({ ...prompt, signal: asked }).catch((error) => {
+                    // Remembered here: a provider may wrap the rejection it is handed in an error of its own. Only a question
+                    // still asked: one the flow withdrew (its callback came first) rejects too, and nobody backed out of it.
+                    if (error instanceof SignInCancelled && !asked?.aborted)
+                        backedOut = error;
+                    throw error;
+                });
+            },
             notify: (event) => interaction.notify(event),
         });
     }
     catch (error) {
         // Whatever the provider made of the abort (its own error, a rejected prompt), it was the caller's decision.
         if (signal.aborted)
-            throw new LoginCancelled("cancelled");
+            throw new SignInCancelled("cancelled");
+        if (backedOut !== undefined)
+            throw backedOut;
         throw error;
     }
     finally {
@@ -223,7 +223,7 @@ async function runFlow(flow, interaction, signal) {
     }
     // A provider that ignored the abort and finished anyway: the caller still cancelled.
     if (signal.aborted)
-        throw new LoginCancelled("cancelled");
+        throw new SignInCancelled("cancelled");
     return credential;
 }
 /**
@@ -314,7 +314,7 @@ async function verifyApiKey(models, providerId, verifyWith, notify, signal) {
     }
     return probe.state;
 }
-/** {@link LoginIO} as pi-ai's `AuthInteraction`: what {@link login} drives for the terminal. */
+/** {@link LoginIO} as pi-ai's `AuthInteraction`: what {@link loginOver} drives for the terminal. */
 function terminalInteraction(io, signal) {
     return {
         ...(signal ? { signal } : {}),
@@ -332,7 +332,7 @@ function terminalInteraction(io, signal) {
                     ...(p.signal ? { signal: p.signal } : {}),
                 });
             if (v === undefined)
-                throw new LoginCancelled("cancelled");
+                throw new SignInCancelled("cancelled");
             return v;
         },
         notify: (e) => {
@@ -354,7 +354,7 @@ function terminalInteraction(io, signal) {
 }
 /**
  * `fastagent login` in a terminal: ask only what was not given, as pi's `/login` asks it (how to sign in, then the
- * provider; a provider named by its id or its name, then how, when it offers both), then {@link login}.
+ * provider; a provider named by its id or its name, then how, when it offers both), then {@link loginOver}.
  */
 export async function loginFlow(io, options) {
     const offered = await loginOptionsOver(options.statusFrom ?? options.authPath, options.providers);
@@ -383,7 +383,7 @@ export async function chooseLogin(offered, given, menus) {
         const value = await menus.select(message, options);
         const option = from.find((o) => by(o) === value);
         if (option === undefined)
-            throw new LoginCancelled("nothing selected");
+            throw new SignInCancelled("nothing selected");
         return option;
     };
     if (given.provider !== undefined) {
@@ -420,7 +420,7 @@ export async function chooseLogin(offered, given, menus) {
         if (way === "radius" && radius)
             return radius;
         if (way !== "oauth" && way !== "api_key")
-            throw new LoginCancelled("no authentication method selected");
+            throw new SignInCancelled("no authentication method selected");
         method = way;
     }
     const candidates = offered.filter((o) => o.method === method);

package/dist/harnesses/models/models.d.ts

@@ -11,10 +11,11 @@ export declare function providerOf(spec: string): string;
 /** Every chat model `models` offers, as `"provider/modelId"`, sorted. */
 export declare function listModels(models: Models): string[];
 /**
- * The built-ins plus `providers` (a same id replaces a built-in), over any credential store. With `catalogs`, the lists
- * its refresh brings up to date; without, the ones this pi-ai was built with.
+ * The built-ins plus `providers` (a same id replaces a built-in), over any credential store, in `environment`: what
+ * the agent's environment adds to this process's, read before it by a provider's auth and by each request. With
+ * `catalogs`, the lists its refresh brings up to date; without, the ones this pi-ai was built with.
  */
-export declare function modelsOver(credentials: CredentialStore, providers?: readonly Provider[], catalogs?: Catalogs): Models;
+export declare function modelsOver(credentials: CredentialStore, providers?: readonly Provider[], catalogs?: Catalogs, environment?: Readonly<Record<string, string>>): Models;
 /**
  * Whether `env` alone satisfies a provider, by pi's own check, and with what when the provider says (its API-key
  * variable, or an ambient source such as an AWS profile); undefined when it does not. A provider in code may

package/dist/harnesses/models/models.js

@@ -21,19 +21,62 @@ export function listModels(models) {
     return specs.sort();
 }
 /**
- * The built-ins plus `providers` (a same id replaces a built-in), over any credential store. With `catalogs`, the lists
- * its refresh brings up to date; without, the ones this pi-ai was built with.
+ * pi's own reading of an environment (a blank variable is unset) through `read` instead of this process's: an agent's
+ * environment is its own when the process runs several. Files a source points at are this machine's unless
+ * `fileExists` says otherwise.
  */
-export function modelsOver(credentials, providers = [], catalogs) {
+function authContextIn(read, fileExists = defaultProviderAuthContext().fileExists) {
+    return {
+        env: async (name) => {
+            const value = read(name);
+            return value?.trim() ? value : undefined;
+        },
+        fileExists,
+    };
+}
+/**
+ * `provider` with `environment` given to each request, as its auth reads it: pi resolves a provider's key from the
+ * auth context, but a request reads its region, endpoint or ambient key (Bedrock, Azure, Vertex) from the request's
+ * own `env`, which it otherwise takes from this process.
+ */
+function inEnvironment(provider, environment) {
+    const withEnv = (options) => ({ ...options, env: { ...environment, ...options?.env } });
+    const { fetchDeferred, cancelDeferred, generateImages, classify } = provider;
+    return {
+        ...provider,
+        stream: (model, context, options) => provider.stream(model, context, withEnv(options)),
+        streamSimple: (model, context, options) => provider.streamSimple(model, context, withEnv(options)),
+        ...(fetchDeferred && {
+            fetchDeferred: (model, handle, options) => fetchDeferred.call(provider, model, handle, withEnv(options)),
+        }),
+        ...(cancelDeferred && {
+            cancelDeferred: (model, handle, options) => cancelDeferred.call(provider, model, handle, withEnv(options)),
+        }),
+        ...(generateImages && {
+            generateImages: (model, context, options) => generateImages.call(provider, model, context, withEnv(options)),
+        }),
+        ...(classify && {
+            classify: (model, context, options) => classify.call(provider, model, context, withEnv(options)),
+        }),
+    };
+}
+/**
+ * The built-ins plus `providers` (a same id replaces a built-in), over any credential store, in `environment`: what
+ * the agent's environment adds to this process's, read before it by a provider's auth and by each request. With
+ * `catalogs`, the lists its refresh brings up to date; without, the ones this pi-ai was built with.
+ */
+export function modelsOver(credentials, providers = [], catalogs, environment = {}) {
     const models = createModels({
         credentials,
-        authContext: defaultProviderAuthContext(),
+        // As a request reads it (pi's getProviderEnvValue): the request's env first, then this process's.
+        authContext: authContextIn((name) => environment[name] || process.env[name]),
         ...(catalogs ? { modelsStore: catalogs.fetched } : {}),
     });
-    for (const builtIn of builtinProviders())
-        models.setProvider(catalogs ? catalogs.over(builtIn) : builtIn);
+    for (const builtIn of builtinProviders()) {
+        models.setProvider(inEnvironment(catalogs ? catalogs.over(builtIn) : builtIn, environment));
+    }
     for (const provider of providers)
-        models.setProvider(provider);
+        models.setProvider(inEnvironment(provider, environment));
     return models;
 }
 /**
@@ -51,11 +94,7 @@ export function modelsOver(credentials, providers = [], catalogs) {
 export async function environmentAuth(providerId, env, fileExists = defaultProviderAuthContext().fileExists, providers = []) {
     const models = builtinModels({
         credentials: new InMemoryCredentialStore(),
-        authContext: {
-            // pi's own reading of a variable (a blank one is unset), over the given environment.
-            env: async (name) => (env[name]?.trim() ? env[name] : undefined),
-            fileExists,
-        },
+        authContext: authContextIn((name) => env[name], fileExists),
     });
     for (const provider of providers)
         models.setProvider(provider);

package/dist/harnesses/pi-durable/agent.js

@@ -177,6 +177,8 @@ function durableAgent(harness, ids, sessions, lifetime, options) {
                 provider: model.provider,
                 modelId: model.id,
                 ...(model.name ? { name: model.name } : {}),
+                // pi reads a window a model does not declare (a virtual model's, before its first answer) as 0.
+                ...(model.contextWindow > 0 ? { contextWindow: model.contextWindow } : {}),
             })),
             ...(options.model === undefined
                 ? {}

package/dist/harnesses/pi-durable/open.d.ts

@@ -82,7 +82,14 @@ export interface AssembleAgentOptions {
     settings?: HarnessSettings;
     /** Where the instance's state is: given by a serve, whose scheduler fires the wake-ups `wake` keeps there. */
     stateRoot?: string;
+    /** Whether that scheduler runs now: an app's `openAgent` runs one only while it serves. Default always. */
+    wakeTicking?: () => boolean;
     unfinished?: Unfinished;
+    /**
+     * What the agent's environment adds to this process's, for the commands it runs: its value file's variables and its
+     * packages' PATH.
+     */
+    environment?: Readonly<Record<string, string>>;
 }
 /** Open the definition as an Agent over `models`: the coding tools, then its own. */
 export declare function assembleAgent(definition: AgentDefinition, options: AssembleAgentOptions): Promise<DurableAgent>;

package/dist/harnesses/pi-durable/open.js

@@ -309,8 +309,9 @@ export async function assembleAgent(definition, options) {
     }));
     for (const extension of code.extensions)
         registry.install(extension);
-    if (options.stateRoot !== undefined && !ownWake)
-        registry.install(wakeExtension(options.stateRoot));
+    if (options.stateRoot !== undefined && !ownWake) {
+        registry.install(wakeExtension(options.stateRoot, options.wakeTicking === undefined ? {} : { ticking: options.wakeTicking }));
+    }
     const thinkingLevel = options.thinkingLevel ?? config.thinkingLevel;
     return openDurableAgent({
         storage: options.storage,
@@ -323,7 +324,7 @@ export async function assembleAgent(definition, options) {
         ...(options.settings === undefined ? {} : { settings: options.settings }),
         ...(options.unfinished === undefined ? {} : { unfinished: options.unfinished }),
         // What the agent runs is not `dev`'s own serving, even when `dev` is what runs the agent.
-        env: ({ cwd }) => new NodeExecutionEnv({ cwd: cwd ?? dir, shellEnv: { [DEV_SERVE_ENV]: undefined } }),
+        env: ({ cwd }) => new NodeExecutionEnv({ cwd: cwd ?? dir, shellEnv: { ...options.environment, [DEV_SERVE_ENV]: undefined } }),
         commands: () => readCommands(dir),
     });
 }

package/dist/harnesses/pi-durable/serve.d.ts

@@ -1,7 +1,8 @@
-import type { CredentialStore, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
 import { type Harness } from "@earendil-works/pi-durable";
 import type { CredentialSourceOptions } from "../models/credentials.ts";
 import { type ModelEnvironment } from "../models/environment.ts";
+import type { CredentialStore } from "../../sign-in-api.ts";
 import { type ResolvedContent } from "../../content/resolve.ts";
 import type { Agent } from "../../agent-api.ts";
 import { type Service } from "../../service.ts";
@@ -22,6 +23,10 @@ export interface OpenServingOptions extends CredentialSourceOptions {
     storage?: ServingStorage;
     /** What becomes of the messages an earlier process left unfinished in the storage. Default `"resume"`. */
     unfinished?: Unfinished;
+    /** The instance's state root, over `FASTAGENT_STATE_DIR` and the directory's own. */
+    stateRoot?: string;
+    /** Whether a clock fires the instance's wake-ups now (`assembleAgent`'s `wakeTicking`). Default always. */
+    wakeTicking?: () => boolean;
 }
 type ServingStorage = {
     instance: StorageLocking;
@@ -70,6 +75,11 @@ export interface OpenAgentOptions {
     model?: string;
     /** Where provider credentials are kept, instead of the agent's own `.secrets/auth.json` over the machine's. */
     credentials?: CredentialStore;
+    /**
+     * Where this instance keeps its sessions, its channels' and schedules' state and its model lists, instead of
+     * `FASTAGENT_STATE_DIR` or the agent's `.state/`: a host's own instance of an agent beside `fastagent dev`'s.
+     */
+    stateDir?: string;
 }
 /**
  * Open the agent directory `dir` the way `dev` and `start` do before they serve: its definition, its code built with

package/dist/harnesses/pi-durable/serve.js

@@ -8,11 +8,13 @@ import { join } from "node:path";
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { MemoryStorage } from "@earendil-works/pi-durable";
 import { modelEnvironment } from "../models/environment.js";
+import { piCredentials } from "../models/host.js";
 import { loadContent } from "../../content/file.js";
 import { absentNotice, cloneContent, contentAbsentHere, resolveContent, } from "../../content/resolve.js";
-import { enterEnvironment } from "../../environment/mise.js";
+import { agentValues } from "../../value-file.js";
+import { prepareEnvironment } from "../../environment/mise.js";
 import { log } from "../../log.js";
-import { resolveStateRoot } from "../../paths.js";
+import { resolveOverridePath, resolveStateRoot } from "../../paths.js";
 import { serveAgent } from "../../service.js";
 import { buildDefinition, assembleAgent, prepareDefinition, } from "./open.js";
 import { openLockedStorage } from "./storage.js";
@@ -24,12 +26,12 @@ const INSTANCE_HOLDERS = "another `fastagent dev`, `start` or `schedules` comman
  * up to date in place where git can do so without touching the agent's work, first; then resolved again as what is now
  * on disk.
  */
-async function contentForThisRun(dir) {
+async function contentForThisRun(dir, env) {
     const declaration = loadContent(dir);
     for (const entry of resolveContent(dir, declaration)) {
         if (entry.kind !== "github" || !entry.clone)
             continue;
-        const done = await cloneContent(entry);
+        const done = await cloneContent(entry, env);
         if (done.outcome === "kept") {
             log.warn(`[fastagent] content "${entry.name}": the clone in ${entry.location} is kept as it is, ${done.reason}`);
         }
@@ -67,27 +69,33 @@ function openStorage(stateRoot, storage) {
 export async function openServing(directory, options = {}) {
     const definition = await prepareDefinition(directory);
     const { dir } = definition;
-    const code = buildDefinition(definition);
+    // The agent's environment is ONE value every reader below is given, and this process's is never written: a process
+    // may run several agents, each with its own values and packages.
+    const values = agentValues(dir);
+    const code = buildDefinition(definition, { ...process.env, ...values });
     // The commands the agent runs, as `context.json`'s environment declares them, before anything can run one.
-    await enterEnvironment(dir);
-    const content = await contentForThisRun(dir);
+    const environment = { ...values, ...(await prepareEnvironment(dir, { ...process.env, ...values })) };
+    const env = { ...process.env, ...environment };
+    const content = await contentForThisRun(dir, env);
+    const stateRoot = options.stateRoot ?? resolveStateRoot(dir, env);
     const models = await modelEnvironment(dir, {
         ...(options.authPath === undefined ? {} : { authPath: options.authPath }),
         ...(options.credentialStore === undefined ? {} : { credentialStore: options.credentialStore }),
-    }, code.providers);
-    const stateRoot = resolveStateRoot(dir);
+    }, code.providers, { stateRoot, environment });
     const chosen = options.storage ?? { instance: "posix" };
     const storage = await openStorage(stateRoot, chosen);
     const agent = await assembleAgent(definition, {
         storage,
         code,
         content,
+        environment,
         models: models.models,
         ...(models.catalogProblem === undefined ? {} : { catalogProblem: models.catalogProblem }),
         ...(typeof chosen === "object" && "instance" in chosen ? { stateRoot } : {}),
         ...(options.model === undefined ? {} : { model: options.model }),
         ...(options.thinkingLevel === undefined ? {} : { thinkingLevel: options.thinkingLevel }),
         ...(options.unfinished === undefined ? {} : { unfinished: options.unfinished }),
+        ...(options.wakeTicking === undefined ? {} : { wakeTicking: options.wakeTicking }),
     }).catch(async (error) => {
         // An Agent that did not open does not own the storage, and its lock would refuse this process's next attempt.
         await storage.close(BACKGROUND_CONTEXT);
@@ -105,15 +113,26 @@ export async function openServing(directory, options = {}) {
         schedules: code.schedules,
     };
 }
+/** `stateDir` read as `FASTAGENT_STATE_DIR` is: `~` is the home directory, a relative one resolves against the cwd. */
+function stateDirOf(stateDir) {
+    const resolved = resolveOverridePath(stateDir);
+    if (resolved === undefined)
+        throw new Error("stateDir needs the directory the instance's state is kept in");
+    return resolved;
+}
 /**
  * Open the agent directory `dir` the way `dev` and `start` do before they serve: its definition, its code built with
  * the secrets it declares, its environment, its content and the instance's storage, which one process holds at a time.
  * Nothing reaches the agent until `serve`.
  */
 export async function openAgent(dir, options = {}) {
+    // An app may never serve the agent, and then no clock fires a wake-up: `wake` is refused until it does.
+    let ticking = false;
     const opened = await openServing(dir, {
+        wakeTicking: () => ticking,
         ...(options.model === undefined ? {} : { model: options.model }),
-        ...(options.credentials === undefined ? {} : { credentialStore: options.credentials }),
+        ...(options.credentials === undefined ? {} : { credentialStore: piCredentials(options.credentials) }),
+        ...(options.stateDir === undefined ? {} : { stateRoot: stateDirOf(options.stateDir) }),
     });
     const { agent } = opened;
     let served;
@@ -130,10 +149,21 @@ export async function openAgent(dir, options = {}) {
                 return Promise.reject(new Error("this agent is closed"));
             if (served !== undefined)
                 return Promise.reject(new Error("this agent is already served"));
-            const serving = serveAgent(opened, serveOptions);
+            const serving = serveAgent(opened, serveOptions).then((service) => ({
+                ...service,
+                close: () => {
+                    // Its clock stops with it, whichever closes it: a wake-up kept after this is one nothing fires.
+                    ticking = false;
+                    return service.close();
+                },
+            }));
             served = serving;
+            serving.then(() => {
+                if (served === serving && closing === undefined)
+                    ticking = true;
+            }, 
             // A serve that failed to start rolled itself back, so the agent may be served again.
-            serving.catch(() => {
+            () => {
                 if (served === serving)
                     served = undefined;
             });

package/dist/harnesses/pi-durable/wake.d.ts

@@ -1,4 +1,11 @@
 import { type Extension } from "@earendil-works/pi-durable";
 export declare const WAKE_EXTENSION = "fastagent.wake";
 export declare const WAKE_TOOLS: string[];
-export declare function wakeExtension(stateRoot: string, now?: () => Date): Extension;
+/**
+ * `ticking` says whether a clock fires the wake-ups kept in `stateRoot` now; a wake-up nothing would fire is refused.
+ * Without it, one always does: `dev`, `start` and AgentCore serve whatever they open.
+ */
+export declare function wakeExtension(stateRoot: string, options?: {
+    now?: () => Date;
+    ticking?: () => boolean;
+}): Extension;

package/dist/harnesses/pi-durable/wake.js

@@ -12,7 +12,14 @@ export const WAKE_TOOLS = ["wake", "unwake"];
 const said = (text) => ({ output: [{ type: "text", text }] });
 const refused = (text) => ({ output: [{ type: "text", text }], isError: true });
 const NOT_A_SESSION = "wake-ups belong to a session, and this conversation is not one (a subagent's): nothing would wake it.";
-export function wakeExtension(stateRoot, now = () => new Date()) {
+const NO_CLOCK = "nothing fires wake-ups for this agent now: the app that opened it does not serve it, so no clock runs. Do the " +
+    "work now, or say it cannot be scheduled.";
+/**
+ * `ticking` says whether a clock fires the wake-ups kept in `stateRoot` now; a wake-up nothing would fire is refused.
+ * Without it, one always does: `dev`, `start` and AgentCore serve whatever they open.
+ */
+export function wakeExtension(stateRoot, options = {}) {
+    const now = options.now ?? (() => new Date());
     return defineExtension({
         name: WAKE_EXTENSION,
         tools: [
@@ -37,6 +44,8 @@ export function wakeExtension(stateRoot, now = () => new Date()) {
                     }),
                 }),
                 execute: async (args, api, context) => {
+                    if (options.ticking?.() === false)
+                        return refused(NO_CLOCK);
                     if ((args.in === undefined) === (args.cron === undefined)) {
                         return refused("pass exactly one of `in` (one-shot) or `cron` (recurring).");
                     }

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 /**
  * The package's one entry (SPEC.md §8), besides each first-party channel's: the Agent API, opening an agent
- * directory and serving it, and what an author writes.
+ * directory and serving it, what a host embedding agents needs beside them (creating one, model credentials and
+ * sign-in), and what an author writes.
  */
 export type { Agent, AgentErrorData, AgentInfo, CompactOptions, ContentPart, CreateSessionOptions, EntriesOptions, Entry, ErrorCode, Json, ListOptions, Message, MessageKey, MessageStatus, MessageStreamEvent, ModelRef, Page, SendRequest, Session, SessionChanges, SessionEvent, SessionSettings, SessionStatus, ThinkingLevel, Tokens, Usage, WaitOptions, } from "./agent-api.ts";
 export { AgentError, LIMITS, hasEnded } from "./agent-api.ts";
 export { openAgent, type LocalAgent, type OpenAgentOptions, type ServeAgentOptions, } from "./harnesses/pi-durable/serve.ts";
 export type { Service } from "./service.ts";
-/** What `openAgent`'s `credentials` takes: where provider credentials are kept, pi-ai's. */
-export type { CredentialStore } from "@earendil-works/pi-ai";
+export { createAgent, type CreatedAgent } from "./authoring.ts";
+export { SignInCancelled, type Credential, type CredentialStore, type ProviderAuth, type SignInEvent, type SignInInteraction, type SignInMethod, type SignInOption, type SignInPrompt, type SignInRequest, type SignInResult, } from "./sign-in-api.ts";
+export { credentialFile, providerAuth, signIn, signInOptions } from "./harnesses/models/host.ts";
 export { defineAgent, defineSchedule, needs, type AgentConfig, type Needs, type SecretSpec, type SecretValues, } from "./harnesses/pi-durable/define.ts";
 export type { ScheduleConfig } from "./schedule/schedule.ts";
 export { defineChannel, type ChannelContext, type ChannelHandler, type ChannelModule, type ForkSource, type LongConnection, type LongConnectionChannelModule, type Routes, } from "./channel.ts";

package/dist/index.js

@@ -1,5 +1,8 @@
 export { AgentError, LIMITS, hasEnded } from "./agent-api.js";
 export { openAgent, } from "./harnesses/pi-durable/serve.js";
+export { createAgent } from "./authoring.js";
+export { SignInCancelled, } from "./sign-in-api.js";
+export { credentialFile, providerAuth, signIn, signInOptions } from "./harnesses/models/host.js";
 export { defineAgent, defineSchedule, needs, } from "./harnesses/pi-durable/define.js";
 export { defineChannel, } from "./channel.js";
 // What a channel reads a request with, answers with, and compares its platform's secret with (constant time).

package/dist/scaffold/add-channel.js

@@ -8,7 +8,7 @@ import { detectRuntime } from "../runtime.js";
 import { assertInsideAgentDir, exists } from "../paths.js";
 import { channelBundleFiles, channelTemplate } from "./templates.js";
 import { writeValues } from "../value-file.js";
-import { envExamplePath } from "../env.js";
+import { envExamplePath } from "../value-file.js";
 import { FEISHU_AGENT_SCOPES } from "../channels/feishu/setup-mode.js";
 import { slackBotScopes } from "../channels/slack/manifest.js";
 const AGENT_SCOPE_LIST = FEISHU_AGENT_SCOPES.map((entry) => entry.request).join(", ");