@fastagent-sh/fastagent 0.17.0 → 0.18.0

package/dist/engines/pi/turn-kit.js

@@ -0,0 +1,161 @@
+import { ABORTED_CODE } from "../../agent.js";
+export function inProcessLease() {
+    const busy = new Set();
+    return {
+        tryAcquire(session) {
+            if (busy.has(session))
+                return null;
+            busy.add(session);
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                busy.delete(session);
+            };
+        },
+    };
+}
+/** Clearly-transient network error codes (Node/undici), decisive on their own. */
+const RETRYABLE_CODES = new Set([
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "EAI_AGAIN",
+    "EPIPE",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+/** 429 (rate limit) and 5xx (server) are worth retrying; other statuses are decisive NON-retryable. */
+const statusIsRetryable = (status) => status === 429 || (status >= 500 && status < 600);
+/** Last-resort prose match, used only when no structured status/code is available. */
+const RETRYABLE_MESSAGE = /\b(429|5\d\d|timeout|timed out|rate.?limit|overloaded|ECONNRESET|ETIMEDOUT|ENETUNREACH|EAI_AGAIN|socket hang up)\b/i;
+/** A structured status/code decision, or `null` when the signal is absent/undecisive → fall to prose. */
+function retryableFromSignal(signal) {
+    if (typeof signal.status === "number")
+        return statusIsRetryable(signal.status);
+    const { code } = signal;
+    if (typeof code === "number")
+        return statusIsRetryable(code);
+    if (typeof code === "string") {
+        if (RETRYABLE_CODES.has(code))
+            return true;
+        if (/^\d{3}$/.test(code))
+            return statusIsRetryable(Number(code)); // a status carried as a string
+    }
+    return null; // no code, or an unknown one — not decisive on its own
+}
+/** Classify `retryable`: structured status/code first, message prose only as the last-resort ceiling. */
+export function classifyRetryable(details, signal) {
+    return retryableFromSignal(signal) ?? RETRYABLE_MESSAGE.test(details);
+}
+/** Pull a structured status/code off a thrown error (HTTP status or a network code, incl. its cause). */
+function errorSignal(error) {
+    if (!error || typeof error !== "object")
+        return {};
+    const e = error;
+    const status = typeof e.status === "number" ? e.status : typeof e.statusCode === "number" ? e.statusCode : undefined;
+    const causeCode = e.cause && typeof e.cause === "object" ? e.cause.code : undefined;
+    return { status, code: e.code ?? causeCode };
+}
+/**
+ * Pull the structured error `code` pi records on a failed message's diagnostics. `diagnostics`
+ * accumulates across attempts (`appendAssistantMessageDiagnostic`), so the terminal cause is the LAST
+ * code-bearing entry — `findLast`, not `find`: an earlier attempt's transient 503 must not classify a
+ * terminal 400/auth failure as retryable. (Reverse scan rather than `findLast` — the tsconfig lib is
+ * ES2022.)
+ */
+function messageSignal(message) {
+    const diagnostics = message.diagnostics ?? [];
+    for (let i = diagnostics.length - 1; i >= 0; i--) {
+        const code = diagnostics[i]?.error?.code;
+        if (code !== undefined)
+            return { code };
+    }
+    return {};
+}
+/**
+ * Terminal mapping, decided by the resolved message's stopReason: pi's prompt() resolves a message
+ * with stopReason "error"/"aborted" rather than throwing, so relying on catch alone would miss this
+ * entire failure class (violating SPEC MUST 1).
+ */
+export function toTerminal(message) {
+    if (message.stopReason === "aborted") {
+        // A deliberate stop (control-plane abort / harness abort), not an error — see {@link ABORTED_CODE}
+        // for the consumer contract (design §6).
+        const details = message.errorMessage ?? "run aborted";
+        return { type: "failed", details, retryable: false, code: ABORTED_CODE };
+    }
+    if (message.stopReason === "error") {
+        const details = message.errorMessage ?? `model stopped: ${message.stopReason}`;
+        return { type: "failed", details, retryable: classifyRetryable(details, messageSignal(message)) };
+    }
+    return { type: "completed" };
+}
+export function errorToTerminal(error) {
+    const details = error instanceof Error ? error.message : String(error);
+    return { type: "failed", details, retryable: classifyRetryable(details, errorSignal(error)) };
+}
+/**
+ * Map prompt images to pi ImageContent, resizing each to model-friendly dimensions/size with pi's
+ * Photon resizer (reused from pi-coding-agent, lazy-imported so the common no-image headless path never
+ * loads the TUI module graph). A null resize (unresizable / Photon unavailable) keeps the original
+ * bytes — the provider then applies its own limit.
+ */
+export async function toPiPromptOptions(prompt) {
+    if (!prompt.images || prompt.images.length === 0)
+        return undefined;
+    const { resizeImage } = await import("@earendil-works/pi-coding-agent");
+    const images = await Promise.all(prompt.images.map(async (img) => {
+        const resized = await resizeImage(Buffer.from(img.data, "base64"), img.mimeType, {
+            maxWidth: 1568,
+            maxHeight: 1568,
+            maxBytes: 5 * 1024 * 1024,
+        }).catch(() => null);
+        return resized
+            ? { type: "image", data: resized.data, mimeType: resized.mimeType }
+            : { type: "image", data: img.data, mimeType: img.mimeType };
+    }));
+    return { images };
+}
+// ── EventQueue: push→pull plumbing for a two-port engine ────────────────────
+//
+// Single-consumer async queue; single-threaded JS means no await interleaves between push and
+// drain, so no locking. Engines that are natively async-iterable would not need it.
+export class EventQueue {
+    buffer = [];
+    wake;
+    push(item) {
+        this.buffer.push(item);
+        const wake = this.wake;
+        this.wake = undefined;
+        wake?.();
+    }
+    /**
+     * Yield pushed events in order until `done` settles AND the buffer is drained. The terminal is
+     * produced separately (toTerminal); rejections of `done` are swallowed here (the caller awaits
+     * `run` itself) to avoid unhandled rejections.
+     */
+    async *drainUntil(done) {
+        let settled = false;
+        const onSettle = () => {
+            settled = true;
+            const wake = this.wake;
+            this.wake = undefined;
+            wake?.();
+        };
+        const finished = done.then(onSettle, onSettle);
+        while (true) {
+            while (this.buffer.length > 0) {
+                yield this.buffer.shift();
+            }
+            if (settled)
+                break;
+            await new Promise((resolve) => {
+                this.wake = resolve;
+            });
+        }
+        await finished;
+    }
+}

package/dist/paths.d.ts

@@ -24,6 +24,12 @@ export declare const STATE_DIRNAME = ".state";
 /** The config filenames, in load precedence. ONE source: the loader (below) and `scaffoldAgent`'s
  *  already-an-agent refusal both read this, so "is there a config?" can't diverge between them. */
 export declare const AGENT_CONFIG_NAMES: readonly ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
+/** The optional custom-model-endpoint file inside an agent dir (pi's models.json schema). Definition
+ *  data, not machinery: it declares WHICH endpoint the agent talks to, so it belongs beside the config
+ *  and travels into the deployed image. The name lives HERE, with the other placement facts, because
+ *  two neutral readers need it — the loader in engines/pi/models.ts and `dev`'s watcher, whose restart
+ *  scope must not silently drift from what the worker actually loads. */
+export declare const AGENT_MODELS_FILE = "models.json";
 export interface ResolvedPlacement {
     /** The AGENT directory — where the definition (persona.md/skills/tools/channels/schedules), the
      *  config, and the machinery dirs (`.secrets/`, `.state/`) live. Absolute. */

package/dist/paths.js

@@ -46,6 +46,12 @@ export const STATE_DIRNAME = ".state";
 /** The config filenames, in load precedence. ONE source: the loader (below) and `scaffoldAgent`'s
  *  already-an-agent refusal both read this, so "is there a config?" can't diverge between them. */
 export const AGENT_CONFIG_NAMES = ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
+/** The optional custom-model-endpoint file inside an agent dir (pi's models.json schema). Definition
+ *  data, not machinery: it declares WHICH endpoint the agent talks to, so it belongs beside the config
+ *  and travels into the deployed image. The name lives HERE, with the other placement facts, because
+ *  two neutral readers need it — the loader in engines/pi/models.ts and `dev`'s watcher, whose restart
+ *  scope must not silently drift from what the worker actually loads. */
+export const AGENT_MODELS_FILE = "models.json";
 /** The definition paths an agent LOADS content from — the surface a second agent must not be scaffolded
  *  inside ({@link agentDefinitionOwner}), because the outer agent would read it as its own skills/tools.
  *  NOT evidence of an agent: `tools/` and `skills/` are ordinary names half the world's repositories

package/dist/pi.d.ts

@@ -7,10 +7,11 @@ export { loadChannels, type ChannelCollision } from "./engines/pi/channel.ts";
 export { createPiAgentFromDir, type CreatePiAgentFromDirOptions, } from "./engines/pi/open.ts";
 export type { LoadedDefinition, SkillCollision } from "./engines/pi/definition.ts";
 export { defineConfig, listModels, resolveModel, type FastagentConfig } from "./engines/pi/config.ts";
-export { inProcessLease, type Lease, type Release, type SessionObserver } from "./engines/pi/invoke.ts";
+export type { SessionObserver } from "./engines/pi/invoke.ts";
+export { inProcessLease, type Lease, type Release } from "./engines/pi/turn-kit.ts";
 export { createPiSessionControl, type CreatePiSessionControlOptions, } from "./engines/pi/session-control.ts";
 export type { AnyModel } from "./engines/pi/harness.ts";
-export { inMemorySessionStore, jsonlSessionStore, type PiSessionReader, type PiSessionStore, } from "./engines/pi/sessions.ts";
+export { inMemorySessionStore, jsonlSessionStore, type PiSessionReader, type PiSessionStore, type SessionInheritance, } from "./engines/pi/sessions.ts";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore, type FastagentAuthOptions } from "./engines/pi/auth.ts";
 export { createPiModels, probeAuthSource, type CreatePiModelsOptions } from "./engines/pi/models.ts";
 export type { Models } from "@earendil-works/pi-ai";

package/dist/pi.js

@@ -5,7 +5,7 @@ export { z } from "zod";
 export { loadChannels } from "./engines/pi/channel.js";
 export { createPiAgentFromDir, } from "./engines/pi/open.js";
 export { defineConfig, listModels, resolveModel } from "./engines/pi/config.js";
-export { inProcessLease } from "./engines/pi/invoke.js";
+export { inProcessLease } from "./engines/pi/turn-kit.js";
 export { createPiSessionControl, } from "./engines/pi/session-control.js";
 export { inMemorySessionStore, jsonlSessionStore, } from "./engines/pi/sessions.js";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./engines/pi/auth.js";

package/dist/scaffold/templates/fastagent.config.mjs

@@ -5,6 +5,8 @@
 // No model is preset: `fastagent dev` shows the full model catalog (models you already have
 // credentials for come first; picking one that needs auth logs you in inline) and writes your choice
 // below. Or set it by hand to a "provider/modelId" (`fastagent models` lists them).
+// Self-hosted model (vLLM/Ollama/…) or your own gateway? Declare it in a models.json next to this
+// file and select it like any other spec — see docs/configuration.md "Custom model endpoints".
 export default {
   // model: "openai-codex/gpt-5.5",
   // thinkingLevel: "high", // reasoning effort (off|minimal|low|medium|high|xhigh|max); default "medium" (pi TUI parity)

package/dist/session-remote.js

@@ -202,7 +202,8 @@ export function connectAgent(options) {
     // (carry it or reject it), never vanish on the wire while the client believes it was sent.
     const _invokeDriftGuard = {};
     void _invokeDriftGuard;
-    // Same guard for Scope: the body carries session only — a new Scope field must force a decision.
+    // Same guard for Scope: the body carries session + the lineage extension — a new Scope field must
+    // force a decision (carry it or reject it), never vanish on the wire.
     const _scopeDriftGuard = {};
     void _scopeDriftGuard;
     return {
@@ -229,7 +230,14 @@ export function connectAgent(options) {
                     const res = await fetchFn(`${base}/control/invoke`, {
                         method: "POST",
                         headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
-                        body: JSON.stringify({ session: scope.session, text: prompt.text }),
+                        body: JSON.stringify({
+                            session: scope.session,
+                            text: prompt.text,
+                            // Lineage rides the wire so a remote thread scope inherits server-side; the server
+                            // reads it on the session-create path only, same as in-process.
+                            ...(scope.parentSession !== undefined ? { parentSession: scope.parentSession } : {}),
+                            ...(scope.branchHints !== undefined ? { branchHints: scope.branchHints } : {}),
+                        }),
                         signal: abort.signal,
                     });
                     watchdog.disarm(); // headers arrived

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.17.0",
+  "version": "0.18.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",