@threadbase-sh/streamer 1.37.0 → 1.38.0

package/dist/index.d.cts

@@ -102,6 +102,17 @@ interface FlagDefinition {
 type ClaudeFlagValue = string | string[] | boolean;
 type ClaudeFlagValues = Record<string, ClaudeFlagValue>;
 
+interface FeatureFlagDefinition {
+    /** Stable config/wire key. Used in server.yaml, on the CLI, and over HTTP. */
+    id: string;
+    /** Shipped to clients alongside the values so a UI can render it. */
+    description: string;
+    default: boolean;
+    /** Full env var name. */
+    env: string;
+}
+type FeatureFlagValues = Record<string, boolean>;
+
 declare const CLAUDE_CODE_PROVIDER: "claude-code";
 declare const CODEX_CLI_PROVIDER: "codex-cli";
 type ProviderName = typeof CLAUDE_CODE_PROVIDER | typeof CODEX_CLI_PROVIDER;
@@ -487,6 +498,8 @@ interface ServerConfig {
     tailSize?: number;
     directoryScanDebounceMs?: number;
     defaultSystemPrompt?: string;
+    codexSystemPromptEnabled?: boolean;
+    featureFlags?: FeatureFlagValues;
     defaultPermissionMode?: PermissionMode;
     defaultModel?: string;
     defaultEffort?: "low" | "medium" | "high" | "xhigh" | "max";
@@ -1045,6 +1058,18 @@ declare class ProjectsRepository {
     upsertProjectByPath(rawPath: string, input?: UpsertProjectInput): Project;
 }
 
+/**
+ * Token kinds. A device supplies three non-interchangeable types, and
+ * conflating them fails only at send time with no signal at registration:
+ *
+ * - `expo` — Expo relay token, for ordinary push notifications.
+ * - `liveactivity_start` — ActivityKit push-to-start token. App-wide, one per
+ *   device, long-lived. Starts an activity when none exists.
+ * - `liveactivity_update` — ActivityKit per-activity update token, issued by
+ *   iOS after an activity starts, scoped to that one activity, short-lived.
+ */
+declare const PUSH_TOKEN_KINDS: readonly ["expo", "liveactivity_start", "liveactivity_update"];
+type PushTokenKind = (typeof PUSH_TOKEN_KINDS)[number];
 interface PushTokenRow {
     token: string;
     platform: string;
@@ -1055,6 +1080,13 @@ interface PushTokenRow {
     last_failure_code: string | null;
     failure_streak: number;
     revoked_at: number | null;
+    kind: PushTokenKind;
+    activity_id: string | null;
+    session_id: string | null;
+    expires_at: number | null;
+    stale_date: number | null;
+    started_at: number | null;
+    renewed_at: number | null;
 }
 /**
  * Health as reported to a client. Deliberately omits the token itself — a push
@@ -1071,10 +1103,16 @@ interface PushTokenHealth {
     failureStreak: number;
     revokedAt: number | null;
     /**
-     * Never delivered vs delivering vs failing vs revoked. The distinction the
-     * user actually needs: "not yet" and "broken" look identical without it.
+     * Never delivered vs delivering vs failing vs revoked vs expired. The
+     * distinction the user actually needs: "not yet" and "broken" look identical
+     * without it.
      */
-    state: "never-delivered" | "healthy" | "failing" | "dead" | "revoked";
+    state: "never-delivered" | "healthy" | "failing" | "dead" | "revoked" | "expired";
+    kind: PushTokenKind;
+    /** Present only for per-activity Live Activity tokens. */
+    activityId: string | null;
+    sessionId: string | null;
+    expiresAt: number | null;
 }
 declare class PushRepository {
     private upsertStmt;
@@ -1086,18 +1124,78 @@ declare class PushRepository {
     private revokeStmt;
     private claimEventStmt;
     private markDeliveredStmt;
+    private listByKindSessionStmt;
+    private listByKindStmt;
+    private listRenewableStmt;
+    private claimRenewalStmt;
+    private expireStmt;
+    private expireSessionActivitiesStmt;
     constructor(db: Database.Database);
+    /**
+     * Register or refresh a token.
+     *
+     * `kind` defaults to Expo so a released client posting `{ token, platform }`
+     * keeps working — tb-mobile cannot be force-updated, and every client
+     * predating Live Activities is registering an Expo relay token.
+     *
+     * Several rows per device is normal and intended: a device runs one activity
+     * per live session, each with its own update token. The token itself is the
+     * primary key, so distinct activities never collide.
+     */
     register(args: {
         token: string;
         platform: string;
         deviceId?: string | null;
+        kind?: PushTokenKind;
+        activityId?: string | null;
+        sessionId?: string | null;
+        expiresAt?: number | null;
+        staleDate?: number | null;
+        startedAt?: number | null;
         now?: number;
     }): void;
     get(token: string): PushTokenRow | null;
-    /** Tokens eligible for delivery — not revoked, not past the failure limit. */
+    /**
+     * Expo tokens eligible for delivery — not revoked, not past the failure limit.
+     *
+     * Deliberately Expo-only. ActivityKit tokens go over direct APNs with a
+     * different topic and are rejected by Expo's relay, so the ordinary
+     * notification fan-out must not see them.
+     */
     listDeliverable(): PushTokenRow[];
+    /** Live-activity tokens for one session, eligible for delivery. */
+    listForSession(kind: PushTokenKind, sessionId: string, now?: number): PushTokenRow[];
+    /**
+     * Every deliverable token of one kind.
+     *
+     * Used for push-to-start, which is app-wide rather than session-scoped: the
+     * activity does not exist yet, so there is no per-activity token to look up.
+     */
+    listByKind(kind: PushTokenKind, now?: number): PushTokenRow[];
+    /** Unrenewed activities with a renewal deadline, soonest first. */
+    listRenewable(): PushTokenRow[];
+    /**
+     * Claim a row for renewal.
+     *
+     * Returns true exactly once per row. A restart re-arms timers from the
+     * persisted deadline, so the same renewal can be attempted twice; the loser
+     * gets false and must not send. Doing this as a conditional UPDATE rather
+     * than read-then-write avoids the race where both attempts observe
+     * "not yet renewed".
+     */
+    claimRenewal(token: string, now?: number): boolean;
+    /** Mark one token expired, so it stops being a delivery target. */
+    expire(token: string, now?: number): void;
+    /**
+     * Expire every live activity for a session.
+     *
+     * Called when the session ends. Without this, a per-activity token outlives
+     * its session and a later renewal sweep would resurrect an activity for a
+     * session that is already gone.
+     */
+    expireSessionActivities(sessionId: string, now?: number): void;
     /** Every token, including dead and revoked ones, for the health report. */
-    listHealth(): PushTokenHealth[];
+    listHealth(now?: number): PushTokenHealth[];
     recordSuccess(token: string, now?: number): void;
     recordFailure(token: string, code: string, now?: number): void;
     revoke(token: string, now?: number): boolean;
@@ -1288,6 +1386,10 @@ type ApiDeps = {
         extraArgs: string | null;
         persisted: boolean;
     };
+    featureFlagsConfig: () => {
+        registry: readonly FeatureFlagDefinition[];
+        values: FeatureFlagValues;
+    };
     publicUrl: string | null;
     browseRoot: string | null;
     browserCors: string | undefined;
@@ -1495,6 +1597,8 @@ declare class StreamerServer {
     private sessionInputAttempts;
     private ptyGracePeriodMs;
     private defaultSystemPrompt;
+    private featureFlags;
+    private codexSystemPromptEnabled;
     private defaultPermissionMode;
     private defaultModel;
     private defaultEffort;
@@ -1520,6 +1624,9 @@ declare class StreamerServer {
     private cacheMetadataRepo;
     private pushRepo;
     private devicesRepo;
+    private apnsClient;
+    private liveActivityNotifier;
+    private liveActivityRenewal;
     private discoveryCache;
     private cacheDir;
     private tailSize;
@@ -1560,6 +1667,17 @@ declare class StreamerServer {
      */
     private withReconciledLifecycle;
     private addSessionSubscriber;
+    /**
+     * Bring up Live Activity push, if credentials are present (Feature 12).
+     *
+     * APNS_KEY absent is the ordinary case on a dev machine and in CI, so this
+     * logs once at info and leaves the feature off rather than failing: the server
+     * must not refuse to boot over a missing optional push credential.
+     *
+     * The key is read from the environment as PEM contents and never from a path
+     * on disk; neither it nor any device token is ever logged.
+     */
+    private initLiveActivityPush;
     /**
      * Classify sessions left behind by previous streamer runs (C1 Phase 3a).
      *
@@ -1643,6 +1761,14 @@ declare class StreamerServer {
     private handlePairStart;
     private handlePairExchange;
     private rotateApiKey;
+    /**
+     * The registry ships with the values so a client renders the list from one
+     * round-trip, same as getClaudeFlagsConfig().
+     *
+     * Deliberately no `persisted` field: unlike claude-flags there is no PUT, and
+     * the absence of that field is the signal that this endpoint is read-only.
+     */
+    private getFeatureFlagsConfig;
     private getClaudeFlagsConfig;
     /**
      * Replace the per-server flag set. Applies to the NEXT spawn — a live PTY

package/dist/index.d.ts

@@ -102,6 +102,17 @@ interface FlagDefinition {
 type ClaudeFlagValue = string | string[] | boolean;
 type ClaudeFlagValues = Record<string, ClaudeFlagValue>;
 
+interface FeatureFlagDefinition {
+    /** Stable config/wire key. Used in server.yaml, on the CLI, and over HTTP. */
+    id: string;
+    /** Shipped to clients alongside the values so a UI can render it. */
+    description: string;
+    default: boolean;
+    /** Full env var name. */
+    env: string;
+}
+type FeatureFlagValues = Record<string, boolean>;
+
 declare const CLAUDE_CODE_PROVIDER: "claude-code";
 declare const CODEX_CLI_PROVIDER: "codex-cli";
 type ProviderName = typeof CLAUDE_CODE_PROVIDER | typeof CODEX_CLI_PROVIDER;
@@ -487,6 +498,8 @@ interface ServerConfig {
     tailSize?: number;
     directoryScanDebounceMs?: number;
     defaultSystemPrompt?: string;
+    codexSystemPromptEnabled?: boolean;
+    featureFlags?: FeatureFlagValues;
     defaultPermissionMode?: PermissionMode;
     defaultModel?: string;
     defaultEffort?: "low" | "medium" | "high" | "xhigh" | "max";
@@ -1045,6 +1058,18 @@ declare class ProjectsRepository {
     upsertProjectByPath(rawPath: string, input?: UpsertProjectInput): Project;
 }
 
+/**
+ * Token kinds. A device supplies three non-interchangeable types, and
+ * conflating them fails only at send time with no signal at registration:
+ *
+ * - `expo` — Expo relay token, for ordinary push notifications.
+ * - `liveactivity_start` — ActivityKit push-to-start token. App-wide, one per
+ *   device, long-lived. Starts an activity when none exists.
+ * - `liveactivity_update` — ActivityKit per-activity update token, issued by
+ *   iOS after an activity starts, scoped to that one activity, short-lived.
+ */
+declare const PUSH_TOKEN_KINDS: readonly ["expo", "liveactivity_start", "liveactivity_update"];
+type PushTokenKind = (typeof PUSH_TOKEN_KINDS)[number];
 interface PushTokenRow {
     token: string;
     platform: string;
@@ -1055,6 +1080,13 @@ interface PushTokenRow {
     last_failure_code: string | null;
     failure_streak: number;
     revoked_at: number | null;
+    kind: PushTokenKind;
+    activity_id: string | null;
+    session_id: string | null;
+    expires_at: number | null;
+    stale_date: number | null;
+    started_at: number | null;
+    renewed_at: number | null;
 }
 /**
  * Health as reported to a client. Deliberately omits the token itself — a push
@@ -1071,10 +1103,16 @@ interface PushTokenHealth {
     failureStreak: number;
     revokedAt: number | null;
     /**
-     * Never delivered vs delivering vs failing vs revoked. The distinction the
-     * user actually needs: "not yet" and "broken" look identical without it.
+     * Never delivered vs delivering vs failing vs revoked vs expired. The
+     * distinction the user actually needs: "not yet" and "broken" look identical
+     * without it.
      */
-    state: "never-delivered" | "healthy" | "failing" | "dead" | "revoked";
+    state: "never-delivered" | "healthy" | "failing" | "dead" | "revoked" | "expired";
+    kind: PushTokenKind;
+    /** Present only for per-activity Live Activity tokens. */
+    activityId: string | null;
+    sessionId: string | null;
+    expiresAt: number | null;
 }
 declare class PushRepository {
     private upsertStmt;
@@ -1086,18 +1124,78 @@ declare class PushRepository {
     private revokeStmt;
     private claimEventStmt;
     private markDeliveredStmt;
+    private listByKindSessionStmt;
+    private listByKindStmt;
+    private listRenewableStmt;
+    private claimRenewalStmt;
+    private expireStmt;
+    private expireSessionActivitiesStmt;
     constructor(db: Database.Database);
+    /**
+     * Register or refresh a token.
+     *
+     * `kind` defaults to Expo so a released client posting `{ token, platform }`
+     * keeps working — tb-mobile cannot be force-updated, and every client
+     * predating Live Activities is registering an Expo relay token.
+     *
+     * Several rows per device is normal and intended: a device runs one activity
+     * per live session, each with its own update token. The token itself is the
+     * primary key, so distinct activities never collide.
+     */
     register(args: {
         token: string;
         platform: string;
         deviceId?: string | null;
+        kind?: PushTokenKind;
+        activityId?: string | null;
+        sessionId?: string | null;
+        expiresAt?: number | null;
+        staleDate?: number | null;
+        startedAt?: number | null;
         now?: number;
     }): void;
     get(token: string): PushTokenRow | null;
-    /** Tokens eligible for delivery — not revoked, not past the failure limit. */
+    /**
+     * Expo tokens eligible for delivery — not revoked, not past the failure limit.
+     *
+     * Deliberately Expo-only. ActivityKit tokens go over direct APNs with a
+     * different topic and are rejected by Expo's relay, so the ordinary
+     * notification fan-out must not see them.
+     */
     listDeliverable(): PushTokenRow[];
+    /** Live-activity tokens for one session, eligible for delivery. */
+    listForSession(kind: PushTokenKind, sessionId: string, now?: number): PushTokenRow[];
+    /**
+     * Every deliverable token of one kind.
+     *
+     * Used for push-to-start, which is app-wide rather than session-scoped: the
+     * activity does not exist yet, so there is no per-activity token to look up.
+     */
+    listByKind(kind: PushTokenKind, now?: number): PushTokenRow[];
+    /** Unrenewed activities with a renewal deadline, soonest first. */
+    listRenewable(): PushTokenRow[];
+    /**
+     * Claim a row for renewal.
+     *
+     * Returns true exactly once per row. A restart re-arms timers from the
+     * persisted deadline, so the same renewal can be attempted twice; the loser
+     * gets false and must not send. Doing this as a conditional UPDATE rather
+     * than read-then-write avoids the race where both attempts observe
+     * "not yet renewed".
+     */
+    claimRenewal(token: string, now?: number): boolean;
+    /** Mark one token expired, so it stops being a delivery target. */
+    expire(token: string, now?: number): void;
+    /**
+     * Expire every live activity for a session.
+     *
+     * Called when the session ends. Without this, a per-activity token outlives
+     * its session and a later renewal sweep would resurrect an activity for a
+     * session that is already gone.
+     */
+    expireSessionActivities(sessionId: string, now?: number): void;
     /** Every token, including dead and revoked ones, for the health report. */
-    listHealth(): PushTokenHealth[];
+    listHealth(now?: number): PushTokenHealth[];
     recordSuccess(token: string, now?: number): void;
     recordFailure(token: string, code: string, now?: number): void;
     revoke(token: string, now?: number): boolean;
@@ -1288,6 +1386,10 @@ type ApiDeps = {
         extraArgs: string | null;
         persisted: boolean;
     };
+    featureFlagsConfig: () => {
+        registry: readonly FeatureFlagDefinition[];
+        values: FeatureFlagValues;
+    };
     publicUrl: string | null;
     browseRoot: string | null;
     browserCors: string | undefined;
@@ -1495,6 +1597,8 @@ declare class StreamerServer {
     private sessionInputAttempts;
     private ptyGracePeriodMs;
     private defaultSystemPrompt;
+    private featureFlags;
+    private codexSystemPromptEnabled;
     private defaultPermissionMode;
     private defaultModel;
     private defaultEffort;
@@ -1520,6 +1624,9 @@ declare class StreamerServer {
     private cacheMetadataRepo;
     private pushRepo;
     private devicesRepo;
+    private apnsClient;
+    private liveActivityNotifier;
+    private liveActivityRenewal;
     private discoveryCache;
     private cacheDir;
     private tailSize;
@@ -1560,6 +1667,17 @@ declare class StreamerServer {
      */
     private withReconciledLifecycle;
     private addSessionSubscriber;
+    /**
+     * Bring up Live Activity push, if credentials are present (Feature 12).
+     *
+     * APNS_KEY absent is the ordinary case on a dev machine and in CI, so this
+     * logs once at info and leaves the feature off rather than failing: the server
+     * must not refuse to boot over a missing optional push credential.
+     *
+     * The key is read from the environment as PEM contents and never from a path
+     * on disk; neither it nor any device token is ever logged.
+     */
+    private initLiveActivityPush;
     /**
      * Classify sessions left behind by previous streamer runs (C1 Phase 3a).
      *
@@ -1643,6 +1761,14 @@ declare class StreamerServer {
     private handlePairStart;
     private handlePairExchange;
     private rotateApiKey;
+    /**
+     * The registry ships with the values so a client renders the list from one
+     * round-trip, same as getClaudeFlagsConfig().
+     *
+     * Deliberately no `persisted` field: unlike claude-flags there is no PUT, and
+     * the absence of that field is the signal that this endpoint is read-only.
+     */
+    private getFeatureFlagsConfig;
     private getClaudeFlagsConfig;
     /**
      * Replace the per-server flag set. Applies to the NEXT spawn — a live PTY