@fastagent-sh/fastagent 0.23.0 → 0.24.0

package/dist/engines/pi/open.d.ts

@@ -1,7 +1,7 @@
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
-import type { AgentCommand, SessionControl } from "../../session.ts";
-import { type PiAssembly } from "./create.ts";
+import type { AgentCommand, ModelDescriptor, SessionControl } from "../../session.ts";
+import { type IndirectTool, type PiAssembly } from "./create.ts";
 import type { SessionObserver } from "./turn-kit.ts";
 import { type LoadedDefinition } from "./definition.ts";
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
@@ -72,10 +72,10 @@ export interface AgentAssembly {
     stateRoot: string;
     /** The credential store and model registry every turn and every report reads ({@link agentModels}). */
     models: AgentModels;
-    /** The full mounted tool surface (all coding tools + config.tools + discovered tools/, search_tools applied). */
+    /** The full mounted tool surface (all coding tools + config.tools + discovered tools/). */
     tools: MountedTool[];
     toolNames: string[];
-    deferredToolNames: string[];
+    indirectTools: IndirectTool[];
     toolCollisions: ToolCollision[];
     /** Env vars the mounted tools declared, by tool name — already asserted present by this function. */
     toolSecrets: Map<string, DeclaredSecret[]>;
@@ -96,15 +96,16 @@ export declare function assembleFront(front: AgentAssembly, extra?: {
     definition: LoadedDefinition;
 }>;
 /**
- * The model specs `createPiAgentFromDir(dir, { authPath })` could run now: the agent's registry (pi's built-ins plus
- * its `models.json`) filtered to the providers whose credentials are configured, sorted. The directory needs no model
- * set, and the same placement and credential layers as the opener apply, so a listed spec authenticates there.
- * Configuration is checked, not validity: no OAuth token is refreshed and no provider is called.
+ * The models `createPiAgentFromDir(dir, { authPath })` could run now, as a picker shows them (spec, name, the thinking
+ * levels a session on it accepts, context window), sorted by spec: the agent's registry (pi's built-ins, its
+ * `models.json`, and what its `extensions/` declare) filtered to the providers whose credentials are configured. The
+ * directory needs no model set, and the same placement and credential layers as the opener apply, so a listed spec
+ * authenticates there. Configuration is checked, not validity: no OAuth token is refreshed and no provider is called.
  *
  * `warn` reaches the credential store. An unreadable or corrupt credentials file otherwise reads as "nothing
  * configured", so a client that must not show that as an empty list passes a sink that throws.
  */
-export declare function availableModelsFromDir(dir: string, options?: FastagentAuthOptions & CredentialSourceOptions): Promise<string[]>;
+export declare function availableModelsFromDir(dir: string, options?: FastagentAuthOptions & CredentialSourceOptions): Promise<ModelDescriptor[]>;
 /**
  * Refresh the agent's model catalog (`<agent dir>/models-store.json`) with the credentials
  * `createPiAgentFromDir(dir, { authPath })` would use, so a model released after the installed pi appears in
@@ -122,6 +123,19 @@ export declare function refreshModelCatalog(dir: string, options?: FastagentAuth
 export declare function refreshModelCatalogOver(dir: string, options: FastagentAuthOptions & CredentialSourceOptions & {
     signal?: AbortSignal;
 }, catalogBaseUrl?: string): Promise<void>;
+/**
+ * Refresh the MACHINE's model catalog (`~/.fastagent/models-store.json`), which every agent here reads under its own,
+ * so one refresh serves them all and no file is written into any agent. Credentials resolve as for
+ * {@link refreshModelCatalog} without a directory: `credentialStore`, else `authPath`, else the global credentials file;
+ * the environment applies either way. Rejects for the same reasons. The file never ships with a deploy.
+ */
+export declare function refreshMachineModelCatalog(options?: FastagentAuthOptions & CredentialSourceOptions & {
+    signal?: AbortSignal;
+}): Promise<void>;
+/** {@link refreshMachineModelCatalog} against another catalog server. Not public: a test seam. */
+export declare function refreshMachineModelCatalogOver(options: FastagentAuthOptions & CredentialSourceOptions & {
+    signal?: AbortSignal;
+}, catalogBaseUrl?: string): Promise<void>;
 /**
  * "Point at a directory → agent": resolve the placement (`dir` may be either end — the workspace or the agent dir
  * itself), load the config, resolve model and tools, then L2.
@@ -153,7 +167,7 @@ export declare function createPiAgentFromDir(dir: string, options?: CreatePiAgen
     http?: HttpSurface;
     /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. */
     toolNames: string[];
-    /** Tools registered but not initially active (deferred) — activated via search_tools. */
-    deferredToolNames: string[];
+    /** Mounted authored tools the model is not given up front, with how each is reached. */
+    indirectTools: IndirectTool[];
     toolCollisions: ToolCollision[];
 }>;

package/dist/engines/pi/open.js

@@ -6,6 +6,7 @@ import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { loadConfig, resolveModelSpec } from "./config.js";
 import { AGENT_MODEL_CATALOG_FILE, resolveSessionsDir, resolveStateRoot, resolvePlacement } from "../../paths.js";
+import { describeModels } from "./session-settings.js";
 import { agentOf, assemblePiFromDefinition, resolveAgentTools } from "./create.js";
 import { createPiSessionControl } from "./session-control.js";
 import { withWakeTool } from "./wake-tool.js";
@@ -14,7 +15,7 @@ import { loadAgentSkills } from "./definition.js";
 import { servedExtensionCommands } from "./agent-session-factory.js";
 import { reportFindingsIfChanged } from "./report.js";
 import { readMachine, withMachine } from "./machine.js";
-import { createPiModelRuntime, refreshCatalog } from "./models.js";
+import { createPiModelRuntime, globalCatalogPath, machineModelRuntime, refreshCatalog } from "./models.js";
 import { agentModels } from "./agent-models.js";
 import { piSessionRecordStore } from "./session-store.js";
 import { gateSecrets } from "../../secrets-gate.js";
@@ -36,9 +37,11 @@ export async function agentCommands(agentDir, workspace, served) {
     reportFindingsIfChanged(own.dir, own);
     const machine = await readMachine(workspace);
     const { extensionPaths } = served;
-    const extensionCommands = extensionPaths.length === 0
-        ? []
-        : await servedExtensionCommands({ cwd: workspace, modelRuntime: await served.modelRuntime(), extensionPaths });
+    const extensionCommands = await servedExtensionCommands({
+        cwd: workspace,
+        modelRuntime: await served.modelRuntime(),
+        extensionPaths,
+    });
     // pi dispatches an extension command before it expands a template, so a template it shadows never runs.
     const shadowed = new Set(extensionCommands.map((command) => command.invocationName));
     return [
@@ -69,7 +72,7 @@ export async function resolveAgentAssembly(dir, options = {}) {
     if (!modelSpec) {
         throw new Error(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai-codex/gpt-5.5")`);
     }
-    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures, toolSecrets } = await resolveAgentTools(config, agentDir, workspace);
+    const { tools, toolNames, indirectTools, toolCollisions, toolFailures, toolSecrets } = await resolveAgentTools(config, agentDir, workspace);
     // THE serving-path gate for tool declarations, in the order that costs the fewest round trips. A file that could
     // not be imported declares nothing, so its `secrets:` are missing from `toolSecrets` — gating secrets first would
     // report an incomplete set, and fixing the file could then reveal more missing values. Refuse the broken file
@@ -79,7 +82,7 @@ export async function resolveAgentAssembly(dir, options = {}) {
     // definition and must survive both faults; every path through this function is about to run ALL of the tools, so
     // no `owner`.
     //
-    // DEFERRED tools gate too, deliberately: `search_tools` can activate one mid-turn, so "registered"
+    // DEFERRED tools gate too, deliberately: native discovery can activate one mid-turn, so "registered"
     // means "may run in this process" — letting it start would put the empty-credential failure back
     // inside a turn. An author who does not want that opts out per tool by not declaring.
     gateSecrets({ declared: toolSecrets, failures: [] });
@@ -94,10 +97,10 @@ export async function resolveAgentAssembly(dir, options = {}) {
         workspace,
         stateRoot,
         // Project-level by default (under `<agentDir>/.secrets`), with the global file behind it per provider.
-        models: agentModels(agentDir, options),
+        models: agentModels(agentDir, options, { cwd: workspace }),
         tools,
         toolNames,
-        deferredToolNames,
+        indirectTools,
         toolCollisions,
         toolSecrets,
     };
@@ -118,18 +121,19 @@ export function assembleFront(front, extra = {}) {
     });
 }
 /**
- * The model specs `createPiAgentFromDir(dir, { authPath })` could run now: the agent's registry (pi's built-ins plus
- * its `models.json`) filtered to the providers whose credentials are configured, sorted. The directory needs no model
- * set, and the same placement and credential layers as the opener apply, so a listed spec authenticates there.
- * Configuration is checked, not validity: no OAuth token is refreshed and no provider is called.
+ * The models `createPiAgentFromDir(dir, { authPath })` could run now, as a picker shows them (spec, name, the thinking
+ * levels a session on it accepts, context window), sorted by spec: the agent's registry (pi's built-ins, its
+ * `models.json`, and what its `extensions/` declare) filtered to the providers whose credentials are configured. The
+ * directory needs no model set, and the same placement and credential layers as the opener apply, so a listed spec
+ * authenticates there. Configuration is checked, not validity: no OAuth token is refreshed and no provider is called.
  *
  * `warn` reaches the credential store. An unreadable or corrupt credentials file otherwise reads as "nothing
  * configured", so a client that must not show that as an empty list passes a sink that throws.
  */
 export async function availableModelsFromDir(dir, options = {}) {
-    const { agentDir } = resolvePlacement(dir);
-    const models = await agentModels(agentDir, options).runtime();
-    return (await models.getAvailable()).map((model) => `${model.provider}/${model.id}`).sort();
+    const { agentDir, workspace } = resolvePlacement(dir);
+    const models = await agentModels(agentDir, options, { cwd: workspace }).runtime();
+    return describeModels(await models.getAvailable());
 }
 /**
  * Refresh the agent's model catalog (`<agent dir>/models-store.json`) with the credentials
@@ -148,10 +152,28 @@ export function refreshModelCatalog(dir, options = {}) {
 export async function refreshModelCatalogOver(dir, options, catalogBaseUrl) {
     const { agentDir } = resolvePlacement(dir);
     const { credentials } = agentModels(agentDir, options);
-    await refreshCatalog((catalogFile) => createPiModelRuntime({
+    await refreshCatalog(join(agentDir, AGENT_MODEL_CATALOG_FILE), (catalogFile) => createPiModelRuntime({
         agentDir,
         credentials,
-        ...(catalogFile ? { catalogFile: join(agentDir, AGENT_MODEL_CATALOG_FILE) } : {}),
+        catalogFile,
+        ...(catalogBaseUrl ? { catalogBaseUrl } : {}),
+    }), options.signal ? { signal: options.signal } : {});
+}
+/**
+ * Refresh the MACHINE's model catalog (`~/.fastagent/models-store.json`), which every agent here reads under its own,
+ * so one refresh serves them all and no file is written into any agent. Credentials resolve as for
+ * {@link refreshModelCatalog} without a directory: `credentialStore`, else `authPath`, else the global credentials file;
+ * the environment applies either way. Rejects for the same reasons. The file never ships with a deploy.
+ */
+export function refreshMachineModelCatalog(options = {}) {
+    return refreshMachineModelCatalogOver(options);
+}
+/** {@link refreshMachineModelCatalog} against another catalog server. Not public: a test seam. */
+export async function refreshMachineModelCatalogOver(options, catalogBaseUrl) {
+    const { credentials } = agentModels(undefined, options);
+    await refreshCatalog(globalCatalogPath(), (catalogFile) => machineModelRuntime({
+        credentials,
+        catalogFile,
         ...(catalogBaseUrl ? { catalogBaseUrl } : {}),
     }), options.signal ? { signal: options.signal } : {});
 }
@@ -161,7 +183,7 @@ export async function refreshModelCatalogOver(dir, options, catalogBaseUrl) {
  */
 export async function createPiAgentFromDir(dir, options = {}) {
     const front = await resolveAgentAssembly(dir, options);
-    const { config, configPath, modelSpec, agentDir, workspace, stateRoot, models, tools, toolNames, deferredToolNames, toolCollisions, } = front;
+    const { config, configPath, modelSpec, agentDir, workspace, stateRoot, models, tools, toolNames, indirectTools, toolCollisions, } = front;
     // Every serve mounts the built-in `wake` tool: the agent's own follow-up work is a default capability, and a serve
     // is where the poller that honors it runs. A one-shot `invoke` has no poller, so nothing there would fire it.
     const mountedTools = withWakeTool(tools, stateRoot, !!options.serving);
@@ -201,7 +223,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
             // the prompt would not expand — a second reading of "which skills exist" is how those two come to disagree.
             commands: () => agentCommands(agentDir, workspace, {
                 extensionPaths: assembly.extensionPaths,
-                modelRuntime: async () => (await assembly.engine()).modelRuntime,
+                modelRuntime: assembly.createModelRuntime,
             }),
             // The caller tap's boundary-event half: state_changed/compaction_* originate in the hub and never cross the
             // data plane's observer seam.
@@ -233,7 +255,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
         sessionsDir,
         models,
         toolNames,
-        deferredToolNames,
+        indirectTools,
         toolCollisions,
     };
 }

package/dist/engines/pi/report.d.ts

@@ -5,6 +5,7 @@
 import type { SkillDiagnostic } from "@earendil-works/pi-agent-core";
 import type { SkillCollision } from "./definition.ts";
 import type { ToolCollision } from "./tool.ts";
+import type { IndirectTool } from "./create.ts";
 type Findings = {
     collisions: SkillCollision[];
     diagnostics: SkillDiagnostic[];
@@ -12,5 +13,7 @@ type Findings = {
 /** THE door for definition findings: warns only when this dir's set CHANGED since the last report. */
 export declare function reportFindingsIfChanged(dir: string, def: Findings): void;
 export declare function reportDefinitionWarnings(collisions: SkillCollision[], diagnostics: SkillDiagnostic[]): void;
+/** The report line for the mounted tools the model is not given up front: each name with its way in. */
+export declare function describeIndirectTools(tools: readonly IndirectTool[]): string;
 export declare function reportToolCollisions(collisions: ToolCollision[]): void;
 export {};

package/dist/engines/pi/report.js

@@ -23,6 +23,17 @@ export function reportDefinitionWarnings(collisions, diagnostics) {
         log.warn(`[fastagent] ${d.code}: ${d.message} (${d.path})`);
     }
 }
+const REACH = {
+    tool_search: "loaded via tool_search",
+    codemode: "codemode scripts only",
+    hidden: "hidden",
+    inactive: "inactive until an authored loader activates it",
+    unreachable: "unreachable: pi's settings disable the built-in extension it needs",
+};
+/** The report line for the mounted tools the model is not given up front: each name with its way in. */
+export function describeIndirectTools(tools) {
+    return tools.map((tool) => `${tool.name} (${REACH[tool.reach]})`).join(", ");
+}
 export function reportToolCollisions(collisions) {
     for (const c of collisions) {
         log.warn(`[fastagent] tool "${c.name}" (${c.source}) dropped — a default/config tool already uses that name`);

package/dist/engines/pi/session-builder.js

@@ -4,9 +4,8 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { SessionManager, SettingsManager, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, } from "@earendil-works/pi-coding-agent";
-import { bindPiSession, definitionResourceLoaderOptions, reportExtensionErrors } from "./agent-session-factory.js";
-import { readMachine } from "./machine.js";
+import { SessionManager, SettingsManager, createAgentSessionRuntime, getAgentDir, } from "@earendil-works/pi-coding-agent";
+import { bindPiSession, definitionServices } from "./agent-session-factory.js";
 import { resolveModel } from "./config.js";
 import { canonicalPath } from "./definition.js";
 import { reportToolCollisions } from "./report.js";
@@ -42,29 +41,14 @@ export async function buildAgentSessionRuntime(dir, options = {}, sessionManager
     const createRuntime = async ({ cwd, sessionManager, sessionStartEvent }) => {
         const { modelSpec, assembly, definition } = await assemblyFor(cwd);
         // Per session, NOT memoized with the assembly.
-        const [modelRuntime, machine] = await Promise.all([assembly.modelRuntime(), readMachine(cwd)]);
-        const loaded = await createAgentSessionServices({
-            cwd,
-            // fastagent's models + auth hub replaces pi's default (~/.pi-backed) one — the auth unification point.
-            modelRuntime,
-            // PACKAGELESS, for the loader: fastagent never installs a pi package (machine.ts). Handed pi's own settings, the
-            // loader resolves `packages` itself — installing a missing one, and failing chat's start when that fails.
-            settingsManager: machine.settingsManager(),
-            resourceLoaderOptions: definitionResourceLoaderOptions({
-                systemPrompt: () => definition.systemPrompt,
-                skills: () => definition.skills,
-                machine,
-                extensionPaths: assembly.extensionPaths,
-            }),
-        });
+        const modelRuntime = await assembly.createModelRuntime();
+        const loaded = await definitionServices({ cwd, modelRuntime, definition, extensionPaths: assembly.extensionPaths });
         // ...while the SESSION keeps pi's own file-backed settings, so `/settings` in the TUI still saves. pi persists by
         // re-reading the file under its lock and writing only the fields that changed, so `packages` there is untouched.
         const services = { ...loaded, settingsManager: SettingsManager.create(cwd, loaded.agentDir) };
-        reportExtensionErrors(services);
         // AFTER the services, because an extension may be what defines the model.
         const model = resolveModel(modelRuntime, modelSpec);
-        // The same bind serving performs, minus the activation record: pi's chat session has nowhere to put one, which is
-        // the documented divergence.
+        // Serving and chat restore the same native transcript declarations.
         const result = await bindPiSession({
             services,
             sessionManager,
@@ -74,9 +58,9 @@ export async function buildAgentSessionRuntime(dir, options = {}, sessionManager
             // is the definition's (`thinkingLevel` in fastagent.config.ts), like serving's.
             thinkingLevel: assembly.thinkingLevel,
             tools: assembly.tools,
+            excludedToolNames: assembly.excludedToolNames,
             // A tool must see one spelling of the workspace, including when opened through a symlink.
             cwd: rootCwd,
-            recordActivations: false,
         });
         return { ...result, services, diagnostics: services.diagnostics };
     };

package/dist/engines/pi/session-control.d.ts

@@ -15,7 +15,7 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type Models } from "@earendil-works/pi-ai";
 import { type AgentCommand, type SessionControl, type SessionEvent } from "../../session.ts";
-import type { SessionObserver, Lease } from "./turn-kit.ts";
+import { type SessionObserver, type Lease } from "./turn-kit.ts";
 import type { AnyModel } from "./models.ts";
 import type { PiAgentSessionFactory } from "./invoke-session.ts";
 import type { PiSessionRecordStore } from "./session-store.ts";
@@ -25,9 +25,9 @@ export declare const SUBSCRIBER_BUFFER_CAP = 10000;
 export declare const SUBSCRIBER_BUFFER_BYTES: number;
 /** What the plane's writes (`update` / `compact` / `fork` / `delete`) need — the SAME instances the
  *  agent assembly uses: the lease (a write must not race a run), the model registry (validation +
- *  allowedModels), and the session factory (compaction is a model call). Writes go through the
- *  record the hub's reader opened — after an existence check, so the control plane never creates
- *  a session (that is the data plane's monopoly). */
+ *  allowedModels), and the session factory (compaction is a model call). Two writes create a record:
+ *  fork's `into`, and `update()` on an id that has none (through the store's `openOrCreate`, like an
+ *  invoke). Every other write needs a record that exists. */
 export interface PiBoundaryWiring {
     lease: Lease;
     models: Models;

package/dist/engines/pi/session-control.js

@@ -10,12 +10,12 @@ import { calculateContextTokens, estimateTokens, getLastAssistantUsage, } from "
 import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 import { SESSION_BUSY_CODE } from "../../agent.js";
 import { BOUNDARY_COMMAND_FAILED_CODE, INVALID_COMMAND_CODE, isAddressableSession, NO_ACTIVE_RUN_CODE, NOTHING_TO_COMPACT_CODE, NO_SUCH_SESSION_CODE, PARTIAL_UPDATE_CODE, UPDATE_FIELDS, RUN_COMMAND_FAILED_CODE, UNSUPPORTED_CAPABILITY_CODE, } from "../../session.js";
-import { listModels } from "./config.js";
-import { forkProvenance, isNavigable, publishedLeaf } from "./session-markers.js";
+import { forkProvenance, isConversationMessage, isNavigable, publishedLeaf } from "./session-markers.js";
 import { entryImages, imageAt } from "./entry-images.js";
+import { answerOutcome } from "./turn-kit.js";
 import { startCompaction } from "./agent-session-factory.js";
 import { toRetryScheduledEvent } from "./retry-event.js";
-import { THINKING_LEVELS, activePath, resolveSessionSettings } from "./session-settings.js";
+import { THINKING_LEVELS, activePath, describeModels, resolveSessionSettings } from "./session-settings.js";
 import { log } from "../../log.js";
 // ── Usage (read from the record) ─────────────────────────────────────────────
 /**
@@ -92,6 +92,9 @@ function toSessionEntry(entry, parentId) {
             const data = { text: contentText(m.content, "") };
             if (toolCalls.length > 0)
                 data.toolCalls = toolCalls;
+            const outcome = answerOutcome(m);
+            if (outcome)
+                data.outcome = outcome;
             return { ...base, kind: "assistant", data };
         }
         if (m.role === "toolResult") {
@@ -267,10 +270,10 @@ export function createPiSessionControl(options) {
                 // The CONTRACT's list, not a copy of it: a field added to SessionUpdate is advertised
                 // without anyone remembering to, and one removed cannot linger here.
                 updatable: b ? [...UPDATE_FIELDS] : [],
-                // The registry is a deployment fact (any session may be pointed at any of it). Thinking
-                // LEVELS are a property of the model a session is running, so they ride
-                // `state().availableThinkingLevels` — a list here could only answer for one model.
-                ...(b ? { allowedModels: listModels(b.models) } : {}),
+                // The registry is a deployment fact (any session may be pointed at any of it). Each model carries the levels
+                // a session on it accepts, so a picker can offer them before the session runs on that model;
+                // `state().availableThinkingLevels` answers for the model the session is on.
+                ...(b ? { allowedModels: describeModels(b.models.getModels()) } : {}),
                 toolProgress: true, // tool_progress IS delivered (replace-semantics snapshots)
                 usage: true, // state().usage, and state_changed{usage} after each run and compaction
             };
@@ -289,12 +292,27 @@ export function createPiSessionControl(options) {
             const b = boundary;
             let settings;
             let usage;
-            if (opened) {
+            if (!opened) {
+                // An id with no record is an empty conversation at the defaults: its first turn would run on these.
+                if (b)
+                    settings = resolveSessionSettings([], b.models, b.defaults);
+            }
+            else {
                 try {
                     const path = activePath(opened);
                     if (b)
                         settings = resolveSessionSettings(path, b.models, b.defaults);
-                    usage = sessionUsage(path, opened, settings?.model.contextWindow);
+                    const selected = settings?.model;
+                    const latest = selected?.api === "pi-virtual"
+                        ? opened
+                            .buildSessionContext()
+                            .messages.filter((message) => message.role === "assistant" &&
+                            message.stopReason !== "error" &&
+                            message.stopReason !== "aborted")
+                            .at(-1)
+                        : undefined;
+                    const physical = latest?.role === "assistant" ? b?.models.getModel(latest.provider, latest.model) : undefined;
+                    usage = sessionUsage(path, opened, (physical ?? selected)?.contextWindow);
                 }
                 catch (error) {
                     log.warn(`[fastagent] session ${session}: state unreadable (entry chain): ${String(error)}`);
@@ -457,6 +475,21 @@ export function createPiSessionControl(options) {
         ok: false,
         error: { code: NO_SUCH_SESSION_CODE, message: `session "${session}" does not exist`, retryable: false },
     });
+    /**
+     * The refusal for an id no client could then open: the empty string, `.` and `..` are not URL path segments
+     * (isAddressableSession), so minting one would put a row in list() that nothing can address — listed, unopenable by
+     * the client that just listed it. Both writes that create a record (fork's `into`, and an update to an id with no
+     * record) refuse it.
+     */
+    const unaddressable = (session) => invalid(`${JSON.stringify(session)} cannot be a session id — the control plane could not address it`);
+    const nothingToCompact = () => ({
+        ok: false,
+        error: {
+            code: NOTHING_TO_COMPACT_CODE,
+            message: "nothing to compact — the session has no compactable history yet; retry after more turns",
+            retryable: false,
+        },
+    });
     const invalid = (message) => ({
         ok: false,
         error: { code: INVALID_COMMAND_CODE, message, retryable: false },
@@ -518,12 +551,12 @@ export function createPiSessionControl(options) {
             };
         }
         const controls = run.controls;
-        yield* port(() => action.type === "steer"
-            ? controls.steer(action.prompt)
-            : action.type === "follow_up"
-                ? controls.followUp(action.prompt)
-                : controls.abort());
-        return { ok: true, runId: run.runId };
+        if (action.type === "abort") {
+            yield* port(() => controls.abort());
+            return { ok: true, runId: run.runId };
+        }
+        const disposition = yield* port(() => action.type === "steer" ? controls.steer(action.prompt) : controls.followUp(action.prompt));
+        return { ok: true, runId: run.runId, disposition };
     }).pipe(Effect.catchCause((cause) => Effect.succeed({
         ok: false,
         error: { code: RUN_COMMAND_FAILED_CODE, message: String(portError(cause)), retryable: false },
@@ -557,7 +590,7 @@ export function createPiSessionControl(options) {
             const slash = patch.model.indexOf("/");
             model = slash > 0 ? b.models.getModel(patch.model.slice(0, slash), patch.model.slice(slash + 1)) : undefined;
             if (!model) {
-                return invalid(`unknown model "${patch.model}" — capabilities().allowedModels lists the accepted specs`);
+                return invalid(`unknown model "${patch.model}" — capabilities().allowedModels lists the accepted models`);
             }
         }
         if (patch.thinkingLevel !== undefined && !THINKING_LEVELS.has(patch.thinkingLevel)) {
@@ -566,18 +599,18 @@ export function createPiSessionControl(options) {
         // A name is the client's own label; the only thing that cannot be one is nothing.
         if (patch.name !== undefined && patch.name.trim() === "")
             return invalid("a session name cannot be empty");
-        // Sessions are created by invoke or copied by fork, never minted by an update: an unknown id is
-        // rejected, not turned into a ghost record. (Read-only handle — the WRITE one is opened under
-        // the lease below, and this one is discarded.)
+        // An id with no record takes properties too: its first turn is the "next turn" they apply to, so the write
+        // creates its record (below, under the lease). (Read-only handle — the WRITE one is opened under the lease,
+        // and this one is discarded.)
         const existing = yield* port(() => sessions.openIfExists(session));
-        if (!existing)
-            return noSuchSession(session);
+        if (!existing && !isAddressableSession(session))
+            return unaddressable(session);
         if (patch.leafEntryId !== undefined) {
             // A target that cannot BE a leaf is a permanent payload error, not a session error — the same
             // disposition as an unknown model spec. Same predicate `entries()` publishes by, so
             // "everything published is a position" holds by construction rather than by two literals
             // agreeing.
-            const entry = existing.getEntry(patch.leafEntryId);
+            const entry = existing?.getEntry(patch.leafEntryId);
             if (!entry || !isNavigable(entry)) {
                 return invalid(entry
                     ? `entry "${patch.leafEntryId}" is not a position — entries() publishes every id you can move to, and this is not one of them`
@@ -593,7 +626,8 @@ export function createPiSessionControl(options) {
                 // Against the path this patch LANDS on: a leaf move is written first, and the branch it
                 // moves to can carry a model override of its own — validating on the path being left would
                 // reject a level the destination supports, and accept one it does not.
-                resolved = resolveSessionSettings(activePath(existing, patch.leafEntryId), b.models, b.defaults);
+                const path = existing ? activePath(existing, patch.leafEntryId) : [];
+                resolved = resolveSessionSettings(path, b.models, b.defaults);
             }
             catch (error) {
                 return failed(error);
@@ -611,6 +645,10 @@ export function createPiSessionControl(options) {
             yield* acquireSessionLease(b.lease, session);
             // portJoin, not port: the lease is held for the duration of this write, so an interrupted
             // fiber must not release it while the store is still writing (effect-port.ts, rule 1).
+            // A never-run session's record is created through the data plane's own path, under the same lease an
+            // invoke creating it takes; one that invoke created meanwhile is simply opened.
+            if (!existing)
+                yield* portJoin(() => sessions.openOrCreate(session));
             return yield* portJoin(() => sessions.applyProperties(session, {
                 ...(patch.name !== undefined ? { name: patch.name } : {}),
                 ...(model ? { model: { provider: model.provider, id: model.id } } : {}),
@@ -619,7 +657,7 @@ export function createPiSessionControl(options) {
             }));
         }));
         if (!applied)
-            return noSuchSession(session); // vanished in the window: same condition, same code
+            return noSuchSession(session); // deleted in the window between the read and the lease
         if (applied.landed.length > 0) {
             // ONE event for the patch, built from what the RECORD holds. The settings pair rides along
             // whenever anything but the name changed: model and thinking level are one setting, and a
@@ -688,6 +726,12 @@ export function createPiSessionControl(options) {
             const existing = yield* port(() => sessions.openIfExists(session));
             if (!existing)
                 return noSuchSession(session);
+            // A record with no conversation in it (the list's `messageCount: 0`, e.g. one `update()` created before a first
+            // turn) has nothing to compact on any branch. Said before binding, because binding is a write: pi records the
+            // model and thinking level on a session that has no messages, so asking pi would add two entries and then
+            // refuse. Whether a record WITH messages has a cut point stays pi's decision (below).
+            if (!existing.getEntries().some(isConversationMessage))
+                return nothingToCompact();
             yield* acquireSessionLease(b.lease, session);
             const bound = yield* acquireSession(b.sessionFactory, session);
             yield* Effect.acquireRelease(Effect.try({
@@ -713,16 +757,8 @@ export function createPiSessionControl(options) {
                 Deferred.doneUnsafe(admitted, Effect.succeed({ ok: true }));
             });
             const admission = yield* portAbort("compact admission", () => compaction.admission, () => bound.abortCompaction());
-            if (admission === "nothing_to_compact") {
-                return {
-                    ok: false,
-                    error: {
-                        code: NOTHING_TO_COMPACT_CODE,
-                        message: "nothing to compact — the session has no compactable history yet; retry after more turns",
-                        retryable: false,
-                    },
-                };
-            }
+            if (admission === "nothing_to_compact")
+                return nothingToCompact();
             // Any other error pi raises before admission. A served session has no known trigger: it always binds a
             // model, and pi swallows a credential failure here and meets it at the model call (compaction_finished).
             // NOT retryable all the same: it is pi's decision on this session, not a transport or lease fault that
@@ -767,12 +803,8 @@ export function createPiSessionControl(options) {
         const b = boundary;
         if (!b)
             return unsupported("fork()");
-        // An id no client could then open: the empty string, `.` and `..` are not URL path segments
-        // (isAddressableSession), so minting one would put a row in list() that nothing can address —
-        // listed, unopenable by the client that just listed it.
-        if (!isAddressableSession(into)) {
-            return invalid(`${JSON.stringify(into)} cannot be a session id — the control plane could not address it`);
-        }
+        if (!isAddressableSession(into))
+            return unaddressable(into);
         const source = yield* port(() => sessions.openIfExists(from));
         if (!source)
             return noSuchSession(from);

package/dist/engines/pi/session-settings.d.ts

@@ -2,8 +2,17 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type Models } from "@earendil-works/pi-ai";
 import type { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { ModelDescriptor } from "../../session.ts";
 import type { AnyModel } from "./models.ts";
 export declare const THINKING_LEVELS: ReadonlySet<ThinkingLevel>;
+/**
+ * Models as a client's picker shows them, ordered by spec: the ONE description both listings give
+ * (`capabilities().allowedModels` and `availableModelsFromDir`). Its levels come from the function
+ * `resolveSessionSettings` reads, so a picker offers what `state()` will then report. A model that declares no name or
+ * context window (an extension's virtual model may not: pi reads the window as 0) leaves the field out rather than
+ * inventing one.
+ */
+export declare function describeModels(models: readonly AnyModel[]): ModelDescriptor[];
 /** The shape both override consumers walk — a session entry, structurally. */
 export interface OverrideEntryLike {
     type: string;

package/dist/engines/pi/session-settings.js

@@ -10,6 +10,23 @@ const ALL_THINKING_LEVELS = {
     max: true,
 };
 export const THINKING_LEVELS = new Set(Object.keys(ALL_THINKING_LEVELS));
+/**
+ * Models as a client's picker shows them, ordered by spec: the ONE description both listings give
+ * (`capabilities().allowedModels` and `availableModelsFromDir`). Its levels come from the function
+ * `resolveSessionSettings` reads, so a picker offers what `state()` will then report. A model that declares no name or
+ * context window (an extension's virtual model may not: pi reads the window as 0) leaves the field out rather than
+ * inventing one.
+ */
+export function describeModels(models) {
+    return models
+        .map((model) => ({
+        spec: `${model.provider}/${model.id}`,
+        ...(model.name ? { name: model.name } : {}),
+        thinkingLevels: getSupportedThinkingLevels(model),
+        ...(model.contextWindow > 0 ? { contextWindow: model.contextWindow } : {}),
+    }))
+        .sort((a, b) => (a.spec < b.spec ? -1 : a.spec > b.spec ? 1 : 0));
+}
 /**
  * The last entry of each kind wins, and a malformed one reads as ABSENT rather than falling through to an earlier
  * record.

package/dist/engines/pi/session-store.d.ts

@@ -6,8 +6,8 @@ import { type SessionInheritance } from "./session-inheritance.ts";
 export interface PiSessionRecordStore {
     openOrCreate(sessionId: string, inherit?: SessionInheritance): Promise<SessionManager>;
     /**
-     * OPEN-EXISTING sibling: an unknown session answers undefined, never creates one — sessions are the data plane's
-     * monopoly.
+     * OPEN-EXISTING sibling: an unknown session answers undefined, never creates one. The reads and every write that
+     * needs history go through it; creating is `openOrCreate`'s.
      */
     openIfExists(sessionId: string): Promise<SessionManager | undefined>;
     /** Write session properties, in the order pi's leaf pointer requires, and report what LANDED. */