@mycadet/credential-executor 0.0.1 → 0.12.6-dev.202610072225.d7acd73

package/node_modules/@mycadet/service-contracts/src/guardian-requests.ts

@@ -0,0 +1,92 @@
+/**
+ * Canonical vocabulary for guardian requests, shared by the gateway that owns
+ * the request rows, the daemon that decides and projects them, and the web
+ * that renders the projection: a request's lifecycle status, the actions a
+ * guardian can decide it with, and the weight a card gives each action.
+ */
+import { z } from "zod";
+
+export const GUARDIAN_REQUEST_STATUS_VALUES = [
+  "pending",
+  "approved",
+  "denied",
+  "expired",
+  "cancelled",
+] as const;
+export const GuardianRequestStatusSchema = z.enum(
+  GUARDIAN_REQUEST_STATUS_VALUES,
+);
+export type GuardianRequestStatus = z.infer<typeof GuardianRequestStatusSchema>;
+
+/**
+ * The actions a guardian can decide a request with.
+ *
+ * `approve_once` / `reject` are the generic decision pair used by every
+ * request kind. `trust` / `verify_code` / `leave_unverified` / `block` are the
+ * introduction-card actions, valid only for `access_request` requests.
+ */
+export const GUARDIAN_DECISION_ACTION_IDS = [
+  "approve_once",
+  "reject",
+  "trust",
+  "verify_code",
+  "leave_unverified",
+  "block",
+] as const;
+export const GuardianDecisionActionIdSchema = z.enum(
+  GUARDIAN_DECISION_ACTION_IDS,
+);
+export type GuardianDecisionActionId = z.infer<
+  typeof GuardianDecisionActionIdSchema
+>;
+
+/** Actions that resolve a request to `denied`; every other one approves. */
+export const GUARDIAN_DENYING_ACTION_VALUES = [
+  "reject",
+  "leave_unverified",
+  "block",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+/**
+ * The denying actions that park the sender at `unverified`: a neutral hold,
+ * not a rejection. A parked contact is still admitted under the permissive
+ * admission floors (`any_contact`, `strangers`) and can be trusted or verified
+ * later; contrast `block` (revoked, a hard keep-out) and `reject` (an explicit
+ * decline). All three resolve the request to `denied`, so a resolved card
+ * consults this to read a park neutrally rather than as a denial.
+ */
+export const GUARDIAN_PARK_ACTION_VALUES = [
+  "leave_unverified",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+const DENYING_ACTIONS: ReadonlySet<string> = new Set(
+  GUARDIAN_DENYING_ACTION_VALUES,
+);
+const PARK_ACTIONS: ReadonlySet<string> = new Set(GUARDIAN_PARK_ACTION_VALUES);
+
+/** True when `action` resolves a request to `denied`. */
+export function isDenyingGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && DENYING_ACTIONS.has(action);
+}
+
+/** True when `action` parks the sender at `unverified`. */
+export function isParkGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && PARK_ACTIONS.has(action);
+}
+
+/**
+ * Surface-agnostic weight of a card action. Each renderer translates it to
+ * its own token (Slack primary/danger, a web button variant); absent means the
+ * renderer's default.
+ */
+export const GUARDIAN_ACTION_EMPHASIS_VALUES = [
+  "primary",
+  "secondary",
+  "destructive",
+] as const;
+export const GuardianActionEmphasisSchema = z.enum(
+  GUARDIAN_ACTION_EMPHASIS_VALUES,
+);
+export type GuardianActionEmphasis = z.infer<
+  typeof GuardianActionEmphasisSchema
+>;

package/node_modules/@mycadet/service-contracts/src/handles.ts

@@ -0,0 +1,209 @@
+/**
+ * CES credential handle formats and parser helpers.
+ *
+ * A "handle" is an opaque string that the assistant passes to CES to identify
+ * which credential context should be used for a given execution. Handles never
+ * contain secret material — they are references that CES resolves internally.
+ *
+ * v1 handle formats:
+ *
+ * 1. **Local static** — references a credential stored in the local secure-key
+ *    backend. Format: `local_static:<service>/<field>` (matches the
+ *    `credential/{service}/{field}` key pattern from credential-storage).
+ *
+ * 2. **Local OAuth** — references a locally persisted OAuth connection.
+ *    Format: `local_oauth:<providerKey>/<connectionId>` where providerKey
+ *    is the bare provider name (e.g. `google`).
+ *
+ * 3. **Managed OAuth** — references an OAuth connection managed by the
+ *    platform. Format: `platform_oauth:<connectionId>` where connectionId
+ *    is the platform-assigned connection identifier.
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Handle type discriminator
+// ---------------------------------------------------------------------------
+
+export const HandleType = {
+  LocalStatic: "local_static",
+  LocalOAuth: "local_oauth",
+  PlatformOAuth: "platform_oauth",
+} as const;
+
+export type HandleType = (typeof HandleType)[keyof typeof HandleType];
+
+// ---------------------------------------------------------------------------
+// Parsed handle shapes
+// ---------------------------------------------------------------------------
+
+export interface LocalStaticHandle {
+  type: typeof HandleType.LocalStatic;
+  /** Service name (e.g. "github", "fal"). */
+  service: string;
+  /** Field name within the service (e.g. "api_key", "password"). */
+  field: string;
+  /** The raw handle string. */
+  raw: string;
+}
+
+export interface LocalOAuthHandle {
+  type: typeof HandleType.LocalOAuth;
+  /** Provider key (e.g. "google", "slack"). */
+  providerKey: string;
+  /** Connection identifier. */
+  connectionId: string;
+  /** The raw handle string. */
+  raw: string;
+}
+
+export interface PlatformOAuthHandle {
+  type: typeof HandleType.PlatformOAuth;
+  /** Platform-assigned connection identifier. */
+  connectionId: string;
+  /** The raw handle string. */
+  raw: string;
+}
+
+export type ParsedHandle =
+  | LocalStaticHandle
+  | LocalOAuthHandle
+  | PlatformOAuthHandle;
+
+// ---------------------------------------------------------------------------
+// Handle construction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a local static credential handle from service and field.
+ *
+ * Accepts the same service/field values used in `credentialKey()` from
+ * `@mycadet/credential-storage`.
+ */
+export function localStaticHandle(service: string, field: string): string {
+  return `${HandleType.LocalStatic}:${service}/${field}`;
+}
+
+/**
+ * Build a local OAuth credential handle from a provider key and connection ID.
+ */
+export function localOAuthHandle(
+  providerKey: string,
+  connectionId: string,
+): string {
+  return `${HandleType.LocalOAuth}:${providerKey}/${connectionId}`;
+}
+
+/**
+ * Build a managed (platform) OAuth credential handle from a connection ID.
+ */
+export function platformOAuthHandle(connectionId: string): string {
+  return `${HandleType.PlatformOAuth}:${connectionId}`;
+}
+
+// ---------------------------------------------------------------------------
+// Handle parsing
+// ---------------------------------------------------------------------------
+
+export type ParseHandleResult =
+  | { ok: true; handle: ParsedHandle }
+  | { ok: false; error: string };
+
+/**
+ * Parse a raw handle string into a structured `ParsedHandle`.
+ *
+ * Returns a discriminated result so callers can inspect parse errors
+ * without catching exceptions.
+ */
+export function parseHandle(raw: string): ParseHandleResult {
+  const colonIdx = raw.indexOf(":");
+  if (colonIdx === -1) {
+    return {
+      ok: false,
+      error: `Invalid handle format: missing type prefix in "${raw}"`,
+    };
+  }
+
+  const prefix = raw.slice(0, colonIdx);
+  const rest = raw.slice(colonIdx + 1);
+
+  switch (prefix) {
+    case HandleType.LocalStatic: {
+      const slashIdx = rest.indexOf("/");
+      if (slashIdx === -1 || slashIdx === 0 || slashIdx === rest.length - 1) {
+        return {
+          ok: false,
+          error: `Invalid local_static handle: expected "local_static:<service>/<field>", got "${raw}"`,
+        };
+      }
+      return {
+        ok: true,
+        handle: {
+          type: HandleType.LocalStatic,
+          service: rest.slice(0, slashIdx),
+          field: rest.slice(slashIdx + 1),
+          raw,
+        },
+      };
+    }
+
+    case HandleType.LocalOAuth: {
+      // Split providerKey from connectionId.
+      const slashIdx = rest.indexOf("/");
+      if (slashIdx === -1 || slashIdx === 0 || slashIdx === rest.length - 1) {
+        return {
+          ok: false,
+          error: `Invalid local_oauth handle: expected "local_oauth:<providerKey>/<connectionId>", got "${raw}"`,
+        };
+      }
+      return {
+        ok: true,
+        handle: {
+          type: HandleType.LocalOAuth,
+          providerKey: rest.slice(0, slashIdx),
+          connectionId: rest.slice(slashIdx + 1),
+          raw,
+        },
+      };
+    }
+
+    case HandleType.PlatformOAuth: {
+      if (!rest || rest.length === 0) {
+        return {
+          ok: false,
+          error: `Invalid platform_oauth handle: missing connectionId in "${raw}"`,
+        };
+      }
+      return {
+        ok: true,
+        handle: {
+          type: HandleType.PlatformOAuth,
+          connectionId: rest,
+          raw,
+        },
+      };
+    }
+
+    default:
+      return {
+        ok: false,
+        error: `Unknown handle type prefix "${prefix}" in "${raw}"`,
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Zod schema for wire validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Zod schema that validates a string as a well-formed CES credential handle.
+ * Useful in RPC schemas where the handle travels on the wire.
+ */
+export const CredentialHandleSchema = z.string().check(
+  z.refine((val: string) => {
+    const result = parseHandle(val);
+    return result.ok;
+  }, "Must be a valid CES credential handle (local_static:*, local_oauth:*, or platform_oauth:*)"),
+);

package/node_modules/@mycadet/service-contracts/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @mycadet/service-contracts — aggregate export (compat entry point)
+ *
+ * This is a compatibility aggregate that re-exports everything from all
+ * submodules. Prefer the explicit domain subpaths for new code:
+ *
+ *   - `@mycadet/service-contracts/credential-rpc`  — transport, RPC, handles, error
+ *   - `@mycadet/service-contracts/trust-rules`     — trust-rule types and parsing helpers
+ *   - `@mycadet/service-contracts/twilio-ingress`  — shared Twilio ingress config constants
+ *   - `@mycadet/service-contracts/ingress`         — shared public ingress URL helpers
+ *
+ * Fine-grained subpaths are also available for low-friction migration:
+ *   `./rpc`, `./handles`, `./error`, `./trust-rules`, `./ingress`, `./twilio-ingress`
+ *
+ * Neutral wire-protocol contracts for communication between the assistant
+ * daemon and the Credential Execution Service (CES). This package is
+ * intentionally free of imports from `assistant/` or any CES implementation
+ * module so that both sides can depend on it without circular references.
+ */
+
+export * from "./channels.js";
+export * from "./client-metadata.js";
+export * from "./conversation-handle.js";
+export * from "./transport.js";
+export * from "./error.js";
+export * from "./handles.js";
+export * from "./rpc.js";
+export * from "./trust-rules.js";
+export * from "./ingress.js";
+export * from "./no-response.js";
+export * from "./plan-credit.js";
+export * from "./integration-categories.js";
+export * from "./mcp-oauth.js";
+export * from "./platform-credential.js";
+export * from "./remote-web-pairing.js";
+export * from "./twilio-ingress.js";
+export * from "./url-normalization.js";

package/node_modules/@mycadet/service-contracts/src/ingress.ts

@@ -0,0 +1,175 @@
+/**
+ * Map a Cadet Cloud host onto its environment's tunnel host, following the
+ * deployment naming convention (`cloud.mycadet.ai` → `tunnel.mycadet.ai`,
+ * `{env}-cloud.mycadet.ai` → `tunnel-{env}.mycadet.ai`). Returns null for
+ * hosts outside that convention (localhost, custom domains). Shared by the
+ * gateway speech relay and the web live-voice client so the two ends of the
+ * managed-speech transport can't drift.
+ */
+export function tunnelHostForPlatformHost(host: string): string | null {
+  if (host === "cloud.mycadet.ai") {
+    return "tunnel.mycadet.ai";
+  }
+  const match = /^([a-z0-9-]+)-cloud\.mycadet\.ai$/.exec(host);
+  return match ? `tunnel-${match[1]}.mycadet.ai` : null;
+}
+
+export function normalizePublicBaseUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().replace(/\/+$/, "");
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+/**
+ * Application close code the gateway's tunnel bridge sends to proxied
+ * WebSockets when the tunnel itself is lost (tunnel disconnect, gateway
+ * shutdown). A dedicated code because the natural 1001 (going away) cannot
+ * be sent through the JS `close()` API (the bridge would remap it to a
+ * misleading 4001), and Bun's WebSocket client drops close reasons, so the
+ * code is the only signal that survives the relay to the daemon.
+ */
+export const GATEWAY_TUNNEL_LOST_WS_CLOSE_CODE = 4801;
+
+export function normalizeHttpPublicBaseUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+  if (/[?#]/.test(trimmed)) return undefined;
+
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return undefined;
+    }
+    if (!url.hostname) return undefined;
+    url.pathname = url.pathname.replace(/\/+$/, "") || "/";
+    return url.toString();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The same validation as `normalizeHttpPublicBaseUrl`, minus the root path it
+ * always emits (`https://x` becomes `https://x/`). Callers that append a path
+ * or persist the result want this shape, so they neither join through a double
+ * slash nor re-strip what the normalizer just added.
+ */
+export function normalizeHttpPublicBaseUrlWithoutTrailingSlash(
+  value: unknown,
+): string | undefined {
+  return normalizePublicBaseUrl(normalizeHttpPublicBaseUrl(value));
+}
+
+/**
+ * A trimmed string, or undefined when the value is not a non-blank string.
+ *
+ * Exported because the identity check in the daemon's tunnel probe compares an
+ * id recorded here against one an edge serves, and the two sides have to trim
+ * alike: a padded served id must read as a match, not as a different
+ * assistant.
+ */
+export function trimmedNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+// Records `cadet tunnel` leaves in the workspace config's `ingress` section.
+// The CLI writes them and the daemon reads them, and the two are separate
+// build units that cannot import each other, so the key names, the provider
+// allowlist, and the validation all live here rather than in a copy on each
+// side.
+
+/** Key under `ingress` holding the tunnel that most recently ran. */
+export const INGRESS_LAST_TUNNEL_KEY = "lastTunnel";
+
+/**
+ * Key under `ingress` holding a tunnel published for device pairing alone.
+ *
+ * A tailnet-only tunnel started while webhook integrations are configured
+ * cannot carry their callbacks, so it leaves `publicBaseUrl` (the callback
+ * base) as it is and records itself here. Readers that answer the pairing card
+ * prefer this address over `publicBaseUrl`; teardown drops the key.
+ */
+export const INGRESS_PAIRING_TUNNEL_KEY = "pairingTunnel";
+
+/** Key under `ingress` holding the assistant id that tunnel fronted. */
+export const INGRESS_ASSISTANT_ID_KEY = "assistantId";
+
+/**
+ * The local tunnel providers the CLI can start, in the order they are offered.
+ * `cadet tunnel`'s accepted `--provider` values and the persisted-record
+ * validation below both derive from it.
+ */
+export const TUNNEL_PROVIDERS = ["ngrok", "cloudflare", "tailscale"] as const;
+
+export type TunnelProviderName = (typeof TUNNEL_PROVIDERS)[number];
+
+/** A recorded tunnel, kept after teardown so UIs can name the command to restart. */
+export interface TunnelRecord {
+  provider: TunnelProviderName;
+  publicBaseUrl: string;
+}
+
+function isTunnelProviderName(value: unknown): value is TunnelProviderName {
+  return (
+    typeof value === "string" &&
+    (TUNNEL_PROVIDERS as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Parse an `ingress.lastTunnel` or `ingress.pairingTunnel` value, or null when
+ * it is absent or malformed.
+ *
+ * A hand-edited config must not hand callers an unusable address or a provider
+ * name no command accepts: the provider is checked against the allowlist
+ * because readers render it into a restart command, and the URL faces the same
+ * absolute HTTP(S) constraint as every other public base URL. The URL comes
+ * back in the shape the validator produced, so readers never re-normalize it.
+ */
+export function parseTunnelRecord(value: unknown): TunnelRecord | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const { provider, publicBaseUrl } = value as Record<string, unknown>;
+  if (!isTunnelProviderName(provider)) {
+    return null;
+  }
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (normalized === undefined) {
+    return null;
+  }
+  return { provider, publicBaseUrl: normalized };
+}
+
+/**
+ * The tunnel a reader should offer to restart, given an `ingress` section, or
+ * null when it records none.
+ *
+ * A pairing-only record wins: it is written by a tunnel that deliberately left
+ * `publicBaseUrl` (and the `lastTunnel` beside it) pointing at an older public
+ * provider, so naming that older one would send the user to rebuild an ingress
+ * they are not using instead of the tunnel actually in front of them.
+ */
+export function selectRestartTunnelRecord(
+  ingress: unknown,
+): TunnelRecord | null {
+  if (typeof ingress !== "object" || ingress === null) {
+    return null;
+  }
+  const section = ingress as Record<string, unknown>;
+  return (
+    parseTunnelRecord(section[INGRESS_PAIRING_TUNNEL_KEY]) ??
+    parseTunnelRecord(section[INGRESS_LAST_TUNNEL_KEY])
+  );
+}
+
+/** Parse an `ingress.assistantId` value, or null when it is absent or blank. */
+export function parseRecordedAssistantId(value: unknown): string | null {
+  return trimmedNonEmptyString(value) ?? null;
+}

package/node_modules/@mycadet/service-contracts/src/integration-categories.ts

@@ -0,0 +1,36 @@
+/**
+ * Category vocabulary for the integrations catalog, shared by the assistant
+ * daemon (which stamps it on OAuth providers and marketplace MCP entries) and
+ * the clients (which draw the category filter from it).
+ *
+ * The order here is the order clients show the categories in. The slug is the
+ * wire value; the user-facing label is the client's, so it can be translated.
+ */
+export const INTEGRATION_CATEGORIES = [
+  "productivity",
+  "communication",
+  "meetings",
+  "sales",
+  "marketing",
+  "finance",
+  "commerce",
+  "engineering",
+  "knowledge",
+  "recruiting",
+] as const;
+
+export type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number];
+
+const INTEGRATION_CATEGORY_SET: ReadonlySet<string> = new Set(
+  INTEGRATION_CATEGORIES,
+);
+
+/**
+ * Whether `value` names a category this build knows. A client reading a newer
+ * catalog treats an unknown slug as uncategorized rather than failing.
+ */
+export function isIntegrationCategory(
+  value: unknown,
+): value is IntegrationCategory {
+  return typeof value === "string" && INTEGRATION_CATEGORY_SET.has(value);
+}

package/node_modules/@mycadet/service-contracts/src/mcp-oauth.ts

@@ -0,0 +1,60 @@
+import { normalizeHttpPublicBaseUrlWithoutTrailingSlash } from "./ingress.js";
+
+export const MCP_OAUTH_CALLBACK_PATH = "/webhooks/oauth/callback";
+export const MCP_OAUTH_CLIENT_METADATA_PATH = "/oauth/client-metadata.json";
+export const MCP_OAUTH_CLIENT_LOGO_URI = "https://mycadet.ai/favicon.svg";
+
+export interface McpOAuthClientMetadata {
+  client_id?: string;
+  redirect_uris: string[];
+  token_endpoint_auth_method: "none";
+  grant_types: ["authorization_code", "refresh_token"];
+  response_types: ["code"];
+  client_name: string;
+  logo_uri: string;
+  software_id?: string;
+  software_version?: string;
+}
+
+export interface BuildMcpOAuthClientMetadataOptions {
+  clientId?: string;
+  redirectUris: string[];
+  clientName?: string;
+  softwareId?: string;
+  softwareVersion?: string;
+}
+
+export function buildMcpOAuthClientMetadata(
+  options: BuildMcpOAuthClientMetadataOptions,
+): McpOAuthClientMetadata {
+  return {
+    ...(options.clientId && { client_id: options.clientId }),
+    redirect_uris: options.redirectUris,
+    token_endpoint_auth_method: "none",
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    client_name: options.clientName ?? "Cadet",
+    logo_uri: MCP_OAUTH_CLIENT_LOGO_URI,
+    ...(options.softwareId && { software_id: options.softwareId }),
+    ...(options.softwareVersion && {
+      software_version: options.softwareVersion,
+    }),
+  };
+}
+
+export function buildMcpOAuthCallbackUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CALLBACK_PATH}`;
+}
+
+export function buildMcpOAuthClientMetadataUrl(publicBaseUrl: string): string {
+  return `${normalizeBaseUrl(publicBaseUrl)}${MCP_OAUTH_CLIENT_METADATA_PATH}`;
+}
+
+function normalizeBaseUrl(publicBaseUrl: string): string {
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (!normalized) {
+    throw new Error("MCP OAuth public base URL must be an absolute HTTP URL");
+  }
+  return normalized;
+}

package/node_modules/@mycadet/service-contracts/src/no-response.ts

@@ -0,0 +1,84 @@
+/**
+ * The `<no_response/>` sentinel: the cross-service convention for a turn
+ * that deliberately produces no user-visible reply.
+ *
+ * The model emits it, the daemon stamps and strips it, channel delivery
+ * suppresses it, and clients hold live-streamed prefixes of it back from
+ * display. One definition here keeps every consumer's parsing identical;
+ * a hand-rolled copy in any one of them is how the case-sensitivity of a
+ * regex drifts.
+ */
+
+/** Matches a message whose entire content is the sentinel. */
+const NO_RESPONSE_ONLY_RE = /^\s*<no_response\s*\/?>\s*$/i;
+
+/**
+ * Whether `text` is nothing but the sentinel: the whole reply is a
+ * deliberate non-response, as opposed to real content with an inline
+ * sentinel mixed in.
+ */
+export function isNoResponseOnlyText(text: string): boolean {
+  return NO_RESPONSE_ONLY_RE.test(text);
+}
+
+/** Matches every sentinel occurrence for stripping it out of mixed content. */
+export const NO_RESPONSE_INLINE_RE = /<no_response\s*\/?>/gi;
+
+/**
+ * Detection variant without the `g` flag: a `g`-flagged regex is stateful
+ * under `.test()` (it resumes from `lastIndex`), so reusing
+ * {@link NO_RESPONSE_INLINE_RE} for detection would alternate between
+ * matches and misses across calls.
+ */
+const NO_RESPONSE_MARKER_RE = new RegExp(NO_RESPONSE_INLINE_RE.source, "i");
+
+/** Whether `text` contains the sentinel anywhere. */
+export function containsNoResponseMarker(text: string): boolean {
+  return NO_RESPONSE_MARKER_RE.test(text);
+}
+
+/** Removes every sentinel occurrence, trimming the leftover whitespace. */
+export function stripNoResponseMarkers(text: string): string {
+  return text.replace(NO_RESPONSE_INLINE_RE, "").trim();
+}
+
+const NO_RESPONSE_SENTINEL_FORMS = [
+  "<no_response/>",
+  "<no_response />",
+  "<no_response>",
+] as const;
+
+/**
+ * Whether `text` could still grow into the sentinel, i.e. it is a leading
+ * substring of one of its forms. Holding on these keeps a slowly-streamed
+ * `<no_response/>` from surfacing as visible partial content.
+ */
+export function isPotentialNoResponsePrefix(text: string): boolean {
+  const lower = text.trim().toLowerCase();
+  if (lower.length === 0) {
+    return false;
+  }
+  return NO_RESPONSE_SENTINEL_FORMS.some((sentinel) =>
+    sentinel.startsWith(lower),
+  );
+}
+
+/**
+ * Whether `text` carries user-visible content worth acting on now. Returns
+ * `false` for empty text, the standalone sentinel, and any prefix that could
+ * still complete into one; returns `true` once real content remains after
+ * stripping inline sentinels.
+ */
+export function hasDeliverableAssistantText(text: string): boolean {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return false;
+  }
+  if (NO_RESPONSE_ONLY_RE.test(trimmed)) {
+    return false;
+  }
+  if (isPotentialNoResponsePrefix(trimmed)) {
+    return false;
+  }
+  return stripNoResponseMarkers(trimmed).length > 0;
+}