@fastagent-sh/fastagent 0.19.0 → 0.20.0

package/dist/channels/feishu/feishu.js

@@ -15,9 +15,11 @@ import { text } from "../respond.js";
 import { createSeenRing } from "../kit/seen.js";
 import { createTaskTracker } from "../kit/tasks.js";
 import { ensureStateHome, loadStateFile, saveStateFile } from "../kit/state.js";
+import { signatureIsFresh } from "../kit/signature.js";
 import { dispatchStop, isStopText } from "../kit/stop-command.js";
 import { createTurnQueue } from "../kit/turn-queue.js";
-import { createTurnStore } from "../kit/turn-store.js";
+import { commitAnsweredTurn, createTurnStore } from "../kit/turn-store.js";
+import { discussionBlock } from "../kit/context-buffer.js";
 import { FEISHU_CLOUD } from "./cloud.js";
 import { collectFeishuBufferedAttachments, createFeishuContextBuffer, feishuBufferPlaceKey, feishuBufferText, } from "./context-buffer.js";
 import { decryptEvent, timingSafeEqualStr, verifySignature } from "./crypto.js";
@@ -31,12 +33,17 @@ import { defaultErrorMessage, mountFeishuPreview, settleFeishuPreview, streamFei
 import { connectFeishuWs } from "./ws-ingress.js";
 // Canonical public surface; the Lark subpath aliases these types/functions at its compatibility boundary.
 export { defaultFeishuRoute, feishuEnvelope };
-/** Execution ceiling: a turn that has STARTED running this many times without finishing is dropped
- *  rather than run again (a poison turn must not loop forever under a restart policy). Counted per turn
- *  at dequeue, so a never-run turn queued behind a poison one keeps its full budget. */
-const MAX_TURN_ATTEMPTS = 3;
 /** Event body cap — events are small JSON; 1 MiB is generous and guards a public endpoint. */
 const MAX_EVENT_BYTES = 1 << 20;
+/**
+ * Replay window for a SIGNED event, sized by the OPEN PLATFORM'S REDELIVERY SCHEDULE, not by Slack's
+ * 5 minutes: a failed push is retried at 15s / 5min / 1h / 6h. It is not established whether a retry
+ * is re-signed with a fresh timestamp or replays the original one, and only the second case is safe
+ * to guess wrong about in one direction — a window under 6h would 401 three of the four retries, i.e.
+ * turn one transient fault into a permanently lost user message (and a callback-health alarm). Wide
+ * enough to cover the chain, still bounded, and the `seen` ring dedups an event_id inside it.
+ */
+const MAX_SIGNATURE_AGE_S = 7 * 60 * 60;
 /** Queue feedback is immediate by default: it is the user's acknowledgement that this exact ask was
  *  accepted behind another turn. The same reply-quoted card becomes the preview/final answer, so there
  *  is no extra message or recall tombstone to avoid. Authors may still configure a delay explicitly. */
@@ -220,7 +227,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         });
         const seen = createSeenRing(join(stateHome, "seen.json"), label);
         // Side tasks (stop feedback) run off the ingress path but drain in turnsIdle.
-        const sideTasks = createTaskTracker();
+        const sideTasks = createTaskTracker(label);
         const toStored = (r) => {
             const { preview: _live, ...intent } = r; // drop the live-only field; TS enforces the rest is complete
             return { ...intent, attempts: 0 };
@@ -285,7 +292,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 await notice?.done;
                 notices.delete(rec.id);
                 // Count this execution against the durable record (poison-turn ceiling) before running it again.
-                const decision = store.startAttempt(rec.id, MAX_TURN_ATTEMPTS);
+                const decision = store.startAttempt(rec.id);
                 if (decision === "exceeded") {
                     notifyDropped(rec);
                     return;
@@ -312,8 +319,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 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}`;
+                const prompt = `${roomBlock}${discussionBlock(recent)}${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], {
@@ -331,12 +337,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                         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);
-                        buffer.commit(rec.bufferKey, consumed);
-                    }), api, targetOf(rec), formatError, rec.preview, label);
+                    }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => commitAnsweredTurn(store, buffer, { id: rec.id, bufferKey: rec.bufferKey, consumed })), api, targetOf(rec), formatError, rec.preview, label);
                     log.info(`${label} turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
                 }
                 catch (error) {
@@ -583,6 +584,12 @@ function createFeishuWebhookRoutes(profile, opts, runtime) {
     const { verificationToken, encryptKey } = opts;
     const { kind, envPrefix } = profile;
     const label = `[${kind}]`;
+    if (!encryptKey) {
+        // Said once at wiring, not per request: without an encrypt key events arrive in plaintext and
+        // carry no signature, so the freshness window below never runs and a captured body replays for
+        // as long as the verification token lives.
+        log.warn(`${label} no ${envPrefix}_ENCRYPT_KEY: events are accepted unsigned, with no replay window — set one in the console to enable it`);
+    }
     const handler = async (req) => {
         if (req.method !== "POST")
             return text("POST only\n", 405);
@@ -609,9 +616,19 @@ function createFeishuWebhookRoutes(profile, opts, runtime) {
                 nonce: req.headers.get("x-lark-request-nonce") ?? "",
                 signature: req.headers.get("x-lark-signature") ?? "",
             };
-            if (sig.signature && !verifySignature(encryptKey, sig, body.text)) {
-                log.warn(`${label} rejected an event: invalid X-Lark-Signature (encrypt key mismatch, or a forgery)`);
-                return text("invalid signature\n", 401);
+            if (sig.signature) {
+                // Freshness BEFORE the signature: the signature covers the timestamp but proves nothing about
+                // it, so without a window a captured body + its three x-lark-* headers replays forever. The
+                // `seen` ring is not that defence — it is bounded, and past its rollover a replay re-runs the
+                // turn (a re-sent message, a re-fired tool).
+                if (!signatureIsFresh(sig.timestamp, MAX_SIGNATURE_AGE_S)) {
+                    log.warn(`${label} rejected an event: X-Lark-Request-Timestamp outside the ±${MAX_SIGNATURE_AGE_S / 3600} h replay window`);
+                    return text("stale signature\n", 401);
+                }
+                if (!verifySignature(encryptKey, sig, body.text)) {
+                    log.warn(`${label} rejected an event: invalid X-Lark-Signature (encrypt key mismatch, or a forgery)`);
+                    return text("invalid signature\n", 401);
+                }
             }
             try {
                 envelope = JSON.parse(decryptEvent(encryptKey, outer.encrypt));

package/dist/channels/kit/attachment-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Attachment destination for one conversation. Never rejects an id — but the path it returns is not
+ * promised to be one the filesystem accepts: percent-encoding spends up to 9 bytes per character, so
+ * an id of ~29 CJK characters exceeds a 255-byte `NAME_MAX` and the caller's `mkdir` fails with
+ * `ENAMETOOLONG`. Left to fail there rather than truncated here: a digest suffix would buy a length
+ * no platform id approaches, at the cost of the readability this encoding exists to keep.
+ */
+export declare function attachmentPath(filesDir: string, conversationId: string | number, fileName: string): {
+    dir: string;
+    name: string;
+    path: string;
+};

package/dist/channels/kit/attachment-path.js

@@ -0,0 +1,43 @@
+/**
+ * Where an inbound attachment lands: `<filesDir>/<conversation>/<file>`.
+ *
+ * Both halves come from outside the channel, and they are NOT the same question:
+ *
+ * - The conversation is an id, and turning an arbitrary caller id into a storage name is a job this
+ *   repo already answers by ENCODING it, never by rejecting it (`piSessionId` in
+ *   engines/pi/session-store.ts, same shape: a character whitelist under a fixed prefix). An id is
+ *   the caller's — a route returning `../..` gets an odd directory, not a failed turn, because the
+ *   place to notice that id is broken is the reply it cannot deliver, not the disk.
+ * - The file name is not an id: it is read by a human and by the model, in a path this puts into the
+ *   prompt. Encoding it would cost that, so it is reduced instead — losing the odd character rather
+ *   than the readability. A leading dot survives: `.gitignore` is a name, not an escape, and nothing
+ *   lists this directory, so hiding is not a property anyone here depends on.
+ *
+ * The encoding makes containment structural rather than checked: `encodeURIComponent` emits no path
+ * separator (`/` → `%2F`, `\` → `%5C`, `:` → `%3A`), and the prefix leaves no way to spell `.`, `..`
+ * or the empty string.
+ *
+ * It is lossless for a well-formed id, so `a/b` and `a_b` are different places. Two exceptions, both
+ * outside what a platform hands over: ids differing only in malformed UTF-16 (see the substitution
+ * below), and ids differing only in case on a case-insensitive filesystem.
+ */
+import { resolve, sep } from "node:path";
+/**
+ * Attachment destination for one conversation. Never rejects an id — but the path it returns is not
+ * promised to be one the filesystem accepts: percent-encoding spends up to 9 bytes per character, so
+ * an id of ~29 CJK characters exceeds a 255-byte `NAME_MAX` and the caller's `mkdir` fails with
+ * `ENAMETOOLONG`. Left to fail there rather than truncated here: a digest suffix would buy a length
+ * no platform id approaches, at the cost of the readability this encoding exists to keep.
+ */
+export function attachmentPath(filesDir, conversationId, fileName) {
+    // A lone surrogate makes `encodeURIComponent` throw `URIError`, and this function rejecting an id
+    // is the one thing it must not do — a permanent bad id would surface as a retryable turn failure.
+    // The `u` flag matches by code point, so a valid pair (an emoji in a route's id) is left alone.
+    const id = String(conversationId).replace(/\p{Surrogate}/gu, "\uFFFD");
+    const dir = resolve(filesDir, `c-${encodeURIComponent(id)}`);
+    // The name keeps its own check because it is NOT encoded: separators go, and `resolve` settles
+    // whether what is left (`..`, a Windows `D:foo`) still lands in `dir`.
+    const cleaned = fileName.replace(/[/\\]/g, "_");
+    const name = resolve(dir, cleaned).startsWith(dir + sep) ? cleaned : "file";
+    return { dir, name, path: resolve(dir, name) };
+}

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

@@ -9,6 +9,15 @@ export declare const BUFFER_LINE_MAX_CHARS = 280;
  *  note, so the model never sees an attachment reference it silently cannot open. Shared policy:
  *  each channel's attachment collector caps against this. */
 export declare const BUFFER_ATTACH_MAX = 3;
+/**
+ * The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is
+ * empty. One renderer for every channel: what the agent is told about un-summoned discussion should
+ * not depend on which chat platform delivered it, and three copies of the literal is how that drifts.
+ *
+ * A channel that folds a SECOND source (feishu's originating room) labels that one itself — it is a
+ * different claim about a different place, not this block with another name.
+ */
+export declare function discussionBlock(text: string): string;
 export interface ContextBuffer<E> {
     /** Record an un-summoned message. Persists BEFORE returning (pre-ACK; see the module header). */
     push(placeKey: string, entry: E): void;

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

@@ -39,6 +39,17 @@ export const BUFFER_LINE_MAX_CHARS = 280;
  *  note, so the model never sees an attachment reference it silently cannot open. Shared policy:
  *  each channel's attachment collector caps against this. */
 export const BUFFER_ATTACH_MAX = 3;
+/**
+ * The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is
+ * empty. One renderer for every channel: what the agent is told about un-summoned discussion should
+ * not depend on which chat platform delivered it, and three copies of the literal is how that drifts.
+ *
+ * A channel that folds a SECOND source (feishu's originating room) labels that one itself — it is a
+ * different claim about a different place, not this block with another name.
+ */
+export function discussionBlock(text) {
+    return text ? `[recent group discussion:\n${text}\n]\n\n` : "";
+}
 export function createContextBuffer(options) {
     const { path, label, isEntry, line } = options;
     const load = () => {

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

@@ -0,0 +1,12 @@
+/**
+ * The replay window every signed webhook ingress needs. A signature covers its timestamp but proves
+ * nothing about it, so without a window a captured body plus its signed headers replays forever.
+ * The window LENGTH is the caller's: it is set by the platform's own redelivery schedule, not by us.
+ */
+/**
+ * Whether a Unix-SECONDS timestamp header is within `maxAgeS` of now, in either direction (a clock
+ * ahead of ours is as suspect as one behind). Non-numeric is not fresh: the header is part of the
+ * signed material, so a value the signature commits to but this cannot read is a reason to refuse,
+ * not to wave through.
+ */
+export declare function signatureIsFresh(timestamp: string, maxAgeS: number, nowMs?: number): boolean;

package/dist/channels/kit/signature.js

@@ -0,0 +1,17 @@
+/**
+ * The replay window every signed webhook ingress needs. A signature covers its timestamp but proves
+ * nothing about it, so without a window a captured body plus its signed headers replays forever.
+ * The window LENGTH is the caller's: it is set by the platform's own redelivery schedule, not by us.
+ */
+/**
+ * Whether a Unix-SECONDS timestamp header is within `maxAgeS` of now, in either direction (a clock
+ * ahead of ours is as suspect as one behind). Non-numeric is not fresh: the header is part of the
+ * signed material, so a value the signature commits to but this cannot read is a reason to refuse,
+ * not to wave through.
+ */
+export function signatureIsFresh(timestamp, maxAgeS, nowMs = Date.now()) {
+    if (!/^\d+$/.test(timestamp))
+        return false;
+    const seconds = Number(timestamp);
+    return Number.isSafeInteger(seconds) && Math.abs(Math.floor(nowMs / 1000) - seconds) <= maxAgeS;
+}

package/dist/channels/kit/stop-command.js

@@ -21,16 +21,16 @@ export async function dispatchStop(control, session, label) {
     if (!control)
         return STOP_UNAVAILABLE_NOTICE;
     try {
-        const result = await control.dispatch(session, { type: "abort" });
+        const result = await control.sessions.get(session).abort();
         if (result.ok)
             return STOPPED_NOTICE;
         if (result.error.code === NO_ACTIVE_RUN_CODE)
             return NOTHING_RUNNING_NOTICE;
-        log.warn(`${label} stop dispatch rejected for ${session}: ${result.error.code} — ${result.error.message}`);
+        log.warn(`${label} stop rejected for ${session}: ${result.error.code} — ${result.error.message}`);
         return `⚠️ Could not stop (${result.error.code}).`;
     }
     catch (error) {
-        log.warn(`${label} stop dispatch failed for ${session}: ${String(error)}`);
+        log.warn(`${label} stop failed for ${session}: ${String(error)}`);
         return "⚠️ Could not stop — see the server logs.";
     }
 }

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

@@ -4,4 +4,4 @@ export interface TaskTracker {
     /** Resolves when every currently-tracked task has settled. */
     drain(): Promise<void>;
 }
-export declare function createTaskTracker(): TaskTracker;
+export declare function createTaskTracker(label: string): TaskTracker;

package/dist/channels/kit/tasks.js

@@ -2,10 +2,16 @@
  * SHARED fire-and-forget side-task tracking. Channels launch work off the request path (stop
  * feedback, DM welcomes) that must not block the transport ACK but MUST be drained on shutdown
  * (`turnsIdle`) — otherwise a reply in flight when the process exits is silently dropped. Error
- * handling stays with the caller: track() only guarantees the drain sees the task settle.
+ * handling stays with the caller: track() only guarantees the drain sees the task SETTLE, and settle
+ * includes reject. A caller that handles its error on a separate branch (`p.catch(log); track(p)`)
+ * still hands us a promise that rejects, and a drain that propagated it would fail the channel's whole
+ * `turnsIdle` over one side task. A rejection that reaches us is logged — we
+ * cannot tell a missing `.catch` from one on a separate branch, so the line is a visibility floor
+ * rather than a diagnosis, and without it a dropped side task leaves no trace anywhere.
  */
 import { beginWork } from "../busy.js";
-export function createTaskTracker() {
+import { log } from "../../log.js";
+export function createTaskTracker(label) {
     const tasks = new Set();
     return {
         track(task) {
@@ -18,8 +24,8 @@ export function createTaskTracker() {
                 workDone();
                 tasks.delete(task);
             })
-                .catch(() => { }); // the caller's chain owns the error
+                .catch((error) => log.warn(`${label} side task rejected: ${String(error)}`));
         },
-        drain: () => Promise.all(tasks).then(() => undefined),
+        drain: () => Promise.allSettled(tasks).then(() => undefined),
     };
 }

package/dist/channels/kit/turn-store.d.ts

@@ -1,3 +1,4 @@
+import type { ContextBuffer } from "./context-buffer.ts";
 /** What every persisted turn record carries regardless of channel: identity, the session whose FIFO
  *  chain it runs on, and how many times it has STARTED executing without finishing (0 until its first
  *  run; bumped at each `startAttempt`). The channel's record type extends this with everything its
@@ -20,14 +21,14 @@ export interface TurnStore<T extends TurnRecordBase> {
     recover(): T[];
     /** Called when a turn is about to RUN (dequeued). Returns:
      *   - "run": bumped its persisted execution count; go ahead.
-     *   - "exceeded": over `maxAttempts` starts without finishing (killed mid-run every time, whatever the
-     *     cause); the record is dropped and the runner notifies the asker.
+     *   - "exceeded": over {@link MAX_TURN_ATTEMPTS} starts without finishing (killed mid-run every time,
+     *     whatever the cause); the record is dropped and the runner notifies the asker.
      *   - "defer": the bump could not be persisted — skip this cycle (fail closed: an unpersisted count
      *     would let a poison turn re-run forever); the record stays on disk and replays on the next start
      *     (a restart is required — disk recovery alone does not re-run it). The runner does NOT notify.
      *  An id with no record returns "run" (untracked): a completed turn's `remove` cleared it, so the
      *  redelivery-double-run tail (see the header's pre-ACK window) lands here. */
-    startAttempt(id: string, maxAttempts: number): "run" | "exceeded" | "defer";
+    startAttempt(id: string): "run" | "exceeded" | "defer";
 }
 export interface TurnStoreOptions<T extends TurnRecordBase> {
     /** Log prefix naming the consumer (e.g. "[telegram]") — the store itself is channel-neutral. */
@@ -39,4 +40,19 @@ export interface TurnStoreOptions<T extends TurnRecordBase> {
      *  (telegram: numeric update_id; lark: an explicit per-record seq). */
     order: (a: T, b: T) => number;
 }
+/**
+ * End an ANSWERED turn: drop its durable intent, then commit the discussion it folded in.
+ *
+ * The ORDER is the safety property, which is why this is a function and not two lines at each call
+ * site. A crash between the two writes may re-fold already-answered context into the next summon —
+ * additive and harmless. The reverse order leaves intent on disk with its context already consumed,
+ * so the replay runs the same turn with its context stripped.
+ *
+ * Called from the turn's `completed` event, when the fold provably lives in the durable session.
+ */
+export declare function commitAnsweredTurn<T extends TurnRecordBase, E>(store: TurnStore<T>, buffer: ContextBuffer<E>, turn: {
+    id: string;
+    bufferKey: string;
+    consumed: E[];
+}): void;
 export declare function createTurnStore<T extends TurnRecordBase>(path: string, opts: TurnStoreOptions<T>): TurnStore<T>;

package/dist/channels/kit/turn-store.js

@@ -51,6 +51,33 @@
  */
 import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "./state.js";
+/**
+ * How many times a turn may START without finishing before it is dropped rather than run again — the
+ * poison-turn ceiling described at length above. One value for every channel: it prices replay against
+ * DEPLOY frequency, which is a property of how fastagent is operated, not of which chat platform is in
+ * front of it.
+ *
+ * Known limitation: the count cannot tell a self-inflicted crash from an external SIGTERM (there is no
+ * graceful drain), so a legitimately long turn interrupted by this many successive deploys is dropped
+ * as if it were poison. Three is a bet that such a turn is an outlier, not a defence against one:
+ * catching SIGTERM to spare it would reintroduce the drain the design refuses — raise this constant
+ * instead if such turns are expected.
+ */
+const MAX_TURN_ATTEMPTS = 3;
+/**
+ * End an ANSWERED turn: drop its durable intent, then commit the discussion it folded in.
+ *
+ * The ORDER is the safety property, which is why this is a function and not two lines at each call
+ * site. A crash between the two writes may re-fold already-answered context into the next summon —
+ * additive and harmless. The reverse order leaves intent on disk with its context already consumed,
+ * so the replay runs the same turn with its context stripped.
+ *
+ * Called from the turn's `completed` event, when the fold provably lives in the durable session.
+ */
+export function commitAnsweredTurn(store, buffer, turn) {
+    store.remove(turn.id);
+    buffer.commit(turn.bufferKey, turn.consumed);
+}
 export function createTurnStore(path, opts) {
     const { label, isRecord, order } = opts;
     const load = () => {
@@ -102,12 +129,12 @@ export function createTurnStore(path, opts) {
             // happening to survive the load's JSON round-trip.
             return [...turns.values()].sort(order);
         },
-        startAttempt(id, maxAttempts) {
+        startAttempt(id) {
             const rec = turns.get(id);
             if (!rec)
                 return "run"; // no record — run untracked (a redelivery double-run whose first run removed it)
             const attempts = rec.attempts + 1;
-            if (attempts > maxAttempts) {
+            if (attempts > MAX_TURN_ATTEMPTS) {
                 // State the fact, not a cause the counter can't prove: a turn killed mid-run every time bumps
                 // this whether IT poisoned the process or a deploy/OOM took it down each time.
                 log.error(`${label} dropping turn ${id} after starting ${rec.attempts} time(s) without finishing ` +

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

@@ -2,7 +2,7 @@
 import type { Agent, AgentEvent } from "../../agent.ts";
 import { type BusyRetry } from "../kit/invoke-turn-kit.ts";
 import type { SlackBufferedFileRef } from "./context-buffer.ts";
-import type { SlackApi } from "./slack-api.ts";
+import { type SlackApi } from "./slack-api.ts";
 export interface SlackTurnTransport {
     api: SlackApi;
     channelId: string;

package/dist/channels/slack/invoke-turn.js

@@ -1,5 +1,6 @@
 import { log } from "../../log.js";
 import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../kit/invoke-turn-kit.js";
+import { SlackApiError } from "./slack-api.js";
 const MARKDOWN_INSTRUCTION = "\n\n(Format your reply as standard Markdown. Slack renders it natively. Do not use HTML or Slack control-mention syntax such as <!here>, <!channel>, or <!everyone>.)";
 async function resolveFile(transport, fileId) {
     const info = await transport.api.fileInfo(fileId);
@@ -58,7 +59,10 @@ export async function* invokeSlackTurn(agent, session, text, transport, attachme
         resolved = await resolveInputs(transport, attachments);
     }
     catch (error) {
-        yield { type: "failed", details: `could not load Slack attachment: ${String(error)}`, retryable: true };
+        // transient (network, exhausted 429 retries, Slack 5xx) is worth re-sending; an access or shape
+        // error reads the same every time, and "try again in a moment" is the wrong thing to tell the user
+        const retryable = error instanceof SlackApiError && (error.status === 0 || error.status === 429 || error.status >= 500);
+        yield { type: "failed", details: `could not load Slack attachment: ${String(error)}`, retryable };
         return;
     }
     const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };

package/dist/channels/slack/onboard.js

@@ -22,7 +22,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
         // Record BEFORE the non-idempotent API call. A transport/internal failure may have created the app;
         // refusing a blind retry is safer than silently producing duplicates.
         state = { ...state, createAttemptedAt: new Date().toISOString() };
-        await writeSlackOnboardingState(input.stateRoot, state);
+        writeSlackOnboardingState(input.stateRoot, state);
         let created;
         try {
             created = await (deps.createApp ?? createSlackApp)(current.token, manifest);
@@ -32,7 +32,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
                 ["fatal_error", "internal_error", "request_timeout", "service_unavailable", "failed_creating_app"].includes(error.code);
             if (!ambiguous) {
                 state = { ...state, createAttemptedAt: undefined };
-                await writeSlackOnboardingState(input.stateRoot, state);
+                writeSlackOnboardingState(input.stateRoot, state);
             }
             throw error;
         }
@@ -45,7 +45,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
             signingSecret: created.signingSecret,
         };
         // Irreversible boundary first: a cancellation or .env write failure can resume without creating a duplicate.
-        await writeSlackOnboardingState(input.stateRoot, state);
+        writeSlackOnboardingState(input.stateRoot, state);
         io.note(`Created Slack app ${created.appId}; credentials captured locally.`);
     }
     else {
@@ -59,7 +59,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
     if (state.signingSecret) {
         await io.writeRuntimeSecrets({ signingSecret: state.signingSecret });
         state = { ...state, signingSecret: undefined };
-        await writeSlackOnboardingState(input.stateRoot, state);
+        writeSlackOnboardingState(input.stateRoot, state);
     }
     if (!state.appId || !state.clientId || !state.clientSecret) {
         throw new Error("Slack onboarding state lost app OAuth credentials before installation");
@@ -104,7 +104,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
         teamName: oauth.teamName,
         installedAt: new Date().toISOString(),
     };
-    await writeSlackOnboardingState(input.stateRoot, state);
+    writeSlackOnboardingState(input.stateRoot, state);
     return state;
 }
 export function newSlackOnboardingState(input) {

package/dist/channels/slack/onboarding-state.d.ts

@@ -18,9 +18,13 @@ export interface SlackOnboardingState {
     teamName?: string;
     installedAt?: string;
 }
-export declare function readSlackOnboardingState(stateRoot: string): Promise<SlackOnboardingState | undefined>;
-/** Atomic replacement with owner-only permissions: this file carries a workspace-wide config refresh token. */
-export declare function writeSlackOnboardingState(stateRoot: string, state: SlackOnboardingState): Promise<void>;
+export declare function readSlackOnboardingState(stateRoot: string): SlackOnboardingState | undefined;
+/** Atomic replacement with owner-only permissions: this file carries a workspace-wide config refresh
+ *  token. Synchronous, through the shared writer, like every other piece of state this repo keeps
+ *  (kit/state.ts): the file is ~1 KB and its writers are `fastagent add slack` and one config-token
+ *  rotation at tunnel startup, so the async spelling bought nothing and cost a fifth set of temp-name
+ *  and permission rules to keep true. */
+export declare function writeSlackOnboardingState(stateRoot: string, state: SlackOnboardingState): void;
 export declare function currentSlackConfigToken(stateRoot: string, state: SlackOnboardingState, options?: {
     now?: number;
     apiBaseUrl?: string;

package/dist/channels/slack/onboarding-state.js

@@ -1,5 +1,6 @@
-import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "../../atomic-write.js";
 import { rotateSlackConfigToken } from "./config-api.js";
 function slackOnboardingStatePath(stateRoot) {
     return join(stateRoot, "channels", "slack", "onboarding.json");
@@ -15,11 +16,11 @@ function validState(value) {
         typeof state.configRefreshToken === "string" &&
         typeof state.configTokenExpiresAt === "number");
 }
-export async function readSlackOnboardingState(stateRoot) {
+export function readSlackOnboardingState(stateRoot) {
     const file = slackOnboardingStatePath(stateRoot);
     let raw;
     try {
-        raw = await readFile(file, "utf8");
+        raw = readFileSync(file, "utf8");
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -36,21 +37,13 @@ export async function readSlackOnboardingState(stateRoot) {
         throw new Error(`invalid Slack onboarding state ${file}: ${error.message}`);
     }
 }
-/** Atomic replacement with owner-only permissions: this file carries a workspace-wide config refresh token. */
-export async function writeSlackOnboardingState(stateRoot, state) {
-    const file = slackOnboardingStatePath(stateRoot);
-    await mkdir(dirname(file), { recursive: true });
-    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
-    try {
-        await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
-        await chmod(temp, 0o600);
-        await rename(temp, file);
-        await chmod(file, 0o600);
-    }
-    catch (error) {
-        await rm(temp, { force: true }).catch(() => { });
-        throw error;
-    }
+/** Atomic replacement with owner-only permissions: this file carries a workspace-wide config refresh
+ *  token. Synchronous, through the shared writer, like every other piece of state this repo keeps
+ *  (kit/state.ts): the file is ~1 KB and its writers are `fastagent add slack` and one config-token
+ *  rotation at tunnel startup, so the async spelling bought nothing and cost a fifth set of temp-name
+ *  and permission rules to keep true. */
+export function writeSlackOnboardingState(stateRoot, state) {
+    writeFileAtomic(slackOnboardingStatePath(stateRoot), `${JSON.stringify(state, null, 2)}\n`, 0o600);
 }
 export async function currentSlackConfigToken(stateRoot, state, options = {}) {
     const now = options.now ?? Date.now();
@@ -64,6 +57,6 @@ export async function currentSlackConfigToken(stateRoot, state, options = {}) {
         configTokenExpiresAt: rotated.expiresAt,
         teamId: state.teamId ?? rotated.teamId,
     };
-    await writeSlackOnboardingState(stateRoot, next);
+    writeSlackOnboardingState(stateRoot, next);
     return { token: next.configToken, state: next };
 }

package/dist/channels/slack/register-webhook.js

@@ -8,7 +8,7 @@ export async function registerSlackWebhook(baseUrl, options) {
     const publicBaseUrl = baseUrl.replace(/\/$/, "");
     let state;
     try {
-        state = await readSlackOnboardingState(options.stateRoot);
+        state = readSlackOnboardingState(options.stateRoot);
     }
     catch (error) {
         note(`[fastagent] slack: cannot read local onboarding state: ${String(error)}`);

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

@@ -71,22 +71,6 @@ async function callSlack<T extends { ok?: boolean; error?: string }>(
   }
 }
 
-function trustedUploadUrl(value: string): URL {
-  const url = new URL(value);
-  const host = url.hostname.toLowerCase();
-  const slackHost =
-    host === "slack-files.com" ||
-    host.endsWith(".slack-files.com") ||
-    host === "slack.com" ||
-    host.endsWith(".slack.com") ||
-    host === "slack-edge.com" ||
-    host.endsWith(".slack-edge.com");
-  if (url.protocol !== "https:" || !slackHost) {
-    throw new Error(`Slack returned an untrusted upload URL host: ${host}`);
-  }
-  return url;
-}
-
 export default defineTool({
   description:
     "Upload one local file to Slack (`path`), or send a message (`text`) for a turn NO channel is " +
@@ -140,7 +124,8 @@ export default defineTool({
     let byteResponse: Response;
     const handle = await open(filePath, "r");
     try {
-      byteResponse = await fetch(trustedUploadUrl(upload.upload_url), {
+      // where getUploadURLExternal points is Slack's call: these bytes are on their way to Slack either way
+      byteResponse = await fetch(upload.upload_url, {
         method: "POST",
         headers: { "content-type": "application/octet-stream" },
         body: handle.readableWebStream(),