@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/channels/feishu/scaffold/feishu-send.ts

@@ -1,37 +1,42 @@
-import { defineTool, z } from "@fastagent-sh/fastagent";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-durable";
+import { needs } from "@fastagent-sh/fastagent";
 import { feishuTransport } from "@fastagent-sh/fastagent/feishu";
 
 // Proactive delivery uses the mounted channel's credentials, gateway and token cache. With no
-// channel mounted (fire/invoke/tool), it reads FEISHU_APP_ID / FEISHU_APP_SECRET from the environment.
-
-export default defineTool({
-  description:
-    "Send a message to a Feishu chat, OUTSIDE the normal reply path. Call it only for a turn NO " +
-    "channel is carrying — a scheduled or self-scheduled (wake) turn, whose plain reply goes " +
-    "nowhere — or to reach a chat OTHER than the one you are answering. In a normal chat turn the " +
-    "channel streams and delivers your reply itself, so do NOT call this to answer the current " +
-    "chat: it would post the message twice, outside the conversation thread. `chatId` (oc_…) names " +
-    "the DESTINATION and must come from your instructions (the asking message, the schedule prompt, " +
-    "or memory); the [feishu: chat …] context line only identifies the chat you are answering — the " +
-    "one chat this tool must not target in a chat turn. Pass exactly ONE of `text` (plain) or " +
-    "`markdown` (rendered as a card: headings, bold, code blocks, links).",
-  input: z.object({
-    chatId: z.string().describe("target chat id (oc_…)"),
-    text: z.string().optional().describe("plain text message to send"),
-    markdown: z.string().optional().describe("markdown to send as a card"),
+// channel mounted, it signs in with FEISHU_APP_ID / FEISHU_APP_SECRET itself.
+export default needs(["FEISHU_APP_ID", "FEISHU_APP_SECRET"], (secrets) =>
+  defineTool({
+    name: "feishu_send",
+    description:
+      "Send a message to a Feishu chat, OUTSIDE the normal reply path. Call it only for a message NO " +
+      "channel is carrying (a scheduled or self-scheduled one, whose plain reply goes " +
+      "nowhere) or to reach a chat OTHER than the one you are answering. In a normal chat turn the " +
+      "channel streams and delivers your reply itself, so do NOT call this to answer the current " +
+      "chat: it would post the message twice, outside the conversation thread. `chatId` (oc_…) names " +
+      "the DESTINATION and must come from your instructions (the asking message, the schedule prompt, " +
+      "or memory); the [feishu: chat …] context line only identifies the chat you are answering, the " +
+      "one chat this tool must not target in a chat turn. Pass exactly ONE of `text` (plain) or " +
+      "`markdown` (rendered as a card: headings, bold, code blocks, links).",
+    parameters: Type.Object({
+      chatId: Type.String({ description: "target chat id (oc_…)" }),
+      text: Type.Optional(Type.String({ description: "plain text message to send" })),
+      markdown: Type.Optional(Type.String({ description: "markdown to send as a card" })),
+    }),
+    execute: async ({ chatId, text, markdown }) => {
+      if ((text === undefined) === (markdown === undefined)) {
+        throw new Error("pass exactly one of `text` (plain) or `markdown` (a card)");
+      }
+      const api = feishuTransport({ appId: secrets.FEISHU_APP_ID, appSecret: secrets.FEISHU_APP_SECRET });
+      if (text !== undefined) await api.sendText({ chatId }, text);
+      else {
+        await api.sendMessage(
+          chatId,
+          "interactive",
+          JSON.stringify({ schema: "2.0", body: { elements: [{ tag: "markdown", content: markdown }] } }),
+        );
+      }
+      return { output: [{ type: "text", text: `sent ${text !== undefined ? "message" : "card"} to chat ${chatId}` }] };
+    },
   }),
-  async execute({ chatId, text, markdown }, ctx) {
-    if ((text === undefined) === (markdown === undefined)) {
-      throw new Error("pass exactly one of `text` (plain) or `markdown` (a card)");
-    }
-    const api = feishuTransport(ctx.cwd);
-    if (text !== undefined) await api.sendText({ chatId }, text);
-    else {
-      await api.sendMessage(chatId, "interactive", JSON.stringify({
-        schema: "2.0",
-        body: { elements: [{ tag: "markdown", content: markdown }] },
-      }));
-    }
-    return `sent ${text !== undefined ? "message" : "card"} to chat ${chatId}`;
-  },
-});
+);

package/dist/channels/feishu/scaffold/feishu-threads.ts

@@ -0,0 +1,25 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-durable";
+import { sessionIdOf } from "@fastagent-sh/fastagent";
+import { feishuThreads } from "@fastagent-sh/fastagent/feishu";
+
+// Reads the threads (topics) of the Feishu group chat this message was asked in, and no other chat's:
+// the channel names where the message runs, so the tool takes no chat id. It works in a group turn
+// served by `fastagent dev`/`start`.
+export default defineTool({
+  name: "feishu_threads",
+  description:
+    "Read the threads (topics) of the Feishu group chat you are answering in. Without `threadId`, list its recent " +
+    "threads, newest first, each with its id; with a `threadId` from that list, read that thread. Use " +
+    "it when a question here concerns something discussed in a thread, such as whether a problem raised there was " +
+    "resolved: the answer is often what a person wrote in the thread. Only this chat's threads can be read, and " +
+    "only in a group chat turn.",
+  parameters: Type.Object({
+    threadId: Type.Optional(Type.String({ description: "a thread id from the list (omt_…); omit it to list" })),
+  }),
+  execute: async ({ threadId }, api, context) => {
+    const threads = feishuThreads(await sessionIdOf(api, context));
+    const text = threadId === undefined ? await threads.list() : await threads.read(threadId);
+    return { output: [{ type: "text", text }] };
+  },
+});

package/dist/channels/feishu/setup-mode.d.ts

@@ -1,19 +1,54 @@
-/** Feishu/Lark app-level event subscription choice used by onboarding and scaffolding. */
+import { type FeishuCloudKind } from "./cloud.ts";
+/** Feishu/Lark app-level event subscription choice: how a channel receives, and what an app is set up for. */
 export type FeishuSubscriptionMode = "webhook" | "websocket";
-/** Onboarding choice for group visibility. */
-export type FeishuGroupBehavior = "context" | "mentions";
+/** The settings {@link feishuIngressFor} reads, one per cloud: what `deploy` must read the way the box will. */
+export declare const FEISHU_INGRESS_SETTINGS: string[];
 /**
- * Configuring THIS app: what every v7 config PATCH needs — registering a webhook Request URL, and adding a scope to
- * the app draft during context-aware group setup.
+ * How THIS process receives a Feishu/Lark channel (docs/design/channel-environments.md): `<PREFIX>_INGRESS` when the
+ * environment names one, else WebSocket under `dev` (no public URL, no reviewed scope) and webhook everywhere else,
+ * which is what every deployment runs. The channel file asks at import, and so does every reader of its shape: `deploy`
+ * inspects it in a process that is not `dev`, with the same value file loaded, so it sees what the box will serve.
+ */
+export declare function feishuIngressFor(kind: FeishuCloudKind, env?: NodeJS.ProcessEnv): FeishuSubscriptionMode;
+/**
+ * Configuring THIS app through the v7 config API: registering a webhook Request URL and switching the subscription
+ * mode. Requested for a webhook app only. A tenant may review it, and a scope under review holds the app's whole first
+ * version in review, so a WebSocket app, which never uses it, would wait on an admin for nothing (measured: the same
+ * creation without it came back active).
  */
 export declare const FEISHU_APP_CONFIG_SCOPE = "application:application:patch";
 /** The one event an agent app cannot serve without: an inbound message. */
 export declare const FEISHU_MESSAGE_RECEIVE_EVENT = "im.message.receive_v1";
+/** A scope the onboarding asks for, plus any BROADER spelling that already satisfies it. */
+export interface FeishuScopeRequest {
+    /** What to request when nothing satisfies it. */
+    request: string;
+    /** EXTRA spellings that also count — supersets. */
+    supersets?: string[];
+    /** What the agent loses without it, for the warning that names it. */
+    withoutIt: string;
+}
+/** Whether `predicate` holds for any spelling that satisfies this request. */
+export declare function scopeSatisfied(entry: FeishuScopeRequest, predicate: (name: string) => boolean): boolean;
+/**
+ * What an agent may know about the rooms it is in, on top of the platform's agent template. There is one posture: the
+ * agent takes part in its rooms like a colleague (participant-model.md), so every app gets all of it, requested at
+ * creation in the one round a tenant may want to approve. What a scope is for is the agent's, not only the channel's:
+ * the agent can call the Open API with the app's credentials. A scope belongs here only once something uses it:
+ * `im:message.group_msg.include_bot:read` (other bots' group messages) is an event-delivery scope. The channel reads
+ * other bots' messages from a chat's history, which does not need it (measured), and drops every non-user event.
+ */
+export declare const FEISHU_AGENT_SCOPES: FeishuScopeRequest[];
+/**
+ * Every scope an app of this ingress needs: what onboarding requests at creation AND what it checks the app holds, so a
+ * scope the app is asked for is one whose absence is reported.
+ */
+export declare function feishuAppScopes(ingress: FeishuSubscriptionMode): FeishuScopeRequest[];
 /**
- * What a created app carries on top of the platform's agent template, for EITHER ingress — the `addons` merged onto
- * the confirm page.
+ * What a created app carries on top of the platform's agent template — the `addons` merged onto the confirm page. A
+ * scope that arrives here needs no console visit; one a tenant withholds is reported after creation (`add-feishu.ts`).
  */
-export declare function feishuAppAddons(): {
+export declare function feishuAppAddons(ingress: FeishuSubscriptionMode): {
     scopes: {
         tenant: string[];
     };
@@ -23,20 +58,5 @@ export declare function feishuAppAddons(): {
         };
     };
 };
-/** The sensitive tenant scope behind both bare replies in the agent's threads and group context buffering. */
-export declare const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";
-/** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8). */
-export declare const FEISHU_MESSAGE_READ_SCOPE = "im:message:readonly";
-/** A scope the onboarding asks for, plus any BROADER spelling that already satisfies it. */
-export interface FeishuScopeRequest {
-    /** What to add to the app draft when nothing satisfies it. */
-    request: string;
-    /** EXTRA spellings that also count — supersets. */
-    supersets?: string[];
-}
-/** Whether `predicate` holds for any spelling that satisfies this request. */
-export declare function scopeSatisfied(entry: FeishuScopeRequest, predicate: (name: string) => boolean): boolean;
-/** Reading a quoted message: `im:message` is the read/write superset, so an app holding it can already do so. */
-export declare const FEISHU_MESSAGE_READ_REQUEST: FeishuScopeRequest;
-/** What `--group-behavior context` REQUESTS in one approval round — not a dependency set. */
-export declare const FEISHU_CONTEXT_ONBOARDING_SCOPES: FeishuScopeRequest[];
+/** The console page that requests `scopes` for this app, pre-filled: the platform's own link for a missing scope. */
+export declare function feishuScopeRequestUrl(apiBase: string, appId: string, scopes: readonly string[]): string;

package/dist/channels/feishu/setup-mode.js

@@ -1,35 +1,86 @@
+import { servedByDev } from "../../serving-command.js";
+import { cloudFor } from "./cloud.js";
+/** The settings {@link feishuIngressFor} reads, one per cloud: what `deploy` must read the way the box will. */
+export const FEISHU_INGRESS_SETTINGS = ["feishu", "lark"].map((kind) => `${cloudFor(kind).envPrefix}_INGRESS`);
 /**
- * Configuring THIS app: what every v7 config PATCH needs — registering a webhook Request URL, and adding a scope to
- * the app draft during context-aware group setup.
+ * How THIS process receives a Feishu/Lark channel (docs/design/channel-environments.md): `<PREFIX>_INGRESS` when the
+ * environment names one, else WebSocket under `dev` (no public URL, no reviewed scope) and webhook everywhere else,
+ * which is what every deployment runs. The channel file asks at import, and so does every reader of its shape: `deploy`
+ * inspects it in a process that is not `dev`, with the same value file loaded, so it sees what the box will serve.
+ */
+export function feishuIngressFor(kind, env = process.env) {
+    const name = `${cloudFor(kind).envPrefix}_INGRESS`;
+    const raw = env[name]?.trim();
+    if (!raw)
+        return servedByDev(env) ? "websocket" : "webhook";
+    if (raw !== "webhook" && raw !== "websocket") {
+        throw new Error(`${name} must be "webhook" or "websocket", got "${raw}"`);
+    }
+    return raw;
+}
+/**
+ * Configuring THIS app through the v7 config API: registering a webhook Request URL and switching the subscription
+ * mode. Requested for a webhook app only. A tenant may review it, and a scope under review holds the app's whole first
+ * version in review, so a WebSocket app, which never uses it, would wait on an admin for nothing (measured: the same
+ * creation without it came back active).
  */
 export const FEISHU_APP_CONFIG_SCOPE = "application:application:patch";
 /** The one event an agent app cannot serve without: an inbound message. */
 export const FEISHU_MESSAGE_RECEIVE_EVENT = "im.message.receive_v1";
+/** Whether `predicate` holds for any spelling that satisfies this request. */
+export function scopeSatisfied(entry, predicate) {
+    return [entry.request, ...(entry.supersets ?? [])].some(predicate);
+}
 /**
- * What a created app carries on top of the platform's agent template, for EITHER ingress — the `addons` merged onto
- * the confirm page.
+ * What an agent may know about the rooms it is in, on top of the platform's agent template. There is one posture: the
+ * agent takes part in its rooms like a colleague (participant-model.md), so every app gets all of it, requested at
+ * creation in the one round a tenant may want to approve. What a scope is for is the agent's, not only the channel's:
+ * the agent can call the Open API with the app's credentials. A scope belongs here only once something uses it:
+ * `im:message.group_msg.include_bot:read` (other bots' group messages) is an event-delivery scope. The channel reads
+ * other bots' messages from a chat's history, which does not need it (measured), and drops every non-user event.
  */
-export function feishuAppAddons() {
+export const FEISHU_AGENT_SCOPES = [
+    {
+        request: "im:message.group_msg", // sensitive: some tenants approve it by hand
+        withoutIt: "only @mentions arrive: no bare replies in the agent's threads, no group discussion as context",
+    },
+    {
+        request: "im:message:readonly",
+        supersets: ["im:message"], // the read/write superset
+        withoutIt: "the discussion before an ask cannot be read (the prompt says so), and a quoted message degrades to a marker",
+    },
+    {
+        request: "im:chat.members:read",
+        withoutIt: "people in the discussion the agent reads are shown by open_id, not by name",
+    },
+];
+/** The config scope as an app needs it: webhook only ({@link FEISHU_APP_CONFIG_SCOPE}). */
+const FEISHU_APP_CONFIG_REQUEST = {
+    request: FEISHU_APP_CONFIG_SCOPE,
+    withoutIt: "the Verification Token is not captured and no Request URL is registered for you (add, dev --tunnel, deploy --run)",
+};
+/**
+ * Every scope an app of this ingress needs: what onboarding requests at creation AND what it checks the app holds, so a
+ * scope the app is asked for is one whose absence is reported.
+ */
+export function feishuAppScopes(ingress) {
+    return [...(ingress === "webhook" ? [FEISHU_APP_CONFIG_REQUEST] : []), ...FEISHU_AGENT_SCOPES];
+}
+/**
+ * What a created app carries on top of the platform's agent template — the `addons` merged onto the confirm page. A
+ * scope that arrives here needs no console visit; one a tenant withholds is reported after creation (`add-feishu.ts`).
+ */
+export function feishuAppAddons(ingress) {
     return {
-        scopes: { tenant: [FEISHU_APP_CONFIG_SCOPE] },
+        scopes: { tenant: feishuAppScopes(ingress).map((entry) => entry.request) },
         events: { items: { tenant: [FEISHU_MESSAGE_RECEIVE_EVENT] } },
     };
 }
-/** The sensitive tenant scope behind both bare replies in the agent's threads and group context buffering. */
-export const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";
-/** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8). */
-export const FEISHU_MESSAGE_READ_SCOPE = "im:message:readonly";
-/** Whether `predicate` holds for any spelling that satisfies this request. */
-export function scopeSatisfied(entry, predicate) {
-    return [entry.request, ...(entry.supersets ?? [])].some(predicate);
+/** The console page that requests `scopes` for this app, pre-filled: the platform's own link for a missing scope. */
+export function feishuScopeRequestUrl(apiBase, appId, scopes) {
+    const url = new URL(`${apiBase}/app/${encodeURIComponent(appId)}/auth`);
+    url.searchParams.set("q", scopes.join(","));
+    url.searchParams.set("op_from", "openapi");
+    url.searchParams.set("token_type", "tenant");
+    return url.toString();
 }
-/** Reading a quoted message: `im:message` is the read/write superset, so an app holding it can already do so. */
-export const FEISHU_MESSAGE_READ_REQUEST = {
-    request: FEISHU_MESSAGE_READ_SCOPE,
-    supersets: ["im:message"],
-};
-/** What `--group-behavior context` REQUESTS in one approval round — not a dependency set. */
-export const FEISHU_CONTEXT_ONBOARDING_SCOPES = [
-    { request: FEISHU_GROUP_CONTEXT_SCOPE },
-    FEISHU_MESSAGE_READ_REQUEST,
-];

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

@@ -1,10 +1,28 @@
+/**
+ * The mounted channel and proactive tools share credentials, token cache, gateway and retry policy: one transport per
+ * app a process holds, found by the app id both hold.
+ */
+import { roomThreads } from "../kit/room-threads.ts";
 import { type FeishuCloudKind } from "./cloud.ts";
 import { type FeishuApi } from "./feishu-api.ts";
 /** The delivery methods a proactive sender needs. */
 export type FeishuTransport = Pick<FeishuApi, "sendText" | "sendMessage">;
-/** A remount replaces the transport; separate clouds can share one agent state root. */
-export declare function registerFeishuApi(stateRoot: string, kind: FeishuCloudKind, api: FeishuApi): void;
-/** Resolve the Feishu transport for a tool's workspace (`ctx.cwd`). */
-export declare function feishuTransport(cwd: string): FeishuTransport;
-/** Resolve the Lark transport for a tool's workspace (`ctx.cwd`). */
-export declare function larkTransport(cwd: string): FeishuTransport;
+/** The app a transport signs in as. */
+export interface FeishuAppCredentials {
+    appId: string;
+    appSecret: string;
+}
+/** A remount replaces the transport: the channel's is the authoritative one for its app. */
+export declare function registerFeishuApi(appId: string, kind: FeishuCloudKind, api: FeishuApi): void;
+/** The Feishu transport of an app: its mounted channel's, or the app's own when none is mounted. */
+export declare function feishuTransport(app: FeishuAppCredentials): FeishuTransport;
+/** The Lark transport of an app: its mounted channel's, or the app's own when none is mounted. */
+export declare function larkTransport(app: FeishuAppCredentials): FeishuTransport;
+/**
+ * The threads of the group chat the message running in `sessionId` was asked in, and only those
+ * (`kit/room-threads.ts`): `list()` its recent threads, `read(threadId)` one of them. Throws outside a Feishu group
+ * turn served by this process.
+ */
+export declare function feishuThreads(sessionId: string | undefined): ReturnType<typeof roomThreads>;
+/** {@link feishuThreads}, for a Lark group turn. */
+export declare function larkThreads(sessionId: string | undefined): ReturnType<typeof roomThreads>;

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

@@ -1,38 +1,44 @@
-/** The mounted channel and proactive tools share credentials, token cache, gateway and retry policy. */
-import { findAgentDir, resolveStateRoot } from "../../paths.js";
+/**
+ * The mounted channel and proactive tools share credentials, token cache, gateway and retry policy: one transport per
+ * app a process holds, found by the app id both hold.
+ */
+import { roomThreads } from "../kit/room-threads.js";
 import { cloudFor } from "./cloud.js";
 import { createFeishuApi } from "./feishu-api.js";
 const byKind = {
     feishu: new Map(),
     lark: new Map(),
 };
-/** A remount replaces the transport; separate clouds can share one agent state root. */
-export function registerFeishuApi(stateRoot, kind, api) {
-    byKind[kind].set(stateRoot, api);
+/** A remount replaces the transport: the channel's is the authoritative one for its app. */
+export function registerFeishuApi(appId, kind, api) {
+    byKind[kind].set(appId, api);
 }
-function cloudTransport(cwd, kind) {
-    // Embedded senders may use a bare definition directory or an independent workspace.
-    const stateRoot = resolveStateRoot(findAgentDir(cwd) ?? cwd);
+function cloudTransport({ appId, appSecret }, kind) {
     const transports = byKind[kind];
-    let api = transports.get(stateRoot);
+    let api = transports.get(appId);
     if (!api) {
-        // fire/invoke/tool do not mount channels, so their credentials come from the agent's environment.
-        const { apiBase, envPrefix } = cloudFor(kind);
-        const appId = process.env[`${envPrefix}_APP_ID`];
-        const appSecret = process.env[`${envPrefix}_APP_SECRET`];
-        if (!appId || !appSecret) {
-            throw new Error(`${envPrefix}_APP_ID / ${envPrefix}_APP_SECRET are not set and no ${kind} channel is mounted`);
-        }
-        api = createFeishuApi({ kind, baseUrl: apiBase, appId, appSecret });
-        transports.set(stateRoot, api);
+        api = createFeishuApi({ kind, baseUrl: cloudFor(kind).apiBase, appId, appSecret });
+        transports.set(appId, api);
     }
     return api;
 }
-/** Resolve the Feishu transport for a tool's workspace (`ctx.cwd`). */
-export function feishuTransport(cwd) {
-    return cloudTransport(cwd, "feishu");
+/** The Feishu transport of an app: its mounted channel's, or the app's own when none is mounted. */
+export function feishuTransport(app) {
+    return cloudTransport(app, "feishu");
 }
-/** Resolve the Lark transport for a tool's workspace (`ctx.cwd`). */
-export function larkTransport(cwd) {
-    return cloudTransport(cwd, "lark");
+/** The Lark transport of an app: its mounted channel's, or the app's own when none is mounted. */
+export function larkTransport(app) {
+    return cloudTransport(app, "lark");
+}
+/**
+ * The threads of the group chat the message running in `sessionId` was asked in, and only those
+ * (`kit/room-threads.ts`): `list()` its recent threads, `read(threadId)` one of them. Throws outside a Feishu group
+ * turn served by this process.
+ */
+export function feishuThreads(sessionId) {
+    return roomThreads("feishu", sessionId);
+}
+/** {@link feishuThreads}, for a Lark group turn. */
+export function larkThreads(sessionId) {
+    return roomThreads("lark", sessionId);
 }

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

@@ -1,3 +1,9 @@
+import type { DiscussionSource } from "./place-history.ts";
+/**
+ * Char budget for the per-place buffer — bounds the cost of folding it into a prompt; when exceeded the OLDEST
+ * un-summoned messages are dropped. Not a time window: a quiet group keeps its sparse-but-relevant lines.
+ */
+export declare const BUFFER_MAX_CHARS = 4000;
 /** Per-message bound INSIDE that budget. */
 export declare const BUFFER_LINE_MAX_CHARS = 280;
 /** How many buffered files and images (each, most recent first) a summon pulls in with the folded discussion. */
@@ -10,9 +16,12 @@ export declare function capBufferedRefs<R>(refs: R[]): {
     kept: R[];
     skipped: number;
 };
-/** The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is empty. */
+/**
+ * The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is empty. "Here", not
+ * "group": a direct chat's buffer holds what the agent sent there itself.
+ */
 export declare function discussionBlock(text: string): string;
-export interface ContextBuffer<E> {
+export interface ContextBuffer<E> extends DiscussionSource<E> {
     /** Record an un-summoned message. */
     push(placeKey: string, entry: E): void;
     /** Render the fold text and snapshot the consumed entries (see the module header's consume protocol). */

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

@@ -14,12 +14,12 @@
  * never flowing in as trusted data.
  */
 import { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "./state.js";
+import { loadStateFile, saveStateFile } from "../../state-file.js";
 /**
  * Char budget for the per-place buffer — bounds the cost of folding it into a prompt; when exceeded the OLDEST
  * un-summoned messages are dropped. Not a time window: a quiet group keeps its sparse-but-relevant lines.
  */
-const BUFFER_MAX_CHARS = 4000;
+export const BUFFER_MAX_CHARS = 4000;
 /** Per-message bound INSIDE that budget. */
 export const BUFFER_LINE_MAX_CHARS = 280;
 /** How many buffered files and images (each, most recent first) a summon pulls in with the folded discussion. */
@@ -31,9 +31,12 @@ export const BUFFER_ATTACH_MAX = 3;
 export function capBufferedRefs(refs) {
     return { kept: refs.slice(-BUFFER_ATTACH_MAX), skipped: Math.max(0, refs.length - BUFFER_ATTACH_MAX) };
 }
-/** The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is empty. */
+/**
+ * The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is empty. "Here", not
+ * "group": a direct chat's buffer holds what the agent sent there itself.
+ */
 export function discussionBlock(text) {
-    return text ? `[recent group discussion:\n${text}\n]\n\n` : "";
+    return text ? `[recent discussion here:\n${text}\n]\n\n` : "";
 }
 export function createContextBuffer(options) {
     const { path, label, isEntry, line } = options;

package/dist/channels/kit/delivery.d.ts

@@ -1,13 +1,29 @@
 import * as Effect from "effect/Effect";
 import type * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
-import type { AgentEvent } from "../../agent.ts";
+import type { TurnEvent } from "./invoke-turn-kit.ts";
 import type { ChannelFailure } from "./preview-kit.ts";
 import { PortFailure } from "../../effect-port.ts";
+/** How a turn ended: answered, or the failure to tell the asker about. */
+export type TurnEnd = {
+    answered: true;
+} | {
+    failure: ChannelFailure;
+};
+/**
+ * Whether this event ends the turn, and how: the message was refused, or the turn's message ended. A message the
+ * agent stopped answering at its output limit still answers with what was written.
+ */
+export declare function turnEnd(event: TurnEvent, messageId: string | undefined): TurnEnd | undefined;
+/**
+ * A turn whose stream ended before its message did, after the agent said why (`stream_error`: the message's end could
+ * not be recorded, or missed events could not be read back): a failure worth trying again. Undefined when nothing was said.
+ */
+export declare function unfinishedTurn(streamError: string | undefined): ChannelFailure | undefined;
 /** Snapshot/edit renderers share terminal ownership; platform-specific settle policies stay injected. */
-export declare function renderReply(events: Stream.Stream<AgentEvent, PortFailure>, opts: {
+export declare function renderReply(events: Stream.Stream<TurnEvent, PortFailure>, opts: {
     label: string;
-    onEvent: (event: AgentEvent) => void;
+    onEvent: (event: TurnEvent) => void;
     finish: Effect.Effect<void>;
     answer: () => string;
     settle: (text: string) => Effect.Effect<void, PortFailure>;

package/dist/channels/kit/delivery.js

@@ -6,7 +6,44 @@ import * as Fiber from "effect/Fiber";
 import * as Queue from "effect/Queue";
 import * as Stream from "effect/Stream";
 import { log } from "../../log.js";
-import { PortFailure, portJoin } from "../../effect-port.js";
+import { PortFailure, portError, portJoin } from "../../effect-port.js";
+/**
+ * Whether this event ends the turn, and how: the message was refused, or the turn's message ended. A message the
+ * agent stopped answering at its output limit still answers with what was written.
+ */
+export function turnEnd(event, messageId) {
+    if (event.type === "rejected") {
+        const { code, message, retryable } = event.error;
+        return { failure: { details: message, retryable, code } };
+    }
+    if (event.type !== "done" || event.message.id !== messageId)
+        return undefined;
+    const { status, error } = event.message;
+    switch (status) {
+        case "completed":
+        case "incomplete":
+            return { answered: true };
+        case "failed":
+            return {
+                failure: {
+                    details: error?.message ?? "the message failed",
+                    retryable: error?.retryable ?? false,
+                    code: error?.code ?? "failed",
+                },
+            };
+        case "canceled":
+            return { failure: { details: "the message was canceled", retryable: false, code: "canceled" } };
+        default:
+            return undefined;
+    }
+}
+/**
+ * A turn whose stream ended before its message did, after the agent said why (`stream_error`: the message's end could
+ * not be recorded, or missed events could not be read back): a failure worth trying again. Undefined when nothing was said.
+ */
+export function unfinishedTurn(streamError) {
+    return streamError === undefined ? undefined : { details: streamError, retryable: true, code: "stream_error" };
+}
 /** Snapshot/edit renderers share terminal ownership; platform-specific settle policies stay injected. */
 export function renderReply(events, opts) {
     return Effect.gen(function* () {
@@ -17,8 +54,19 @@ export function renderReply(events, opts) {
             if (!finalized)
                 yield* notify({ details: "the turn ended without completing", retryable: false }, "abnormal-turn");
         }));
+        let messageId;
+        let streamError;
+        const failWith = (failure) => Effect.gen(function* () {
+            yield* notify(failure, "agent-failure");
+            return yield* Effect.fail(new PortFailure(new Error(`agent failed: ${failure.details} (retryable=${failure.retryable})`)));
+        });
         yield* Stream.runForEachWhile(events, (event) => {
-            if (event.type !== "completed" && event.type !== "failed") {
+            if (event.type === "message")
+                messageId = event.message.id;
+            if (event.type === "stream_error")
+                streamError = event.error.message;
+            const end = turnEnd(event, messageId);
+            if (end === undefined) {
                 return Effect.try({
                     try: () => {
                         opts.onEvent(event);
@@ -30,7 +78,7 @@ export function renderReply(events, opts) {
             return Effect.gen(function* () {
                 yield* opts.finish;
                 finalized = true;
-                if (event.type === "completed") {
+                if ("answered" in end) {
                     const answer = opts.answer();
                     yield* Effect.try({
                         try: () => opts.onAnswered?.(answer),
@@ -39,18 +87,20 @@ export function renderReply(events, opts) {
                     yield* opts.settle(answer);
                 }
                 else {
-                    yield* notify({
-                        details: event.details,
-                        retryable: event.retryable,
-                        ...(event.code !== undefined ? { code: event.code } : {}),
-                    }, "agent-failure");
-                    return yield* Effect.fail(new PortFailure(new Error(`agent failed: ${event.details} (retryable=${event.retryable})`)));
+                    return yield* failWith(end.failure);
                 }
                 return false;
             }).pipe(Effect.uninterruptible);
         });
-        if (!finalized)
-            yield* Effect.fail(new PortFailure(new Error("stream ended without a terminal event")));
+        if (finalized)
+            return;
+        const unfinished = unfinishedTurn(streamError);
+        if (unfinished === undefined) {
+            return yield* Effect.fail(new PortFailure(new Error("stream ended without a terminal event")));
+        }
+        yield* opts.finish;
+        finalized = true;
+        yield* failWith(unfinished).pipe(Effect.uninterruptible);
     });
 }
 export function previewPump(opts) {
@@ -113,11 +163,20 @@ export function serialWriter() {
             }
         }).pipe(Effect.catchTag("Done", () => Effect.void));
         const fiber = yield* Effect.forkScoped(work);
-        const finish = Effect.sync(() => {
+        const end = Effect.sync(() => {
             Queue.endUnsafe(queue);
-        }).pipe(Effect.andThen(Fiber.join(fiber)));
-        // This finalizer precedes forkScoped's interruption: accepted append/status writes must drain.
-        yield* Effect.addFinalizer(() => finish.pipe(Effect.orDie));
+        });
+        let reported = false;
+        const finish = end.pipe(Effect.andThen(Fiber.join(fiber)), Effect.onExit((exit) => Effect.sync(() => {
+            if (!Exit.hasInterrupts(exit))
+                reported = true;
+        })));
+        // This finalizer precedes forkScoped's interruption: accepted append/status writes must drain. It must not fail:
+        // a defect makes the scope's typed failure one too, and a `catchTag` downstream misses it. So a write failure no
+        // `finish` reported is said in the log.
+        yield* Effect.addFinalizer(() => end.pipe(Effect.andThen(Fiber.await(fiber)), Effect.flatMap((exit) => Exit.isFailure(exit) && !reported && !Cause.hasInterruptsOnly(exit.cause)
+            ? Effect.sync(() => log.error(`[delivery] a write failed after its turn stopped: ${String(portError(exit.cause))}`))
+            : Effect.void)));
         return {
             enqueue: (next) => {
                 if (!Queue.offerUnsafe(queue, next))