@fastagent-sh/fastagent 0.18.0 → 0.19.0

package/dist/session-remote.d.ts

@@ -1,6 +1,6 @@
 /**
  * The remote `SessionControl` — the client half of the Phase 3 transport (design §13). Engine- and
- * server-neutral: speaks only the wire protocol `controlRoutes` serves (HTTP JSON + SSE with the
+ * server-neutral: speaks only the wire protocol `createControlPlane` serves (HTTP JSON + SSE with the
  * {sessionId, epoch, seq, event} envelope) and re-exposes the SAME `SessionControl` interface, so
  * local and remote consumers are isomorphic — client code does not change when the agent moves out
  * of process.

package/dist/session.d.ts

@@ -91,7 +91,7 @@ export declare const INVALID_COMMAND_CODE = "invalid_command";
  *  before acceptance; retry after the session's first turn exists. */
 export declare const NO_SUCH_SESSION_CODE = "no_such_session";
 /** Stable `SessionResult.error.code` for a boundary mutation rejected BEFORE acceptance with
- *  nothing durable landed — a failed override append, or compact's admission failing (the harness
+ *  nothing durable landed — a failed override append, or compact's admission failing (binding the session
  *  build, the local preparation). Acceptance sits where the work becomes asynchronous and
  *  expensive: the model call — compact is accept-fast (holding the dispatch open for a full model
  *  call would make acceptance = outcome), and post-acceptance outcomes travel as
@@ -289,7 +289,9 @@ export type CompactionFinishedEvent = SessionEvent<"compaction_finished", {
  *  the next event (message_*, `run_settled`, `compaction_finished`) is the closure, and the
  *  engine's `retry_finished` carries no outcome to forward. */
 export type RetryScheduledEvent = SessionEvent<"retry_scheduled", {
-    operation: "compaction" | "branch_summary";
+    /** "assistant" is an engine that retries the ANSWER request itself (pi's AgentSession does;
+     *  pi's own session does; a summarization call is the other two). */
+    operation: "assistant" | "compaction" | "branch_summary";
     attempt: number;
     maxAttempts: number;
     delayMs: number;

package/dist/session.js

@@ -16,7 +16,7 @@ export const INVALID_COMMAND_CODE = "invalid_command";
  *  before acceptance; retry after the session's first turn exists. */
 export const NO_SUCH_SESSION_CODE = "no_such_session";
 /** Stable `SessionResult.error.code` for a boundary mutation rejected BEFORE acceptance with
- *  nothing durable landed — a failed override append, or compact's admission failing (the harness
+ *  nothing durable landed — a failed override append, or compact's admission failing (binding the session
  *  build, the local preparation). Acceptance sits where the work becomes asynchronous and
  *  expensive: the model call — compact is accept-fast (holding the dispatch open for a full model
  *  call would make acceptance = outcome), and post-acceptance outcomes travel as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on GitHub, Telegram, Slack, or behind any channel.",
   "keywords": [
     "agent",
@@ -43,6 +43,10 @@
       "types": "./dist/core.d.ts",
       "default": "./dist/core.js"
     },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
     "./session": {
       "types": "./dist/session.d.ts",
       "default": "./dist/session.js"
@@ -101,9 +105,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@earendil-works/pi-agent-core": "^0.83.0",
-    "@earendil-works/pi-ai": "^0.83.0",
-    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-agent-core": "^0.84.3",
+    "@earendil-works/pi-ai": "^0.84.3",
+    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "@hono/node-server": "^2.1.1",
     "@larksuiteoapi/node-sdk": "^1.71.1",
     "@octokit/webhooks-methods": "^6.0.0",
     "@octokit/webhooks-types": "^7.6.1",
@@ -118,9 +123,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.2",
+    "@types/express": "^5.0.6",
     "@types/proper-lockfile": "^4.1.4",
+    "express": "^5.2.1",
+    "fastify": "^5.12.1",
     "knip": "^6.29.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.9",
+    "yaml": "^2.9.0"
   }
 }

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

@@ -1,115 +0,0 @@
-/**
- * pi harness wiring: construct one pi `AgentHarness` per session. The agent definition (AGENTS.md +
- * skills) is content fed INTO the harness (see definition.ts), not part of it.
- *
- * Under the stateless design the harness is discarded after each use; continuity comes from
- * persisting the session (PiSessionStore) and re-opening it per invoke — pi's prompt() folds the
- * historical entries back into context via buildContext().
- */
-import { AgentHarness } from "@earendil-works/pi-agent-core";
-import type { ExecutionEnv, ExecutionToolContext, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Model, Models } from "@earendil-works/pi-ai";
-import { type PiSessionStore, type SessionInheritance } from "./sessions.ts";
-import { type MountedTool } from "./tool.ts";
-import { type OverrideEntryLike } from "./session-settings.ts";
-/**
- * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
- * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
- * `active_tools_change` entries are full active-set SNAPSHOTS (setActiveTools persists everything
- * active at that moment), and reinterpreting a snapshot as activations would keep a tool active in
- * old sessions after the author flips it to `deferred` — the session never discovered it. Deltas
- * carry only what was actually discovered.
- */
-export declare const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
-/** The session a factory-built harness is bound to — the seam the activation bridge (invoke.ts) uses
- *  to write {@link TOOL_ACTIVATION_ENTRY} deltas (pi's harness keeps its session private). Absent for
- *  a harness built outside {@link piHarnessFactory}: activation still works in-turn there, but is not
- *  recorded — the factory owns persistence. */
-type AnyHarness = AgentHarness<any>;
-export type PiSession = Awaited<ReturnType<PiSessionStore["openOrCreate"]>>;
-export declare function harnessSession(harness: AnyHarness): PiSession | undefined;
-/**
- * pi's Model with the API-shape generic erased — fastagent only passes models through to the
- * harness, so the generic carries no information. One alias keeps the `any` auditable.
- */
-export type AnyModel = Model<any>;
-/** Builds a pi harness bound to the given session — called once per invoke. */
-/** The harness fastagent builds: context-typed on {@link ExecutionToolContext}, because that is what
- *  pi's env-backed default tools read (pi 0.83). Custom tools are context-FREE and stay assignable — a
- *  four-parameter `execute` satisfies the five-parameter one, so `defineTool` is untouched by this. */
-type PiHarness = AgentHarness<ExecutionToolContext>;
-export type PiHarnessFactory = (session: string, 
-/** Where a NEW session starts from (sessions.ts) — an existing session ignores it. */
-inherit?: SessionInheritance) => PiHarness | Promise<PiHarness>;
-export interface PiHarnessFactoryOptions {
-    /** Session persistence. Continuity = same backing store + same session id. */
-    sessions: PiSessionStore;
-    /** Filesystem/process environment for the default coding tools. Handed to the harness as the TURN's
-     *  tool context (pi 0.83), which is how read/bash/edit/write reach the machine at all — so this is the
-     *  ONE seam a sandbox adapter implements, not a knob beside the tools that ignore it. */
-    env: ExecutionEnv;
-    /** Provider collection for all model requests; {@link model} must belong to it (same provider id). */
-    models: Models;
-    model: AnyModel;
-    /** Reasoning effort for the model (pi's scale). Unset = fastagent's pinned default ("medium", pi
-     *  TUI parity — see {@link DEFAULT_THINKING_LEVEL}); unsupported levels are clamped by pi per model. */
-    thinkingLevel?: ThinkingLevel;
-    tools?: MountedTool[];
-    /**
-     * Final assembled prompt, or a SYNC factory re-evaluated per invoke (how L1 serves dynamic
-     * `instructions` + the skills listing). Distinct from {@link live}, which is the directory rung's
-     * ASYNC re-read of prompt AND skills as one pair — both are exercised, by different rungs.
-     */
-    systemPrompt?: string | (() => string);
-    /** Skills visible to the model / explicitly invokable (injected as harness resources). */
-    skills?: Skill[];
-    /**
-     * Per-invoke source for the prompt+skills PAIR, re-evaluated on every harness build. When set it
-     * supersedes {@link systemPrompt}/{@link skills} — one call yields both, so the skills listing
-     * inside the prompt and the mounted skill resources can never come from two different reads. The
-     * directory rung (L2) uses it to re-read the definition, so AGENTS.md/skills edits — the author's or
-     * the agent's own — take effect on the next turn without a process restart. A rejection surfaces
-     * as that invoke's `failed` event (the factory throw path), never a crash.
-     */
-    live?: () => Promise<{
-        systemPrompt?: string;
-        skills?: Skill[];
-    }>;
-}
-/**
- * Retry policy for generated compaction/branch-summary model calls (pi ≥0.81.1, #6901). OPT-IN
- * upstream — an undefined policy means no retries — so both compaction paths pass it explicitly:
- * the harness config (auto-compaction inside a run) and the manual `compact()` dispatch in
- * session-control. Values mirror pi's own app defaults (maxRetries 3, base 2s exponential).
- */
-export declare const SUMMARIZATION_RETRY_POLICY: {
-    readonly enabled: true;
-    readonly maxRetries: 3;
-    readonly baseDelayMs: 2000;
-};
-/**
- * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its
- * DEFAULT_THINKING_LEVEL) — NOT inherited from the bare harness, whose own fallback is "off": an
- * author vibes at "medium" in pi and must get "medium" when served (fidelity), and pinning the value
- * here means an upstream default change in either place cannot silently alter deployments. Models
- * that don't support a level are clamped by pi per model.
- */
-export declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
-/**
- * {@link resolveSessionSettings} plus the warn only the execution path owes: a recorded pair can stop
- * being executable with no control-plane command involved (pi appends these entries itself; a
- * deployment's configured model can change between restarts). Deduped per session+cause — it would
- * otherwise repeat every turn.
- */
-export declare function resolveHarnessOverrides(entries: OverrideEntryLike[], models: Models, defaults: {
-    model: AnyModel;
-    thinkingLevel: ThinkingLevel;
-}, sessionId: string): {
-    model: AnyModel;
-    thinkingLevel: ThinkingLevel;
-};
-export declare function resolveHarnessActiveToolNames(recorded: string[] | null, tools: MountedTool[], sessionId: string): string[] | undefined;
-/** Open-or-create the session per invoke: existing → open (history via buildContext); missing →
- *  create, seeded from `inherit` when the scope names a parent. */
-export declare function piHarnessFactory(options: PiHarnessFactoryOptions): PiHarnessFactory;
-export {};

package/dist/engines/pi/harness.js

@@ -1,154 +0,0 @@
-/**
- * pi harness wiring: construct one pi `AgentHarness` per session. The agent definition (AGENTS.md +
- * skills) is content fed INTO the harness (see definition.ts), not part of it.
- *
- * Under the stateless design the harness is discarded after each use; continuity comes from
- * persisting the session (PiSessionStore) and re-opening it per invoke — pi's prompt() folds the
- * historical entries back into context via buildContext().
- */
-import { AgentHarness } from "@earendil-works/pi-agent-core";
-import { log } from "../../log.js";
-import { activePathEntries } from "./sessions.js";
-import { isDeferredTool } from "./tool.js";
-import { resolveSessionSettings } from "./session-settings.js";
-/**
- * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
- * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
- * `active_tools_change` entries are full active-set SNAPSHOTS (setActiveTools persists everything
- * active at that moment), and reinterpreting a snapshot as activations would keep a tool active in
- * old sessions after the author flips it to `deferred` — the session never discovered it. Deltas
- * carry only what was actually discovered.
- */
-export const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
-const harnessSessions = new WeakMap();
-export function harnessSession(harness) {
-    return harnessSessions.get(harness);
-}
-/**
- * Provider request retries. The OpenAI-family / Anthropic / Azure / Codex pi-ai adapters
- * implement client-side retries (429/5xx/request-phase network failures with backoff, honoring
- * Retry-After; a Codex websocket that fails before the stream starts falls back to SSE) but all
- * default maxRetries to 0 (even SDK-backed ones override the SDK default), so a single transient
- * `fetch failed` would otherwise kill the whole turn; 2 matches the OpenAI/Anthropic SDK default.
- * The google / vertex / bedrock / mistral adapters ignore this option (a pi-ai upstream gap) —
- * transients there still fail the turn. Mid-stream drops are deliberately NOT retried anywhere on
- * this path — partial output was already streamed and the SPEC event stream cannot retract it,
- * so a mid-stream failure surfaces as a `failed` event.
- */
-const PROVIDER_MAX_RETRIES = 2;
-/**
- * Retry policy for generated compaction/branch-summary model calls (pi ≥0.81.1, #6901). OPT-IN
- * upstream — an undefined policy means no retries — so both compaction paths pass it explicitly:
- * the harness config (auto-compaction inside a run) and the manual `compact()` dispatch in
- * session-control. Values mirror pi's own app defaults (maxRetries 3, base 2s exponential).
- */
-export const SUMMARIZATION_RETRY_POLICY = { enabled: true, maxRetries: 3, baseDelayMs: 2000 };
-/**
- * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its
- * DEFAULT_THINKING_LEVEL) — NOT inherited from the bare harness, whose own fallback is "off": an
- * author vibes at "medium" in pi and must get "medium" when served (fidelity), and pinning the value
- * here means an upstream default change in either place cannot silently alter deployments. Models
- * that don't support a level are clamped by pi per model.
- */
-export const DEFAULT_THINKING_LEVEL = "medium";
-/**
- * Resolve the active-tool set for a fresh harness — the ONE place both fallbacks live. pi's harness
- * WRITES active-tool changes to the session (`setActiveTools` → `active_tools_change`) but its
- * constructor never reads them back — pi's long-lived TUI harness keeps the set in memory, while
- * fastagent builds a FRESH harness per invoke, which would silently reset the session's active set
- * every turn.
- *
- * No record (`null`) → the INITIAL set: every non-deferred tool; undefined when nothing is deferred
- * (pi's default — all active — applies, and no session entry is ever written; tool-sets without
- * deferral behave exactly as before deferral existed).
- *
- * A record is NOT replayed as a frozen snapshot — the active set is rebuilt as the UNION of the
- * initial set and the recorded names (filtered to the mounted tools: the constructor THROWS on
- * unknown names, so a recorded-but-removed tool would otherwise brick every future invoke of that
- * session). On the serving path only the additive activation bridge writes records, so a record's
- * real semantic is "which deferred tools this session activated" — layered on top of whatever the
- * workspace mounts TODAY. A snapshot replay would silently freeze a later-added non-deferred tool
- * out of every session the loader ever touched. Missing recorded names are logged (fail visibly) —
- * ONCE per session+missing set: a fresh harness is built per invoke and channel sessions live for
- * weeks, so an un-deduped warn would repeat every turn and dilute its own signal. A log-dedup memo
- * (like L2's findings memo), not session state — the resolve stays derived from the session.
- */
-const warnedRestores = new Set();
-/**
- * {@link resolveSessionSettings} plus the warn only the execution path owes: a recorded pair can stop
- * being executable with no control-plane command involved (pi appends these entries itself; a
- * deployment's configured model can change between restarts). Deduped per session+cause — it would
- * otherwise repeat every turn.
- */
-export function resolveHarnessOverrides(entries, models, defaults, sessionId) {
-    const settings = resolveSessionSettings(entries, models, defaults);
-    const warnOnce = (key, message) => {
-        const emit = warnedRestores.has(key) ? log.debug : log.warn;
-        warnedRestores.add(key);
-        emit(message);
-    };
-    const dropped = settings.dropped;
-    if (dropped?.model) {
-        warnOnce(`${sessionId}\u0000model\u0000${dropped.model}`, `[fastagent] session ${sessionId}: recorded model override ${dropped.model} is not in this deployment's registry — using the configured default`);
-    }
-    if (dropped?.thinkingLevel) {
-        const { recorded, running, known } = dropped.thinkingLevel;
-        warnOnce(`${sessionId}\u0000thinking\u0000${settings.model.provider}/${settings.model.id}\u0000${recorded}`, known
-            ? `[fastagent] session ${sessionId}: recorded thinking level "${recorded}" is not supported by ${settings.model.provider}/${settings.model.id} — running at "${running}"`
-            : `[fastagent] session ${sessionId}: recorded thinking level "${recorded}" is unknown — using the configured default`);
-    }
-    return { model: settings.model, thinkingLevel: settings.thinkingLevel };
-}
-export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
-    const anyDeferred = tools.some(isDeferredTool);
-    const initial = tools.filter((t) => !isDeferredTool(t)).map((t) => t.name);
-    if (recorded === null)
-        return anyDeferred ? initial : undefined;
-    const mounted = new Set(tools.map((t) => t.name));
-    const known = recorded.filter((name) => mounted.has(name));
-    const missing = recorded.filter((name) => !mounted.has(name));
-    if (missing.length > 0) {
-        const emit = warnedRestores.has(`${sessionId}\u0000${missing.join(",")}`) ? log.debug : log.warn;
-        warnedRestores.add(`${sessionId}\u0000${missing.join(",")}`);
-        emit(`[fastagent] session ${sessionId}: dropping recorded activation(s) no longer mounted: ${missing.join(", ")}`);
-    }
-    return [...new Set([...initial, ...known])];
-}
-/** Open-or-create the session per invoke: existing → open (history via buildContext); missing →
- *  create, seeded from `inherit` when the scope names a parent. */
-export function piHarnessFactory(options) {
-    return async (sessionId, inherit) => {
-        const session = await options.sessions.openOrCreate(sessionId, inherit);
-        // One extra entry walk per invoke to collect the activation deltas — negligible against the model
-        // call, same trade as L2's per-invoke definition re-read. The walk is over the ACTIVE PATH, not
-        // the flat journal: `navigate` moves the leaf, so the tree can hold an abandoned branch whose
-        // activations and overrides this session has left behind.
-        const entries = await activePathEntries(session);
-        const activated = entries.flatMap((e) => e.type === "custom" && e.customType === TOOL_ACTIVATION_ENTRY
-            ? (e.data?.names ?? [])
-            : []);
-        const fresh = options.live ? await options.live() : undefined;
-        const { systemPrompt } = options;
-        const prompt = fresh ? fresh.systemPrompt : typeof systemPrompt === "function" ? systemPrompt() : systemPrompt;
-        const skills = fresh ? fresh.skills : options.skills;
-        // Session overrides (set_model / set_thinking) win over the assembly defaults — same entry walk.
-        const overrides = resolveHarnessOverrides(entries, options.models, { model: options.model, thinkingLevel: options.thinkingLevel ?? DEFAULT_THINKING_LEVEL }, sessionId);
-        const harness = new AgentHarness({
-            // Static, not a per-turn provider: the env is fixed for the agent's lifetime, and resolving a
-            // constant per turn would only add a promise to the turn's critical path.
-            toolContext: { env: options.env },
-            session,
-            models: options.models,
-            model: overrides.model,
-            thinkingLevel: overrides.thinkingLevel,
-            tools: options.tools,
-            activeToolNames: resolveHarnessActiveToolNames(activated.length > 0 ? activated : null, options.tools ?? [], sessionId),
-            systemPrompt: prompt,
-            resources: skills ? { skills } : undefined,
-            streamOptions: { maxRetries: PROVIDER_MAX_RETRIES },
-            retry: SUMMARIZATION_RETRY_POLICY,
-        });
-        harnessSessions.set(harness, session);
-        return harness;
-    };
-}

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

@@ -1,60 +0,0 @@
-/**
- * The harness L0: fan pi AgentHarness's two ports (subscribe event side-channel + prompt final
- * value) into SPEC's single event stream, under a single-writer-per-session lease.
- *
- * The half that does not care which pi class runs the turn — lease, terminals, event queue, prompt
- * prep — is turn-kit.ts. What lives here is what only the harness has: its event vocabulary, translated ONCE
- * into the rich `SessionEvent` layer, and the observation plane that layer feeds.
- *
- * Concurrency: at most one in-flight turn per session; a second invoke fails fast with
- * `failed{retryable}` ("session busy"), leaving dedupe/queueing/steering to the channel. Each
- * invoke builds a fresh harness bound to the session and discards it (stateless multi-session).
- */
-import type { AgentHarnessEvent } from "@earendil-works/pi-agent-core";
-import { type Agent, type AgentEvent, type Prompt } from "../../agent.ts";
-import type { SessionEvent } from "../../session.ts";
-import { type PiHarnessFactory } from "./harness.ts";
-import { type Lease } from "./turn-kit.ts";
-/**
- * In-stream event mapping — pi events are translated ONCE into the rich `SessionEvent` vocabulary;
- * the SPEC `AgentEvent` stream is a narrow {@link projectAgentEvent} of it (design §6: one
- * translation plus one projection, never two parallel translations). pi events with no session
- * vocabulary yet (turn_start, agent_start, …) are dropped.
- */
-export declare function toSessionEvent(pe: AgentHarnessEvent, runId: string): SessionEvent | null;
-/** The SPEC projection of the rich stream. Events with no `AgentEvent` counterpart (progress,
- *  message boundaries, run boundaries) project to null — the invoke terminal is produced from the
- *  resolved message ({@link toTerminal}), not from `run_settled`. */
-export declare function projectAgentEvent(se: SessionEvent): AgentEvent | null;
-/** Live modulation handles for one active run — what the control plane's `dispatch` routes to.
- *  Built inside the invoke closure (it owns the harness); registered with the observer at
- *  run_started, gone after run_settled. RACE WINDOW (all three commands, symmetric): the run may
- *  resolve between the settled-check and the engine call landing — an accepted `abort` can still
- *  settle `completed`, and an accepted `steer`/`followUp` can settle without the prompt ever being
- *  consumed. Acceptance is not outcome; the settlement is the truth. */
-export interface RunControls {
-    steer(prompt: Prompt): Promise<void>;
-    followUp(prompt: Prompt): Promise<void>;
-    abort(): Promise<void>;
-}
-/** The DATA-plane observation seam: every rich event of every run, pushed as it happens. `run`
- *  carries the live {@link RunControls}, attached to the `run_started` event only. A hub
- *  (session-control.ts) implements this to serve `events()`/`state()`/`dispatch`; absent = zero
- *  overhead. Scope: RUN events only — the hub's own boundary-mutation events (`state_changed`,
- *  `compaction_*`) originate in the hub and reach full-vocabulary taps via the hub's `tap` option,
- *  not this seam. TRUST BOUNDARY: since Phase 2a this seam hands every wired observer the run's
- *  modulation handles — it is the trusted hub seam, not a public fan-out point. Do not wire
- *  untrusted taps here; give third parties the read-only `events()` stream instead. */
-export type SessionObserver = (session: string, event: SessionEvent, run?: RunControls) => void;
-export interface CreatePiAgentFromHarnessOptions {
-    harnessFactory: PiHarnessFactory;
-    /** Single-writer lease. Defaults to the in-process per-session fail-fast lease. */
-    lease?: Lease;
-    /** Observation-plane tap (see {@link SessionObserver}). Optional; invoke behavior is identical
-     *  with or without it — the SPEC stream is a projection of what the observer sees. */
-    observer?: SessionObserver;
-    /** Working directory exposed to FastAgent-defined tools. Defaults to process.cwd(). */
-    cwd?: string;
-}
-/** "From a harness factory": engine wired by the caller; adds only the concurrency/stream shell. */
-export declare function createPiAgentFromHarness(options: CreatePiAgentFromHarnessOptions): Agent;