@fastagent-sh/fastagent 0.21.0 → 0.22.0

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

@@ -1,36 +1,33 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Queue from "effect/Queue";
 import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
-import { toRetryScheduledEvent } from "./retry-event.js";
 import { cancellableStream } from "../../collect.js";
 import { log } from "../../log.js";
-import { EventQueue, errorToTerminal, inProcessLease, projectAgentEvent, toPiPromptOptions, toTerminal, } from "./turn-kit.js";
-/**
- * pi session events into the rich `SessionEvent` vocabulary — the SINGLE translation point. Events
- * with no vocabulary yet (agent_start, turn_start, entry_appended, …) are dropped.
- *
- * `auto_retry_start` reports as a `retry_scheduled` with `operation: "assistant"`: pi retries a
- * failed ANSWER request itself, which the summarization-only cases of that vocabulary predate.
- */
+import { toRetryScheduledEvent } from "./retry-event.js";
+import { PortFailure, port, portAbort, portCleanup, portError } from "../../effect-port.js";
+import { SessionBusy, acquireSession, acquireSessionLease } from "./session-effects.js";
+import { errorToTerminal, inProcessLease, projectAgentEvent, toPiPromptOptions, toTerminal, } from "./turn-kit.js";
 function toSessionEvent(event, runId) {
     const at = Date.now();
     switch (event.type) {
         case "message_start":
-            // Assistant streaming only — a user/toolResult message is not a live message boundary.
             if (event.message.role !== "assistant")
                 return null;
             return { type: "message_started", timestamp: at, runId, data: {} };
         case "message_update": {
-            // An empty delta is not output: it moves no consumer's state, and treating it as output would
-            // spend the silent window that auto-retry is allowed to use (see runOnSession).
             const ev = event.assistantMessageEvent;
-            if (ev.type === "text_delta") {
+            if (ev.type === "text_delta" || ev.type === "thinking_delta") {
+                // Empty deltas must not spend the silent window in which a provider retry is safe.
                 return ev.delta === ""
                     ? null
-                    : { type: "message_delta", timestamp: at, runId, data: { channel: "text", delta: ev.delta } };
-            }
-            if (ev.type === "thinking_delta") {
-                return ev.delta === ""
-                    ? null
-                    : { type: "message_delta", timestamp: at, runId, data: { channel: "thinking", delta: ev.delta } };
+                    : {
+                        type: "message_delta",
+                        timestamp: at,
+                        runId,
+                        data: { channel: ev.type === "text_delta" ? "text" : "thinking", delta: ev.delta },
+                    };
             }
             return null;
         }
@@ -64,7 +61,7 @@ function toSessionEvent(event, runId) {
                 type: "queue_changed",
                 timestamp: at,
                 runId,
-                data: { steering: event.steering.length, followUp: event.followUp.length },
+                data: { steering: [...event.steering], followUp: [...event.followUp] },
             };
         case "auto_retry_start":
         case "summarization_retry_scheduled":
@@ -73,46 +70,40 @@ function toSessionEvent(event, runId) {
             return null;
     }
 }
+/** pi's error-channel events for work an invoke owes its caller: the command it ran, and the turns it started. */
+const OWED_BY_THE_RUN = new Set(["command", "send_user_message", "send_message"]);
 /**
- * The turn's outcome. `prompt()` resolves void and never throws for an engine-side failure (measured:
- * a provider error and an abort both resolve normally), so the terminal comes from the assistant
- * message the run ended on.
- *
- * That message is taken from the EVENT STREAM, not from `session.state.messages`. Session state is
- * mutable mid-turn: compaction replaces the array, and overflow recovery splices the last assistant
- * message out of it outright (`state.messages = messages.slice(0, -1)`). Any index into it is a
- * turn boundary that the engine is free to invalidate, while a `message_end` payload is a fact that
- * already happened. Auto-compaction runs its own model call outside the agent's event stream, so it
- * cannot masquerade as the turn's answer here.
+ * The turns extensions start on this session and have not finished. `pi.sendUserMessage` and `pi.sendMessage` reach
+ * these two session methods, and pi discards the promise; wrapping the methods keeps it. The session is this run's
+ * alone, so the wrap never outlives the run.
  */
-const ENGINE_PRODUCED_NOTHING = {
-    // Unreachable on a settled run: pi ends every outcome, error and abort included, with an assistant
-    // message. Reaching it means the engine broke its own contract — name the engine, not the turn.
-    type: "failed",
-    details: "the engine settled the run without ending an assistant message",
-    retryable: false,
-};
+function trackExtensionTurns(session) {
+    const pending = new Set();
+    const track = (sent) => {
+        pending.add(sent);
+        const done = () => void pending.delete(sent);
+        sent.then(done, done); // pi's own `.catch` on `sent` reports the failure
+        return sent;
+    };
+    const sendUserMessage = session.sendUserMessage.bind(session);
+    const sendCustomMessage = session.sendCustomMessage.bind(session);
+    session.sendUserMessage = (...args) => track(sendUserMessage(...args));
+    session.sendCustomMessage = (...args) => track(sendCustomMessage(...args));
+    return pending;
+}
 export function createPiAgentFromSession(options) {
     const { sessionFactory, lease = inProcessLease(), observer } = options;
     async function* turn(scope, prompt, { onCancelReady, wasCancelled }) {
-        const release = lease.tryAcquire(scope.session);
-        if (!release) {
-            // Rejected BEFORE acceptance: no run exists, so the observer sees nothing (replay-safe).
-            yield {
-                type: "failed",
-                details: "session busy: a turn is already in flight for this session",
-                retryable: true,
-                code: SESSION_BUSY_CODE,
-            };
-            return;
-        }
-        // The run exists from here: exactly one run_started, exactly one run_settled. The settlement is
-        // emitted in the outer finally, immediately before the lease releases, so the observation
-        // plane's "running" window equals the lease window — state() must never read idle while a new
-        // invoke would still be rejected session_busy. A run with no recorded outcome was cancelled by
-        // the caller (SPEC: cancellation has no terminal event), which settles as aborted.
+        const queue = Effect.runSync(Queue.unbounded());
+        const consumed = Deferred.makeUnsafe();
+        const bound = Deferred.makeUnsafe();
+        const abort = new AbortController();
+        onCancelReady(() => abort.abort());
         const runId = crypto.randomUUID();
+        let settled = false;
         let outcome;
+        let abortsInFlight = 0;
+        let abortSucceeded = false;
         const observe = (event, run) => {
             if (!event || !observer)
                 return;
@@ -120,220 +111,194 @@ export function createPiAgentFromSession(options) {
                 observer(scope.session, event, run);
             }
             catch (error) {
-                // The observation plane must never break the data plane; a broken hub is its own problem.
                 log.warn(`[fastagent] session observer threw (event ${event.type}): ${String(error)}`);
             }
         };
-        // run_started is published BEFORE the session is built, so no early event can outrun the
-        // registration — which means the controls have to await the build rather than reject during it:
-        // a dispatch that races it simply queues on the freshly bound session. A build failure rejects
-        // the gate, so a pending dispatch learns why instead of hanging.
-        let sessionReady;
-        let sessionFailed;
-        const bound = new Promise((resolve, reject) => {
-            sessionReady = resolve;
-            sessionFailed = reject;
-        });
-        bound.catch(() => { }); // observed through the controls only when a dispatch actually happens
-        // Stale-controls guard: after settlement pi's steer()/followUp()/abort() would still resolve
-        // (they queue onto a session about to be disposed), which is a silent acceptance of a command
-        // that can never take effect. The check and the engine call share one synchronous block — pi
-        // enqueues at method entry, so a check behind its own await would only shrink the race.
-        let settled = false;
-        const settledError = () => new Error("run already settled; the command cannot take effect");
-        // Aborted classification has two sources, either sufficient: pi's own stopReason "aborted", and
-        // control-plane INTENT — providers do not uniformly attribute an aborted stream, so an abort
-        // that was still in flight when the terminal arrived counts too.
-        let abortsInFlight = 0;
-        let abortSucceeded = false;
+        const ready = Deferred.await(bound);
+        /**
+         * Every control command obeys one admission rule: wait for this run's binding, then refuse once it has settled.
+         * Kept in one place so a fourth command cannot arrive with a fifth spelling of it.
+         */
+        const command = (run) => Effect.runPromise(Effect.gen(function* () {
+            const session = yield* ready;
+            if (settled)
+                return yield* Effect.fail(new PortFailure(new Error("run already settled; the command cannot take effect")));
+            yield* run(session);
+        }));
+        // Prompt preparation stays OUTSIDE admission. An await between the settled check and the enqueue would let the run
+        // end in between, and pi accepts a message for a finished run without complaint (`_steeringMessages.push`) — the
+        // command would be dropped and still reported as success. Image resizing is exactly such an await, hundreds of
+        // milliseconds of dynamic import and Photon work, and doing it here also keeps it overlapping session acquisition.
+        const enqueue = async (p, kind) => {
+            const opts = await toPiPromptOptions(p, "queued");
+            return command((session) => port(() => session[kind](p.text, opts?.images)));
+        };
         const controls = {
-            async steer(p) {
-                const opts = await toPiPromptOptions(p);
-                const session = await bound;
-                if (settled)
-                    throw settledError();
-                await session.steer(p.text, opts?.images);
-            },
-            async followUp(p) {
-                const opts = await toPiPromptOptions(p);
-                const session = await bound;
-                if (settled)
-                    throw settledError();
-                await session.followUp(p.text, opts?.images);
-            },
-            async abort() {
-                const session = await bound;
-                if (settled)
-                    throw settledError();
+            steer: (p) => enqueue(p, "steer"),
+            followUp: (p) => enqueue(p, "followUp"),
+            abort: () => command((session) => Effect.gen(function* () {
                 abortsInFlight++;
-                try {
-                    await session.abort();
+                yield* port(() => session.abort()).pipe(Effect.tap(() => Effect.sync(() => {
                     abortSucceeded = true;
-                }
-                finally {
+                })), Effect.ensuring(Effect.sync(() => {
                     abortsInFlight--;
-                }
-            },
+                })));
+            })),
         };
-        observe({ type: "run_started", timestamp: Date.now(), runId, data: {} }, controls);
-        try {
-            let session;
-            try {
-                // The scope's lineage reaches the store's CREATE path only — an existing session opens
-                // exactly as before, whatever the scope names.
-                session = await sessionFactory(scope.session, scope.parentSession === undefined
-                    ? undefined
-                    : {
-                        parentSession: scope.parentSession,
-                        ...(scope.branchHints !== undefined ? { branchHints: scope.branchHints } : {}),
-                    });
-                sessionReady(session);
-            }
-            catch (error) {
-                // Setup failures (session open, auth, a broken definition) are EVENTS, never throws
-                // (MUST 2) — and they settle the run as failed: an unrecorded outcome means the caller
-                // cancelled, which this is not.
-                sessionFailed(error); // a pending dispatch learns the run cannot take commands
-                const terminal = errorToTerminal(error);
-                outcome = { status: "failed", error: { message: terminal.details, retryable: terminal.retryable } };
+        const execute = Effect.gen(function* () {
+            yield* acquireSessionLease(lease, scope.session);
+            yield* Effect.addFinalizer(() => Effect.sync(() => {
                 settled = true;
-                yield terminal;
-                return;
-            }
-            try {
-                const abort = () => session.abort().catch(() => { });
-                onCancelReady(() => void abort());
-                const queue = new EventQueue();
-                let finalAssistant;
-                /** Whether any of THIS attempt's answer has been streamed — the only output a retry duplicates. */
-                let streamedAnswer = false;
-                /** Set when a retry is refused because the answer already streamed — carries the ending error. */
-                let retriedAfterAnswer;
-                const unsub = session.subscribe((event) => {
-                    if (retriedAfterAnswer !== undefined)
-                        return; // decided; the retry's output is not ours
-                    if (event.type === "message_end" && event.message.role === "assistant") {
-                        finalAssistant = event.message;
-                        // Error messages and details can contain provider payloads; log only diagnostic metadata.
-                        for (const diagnostic of finalAssistant.diagnostics ?? []) {
-                            log.warn(`[fastagent] provider diagnostic ${diagnostic.type} (${finalAssistant.provider}/${finalAssistant.model}, session ${scope.session}, run ${runId})`);
-                        }
-                    }
-                    if (event.type === "compaction_end" && event.reason !== "manual") {
-                        const status = event.aborted ? "aborted" : event.errorMessage ? "failed" : "completed";
-                        const emit = event.errorMessage && !event.aborted ? log.warn : log.debug;
-                        emit(`[fastagent] automatic compaction ${event.reason} (session ${scope.session}, run ${runId}): ${status}`);
-                    }
-                    // pi retries a failed assistant request by DISCARDING that attempt's assistant message and
-                    // asking again. Everything the turn achieved before it survives — executed tools keep
-                    // their persisted results, and the retry resumes from them — so the only thing a retry can
-                    // duplicate is answer text already streamed, which SPEC deltas cannot retract. Refuse it
-                    // exactly there: refusing on tool events instead would push the retry out to the CALLER,
-                    // who can only re-run the whole prompt and execute the tool a second time.
-                    if (event.type === "auto_retry_start" && streamedAnswer) {
-                        retriedAfterAnswer = event.errorMessage;
-                        // Not synchronously: pi emits this event BEFORE creating the controller that makes its
-                        // backoff abortable, so an abort from inside the listener would find nothing to cancel
-                        // and the turn would still pay the delay and burn a provider call on a discarded answer.
-                        queueMicrotask(() => void abort());
-                        return;
-                    }
-                    const rich = toSessionEvent(event, runId);
-                    if (!rich)
-                        return;
-                    observe(rich);
-                    const projected = projectAgentEvent(rich);
-                    if (!projected)
-                        return;
-                    if (projected.type === "text" || projected.type === "thinking")
-                        streamedAnswer = true;
-                    queue.push(projected);
+                observe({ type: "run_settled", timestamp: Date.now(), runId, data: outcome ?? { status: "aborted" } });
+            }));
+            // Admission precedes binding so a racing control command waits on this run's readiness gate.
+            observe({ type: "run_started", timestamp: Date.now(), runId, data: {} }, controls);
+            const session = yield* acquireSession(sessionFactory, scope.session, scope.parentSession === undefined
+                ? undefined
+                : {
+                    parentSession: scope.parentSession,
+                    ...(scope.branchHints !== undefined ? { branchHints: scope.branchHints } : {}),
                 });
-                try {
-                    // Resolving prompt options lazy-loads the image pipeline and re-encodes every attachment,
-                    // so it both takes time and can throw before any engine work exists to fail. Hence the two
-                    // guards, in this order and no earlier: its failure is a turn failure (MUST 2), and the
-                    // latch has to be read after the LAST await before the call — the door armed above only
-                    // stops a RUNNING session, so a consumer who walked away during the build or the resize
-                    // would knock on an idle one and have the turn start anyway.
-                    let promptOptions;
-                    try {
-                        promptOptions = await toPiPromptOptions(prompt);
-                    }
-                    catch (error) {
-                        const terminal = errorToTerminal(error);
-                        outcome = { status: "failed", error: { message: terminal.details, retryable: terminal.retryable } };
-                        settled = true;
-                        yield terminal;
+            let finalAssistant;
+            let runStarted = false;
+            let extensionFailure;
+            let streamedAnswer = false;
+            let retriedAfterAnswer;
+            let eventFailure;
+            const stop = () => {
+                void Effect.runPromise(portCleanup("event-fault abort", () => session.abort()));
+            };
+            yield* Effect.acquireRelease(Effect.try({
+                try: () => session.subscribe((event) => {
+                    if (retriedAfterAnswer !== undefined || eventFailure)
                         return;
-                    }
-                    if (wasCancelled()) {
-                        settled = true;
-                        await abort();
-                        return; // cancelled: the outer finally settles it as aborted
-                    }
-                    const run = session.prompt(prompt.text, promptOptions);
-                    yield* queue.drainUntil(run);
-                    let terminal;
                     try {
-                        await run;
-                        terminal =
-                            retriedAfterAnswer !== undefined
-                                ? { type: "failed", details: retriedAfterAnswer, retryable: true }
-                                : finalAssistant
-                                    ? toTerminal(finalAssistant)
-                                    : ENGINE_PRODUCED_NOTHING;
+                        if (event.type === "agent_start")
+                            runStarted = true;
+                        // Compaction rewrites session history; the event's assistant message is the turn's fact.
+                        if (event.type === "message_end" && event.message.role === "assistant") {
+                            finalAssistant = event.message;
+                            for (const diagnostic of finalAssistant.diagnostics ?? []) {
+                                log.warn(`[fastagent] provider diagnostic ${diagnostic.type} (${finalAssistant.provider}/${finalAssistant.model}, session ${scope.session}, run ${runId})`);
+                            }
+                        }
+                        if (event.type === "compaction_end" && event.reason !== "manual") {
+                            const status = event.aborted ? "aborted" : event.errorMessage ? "failed" : "completed";
+                            const emit = event.errorMessage && !event.aborted ? log.warn : log.debug;
+                            emit(`[fastagent] automatic compaction ${event.reason} (session ${scope.session}, run ${runId}): ${status}`);
+                        }
+                        if (event.type === "auto_retry_start" && streamedAnswer) {
+                            retriedAfterAnswer = event.errorMessage;
+                            // Pi installs the retry controller after emitting this event.
+                            queueMicrotask(stop);
+                            return;
+                        }
+                        const rich = toSessionEvent(event, runId);
+                        observe(rich);
+                        if (!rich)
+                            return;
+                        const projected = projectAgentEvent(rich);
+                        if (!projected)
+                            return;
+                        if (projected.type === "text" || projected.type === "thinking")
+                            streamedAnswer = true;
+                        Queue.offerUnsafe(queue, projected);
                     }
                     catch (error) {
-                        terminal = errorToTerminal(error);
+                        eventFailure = new PortFailure(error);
+                        queueMicrotask(stop);
                     }
-                    if ((abortSucceeded || abortsInFlight > 0) && terminal.type === "failed") {
-                        terminal = { type: "failed", details: terminal.details, retryable: false, code: ABORTED_CODE };
+                }),
+                catch: (error) => new PortFailure(error),
+            }), (unsubscribe) => portCleanup("unsubscribe", unsubscribe));
+            // pi swallows a failing extension command, and a turn an extension failed to start, into its error channel;
+            // both are work this run owes its caller, so the run reports them.
+            yield* Effect.acquireRelease(Effect.sync(() => session.extensionRunner.onError((error) => {
+                if (OWED_BY_THE_RUN.has(error.event))
+                    extensionFailure ??= `${error.event} failed (${error.extensionPath}): ${error.error}`;
+            })), (unsubscribe) => Effect.sync(unsubscribe));
+            const extensionTurns = trackExtensionTurns(session);
+            // Completing the gate can run waiting controls synchronously; their queue events must be observed.
+            yield* Deferred.succeed(bound, session);
+            const promptOptions = yield* port(() => toPiPromptOptions(prompt, "prompt"));
+            if (eventFailure)
+                return yield* Effect.fail(eventFailure);
+            // Whether an extension could take this input instead of the model (a command, or an `input` handler): only
+            // then may a prompt settle with no model run and still have done its job.
+            const extensionMayTakeInput = session.extensionRunner.getRegisteredCommands().length > 0 || session.extensionRunner.hasHandlers("input");
+            yield* portAbort("prompt", async () => {
+                await session.prompt(prompt.text, promptOptions);
+                // An extension command returns from `prompt()` as soon as its handler does, and a turn it started may not
+                // have begun yet, so idleness alone proves nothing. This run owns those turns until they settle, and any
+                // turn they start in turn.
+                do {
+                    await Promise.allSettled([...extensionTurns]);
+                    await session.waitForIdle();
+                } while (extensionTurns.size > 0);
+            }, () => session.abort());
+            if (eventFailure)
+                return yield* Effect.fail(eventFailure);
+            if (extensionFailure !== undefined)
+                return { type: "failed", details: extensionFailure, retryable: false };
+            if (retriedAfterAnswer !== undefined)
+                return { type: "failed", details: retriedAfterAnswer, retryable: true };
+            if (finalAssistant)
+                return toTerminal(finalAssistant);
+            // No model run at all: an extension took the input (a command, or an `input` handler) and did its work.
+            if (!runStarted && extensionMayTakeInput)
+                return { type: "completed" };
+            return {
+                type: "failed",
+                details: "the engine settled the run without ending an assistant message",
+                retryable: false,
+            };
+        }).pipe(Effect.onError((cause) => Deferred.failCause(bound, cause)));
+        const work = Effect.runFork(Effect.scoped(Effect.gen(function* () {
+            const terminal = yield* execute.pipe(Effect.catchCause((cause) => {
+                const error = portError(cause);
+                return Effect.succeed(error instanceof SessionBusy
+                    ? {
+                        type: "failed",
+                        details: "session busy: a turn is already in flight for this session",
+                        retryable: true,
+                        code: SESSION_BUSY_CODE,
                     }
-                    if (terminal.type === "failed") {
+                    : errorToTerminal(error));
+            }));
+            settled = true;
+            Queue.offerUnsafe(queue, terminal.type === "failed" && (abortSucceeded || abortsInFlight > 0)
+                ? { ...terminal, retryable: false, code: ABORTED_CODE }
+                : terminal);
+            Queue.endUnsafe(queue);
+            // Producer completion is earlier than consumer completion.
+            yield* Deferred.await(consumed);
+        })).pipe(Effect.ensuring(Effect.sync(() => {
+            Queue.endUnsafe(queue);
+        }))), { signal: abort.signal });
+        const read = Queue.takeAll(queue).pipe(Effect.catchTag("Done", () => Effect.succeed([])));
+        try {
+            for (;;) {
+                const events = await Effect.runPromise(read);
+                if (events.length === 0)
+                    return;
+                for (const event of events) {
+                    if (wasCancelled())
+                        return;
+                    if (event.type === "failed") {
                         outcome =
-                            terminal.code === ABORTED_CODE
-                                ? // Carry the detail: an independent error that raced an accepted abort must stay
-                                    // diagnosable in the settlement, which is what audit consumers read.
-                                    { status: "aborted", error: { message: terminal.details, retryable: false } }
-                                : {
-                                    status: "failed",
-                                    error: { code: terminal.code, message: terminal.details, retryable: terminal.retryable },
-                                };
+                            event.code === ABORTED_CODE
+                                ? { status: "aborted", error: { message: event.details, retryable: false } }
+                                : { status: "failed", error: { code: event.code, message: event.details, retryable: event.retryable } };
                     }
-                    else {
+                    else if (event.type === "completed")
                         outcome = { status: "completed" };
-                    }
-                    // Commands become ineffective the moment the run resolved — not at the outer finally,
-                    // which sits behind a consumer-paced `yield`.
-                    settled = true;
-                    yield terminal;
-                }
-                finally {
-                    settled = true;
-                    unsub();
-                }
-            }
-            finally {
-                // NO session_shutdown here, deliberately. A per-invoke session makes one look right, but the
-                // extension INSTANCE it would tear down is not per-invoke: extensions belong to the agent's
-                // assembly and every turn shares one. Emitting a shutdown per turn had a finished
-                // turn clearing a timer a concurrent turn had just opened (measured, and pinned in
-                // definition-extensions.test.ts). The lifecycle has to match the instance, not the session
-                // wrapper: one agent, one instance, no per-turn teardown. Extensions that need per-turn
-                // cleanup do it in the tool or handler that opened the resource.
-                try {
-                    session.dispose();
-                }
-                catch (error) {
-                    log.warn(`[fastagent] session dispose failed during cleanup: ${String(error)}`);
+                    yield event;
                 }
             }
         }
         finally {
-            settled = true;
-            observe({ type: "run_settled", timestamp: Date.now(), runId, data: outcome ?? { status: "aborted" } });
-            release(); // after the settlement, so the next invoke for this session cannot outrun it
+            Deferred.doneUnsafe(consumed, Effect.void);
+            await Effect.runPromise(Fiber.await(work));
         }
     }
     return { invoke: (scope, prompt) => cancellableStream((hooks) => turn(scope, prompt, hooks)) };