@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/cli/commands/logs.js

@@ -1,26 +1,28 @@
-/** `fastagent logs agentcore [dir]`: discover and tail the deployed AgentCore CloudWatch logs. */
+/** `fastagent logs agentcore [agent]`: discover and tail the deployed AgentCore CloudWatch logs. */
 import { basename, resolve } from "node:path";
 import { agentcoreName } from "../../deploy/agentcore/plan.js";
 import { tailAgentcoreLogs } from "../../deploy/agentcore/logs.js";
 import { awsRunner } from "../../deploy/runner.js";
 import { enterAgentEnv } from "../../env.js";
-import { failStartup, failUsage, placementOrExit } from "../fail.js";
+import { selectAgentEnvironment } from "../../paths.js";
+import { agentDirOrExit, failStartup, failUsage } from "../fail.js";
 export async function runLogs(host, dirArg, opts) {
     // The host argument is DISPATCHED here, as in runDeploy.
     if (host !== "agentcore")
         failUsage(`logs: unsupported host "${host}" — only agentcore has remote logs`);
-    const placement = placementOrExit(resolve(dirArg));
-    enterAgentEnv(placement.agentDir); // AWS_PROFILE/region/proxy may be definition-local, as on deploy
+    const agentDir = agentDirOrExit(resolve(dirArg));
+    selectAgentEnvironment("production");
+    enterAgentEnv(agentDir);
     const source = opts.source ?? "runtime";
     if (source !== "runtime" && source !== "forwarder") {
         failUsage(`logs: --source must be "runtime" or "forwarder"`);
     }
     const outcome = await tailAgentcoreLogs({
-        name: agentcoreName(basename(placement.workspace)),
+        name: agentcoreName(basename(agentDir)),
         source: source,
         since: opts.since,
         follow: opts.follow === true,
-    }, awsRunner(placement.workspace), (message) => console.error(`[fastagent] logs: ${message}`));
+    }, awsRunner(agentDir), (message) => console.error(`[fastagent] logs: ${message}`));
     if (!outcome.ok)
         failStartup(new Error(`logs stopped: ${outcome.gate}`));
 }

package/dist/cli/commands/models.d.ts

@@ -1,4 +1,5 @@
 export declare function runModels(search: string | undefined, opts?: {
-    refresh?: boolean;
     global?: boolean;
+    refresh?: boolean;
+    json?: boolean;
 }): Promise<void>;

package/dist/cli/commands/models.js

@@ -1,44 +1,46 @@
 /**
- * `fastagent models [search]`: print every "provider/modelId" the agent here (or, outside one or with `-g`, this
- * machine) can name; `[search]` filters by substring. `--refresh` first fetches the model catalog into that scope's
- * `models-store.json`.
+ * `fastagent models [search]`: print every "provider/modelId" the agent here can name (pi-ai's built-ins with their
+ * published catalogs, and the providers its definition declares), or, outside an agent, the built-ins; `[search]`
+ * filters by substring. `--refresh` asks the network for the lists even when the kept ones are fresh.
  */
-import { join } from "node:path";
 import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
-import { formatModelsCommand } from "../models-view.js";
-import { listModels } from "../../engines/pi/config.js";
-import { createPiModelRuntime, globalCatalogPath, machineModelRuntime } from "../../engines/pi/models.js";
-import { refreshMachineModelCatalog, refreshModelCatalog } from "../../engines/pi/open.js";
-import { AGENT_MODEL_CATALOG_FILE, findAgentDir, globalHome, placementDeadEnd } from "../../paths.js";
+import { modelEnvironment } from "../../harnesses/models/environment.js";
+import { listModels, providerOf } from "../../harnesses/models/models.js";
+import { definitionProviders } from "../../harnesses/pi-durable/open.js";
 import { enterAgentEnv } from "../../env.js";
-import { failStartup, placementOrExit } from "../fail.js";
+import { installProxyFetch } from "../../proxy.js";
+import { formatModelsCommand } from "../models-view.js";
+import { failStartup, optionalAgentDirOrExit } from "../fail.js";
 export async function runModels(search, opts = {}) {
-    const cwd = process.cwd();
-    const agentDir = opts.global ? undefined : findAgentDir(cwd);
-    // "Outside an agent" must mean exactly that, as for `login`: inside an agent's subdirectory, or among several agents
-    // with no default, falling back to the machine would list without the agent's own catalog and models.json, and a
-    // refresh would record the models where no deploy carries them. Refused either way; `-g` asks for the machine.
-    if (!opts.global && !agentDir && placementDeadEnd(cwd))
-        placementOrExit(cwd);
-    if (opts.refresh) {
-        // pi fetches a provider's catalog only with a usable credential for it: the scope's own credentials and `.env`
-        // keys, as `login` reads them.
-        enterAgentEnv(agentDir ?? globalHome());
-        if (agentDir) {
-            await refreshModelCatalog(agentDir).catch(failStartup);
-            console.error(`[fastagent] refreshed ${join(agentDir, AGENT_MODEL_CATALOG_FILE)} — commit it: it ships with a deploy`);
-        }
-        else {
-            await refreshMachineModelCatalog().catch(failStartup);
-            console.error(`[fastagent] refreshed ${globalCatalogPath()} — every agent on this machine reads it`);
-        }
+    // "Outside an agent" must mean exactly that, as for `login`: refused inside an agent's subdirectory (findAgentDir);
+    // `-g` asks for pi-ai's built-ins alone.
+    const agentDir = opts.global ? undefined : optionalAgentDirOrExit(process.cwd());
+    let providers = [];
+    if (agentDir) {
+        enterAgentEnv(agentDir); // a provider in code may read its secrets when it is built
+        providers = await definitionProviders(agentDir).catch(failStartup);
+    }
+    else {
+        installProxyFetch();
+    }
+    // Outside an agent, no credentials file is read: the built-ins' lists need none.
+    const environment = await modelEnvironment(agentDir, agentDir ? {} : { credentialStore: new InMemoryCredentialStore() }, providers, { force: opts.refresh === true });
+    const { lines, error } = formatModelsCommand(listModels(environment.models), search);
+    if (opts.json) {
+        const models = lines.map((spec) => {
+            const provider = providerOf(spec);
+            const id = spec.slice(provider.length + 1);
+            return { spec, provider, id, name: environment.models.getModel(provider, id)?.name ?? id };
+        });
+        console.log(JSON.stringify(models, null, 2));
+    }
+    else {
+        for (const spec of lines)
+            console.log(spec);
+        if (error)
+            console.error(error);
     }
-    const models = await (agentDir
-        ? createPiModelRuntime({ agentDir, credentials: new InMemoryCredentialStore() })
-        : machineModelRuntime()).catch(failStartup);
-    const { lines, error } = formatModelsCommand(listModels(models), search);
-    for (const spec of lines)
-        console.log(spec);
-    if (error)
-        console.error(error);
+    // The list printed is the one kept; the warning above it said why it is not newer.
+    if (opts.refresh && environment.catalogProblem !== undefined)
+        process.exitCode = 1;
 }

package/dist/cli/commands/schedules.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Text mode answers "when does each run next, and did the last run work?" from the newest claim alone, so an old file
+ * in the retained window cannot fail it; `--json` adds each schedule's whole retained fire history (the claims under
+ * `schedule/claims/<name>/`). What a run SAID is in its session, once it has fired.
+ */
+export declare function runSchedulesList(dirArg: string, json: boolean): Promise<void>;
+/**
+ * Fire the schedule `name` now, as its clock would: in its session, with its claim and its outcome recorded. It opens
+ * the instance's storage, so a serve of it refuses this, and the other way round. The answer goes to stdout; exit 0
+ * only when its message completed, as `invoke`'s.
+ */
+export declare function runScheduleNow(name: string, dirArg: string, opts: {
+    model?: string;
+    input?: boolean;
+}): Promise<void>;
+/**
+ * Cancel the pending wake-up `id`, whatever session set it: the one way out of a wake-up set where nobody can message
+ * the agent (a schedule's own session). It holds the instance's storage while it writes, so it is refused while a serve
+ * of the instance runs, whose poll writes the same store.
+ */
+export declare function runUnwake(id: string, dirArg: string): Promise<void>;

package/dist/cli/commands/schedules.js

@@ -0,0 +1,143 @@
+/**
+ * `fastagent schedules` — what is going to wake this agent up: the schedules its definition declares, and the wake-ups
+ * it set for itself. `list` shows both, `run` fires a schedule now, `unwake` cancels a wake-up.
+ *
+ * The two have different owners (a schedule is the definition's, a wake-up the state's) but answer the same operator
+ * question, so one command lists both, labelled apart.
+ */
+import { resolve } from "node:path";
+import * as Effect from "effect/Effect";
+import { AgentError, hasEnded } from "../../agent-api.js";
+import { enterAgentEnv } from "../../env.js";
+import { buildDefinitionShape, prepareDefinition } from "../../harnesses/pi-durable/open.js";
+import { holdingInstance, openServing } from "../../harnesses/pi-durable/serve.js";
+import { resolveStateRoot } from "../../paths.js";
+import { nextRun } from "../../schedule/cron.js";
+import { fireScheduleNow, scheduleSessions } from "../../schedule/scheduler.js";
+import { latestFire, readFires } from "../../schedule/state.js";
+import { listWakeups, removeAnyWakeup } from "../../schedule/wakeups.js";
+import { agentDirOrExit, failStartup, failUsage } from "../fail.js";
+import { exitCodeOf } from "../invoke-stream.js";
+import { enterAgentCommand, reportAuth } from "../shared.js";
+/**
+ * Text mode answers "when does each run next, and did the last run work?" from the newest claim alone, so an old file
+ * in the retained window cannot fail it; `--json` adds each schedule's whole retained fire history (the claims under
+ * `schedule/claims/<name>/`). What a run SAID is in its session, once it has fired.
+ */
+export async function runSchedulesList(dirArg, json) {
+    const target = agentDirOrExit(resolve(dirArg));
+    enterAgentEnv(target); // FASTAGENT_STATE_DIR may live in .env — read the SAME state root the scheduler wrote
+    const stateRoot = resolveStateRoot(target);
+    // Its shape only: listing what will fire needs none of the values the code reads.
+    const { schedules } = await prepareDefinition(target)
+        .then((definition) => buildDefinitionShape(definition, process.env))
+        .catch(failStartup);
+    const sessions = scheduleSessions(stateRoot);
+    const now = new Date();
+    // A claim state this command cannot read is the operator's to fix: one line, never a Node stack.
+    const read = (name, what, fn) => {
+        try {
+            return fn();
+        }
+        catch (e) {
+            failStartup(new Error(`the ${what} of "${name}" is unreadable (state: ${stateRoot}): ${String(e)}`));
+        }
+    };
+    const rows = schedules.map(({ name, cron, tz, prompt }) => ({
+        name,
+        cron,
+        ...(tz === undefined ? {} : { tz }),
+        ...(typeof prompt === "string" ? { prompt } : {}),
+        next: nextRun(cron, tz, now)?.toISOString() ?? null,
+        session: sessions.get(name) ?? null,
+    }));
+    const wakeups = listWakeups(stateRoot);
+    if (json) {
+        const withFires = rows.map((r) => ({
+            ...r,
+            fires: read(r.name, "fire history", () => readFires(stateRoot, r.name)),
+        }));
+        console.log(JSON.stringify({ schedules: withFires, wakeups }, null, 2));
+        return;
+    }
+    if (rows.length === 0 && wakeups.length === 0) {
+        console.error(`nothing scheduled — no src/schedules/, no wake-ups (agent: ${target})`);
+        return;
+    }
+    for (const r of rows) {
+        const last = read(r.name, "last fire", () => latestFire(stateRoot, r.name));
+        const lastRun = last ? `last ${last.firedAt} ${last.outcome ?? "unreported"}` : "never run";
+        console.log(`${r.name.padEnd(20)} next ${(r.next ?? "(never)").padEnd(26)}cron ${r.cron}${r.tz ? ` ${r.tz}` : ""}  ${lastRun}  session=${r.session ?? "(none yet)"}`);
+    }
+    for (const w of wakeups) {
+        const kind = w.cron ? `cron ${w.cron}${w.tz ? ` ${w.tz}` : ""}` : "one-shot";
+        console.log(`wake ${w.id}  ${w.fireAt}  ${kind}  session=${w.session}  ${w.prompt.slice(0, 60)}`);
+    }
+}
+/**
+ * Fire the schedule `name` now, as its clock would: in its session, with its claim and its outcome recorded. It opens
+ * the instance's storage, so a serve of it refuses this, and the other way round. The answer goes to stdout; exit 0
+ * only when its message completed, as `invoke`'s.
+ */
+export async function runScheduleNow(name, dirArg, opts) {
+    // The name before the model, from the definition's shape: a script told its schedule does not exist need not set up
+    // a model first.
+    const { agentDir, modelSpec } = await enterAgentCommand(dirArg, opts, async (target) => {
+        const declared = await prepareDefinition(target)
+            .then((definition) => buildDefinitionShape(definition, process.env).schedules.map((s) => s.name))
+            .catch(failStartup);
+        if (!declared.includes(name)) {
+            failUsage(`no schedule "${name}" in ${target}/src/schedules/ (declared: ${declared.join(", ") || "none"})`);
+        }
+    });
+    // Refused while the instance holds work a stopped serve left: this process would run it, and cut it off at its exit.
+    const { agent, models, schedules, stateRoot } = await openServing(agentDir, {
+        model: modelSpec,
+        unfinished: "refuse",
+    }).catch(failStartup);
+    const schedule = schedules.find((s) => s.name === name);
+    if (schedule === undefined) {
+        // Checked above: only an edit of src/schedules/ while this ran gets here.
+        await agent.close();
+        failStartup(new Error(`src/schedules/ changed while this ran: "${name}" is gone from it — run it again`));
+    }
+    await reportAuth(models, modelSpec, agentDir);
+    const fired = await Effect.runPromise(fireScheduleNow({ agent, stateRoot, schedule })).catch(failStartup);
+    const sessionId = scheduleSessions(stateRoot).get(name);
+    const message = fired.fired && sessionId !== undefined
+        ? await agent.messages
+            .get({ sessionId, idempotencyKey: fired.slot.toISOString() })
+            .catch((error) => {
+            // A fire refused before it sent its message (a busy session) has none.
+            if (error instanceof AgentError && error.code === "not_found")
+                return undefined;
+            throw error;
+        })
+            .catch(failStartup)
+        : undefined;
+    const ended = message !== undefined && hasEnded(message) ? message : undefined;
+    if (ended?.answer !== undefined)
+        process.stdout.write(`${ended.answer.text}\n`);
+    await agent.close();
+    if (!fired.fired)
+        console.error(`[fastagent] ${name} did not fire: ${fired.skippedReason}`);
+    // The claim counts a cut-off answer as completed; the exit code does not.
+    else if (ended?.status === "incomplete")
+        console.error(`[fastagent] ${name}: its answer was cut off (incomplete)`);
+    process.exit(ended === undefined ? 1 : exitCodeOf(ended));
+}
+/**
+ * Cancel the pending wake-up `id`, whatever session set it: the one way out of a wake-up set where nobody can message
+ * the agent (a schedule's own session). It holds the instance's storage while it writes, so it is refused while a serve
+ * of the instance runs, whose poll writes the same store.
+ */
+export async function runUnwake(id, dirArg) {
+    const target = agentDirOrExit(resolve(dirArg));
+    enterAgentEnv(target);
+    const stateRoot = resolveStateRoot(target);
+    const removed = await holdingInstance(stateRoot, () => removeAnyWakeup(stateRoot, id)).catch(failStartup);
+    if (removed === undefined) {
+        failStartup(new Error(`no pending wake-up ${id} (state: ${stateRoot}); \`fastagent schedules list\` shows them`));
+    }
+    console.log(`removed wake ${removed.id}  ${removed.fireAt}  session=${removed.session}  ${removed.prompt.slice(0, 60)}`);
+}

package/dist/cli/commands/start.d.ts

@@ -1,34 +1,35 @@
-import { type AgentService } from "../../service.ts";
+import type { Agent } from "../../agent-api.ts";
+import type { AgentConfig } from "../../harnesses/pi-durable/define.ts";
+import { type ServedAgent } from "../../service.ts";
 export interface StartOptions {
     port?: string;
     bind?: string;
     model?: string;
     tunnel?: boolean;
-    /** false ⇔ `--no-invoke`: withhold `POST /invoke` for THIS run (`http.invoke` is the persistent form). */
-    invoke?: boolean;
     input?: boolean;
 }
-type StartedService = AgentService & {
+/** What `start` opened and serves: the agent too, for a deployment's own check of what it runs. */
+type StartedService = ServedAgent & {
+    agent: Agent;
     stateRoot: string;
     port: number;
+    config: AgentConfig;
 };
 export declare function runStart(dirArg: string, opts: StartOptions): Promise<void>;
 /** What the storage stage hands the opening stage. */
 export interface PreparedWorkspace {
-    /** The workspace to open — the volume's `base/` when a release manifest selected one. */
+    /** The agent directory to open — the storage's deployed definition when a release manifest selected one. */
     dir: string;
-    /** Set when this process took a deployed workspace. */
+    /** The storage root, set when this process took a deployment's storage. */
     deployed?: {
         root: string;
-        agent: string;
     };
 }
 /**
- * Stage one — TAKE the workspace: verify the storage is mounted, apply the release, and point the machinery at the
- * volume.
+ * Stage one — TAKE the storage: verify it is mounted, apply the release, and point the machinery at the volume.
  */
 export declare function prepareStartWorkspace(dirArg: string): Promise<PreparedWorkspace>;
 export declare function openStartService(dirArg: string, opts: StartOptions): Promise<StartedService>;
-/** Internal entry loaded from the active workspace's installed package after storage initialization. */
+/** Internal entry loaded from the agent's installed package after storage initialization. */
 export declare function openPreparedStartService(dirArg: string, opts: StartOptions): Promise<StartedService>;
 export {};

package/dist/cli/commands/start.js

@@ -11,19 +11,16 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
-import * as Effect from "effect/Effect";
 import { applyCarriedEnv } from "../../deploy/secrets.js";
 import { applyReleaseEnv, installAgentDependencies, parseDeploymentRelease, prepareDeployment, } from "../../deploy/workspace.js";
-import { resolveSecretsDir, isAgentcoreRuntime, isUnderDir, exists } from "../../paths.js";
+import { selectAgentEnvironment, resolveSecretsDir, isAgentcoreRuntime, isUnderDir, exists } from "../../paths.js";
 import { log, setLogLevel } from "../../log.js";
-import { createPiAgentFromDir } from "../../engines/pi/open.js";
-import { DEFAULT_HTTP_PORT, mountAgentService } from "../../service.js";
-import { logAgentLoop } from "../../observe.js";
+import { openServing } from "../../harnesses/pi-durable/serve.js";
+import { DEFAULT_HTTP_PORT, serveAgent } from "../../service.js";
 import { mountAgentcoreService, deferAgentcoreService } from "../../channels/agentcore-service.js";
-import { createWakeAlarmSink } from "../../schedule/wake-alarm.js";
-import { setWakeupsSink } from "../../schedule/wakeups.js";
 import { failStartup } from "../fail.js";
-import { announceControl, assertTunnelBindable, bindLine, cliMountOptions, serveService, serve, withRunOverrides, } from "../serve.js";
+import { unmarkDevServe } from "../../serving-command.js";
+import { assertTunnelBindable, bindLine, cliMountOptions, serveService, serve } from "../serve.js";
 import { enterAgentCommand, parseBind, parsePort, reportAssembly } from "../shared.js";
 export async function runStart(dirArg, opts) {
     const portFlag = parsePort(opts.port, "--port", "flag");
@@ -36,6 +33,8 @@ export async function runStart(dirArg, opts) {
         failStartup(error);
     }
     setLogLevel("info");
+    selectAgentEnvironment("production");
+    unmarkDevServe();
     if (isAgentcoreRuntime()) {
         // The generated Runtime resource sets PORT; 8080 is the platform's contract when nothing does.
         const port = portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? 8080;
@@ -44,19 +43,13 @@ export async function runStart(dirArg, opts) {
             assemble: async (prepared) => {
                 const service = await openPreparedWorkspace(prepared, opts);
                 await service.ready;
-                announceControl(service, { host: bindFlag, tunnel: false });
                 return service;
             },
         });
-        serve(deferred.handler, { port, host: bindFlag }, {
-            // The assembly report waits for the first envelope, so this line is the only sign of life a booted container
-            // gives.
-            onListening: (port) => {
-                // NOT `readyAddressLines`: this posture serves the Runtime's `/invocations` contract, not our `/invoke`.
-                log.info(bindLine(bindFlag, port));
-                log.info("[fastagent] agentcore: the definition opens on the first invocation");
-            },
-            onShutdown: () => deferred.close(),
+        // The assembly report waits for the first envelope, so this line is the only sign of life a booted container gives.
+        serve(deferred, { port, host: bindFlag }, (port) => {
+            log.info(bindLine(bindFlag, port));
+            log.info("[fastagent] agentcore: the definition opens on the first invocation");
         });
         return;
     }
@@ -66,11 +59,10 @@ export async function runStart(dirArg, opts) {
     const tunnel = opts.tunnel ?? false;
     // An unset bind stays the wildcard: this is the container posture, and a published port needs it.
     assertTunnelBindable(bindFlag, tunnel);
-    serveService(service, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? service.port, host: bindFlag }, { tunnel, agentDir: service.agentDir, stateRoot: service.stateRoot });
+    serveService(service, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? service.port, host: bindFlag }, { tunnel, agentDir: service.agentDir, stateRoot: service.stateRoot, config: service.config });
 }
 /**
- * Stage one — TAKE the workspace: verify the storage is mounted, apply the release, and point the machinery at the
- * volume.
+ * Stage one — TAKE the storage: verify it is mounted, apply the release, and point the machinery at the volume.
  */
 export async function prepareStartWorkspace(dirArg) {
     const manifestPath = process.env.FASTAGENT_RELEASE_FILE;
@@ -78,7 +70,7 @@ export async function prepareStartWorkspace(dirArg) {
         return { dir: dirArg };
     const storage = process.env.FASTAGENT_STORAGE_DIR;
     if (!storage)
-        throw new Error("FASTAGENT_STORAGE_DIR is required for a deployed workspace");
+        throw new Error("FASTAGENT_STORAGE_DIR is required for a deployment");
     const root = resolve(storage);
     const manifest = parseDeploymentRelease(await readFile(manifestPath, "utf8"));
     const dir = await prepareDeployment(resolve(dirArg), root, manifest);
@@ -86,26 +78,27 @@ export async function prepareStartWorkspace(dirArg) {
     // their state is the one failure they could not diagnose from the logs.
     process.env.FASTAGENT_STATE_DIR ||= join(root, ".state");
     process.env.FASTAGENT_SECRETS_DIR ||= join(root, ".secrets");
-    process.env.FASTAGENT_AGENT = manifest.agent;
+    // mise's data directory, on the storage rather than the container's disk. The image's packages are in mise's system
+    // directory, which mise reads as well, so a start installs nothing there.
+    process.env.MISE_DATA_DIR ||= join(process.env.FASTAGENT_STATE_DIR, "mise");
     // The release's own declarations, projected into the environment it was resolved FOR. This must stay BEFORE
-    // `enterAgentEnv` reads the workspace's `.env`, which is what makes either source outrank a value edited on the
+    // `enterAgentEnv` reads the agent's `.env`, which is what makes either source outrank a value edited on the
     // box (applyReleaseEnv's own tests pin the precedence).
     applyReleaseEnv(manifest);
     process.chdir(dir);
-    return { dir, deployed: { root, agent: manifest.agent } };
+    return { dir, deployed: { root } };
 }
 /**
- * Stage two — RUN in the prepared workspace: install the agent's dependencies, then open through the workspace's own
- * FastAgent install.
+ * Stage two — RUN the prepared agent directory: install its dependencies, then open through its own FastAgent install.
  */
 async function openPreparedWorkspace(prepared, opts) {
     let open = openPreparedStartService;
     if (prepared.deployed) {
-        const { root, agent } = prepared.deployed;
-        const agentDir = join(prepared.dir, agent);
+        const { root } = prepared.deployed;
+        const agentDir = prepared.dir;
         if (await exists(join(agentDir, "package.json"))) {
             await installAgentDependencies(root, agentDir);
-            // Tools and their session context must share the workspace's runtime module instance.
+            // Tools and their session context must share the agent's runtime module instance.
             const entry = createRequire(join(agentDir, "package.json")).resolve("@fastagent-sh/fastagent");
             const local = (await import(__rewriteRelativeImportExtension(new URL("./cli/commands/start.js", pathToFileURL(entry)).href)));
             // A version-skewed dependency resolves and imports fine, then fails as "open is not a function" with nothing
@@ -121,45 +114,25 @@ async function openPreparedWorkspace(prepared, opts) {
 export async function openStartService(dirArg, opts) {
     return openPreparedWorkspace(await prepareStartWorkspace(dirArg), opts);
 }
-/** Internal entry loaded from the active workspace's installed package after storage initialization. */
+/** Internal entry loaded from the agent's installed package after storage initialization. */
 export async function openPreparedStartService(dirArg, opts) {
-    const placement = await enterAgentCommand(dirArg, opts);
-    const opened = await createPiAgentFromDir(placement.agentDir, {
-        model: placement.modelSpec,
-        serving: true,
-    });
-    const { agent, agentDir, config, stateRoot, sessionsDir } = opened;
-    await reportAssembly({ ...opened, modelSpec: placement.modelSpec }, {
-        afterTools: [
-            ["state", stateRoot],
-            ["sessions", sessionsDir],
-        ],
+    const { agentDir, modelSpec } = await enterAgentCommand(dirArg, opts);
+    const opened = await openServing(agentDir, {
+        model: modelSpec,
+        // AgentCore's session storage refuses SQLite's own locks; the deployment's lease makes the dotfile lock safe.
+        storage: { instance: isAgentcoreRuntime() ? "leased-dotfile" : "posix" },
     });
+    const { stateRoot } = opened;
+    await reportAssembly(opened, modelSpec);
     if (isUnderDir(stateRoot, agentDir)) {
         log.info("[fastagent] note: state lives under the definition; use FASTAGENT_STATE_DIR on persistent storage for deployment.");
     }
     if (isUnderDir(resolveSecretsDir(agentDir), agentDir)) {
         log.info("[fastagent] note: credentials live under the definition; use FASTAGENT_SECRETS_DIR on persistent storage for deployment.");
     }
-    const traced = logAgentLoop(agent);
-    const onStateReady = isAgentcoreRuntime() ? armWakeAlarms(stateRoot) : undefined;
-    const mountable = withRunOverrides(opened, opts);
+    const { config } = opened.definition;
     const service = await (isAgentcoreRuntime()
-        ? mountAgentcoreService(mountable, { wrapAgent: () => traced, onStateReady })
-        : mountAgentService(mountable, cliMountOptions(() => traced)));
-    return { ...service, stateRoot, port: config.http?.port ?? DEFAULT_HTTP_PORT };
-}
-/**
- * Install the wake-ALARM sink before the scheduler starts: the first wake poll may advance a recurring entry, and that
- * save must already re-arm its alarm.
- */
-function armWakeAlarms(stateRoot) {
-    const secret = process.env.FASTAGENT_WAKE_SECRET;
-    if (!secret) {
-        log.warn("[fastagent] FASTAGENT_WAKE_SECRET is missing; external wake alarms cannot be registered");
-        return undefined;
-    }
-    const sink = Effect.runSync(createWakeAlarmSink({ secret }));
-    setWakeupsSink(sink);
-    return () => sink(stateRoot);
+        ? mountAgentcoreService(opened)
+        : serveAgent(opened, cliMountOptions(config)));
+    return { ...service, agent: opened.agent, stateRoot, port: config.http?.port ?? DEFAULT_HTTP_PORT, config };
 }

package/dist/cli/content-view.d.ts

@@ -0,0 +1,9 @@
+/** How the CLI writes an agent's content. */
+import type { BoundContent } from "../content/declare.ts";
+import { type ResolvedContent } from "../content/resolve.ts";
+/**
+ * The report lines for an agent's content — `works on` / `knows`, one per entry, then a `notice` line for each
+ * thing its resolution has to say, then one for each directory this machine binds that is not here — shared by the
+ * startup report, `info` and `content list`, so the three say the same thing.
+ */
+export declare function contentLines(content: readonly ResolvedContent[], absent?: readonly BoundContent[]): [label: string, value: string][];

package/dist/cli/content-view.js

@@ -0,0 +1,26 @@
+import { LOCAL_CONTEXT_FILE } from "../paths.js";
+import { absentNotice } from "../content/resolve.js";
+/** What a content entry is, in the words the reports use. */
+function contentKind(c) {
+    if (c.kind !== "github")
+        return `this machine only, bound in ${LOCAL_CONTEXT_FILE}`;
+    const github = `github ${c.repo}${c.ref ? `@${c.ref}` : ""}`;
+    return c.clone ? `${github}, a clone brought up to date at each start` : `${github}, your checkout bound here`;
+}
+/**
+ * The report lines for an agent's content — `works on` / `knows`, one per entry, then a `notice` line for each
+ * thing its resolution has to say, then one for each directory this machine binds that is not here — shared by the
+ * startup report, `info` and `content list`, so the three say the same thing.
+ */
+export function contentLines(content, absent = []) {
+    const lines = content.flatMap((c) => [
+        [c.readonly ? "knows" : "works on", `${c.name.padEnd(width(content))}  ${c.location} (${contentKind(c)})`],
+        ...c.notices.map((notice) => ["notice", `${c.name}: ${notice}`]),
+    ]);
+    for (const binding of absent)
+        lines.push(["notice", absentNotice(binding)]);
+    return lines.length === 0 ? [["content", "(none)"]] : lines;
+}
+function width(content) {
+    return Math.max(0, ...content.map((c) => c.name.length));
+}

package/dist/cli/fail.d.ts

@@ -1,22 +1,19 @@
-import { type ResolvedPlacement } from "../paths.ts";
-import { gateSecrets } from "../secrets-gate.ts";
 /** The ONE error prefix every error message carries — bold red when stderr renders color, plain otherwise. */
 export declare function errorPrefix(colors?: boolean): string;
+/**
+ * A ticket's process (ticket.ts): a failure that ends the process is the ticket's failure too, recorded before the
+ * process exits, wherever in a long command it happens.
+ */
+export declare function recordFailures(record: ((message: string) => void) | undefined): void;
 /**
  * User-fixable startup problems (missing model / bad config / broken definition) are thrown as plain `Error` — print
  * just the message. Anything else (a TypeError, a non-Error throw) is a bug: keep the stack.
  */
 export declare function failStartup(error: unknown): never;
-/**
- * {@link gateSecrets} at the process boundary, for a command that runs ONE owner's code (`fastagent
- * tool`, `fastagent routine run`). The gate throws SYNCHRONOUSLY, so there is no promise to hang the usual
- * `.catch(failStartup)` on, and a raw throw reaches `cli.ts`'s top-level await as a Node stack that
- * buries the one line naming the file. The catch translates that expected failure into the CLI's
- * single-line refusal and exits 1; nothing is recovered.
- */
-export declare function gateSecretsOrExit(input: Parameters<typeof gateSecrets>[0]): void;
-/** THE placement entry point for commands: resolve `dir`, or exit 1 with the one-line refusal. */
-export declare function placementOrExit(dir: string): ResolvedPlacement;
+/** THE addressing entry point for commands: the agent directory `dir` names, or exit 1 with the one-line refusal. */
+export declare function agentDirOrExit(dir: string): string;
+/** {@link findAgentDir} for a command that also works without an agent: undefined when there is none, exit 1 inside one. */
+export declare function optionalAgentDirOrExit(dir: string): string | undefined;
 /**
  * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination discovered in a
  * command body): print the message and exit 2.