@tangle-network/agent-app 0.45.54 → 0.45.55

package/README.md

@@ -184,7 +184,7 @@ pnpm install
 pnpm typecheck && pnpm test && pnpm build
 ```
 
-Build is [tsup](https://tsup.egoist.dev) (ESM + `.d.ts`), tests are [vitest](https://vitest.dev). A change keeps the suite green and follows the layering rule above — anything engine-general is contributed down to the substrate, not duplicated here. See [AGENTS.md](./AGENTS.md) for the full contributor contract.
+Build is [tsup](https://tsup.egoist.dev) for the ESM output plus `tsc` for the `.d.ts`, tests are [vitest](https://vitest.dev). A change keeps the suite green and follows the layering rule above — anything engine-general is contributed down to the substrate, not duplicated here. See [AGENTS.md](./AGENTS.md) for the full contributor contract.
 
 ## License
 

package/dist/alerting/index.d.ts

@@ -1,178 +1,8 @@
 /**
- * `/alerting` — post an operational alert to Slack, and say honestly when it
- * did not arrive.
+ * `/alerting` — the operational alert channel every product hand-rolled.
  *
- * WHY THIS EXISTS: on 2026-08-06 an audit of every Slack credential the org
- * held found three of four dead — the fleet incoming webhook 404ing
- * (`no_service`), a second company webhook likewise, and the bot token
- * answering `account_inactive`. One ops webhook was still live. Nobody knew
- * which was which until each was tested by hand, and that is the actual
- * problem: the credentials were indistinguishable from where the code stood.
- *
- * This failure has already been paid for once, with numbers: in
- * `agent-dev-container`, a revoked webhook let the CI healthcheck sit dead for
- * 18 days — 2,567 consecutive failures, 27 successes, zero alerts — because
- * fifteen call sites across six workflows posted with no body inspection and
- * then asserted delivery. That repo fixed the reporting (its `post-slack.sh`
- * confirms 2xx AND Slack's literal `ok` body, and fails closed otherwise) and
- * that half of the lesson is theirs, adopted here.
- *
- * What their fix cannot do, and this module can, is answer the question BEFORE
- * an alert needs to fire. A fail-closed post still only discovers a dead
- * credential at the moment a page is lost. That is the second half.
- *
- * Two design consequences, and they are the whole module:
- *
- * 1. **A bot token and `chat.postMessage` is the preferred transport; an
- *    incoming webhook is supported because one is usually what you already
- *    have.** A token reaches every channel (a webhook is bolted to one), is
- *    revocable and rotatable in place, and — the part that matters — is
- *    VERIFIABLE: `auth.test` answers whether the credential is alive without
- *    posting anything, which is what lets `/preflight` fail a deploy on a dead
- *    alerting channel instead of discovering it during an incident. A webhook
- *    can only be tested by posting to it, which is why the three dead
- *    credentials above went unnoticed. A token is never fallen back FROM: if
- *    one is configured and dead, delivering over a webhook instead would hide
- *    the very condition worth reporting.
- *
- * 2. **Slack answers `ok:false` under HTTP 200.** `invalid_auth`,
- *    `channel_not_found` and `not_in_channel` all arrive as a successful
- *    response with a failure inside it, so a status check reads a dead channel
- *    as a delivered page. The body is always parsed, and the outcome
- *    distinguishes a MISSING credential (configuration absent — not an
- *    incident) from a DEAD one (the alerting channel itself is broken — the
- *    loudest thing this module can report). A summary that calls those two the
- *    same thing is the defect wearing a different hat.
- *
- * The caller decides what to do with a non-delivery; this module never throws
- * on one, because an alerting path that can take down the thing it reports on
- * is worse than the outage it was watching for. It is also never the only
- * channel: a durable record (an issue, an audit row) is the caller's job, and
- * that is what survives the credential going dead again.
- *
- * Server-only: holds a bot token. This subpath must never reach a browser
- * bundle.
- */
-/**
- * Why an alert did not reach Slack. The split is by what a human must DO about
- * it, since that is the only distinction a caller can act on.
- */
-type SlackFailureReason = 
-/** No token or no channel configured. Configuration is absent, nothing is broken. */
-'not-configured'
-/**
- * The token is dead — revoked, or its app removed from the workspace. No
- * alert will EVER arrive until a human mints a new one. This is itself an
- * incident and the caller should escalate it on a channel that does not
- * depend on Slack.
- */
- | 'credential'
-/**
- * The credential is alive but cannot post HERE: the channel is wrong,
- * archived, or the bot was never invited to it. One human action fixes it.
- */
- | 'channel'
-/** Slack asked us to slow down. Transient; the alert is worth retrying. */
- | 'rate-limited'
-/** The request never got an answer — network, DNS, timeout. Transient. */
- | 'transport'
-/** Slack refused for some other reason; `detail` carries its error code. */
- | 'api';
-/** An alert that did not arrive, and why. Named because the classifiers only ever produce this half. */
-interface SlackAlertFailure {
-    delivered: false;
-    reason: SlackFailureReason;
-    /** One line naming what is wrong and what fixes it. Safe to log; carries no token. */
-    detail: string;
-}
-/** What one `postSlackAlert` call did. Never a bare boolean — the caller pages differently per reason. */
-type SlackAlertOutcome = {
-    delivered: true;
-    /** The channel id Slack resolved (not necessarily the name that was passed). */
-    channel: string;
-    /** Slack's message timestamp — the message's identity, for a later thread reply. */
-    ts: string;
-} | SlackAlertFailure;
-/** Define configuration options for posting an alert message to a Slack channel */
-interface SlackAlertOptions {
-    /**
-     * Slack bot token (`xoxb-…`) with `chat:write`. The PREFERRED transport,
-     * because it is the only one whose liveness can be checked before an alert
-     * needs it. An empty or absent value is `not-configured`, never an error — a
-     * product that has not adopted Slack yet must not fail its alerting path.
-     */
-    token?: string | undefined;
-    /**
-     * Channel to post to: a name (`#infra-alerts`) or an id (`C01234567`). The
-     * bot must be a member; Slack answers `not_in_channel` otherwise. Required
-     * with `token`, meaningless with `webhookUrl` (a webhook carries its own
-     * channel, fixed when it was created).
-     */
-    channel?: string | undefined;
-    /**
-     * Slack incoming-webhook URL, used only when no `token` is configured.
-     *
-     * It works and it needs no setup, which is why it is supported — but it
-     * cannot be verified without posting, cannot be pointed at a second channel,
-     * and gives back an error token instead of a code. Two of the three webhooks
-     * this org has held were found revoked. Treat it as the transport you have,
-     * not the one you want.
-     *
-     * When a `token` is also configured this is IGNORED rather than used as a
-     * fallback: a dead token must surface as the incident it is, and quietly
-     * succeeding over a second transport is how the last outage stayed invisible.
-     */
-    webhookUrl?: string | undefined;
-    /** Message body as Slack mrkdwn. Newlines are preserved. */
-    text: string;
-    /**
-     * Attempts for a TRANSIENT failure (429 / 5xx / transport). Default 3. A
-     * dead credential or a wrong channel is never retried — the answer will not
-     * change, and retrying an auth failure is how a token gets rate-limited.
-     */
-    attempts?: number;
-    /** Per-request deadline. Default 10s. */
-    timeoutMs?: number;
-    /** Injection seam for tests; defaults to global `fetch`. */
-    fetchImpl?: typeof fetch;
-    /** Injection seam for tests; defaults to a real delay between retries. */
-    sleepImpl?: (ms: number) => Promise<void>;
-}
-/**
- * Post one alert to a Slack channel.
- *
- * Never throws and never retries a failure whose answer cannot change. The
- * returned outcome is the whole result — a caller that ignores it has an
- * alerting path it cannot prove works, which is the failure this module was
- * written for.
- */
-declare function postSlackAlert(options: SlackAlertOptions): Promise<SlackAlertOutcome>;
-/** Define configuration options for verifying that a Slack bot token is live */
-interface SlackCredentialCheckOptions {
-    token: string | undefined;
-    /** Per-request deadline. Default 10s. */
-    timeoutMs?: number;
-    /** Injection seam for tests; defaults to global `fetch`. */
-    fetchImpl?: typeof fetch;
-}
-/** What `checkSlackCredential` concluded. `team`/`botId` are present only when live. */
-type SlackCredentialVerdict = {
-    live: true;
-    team: string;
-    botId: string;
-} | {
-    live: false;
-    reason: SlackFailureReason;
-    detail: string;
-};
-/**
- * Ask Slack whether the bot token is alive, WITHOUT posting anything.
- *
- * This is the check that was missing. An incoming webhook offers no equivalent
- * — the only way to test one is to post to it — which is how a revoked webhook
- * sat in a repo secret for months looking configured. Wire it into `/preflight`
- * so a dead alerting channel fails a deploy rather than an incident.
+ * The module's own doctrine, and the incident behind it, is in `./slack`.
+ * Nothing domain-specific lives here: the message text and the decision to
+ * alert are the caller's, this owns delivery and the honest verdict about it.
  */
-declare function checkSlackCredential(options: SlackCredentialCheckOptions): Promise<SlackCredentialVerdict>;
-
-export { type SlackAlertFailure, type SlackAlertOptions, type SlackAlertOutcome, type SlackCredentialCheckOptions, type SlackCredentialVerdict, type SlackFailureReason, checkSlackCredential, postSlackAlert };
+export { checkSlackCredential, postSlackAlert, type SlackAlertFailure, type SlackAlertOptions, type SlackAlertOutcome, type SlackCredentialCheckOptions, type SlackCredentialVerdict, type SlackFailureReason, } from './slack';

package/dist/alerting/slack.d.ts

@@ -0,0 +1,176 @@
+/**
+ * `/alerting` — post an operational alert to Slack, and say honestly when it
+ * did not arrive.
+ *
+ * WHY THIS EXISTS: on 2026-08-06 an audit of every Slack credential the org
+ * held found three of four dead — the fleet incoming webhook 404ing
+ * (`no_service`), a second company webhook likewise, and the bot token
+ * answering `account_inactive`. One ops webhook was still live. Nobody knew
+ * which was which until each was tested by hand, and that is the actual
+ * problem: the credentials were indistinguishable from where the code stood.
+ *
+ * This failure has already been paid for once, with numbers: in
+ * `agent-dev-container`, a revoked webhook let the CI healthcheck sit dead for
+ * 18 days — 2,567 consecutive failures, 27 successes, zero alerts — because
+ * fifteen call sites across six workflows posted with no body inspection and
+ * then asserted delivery. That repo fixed the reporting (its `post-slack.sh`
+ * confirms 2xx AND Slack's literal `ok` body, and fails closed otherwise) and
+ * that half of the lesson is theirs, adopted here.
+ *
+ * What their fix cannot do, and this module can, is answer the question BEFORE
+ * an alert needs to fire. A fail-closed post still only discovers a dead
+ * credential at the moment a page is lost. That is the second half.
+ *
+ * Two design consequences, and they are the whole module:
+ *
+ * 1. **A bot token and `chat.postMessage` is the preferred transport; an
+ *    incoming webhook is supported because one is usually what you already
+ *    have.** A token reaches every channel (a webhook is bolted to one), is
+ *    revocable and rotatable in place, and — the part that matters — is
+ *    VERIFIABLE: `auth.test` answers whether the credential is alive without
+ *    posting anything, which is what lets `/preflight` fail a deploy on a dead
+ *    alerting channel instead of discovering it during an incident. A webhook
+ *    can only be tested by posting to it, which is why the three dead
+ *    credentials above went unnoticed. A token is never fallen back FROM: if
+ *    one is configured and dead, delivering over a webhook instead would hide
+ *    the very condition worth reporting.
+ *
+ * 2. **Slack answers `ok:false` under HTTP 200.** `invalid_auth`,
+ *    `channel_not_found` and `not_in_channel` all arrive as a successful
+ *    response with a failure inside it, so a status check reads a dead channel
+ *    as a delivered page. The body is always parsed, and the outcome
+ *    distinguishes a MISSING credential (configuration absent — not an
+ *    incident) from a DEAD one (the alerting channel itself is broken — the
+ *    loudest thing this module can report). A summary that calls those two the
+ *    same thing is the defect wearing a different hat.
+ *
+ * The caller decides what to do with a non-delivery; this module never throws
+ * on one, because an alerting path that can take down the thing it reports on
+ * is worse than the outage it was watching for. It is also never the only
+ * channel: a durable record (an issue, an audit row) is the caller's job, and
+ * that is what survives the credential going dead again.
+ *
+ * Server-only: holds a bot token. This subpath must never reach a browser
+ * bundle.
+ */
+/**
+ * Why an alert did not reach Slack. The split is by what a human must DO about
+ * it, since that is the only distinction a caller can act on.
+ */
+export type SlackFailureReason = 
+/** No token or no channel configured. Configuration is absent, nothing is broken. */
+'not-configured'
+/**
+ * The token is dead — revoked, or its app removed from the workspace. No
+ * alert will EVER arrive until a human mints a new one. This is itself an
+ * incident and the caller should escalate it on a channel that does not
+ * depend on Slack.
+ */
+ | 'credential'
+/**
+ * The credential is alive but cannot post HERE: the channel is wrong,
+ * archived, or the bot was never invited to it. One human action fixes it.
+ */
+ | 'channel'
+/** Slack asked us to slow down. Transient; the alert is worth retrying. */
+ | 'rate-limited'
+/** The request never got an answer — network, DNS, timeout. Transient. */
+ | 'transport'
+/** Slack refused for some other reason; `detail` carries its error code. */
+ | 'api';
+/** An alert that did not arrive, and why. Named because the classifiers only ever produce this half. */
+export interface SlackAlertFailure {
+    delivered: false;
+    reason: SlackFailureReason;
+    /** One line naming what is wrong and what fixes it. Safe to log; carries no token. */
+    detail: string;
+}
+/** What one `postSlackAlert` call did. Never a bare boolean — the caller pages differently per reason. */
+export type SlackAlertOutcome = {
+    delivered: true;
+    /** The channel id Slack resolved (not necessarily the name that was passed). */
+    channel: string;
+    /** Slack's message timestamp — the message's identity, for a later thread reply. */
+    ts: string;
+} | SlackAlertFailure;
+/** Define configuration options for posting an alert message to a Slack channel */
+export interface SlackAlertOptions {
+    /**
+     * Slack bot token (`xoxb-…`) with `chat:write`. The PREFERRED transport,
+     * because it is the only one whose liveness can be checked before an alert
+     * needs it. An empty or absent value is `not-configured`, never an error — a
+     * product that has not adopted Slack yet must not fail its alerting path.
+     */
+    token?: string | undefined;
+    /**
+     * Channel to post to: a name (`#infra-alerts`) or an id (`C01234567`). The
+     * bot must be a member; Slack answers `not_in_channel` otherwise. Required
+     * with `token`, meaningless with `webhookUrl` (a webhook carries its own
+     * channel, fixed when it was created).
+     */
+    channel?: string | undefined;
+    /**
+     * Slack incoming-webhook URL, used only when no `token` is configured.
+     *
+     * It works and it needs no setup, which is why it is supported — but it
+     * cannot be verified without posting, cannot be pointed at a second channel,
+     * and gives back an error token instead of a code. Two of the three webhooks
+     * this org has held were found revoked. Treat it as the transport you have,
+     * not the one you want.
+     *
+     * When a `token` is also configured this is IGNORED rather than used as a
+     * fallback: a dead token must surface as the incident it is, and quietly
+     * succeeding over a second transport is how the last outage stayed invisible.
+     */
+    webhookUrl?: string | undefined;
+    /** Message body as Slack mrkdwn. Newlines are preserved. */
+    text: string;
+    /**
+     * Attempts for a TRANSIENT failure (429 / 5xx / transport). Default 3. A
+     * dead credential or a wrong channel is never retried — the answer will not
+     * change, and retrying an auth failure is how a token gets rate-limited.
+     */
+    attempts?: number;
+    /** Per-request deadline. Default 10s. */
+    timeoutMs?: number;
+    /** Injection seam for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Injection seam for tests; defaults to a real delay between retries. */
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+/**
+ * Post one alert to a Slack channel.
+ *
+ * Never throws and never retries a failure whose answer cannot change. The
+ * returned outcome is the whole result — a caller that ignores it has an
+ * alerting path it cannot prove works, which is the failure this module was
+ * written for.
+ */
+export declare function postSlackAlert(options: SlackAlertOptions): Promise<SlackAlertOutcome>;
+/** Define configuration options for verifying that a Slack bot token is live */
+export interface SlackCredentialCheckOptions {
+    token: string | undefined;
+    /** Per-request deadline. Default 10s. */
+    timeoutMs?: number;
+    /** Injection seam for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** What `checkSlackCredential` concluded. `team`/`botId` are present only when live. */
+export type SlackCredentialVerdict = {
+    live: true;
+    team: string;
+    botId: string;
+} | {
+    live: false;
+    reason: SlackFailureReason;
+    detail: string;
+};
+/**
+ * Ask Slack whether the bot token is alive, WITHOUT posting anything.
+ *
+ * This is the check that was missing. An incoming webhook offers no equivalent
+ * — the only way to test one is to post to it — which is how a revoked webhook
+ * sat in a repo secret for months looking configured. Wire it into `/preflight`
+ * so a dead alerting channel fails a deploy rather than an incident.
+ */
+export declare function checkSlackCredential(options: SlackCredentialCheckOptions): Promise<SlackCredentialVerdict>;

package/dist/app-auth/index.d.ts

@@ -1,6 +1,3 @@
-import { Session, User, Auth, BetterAuthOptions } from 'better-auth';
-import { A as AuthGuard, T as TangleSsoHandlers, a as TangleSsoAuthClient, b as TangleSsoAccountStore } from '../sso-Cm00S61u.js';
-
 /**
  * better-auth config factory for agent products (#188 Phase 1). Every product
  * hand-rolls the same ~70–150 line setup — drizzle adapter over the standard
@@ -20,9 +17,11 @@ import { A as AuthGuard, T as TangleSsoHandlers, a as TangleSsoAuthClient, b as
  * better-auth is an OPTIONAL peer: only this subpath imports it, so it is
  * deliberately NOT re-exported from the root barrel.
  */
-
+import { type Auth, type BetterAuthOptions, type Session, type User } from 'better-auth';
+import { type AuthGuard } from '../platform/guards';
+import { type TangleSsoAccountStore, type TangleSsoAuthClient, type TangleSsoHandlers } from '../platform/sso';
 /** Structural slice of a Resend-style client — no `resend` import. */
-interface AppAuthEmailClient {
+export interface AppAuthEmailClient {
     emails: {
         send(message: {
             from: string;
@@ -34,7 +33,7 @@ interface AppAuthEmailClient {
     };
 }
 /** Define email configuration for app authentication including client, sender, verification, and warning options */
-interface AppAuthEmailConfig {
+export interface AppAuthEmailConfig {
     /** A Resend-style client, or a lazy getter returning null when the API key
      *  is absent (the products' dev default — mail is skipped with a warning,
      *  sign-up itself must not crash). */
@@ -49,12 +48,12 @@ interface AppAuthEmailConfig {
 }
 /** Env-shaped: pass the env vars straight through; the provider is registered
  *  only when BOTH values are non-empty, so unset env disables it. */
-interface AppAuthSocialProviderConfig {
+export interface AppAuthSocialProviderConfig {
     clientId?: string;
     clientSecret?: string;
 }
 /** Define social authentication configuration options for GitHub and Google providers */
-interface AppAuthSocialConfig {
+export interface AppAuthSocialConfig {
     github?: AppAuthSocialProviderConfig;
     google?: AppAuthSocialProviderConfig;
 }
@@ -62,7 +61,7 @@ interface AppAuthSocialConfig {
  *  `setSessionCookie` via `createBetterAuthSessionCookieMinter(auth)` (signed
  *  `__Secure-`/prefixed cookie that `auth.api.getSession` accepts) — so the
  *  product no longer touches `better-auth/crypto` itself. */
-interface AppAuthSsoConfig {
+export interface AppAuthSsoConfig {
     /** Platform wire client (authorizeUrl + exchange). */
     client: TangleSsoAuthClient;
     /** Product persistence: user upsert, session row, platform link. */
@@ -86,14 +85,14 @@ interface AppAuthSsoConfig {
     log?: (message: string, error?: unknown) => void;
 }
 /** Define the structure for application authentication data including users, sessions, accounts, and verifications */
-interface AppAuthSchema {
+export interface AppAuthSchema {
     users: unknown;
     sessions: unknown;
     accounts: unknown;
     verifications: unknown;
 }
 /** Define configuration settings for app authentication including app name, base URL, secrets, and trusted origins */
-interface AppAuthConfig {
+export interface AppAuthConfig {
     /** Product name — used in email subjects and as the cookie-prefix default. */
     appName: string;
     /** Absolute origin better-auth serves from (`BETTER_AUTH_URL`). */
@@ -141,14 +140,14 @@ interface AppAuthConfig {
 }
 /** The configured better-auth instance, typed at better-auth's base surface
  *  (`handler`, `api`, `$context`, `$Infer`). */
-type AppAuthInstance = Auth;
+export type AppAuthInstance = Auth;
 /** What `getSession`/guards resolve: better-auth's base session + user rows. */
-interface AppAuthSession {
+export interface AppAuthSession {
     session: Session;
     user: User;
 }
 /** Define authentication guard with session retrieval and optional SSO handlers for app requests */
-interface AppAuth extends AuthGuard<AppAuthSession> {
+export interface AppAuth extends AuthGuard<AppAuthSession> {
     auth: AppAuthInstance;
     /** `auth.api.getSession` over a `Request` — the seam the guards consume. */
     getSession(request: Request): Promise<AppAuthSession | null>;
@@ -163,6 +162,4 @@ interface AppAuth extends AuthGuard<AppAuthSession> {
  * start/callback handlers with the session cookie minted through better-auth's
  * own name/attributes/signing (no `better-auth/crypto` in product code).
  */
-declare function createAppAuth(config: AppAuthConfig): AppAuth;
-
-export { type AppAuth, type AppAuthConfig, type AppAuthEmailClient, type AppAuthEmailConfig, type AppAuthInstance, type AppAuthSchema, type AppAuthSession, type AppAuthSocialConfig, type AppAuthSocialProviderConfig, type AppAuthSsoConfig, createAppAuth };
+export declare function createAppAuth(config: AppAuthConfig): AppAuth;