@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/dev-supervisor.js

@@ -5,7 +5,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 { AGENT_CONFIG_FILE, CONTEXT_FILE, INSTANCE_CONFIG_FILE, isUnderDir } from "./paths.js";
 import { dotEnvPath } from "./value-file.js";
 import { log } from "./log.js";
 import { openExternalUrl } from "./open-url.js";
@@ -14,7 +14,7 @@ import { activeWork } from "./channels/busy.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** The agent's code (its tools, extensions, channels and schedules), loaded ONCE per worker: a restart is its only re-read. */
 const CODE_DIR = "src";
-const WATCHED_HINT = `${CODE_DIR}/, package.json, fastagent.config.ts, context.json, context.local.json, .secrets/.env`;
+const WATCHED_HINT = `${CODE_DIR}/, package.json, fastagent.config.ts, context.json, fastagent.json, .secrets/.env`;
 /** chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. */
 export function devWatchIgnored(root, envFile) {
     // The `.env` is allow-listed by its RESOLVED path, not by the `.secrets` name.
@@ -25,9 +25,9 @@ export function devWatchIgnored(root, envFile) {
         const rel = relative(root, path);
         // Code inputs at the agent dir root: config, package.json, and the code loaded once per worker (a restart is
         // their only re-read).
-        if (rel === AGENT_CONFIG_FILE || rel === CONTEXT_FILE || rel === LOCAL_CONTEXT_FILE)
+        if (rel === AGENT_CONFIG_FILE || rel === CONTEXT_FILE)
             return false;
-        if (rel === "package.json")
+        if (rel === "package.json" || rel === INSTANCE_CONFIG_FILE)
             return false;
         const segments = rel.split(sep);
         if (segments[0] === CODE_DIR)
@@ -95,7 +95,6 @@ export async function runDevSupervisor(agentDir, options = {}) {
                         tunnel = t;
                         void announceWebhooks(agentDir, t.url, declaredChannels(m.routeChannels ?? []), {
                             openUrl: openExternalUrl,
-                            stateRoot: resolveStateRoot(agentDir),
                         });
                     }
                 });
@@ -145,9 +144,9 @@ export async function runDevSupervisor(agentDir, options = {}) {
     });
     watcher.on("error", (error) => log.warn(`[fastagent] file watching error (${error.message}); some edits may need a manual restart`));
     log.info(`[fastagent] watching ${WATCHED_HINT} — code edits restart the dev worker (--no-watch to disable); SYSTEM.md, AGENTS.md, skills/ and prompts/ go live without a restart`);
-    // FASTAGENT_SECRETS_DIR can move the `.env` OUT of the agent dir entirely.
+    // FASTAGENT_SECRETS_DIR or --env-file can move the `.env` OUT of the agent dir entirely.
     if (!isUnderDir(dotEnvPath(agentDir), agentDir)) {
-        log.warn(`[fastagent] .env lives outside the agent dir (FASTAGENT_SECRETS_DIR → ${dotEnvPath(agentDir)}) — it is NOT watched; restart dev after editing it`);
+        log.warn(`[fastagent] .env lives outside the agent dir (FASTAGENT_SECRETS_DIR or --env-file → ${dotEnvPath(agentDir)}) — it is NOT watched; restart dev after editing it`);
     }
     const shutdown = () => {
         worker?.kill("SIGTERM");

package/dist/environment/declare.js

@@ -61,7 +61,7 @@ function declareVariables(raw) {
         if (!isEnvName(name))
             throw new Error(`${at} is not an environment variable name`);
         if (isDeployOwned(name)) {
-            throw new Error(`${at} is set by the deployment itself, so it cannot be declared: a value file's copy never travels`);
+            throw new Error(`${at} is set by the deployment itself, so it cannot be declared`);
         }
         if (!variable || typeof variable !== "object" || Array.isArray(variable)) {
             throw new Error(`${at} must be { "description": "what it is for" }: its value goes in the stage's value file ` +
@@ -87,8 +87,9 @@ function declareVariables(raw) {
 export function declaredVariables(environment) {
     return Object.entries(environment?.variables ?? {}).map(([name, { description }]) => ({
         name,
-        source: CONTEXT_FILE,
+        declaredIn: CONTEXT_FILE,
         description,
+        optional: false,
     }));
 }
 function declarePackages(raw) {

package/dist/environment/mise.d.ts

@@ -48,4 +48,6 @@ export declare function installPackages(agentDir: string, bin: string, packages:
  * 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 prepareEnvironment(agentDir: string, env: NodeJS.ProcessEnv): Promise<Record<string, string>>;
+export declare function prepareEnvironment(agentDir: string, env: NodeJS.ProcessEnv, 
+/** What the packages' `PATH` is computed over: the agent's own, which is not the installer's. */
+commandsEnv?: NodeJS.ProcessEnv): Promise<Record<string, string>>;

package/dist/environment/mise.js

@@ -256,7 +256,9 @@ function missingMise(agentDir) {
  * 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 async function prepareEnvironment(agentDir, env) {
+export async function prepareEnvironment(agentDir, env, 
+/** What the packages' `PATH` is computed over: the agent's own, which is not the installer's. */
+commandsEnv = env) {
     const declared = loadEnvironment(agentDir);
     const missingApt = missingAptPackages(declared?.aptPackages ?? []);
     if (missingApt && missingApt.length > 0)
@@ -268,5 +270,5 @@ export async function prepareEnvironment(agentDir, env) {
     if (!bin)
         throw missingMise(agentDir);
     await installPackages(agentDir, bin, packages, [], env);
-    return packagesEnvironment(agentDir, bin, packageSpecs(packages), env);
+    return packagesEnvironment(agentDir, bin, packageSpecs(packages), commandsEnv);
 }

package/dist/feishu.d.ts

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
-export { feishuChannel, feishuIngress, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, type FeishuChannelOptions, type FeishuWebSocketChannelOptions, type FeishuMessageEvent, type FeishuMessage, type FeishuRoute, type FeishuFailure, } from "./channels/feishu/feishu.ts";
+export { feishuChannel, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, type FeishuChannelOptions, type FeishuWebSocketChannelOptions, type FeishuMessageEvent, type FeishuMessage, type FeishuRoute, type FeishuFailure, } from "./channels/feishu/feishu.ts";
 export { feishuThreads, feishuTransport, type FeishuTransport } from "./channels/feishu/shared-api.ts";

package/dist/feishu.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
-export { feishuChannel, feishuIngress, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, } from "./channels/feishu/feishu.js";
+export { feishuChannel, feishuWebSocketChannel, defaultFeishuRoute, feishuEnvelope, } from "./channels/feishu/feishu.js";
 export { feishuThreads, feishuTransport } from "./channels/feishu/shared-api.js";

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

@@ -11,6 +11,7 @@ export interface Catalogs {
      */
     refresh(models: Models, options?: {
         force?: boolean;
+        offline?: boolean;
     }): Promise<string | undefined>;
 }
 /** The catalogs kept in `dir`, or, without one, for this process alone. `url` and `timeoutMs` are for tests. */

package/dist/harnesses/models/catalog.js

@@ -110,8 +110,7 @@ export function catalogsIn(dir, options = {}) {
             };
         },
         fetched,
-        async refresh(models, { force = false } = {}) {
-            const offline = process.env[OFFLINE_VARIABLE] === "1";
+        async refresh(models, { force = false, offline = process.env[OFFLINE_VARIABLE] === "1" } = {}) {
             const signal = AbortSignal.timeout(timeoutMs);
             const why = (error) => signal.aborted ? `no answer within ${timeoutMs / 1000}s` : messageOf(error);
             const [published, own] = await Promise.all([

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

@@ -35,8 +35,9 @@ export interface ModelEnvironment {
  * The model environment of the agent in `agentDir` (or, without one, of a caller with no directory: the named or global
  * credentials file). A supplied `credentialStore` is used as given; otherwise the files: the directory's own layers
  * ({@link resolveAuthLayers}), or the named file, or the global one. `providers` are the definition's. `environment` is
- * what the agent's environment adds to this process's: its keys, the requests' settings, and where its files are
- * (`FASTAGENT_AUTH_PATH`, `FASTAGENT_STATE_DIR`) are all read there first. The model lists are refreshed before it
+ * the one source of the values a provider authenticates with and of the requests' settings, which this process's
+ * environment never adds to; where its files are (`FASTAGENT_AUTH_PATH`, `FASTAGENT_STATE_DIR`) is still read from
+ * this process's first. The model lists are refreshed before it
  * resolves, kept in the instance's state root (`stateRoot`, else the directory's); `force` asks the network even when
  * they are fresh.
  */
@@ -44,5 +45,9 @@ export declare function modelEnvironment(agentDir: string | undefined, source?:
     force?: boolean;
     stateRoot?: string;
     environment?: Readonly<Record<string, string>>;
+    /** The environment `FASTAGENT_AUTH_PATH` and `FASTAGENT_STATE_DIR` are read from. Default: this process's. */
+    env?: Readonly<Record<string, string | undefined>>;
+    /** Refresh the lists without the network. Default: `FASTAGENT_OFFLINE` is `1` in this process's environment. */
+    offline?: boolean;
 }): Promise<ModelEnvironment>;
 export {};

package/dist/harnesses/models/environment.js

@@ -15,14 +15,15 @@ import { environmentAuth, modelsOver, probeAuthSource } from "./models.js";
  * The model environment of the agent in `agentDir` (or, without one, of a caller with no directory: the named or global
  * credentials file). A supplied `credentialStore` is used as given; otherwise the files: the directory's own layers
  * ({@link resolveAuthLayers}), or the named file, or the global one. `providers` are the definition's. `environment` is
- * what the agent's environment adds to this process's: its keys, the requests' settings, and where its files are
- * (`FASTAGENT_AUTH_PATH`, `FASTAGENT_STATE_DIR`) are all read there first. The model lists are refreshed before it
+ * the one source of the values a provider authenticates with and of the requests' settings, which this process's
+ * environment never adds to; where its files are (`FASTAGENT_AUTH_PATH`, `FASTAGENT_STATE_DIR`) is still read from
+ * this process's first. The model lists are refreshed before it
  * resolves, kept in the instance's state root (`stateRoot`, else the directory's); `force` asks the network even when
  * they are fresh.
  */
 export async function modelEnvironment(agentDir, source = {}, providers = [], options = {}) {
     const environment = options.environment ?? {};
-    const env = { ...process.env, ...environment };
+    const env = { ...(options.env ?? process.env), ...environment };
     assertOneCredentialSource(source);
     const files = source.credentialStore
         ? undefined
@@ -34,7 +35,10 @@ export async function modelEnvironment(agentDir, source = {}, providers = [], op
     const stateRoot = options.stateRoot ?? (agentDir === undefined ? undefined : resolveStateRoot(agentDir, env));
     const catalogs = catalogsIn(stateRoot === undefined ? undefined : join(stateRoot, "models"));
     const models = modelsOver(credentials, providers, catalogs, environment);
-    const catalogProblem = await catalogs.refresh(models, { force: options.force === true });
+    const catalogProblem = await catalogs.refresh(models, {
+        force: options.force === true,
+        ...(options.offline === undefined ? {} : { offline: options.offline }),
+    });
     if (catalogProblem !== undefined)
         log.warn(`[fastagent] ${catalogProblem}`);
     return {
@@ -58,7 +62,7 @@ export async function modelEnvironment(agentDir, source = {}, providers = [], op
             }
             // `read` never refreshes: this is the kind on file, whatever became of it.
             const stored = (await credentials.read(provider))?.type;
-            const fromEnvironment = stored === undefined ? undefined : (await environmentAuth(provider, env, undefined, providers))?.source;
+            const fromEnvironment = stored === undefined ? undefined : (await environmentAuth(provider, environment, undefined, providers))?.source;
             const shadowed = resolved.source !== undefined && fromEnvironment !== resolved.source ? fromEnvironment : undefined;
             return {
                 ...(store ? { path: await store.layerOf(provider) } : {}),

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

@@ -1,10 +1,3 @@
-/**
- * What an embedding host calls for model credentials (sign-in-api.ts has the types): a store kept where the host
- * chooses, a sign-in in its own UI, and what authenticates a provider. Thin over what `fastagent login`, `logout` and
- * `auth check` run, so each rule keeps one implementation. The one translation between FastAgent's types and pi-ai's
- * is here, written without casts and with every function checked as a function, so it stops compiling when the two
- * drift apart.
- */
 import type { CredentialStore as PiCredentialStore } from "@earendil-works/pi-ai";
 import type { CredentialStore, ProviderAuth, SignInOption, SignInRequest, SignInResult } from "../../sign-in-api.ts";
 /**

package/dist/harnesses/models/host.js

@@ -1,3 +1,11 @@
+/**
+ * What an embedding host calls for model credentials (sign-in-api.ts has the types): a store kept where the host
+ * chooses, a sign-in in its own UI, and what authenticates a provider. Thin over what `fastagent login`, `logout` and
+ * `auth check` run, so each rule keeps one implementation. The one translation between FastAgent's types and pi-ai's
+ * is here, written without casts and with every function checked as a function, so it stops compiling when the two
+ * drift apart.
+ */
+import { definedValues } from "../../declared-secrets.js";
 import { resolveOverridePath } from "../../paths.js";
 import { fastagentCredentialStore } from "./credentials.js";
 import { loginOptionsOver, loginOver } from "./login.js";
@@ -74,7 +82,8 @@ export function signIn(request) {
  * does; rejects when resolving fails, such as a refresh the provider refused.
  */
 export async function providerAuth(credentials, provider) {
-    const models = modelsOver(piCredentials(credentials));
+    // The host's own environment: the answer is what a request this process sends authenticates with.
+    const models = modelsOver(piCredentials(credentials), [], undefined, definedValues(process.env));
     if (models.getProvider(provider) === undefined)
         throw new Error(`unknown provider "${provider}"`);
     const checked = await models.checkAuth(provider);

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

@@ -1,11 +1,3 @@
-/**
- * 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 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 { type AuthInteraction, type CredentialStore, type Provider } from "@earendil-works/pi-ai";
 import { type SignInMethod, type SignInOption, type SignInResult } from "../../sign-in-api.ts";
 /** A sign-in that cannot start as asked: an unknown provider, or a choice a caller without menus did not make. */

package/dist/harnesses/models/login.js

@@ -6,6 +6,7 @@
  * ({@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 { definedValues } from "../../declared-secrets.js";
 import { InMemoryCredentialStore, } from "@earendil-works/pi-ai";
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile } from "node:fs/promises";
@@ -36,8 +37,8 @@ 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.
     const held = new Map((await storeOf(credentials).list()).map((info) => [info.providerId, info.type]));
-    // The environment alone, over no store: what authenticates a provider nothing is stored for.
-    const environment = modelsOver(new InMemoryCredentialStore(), providers);
+    // The environment alone, over no store: what authenticates a provider nothing is stored for, here the host's own.
+    const environment = modelsOver(new InMemoryCredentialStore(), providers, undefined, definedValues(process.env));
     const offered = [];
     for (const provider of loginProviders(providers)) {
         const methods = ["oauth", "api_key"].filter((method) => provider.auth[method === "oauth" ? "oauth" : "apiKey"]);
@@ -129,7 +130,7 @@ export async function loginOver(request, internals = {}) {
     // The key under test lives here, not in the file, until it passes.
     const trial = new InMemoryCredentialStore();
     // Only a key needs the registry: it is checked with one request before it is kept.
-    const models = method === "api_key" ? modelsOver(trial, providers) : undefined;
+    const models = method === "api_key" ? modelsOver(trial, providers, undefined, definedValues(process.env)) : undefined;
     const store = request.credentialStore ?? fastagentCredentialStore(request.authPath);
     await store.modify(provider.id, async () => undefined);
     const signal = interaction.signal ?? new AbortController().signal;
@@ -235,7 +236,7 @@ export const PI_DEFAULT_MODELS = {
     "amazon-bedrock": "us.anthropic.claude-opus-4-6-v1",
     "ant-ling": "Ring-2.6-1T",
     anthropic: "claude-opus-4-8",
-    openai: "gpt-5.5",
+    openai: "gpt-6.1-sol",
     azure: "gpt-5.4",
     "openai-codex": "gpt-6.1-sol",
     radius: "balanced",

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

@@ -11,8 +11,13 @@ 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, 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
+ * What to say when `spec` names no model: the models of its provider that read most like it, or the providers there are
+ * when the provider is the unknown part, and the command that lists them.
+ */
+export declare function modelHint(specs: readonly string[], spec: string): string;
+/**
+ * The built-ins plus `providers` (a same id replaces a built-in), over any credential store, in `environment`: the
+ * values a provider's auth reads its keys from, and each request is given. 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, environment?: Readonly<Record<string, string>>): Models;

package/dist/harnesses/models/models.js

@@ -20,6 +20,30 @@ export function listModels(models) {
     }
     return specs.sort();
 }
+const tokensOf = (text) => text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+/**
+ * What to say when `spec` names no model: the models of its provider that read most like it, or the providers there are
+ * when the provider is the unknown part, and the command that lists them.
+ */
+export function modelHint(specs, spec) {
+    const provider = providerOf(spec);
+    const own = specs.filter((candidate) => candidate.startsWith(`${provider}/`));
+    if (own.length === 0) {
+        const providers = [...new Set(specs.map(providerOf))];
+        return `there is no provider "${provider}"; the providers are ${providers.join(", ")} (\`fastagent models\` lists their models)`;
+    }
+    const wanted = new Set(tokensOf(spec.slice(provider.length + 1)));
+    const overlap = (candidate) => tokensOf(candidate.slice(provider.length + 1)).filter((t) => wanted.has(t)).length;
+    const closest = own
+        .map((candidate) => ({ candidate, score: overlap(candidate) }))
+        .sort((a, b) => b.score - a.score || a.candidate.localeCompare(b.candidate))
+        .slice(0, 5)
+        .map(({ candidate }) => candidate);
+    return `${provider}'s models include ${closest.join(", ")} (\`fastagent models ${provider}\` lists all ${own.length})`;
+}
 /**
  * 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
@@ -61,15 +85,15 @@ function inEnvironment(provider, environment) {
     };
 }
 /**
- * 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
+ * The built-ins plus `providers` (a same id replaces a built-in), over any credential store, in `environment`: the
+ * values a provider's auth reads its keys from, and each request is given. 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,
-        // 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]),
+        // The values given, and none of this process's: an instance's keys are its own, whoever else runs here.
+        authContext: authContextIn((name) => environment[name]),
         ...(catalogs ? { modelsStore: catalogs.fetched } : {}),
     });
     for (const builtIn of builtinProviders()) {

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

@@ -23,7 +23,6 @@ import { admitSettings } from "./defaults.js";
 import { USER_ENTRY, imageAt, isPublished, parseImageRef } from "./entries.js";
 import { sessionEvents } from "./events.js";
 import { storageIds } from "./ids.js";
-import { giveUpOnParked } from "./parked.js";
 import { isInput, queuedInputs, requestIdFor, usageOfState } from "./messages.js";
 import { durableReads } from "./reads.js";
 import { releaseWaitingQueues } from "./release.js";
@@ -38,13 +37,12 @@ export async function openDurableAgent(options) {
         registry: options.registry,
         ...(options.settings === undefined ? {} : { settings: options.settings }),
         ...(options.env === undefined ? {} : { env: options.env }),
-        onReport: (error) => log.warn(`[fastagent] pi-durable reported: ${String(error)}`),
+        onReport: (report) => log.warn(`[fastagent] pi-durable reported ${report.kind}: ${String(report.error)}`),
     }, context);
     const lifetime = Scope.makeUnsafe();
     try {
         const ids = await storageIds(harness, context);
         const sessions = await Effect.runPromise(Scope.provide(trackSessions(harness, options.storage, context), lifetime));
-        await giveUpOnParked(harness, context);
         // Before `resume()`, which runs an earlier process's work. An abort enables the scheduler too, but commits first, so
         // the aborted work does not run (measured).
         const unsettled = (await harness.inspect(context)).submissions.filter(isInput);
@@ -215,58 +213,81 @@ function durableAgent(harness, ids, sessions, lifetime, options) {
         sessionId: ids.encode(conversation.id),
         ...(messageId === undefined ? {} : { messageId: ids.encode(messageId) }),
     });
-    /** Admission: a key's lookup, the limits, the settings and the submission, one at a time per process. */
+    /**
+     * Admission, one at a time per process: one commit that looks the key up, then checks the process's limit and the
+     * queue, takes the defaults and submits, so it stores all of that or none of it.
+     */
     const admit = (request) => Semaphore.withPermits(admission, 1)(Effect.gen(function* () {
         const requestId = requestIdFor(request.idempotencyKey);
         // Before anything is written: reading or expanding a command reads the definition's files, and may throw.
         const { content, sent } = expandCommand(request.content, commands());
         const conversation = yield* conversationOf(request.sessionId);
-        if (request.idempotencyKey !== undefined) {
-            const seen = yield* reads.submissionByKey(conversation, requestId);
-            if (seen !== undefined)
-                return { message: yield* reads.message(seen), replayed: true };
-        }
-        if ((yield* inFlight) >= inFlightLimit) {
-            return yield* agentError("busy", `This agent already holds ${inFlightLimit} messages`, {
-                reason: "capacity",
-            });
-        }
-        if (request.whenBusy !== "reject") {
-            const inbox = yield* reads.inbox(conversation);
-            if (queuedInputs(inbox).length >= LIMITS.queuedPerSession) {
-                return yield* agentError("busy", `The session already has ${LIMITS.queuedPerSession} queued messages`, {
-                    reason: "queue_full",
-                });
-            }
-        }
-        const refused = yield* port(() => conversation.commit((tx) => admitSettings(tx, conversation.id, defaults, has), context));
-        if (refused !== undefined)
-            return yield* unanswerable(refused);
+        // Read before the commit, which cannot read the harness, and applied after the key: a key the session has
+        // seen answers with its message whatever the process holds (SPEC.md §5.2).
+        const atCapacity = (yield* inFlight) >= inFlightLimit;
         const data = { requestId, ...(sent === undefined ? {} : { sent }) };
-        let messageId;
-        return yield* Effect.gen(function* () {
-            const submission = yield* port(() => conversation.submit({
+        let submitting = false;
+        const admitted = yield* port(() => conversation.commit(async (tx) => {
+            if (request.idempotencyKey !== undefined) {
+                const seen = await tx.submissionByRequest(conversation.id, requestId);
+                if (isInput(seen))
+                    return { kind: "seen", seen };
+            }
+            if (atCapacity)
+                return { kind: "capacity" };
+            if (request.whenBusy !== "reject") {
+                const inbox = await tx.doc(InboxDoc, conversation.id);
+                if (queuedInputs(inbox).length >= LIMITS.queuedPerSession)
+                    return { kind: "full" };
+            }
+            const refused = await admitSettings(tx, conversation.id, defaults, has);
+            if (refused !== undefined)
+                return { kind: "refused", refused };
+            submitting = true;
+            const id = await conversation.submit(tx, {
                 type: "input",
                 content,
                 requestId,
                 whenBusy: request.whenBusy === "steer" ? "steer" : request.whenBusy === "reject" ? "reject" : "followUp",
                 entry: { kind: USER_ENTRY, data },
-            }, context));
-            messageId = submission.id;
+            });
+            return { kind: "admitted", id };
+        }, context)).pipe(
+        // Once the submission is in the commit, only pi-durable's explicit refusal proves nothing was recorded.
+        Effect.catchCause((cause) => {
+            const error = portError(cause);
+            if (error instanceof ConversationBusy) {
+                return Effect.fail(agentError("busy", "The session is answering another message", { reason: "running" }));
+            }
+            return submitting ? Effect.fail(unconfirmed(conversation, undefined, error)) : Effect.failCause(cause);
+        }));
+        if (admitted.kind === "seen")
+            return { message: yield* reads.message(admitted.seen), replayed: true };
+        if (admitted.kind === "capacity") {
+            return yield* agentError("busy", `This agent already holds ${inFlightLimit} messages`, {
+                reason: "capacity",
+            });
+        }
+        if (admitted.kind === "full") {
+            return yield* agentError("busy", `The session already has ${LIMITS.queuedPerSession} queued messages`, {
+                reason: "queue_full",
+            });
+        }
+        if (admitted.kind === "refused")
+            return yield* unanswerable(admitted.refused);
+        const messageId = admitted.id;
+        return yield* Effect.gen(function* () {
+            const submission = yield* port(() => harness.submission(messageId, context));
+            if (submission === undefined) {
+                throw new Error(`submission ${messageId} is not in the storage it was admitted to`);
+            }
             // Counted once it is read back, whether or not that read succeeds: the wait must not be what reads the
             // storage first, or a failing read would fail it instead of answering this call.
             const record = yield* port(() => submission.status(context)).pipe(Effect.ensuring(Effect.sync(() => countUntilSettled(submission))));
             if (!isInput(record))
                 throw new Error(`submission ${record.id} was admitted as a write`);
             return { message: yield* reads.message(record), replayed: false };
-        }).pipe(
-        // Once submission starts, only pi-durable's explicit refusal proves nothing was recorded.
-        Effect.catchCause((cause) => {
-            const error = portError(cause);
-            return Effect.fail(messageId === undefined && error instanceof ConversationBusy
-                ? agentError("busy", "The session is answering another message", { reason: "running" })
-                : unconfirmed(conversation, messageId, error));
-        }));
+        }).pipe(Effect.catchCause((cause) => Effect.fail(unconfirmed(conversation, messageId, portError(cause)))));
     }));
     /** The message as it is now. */
     const current = (message) => reads.submission(message.id).pipe(Effect.flatMap((record) => {

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

@@ -0,0 +1,12 @@
+import { type AgentDefinition } from "./definition.ts";
+export interface BuildOptions {
+    /** Type-check the project (default). Without it, `tsc --noCheck` only emits. */
+    check?: boolean;
+}
+export interface BuildResult {
+    dist: string;
+    definition: AgentDefinition;
+    /** What the build would publish that the author should look at: a literal credential in `mcpServers`, say. */
+    warnings: string[];
+}
+export declare function buildProject(directory: string, options?: BuildOptions): Promise<BuildResult>;