@threadbase-sh/streamer 1.63.0 → 1.65.0

package/dist/services/providers/capabilities.d.ts

@@ -0,0 +1,105 @@
+import { type ProviderName } from "../../providers";
+/**
+ * Provider capability declarations (C2).
+ * See docs/architecture/2026-07-24-provider-compatibility.md.
+ *
+ * Every field here is a branch that ALREADY exists somewhere in the codebase —
+ * this promotes it from an implied code path to queryable data. The point is
+ * that a client can ask what a provider supports instead of discovering it by
+ * attempting an action and getting a 501 or a silently wrong result.
+ */
+export interface ProviderCapabilities {
+    /**
+     * How a fresh session gets its id.
+     * `explicit`   — we generate it and pass it in (Claude: `--session-id <uuid>`).
+     * `late-bound` — the CLI creates its own and we discover it afterwards
+     *                (Codex: no `--session-id` equivalent, so the rollout id is
+     *                found by watching the sessions dir after spawn).
+     */
+    freshSessionId: "explicit" | "late-bound";
+    /** Whether the CLI can replay a prior transcript from an id. */
+    resume: "native" | "unsupported";
+    /**
+     * How a system prompt reaches the CLI.
+     * `flag`       — a dedicated flag (Claude: `--system-prompt`).
+     * `positional` — passed as the opening turn (Codex has no flag).
+     */
+    systemPrompt: "flag" | "positional" | "unsupported";
+    /** We can detect and parse structured question menus from the TUI. */
+    structuredQuestions: boolean;
+    /** We can detect permission/trust gates and answer them programmatically. */
+    permissionGates: boolean;
+    /**
+     * We can send input to a live session. False means read-only observation —
+     * the honest state for a provider whose input path we do not understand.
+     */
+    liveControl: boolean;
+}
+/**
+ * Provider versions an adapter's parsing and detection were captured against.
+ *
+ * `captured` lists the versions we hold fixtures for. `min`/`max` bound the
+ * range we claim to support. A provider outside that range still runs — it just
+ * reports a compatibility warning rather than pretending to be verified.
+ */
+export interface VerifiedAgainst {
+    min?: string;
+    max?: string;
+    captured: string[];
+}
+/**
+ * Outcome of normalizing one native-history line.
+ *
+ * The `ignored` / `unknown` split is the reason this type exists. Today every
+ * non-chat line returns null (src/utils/codexConversationLine.ts), so "a
+ * session_meta header we deliberately skip" and "a shape this adapter has never
+ * seen" are indistinguishable — and a provider schema change therefore renders
+ * an empty conversation with no error at all.
+ */
+export type NormalizeResult = 
+/** Recognized chat content, normalized to the client-facing shape. */
+{
+    kind: "message";
+    line: string;
+}
+/** Recognized, but deliberately not rendered (headers, dupes, injected context). */
+ | {
+    kind: "ignored";
+    reason: string;
+}
+/** NOT recognized. Counted and surfaced as a compatibility signal. */
+ | {
+    kind: "unknown";
+    raw: string;
+    reason: string;
+};
+/**
+ * The descriptive half of a provider integration. `SessionRunner` (types.ts) is
+ * the behavioural half — how to spawn and drive the CLI. This is what the
+ * integration claims about itself, so adding a provider means implementing a
+ * declared surface rather than copying a runner and hoping.
+ */
+export interface ProviderAdapter {
+    name: ProviderName;
+    capabilities: ProviderCapabilities;
+    verifiedAgainst: VerifiedAgainst;
+    /** Installed provider version, or null when it cannot be determined. */
+    detectVersion(): Promise<string | null>;
+    /** Classify one raw native-history line. Never silently discards. */
+    normalizeLine(line: string): NormalizeResult;
+}
+export declare const CLAUDE_CODE_CAPABILITIES: ProviderCapabilities;
+export declare const CODEX_CLI_CAPABILITIES: ProviderCapabilities;
+/**
+ * Capabilities for a provider we do not recognize.
+ *
+ * This is the generic-terminal fallback: stream bytes, accept input, and claim
+ * no semantic understanding. It exists because the current behaviour is worse —
+ * `coerceProviderForRunner` (providers.ts) silently maps an unknown provider to
+ * claude-code, so an unrecognized CLI gets driven with Claude's argv, Claude's
+ * markers, and Claude's env scrubbing. Admitting we don't know beats asserting
+ * the wrong thing.
+ */
+export declare const GENERIC_TERMINAL_CAPABILITIES: ProviderCapabilities;
+export declare function capabilitiesFor(provider: ProviderName): ProviderCapabilities;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/services/providers/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/services/providers/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4C,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE9F;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,cAAc,EAAE,UAAU,GAAG,YAAY,CAAC;IAC1C,gEAAgE;IAChE,MAAM,EAAE,QAAQ,GAAG,aAAa,CAAC;IACjC;;;;OAIG;IACH,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,aAAa,CAAC;IACpD,sEAAsE;IACtE,mBAAmB,EAAE,OAAO,CAAC;IAC7B,6EAA6E;IAC7E,eAAe,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe;AACzB,sEAAsE;AACpE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACnC,oFAAoF;GAClF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACrC,sEAAsE;GACpE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,oBAAoB,CAAC;IACnC,eAAe,EAAE,eAAe,CAAC;IACjC,wEAAwE;IACxE,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxC,qEAAqE;IACrE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC;CAC9C;AAaD,eAAO,MAAM,wBAAwB,EAAE,oBAOtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,oBAOpC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,EAAE,oBAO3C,CAAC;AAEF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,oBAAoB,CAO5E"}

package/dist/services/providers/providerHealth.d.ts

@@ -0,0 +1,72 @@
+import { type ProviderName } from "../../providers";
+import { type ProviderCapabilities, type VerifiedAgainst } from "./capabilities";
+/**
+ * Provider version detection and compatibility reporting (C2).
+ * See docs/architecture/2026-07-24-provider-compatibility.md.
+ *
+ * Our parsing and TUI detection are calibrated against specific provider
+ * versions — the fixtures under __tests__/fixtures/providers/<provider>/<version>
+ * record which. This module compares what is actually installed against that,
+ * so drift is reported instead of surfacing as a mysteriously stuck session.
+ *
+ * A warning is never a refusal. A provider working slightly outside our verified
+ * range is vastly better than us blocking it.
+ */
+/** Versions each adapter's fixtures were captured against. */
+export declare const VERIFIED_AGAINST: Record<ProviderName, VerifiedAgainst>;
+export type ProviderWarningCode = 
+/** The CLI is not installed, or not on PATH. */
+"provider_not_found"
+/** Installed, but we could not read a version from it. */
+ | "version_undetectable"
+/** Installed and readable, but outside the range our fixtures cover. */
+ | "version_unverified";
+export interface ProviderWarning {
+    code: ProviderWarningCode;
+    message: string;
+}
+export interface ProviderHealth {
+    name: ProviderName;
+    available: boolean;
+    version: string | null;
+    verifiedAgainst: VerifiedAgainst;
+    capabilities: ProviderCapabilities;
+    warnings: ProviderWarning[];
+}
+/**
+ * Run `<exe> --version` and return the first version-looking token.
+ *
+ * Deliberately tolerant: providers format this line differently and change it
+ * between releases, so we scrape a semver-shaped substring rather than assume a
+ * layout. Any failure yields null, which the caller treats as "unverified"
+ * rather than "incompatible" — an unreadable version is not evidence of a
+ * problem with the provider.
+ */
+export declare function parseVersionOutput(output: string): string | null;
+/**
+ * Compare a detected version against the range an adapter claims to cover.
+ *
+ * Only `min` is enforced as a floor. There is deliberately no upper bound check
+ * beyond `max` when set: providers release constantly, and refusing to run
+ * against a version merely newer than our newest fixture would break users on
+ * every provider update for no evidence of an actual incompatibility.
+ */
+export declare function compareToVerified(version: string | null, verified: VerifiedAgainst): ProviderWarning | null;
+/**
+ * Compare two semver-ish strings. Prerelease suffixes sort BELOW the same
+ * release (0.140.0-alpha.19 < 0.140.0), matching semver, so a prerelease we
+ * captured does not read as newer than the release it precedes.
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Resolve health for one provider. `locateExe` is injected so tests can drive
+ * detection without depending on what happens to be installed on the machine;
+ * it defaults to the same `locateProviderExe` the session-start pre-flight
+ * uses. Sharing that one entry point is load-bearing rather than tidy: it
+ * clears the memoized resolution on a miss, so a health check and a start
+ * attempt cannot reach opposite conclusions about the same machine — which is
+ * what happened when this called `locateExecutable(resolveExe())` directly and
+ * left a stale absolute path (the normal case under launchd) in place.
+ */
+export declare function providerHealth(name: ProviderName, locateExe?: () => string | null, detect?: (exe: string) => Promise<string | null>): Promise<ProviderHealth>;
+//# sourceMappingURL=providerHealth.d.ts.map

package/dist/services/providers/providerHealth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providerHealth.d.ts","sourceRoot":"","sources":["../../../src/services/providers/providerHealth.ts"],"names":[],"mappings":"AAEA,OAAO,EAA4C,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAmB,KAAK,oBAAoB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAElG;;;;;;;;;;;GAWG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,YAAY,EAAE,eAAe,CAGlE,CAAC;AAEF,MAAM,MAAM,mBAAmB;AAC7B,gDAAgD;AAC9C,oBAAoB;AACtB,0DAA0D;GACxD,sBAAsB;AACxB,wEAAwE;GACtE,oBAAoB,CAAC;AAEzB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,eAAe,EAAE,eAAe,CAAC;IACjC,YAAY,EAAE,oBAAoB,CAAC;IACnC,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAID;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AA+CD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,QAAQ,EAAE,eAAe,GACxB,eAAe,GAAG,IAAI,CAyBxB;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB1D;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,YAAY,EAClB,SAAS,GAAE,MAAM,MAAM,GAAG,IAAoC,EAC9D,MAAM,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAc,GAC3D,OAAO,CAAC,cAAc,CAAC,CAqDzB"}

package/dist/services/push/apnsClient.d.ts

@@ -0,0 +1,105 @@
+/** Sandbox default: the app's `aps-environment` is still `development`. */
+export declare const APNS_HOST_SANDBOX = "api.sandbox.push.apple.com";
+export declare const APNS_HOST_PRODUCTION = "api.push.apple.com";
+/**
+ * APNs rejects a payload over 4 KB.
+ *
+ * Checked before sending rather than after a rejection, so an oversized payload
+ * is a diagnosable local error instead of an opaque 413 from Apple.
+ */
+export declare const APNS_MAX_PAYLOAD_BYTES = 4096;
+export interface ApnsCredentials {
+    /** p8 PEM contents. Never a filesystem path. */
+    key: string;
+    keyId: string;
+    teamId: string;
+    bundleId: string;
+    host: string;
+}
+export interface ApnsSendResult {
+    ok: boolean;
+    status: number;
+    /** APNs `reason`, e.g. `BadDeviceToken` / `ExpiredToken`. */
+    reason?: string;
+    /**
+     * True when APNs says this token will never work again. The caller must stop
+     * using it rather than retrying — retrying a dead token fails forever and
+     * makes the health report read "failing" instead of "this device is gone".
+     */
+    tokenDead: boolean;
+}
+/**
+ * Read APNs credentials from the environment.
+ *
+ * Returns null when `APNS_KEY` is absent, which is the normal case for a
+ * developer machine and for CI. Callers treat null as "Live Activity push is
+ * off" and skip sending — the server must not fail to boot because an optional
+ * push credential is missing.
+ *
+ * Every identifier comes from the environment with no default. Baking one
+ * deployment's Apple account into the source would make this package silently
+ * sign for the wrong team when someone else deploys it, and the resulting APNs
+ * rejection names none of that. Only the host has a default, because sandbox
+ * versus production is a deployment choice rather than an account identity.
+ *
+ * Returns null (rather than throwing) when the key is present but an identifier
+ * is missing, so a half-configured environment disables the feature instead of
+ * taking the server down. `describeMissingApnsCredentials` explains which one.
+ */
+export declare function readApnsCredentialsFromEnv(env?: NodeJS.ProcessEnv): ApnsCredentials | null;
+/**
+ * Why Live Activity push is unavailable, as a message safe to log.
+ *
+ * Says which variable is missing and nothing about its value, so a boot log can
+ * explain the feature being off without becoming a place secrets leak.
+ */
+export declare function describeMissingApnsCredentials(env?: NodeJS.ProcessEnv): string | null;
+export declare class ApnsClient {
+    private readonly creds;
+    private session;
+    private cachedJwt;
+    constructor(creds: ApnsCredentials);
+    /**
+     * The `apns-topic` for Live Activity pushes.
+     *
+     * The `.push-type.liveactivity` suffix is mandatory and is why the signing key
+     * must be Team Scoped (All Topics) — a key scoped to the bundle id alone
+     * cannot sign this topic.
+     */
+    get topic(): string;
+    /**
+     * Mint or reuse the provider JWT.
+     *
+     * ES256 over the p8 key. Cached until shortly before expiry: Apple rejects a
+     * token older than an hour, but minting one per request is wasteful and can
+     * trip APNs' provider-token-update throttle.
+     */
+    private getJwt;
+    /**
+     * Reuse one HTTP/2 session across sends.
+     *
+     * APNs expects a long-lived connection; a fresh TLS handshake per push is slow
+     * and Apple treats connection churn as abuse.
+     */
+    private getSession;
+    /**
+     * Send one push.
+     *
+     * Resolves with a result rather than rejecting on an APNs rejection: a
+     * rejected push is an expected outcome the caller must act on (retire the
+     * token), not an exception. Only a genuinely unexpected local failure throws,
+     * and the caller logs it.
+     */
+    send(args: {
+        deviceToken: string;
+        payload: unknown;
+        /** 10 for a user-visible change, 5 to let iOS batch. */
+        priority?: 5 | 10;
+        /** Seconds since epoch after which APNs stops trying. */
+        expirationSeconds?: number;
+        timeoutMs?: number;
+    }): Promise<ApnsSendResult>;
+    /** Close the shared connection. Called on server shutdown. */
+    close(): void;
+}
+//# sourceMappingURL=apnsClient.d.ts.map

package/dist/services/push/apnsClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apnsClient.d.ts","sourceRoot":"","sources":["../../../src/services/push/apnsClient.ts"],"names":[],"mappings":"AAuBA,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,+BAA+B,CAAC;AAC9D,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAS3C,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAmBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,eAAe,GAAG,IAAI,CAYxB;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,IAAI,CA2Bf;AAED,qBAAa,UAAU;IAIT,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,SAAS,CAAqD;IAEtE,YAA6B,KAAK,EAAE,eAAe,EAAI;IAEvD;;;;;;OAMG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;OAMG;IACH,OAAO,CAAC,MAAM;IAsBd;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAclB;;;;;;;OAOG;IACG,IAAI,CAAC,IAAI,EAAE;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,OAAO,CAAC;QACjB,wDAAwD;QACxD,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC;QAClB,yDAAyD;QACzD,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,cAAc,CAAC,CAiE1B;IAED,8DAA8D;IAC9D,KAAK,IAAI,IAAI,CAGZ;CACF"}

package/dist/services/push/expoPushSender.d.ts

@@ -0,0 +1,37 @@
+import type { PushRepository } from "../../db/repositories/push.repository";
+export declare const EXPO_PUSH_ENDPOINT = "https://exp.host/--/api/v2/push/send";
+/** Expo accepts at most 100 messages per request. */
+export declare const EXPO_PUSH_BATCH_SIZE = 100;
+export interface ExpoPushMessage {
+    title: string;
+    body: string;
+    /** Delivered to the app as `notification.request.content.data`. */
+    data: Record<string, string>;
+}
+export interface ExpoPushOutcome {
+    attempted: number;
+    succeeded: number;
+    /** Tokens Expo rejected as permanently dead, now revoked locally. */
+    retired: number;
+}
+export declare class ExpoPushSender {
+    private readonly repo;
+    private readonly accessToken?;
+    /**
+     * @param accessToken Expo access token, when the project has enhanced
+     * security enabled. Optional on purpose: a self-hoster does not own the Expo
+     * project and cannot obtain one, so requiring it would break the deployment
+     * this transport exists to serve.
+     */
+    constructor(repo: PushRepository, accessToken?: string | undefined);
+    /**
+     * Send one message to every deliverable Expo token.
+     *
+     * Sends are independent: Expo returns a ticket per token in one response, so
+     * a dead device is recorded against its own row and never silences the other
+     * devices in the batch.
+     */
+    send(message: ExpoPushMessage, now?: number): Promise<ExpoPushOutcome>;
+    private sendChunk;
+}
+//# sourceMappingURL=expoPushSender.d.ts.map

package/dist/services/push/expoPushSender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expoPushSender.d.ts","sourceRoot":"","sources":["../../../src/services/push/expoPushSender.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,uCAAuC,CAAC;AAmB1F,eAAO,MAAM,kBAAkB,yCAAyC,CAAC;AAEzE,qDAAqD;AACrD,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAiBD,qBAAa,cAAc;IAQvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAR/B;;;;;OAKG;IACH,YACmB,IAAI,EAAE,cAAc,EACpB,WAAW,CAAC,EAAE,MAAM,YAAA,EACnC;IAEJ;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,eAAe,CAAC,CAUvF;YAEa,SAAS;CA0ExB"}

package/dist/services/push/liveActivityContentState.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The Live Activity content-state contract, shared with tb-mobile.
+ *
+ * tb-mobile defines the mirror of this shape in `types/live-activity.ts` and
+ * decodes it with a Swift `Codable` ActivityAttributes struct. A decode failure
+ * in ActivityKit is silent — the Lock Screen surface simply stops updating,
+ * with no error anywhere on the server — so a field name or type drifting apart
+ * from mobile's struct breaks the feature invisibly. Treat this file as a
+ * contract, not an internal type: changing it requires a coordinated tb-mobile
+ * change.
+ */
+/**
+ * Statuses the surface renders. Deliberately narrower than the server's
+ * `SessionStatus`: `idle` has no Live Activity representation, because a session
+ * that is no longer live gets an `end` event rather than an update carrying a
+ * third status mobile has no case for.
+ */
+export type LiveActivityStatus = "running" | "waiting_input";
+/** Longest `lastOutput` sent. Mobile truncates to the same bound. */
+export declare const LAST_OUTPUT_MAX_LENGTH = 90;
+export interface LiveActivityContentState {
+    sessionId: string;
+    serverId: string;
+    projectName: string;
+    status: LiveActivityStatus;
+    /**
+     * Epoch **milliseconds** of the session's start.
+     *
+     * iOS renders its own ticking elapsed timer from this, so the server must
+     * never send a precomputed elapsed value and never push per-second updates.
+     * Carried unchanged across a renewal — a fresh value makes the user's visible
+     * timer reset to zero.
+     */
+    startedAt: number;
+    lastOutput: string;
+    serverLabel?: string;
+    /**
+     * User-visible session title, derived from the first user message.
+     *
+     * Absent until the first message is submitted (a session between spawn and
+     * that point has no title yet); mobile falls back to `projectName` when unset.
+     */
+    sessionName?: string;
+}
+/**
+ * Collapse a server session status onto the two the surface renders.
+ *
+ * Returns null for a status with no representation, which is the signal to send
+ * an `end` rather than an update.
+ */
+export declare function toLiveActivityStatus(status: string): LiveActivityStatus | null;
+/**
+ * Trim terminal output to the field's bound.
+ *
+ * Terminal output is unbounded and the whole APNs payload must stay under 4 KB,
+ * so this is what keeps a chatty session from producing a rejected push.
+ * Newlines collapse to spaces because the surface renders a single line.
+ */
+export declare function truncateLastOutput(raw: string): string;
+//# sourceMappingURL=liveActivityContentState.d.ts.map

package/dist/services/push/liveActivityContentState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveActivityContentState.d.ts","sourceRoot":"","sources":["../../../src/services/push/liveActivityContentState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,eAAe,CAAC;AAE7D,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKtD"}

package/dist/services/push/liveActivityNotifier.d.ts

@@ -0,0 +1,49 @@
+import type { ManagedSession } from "../../types";
+import { type LiveActivityContentState } from "./liveActivityContentState";
+import type { LiveActivitySender } from "./liveActivitySender";
+/**
+ * Build the content state mobile decodes.
+ *
+ * `startedAt` comes from the session's own start and is passed through in epoch
+ * milliseconds: iOS renders its own ticking timer from it, so the server must
+ * never compute an elapsed value.
+ */
+export declare function contentStateForSession(args: {
+    session: ManagedSession;
+    serverId: string;
+    serverLabel?: string;
+    /** Overrides the session's own start — used by a renewal to preserve continuity. */
+    startedAtOverride?: number | null;
+}): LiveActivityContentState | null;
+export declare class LiveActivityNotifier {
+    private readonly sender;
+    private readonly serverId;
+    private readonly serverLabel?;
+    /**
+     * Sessions with a currently open (pushed) activity.
+     *
+     * An activity opens on a `waiting_input → running` edge (the user sent a
+     * prompt) and closes on the matching `running → waiting_input` edge (the
+     * response, including any sub-agents, finished) — so this set is what makes
+     * the notifier per-turn rather than per-session. A session's very first
+     * `running` (right after spawn, before any user prompt) has no prior
+     * `waiting_input` and therefore no edge, so it never opens an activity —
+     * this is what keeps a fresh/idle session from pushing anything.
+     */
+    private openActivity;
+    constructor(sender: LiveActivitySender, serverId: string, serverLabel?: string | undefined);
+    /**
+     * React to a session status change.
+     *
+     * Fire-and-forget by design: a push must never delay or fail a session
+     * transition, so this returns a promise the caller may ignore and every error
+     * is logged rather than propagated.
+     */
+    onStatusChange(session: ManagedSession, previousStatus?: string): Promise<void>;
+    private startTurn;
+    private maybeSendName;
+    private endFor;
+    /** Drop cached state for a session, so a resume re-opens on its next turn. */
+    forget(sessionId: string): void;
+}
+//# sourceMappingURL=liveActivityNotifier.d.ts.map

package/dist/services/push/liveActivityNotifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveActivityNotifier.d.ts","sourceRoot":"","sources":["../../../src/services/push/liveActivityNotifier.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,KAAK,wBAAwB,EAG9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAuB/D;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC,GAAG,wBAAwB,GAAG,IAAI,CAgBlC;AAED,qBAAa,oBAAoB;IAe7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAhB/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY,CAAmD;IAEvE,YACmB,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,YAAA,EACnC;IAEJ;;;;;;OAMG;IACG,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCpF;YAEa,SAAS;YAwBT,aAAa;YA2Bb,MAAM;IAuBpB,8EAA8E;IAC9E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE9B;CACF"}

package/dist/services/push/liveActivityRenewal.d.ts

@@ -0,0 +1,63 @@
+import type { PushRepository, PushTokenRow } from "../../db/repositories/push.repository";
+import type { SessionStore } from "../../session-store";
+import { type LiveActivitySender } from "./liveActivitySender";
+/**
+ * How long before the cap to renew.
+ *
+ * Far enough out that a missed tick or a slow APNs round trip still lands inside
+ * the window, close enough that the replacement activity gets a nearly full
+ * 8-hour lifetime of its own.
+ */
+export declare const RENEWAL_LEAD_MS: number;
+export interface LiveActivityRenewalDeps {
+    repo: PushRepository;
+    sender: LiveActivitySender;
+    sessionStore: SessionStore;
+    serverId: string;
+    serverLabel?: string;
+    /** Injected in tests; production uses the real clock. */
+    now?: () => number;
+}
+/** When a row should be renewed: its cap, minus the lead time. */
+export declare function renewalDueAt(row: PushTokenRow): number | null;
+export declare class LiveActivityRenewalScheduler {
+    private readonly deps;
+    private timer;
+    private stopped;
+    private readonly now;
+    constructor(deps: LiveActivityRenewalDeps);
+    /**
+     * Arm the scheduler from persisted state.
+     *
+     * Called on boot, which is what makes a renewal survive a restart: the
+     * deadlines were never in memory to begin with.
+     */
+    start(): void;
+    stop(): void;
+    /**
+     * Renew everything due, then sleep until the next deadline.
+     *
+     * Re-reads from the DB every tick rather than caching a schedule in memory, so
+     * an activity registered after boot is picked up without re-arming anything.
+     */
+    tick(): Promise<void>;
+    private scheduleNext;
+    /**
+     * Renew one activity.
+     *
+     * Claims first: `claimRenewal()` succeeds exactly once per row, so a timer
+     * re-armed after a restart mid-window cannot send a second time.
+     */
+    private renew;
+    /**
+     * Ask the device to start a replacement activity.
+     *
+     * Uses the app-wide push-to-start token, because the replacement does not
+     * exist yet and therefore has no per-activity token. Returns false when the
+     * device never registered one, which is not an error: the app simply cannot be
+     * asked to start an activity remotely, and the next foreground WS update
+     * recreates it.
+     */
+    private startReplacement;
+}
+//# sourceMappingURL=liveActivityRenewal.d.ts.map

package/dist/services/push/liveActivityRenewal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveActivityRenewal.d.ts","sourceRoot":"","sources":["../../../src/services/push/liveActivityRenewal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAE1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAwBzF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAiB,CAAC;AAW9C,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAE7D;AAED,qBAAa,4BAA4B;IAK3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,YAA6B,IAAI,EAAE,uBAAuB,EAEzD;IAED;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAGZ;IAED,IAAI,IAAI,IAAI,CAMX;IAED;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAoB1B;IAED,OAAO,CAAC,YAAY;IAmBpB;;;;;OAKG;YACW,KAAK;IAgFnB;;;;;;;;OAQG;YACW,gBAAgB;CAgC/B"}

package/dist/services/push/liveActivitySender.d.ts

@@ -0,0 +1,88 @@
+import type { PushRepository, PushTokenRow } from "../../db/repositories/push.repository";
+import type { ApnsClient } from "./apnsClient";
+import type { LiveActivityContentState } from "./liveActivityContentState";
+/** iOS ends a Live Activity ~8h after it starts. */
+export declare const ACTIVITY_MAX_LIFETIME_MS: number;
+export type LiveActivityEvent = "update" | "end";
+export interface LiveActivitySendOutcome {
+    attempted: number;
+    succeeded: number;
+    /** Tokens APNs rejected as permanently unusable, now expired locally. */
+    retired: number;
+}
+/**
+ * The APNs `aps` envelope for an ActivityKit push.
+ *
+ * Key names are Apple's and are not ours to choose: `content-state`,
+ * `stale-date`, and `dismissal-date` are hyphenated, while `timestamp` and
+ * `event` are not.
+ */
+interface ActivityKitPayload {
+    aps: {
+        /** Seconds since epoch. iOS discards a push whose timestamp regresses. */
+        timestamp: number;
+        event: LiveActivityEvent;
+        "content-state": LiveActivityContentState;
+        /** Seconds since epoch. When iOS should start showing the content as stale. */
+        "stale-date"?: number;
+        "dismissal-date"?: number;
+    };
+}
+export declare function buildActivityKitPayload(args: {
+    event: LiveActivityEvent;
+    contentState: LiveActivityContentState;
+    now: number;
+    staleDate?: number | null;
+    dismissalDate?: number | null;
+}): ActivityKitPayload;
+export declare class LiveActivitySender {
+    private readonly apns;
+    private readonly repo;
+    constructor(apns: ApnsClient, repo: PushRepository);
+    /**
+     * Push to every live activity of a session.
+     *
+     * Sends are independent: one rejected token must not stop the others, because
+     * a single dead device would otherwise silence every other device watching the
+     * same session.
+     */
+    send(args: {
+        sessionId: string;
+        event: LiveActivityEvent;
+        contentState: LiveActivityContentState;
+        now?: number;
+        priority?: 5 | 10;
+    }): Promise<LiveActivitySendOutcome>;
+    /**
+     * Push to an explicit token list.
+     *
+     * Renewal needs this: a replacement activity does not exist yet, so it is
+     * started via the app-wide push-to-start token rather than any per-session
+     * lookup. Shares one fan-out body with `send()` so failure handling cannot
+     * drift between the two paths.
+     */
+    sendToTokens(args: {
+        tokens: PushTokenRow[];
+        sessionId: string;
+        event: LiveActivityEvent;
+        contentState: LiveActivityContentState;
+        now?: number;
+        priority?: 5 | 10;
+        /** Overrides the row's own cap — renewal sets the replacement's window. */
+        staleDate?: number | null;
+    }): Promise<LiveActivitySendOutcome>;
+    /**
+     * End every live activity for a session and stop tracking them.
+     *
+     * Expiring locally is what stops the renewal sweep from later resurrecting an
+     * activity for a session that has already finished.
+     */
+    end(args: {
+        sessionId: string;
+        contentState: LiveActivityContentState;
+        now?: number;
+    }): Promise<LiveActivitySendOutcome>;
+    private sendToToken;
+}
+export {};
+//# sourceMappingURL=liveActivitySender.d.ts.map

package/dist/services/push/liveActivitySender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveActivitySender.d.ts","sourceRoot":"","sources":["../../../src/services/push/liveActivitySender.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAE1F,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAa3E,oDAAoD;AACpD,eAAO,MAAM,wBAAwB,QAAqB,CAAC;AAE3D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEjD,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,UAAU,kBAAkB;IAC1B,GAAG,EAAE;QACH,0EAA0E;QAC1E,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,iBAAiB,CAAC;QACzB,eAAe,EAAE,wBAAwB,CAAC;QAC1C,+EAA+E;QAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,KAAK,EAAE,iBAAiB,CAAC;IACzB,YAAY,EAAE,wBAAwB,CAAC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,GAAG,kBAAkB,CAYrB;AAED,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFvB,YACmB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,cAAc,EACnC;IAEJ;;;;;;OAMG;IACG,IAAI,CAAC,IAAI,EAAE;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,iBAAiB,CAAC;QACzB,YAAY,EAAE,wBAAwB,CAAC;QACvC,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC;KACnB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAUnC;IAED;;;;;;;OAOG;IACG,YAAY,CAAC,IAAI,EAAE;QACvB,MAAM,EAAE,YAAY,EAAE,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,iBAAiB,CAAC;QACzB,YAAY,EAAE,wBAAwB,CAAC;QACvC,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC;QAClB,2EAA2E;QAC3E,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA0DnC;IAED;;;;;OAKG;IACG,GAAG,CAAC,IAAI,EAAE;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,wBAAwB,CAAC;QACvC,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAUnC;YAEa,WAAW;CAwB1B"}