@fastagent-sh/fastagent 0.17.1 → 0.19.0

package/dist/channels/control.js

@@ -1,9 +1,98 @@
 import { INVALID_COMMAND_CODE } from "../session.js";
 import { timingSafeEqual } from "node:crypto";
+import { parseRouteKey, withoutBody } from "./serve.js";
+import { log } from "../log.js";
 import { readBodyCapped } from "./body.js";
 import { MAX_BODY_BYTES, createInvokeHandler, sseHeartbeat } from "./http.js";
 import { text } from "./respond.js";
+/** The prefix this plane OWNS: everything under it is the plane's to answer. */
+const CONTROL_PREFIX = "/control";
 const json = (value, status = 200) => new Response(`${JSON.stringify(value)}\n`, { status, headers: { "content-type": "application/json" } });
+/**
+ * The plane as one mounted sub-application rather than routes sharing a prefix.
+ *
+ * CORS belongs to every reply that leaves the plane — including the ones no route produces (an
+ * unknown path, an unserved method, a throwing handler). As separate routes those came from the
+ * host, outside anything the plane could decorate. Owning the prefix makes them its own answers,
+ * headers applied at the single exit they share.
+ *
+ * `*` is the right origin: authorisation is the bearer token — never the origin, never a cookie —
+ * so an origin that cannot present it gets 401 either way, and a deployment cannot know the origins
+ * of the GUIs that will manage it (§14's asymmetry).
+ *
+ * `authorization` is not CORS-safelisted, so EVERY call preflights, including a plain GET.
+ * `content-type` is not either (only three values are, and `application/json` is not among them),
+ * so a browser POSTing to dispatch/invoke names it — allowing just `authorization` leaves precisely
+ * the WRITE routes unreachable while reads work.
+ */
+function planeApp(routes) {
+    // Normalised keys (see serve.ts): the method is upper-cased when parsed.
+    const byKey = new Map(Object.entries(routes).map(([key, handler]) => {
+        const { method, path } = parseRouteKey(key);
+        return [method ? `${method} ${path}` : path, handler];
+    }));
+    const methodsByPath = new Map();
+    for (const key of Object.keys(routes)) {
+        const { method, path } = parseRouteKey(key);
+        const methods = methodsByPath.get(path) ?? new Set();
+        if (method)
+            methods.add(method);
+        methodsByPath.set(path, methods);
+    }
+    // Per PATH, stating what it actually serves — omitting a method it does serve has the browser
+    // refuse a call that would have worked. `HEAD` is that case: every GET route answers it.
+    const allowMethods = (path, requested) => {
+        const methods = new Set(methodsByPath.get(path) ?? []);
+        if (methods.has("GET"))
+            methods.add("HEAD");
+        // The requested method is always allowed, even where this path does not serve it: preflight is a
+        // gate applied BEFORE the request exists, so refusing there means the real request is never sent
+        // and the client sees an opaque network error. Allowing it lets the plane's own 404/405 arrive,
+        // with these headers and an explanation.
+        if (requested)
+            methods.add(requested.toUpperCase());
+        return [...methods, "OPTIONS"].join(", ");
+    };
+    return async (req) => {
+        const path = new URL(req.url).pathname;
+        const known = methodsByPath.has(path);
+        const answer = async () => {
+            // A preflight carries no token — that is its purpose — so it is answered before auth, and for
+            // ANY path under the prefix: gating it would stop the request the 404 below is waiting for.
+            if (req.method === "OPTIONS")
+                return new Response(null, { status: 204 });
+            const handler = byKey.get(`${req.method} ${path}`) ?? byKey.get(path);
+            if (handler)
+                return await handler(req);
+            if (known && req.method === "HEAD") {
+                const get = byKey.get(`GET ${path}`);
+                if (get)
+                    return await get(req);
+            }
+            // 404 vs 405 as in the host router: a client reads 404 as "this serve predates the route".
+            if (known)
+                return text("method not allowed\n", 405);
+            return text("not found\n", 404);
+        };
+        let res;
+        try {
+            // HEAD carries no content, whichever branch answered — including this plane's own 404/405.
+            const answered = await answer();
+            res = req.method === "HEAD" ? withoutBody(answered) : answered;
+        }
+        catch (error) {
+            // The plane's own totality boundary: a rejecting handler (`commands()` on an unreadable
+            // definition) must still answer with the headers; the message stays internal.
+            log.error(`[control] ${req.method} ${path} failed: ${String(error)}`);
+            res = text("internal error\n", 500);
+        }
+        // THE single exit. Every reply above — route, preflight, 404, 405, 500 — leaves through here.
+        res.headers.set("access-control-allow-origin", "*");
+        res.headers.set("access-control-allow-headers", "authorization, content-type");
+        res.headers.set("access-control-allow-methods", allowMethods(path, req.headers.get("access-control-request-method")));
+        return res;
+    };
+}
 // ONE constant for every Prompt-bearing wire surface (imported from the invoke channel — the two
 // caps cannot drift apart): commands carry Prompts, which may ride base64 images.
 const DISPATCH_BODY_LIMIT = MAX_BODY_BYTES;
@@ -84,13 +173,26 @@ function parseWireCommand(raw) {
     }
 }
 /**
- * Mount the control plane: `GET /control/capabilities|commands|state|entries|events` + `POST
- * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ * Create the control plane as a mountable prefix owner: `GET
+ * /control/capabilities|commands|state|entries|events` + `POST /control/dispatch`, all
+ * bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
+ * The plane OWNS {@link CONTROL_PREFIX}: it is mounted as one sub-application, answers its own
+ * 404/405/preflight, and puts CORS headers on every reply — see {@link planeApp}.
  */
-export function controlRoutes(control, options) {
+export function createControlPlane(control, options) {
+    return mountControlPlane(controlPlaneRoutes(control, options));
+}
+/** Mount a plane route table as a {@link PrefixMount} — the plane owns a PREFIX, while a route
+ *  table is a set of literal paths. */
+export function mountControlPlane(routes) {
+    return { prefix: CONTROL_PREFIX, handler: planeApp(routes) };
+}
+/** The plane's route table. Exported so the conformance sweeps derive their route list from what is
+ *  actually mounted, rather than from a hand-kept copy that cannot notice a new route. */
+export function controlPlaneRoutes(control, options) {
     const { token } = options;
     if (!token)
-        throw new Error("controlRoutes: a bearer token is required (empty tokens are not a mode)");
+        throw new Error("createControlPlane: a bearer token is required (empty tokens are not a mode)");
     const epoch = crypto.randomUUID();
     // Timing-safe: the bearer token is this surface's ONLY auth (and the --tunnel warning names it
     // as the sole protection on a public URL) — a plain === would leak byte-by-byte via timing.

package/dist/{engines/pi/channel.d.ts → channels/discover.d.ts}

@@ -1,5 +1,5 @@
-import { type ChannelContext, type LongConnection, type Routes } from "../../host/node.ts";
-import { type ModuleLoadFailure } from "../../loader.ts";
+import type { ChannelContext, LongConnection, Routes } from "../channel.ts";
+import { type ModuleLoadFailure } from "../loader.ts";
 /** A dropped route: two channels claim the same key. Surfaced, never silent. */
 export interface ChannelCollision {
     route: string;

package/dist/{engines/pi/channel.js → channels/discover.js}

@@ -1,12 +1,15 @@
 /**
  * Channel discovery (the N axis, filesystem form). A channel file default-exports either the existing
  * route factory `(ctx) => Routes`, or an explicit long-connection module `{ name, connect(ctx, signal) }`.
+ *
+ * Engine-neutral, and living here rather than under `engines/` because of it: reading `channels/*.ts`
+ * is the Channel contract plus a directory, with no engine in sight.
  */
 import { readdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
-import { parseRouteKey, } from "../../host/node.js";
-import { isModuleFile, loadModuleDir } from "../../loader.js";
-import { assertInsideAgentDir } from "../../paths.js";
+import { assertRouteKey, routeKeysConflict } from "./serve.js";
+import { isModuleFile, loadModuleDir } from "../loader.js";
+import { assertInsideAgentDir } from "../paths.js";
 function longConnectionModule(value) {
     return value !== null && typeof value === "object" && typeof value.connect === "function";
 }
@@ -79,9 +82,7 @@ function validateRoutes(value, label) {
         if (typeof handler !== "function") {
             throw new Error(`${label}: route "${route}" must map to a handler function, got ${typeof handler}`);
         }
-        if (!parseRouteKey(route).path.startsWith("/")) {
-            throw new Error(`${label}: route "${route}" is not a valid route key (expected "METHOD /path" or "/path")`);
-        }
+        assertRouteKey(route, (problem) => `${label}: route "${route}" is not a valid route key — ${problem}`);
     }
     return routes;
 }
@@ -121,12 +122,7 @@ export async function loadChannels(dir, ctx) {
             }
             const declaredRoutes = validateRoutes(declared, label);
             for (const [route, handler] of declaredRoutes) {
-                const parsed = parseRouteKey(route);
-                const clash = Object.keys(routes).some((key) => {
-                    const existing = parseRouteKey(key);
-                    return (existing.path === parsed.path &&
-                        (existing.method === undefined || parsed.method === undefined || existing.method === parsed.method));
-                });
+                const clash = Object.keys(routes).some((key) => routeKeysConflict(key, route));
                 if (clash) {
                     collisions.push({ route, source: label });
                     continue;

package/dist/channels/feishu/card.js

@@ -17,7 +17,7 @@
  * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
  * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
  */
-import { truncateCodePointPrefix } from "../text.js";
+import { truncateCodePointPrefix } from "../kit/text.js";
 /** The append-only answer element's id — shared by create (card.ts) and update (preview.ts). */
 export const ANSWER_ELEMENT_ID = "answer";
 /** The volatile process element's id (thinking tail + tool lines + retry notice; live-only). */

package/dist/channels/feishu/context-buffer.d.ts

@@ -1,4 +1,4 @@
-import { type ContextBuffer } from "../context-buffer.ts";
+import { type ContextBuffer } from "../kit/context-buffer.ts";
 import type { NormalizedFeishuMessage } from "./model.ts";
 export interface FeishuBufferedResource {
     messageId: string;

package/dist/channels/feishu/context-buffer.js

@@ -1,13 +1,13 @@
 /**
  * Feishu/Lark's half of the shared context buffer (mechanics + consume protocol:
- * ../context-buffer.ts): the entry shape, its fold-line rendering, place-key derivation, and
+ * ../kit/context-buffer.ts): the entry shape, its fold-line rendering, place-key derivation, and
  * buffered-resource selection. Entries are bucketed by conversation place (main chat, or one
  * concrete thread root) and folded into the next answered turn in that place.
  */
 import { log } from "../../log.js";
-import { BUFFER_ATTACH_MAX, BUFFER_LINE_MAX_CHARS, createContextBuffer as createGenericContextBuffer, } from "../context-buffer.js";
-import { loadStateFile, saveStateFile } from "../state.js";
-import { truncateCodePointPrefix } from "../text.js";
+import { BUFFER_ATTACH_MAX, BUFFER_LINE_MAX_CHARS, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
+import { loadStateFile, saveStateFile } from "../kit/state.js";
+import { truncateCodePointPrefix } from "../kit/text.js";
 function bufferLine(entry) {
     const meta = [`msg ${entry.messageId}`, entry.replyTo ? `reply to msg ${entry.replyTo}` : undefined]
         .filter(Boolean)

package/dist/channels/feishu/feishu-api.d.ts

@@ -69,11 +69,13 @@ export interface FeishuApi {
      *
      *  `sender` is typed rather than `unknown` because the referent path READS it: an app-sent message
      *  whose id is THIS app's is the agent's own, which the prompt must say instead of attributing it to
-     *  "user cli_…". The message object carries more (`parent_id`, `root_id`, `thread_id`); they stay
-     *  unnamed until something reads them — this type is the surface in use, not a mirror of the wire. */
+     *  "user cli_…". `parent_id` is read by the reply-chain walk (invoke-turn): the message this one
+     *  itself replied to. The message object carries more (`root_id`, `thread_id`); they stay unnamed
+     *  until something reads them — this type is the surface in use, not a mirror of the wire. */
     getMessage(messageId: string): Promise<{
         message_id?: string;
         msg_type?: string;
+        parent_id?: string;
         body?: {
             content?: string;
         };

package/dist/channels/feishu/feishu-api.js

@@ -21,7 +21,7 @@
  */
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { utf8Prefix } from "../text.js";
+import { utf8Prefix } from "../kit/text.js";
 /** Per-attempt timeout for a JSON API call — small JSON round-trips, so 30s is generous. */
 const API_TIMEOUT_MS = 30_000;
 /** Timeout for downloading resource bytes — sized for a slow link, not a JSON call. */

package/dist/channels/feishu/feishu.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelModule, LongConnectionChannelModule } from "../../host/node.ts";
+import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
 import { type FeishuCloudProfile } from "./cloud.ts";
 import { type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, defaultFeishuRoute, feishuEnvelope } from "./parse.ts";
 import { type FeishuFailure } from "./preview.ts";

package/dist/channels/feishu/feishu.js

@@ -12,19 +12,19 @@ import { isAbsolute, join } from "node:path";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
-import { createSeenRing } from "../seen.js";
-import { createTaskTracker } from "../tasks.js";
-import { ensureStateHome, loadStateFile, removeRetiredStateFile, saveStateFile } from "../state.js";
-import { dispatchStop, isStopText } from "../stop-command.js";
-import { createTurnQueue } from "../turn-queue.js";
-import { createTurnStore } from "../turn-store.js";
+import { createSeenRing } from "../kit/seen.js";
+import { createTaskTracker } from "../kit/tasks.js";
+import { ensureStateHome, loadStateFile, saveStateFile } from "../kit/state.js";
+import { dispatchStop, isStopText } from "../kit/stop-command.js";
+import { createTurnQueue } from "../kit/turn-queue.js";
+import { createTurnStore } from "../kit/turn-store.js";
 import { FEISHU_CLOUD } from "./cloud.js";
 import { collectFeishuBufferedAttachments, createFeishuContextBuffer, feishuBufferPlaceKey, feishuBufferText, } from "./context-buffer.js";
 import { decryptEvent, timingSafeEqualStr, verifySignature } from "./crypto.js";
 import { invokeFeishuTurn } from "./invoke-turn.js";
 import { createFeishuApi } from "./feishu-api.js";
 import { normalizeFeishuMessage } from "./normalize.js";
-import { createThreadParticipants } from "../thread-participants.js";
+import { createThreadParticipants } from "../kit/thread-participants.js";
 import { FEISHU_GROUP_CONTEXT_SCOPE, FEISHU_MESSAGE_READ_REQUEST, FEISHU_MESSAGE_READ_SCOPE, scopeSatisfied, } from "./setup-mode.js";
 import { cloudEnvelope, defaultFeishuRoute, feishuEnvelope, placeKey, senderId, senderLabel, } from "./parse.js";
 import { defaultErrorMessage, mountFeishuPreview, settleFeishuPreview, streamFeishuReply, } from "./preview.js";
@@ -58,6 +58,8 @@ function isStoredFeishuTurn(t) {
         (r.queueReplyTo === undefined || typeof r.queueReplyTo === "string") &&
         (r.replyInThread === undefined || typeof r.replyInThread === "boolean") &&
         (r.parentId === undefined || typeof r.parentId === "string") &&
+        (r.parentSession === undefined || typeof r.parentSession === "string") &&
+        (r.roomBufferKey === undefined || typeof r.roomBufferKey === "string") &&
         refs(r.images) &&
         refs(r.files) &&
         typeof r.attempts === "number");
@@ -160,10 +162,6 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         }
         const stateHome = join(stateRoot, "channels", kind);
         ensureStateHome(stateHome); // buffers/files may carry chat content; the agent .gitignore covers .state/
-        // The participant model replaced the owned-thread index (a cache, so nothing is lost). REMOVE THIS
-        // after the release following the participant model ships — by then no live deployment can still
-        // be carrying the file. test/migration-deadline.test.ts fails when due.
-        removeRetiredStateFile(stateHome, "owned-threads.json", label);
         // The cached bot identity (rationale at the botInfo block above): seed synchronously — the
         // factory runs to completion before any promise resolves, so botOpenId is still unset here and
         // the seed is what the first envelope's dispatch sees. Refresh keeps the file current.
@@ -309,13 +307,31 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 // this snapshot before either commits it. That fan-out loses nothing; claiming by buffer key
                 // would instead couple otherwise-independent root sessions and require failure rollback.
                 const { text: recent, consumed } = buffer.peek(rec.bufferKey);
-                const prompt = recent ? `[recent group discussion:\n${recent}\n]\n\n${rec.baseText}` : rec.baseText;
-                const buffered = collectFeishuBufferedAttachments(consumed, {
+                // PEEK and never commit: the room still owes this discussion to its OWN memory (§8).
+                const room = rec.roomBufferKey !== undefined ? buffer.peek(rec.roomBufferKey) : undefined;
+                const roomBlock = room?.text
+                    ? `[recent discussion in the room this thread branched from — not yet answered there:\n${room.text}\n]\n\n`
+                    : "";
+                const threadBlock = recent ? `[recent group discussion:\n${recent}\n]\n\n` : "";
+                const prompt = `${roomBlock}${threadBlock}${rec.baseText}`;
+                // Room entries FIRST: the collector keeps the TAIL under its cap, so the thread's own
+                // attachments win the slots.
+                const buffered = collectFeishuBufferedAttachments([...(room?.consumed ?? []), ...consumed], {
                     images: rec.images.map((ref) => ({ messageId: ref.msg, key: ref.key })),
                     files: rec.files.map((ref) => ({ messageId: ref.msg, key: ref.key, name: ref.name })),
                 });
+                // Recorded at ingress (see submit) — never re-derived from the session key, which may be a
+                // routed OPAQUE id that only looks like a place key.
+                const parentSession = rec.parentSession;
                 try {
-                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, { api, chatId: rec.chatId, filesDir: join(stateHome, "files"), label, appId }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
+                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, {
+                        api,
+                        chatId: rec.chatId,
+                        filesDir: join(stateHome, "files"),
+                        label,
+                        appId,
+                        ...(parentSession !== undefined ? { parentSession } : {}),
+                    }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
                         // Drop intent first: a crash between these writes may re-fold answered context later,
                         // but can never replay this turn after its context was removed.
                         store.remove(rec.id);
@@ -465,7 +481,19 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             // Memory follows the place (participant model §5): one session per chat, and one per thread.
             // Keyed by `thread_id`, never `root_id` — the platform's root_id tracks the reply chain and can
             // differ between messages of ONE thread, which would split a side conversation in two.
-            const session = r.session ?? placeKey(kind, m);
+            const routed = r.session;
+            const session = routed ?? placeKey(kind, m);
+            // Lineage is recorded ONLY for the default place-derived session. A routed session id is
+            // OPAQUE (the route contract), and re-parsing it as a place key would let a three-segment id
+            // like "tenant:user:alice" masquerade as a thread and inherit from "tenant:user" — a
+            // cross-session injection. Derived from the MESSAGE (the fact this channel owns), at record
+            // time, where routed-ness is still known; the dequeue path only reads it back.
+            const parentSession = routed === undefined && m.thread_id !== undefined ? placeKey(kind, { chat_id: m.chat_id }) : undefined;
+            // Read BEFORE this turn records its own participation below, or it is always true. Keyed by the
+            // SOURCE chat, never the answer target a route may name (§8).
+            const roomBufferKey = parentSession !== undefined && !threadParticipants.agentSpokeIn(session)
+                ? feishuBufferPlaceKey({ chatId: m.chat_id })
+                : undefined;
             const chatId = r.chatId ?? m.chat_id;
             const sameTarget = chatId === m.chat_id;
             // Answer where asked (§4): quote in a group so the ask is identifiable among many speakers,
@@ -517,6 +545,8 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 // already have; it also pins WHICH message is being answered, which a long thread benefits
                 // from anyway.
                 parentId: m.parent_id,
+                ...(parentSession !== undefined ? { parentSession } : {}),
+                ...(roomBufferKey !== undefined ? { roomBufferKey } : {}),
                 images,
                 files,
             }, true);

package/dist/channels/feishu/invoke-turn.d.ts

@@ -8,11 +8,12 @@
  *
  * Inputs have two tiers. PRIMARY is the summoning message plus the message it explicitly replied to;
  * any load failure there aborts visibly so the Agent never runs without an input the user pointed at.
- * BUFFERED resources come from earlier un-summoned thread/group discussion and degrade per attachment:
- * one expired background file must not block the current ask or hide its still-readable siblings.
+ * BUFFERED resources come from earlier un-summoned thread/group discussion and from reply-chain
+ * ancestors, and degrade per attachment: one expired background file must not block the current ask
+ * or hide its still-readable siblings.
  */
 import type { Agent, AgentEvent } from "../../agent.ts";
-import { type BusyRetry } from "../invoke-turn-kit.ts";
+import { type BusyRetry } from "../kit/invoke-turn-kit.ts";
 import type { FeishuBufferedRef } from "./context-buffer.ts";
 import type { FeishuApi } from "./feishu-api.ts";
 /** Everything the transport needs to fetch a turn's attachments. */
@@ -25,6 +26,11 @@ export interface FeishuTurnTransport {
      *  sender is an app. Needed to tell the agent's OWN messages from any other bot's in the same chat:
      *  `sender_type` alone says "some app", which is not the question the referent path asks. */
     appId: string;
+    /** The place this thread branched from (the chat's main place), when the turn runs in a thread —
+     *  rides the Scope's lineage extension so a NEW thread session starts from what the room knew
+     *  (participant-model.md §5). The engine reads it once, at session creation; every later turn
+     *  carries it inertly. */
+    parentSession?: string;
 }
 /** An attachment reference: the resource key inside its CARRYING message (the resource API addresses
  *  bytes by message_id + key, so the pair travels together through the turn record). */