@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/dev-supervisor.js

@@ -1,73 +1,42 @@
 /**
- * The `fastagent dev` process supervisor: re-spawn the CLI as a worker (`FASTAGENT_DEV_WORKER=1`) and
- * restart it on debounced edits to the agent's CODE inputs. Each restart is a fresh process
- * (always-latest, no stale module cache). The supervisor never exits on a bad edit — the worker fails
- * loudly and it waits for the next save.
- *
- * Watch scope is deliberately narrow: only inputs whose changes REQUIRE a new process — imported
- * code (tools/, channels/), fastagent.config.*, package.json, .env. The definition (AGENTS.md,
- * persona.md, skills/) is re-read per invoke by the directory rung, so its edits go live on the next turn with no
- * restart — and, critically, an agent that writes files into its own workspace (its normal work
- * product, including editing its own AGENTS.md) never has its in-flight turn killed by the watcher.
+ * The `fastagent dev` process supervisor: re-spawn the CLI as a worker (`FASTAGENT_DEV_WORKER=1`) and restart it on
+ * debounced edits to the agent's CODE inputs.
  */
 import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
-import { AGENT_CONFIG_NAMES, AGENT_MODELS_FILE, resolveStateRoot, isUnderDir, } from "./paths.js";
+import { AGENT_CONFIG_FILE, AGENT_MODELS_FILE, resolveStateRoot, isUnderDir } from "./paths.js";
 import { dotEnvPath } from "./env.js";
 import { log } from "./log.js";
-import { installProxyFetch } from "./proxy.js";
 import { openExternalUrl } from "./open-url.js";
 import { declaredChannels } from "./channels/discover.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** What the dev watcher restarts on (agent-dir-relative): the process-bound code inputs only. */
-/**
- * The agent-dir directories loaded ONCE per worker: a restart is their only re-read. One list, so
- * the watcher and the line printed at startup cannot disagree — a directory watched but unannounced
- * looks broken, and one announced but unwatched silently strands the author mid-edit.
- */
-const CODE_INPUT_DIRS = ["tools", "channels", "schedules", "extensions"];
-const WATCHED_HINT = `${CODE_INPUT_DIRS.map((dir) => `${dir}/`).join(", ")}, package.json, fastagent.config.*, models.json, .secrets/.env`;
-/**
- * chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. When
- * the agent sits INSIDE the workspace that means the surrounding tree never triggers a restart at all;
- * when the agent IS the workspace the root is that tree, and the allowlist below is what keeps the
- * author's own files out of scope. Ignoring a directory prunes the whole subtree, so everything outside it —
- * `.state/` machine state, node_modules, .git, and any file/dir the agent writes as work product —
- * costs no watchers and triggers no restarts. Helper code imported from OUTSIDE tools//channels/ is
- * out of scope by design (keep it under tools/, or restart manually) — the startup log names the set.
- */
+/** The agent-dir directories loaded ONCE per worker: a restart is their only re-read. */
+const CODE_INPUT_DIRS = ["tools", "channels", "routines", "extensions"];
+const WATCHED_HINT = `${CODE_INPUT_DIRS.map((dir) => `${dir}/`).join(", ")}, package.json, fastagent.config.ts, models.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: FASTAGENT_SECRETS_DIR
-    // can put it in an in-agent directory called anything, and a name-based rule would prune the very
-    // file the worker loads (a credential edit would then silently never restart it).
+    // The `.env` is allow-listed by its RESOLVED path, not by the `.secrets` name.
     const envRel = relative(root, envFile).split(sep);
     return (path) => {
         if (path === root)
             return false; // the root itself must not be pruned
         const rel = relative(root, path);
-        // Code inputs at the agent dir root: config, package.json, and the dirs loaded once per worker
-        // (a restart is their only re-read). Everything else (skills/, persona.md, AGENTS.md) is
-        // live-read — pruned, no restart.
-        // The config NAMES come from paths.ts, not a regex spelled here: adding a name there must not
-        // silently stop `dev` restarting on edits to it.
-        if (AGENT_CONFIG_NAMES.includes(rel))
+        // Code inputs at the agent dir root: config, package.json, and the dirs loaded once per worker (a restart is
+        // their only re-read).
+        if (rel === AGENT_CONFIG_FILE)
             return false;
         if (rel === "package.json")
             return false;
-        // models.json is read ONCE per worker (the model hub is built during assembly), so an edit needs a
-        // restart like any other code input. It is also the one input whose breakage KILLS the worker — a
-        // malformed file fails assembly — so leaving it unwatched would strand the author: the fix that
-        // repairs it would not be the edit that restarts.
+        // models.json is read ONCE per worker (the model hub is built during assembly), so an edit needs a restart like
+        // any other code input.
         if (rel === AGENT_MODELS_FILE)
             return false;
         const segments = rel.split(sep);
         if (CODE_INPUT_DIRS.includes(segments[0]))
             return false;
-        // The `.env` restarts too (credentials are process-bound). Keep it AND its ancestor directories
-        // un-pruned so chokidar can descend to it; every sibling inside them (auth.json, .env.example)
-        // prunes normally. An out-of-agent `.env` yields a `..`-prefixed envRel that matches nothing here
-        // — the supervisor warns about that case instead of pretending to watch it.
+        // The `.env` restarts too (credentials are process-bound).
         if (segments.length <= envRel.length && segments.every((seg, i) => seg === envRel[i]))
             return false;
         return true;
@@ -75,22 +44,14 @@ export function devWatchIgnored(root, envFile) {
 }
 /** Spawn the dev worker and restart it on agent-dir edits; supervise its lifecycle until the process exits. */
 export async function runDevSupervisor(placement, options = {}) {
-    // The placement arrives RESOLVED from the command (which already routed its refusal through
-    // failStartup): re-resolving here would duplicate the rule and surface the same user-fixable
-    // refusal as a raw stack. The watch root is the AGENT DIR — every restart-relevant code input lives
-    // under it, so the surrounding workspace costs no watchers at all. Placement is assumed STATIC for
-    // the session (creating/removing `fastagent/` mid-session is out of scope for watch re-sync).
+    // The placement arrives RESOLVED from the command (which already routed its refusal through failStartup).
     let worker;
     let reloadPending = false;
     let everServed = false; // has any worker successfully bound (sent `ready`) yet?
     let timer;
-    // The supervisor owns the tunnel so the public URL survives worker reloads (a fresh tunnel per save
-    // would mean a new URL + re-registering the webhook on every edit).
+    // The supervisor owns the tunnel so the public URL survives worker reloads (a fresh tunnel per save would mean a
+    // new URL + re-registering the webhook on every edit).
     let tunnel;
-    // The supervisor itself calls the channel webhook APIs (setWebhook) when announcing the tunnel, so
-    // it needs the proxy too (workers install their own). A region-blocked api.telegram.org fails otherwise.
-    if (options.tunnel)
-        installProxyFetch();
     const spawnWorker = () => {
         // ipc fd so the worker can signal readiness once it binds; stdio otherwise inherited.
         // biome-ignore lint/style/noNonNullAssertion: argv[1] is always the script path under a node entry
@@ -125,9 +86,8 @@ export async function runDevSupervisor(placement, options = {}) {
                 spawnWorker(); // restart requested: the old worker has exited, so the port is free
             }
             else if (!everServed) {
-                // Failed BEFORE ever serving — a non-editable startup failure (bad flag, EADDRINUSE, broken
-                // initial workspace) that saving cannot fix. Propagate the exit code (the worker already
-                // printed the error via inherited stdio).
+                // Failed BEFORE ever serving — a non-editable startup failure (bad flag, EADDRINUSE, broken initial
+                // workspace) that saving cannot fix.
                 process.exit(code ?? 1);
             }
             else {
@@ -146,8 +106,7 @@ export async function runDevSupervisor(placement, options = {}) {
             spawnWorker(); // worker was down (broken edit) — retry now
         }
     };
-    // chokidar gives reliable cross-platform recursion + structural ignore that native fs.watch
-    // cannot; devWatchIgnored (above) narrows the scope to the process-bound code inputs.
+    // chokidar gives reliable cross-platform recursion + structural ignore that native fs.watch cannot.
     const watcher = watchTree(placement.agentDir, {
         ignoreInitial: true, // the startup scan is not a change
         ignored: devWatchIgnored(placement.agentDir, dotEnvPath(placement.agentDir)),
@@ -158,9 +117,7 @@ export async function runDevSupervisor(placement, 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); AGENTS.md/persona.md/skills edits go live next turn without a restart`);
-    // FASTAGENT_SECRETS_DIR can move the `.env` OUT of the agent dir entirely; the watcher follows it
-    // anywhere inside (the resolved path is allow-listed above), but outside the watch root the worker
-    // would load a file no watcher sees. Say so once instead of leaving the hint above lying.
+    // FASTAGENT_SECRETS_DIR can move the `.env` OUT of the agent dir entirely.
     if (!isUnderDir(dotEnvPath(placement.agentDir), placement.agentDir)) {
         log.warn(`[fastagent] .env lives outside the agent dir (FASTAGENT_SECRETS_DIR → ${dotEnvPath(placement.agentDir)}) — it is NOT watched; restart dev after editing it`);
     }

package/dist/effect-port.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The ONE crossing between this codebase's Promise-shaped ports and Effect execution.
+ *
+ * The ports are everywhere and none of them are ours to change: the SPEC fixes `Agent.invoke` as an
+ * AsyncIterable and `SessionControl` as Promises, pi's SDK is Promise-based, every platform client
+ * is `fetch`, and so is the filesystem. Two properties have to hold at each crossing:
+ *
+ *  1. INTERRUPTION MUST JOIN. A Promise exposes no abort hook, so cancelling the fiber that awaits
+ *     one does not stop the work behind it. Releasing its resources anyway is how a disposed session
+ *     gets written to, or a lease is handed to the next turn while the previous one is still
+ *     running. {@link portJoin}, {@link portAbort} and {@link portRequest} therefore wait for the
+ *     pending promise to settle before releasing, and abort first when the port gives us a door.
+ *     {@link port} is the explicit opt-out, for work a caller may walk away from — so a call site
+ *     holding a lease, a session or any other resource must not reach for it.
+ *  2. THE CAUSE SURVIVES. Retry classification (`turn-kit.classifyRetryable`), the channels'
+ *     platform error types and every operator-facing message read the ORIGINAL error, so the
+ *     wrapper carries it verbatim and {@link portError} is how a caller gets it back.
+ *
+ * The channel kit, the pi engine, the AgentCore runtime and the scheduler all cross through here, so each rule is
+ * written once.
+ *
+ * What is NOT here is a policy: whether a failure rejects a request, is logged, or ends a turn stays
+ * with the caller that knows. The only opinion this module holds is the one above.
+ */
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+/** A Promise port's failure, carrying the original error as `cause`. One tag, because every caller
+ *  that discriminates does so on WHAT FAILED (its own control flow), never on which module wrapped it. */
+export declare class PortFailure extends Error {
+    readonly _tag = "PortFailure";
+    constructor(cause: unknown);
+}
+/** The original error behind a failed port, for classification and messages. */
+export declare function portError(cause: Cause.Cause<unknown>): unknown;
+/** A Promise port whose work is abandonable: interruption does not wait for it. Use for reads and
+ *  for writes a caller is free to walk away from; anything holding a resource wants {@link portJoin}. */
+export declare function port<A>(run: () => Promise<A>): Effect.Effect<A, PortFailure>;
+/** A Promise port with no abort hook: interruption joins the issued work before releasing. */
+export declare function portJoin<A>(run: () => Promise<A>): Effect.Effect<A, PortFailure>;
+/** A Promise port WITH an abort hook: interruption stops the work, then joins it. The hook runs only
+ *  on interruption — a settled operation must not be told to abort (`session.abort()` on a finished
+ *  run would reach the next one). A failing hook is diagnosed, never rethrown, under `label`: the
+ *  tag is one thing, but a serve running an invoke and a manual compaction at once needs the warn to
+ *  say WHICH abort could not be delivered. */
+export declare function portAbort<A>(label: string, run: () => Promise<A>, abort: () => void | Promise<void>): Effect.Effect<A, PortFailure>;
+/** A request with a deadline: the signal is closed on EVERY exit (it owns the response body, which a
+ *  settled call has to release too), and the real request is joined before ownership is given up. */
+export declare function portRequest<A>(run: (signal: AbortSignal) => Promise<A>, timeoutMs: number): Effect.Effect<A, PortFailure>;
+/** Cleanup anomalies are diagnostic: they cannot change an already-published outcome. */
+export declare function portCleanup(operation: string, run: () => void | Promise<void>): Effect.Effect<void>;

package/dist/effect-port.js

@@ -0,0 +1,77 @@
+/**
+ * The ONE crossing between this codebase's Promise-shaped ports and Effect execution.
+ *
+ * The ports are everywhere and none of them are ours to change: the SPEC fixes `Agent.invoke` as an
+ * AsyncIterable and `SessionControl` as Promises, pi's SDK is Promise-based, every platform client
+ * is `fetch`, and so is the filesystem. Two properties have to hold at each crossing:
+ *
+ *  1. INTERRUPTION MUST JOIN. A Promise exposes no abort hook, so cancelling the fiber that awaits
+ *     one does not stop the work behind it. Releasing its resources anyway is how a disposed session
+ *     gets written to, or a lease is handed to the next turn while the previous one is still
+ *     running. {@link portJoin}, {@link portAbort} and {@link portRequest} therefore wait for the
+ *     pending promise to settle before releasing, and abort first when the port gives us a door.
+ *     {@link port} is the explicit opt-out, for work a caller may walk away from — so a call site
+ *     holding a lease, a session or any other resource must not reach for it.
+ *  2. THE CAUSE SURVIVES. Retry classification (`turn-kit.classifyRetryable`), the channels'
+ *     platform error types and every operator-facing message read the ORIGINAL error, so the
+ *     wrapper carries it verbatim and {@link portError} is how a caller gets it back.
+ *
+ * The channel kit, the pi engine, the AgentCore runtime and the scheduler all cross through here, so each rule is
+ * written once.
+ *
+ * What is NOT here is a policy: whether a failure rejects a request, is logged, or ends a turn stays
+ * with the caller that knows. The only opinion this module holds is the one above.
+ */
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { log } from "./log.js";
+/** A Promise port's failure, carrying the original error as `cause`. One tag, because every caller
+ *  that discriminates does so on WHAT FAILED (its own control flow), never on which module wrapped it. */
+export class PortFailure extends Error {
+    _tag = "PortFailure";
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+    }
+}
+/** The original error behind a failed port, for classification and messages. */
+export function portError(cause) {
+    const error = Cause.squash(cause);
+    return error instanceof PortFailure ? error.cause : error;
+}
+/** Await a promise we already own, as a typed failure. */
+const wait = (pending) => Effect.tryPromise({ try: () => pending, catch: (cause) => new PortFailure(cause) });
+/** A Promise port whose work is abandonable: interruption does not wait for it. Use for reads and
+ *  for writes a caller is free to walk away from; anything holding a resource wants {@link portJoin}. */
+export function port(run) {
+    return Effect.tryPromise({ try: run, catch: (cause) => new PortFailure(cause) });
+}
+/** A Promise port with no abort hook: interruption joins the issued work before releasing. */
+export function portJoin(run) {
+    return Effect.acquireUseRelease(Effect.try({ try: run, catch: (cause) => new PortFailure(cause) }), wait, (pending, exit) => (Exit.hasInterrupts(exit) ? Effect.exit(wait(pending)) : Effect.void));
+}
+/** A Promise port WITH an abort hook: interruption stops the work, then joins it. The hook runs only
+ *  on interruption — a settled operation must not be told to abort (`session.abort()` on a finished
+ *  run would reach the next one). A failing hook is diagnosed, never rethrown, under `label`: the
+ *  tag is one thing, but a serve running an invoke and a manual compaction at once needs the warn to
+ *  say WHICH abort could not be delivered. */
+export function portAbort(label, run, abort) {
+    return Effect.acquireUseRelease(Effect.try({ try: run, catch: (cause) => new PortFailure(cause) }), wait, (pending, exit) => Exit.hasInterrupts(exit)
+        ? portCleanup(`${label} abort`, abort).pipe(
+        // Cancellation silences the port's result, but its work must settle before release.
+        Effect.andThen(Effect.exit(wait(pending))))
+        : Effect.void);
+}
+/** A request with a deadline: the signal is closed on EVERY exit (it owns the response body, which a
+ *  settled call has to release too), and the real request is joined before ownership is given up. */
+export function portRequest(run, timeoutMs) {
+    return Effect.acquireUseRelease(Effect.sync(() => {
+        const controller = new AbortController();
+        // Publish the controller before entering foreign code, including a synchronous fetch throw.
+        return { controller, pending: Promise.resolve().then(() => run(controller.signal)) };
+    }), ({ pending }) => wait(pending).pipe(Effect.timeout(timeoutMs), Effect.mapError((error) => (error instanceof PortFailure ? error : new PortFailure(error)))), ({ controller, pending }) => Effect.sync(() => controller.abort()).pipe(Effect.andThen(Effect.exit(wait(pending)))));
+}
+/** Cleanup anomalies are diagnostic: they cannot change an already-published outcome. */
+export function portCleanup(operation, run) {
+    return port(async () => run()).pipe(Effect.catchCause((cause) => Effect.sync(() => log.warn(`[fastagent] ${operation} failed during cleanup: ${String(portError(cause))}`))));
+}

package/dist/engines/pi/agent-session-factory.d.ts

@@ -1,5 +1,6 @@
+import { type Machine } from "./machine.ts";
 import type { Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { type AgentSessionServices, type CreateAgentSessionServicesOptions, type ModelRuntime, type SessionManager, createAgentSessionFromServices } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type AgentSessionServices, type CompactionResult, type CreateAgentSessionServicesOptions, type ModelRuntime, type ResolvedCommand, SessionManager, createAgentSessionFromServices } from "@earendil-works/pi-coding-agent";
 import type { PiAgentSessionFactory } from "./invoke-session.ts";
 import type { PiSessionRecordStore } from "./session-store.ts";
 import { type MountedTool } from "./tool.ts";
@@ -9,16 +10,9 @@ interface PiSessionDefinition {
     skills: Skill[];
 }
 export interface PiAgentSessionFactoryOptions {
-    /** Where conversations live. Continuity = same store + same session id. */
+    /** Where conversations live. */
     sessions: PiSessionRecordStore;
-    /**
-     * The model to run and the hub that authenticates it, resolved on FIRST USE and kept.
-     *
-     * A thunk because building a `ModelRuntime` is async while assembling an agent is not: the L1
-     * surface hands back an `Agent` synchronously, so the credential read that a runtime performs
-     * belongs on the first turn rather than in the caller's constructor. The two travel together
-     * because a model must be resolved against the runtime that holds its provider's auth.
-     */
+    /** The model to run and the hub that authenticates it, resolved on FIRST USE and kept. */
     engine: () => Promise<{
         modelRuntime: ModelRuntime;
         model: AnyModel;
@@ -29,34 +23,7 @@ export interface PiAgentSessionFactoryOptions {
     readDefinition: () => PiSessionDefinition | Promise<PiSessionDefinition>;
     /** The agent's working directory — what fastagent-defined tools see as `cwd`. */
     cwd: string;
-    /**
-     * Where pi looks for ITS settings (retry budget, compaction thresholds, default thinking level).
-     *
-     * Deliberately NOT pi's machine-global `~/.pi/agent`: a served agent must behave the same on the
-     * author's laptop and in a container, and reading the operator's personal pi configuration is the
-     * artifact losing to the machine. Point it at a definition-scoped path; a missing directory simply
-     * means pi's own defaults, which is the intended baseline.
-     */
-    agentDir?: string;
-    /**
-     * The definition's own extension entry points, for ANNOUNCING that serving does not run them.
-     *
-     * pi's extension machinery is built for one process serving one session: `bindCore()` copies the
-     * session's actions into a runtime the pi source itself calls "the shared runtime", extension
-     * modules are cached per assembly, and `session_start`/`session_shutdown` are a matched pair.
-     * Serving breaks every one of those assumptions — concurrent turns for unrelated conversations —
-     * and the failure is silent cross-talk: with two turns in flight, an extension calling
-     * `pi.sendMessage()` can deliver into the other conversation.
-     *
-     * Loading them anyway would be a correctness bug dressed as a feature, so serving does not, and
-     * warns when a definition ships some. `chat` runs them fully: one session, one runtime, which is
-     * exactly the shape pi is built for.
-     *
-     * Isolating them per session is mechanically possible — pi's uncached loader path builds a fresh
-     * module (jiti with `moduleCache: false`) and takes the runtime as an argument — but that function
-     * is not exported and the deep path is blocked by the package's `exports`. Reopening this needs
-     * that entry point upstream, not a workaround here.
-     */
+    /** The definition's own extension entry points, loaded fresh for every bound session. */
     extensionPaths?: string[];
     /** Built-ins omitted by an explicit lower-level tool list. */
     excludedToolNames?: readonly string[];
@@ -73,52 +40,66 @@ export interface BindPiSessionOptions {
     cwd: string;
     /** Built-ins omitted by an explicit lower-level tool list. */
     excludedToolNames?: readonly string[];
-    /** The CALLER's session id — what a tool asking which conversation it is in hears. Defaults to
-     *  pi's own id, which is right where the caller has none (chat). */
+    /** The CALLER's session id — what a tool asking which conversation it is in hears. */
     sessionId?: string;
-    /** Record each discovered activation on the session, so the next bind restores it. Off for chat:
-     *  pi's own session has nowhere to put one, so a resumed chat re-discovers. */
+    /** Record each discovered activation on the session, so the next bind restores it. */
     recordActivations: boolean;
 }
 /**
- * Bind ONE pi session to a record: the definition's tools as pi definitions over one turn context,
- * pi's own tool copies kept off, and deferral applied. The per-invoke factory and the resident chat
- * runtime both bind here — they differ in what they hand in (a shared vs a per-session `services`,
- * record-resolved vs configured settings) and in whether a discovered activation has a record to
- * land in, and in nothing else. Two copies of this drifted once (the tool adapter and the deferral
- * narrowing each existed twice, identical but for those parameters).
+ * Bind ONE pi session to a record: the definition's tools as pi definitions over one turn context, pi's own tool
+ * copies kept off, and deferral applied.
  */
 export declare function bindPiSession(options: BindPiSessionOptions): ReturnType<typeof createAgentSessionFromServices>;
 /**
- * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and
- * carries on with the rest — sound for a TUI that shows them, silent for a server that never looks.
- * A definition running without the extension it ships is exactly the "quietly missing" failure this
- * exists to remove. CHAT calls it, once per built services — serving does not load extensions at
- * all, and announces that instead (see PiAgentSessionFactoryOptions.extensionPaths).
+ * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and carries on with the
+ * rest.
  */
 export declare function reportExtensionErrors(services: AgentSessionServices): void;
 /** What pi is allowed to discover, minus the parts each assembly fills in itself. */
 type DefinitionLoaderOptions = NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>;
-/**
- * The resource posture a fastagent definition asks pi for — ONE definition of it, for both
- * assemblies. Serving (`piAgentSessionFactory`) and chat (`buildAgentSessionRuntime`) build
- * different sessions on top, but what pi is allowed to DISCOVER is not one of the differences:
- * everything comes from the definition, nothing from the machine that happens to be running it.
- *
- * Two copies of this drifted once already: `additionalExtensionPaths` was added to both, and only
- * one of them also passed the resulting tool names through pi's `tools` allowlist — so extensions
- * worked when served and vanished in chat. A difference between the two has to be visible AS a
- * difference, which is what the parameters are for: serving reads a prompt and skills that change
- * per turn and passes NO extension paths (it does not run them — see
- * {@link PiAgentSessionFactoryOptions.extensionPaths}); chat reads a fixed assembly and passes its
- * own. Both are arguments now, rather than two files that happen to disagree.
- */
+/** The resource posture a fastagent definition asks pi for — ONE definition of it, for both assemblies. */
 export declare function definitionResourceLoaderOptions(source: {
     systemPrompt: () => string | undefined;
     skills: () => Skill[];
-    /** Omitted by serving, which does not run them. */
+    /** {@link readMachine} for this workspace — resolved by the caller, because this function is synchronous. */
+    machine: Machine;
     extensionPaths?: readonly string[];
 }): DefinitionLoaderOptions;
-/** Open-or-create the record, then bind a fresh session to it. One call per invoke. */
+/** Tell a waiting {@link startCompaction} that pi admitted the compaction on this record. */
+export declare function admitCompaction(record: SessionManager): void;
+/** What pi decided before its model call: go ahead, nothing to do, or a failure of its own (in `refused`). */
+export type CompactAdmission = "admitted" | "nothing_to_compact" | {
+    refused: unknown;
+};
+/**
+ * Start pi's manual compaction on a bound session. `onAdmitted` runs INSIDE pi's admission event, so everything it
+ * publishes precedes anything pi does next (the model call, its retries). `admission` settles before the model call.
+ * pi's own pre-admission failures come back as `refused` rather than a rejection: the caller answers them to its
+ * Caller as a result. `done` is the compaction itself.
+ */
+export declare function startCompaction(session: AgentSession, instructions: string | undefined, onAdmitted: () => void): {
+    admission: Promise<CompactAdmission>;
+    done: Promise<CompactionResult>;
+};
+/**
+ * The `/name` commands a served session dispatches, named the way pi resolves them (a name two extensions share gets
+ * a `:N` suffix). Loaded through the same {@link servingServices} a turn binds, so the menu and the dispatch cannot
+ * disagree. Loading runs the extensions' factories; no session opens, so `session_start` does not fire, and the
+ * instances are never bound (any action they call throws).
+ */
+export declare function servedExtensionCommands(options: {
+    cwd: string;
+    modelRuntime: ModelRuntime;
+    extensionPaths: readonly string[];
+}): Promise<ResolvedCommand[]>;
+/**
+ * Open-or-create the record, then bind a fresh session to it — on a fresh resource loader.
+ *
+ * ONE LOADER PER SESSION, because pi's extension runtime belongs to its loader: a loader shared across concurrent
+ * turns would let one conversation's extension act on another's session. It also makes the definition live with no
+ * bookkeeping: every bind reads the prompt and skills this invoke read. The machine's half is the process's one read
+ * (machine.ts). Extension CODE is imported once per process, so an edit to `extensions/` needs a restart, which is
+ * what `dev` does on one.
+ */
 export declare function piAgentSessionFactory(options: PiAgentSessionFactoryOptions): PiAgentSessionFactory;
 export {};