@maudecode/talaria-web 1.17.2 → 1.19.0

package/dist/tools/updates.d.ts

@@ -1,15 +1,23 @@
+export { backupPersistedStores, CHANNEL_SWITCH_BACKUPS } from '../sessions/storage/json-installation.js';
+import { type AgentRecoveryState, type RuntimeDescribe, type SidecarResult } from '@maudecode/talaria-web-contracts';
 import type { Dict } from '../config/agent-config.js';
 export declare const REPOSITORY = "MaudeCode/talaria";
 export declare const REPOSITORY_URL = "https://github.com/MaudeCode/talaria";
 export declare const API_ROOT = "https://api.github.com/repos/MaudeCode/talaria";
-/** Anchored paths work from both the git root and Web's nested working directory. */
-export declare const WEB_UPDATE_PATHS: string[];
 export declare const CACHE_TTL_S = 1800;
 export declare const AUTO_UPDATE_INTERVAL_MS: number;
 export declare const RESTART_MAX_WAIT_S = 300;
 export declare const DEFAULT_CHANNEL = "stable";
 export type Channel = 'stable' | 'experimental';
 export declare const normalizeChannel: (channel: unknown) => Channel;
+/** TAL-946: one Stable release newer than the installed one; an apply names it by `ref`. */
+export interface UpdateVersion {
+    version: string;
+    ref: string;
+    sha?: string;
+    release_url: string | null;
+}
+export declare const ONLY_STABLE_VERSIONS = "Choosing a version is available only on the Stable channel.";
 export interface GitOutcome {
     out: string;
     ok: boolean;
@@ -36,9 +44,13 @@ export declare class ReleaseUnavailable extends Error {
 export type GetJson = (path: string, opts: {
     asset: boolean;
 }) => Promise<unknown>;
-/** GitHub API client: opt-in `TALARIA_RELEASE_TOKEN`, 2 MB cap, and asset redirects only to GitHub's release host with the token stripped. */
-export declare function githubJson(fetchImpl: typeof fetch, env: Record<string, string | undefined>): GetJson;
-export interface PublishedRelease {
+/**
+ * GitHub API client: opt-in `TALARIA_RELEASE_TOKEN`, 2 MB cap, and asset redirects only to GitHub's release host with the token stripped.
+ * `root` defaults to Talaria's repository; any other root (the public Agent repository) is read anonymously.
+ */
+export declare function githubJson(fetchImpl: typeof fetch, env: Record<string, string | undefined>, root?: string): GetJson;
+/** One completed release set's Web component. */
+export interface WebRelease {
     tag: string;
     version: string;
     sourceRevision: string;
@@ -48,8 +60,19 @@ export interface PublishedRelease {
     manifestReleaseSet: string;
     runtime: Dict;
     release_url: string;
+}
+export interface PublishedRelease extends WebRelease {
     /** Completed channel releases newer than the `installed` version passed to `publishedWebRelease`, this one included; 1 when it was not passed. */
     releasesBehind: number;
+    /** The published notes of the releases `releasesBehind` counts, oldest first; only this release's when `installed` was not passed. */
+    notes: ReleaseNote[];
+    /** TAL-946: the counted releases whose release set is fully valid, in publication order from this one. */
+    versions: WebRelease[];
+}
+/** One release's published notes, for update summaries. */
+export interface ReleaseNote {
+    tag: string;
+    body: string;
 }
 /**
  * Python `published_web_release`: the newest completed `release-set-<sha>` whose Web component matches the channel's tag family.
@@ -92,31 +115,46 @@ export interface ReleaseIdentity {
 }
 /** Python `check_web_update`: npm and packaged installs; a source checkout is contributor-only (TAL-379). */
 export declare function checkWebUpdate(webRoot: string | null, currentVersion: string, channel: Channel, git: GitRun, getJson: GetJson, id: ReleaseIdentity, npmRun?: BuildRun, registry?: ExperimentalRegistry): Promise<Dict>;
-/** Packaged-install collaborators: the Experimental registry and Web's state dir for channel-switch backups. */
+/** Packaged-install collaborators: the Experimental registry, Web's state dir for channel-switch backups, and the candidate self-check timeout. */
 export interface PackagedUpdateOptions {
     registry?: ExperimentalRegistry | undefined;
     stateDir?: string | undefined;
+    selfCheckTimeoutMs?: number | undefined;
+    skipFailedVersion?: boolean | undefined;
 }
-export declare const CHANNEL_SWITCH_BACKUPS = 5;
-/** Copy the persisted stores to `<stateDir>/backups/channel-switch-<UTC timestamp>/`, keeping the newest few; throws on failure. */
-export declare function backupPersistedStores(stateDir: string, now?: Date, keep?: number): string;
 /** Python `apply_web_update`: installs npm releases; a source checkout is never mutated (TAL-379). */
-export declare function applyWebUpdate(webRoot: string | null, channel: Channel, git: GitRun, getJson: GetJson, id: ReleaseIdentity, npmRun?: BuildRun, canApply?: () => boolean, packaged?: PackagedUpdateOptions): Promise<Dict>;
+export declare function applyWebUpdate(webRoot: string | null, channel: Channel, git: GitRun, getJson: GetJson, id: ReleaseIdentity, npmRun?: BuildRun, canApply?: () => boolean, packaged?: PackagedUpdateOptions, version?: string): Promise<Dict>;
+/** TAL-930: the tag of the Agent remote's latest published GitHub release (not draft, not prerelease, strict `vX.Y.Z`); null when GitHub cannot say. */
+export type PublishedAgentTag = (repoUrl: string) => Promise<string | null>;
+export declare const publishedAgentTag: (getJson: GetJson) => PublishedAgentTag;
 export interface AgentUpdatePolicy {
+    /** `sourceRevision`s of the verified Agent window (`sidecar/agent_support.json`). */
+    supportedRevisions: readonly string[];
+    /** The deployment pin, named in the confirmation identity. */
     supportedRevision: string;
     supportedVersion: string;
     confirmedRevision?: string;
+    /** Resolved main and named-profile homes sharing this Agent installation. Read again for every attempt. */
+    retainedStateHomes?: () => readonly string[];
+    repairPending?: boolean;
+    withMutation?: (path: string, revision: string, mutate: (git: GitRun) => Promise<Dict>) => Promise<Dict>;
+    beforeMutation?: (path: string, revision: string) => Promise<void>;
 }
-export interface AgentUpdateOptions {
+/** `version` (TAL-946) names a listed Stable release `ref` for either target; omitted, an update takes the newest. */
+export interface UpdateOptions {
+    skipFailedVersion?: boolean | undefined;
     agentChannel?: Channel | undefined;
     confirmedRevision?: string | undefined;
+    version?: string | undefined;
+    refreshToken?: string | undefined;
+    mutationIntent?: string | undefined;
 }
 /** Fetch and compare the independently selected Agent channel. */
-export declare function checkAgentUpdate(path: string | null, git: GitRun, channel?: Channel): Promise<Dict>;
+export declare function checkAgentUpdate(path: string | null, git: GitRun, channel?: Channel, published?: PublishedAgentTag): Promise<Dict>;
 /** Fetch, confirm the immutable Agent target, stash, fast-forward, and restore the stash. */
-export declare function applyAgentUpdate(path: string | null, git: GitRun, channel?: Channel, policy?: AgentUpdatePolicy): Promise<Dict>;
+export declare function applyAgentUpdate(path: string | null, git: GitRun, channel?: Channel, policy?: AgentUpdatePolicy, version?: string, published?: PublishedAgentTag): Promise<Dict>;
 /** Python `apply_force_update` (agent branch): fetch, refuse a pure-ancestor rewind, `checkout . && clean -fd && reset --hard`. */
-export declare function forceAgentUpdate(path: string | null, git: GitRun, log: (line: string) => void, channel?: Channel, policy?: AgentUpdatePolicy): Promise<Dict>;
+export declare function forceAgentUpdate(path: string | null, git: GitRun, log: (line: string) => void, channel?: Channel, policy?: AgentUpdatePolicy, version?: string, published?: PublishedAgentTag): Promise<Dict>;
 /** Python `_inventory_locks`: report `.git/**\/*.lock` without touching any of them. */
 export declare function inventoryLocks(path: string): {
     well_known_lock_present: boolean;
@@ -135,12 +173,21 @@ export interface RestartBlockers {
     restart_blocked: boolean;
 }
 export interface UpdateServiceDeps {
+    /** One retained-transaction step, including loaded-runtime reconciliation. No release selection. */
+    recoverAgent?: (probe?: boolean, signal?: AbortSignal) => Promise<SidecarResult<'runtime.agent_recovery'> & {
+        waiting_for_idle?: boolean;
+    }>;
+    recoveryChanged?: (state: AgentRecoveryState) => Promise<void>;
+    hasPendingRecovery?: () => boolean;
+    onAgentReconnect?: (listener: (runtime: RuntimeDescribe) => void) => () => void;
     /** `web/` of this installation (a Talaria checkout has it at `<root>/web`). */
     webRoot: string;
     git?: GitRun;
     /** Runs global npm discovery/install for packaged updates. */
     npm?: BuildRun;
     getJson: GetJson;
+    /** Anonymous GitHub API reads rooted at `https://api.github.com`, for the public Agent repository's release notes. */
+    getPublicJson?: GetJson;
     /** The public GHCR Experimental artifact that npm installs follow on the Experimental channel. */
     experimental?: ExperimentalRegistry;
     /** Web's state dir; channel switches back up its persisted stores here first. */
@@ -150,31 +197,41 @@ export interface UpdateServiceDeps {
     /** Re-derive the installed Web version after a check (tags can arrive after startup); returns the current label. */
     refreshWebuiVersion?: () => string;
     agentDir: () => string | null;
+    agentHomes?: () => readonly string[];
+    agentMutation?: (path: string, revision: string, mutate: (git: GitRun, sync: UpdateServiceDeps['agentSync']) => Promise<Dict>, consent?: Pick<UpdateOptions, 'mutationIntent' | 'refreshToken'>) => Promise<Dict>;
+    /** Repair dependencies through the sidecar even while its imported Agent is stale. */
+    agentSync?: (agentDir: string) => Promise<SidecarResult<'runtime.sync_dependencies'>>;
     channel: () => Channel;
     agentChannel?: () => Channel;
     includeAgent: () => boolean;
     autoApply?: () => boolean;
     checkEnabled?: () => boolean;
+    summarizeAutomatically?: () => boolean;
     autoNotification?: {
-        begin: () => string;
+        begin: () => Promise<string>;
         transition: (id: string, phase: 'restarting' | 'succeeded' | 'blocked' | 'failed', expectedIdentity?: string | null, verifiedIdentity?: {
             revision: string | null;
             version: string | null;
-        }, detail?: unknown) => void;
+        }, detail?: unknown) => void | Promise<void>;
     };
     blockers: () => RestartBlockers;
     /** Re-exec the server once active work drains (`restartWhenSafe`). */
     scheduleRestart: () => void;
-    /** Sidecar `gateway.restart` for the active profile. */
-    gatewayRestart: () => Promise<Dict>;
-    /** Optional What's New generator (sidecar `aux.complete`); null keeps the deterministic fallback. */
+    /** TAL-953: a post-update `hermes gateway restart` is running; Agent source must not change under it. */
+    gatewayRestarting?: () => boolean;
+    /** Optional update-summary generator (sidecar `aux.complete`); null keeps the deterministic fallback. */
     llm?: ((system: string, user: string) => Promise<string>) | null;
     now?: () => number;
-    sleep?: (ms: number) => Promise<void>;
     log: (line: string) => void;
 }
 export declare class UpdateService {
     private readonly deps;
+    private recoveryTimer;
+    private recoveryAbort;
+    private recoveryUnsubscribe;
+    private recoveryAttempt;
+    private recoveryFingerprint;
+    private recovery;
     private readonly cache;
     private checking;
     private checkingKey;
@@ -186,12 +243,24 @@ export declare class UpdateService {
     private autoRunning;
     private autoRestartScheduled;
     private readonly summaries;
+    private readonly pendingSummaries;
+    private readonly summaryQueues;
+    private readonly summarizing;
+    private readonly summaryFailures;
+    private readonly publishedTags;
     private readonly git;
     private readonly now;
-    private readonly sleep;
     constructor(deps: UpdateServiceDeps);
+    private persistSummaries;
+    private logSummaryFailure;
+    private summaryKey;
+    private queueSummary;
+    private preGenerateSummaries;
     private agentChannel;
+    /** TAL-930: the Agent's published Stable tag, one anonymous GitHub read per remote per cache TTL; an unreadable answer keeps the last verified tag. */
+    private readonly publishedTag;
     private agentPolicy;
+    private statusSnapshot;
     /** Python `cached_update_status`: no network, no git mutations. */
     cachedStatus(includeAgent?: boolean, channel?: Channel, agentChannel?: Channel): Dict;
     /** 30 min cache keyed on both channels + include_agent; one in-flight check per key. */
@@ -200,6 +269,10 @@ export declare class UpdateService {
     private keepLastGood;
     startAutoApply(intervalMs?: number): void;
     stopAutoApply(): void;
+    /** One sequence owns its timer and RPC; unchanged permanent debt cannot restart it. */
+    private armRecovery;
+    private publishRecovery;
+    private recoverOnce;
     /** Shared turn admission stays closed from update start through the supervisor restart. */
     blocksNewWork(): boolean;
     private pendingRestartResponse;
@@ -207,27 +280,32 @@ export declare class UpdateService {
     blockedResponse(target: string): Dict | null;
     private locked;
     /** Python `apply_update`. */
-    apply(target: string, channel?: Channel | null, canApply?: () => boolean, agentOptions?: AgentUpdateOptions): Promise<Dict>;
+    apply(target: string, channel?: Channel | null, canApply?: () => boolean, options?: UpdateOptions): Promise<Dict>;
     private applyInner;
+    private updateAgent;
     private finishAgent;
-    /** Python `_ensure_gateway_restart_for_agent_update`: retry once after a transient supervisor handoff failure. */
-    private restartGateway;
     /** Python `apply_force_update`: Web keeps its clean-only policy; the Agent resets hard. */
-    force(target: string, channel?: Channel | null, agentOptions?: AgentUpdateOptions): Promise<Dict>;
+    force(target: string, channel?: Channel | null, options?: UpdateOptions): Promise<Dict>;
     /** Python `apply_clear_lock`: never removes a lock; Web retries the clean path, the Agent gets the manual command. */
-    clearLock(target: string, agentOptions?: AgentUpdateOptions): Promise<Dict>;
-    /** Python `_commit_subjects_for_update_with_limit`. */
-    private commitSubjects;
-    /** Python `summarize_update_payload`: What's New sections, LLM when available, cached per exact range. */
-    summarize(updates: Dict, targetRaw: unknown): Promise<Dict>;
+    clearLock(target: string, options?: UpdateOptions): Promise<Dict>;
+    /** Complete commit identities and subjects, oldest first. Failures never commit a partial range. */
+    private commitItems;
+    private descendsFrom;
+    private releaseItems;
+    private refreshSummaryItems;
+    summarize(target: 'webui' | 'agent', checksOff?: boolean): Promise<Dict>;
+    private summarizeTarget;
+    /** The sole model path: fold bounded batches into the prior sections without dropping input text. */
+    private foldSummary;
+    private generateSummary;
 }
 export type UpdateState = 'up_to_date' | 'release_ready' | 'commits_behind' | 'local_changes' | 'finish' | 'manual' | 'check_failed' | 'off' | 'unknown';
 /** TAL-559: one target's status and apply availability, decided here so clients only word them. */
-export declare function updateTargetView(name: 'webui' | 'agent', info: Dict, off: boolean): Dict;
+export declare function updateTargetView(name: 'webui' | 'agent', target: Dict, off: boolean): Dict;
 /** `/api/updates/check`: every present target carries its view; disabled checks report both targets off. */
 export declare function updatesCheckView(status: Dict): Dict;
 /** Python `_wait_until_restart_safe`: poll until no chat work is active, bounded so a stuck run cannot jam the update forever. */
-export declare function waitUntilRestartSafe(blockers: () => RestartBlockers, opts?: {
+export declare function waitUntilRestartSafe(blockers: () => RestartBlockers | Promise<RestartBlockers>, opts?: {
     pollMs?: number;
     maxWaitMs?: number;
     sleep?: (ms: number) => Promise<void>;