@fastagent-sh/fastagent 0.17.1 → 0.19.0

package/dist/engines/pi/read-image.js

@@ -1,62 +0,0 @@
-/**
- * The image pipeline pi's `read` tool needs: normalize an unsupported format to PNG, resize below the
- * inline limit, and hand back the hints that tell the model what it is looking at.
- *
- * pi-agent-core's `createReadTool` takes this as an INJECTED processor and does nothing without one —
- * unlike pi-coding-agent's, which wires its private `processImage` internally. That function is not
- * exported (nor reachable: the package's `exports` map has no deep paths), so this rebuilds it from the
- * two halves that ARE public, `convertToPng` and `resizeImage`/`formatDimensionNote`.
- *
- * It is upstream logic restated, which is a real cost — without it `read` on a screenshot sends the raw
- * bytes (measured: 7.48 MB of base64 where pi-coding-agent sends 3.48 MB, and no dimension note for the
- * model's coordinate math), and a bmp is dropped entirely while the tool's own description still
- * advertises it. test/tools-parity.test.ts compares this against pi-coding-agent's real `read` on both
- * paths, so upstream changing the pipeline surfaces as a failing test rather than as drift.
- */
-import { convertToPng, formatDimensionNote, resizeImage } from "@earendil-works/pi-coding-agent";
-/** Formats a provider takes inline as-is; everything else has to become a PNG first. */
-const INLINE_MIME = {
-    "image/png": "image/png",
-    "image/jpeg": "image/jpeg",
-    "image/jpg": "image/jpeg",
-    "image/gif": "image/gif",
-    "image/webp": "image/webp",
-};
-/** The `read` tool's image processor. Matches pi-coding-agent's messages verbatim: they reach the model
- *  as tool output, so a reworded one is a different prompt, not a different implementation detail. */
-export const readImageProcessor = async (bytes, mimeType, options) => {
-    const base = mimeType.split(";")[0]?.trim().toLowerCase() ?? mimeType.toLowerCase();
-    const inline = INLINE_MIME[base];
-    let normalized;
-    if (inline) {
-        normalized = { bytes, mimeType: inline };
-    }
-    else {
-        const png = await convertToPng(Buffer.from(bytes).toString("base64"), base);
-        if (!png)
-            return { ok: false, message: "[Image omitted: could not be converted to a supported inline image format.]" };
-        normalized = { bytes: Buffer.from(png.data, "base64"), mimeType: png.mimeType, convertedFrom: base };
-    }
-    const hints = [];
-    const converted = (to) => normalized.convertedFrom && normalized.convertedFrom !== to
-        ? `[Image converted from ${normalized.convertedFrom} to ${to}.]`
-        : undefined;
-    if (!options.autoResizeImages) {
-        const hint = converted(normalized.mimeType);
-        if (hint)
-            hints.push(hint);
-        return { ok: true, data: Buffer.from(normalized.bytes).toString("base64"), mimeType: normalized.mimeType, hints };
-    }
-    const resized = await resizeImage(normalized.bytes, normalized.mimeType);
-    if (!resized)
-        return { ok: false, message: "[Image omitted: could not be resized below the inline image size limit.]" };
-    const hint = converted(resized.mimeType);
-    if (hint)
-        hints.push(hint);
-    // The scale factor the model needs to map coordinates back onto the original — dropping it is what
-    // makes a resized screenshot unusable for anything positional.
-    const note = formatDimensionNote(resized);
-    if (note)
-        hints.push(note);
-    return { ok: true, data: resized.data, mimeType: resized.mimeType, hints };
-};

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

@@ -1,44 +0,0 @@
-import type { Session, SessionTreeEntry } from "@earendil-works/pi-agent-core";
-/** What fastagent needs from a session backend: open-or-create by opaque id. */
-export interface PiSessionStore {
-    openOrCreate(sessionId: string): Promise<Session>;
-}
-/**
- * OPEN-EXISTING sibling of {@link PiSessionStore} (session-control.ts): an unknown session answers
- * `undefined`, never creates one — sessions are the data plane's monopoly. Two consumers:
- * - the OBSERVATION plane (`state()`/`entries()`), strictly read-only (design §16 invariant 4);
- * - the control plane's BOUNDARY writers (`set_model`/`set_thinking` append override records to the
- *   returned handle; `navigate` moves its leaf) after an existence check, under the run lease.
- * `openIfExists` skips the open-time crash reconciliation (that appends repair entries — a write
- * the observation plane must not perform). The boundary writers are safe WITHOUT it for two
- * different reasons: an override record is not a message, so it cannot create or pair with a
- * dangling tool_use; a `navigate` writes no message either, but it CAN expose one — parking the
- * leaf on an assistant entry whose tool results are now off-path is the dangling-pair state
- * {@link reconcileInterruptedToolCalls} exists for. That is repaired at the next `openOrCreate`,
- * which repairs AT THE LEAF — exactly where a move puts it.
- *
- * Writing MESSAGE-class records through this handle would bypass that repair: use `openOrCreate`
- * for anything that enters the transcript.
- */
-export interface PiSessionReader {
-    openIfExists(sessionId: string): Promise<Session | undefined>;
-}
-/**
- * The entries on the session's ACTIVE path, root→leaf — what every last-wins read must walk.
- * `getEntries()` is the whole TREE: once `navigate` can move the leaf, the journal still carries
- * the abandoned branch, and reading it flat would run the session on a setting it moved away from.
- * Deliberately NOT `Session.getBranch()`: that walk is bounded by the last compaction's retained
- * window, which is the right bound for MODEL CONTEXT and the wrong one for settings — an override
- * recorded before a compaction is a preference, and it still governs the session after one.
- */
-export declare function activePathEntries(session: Session): Promise<SessionTreeEntry[]>;
-/** In-process store (pi InMemorySessionRepo). Continuity lives and dies with the instance. */
-export declare function inMemorySessionStore(): PiSessionStore & PiSessionReader;
-/**
- * Disk-backed store (pi JsonlSessionRepo under `dir`): restart the process, conversations continue.
- * `cwd` is recorded in session metadata; defaults to process.cwd().
- */
-export declare function jsonlSessionStore(options: {
-    dir: string;
-    cwd?: string;
-}): PiSessionStore & PiSessionReader;

package/dist/engines/pi/sessions.js

@@ -1,182 +0,0 @@
-/**
- * Session persistence — the K-axis port and its first two backends.
- *
- * PiSessionStore is the consumer-owned port: open-or-create by opaque session id, nothing more.
- * pi's full SessionRepo surface (list/open/create/delete/fork) stays behind the adapters. The `Pi`
- * prefix is honest — `openOrCreate` returns pi's `Session`, so this is pi-coupled, not a neutral
- * persistence contract.
- *
- * Continuity = same backing store + same session id: in-memory continuity dies with the instance;
- * jsonl survives process restarts (disk is the truth).
- */
-import { InMemorySessionRepo } from "@earendil-works/pi-agent-core";
-import { JsonlSessionRepo, NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { log } from "../../log.js";
-/**
- * Crash-safety reconciliation, run on every OPEN of an existing session.
- *
- * A turn that dies mid tool-execution leaves an assistant `tool_use` with no matching result (pi
- * persists the assistant message before the tool runs). The next turn would then hand the provider an
- * `assistant(tool_use) -> user` sequence that Anthropic/OpenAI reject — the session is poisoned. We
- * append an honest "interrupted" error result for each dangling call, restoring a valid transcript.
- * Tool side-effect idempotency stays the tool's responsibility (SPEC §6); this only restores
- * transcript validity, not exactly-once execution.
- *
- * Pairing is TURN-LOCAL: a tool_use is paired only by a toolResult that immediately follows it (up to
- * the next non-toolResult). tool-call ids are not unique across turns (a local model may restart ids
- * each response), so matching against the whole transcript could falsely settle a leaf call against an
- * earlier turn's identical id. Append-only logs can only repair a gap AT THE LEAF (last assistant
- * followed by nothing but its own results); an earlier gap is surfaced via log.warn rather than
- * "fixed" with an orphaned result that appending cannot place.
- *
- * The synthetic result splits its audiences: `content` (read by the model, may reach the end user)
- * stays neutral — it must NOT say "aborted" (pi's word for a user cancellation) or leak infra detail;
- * `details` carries the operational marker for developers and is never sent to the provider.
- */
-async function reconcileInterruptedToolCalls(session) {
-    const { messages } = await session.buildContext();
-    let leafIdx = -1;
-    for (let i = messages.length - 1; i >= 0; i--) {
-        if (messages[i]?.role === "assistant") {
-            leafIdx = i;
-            break;
-        }
-    }
-    if (leafIdx === -1)
-        return; // no assistant turn yet
-    const leafReparable = messages.slice(leafIdx + 1).every((m) => m.role === "toolResult");
-    const toRepair = [];
-    const orphaned = [];
-    messages.forEach((m, idx) => {
-        if (m.role !== "assistant")
-            return;
-        const paired = new Set();
-        for (let j = idx + 1; j < messages.length; j++) {
-            const next = messages[j];
-            if (next?.role !== "toolResult")
-                break;
-            paired.add(next.toolCallId);
-        }
-        for (const block of m.content) {
-            if (block.type !== "toolCall" || paired.has(block.id))
-                continue;
-            if (idx === leafIdx && leafReparable)
-                toRepair.push({ id: block.id, name: block.name });
-            else
-                orphaned.push(block.id);
-        }
-    });
-    if (orphaned.length > 0) {
-        log.warn(`[fastagent] unmatched tool_use is not at the session leaf; leaving it unreconciled ` +
-            `(an append-only log cannot repair a mid-history gap): toolCallIds=${orphaned.join(",")}`);
-    }
-    for (const { id, name } of toRepair) {
-        const result = {
-            role: "toolResult",
-            toolCallId: id,
-            toolName: name,
-            content: [
-                {
-                    type: "text",
-                    text: "This tool call did not complete and its result is unavailable. Re-run it if the result is still needed.",
-                },
-            ],
-            details: { fastagent: "interrupted-tool-call" },
-            isError: true,
-            timestamp: Date.now(),
-        };
-        await session.appendMessage(result);
-    }
-}
-/**
- * The entries on the session's ACTIVE path, root→leaf — what every last-wins read must walk.
- * `getEntries()` is the whole TREE: once `navigate` can move the leaf, the journal still carries
- * the abandoned branch, and reading it flat would run the session on a setting it moved away from.
- * Deliberately NOT `Session.getBranch()`: that walk is bounded by the last compaction's retained
- * window, which is the right bound for MODEL CONTEXT and the wrong one for settings — an override
- * recorded before a compaction is a preference, and it still governs the session after one.
- */
-export async function activePathEntries(session) {
-    // LEAF FIRST, then the journal — the order is load-bearing, not incidental: `getEntries()` is a
-    // SNAPSHOT, so reading it first would let any concurrent append (i.e. any turn in progress) leave
-    // a leaf the snapshot cannot contain, and the integrity throw below would fire on a live session
-    // instead of a corrupt one. This way the snapshot is always a superset of the leaf's chain.
-    const leafId = await session.getLeafId();
-    const entries = await session.getEntries();
-    // A null leaf is pi's ROOT position (what `moveTo(null)` sets), so the active path is EMPTY — not
-    // "the whole journal", which on a branched session would mean every abandoned branch at once.
-    if (leafId === null)
-        return [];
-    const byId = new Map(entries.map((e) => [e.id, e]));
-    // A chain that is not intact THROWS: any other disposition returns a short path that reads like a
-    // short session (every override and activation above the gap gone, the next turn silently on
-    // assembly defaults). pi's storages already reject a leaf outside the journal in `getLeafId()`,
-    // but the port is swappable — so the walk names it here rather than dying on `undefined.parentId`.
-    const start = byId.get(leafId);
-    if (!start)
-        throw new Error(`session leaf "${leafId}" is missing from the journal`);
-    const path = [];
-    for (let cur = start;;) {
-        path.push(cur);
-        // A path cannot be longer than the journal it walks; anything more is a parentId cycle, which
-        // would otherwise hang the turn with no `failed` event at all.
-        if (path.length > entries.length)
-            throw new Error(`session entry "${cur.id}" cycles through its parents`);
-        if (!cur.parentId)
-            break;
-        const parent = byId.get(cur.parentId);
-        if (!parent)
-            throw new Error(`session entry "${cur.parentId}" is missing from the journal (parent of "${cur.id}")`);
-        cur = parent;
-    }
-    return path.reverse(); // walked leaf→root; every consumer reads it root→leaf
-}
-/** In-process store (pi InMemorySessionRepo). Continuity lives and dies with the instance. */
-export function inMemorySessionStore() {
-    const repo = new InMemorySessionRepo();
-    return {
-        async openOrCreate(sessionId) {
-            const existing = (await repo.list()).find((m) => m.id === sessionId);
-            if (!existing)
-                return repo.create({ id: sessionId });
-            const session = await repo.open(existing);
-            await reconcileInterruptedToolCalls(session);
-            return session;
-        },
-        async openIfExists(sessionId) {
-            const existing = (await repo.list()).find((m) => m.id === sessionId);
-            return existing ? repo.open(existing) : undefined;
-        },
-    };
-}
-/**
- * Disk-backed store (pi JsonlSessionRepo under `dir`): restart the process, conversations continue.
- * `cwd` is recorded in session metadata; defaults to process.cwd().
- */
-export function jsonlSessionStore(options) {
-    const cwd = options.cwd ?? process.cwd();
-    const repo = new JsonlSessionRepo({ fs: new NodeExecutionEnv({ cwd }), sessionsRoot: options.dir });
-    return {
-        async openOrCreate(sessionId) {
-            // Caller-provided ids land in jsonl FILENAMES — encode anything unsafe before it reaches disk.
-            const id = encodeSessionId(sessionId);
-            // Scope the lookup to this store's cwd: two stores sharing a sessionsRoot must not open each
-            // other's sessions (pi groups sessions by project dir).
-            const existing = (await repo.list({ cwd })).find((m) => m.id === id);
-            if (!existing)
-                return repo.create({ id, cwd });
-            const session = await repo.open(existing);
-            await reconcileInterruptedToolCalls(session);
-            return session;
-        },
-        async openIfExists(sessionId) {
-            const id = encodeSessionId(sessionId);
-            const existing = (await repo.list({ cwd })).find((m) => m.id === id);
-            return existing ? repo.open(existing) : undefined;
-        },
-    };
-}
-/** Injective filename-safe encoding: [A-Za-z0-9._-] verbatim, the rest %-escaped. */
-function encodeSessionId(id) {
-    return id.replace(/[^A-Za-z0-9._-]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
-}

package/dist/host/node.js

@@ -1,52 +0,0 @@
-/**
- * Node host (K-axis): mount a route table of Fetch handlers on a node:http server. Post-ACK work
- * (e.g. a webhook channel's fire-and-forget turns) runs on this process's event loop and is lost on
- * shutdown (the accepted tradeoff until durable execution exists).
- */
-import { createServer } from "node:http";
-import { nodeListener } from "../channels/http.js";
-import { text } from "../channels/respond.js";
-/** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method). */
-export function parseRouteKey(key) {
-    const sp = key.indexOf(" ");
-    return sp === -1 ? { path: key } : { method: key.slice(0, sp).toUpperCase(), path: key.slice(sp + 1) };
-}
-/**
- * Compose a {@link Routes} table into one handler: exact pathname match (optionally method-qualified),
- * 405 when the path exists under another method, 404 otherwise. No params/wildcards.
- */
-export function router(routes) {
-    const entries = Object.entries(routes).map(([key, handler]) => ({
-        ...parseRouteKey(key),
-        handler,
-    }));
-    return (req) => {
-        const { pathname } = new URL(req.url);
-        const onPath = entries.filter((e) => e.path === pathname);
-        if (onPath.length === 0)
-            return text("not found\n", 404);
-        const match = onPath.find((e) => e.method === undefined || e.method === req.method);
-        if (!match)
-            return text("method not allowed\n", 405);
-        return match.handler(req);
-    };
-}
-/**
- * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller stop
- * accepting or force-close active connections — no logging/signals/exit (the CLI owns those).
- * `listening` resolves with the bound port (useful for port 0) or rejects on a bind error.
- * `host` is the bind address; unset means all interfaces (what containers need).
- */
-export function serveNode(handler, options) {
-    const server = createServer(nodeListener(async (req) => handler(req)));
-    const listening = new Promise((resolve, reject) => {
-        server.once("error", reject); // a bind failure surfaces here, before "listening"
-        server.listen({ port: options.port, host: options.host }, () => {
-            server.off("error", reject);
-            resolve(server.address().port);
-        });
-    });
-    const close = () => new Promise((resolve, reject) => server.close((e) => (e ? reject(e) : resolve())));
-    const closeAllConnections = () => server.closeAllConnections();
-    return { listening, close, closeAllConnections };
-}