From bbec2924340c4247d03922cc8c2a556faa42b0db Mon Sep 17 00:00:00 2001 From: William Valentin Date: Thu, 26 Feb 2026 18:59:44 -0800 Subject: [PATCH] feat(companion): include checksums in release bundle artifacts --- README.md | 4 ++-- docs/api/PROTOCOL.md | 2 +- docs/architecture/AGENT_DIAGRAM.md | 2 +- .../GATEWAY_SESSIONS_AND_QUEUE.md | 2 +- ...-personal-assistant-productization-plan.md | 2 +- docs/plans/state.json | 23 +++++++++++++++++-- src/cli/companion.test.ts | 1 + src/cli/companion.ts | 1 + src/companion/releaseBundle.test.ts | 4 ++++ src/companion/releaseBundle.ts | 23 +++++++++++++------ 10 files changed, 49 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 7d397d3..2721064 100644 --- a/README.md +++ b/README.md @@ -1735,14 +1735,14 @@ Companion runtime helper: - runtime observability/control passthroughs (`pendingRequestCount`, `pendingEventWaitCount`, `hasPendingWork`, `idle`, `lastDisconnectCode`, `lastDisconnectReason`, `getPendingWorkSnapshot()`, `getEventSurfaceSnapshot()`, `getConnectionSnapshot()`, `connected`, `waitForIdle()`) - `src/companion/heartbeatLoop.ts` provides `CompanionHeartbeatLoop` for periodic heartbeat scheduling (`publishHeartbeat`) with start/stop safety, optional interval jitter (`jitterRatio`) to spread load (with safe normalization for invalid random samples), `tickNow()` for manual sends, success/error hooks, loop observability (`successCount`, `lastSuccessAt`, `failureCount`, `lastFailure`, `getState()`), and optional auto-stop after repeated failures. - `src/companion/bootstrapManifest.ts` provides `createCompanionBootstrapManifest()` for generating a typed gateway/node/runtime bootstrap contract used by packaging flows, including optional initial status/location/push payloads. -- `src/companion/releaseBundle.ts` provides `writeCompanionReleaseBundle()` for writing a distributable companion bundle directory (bootstrap JSON + launcher script + README). +- `src/companion/releaseBundle.ts` provides `writeCompanionReleaseBundle()` for writing a distributable companion bundle directory (bootstrap JSON + launcher script + README + SHA-256 checksums). Minimal companion CLI: - `flynn companion --once` connects to the gateway, registers a node, publishes one heartbeat, then exits. - `flynn companion --platform macos --heartbeat 30` runs a long-lived node with periodic heartbeats and logs `agent.stream`/`agent.typing` events. - `flynn companion --once --handoff "summarize my status"` performs one post-registration `agent.send` handoff and prints the `done` content. - `flynn companion --export-bootstrap ./companion.bootstrap.json` writes a resolved bootstrap manifest for desktop/mobile companion app packaging (use `-` for stdout). -- `flynn companion --export-release-bundle ./dist/companion-macos` writes a release bundle directory (`companion.bootstrap.json`, `run-companion.sh`, `README.md`) and exits. +- `flynn companion --export-release-bundle ./dist/companion-macos` writes a release bundle directory (`companion.bootstrap.json`, `run-companion.sh`, `README.md`, `CHECKSUMS.sha256`) and exits. - `flynn companion --once --platform ios --app-version 1.2.3 --device-name "iPhone" --status-text ready --battery-pct 84 --power-source battery` sends richer initial node status metadata. - `flynn companion --once --latitude 37.3349 --longitude -122.009 --location-source gps` bootstraps node location metadata. - `flynn companion --once --platform android --push-token ` (or `--platform ios --push-token `) registers push routing metadata during bootstrap. diff --git a/docs/api/PROTOCOL.md b/docs/api/PROTOCOL.md index 4382c21..8c5177d 100644 --- a/docs/api/PROTOCOL.md +++ b/docs/api/PROTOCOL.md @@ -1863,4 +1863,4 @@ For more implementation details, see: - Companion runtime client helper: `src/companion/runtimeClient.ts` (node + system + `canvas.*` typed RPC wrappers, optional `autoConnect`/`autoReconnect`, optional reconnect state replay, `sendAgentMessage` handoff helper, connection event subscriptions) - Platform companion wrappers: `src/companion/platformClients.ts` - Companion bootstrap manifest helper: `src/companion/bootstrapManifest.ts` (typed packaging manifest contract used by `flynn companion --export-bootstrap`, including optional initial status/location/push payloads) -- Companion release bundle helper: `src/companion/releaseBundle.ts` (writes bootstrap JSON + launcher script + README for distributable companion shell bundles) +- Companion release bundle helper: `src/companion/releaseBundle.ts` (writes bootstrap JSON + launcher script + README + `CHECKSUMS.sha256` for distributable companion shell bundles) diff --git a/docs/architecture/AGENT_DIAGRAM.md b/docs/architecture/AGENT_DIAGRAM.md index 40ae56b..aab3e01 100644 --- a/docs/architecture/AGENT_DIAGRAM.md +++ b/docs/architecture/AGENT_DIAGRAM.md @@ -156,7 +156,7 @@ Gateway streaming UX signals: - Routing applies reaction rules with deterministic priority/cooldown (and recursion guard) before intent routing. - Companion nodes re-register `node.*` capabilities after reconnect; runtime clients can auto-reconnect, optionally replay cached node state (`register/status/location/push`), and surface connection events. - `flynn companion --export-bootstrap ` can emit a resolved companion bootstrap manifest (gateway/node/runtime contract) for desktop/mobile packaging flows without opening a runtime connection. -- `flynn companion --export-release-bundle ` can emit a distributable shell bundle (bootstrap JSON + launcher + README) for desktop/mobile packaging pipelines. +- `flynn companion --export-release-bundle ` can emit a distributable shell bundle (bootstrap JSON + launcher + README + SHA-256 checksums) for desktop/mobile packaging pipelines. - `flynn companion` can bootstrap status/location/push metadata on connect (`node.status.set` + optional `node.location.set`/`node.push_token.set`) so thin companion shells can register operational context in one launch. - Canvas artifacts are persisted by the gateway so session UI surfaces can recover after daemon restarts. - TTS synthesis uses an ordered provider chain with health cooldown tracking; if all providers fail, replies degrade to text-only without dropping the response. diff --git a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md index 3d76e33..16e5409 100644 --- a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md +++ b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md @@ -21,7 +21,7 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`. - Browser workflow reliability primitives (`browser.wait_for/assert/extract/checkpoint.*`) execute in the same queued session lane and apply browser-config guardrails (domain allowlist/high-risk confirmation, bounded retries, workflow step budget). - Companion `node.*` registration is per WebSocket connection; reconnects must re-register capabilities before invoking node RPC methods (or use runtime-client reconnect state replay to re-register/status/location/push automatically). - Companion packaging/bootstrap can be generated offline via `flynn companion --export-bootstrap `, which emits resolved gateway/node/runtime settings without opening a WebSocket session. -- Companion release artifacts can be generated via `flynn companion --export-release-bundle `, producing bootstrap JSON + launcher + README for installable shell distribution workflows. +- Companion release artifacts can be generated via `flynn companion --export-release-bundle `, producing bootstrap JSON + launcher + README + `CHECKSUMS.sha256` for installable shell distribution workflows. - Companion CLI supports one-shot shell bootstrap metadata for live sessions (`--app-version`/`--status-text`, `--latitude`/`--longitude`, `--push-token`) so desktop/mobile wrappers can initialize node status/location/push in a single launch flow. - Canvas artifacts are persisted per session under the gateway data directory for UI recovery across restarts. - TTS output is best-effort with ordered provider fallback + per-provider cooldown tracking; synthesis failures still fall back to text-only responses. diff --git a/docs/plans/2026-02-26-personal-assistant-productization-plan.md b/docs/plans/2026-02-26-personal-assistant-productization-plan.md index a86d94b..ca2020a 100644 --- a/docs/plans/2026-02-26-personal-assistant-productization-plan.md +++ b/docs/plans/2026-02-26-personal-assistant-productization-plan.md @@ -49,7 +49,7 @@ Within 8-10 weeks, ship a stable "Personal Assistant Mode" that supports: 2. Ship a minimal mobile companion shell (iOS + Android) for registration, status, push token, and message handoff. 3. Add signed release artifacts and installation docs. -Status update (2026-02-27): companion bootstrap-manifest export is now available via `flynn companion --export-bootstrap ` as a packaging contract for desktop/mobile shells, `flynn companion --export-release-bundle ` now emits bundle artifacts (bootstrap JSON + launcher + README), and `flynn companion` supports one-shot status/location/push bootstrap flags (`--app-version`, `--latitude/--longitude`, `--push-token`) so thin shells can initialize companion metadata in a single run. +Status update (2026-02-27): companion bootstrap-manifest export is now available via `flynn companion --export-bootstrap ` as a packaging contract for desktop/mobile shells, `flynn companion --export-release-bundle ` now emits bundle artifacts (bootstrap JSON + launcher + README + `CHECKSUMS.sha256`), and `flynn companion` supports one-shot status/location/push bootstrap flags (`--app-version`, `--latitude/--longitude`, `--push-token`) so thin shells can initialize companion metadata in a single run. ### Implementation Anchors diff --git a/docs/plans/state.json b/docs/plans/state.json index 12bc1c5..d18e5d0 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -6981,6 +6981,25 @@ "docs/plans/state.json" ], "test_status": "pnpm test:run src/cli/companion.test.ts src/companion/bootstrapManifest.test.ts src/companion/releaseBundle.test.ts + pnpm typecheck passing" + }, + "personal-assistant-productization-phase1-companion-release-checksums": { + "status": "completed", + "date": "2026-02-27", + "updated": "2026-02-27", + "summary": "Hardened companion release-bundle artifacts with deterministic SHA-256 checksums. `writeCompanionReleaseBundle()` now emits `CHECKSUMS.sha256`, and `flynn companion --export-release-bundle` reports checksum output paths for distribution verification.", + "files_modified": [ + "src/companion/releaseBundle.ts", + "src/companion/releaseBundle.test.ts", + "src/cli/companion.ts", + "src/cli/companion.test.ts", + "README.md", + "docs/api/PROTOCOL.md", + "docs/architecture/AGENT_DIAGRAM.md", + "docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md", + "docs/plans/2026-02-26-personal-assistant-productization-plan.md", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/cli/companion.test.ts src/companion/releaseBundle.test.ts + pnpm typecheck passing" } }, "overall_progress": { @@ -6999,7 +7018,7 @@ "tier2_completion": "4/4 (100%) — inbound webhooks, vector memory search, Dockerfile, heartbeat monitor", "tier3_completion": "5/5 (100%) — lane queue, credential redaction, web UI token dashboard, xAI (Grok) provider, Voyage AI embeddings", "tier4_completion": "4/4 (100%) — gateway lock, shell completion, Tailscale Serve/Funnel, DM pairing codes", - "feature_gap_scorecard": "rebaselined 2026-02-26 and updated 2026-02-27 (phase 3 + phase 1 + phase 2 + phase 4 slices + companion packaging/bundle tooling + shell bootstrap controls) — channel breadth, setup wizard, baseline browser automation, subagent controls, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging primitives (bootstrap export + release-bundle artifacts) and one-shot status/location/push shell bootstrap controls, voice reliability hardening (talk controls + TTS fallback/health + interruption-safe cancel semantics), and onboarding first-success funnel improvements are implemented; remaining high-impact personal-assistant gaps center on shipped desktop/mobile companion app binaries and signed distribution pipelines.", + "feature_gap_scorecard": "rebaselined 2026-02-26 and updated 2026-02-27 (phase 3 + phase 1 + phase 2 + phase 4 slices + companion packaging/bundle tooling + shell bootstrap controls) — channel breadth, setup wizard, baseline browser automation, subagent controls, browser workflow reliability primitives (wait/assert/extract/retries/checkpoints/guardrails/budgets), companion reconnect/runtime-handoff foundations, companion packaging primitives (bootstrap export + release-bundle artifacts + checksum manifests) and one-shot status/location/push shell bootstrap controls, voice reliability hardening (talk controls + TTS fallback/health + interruption-safe cancel semantics), and onboarding first-success funnel improvements are implemented; remaining high-impact personal-assistant gaps center on shipped desktop/mobile companion app binaries and signed distribution pipelines.", "operator_dx_milestone": "Phase 3 (Live Ops Dashboard): 2/2 plans complete — milestone done", "dashboard_observability": "completed — service health graphs + core service log viewer added to web UI via observability RPCs and bounded backend sampling", "gmail_auth_cli": "flynn gmail-auth command implemented with OAuth2 flow, doctor check, config routed to Telegram", @@ -7032,7 +7051,7 @@ "deeper_surfaces_phase3_companion_canvas_voice": "completed — companion reconnect resilience (auto-reconnect with backoff, pending-wait cancellation on disconnect), canvas artifact persistence (SQLite-backed store, daemon-restart durability), voice TTS fallback coverage (text-only reply on TTS failure, no dropped responses)", "deeper_surfaces_phase4_rollout": "completed — phase 4 rollout and operator readiness plan documented: canary rollout plan by feature flag/surface, explicit rollback playbook, operator docs and architecture/protocol docs synchronized", "post_phase_test_fixes": "completed — fixed 4 test failures introduced by phases 1-3: iOS/Android push listNodes (missing publishHeartbeat before platform-filtered query), server.test agent.send (run_state events now precede done; added sendAndWaitForDone helper), httpBody 413 (req.destroy() closed socket before response could be sent; replaced with Connection: close header on 413 responses)", - "personal_assistant_productization_plan": "in_progress — 8-10 week phased roadmap active; Phase 3 browser workflow reliability shipped, Phase 1 companion runtime reliability includes reconnect state replay + typed handoff support, companion packaging primitives now include bootstrap manifest export and release-bundle artifact generation, companion shell bootstrap controls cover status/location/push metadata, Phase 2 voice reliability ships talk controls + TTS provider fallback/health + interruption-safe voice cancel mapping, and Phase 4 onboarding includes Personal Assistant Mode preset + live readiness checks + first-success guidance. Remaining phase focus: shipped companion app surfaces and signed release artifacts.", + "personal_assistant_productization_plan": "in_progress — 8-10 week phased roadmap active; Phase 3 browser workflow reliability shipped, Phase 1 companion runtime reliability includes reconnect state replay + typed handoff support, companion packaging primitives now include bootstrap manifest export, release-bundle artifact generation, and checksum manifests, companion shell bootstrap controls cover status/location/push metadata, Phase 2 voice reliability ships talk controls + TTS provider fallback/health + interruption-safe voice cancel mapping, and Phase 4 onboarding includes Personal Assistant Mode preset + live readiness checks + first-success guidance. Remaining phase focus: shipped companion app surfaces and signed release artifacts.", "subagents_support": "completed — subagent phases 1-3 shipped with `subagent.spawn/send/list/cancel/delete/summary`, per-child queue mode (`followup|interrupt`), budgets (`max_turns`, `max_total_tokens`, `turn_timeout_ms`), tool-profile overrides, trace-linked audit events, `/subagents` inspection commands, and focused regression tests." }, "soul_md_and_cron_create": { diff --git a/src/cli/companion.test.ts b/src/cli/companion.test.ts index f36fee4..120b67c 100644 --- a/src/cli/companion.test.ts +++ b/src/cli/companion.test.ts @@ -94,6 +94,7 @@ const { manifestPath: `${input.outputDir}/companion.bootstrap.json`, launcherPath: `${input.outputDir}/run-companion.sh`, readmePath: `${input.outputDir}/README.md`, + checksumsPath: `${input.outputDir}/CHECKSUMS.sha256`, })); return { diff --git a/src/cli/companion.ts b/src/cli/companion.ts index ef1f6f9..aa9eb58 100644 --- a/src/cli/companion.ts +++ b/src/cli/companion.ts @@ -360,6 +360,7 @@ export async function runCompanionSession(options: CompanionCommandOptions): Pro console.log(`- Manifest: ${result.manifestPath}`); console.log(`- Launcher: ${result.launcherPath}`); console.log(`- README: ${result.readmePath}`); + console.log(`- Checksums: ${result.checksumsPath}`); return; } diff --git a/src/companion/releaseBundle.test.ts b/src/companion/releaseBundle.test.ts index d724e2d..91cf883 100644 --- a/src/companion/releaseBundle.test.ts +++ b/src/companion/releaseBundle.test.ts @@ -48,6 +48,7 @@ describe('writeCompanionReleaseBundle', () => { const manifestRaw = await readFile(result.manifestPath, 'utf8'); const launcherRaw = await readFile(result.launcherPath, 'utf8'); const readmeRaw = await readFile(result.readmePath, 'utf8'); + const checksumsRaw = await readFile(result.checksumsPath, 'utf8'); const launcherStat = await stat(result.launcherPath); expect(JSON.parse(manifestRaw)).toMatchObject({ @@ -58,6 +59,9 @@ describe('writeCompanionReleaseBundle', () => { expect(launcherRaw).toContain('--push-token'); expect(launcherRaw).toContain('--latitude'); expect(readmeRaw).toContain('Flynn Companion Release Bundle'); + expect(checksumsRaw).toContain('companion.bootstrap.json'); + expect(checksumsRaw).toContain('run-companion.sh'); + expect(checksumsRaw).toContain('README.md'); expect((launcherStat.mode & 0o111) !== 0).toBe(true); await rm(tempDir, { recursive: true, force: true }); diff --git a/src/companion/releaseBundle.ts b/src/companion/releaseBundle.ts index 341754d..a22ef14 100644 --- a/src/companion/releaseBundle.ts +++ b/src/companion/releaseBundle.ts @@ -1,4 +1,5 @@ import { chmod, mkdir, writeFile } from 'node:fs/promises'; +import { createHash } from 'node:crypto'; import type { CompanionBootstrapManifest } from './bootstrapManifest.js'; export interface WriteCompanionReleaseBundleInput { @@ -11,6 +12,7 @@ export interface WriteCompanionReleaseBundleResult { manifestPath: string; launcherPath: string; readmePath: string; + checksumsPath: string; } function shSingleQuote(value: string): string { @@ -142,20 +144,27 @@ export async function writeCompanionReleaseBundle( const manifestPath = `${input.outputDir}/companion.bootstrap.json`; const launcherPath = `${input.outputDir}/run-companion.sh`; const readmePath = `${input.outputDir}/README.md`; + const checksumsPath = `${input.outputDir}/CHECKSUMS.sha256`; + const manifestBody = `${JSON.stringify(input.manifest, null, 2)}\n`; + const launcherBody = createLauncherScript(input.manifest); + const readmeBody = createReadme(input.manifest); - await writeFile( - manifestPath, - `${JSON.stringify(input.manifest, null, 2)}\n`, - 'utf8', - ); - await writeFile(launcherPath, createLauncherScript(input.manifest), 'utf8'); + await writeFile(manifestPath, manifestBody, 'utf8'); + await writeFile(launcherPath, launcherBody, 'utf8'); await chmod(launcherPath, 0o755); - await writeFile(readmePath, createReadme(input.manifest), 'utf8'); + await writeFile(readmePath, readmeBody, 'utf8'); + const checksums = [ + [createHash('sha256').update(manifestBody, 'utf8').digest('hex'), 'companion.bootstrap.json'], + [createHash('sha256').update(launcherBody, 'utf8').digest('hex'), 'run-companion.sh'], + [createHash('sha256').update(readmeBody, 'utf8').digest('hex'), 'README.md'], + ].map(([hash, name]) => `${hash} ${name}`).join('\n'); + await writeFile(checksumsPath, `${checksums}\n`, 'utf8'); return { outputDir: input.outputDir, manifestPath, launcherPath, readmePath, + checksumsPath, }; }