@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/channels/slack/model.d.ts

@@ -1,4 +1,4 @@
-/** Minimal Slack Events/Web API shapes used by the first-party channel. Unknown fields remain ignored. */
+/** Minimal Slack Events/Web API shapes used by the first-party channel. */
 export interface SlackFile {
     id?: string;
     name?: string;
@@ -57,7 +57,6 @@ export interface SlackEventEnvelope {
         is_bot?: boolean;
     }>;
 }
-/** A routed Slack turn. `threadTs:null` explicitly sends at channel top level. */
 export interface SlackRoute {
     session?: string;
     channelId?: string;

package/dist/channels/slack/model.js

@@ -1,2 +1,2 @@
-/** Minimal Slack Events/Web API shapes used by the first-party channel. Unknown fields remain ignored. */
+/** Minimal Slack Events/Web API shapes used by the first-party channel. */
 export {};

package/dist/channels/slack/onboard.d.ts

@@ -4,14 +4,13 @@ import { type SlackOnboardingState } from "./onboarding-state.ts";
 export interface SlackOnboardIO {
     note(message: string): void;
     openUrl(url: string): void;
-    /** Wait for the one OAuth redirect. Implementations must validate only the path; core validates state. */
+    /** Wait for the one OAuth redirect. */
     waitForOAuth(): Promise<{
         code?: string;
         state?: string;
         error?: string;
     }>;
-    /** Stage the runtime secrets into the gitignored .env — the bot token and the signing secret, nothing
-     *  else: the client credentials are setup-only (the OAuth code exchange) and stay in onboarding state. */
+    /** Stage the runtime secrets into the gitignored .env. */
     writeRuntimeSecrets(values: {
         botToken?: string;
         signingSecret?: string;
@@ -37,5 +36,7 @@ export declare function newSlackOnboardingState(input: {
     groupBehavior: SlackGroupBehavior;
     configToken: string;
     configRefreshToken: string;
+    /** When the pair was captured; pass it through rather than re-deriving the same expiry twice. */
+    configTokenExpiresAt?: number;
     now?: number;
 }): SlackOnboardingState;

package/dist/channels/slack/onboard.js

@@ -2,14 +2,16 @@ import { randomBytes } from "node:crypto";
 import { retryWhile } from "../registration.js";
 import { createSlackApp, exchangeSlackOAuthCode, isSlackRequestUrlUnverified, isSlackRotationLocked, SLACK_ROTATING_APP_UPGRADE, SlackConfigApiError, updateSlackAppManifest, } from "./config-api.js";
 import { buildSlackManifest, slackBotScopes } from "./manifest.js";
-import { currentSlackConfigToken, writeSlackOnboardingState } from "./onboarding-state.js";
+import { configTokenExpiry, currentSlackConfigToken, writeSlackOnboardingState, } from "./onboarding-state.js";
 /** Create/resume one internal Slack app and complete its workspace OAuth installation. */
 export async function onboardSlackApp(input, io, deps = {}) {
     let state = input.state;
     const current = await currentSlackConfigToken(input.stateRoot, state);
     state = current.state;
-    /** Slack challenges request_url from ITS network during a manifest call and validates the whole
-     *  manifest before acting, so an unverifiable URL created nothing and the call is safe to repeat. */
+    /**
+     * Slack challenges request_url from ITS network during a manifest call and validates the whole manifest before
+     * acting, so an unverifiable URL created nothing and the call is safe to repeat.
+     */
     const whileUnverified = (call, onRetry) => retryWhile(call, isSlackRequestUrlUnverified, {
         attempts: deps.attempts,
         retryMs: deps.retryMs,
@@ -37,10 +39,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
         let created;
         try {
             created = await whileUnverified(() => {
-                // 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. The marker spans
-                // exactly one in-flight call: an unverifiable URL created nothing, so it comes off again before
-                // the wait — a Ctrl-C during that wait must not wedge the next run on an app that never existed.
+                // Record BEFORE the non-idempotent API call.
                 setMarker(new Date().toISOString());
                 return (deps.createApp ?? createSlackApp)(current.token, manifest);
             }, () => setMarker(undefined));
@@ -95,8 +94,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
     authorize.searchParams.set("scope", slackBotScopes(state.groupBehavior).join(","));
     authorize.searchParams.set("redirect_uri", input.redirectUrl);
     authorize.searchParams.set("state", oauthState);
-    // The redirect lands on the tunnel hostname, which THIS machine may not resolve yet (#421) — a broken
-    // page beside a terminal that looks hung, unless the reload is named before it happens.
+    // The redirect lands on the tunnel hostname, which THIS machine may not resolve yet (#421).
     io.note(`Click Allow in Slack to install the app: ${authorize}\nIf the page it returns to does not load, reload it.`);
     io.openUrl(authorize.toString());
     const callback = await io.waitForOAuth();
@@ -135,7 +133,6 @@ export function newSlackOnboardingState(input) {
         groupBehavior: input.groupBehavior,
         configToken: input.configToken,
         configRefreshToken: input.configRefreshToken,
-        // Slack config access tokens expire in 12 hours; use 11h so registration rotates before the edge.
-        configTokenExpiresAt: (input.now ?? Date.now()) + 11 * 60 * 60_000,
+        configTokenExpiresAt: input.configTokenExpiresAt ?? configTokenExpiry(input.now),
     };
 }

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

@@ -1,4 +1,6 @@
 import type { SlackGroupBehavior } from "./manifest.ts";
+/** When a token pair captured `now` stops being usable — the ONE place that answers it. */
+export declare function configTokenExpiry(now?: number): number;
 export interface SlackOnboardingState {
     version: 1;
     appName: string;
@@ -19,11 +21,7 @@ export interface SlackOnboardingState {
     installedAt?: string;
 }
 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. */
+/** Atomic replacement with owner-only permissions: this file carries a workspace-wide config refresh token. */
 export declare function writeSlackOnboardingState(stateRoot: string, state: SlackOnboardingState): void;
 export declare function currentSlackConfigToken(stateRoot: string, state: SlackOnboardingState, options?: {
     now?: number;

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

@@ -1,7 +1,14 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeFileAtomic } from "../../atomic-write.js";
+import { SECRET_FILE_MODE } from "../../paths.js";
 import { rotateSlackConfigToken } from "./config-api.js";
+/** Slack config access tokens expire in 12 hours; use 11h so registration rotates before the edge. */
+const CONFIG_TOKEN_TTL_MS = 11 * 60 * 60_000;
+/** When a token pair captured `now` stops being usable — the ONE place that answers it. */
+export function configTokenExpiry(now = Date.now()) {
+    return now + CONFIG_TOKEN_TTL_MS;
+}
 function slackOnboardingStatePath(stateRoot) {
     return join(stateRoot, "channels", "slack", "onboarding.json");
 }
@@ -37,13 +44,9 @@ export 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. 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. */
+/** Atomic replacement with owner-only permissions: this file carries a workspace-wide config refresh token. */
 export function writeSlackOnboardingState(stateRoot, state) {
-    writeFileAtomic(slackOnboardingStatePath(stateRoot), `${JSON.stringify(state, null, 2)}\n`, 0o600);
+    writeFileAtomic(slackOnboardingStatePath(stateRoot), `${JSON.stringify(state, null, 2)}\n`, SECRET_FILE_MODE);
 }
 export async function currentSlackConfigToken(stateRoot, state, options = {}) {
     const now = options.now ?? Date.now();

package/dist/channels/slack/parse.d.ts

@@ -1,11 +1,9 @@
 import type { SlackEventEnvelope, SlackMessageEvent, SlackRoute } from "./model.ts";
 export type { SlackEventEnvelope, SlackFile, SlackMessageEvent, SlackRoute } from "./model.ts";
-/** Does this text address ANYONE — a user, a broadcast, or a user group? The §3 discussion guard. */
+/** Does this text address ANYONE — a user, a broadcast, or a user group? */
 export declare function hasSlackMention(text: string): boolean;
-/** Does this text mention a USER? Distinct from the above because only a user mention can be the bot:
- *  a broadcast never is, so it must not make a message look like a possible summon. */
 export declare function hasSlackUserMention(text: string): boolean;
-/** Does this text mention this specific user (either form)? The id is MATCHED, not interpreted. */
+/** Does this text mention this specific user (either form)? */
 export declare function mentionsSlackUser(text: string, userId: string): boolean;
 /** Strip every mention, e.g. before matching a bare command word or building a title. */
 export declare function stripSlackMentions(text: string, replacement?: string): string;
@@ -17,22 +15,15 @@ export declare function isSlackHumanMessage(event: SlackMessageEvent | undefined
 };
 export declare function isSlackDirectMessage(event: SlackMessageEvent): boolean;
 export declare function isSlackGroupMessage(event: SlackMessageEvent): boolean;
-/** Stable install identity. Events API normally supplies team_id; the fallbacks cover Grid envelopes. */
+/** Stable install identity. */
 export declare function slackTeamId(envelope: SlackEventEnvelope): string | undefined;
 export declare function slackFileIds(event: SlackMessageEvent): string[];
 /** Text plus a structural marker for file-only or captioned file shares. */
 export declare function slackMessageText(event: SlackMessageEvent): string;
 export declare function slackSenderLabel(event: SlackMessageEvent): string;
-/** Main-channel discussion and each concrete thread are independent context buckets.
- *
- *  The `:root:` segment carries `thread_ts`, which in Slack IS the thread's parent message and is
- *  stable for the life of the thread — unrelated to the `<chat>:root:<root_id>` shape Feishu retired
- *  (its `root_id` moves with the reply chain, so it could not identify a side conversation at all).
- *  Same token, different platform meaning; the key is left as-is because renaming it would discard
- *  live context buckets for no semantic gain. */
+/** Main-channel discussion and each concrete thread are independent context buckets. */
 export declare function slackPlaceKey(teamId: string, event: Pick<SlackMessageEvent, "channel" | "thread_ts">): string;
 export declare function slackBufferText(text: string): string;
-/** Canonical prompt envelope. The channel/thread ids also give slack-send an explicit delivery target. */
 export declare function slackEnvelope(envelope: SlackEventEnvelope): string;
 /** Default explicit-summon policy: DMs and app_mention events only. */
 export declare function defaultSlackRoute(envelope: SlackEventEnvelope): SlackRoute | null;

package/dist/channels/slack/parse.js

@@ -1,35 +1,21 @@
 import { BUFFER_LINE_MAX_CHARS } from "../kit/context-buffer.js";
 import { codePointPrefix, truncateCodePointPrefix } from "../kit/text.js";
 const HUMAN_MESSAGE_SUBTYPES = new Set(["file_share", "thread_broadcast"]);
-/**
- * Both forms Slack writes a mention in: `<@U123>` and the labelled `<@U123|name>`. ONE definition,
- * because the forms have to agree across every site that reads them — the "@-mentions only other
- * people is discussion" guard, the structural bot-summon check, the stop-command strip, and the
- * assistant-thread title. They drifted once: widening the first two while the strip still matched only
- * the bare form turned `<@bot|name> stop` into an ordinary turn, queued behind the run it meant to stop.
- */
+/** Both forms Slack writes a mention in: `<@U123>` and the labelled `<@U123|name>`. */
 const mentionSource = (idPattern) => String.raw `<@${idPattern}(?:\|[^>]*)?>`;
 const USER_MENTION = mentionSource("[A-Z0-9]+");
-/** Broadcasts and user groups address people too: `<!here>`, `<!channel>`, `<!everyone>`,
- *  `<!subteam^S123|@team>`. Feishu's twin guard counts every mention, and the summon rule is supposed
- *  to be the same on both — without these, "@here can someone look at this" in a thread the agent takes
- *  part in reads as a bare message addressed to IT, and gets answered. */
+/** Broadcasts and user groups address people too: `<!here>`, `<!channel>`, `<!everyone>`, `<!subteam^S123|@team>`. */
 const ANY_MENTION = String.raw `(?:${USER_MENTION}|<!(?:here|channel|everyone)(?:\|[^>]*)?>|<!subteam\^[^>]*>)`;
-/** Does this text address ANYONE — a user, a broadcast, or a user group? The §3 discussion guard. */
+/** Does this text address ANYONE — a user, a broadcast, or a user group? */
 export function hasSlackMention(text) {
     return new RegExp(ANY_MENTION, "i").test(text);
 }
-/** Does this text mention a USER? Distinct from the above because only a user mention can be the bot:
- *  a broadcast never is, so it must not make a message look like a possible summon. */
 export function hasSlackUserMention(text) {
     return new RegExp(USER_MENTION, "i").test(text);
 }
-/** Escape a platform-supplied id before it becomes part of a pattern. Slack ids are alphanumeric in
- *  practice, but `auth.test`'s value is not validated here, and this runs on every group message: an
- *  unescaped metacharacter would either mis-answer the summon question or throw on the acceptance
- *  path, which Slack answers with an endless redelivery. */
+/** Escape a platform-supplied id before it becomes part of a pattern. */
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-/** Does this text mention this specific user (either form)? The id is MATCHED, not interpreted. */
+/** Does this text mention this specific user (either form)? */
 export function mentionsSlackUser(text, userId) {
     return new RegExp(mentionSource(escapeRegExp(userId)), "i").test(text);
 }
@@ -51,7 +37,7 @@ export function isSlackDirectMessage(event) {
 export function isSlackGroupMessage(event) {
     return !isSlackDirectMessage(event) && (event.type === "app_mention" || event.channel_type !== undefined);
 }
-/** Stable install identity. Events API normally supplies team_id; the fallbacks cover Grid envelopes. */
+/** Stable install identity. */
 export function slackTeamId(envelope) {
     return (envelope.team_id ??
         envelope.event?.team ??
@@ -75,13 +61,7 @@ export function slackMessageText(event) {
 export function slackSenderLabel(event) {
     return `user ${event.user ?? "unknown"}`;
 }
-/** Main-channel discussion and each concrete thread are independent context buckets.
- *
- *  The `:root:` segment carries `thread_ts`, which in Slack IS the thread's parent message and is
- *  stable for the life of the thread — unrelated to the `<chat>:root:<root_id>` shape Feishu retired
- *  (its `root_id` moves with the reply chain, so it could not identify a side conversation at all).
- *  Same token, different platform meaning; the key is left as-is because renaming it would discard
- *  live context buckets for no semantic gain. */
+/** Main-channel discussion and each concrete thread are independent context buckets. */
 export function slackPlaceKey(teamId, event) {
     const base = `${teamId}:${event.channel ?? "unknown-channel"}`;
     return event.thread_ts ? `${base}:root:${event.thread_ts}` : base;
@@ -89,7 +69,6 @@ export function slackPlaceKey(teamId, event) {
 export function slackBufferText(text) {
     return truncateCodePointPrefix(text.replace(/\s+/g, " ").trim(), BUFFER_LINE_MAX_CHARS);
 }
-/** Canonical prompt envelope. The channel/thread ids also give slack-send an explicit delivery target. */
 export function slackEnvelope(envelope) {
     const event = envelope.event;
     if (!event?.channel)

package/dist/channels/slack/preview.d.ts

@@ -1,5 +1,8 @@
 /** Slack reply rendering: native Agent streams first, rate-safe edited-message compatibility second. */
 import type { AgentEvent } from "../../agent.ts";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { PortFailure } from "../../effect-port.ts";
 import { type ChannelFailure, defaultErrorMessage } from "../kit/preview-kit.ts";
 import { type SlackApi, type SlackTarget } from "./slack-api.ts";
 export type SlackFailure = ChannelFailure;
@@ -12,12 +15,19 @@ export { defaultErrorMessage };
  * across the many `<` start positions), while still neutralizing every `<@…>` / `<!…>` control sequence
  * (real Slack controls never contain a `<`). */
 export declare function sanitizeSlackMarkdown(markdown: string): string;
+/**
+ * Deliver a reply this process did not generate: a recovered answer. The stream it was written for is gone with its
+ * process, so there is none to resume — but a compatibility queue message THIS process posted while the record
+ * waited its turn is taken over rather than left above the answer.
+ */
+export declare function deliverSlackAnswer(api: SlackApi, target: SlackTarget, markdown: string, previewTs?: string): Promise<void>;
 /** Settle a queue/drop/defer notice. These are authored plain strings, so the basic text API is enough. */
 export declare function settleSlackPreview(api: SlackApi, target: SlackTarget, previewTs: string | undefined, text: string): Promise<void>;
-export declare function streamSlackReply(events: AsyncIterable<AgentEvent>, api: SlackApi, target: SlackTarget, formatError: (failure: SlackFailure) => string | undefined, options?: {
+export declare function slackReply(events: Stream.Stream<AgentEvent, PortFailure>, api: SlackApi, target: SlackTarget, formatError: (failure: SlackFailure) => string | undefined, options?: {
     rendering?: SlackRendering;
     initialPreviewTs?: string;
     threadTitle?: string;
     disclaimer?: string | false;
     label?: string;
-}): Promise<void>;
+    onAnswered?: (answer: string) => void;
+}): Effect.Effect<void, PortFailure, import("effect/Scope").Scope>;