feat(companion): emit release manifest metadata in bundles
This commit is contained in:
William Valentin
@@ -1735,7 +1735,7 @@ 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 + SHA-256 checksums).
|
||||
- `src/companion/releaseBundle.ts` provides `writeCompanionReleaseBundle()` for writing a distributable companion bundle directory (bootstrap JSON + launcher script + README + SHA-256 checksums + release manifest).
|
||||
- `src/companion/shellTemplate.ts` provides `writeCompanionShellTemplate()` for emitting platform starter shells (macOS/iOS/Android native scaffold snippets + bootstrap JSON).
|
||||
- `src/companion/releaseVerify.ts` provides `verifyCompanionReleaseBundle()` for validating bundle checksums and optional signature metadata.
|
||||
- `src/companion/releasePipeline.ts` provides `buildAndVerifyCompanionReleaseBundle()` for build-and-verify automation (including signed bundle flows).
|
||||
@@ -1746,7 +1746,7 @@ Minimal companion CLI:
|
||||
- `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`, `CHECKSUMS.sha256`) 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`, `RELEASE_MANIFEST.json`) and exits.
|
||||
- `flynn companion --export-release-bundle ./dist/companion-macos --signing-key ./keys/release-private.pem --signing-key-id team-k1` also writes `CHECKSUMS.sha256.sig` for signed verification workflows.
|
||||
- `flynn companion --platform ios --export-shell-template ./dist/companion-ios-template` writes a platform-native starter template directory (`companion.bootstrap.json`, native starter file, `README.md`) and exits.
|
||||
- `flynn companion --verify-release-bundle ./dist/companion-macos --verify-signing-key ./keys/release-public.pem --verify-signing-key-id team-k1 --require-signature` verifies checksums and signature metadata before install.
|
||||
|
||||
@@ -1863,7 +1863,7 @@ 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 + `CHECKSUMS.sha256`; optional `CHECKSUMS.sha256.sig` when a signing key is provided. Launcher performs checksum verification before exec.)
|
||||
- Companion release bundle helper: `src/companion/releaseBundle.ts` (writes bootstrap JSON + launcher script + README + `CHECKSUMS.sha256` + `RELEASE_MANIFEST.json`; optional `CHECKSUMS.sha256.sig` when a signing key is provided. Launcher performs checksum verification before exec.)
|
||||
- Companion release bundle verifier: `src/companion/releaseVerify.ts` (validates `CHECKSUMS.sha256` and optional signature metadata against a provided public key)
|
||||
- Companion release automation pipeline: `src/companion/releasePipeline.ts` + `scripts/build-companion-release-bundle.ts` (build-and-verify workflow for deterministic companion artifact generation)
|
||||
- Companion shell template helper: `src/companion/shellTemplate.ts` (writes platform-native starter template files for `macos`, `ios`, and `android` shell scaffolding)
|
||||
|
||||
@@ -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 <path|->`, which emits resolved gateway/node/runtime settings without opening a WebSocket session.
|
||||
- Companion release artifacts can be generated via `flynn companion --export-release-bundle <dir>`, producing bootstrap JSON + launcher + README + `CHECKSUMS.sha256` for installable shell distribution workflows.
|
||||
- Companion release artifacts can be generated via `flynn companion --export-release-bundle <dir>`, producing bootstrap JSON + launcher + README + `CHECKSUMS.sha256` + `RELEASE_MANIFEST.json` for installable shell distribution workflows.
|
||||
- Generated launchers validate `CHECKSUMS.sha256` before invoking `flynn companion`, reducing accidental tampered-bundle launches.
|
||||
- Companion release-bundle exports can optionally be signed (`--signing-key`, `--signing-key-id`) to emit `CHECKSUMS.sha256.sig` for distribution trust verification.
|
||||
- Companion release bundles can be verified before install via `flynn companion --verify-release-bundle <dir>` with optional signature-key checks.
|
||||
|
||||
@@ -20,6 +20,7 @@ Generated files:
|
||||
- `run-companion.sh`
|
||||
- `README.md`
|
||||
- `CHECKSUMS.sha256`
|
||||
- `RELEASE_MANIFEST.json`
|
||||
|
||||
Optional signed export:
|
||||
|
||||
|
||||
@@ -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 <path|->` as a packaging contract for desktop/mobile shells, `flynn companion --export-release-bundle <dir>` now emits bundle artifacts (bootstrap JSON + launcher + README + `CHECKSUMS.sha256`, optional `CHECKSUMS.sha256.sig` with `--signing-key`), `flynn companion --verify-release-bundle <dir>` now validates checksum/signature artifacts before install, `pnpm companion:bundle -- --output <dir> ...` now provides one-pass build-and-verify automation, `flynn companion --export-shell-template <dir>` now emits macOS/iOS/Android starter shell templates, `pnpm companion:reference-apps` now regenerates in-repo macOS/iOS/Android reference app starter directories, 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 <path|->` as a packaging contract for desktop/mobile shells, `flynn companion --export-release-bundle <dir>` now emits bundle artifacts (bootstrap JSON + launcher + README + `CHECKSUMS.sha256` + `RELEASE_MANIFEST.json`, optional `CHECKSUMS.sha256.sig` with `--signing-key`), `flynn companion --verify-release-bundle <dir>` now validates checksum/signature artifacts before install, `pnpm companion:bundle -- --output <dir> ...` now provides one-pass build-and-verify automation, `flynn companion --export-shell-template <dir>` now emits macOS/iOS/Android starter shell templates, `pnpm companion:reference-apps` now regenerates in-repo macOS/iOS/Android reference app starter directories, 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
|
||||
|
||||
|
||||
+21
-2
@@ -7143,6 +7143,25 @@
|
||||
"docs/plans/state.json"
|
||||
],
|
||||
"test_status": "pnpm test:run src/companion/referenceApps.test.ts src/companion/shellTemplate.test.ts + pnpm typecheck passing"
|
||||
},
|
||||
"personal-assistant-productization-phase1-companion-release-manifest-artifact": {
|
||||
"status": "completed",
|
||||
"date": "2026-02-27",
|
||||
"updated": "2026-02-27",
|
||||
"summary": "Extended companion release bundles with machine-readable `RELEASE_MANIFEST.json` metadata (bundle identity, artifact hashes, optional signature metadata) for downstream CI/release tooling. CLI export output now reports manifest path.",
|
||||
"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/GATEWAY_SESSIONS_AND_QUEUE.md",
|
||||
"docs/operations/COMPANION_RELEASE_BUNDLE.md",
|
||||
"docs/plans/2026-02-26-personal-assistant-productization-plan.md",
|
||||
"docs/plans/state.json"
|
||||
],
|
||||
"test_status": "pnpm test:run src/companion/releaseBundle.test.ts src/cli/companion.test.ts + pnpm typecheck passing"
|
||||
}
|
||||
},
|
||||
"overall_progress": {
|
||||
@@ -7161,7 +7180,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 + platform templates + signed/verified artifacts + automation pipeline + reference app surfaces) — 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 + optional signatures + verification mode + checksum-gated launcher + one-pass build/verify automation), companion install/verification runbook, repo-shipped macOS/iOS/Android reference app starter surfaces, 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 production-grade native companion binaries and distribution hardening automation.",
|
||||
"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 + platform templates + signed/verified artifacts + automation pipeline + reference app surfaces + release manifest artifact) — 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 + release manifest artifact + optional signatures + verification mode + checksum-gated launcher + one-pass build/verify automation), companion install/verification runbook, repo-shipped macOS/iOS/Android reference app starter surfaces, 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 production-grade native companion binaries and end-to-end distribution workflows.",
|
||||
"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",
|
||||
@@ -7194,7 +7213,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 include bootstrap manifest export, release-bundle artifact generation, checksum manifests, optional signature emission, verification mode, checksum-gated launchers, one-pass build/verify automation pipeline, platform starter shell-template generation, repo-shipped reference app starter directories, and an install/verification runbook, 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: production-ready native companion app surfaces and distribution hardening automation.",
|
||||
"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 include bootstrap manifest export, release-bundle artifact generation, checksum manifests, release manifest artifact, optional signature emission, verification mode, checksum-gated launchers, one-pass build/verify automation pipeline, platform starter shell-template generation, repo-shipped reference app starter directories, and an install/verification runbook, 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: production-ready native companion app surfaces and end-to-end distribution workflows.",
|
||||
"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": {
|
||||
|
||||
@@ -100,6 +100,7 @@ const {
|
||||
readmePath: `${input.outputDir}/README.md`,
|
||||
checksumsPath: `${input.outputDir}/CHECKSUMS.sha256`,
|
||||
signaturePath: input.signingKeyPem ? `${input.outputDir}/CHECKSUMS.sha256.sig` : undefined,
|
||||
releaseManifestPath: `${input.outputDir}/RELEASE_MANIFEST.json`,
|
||||
}));
|
||||
const writeCompanionShellTemplate = vi.fn(async (input: {
|
||||
outputDir: string;
|
||||
|
||||
@@ -398,6 +398,7 @@ export async function runCompanionSession(options: CompanionCommandOptions): Pro
|
||||
console.log(`- Launcher: ${result.launcherPath}`);
|
||||
console.log(`- README: ${result.readmePath}`);
|
||||
console.log(`- Checksums: ${result.checksumsPath}`);
|
||||
console.log(`- Release manifest: ${result.releaseManifestPath}`);
|
||||
if (result.signaturePath) {
|
||||
console.log(`- Signature: ${result.signaturePath}`);
|
||||
}
|
||||
|
||||
@@ -50,6 +50,7 @@ describe('writeCompanionReleaseBundle', () => {
|
||||
const launcherRaw = await readFile(result.launcherPath, 'utf8');
|
||||
const readmeRaw = await readFile(result.readmePath, 'utf8');
|
||||
const checksumsRaw = await readFile(result.checksumsPath, 'utf8');
|
||||
const bundleManifestRaw = await readFile(result.releaseManifestPath, 'utf8');
|
||||
const launcherStat = await stat(result.launcherPath);
|
||||
|
||||
expect(JSON.parse(manifestRaw)).toMatchObject({
|
||||
@@ -64,6 +65,13 @@ describe('writeCompanionReleaseBundle', () => {
|
||||
expect(checksumsRaw).toContain('companion.bootstrap.json');
|
||||
expect(checksumsRaw).toContain('run-companion.sh');
|
||||
expect(checksumsRaw).toContain('README.md');
|
||||
expect(JSON.parse(bundleManifestRaw)).toMatchObject({
|
||||
schemaVersion: 1,
|
||||
bundle: { nodeId: 'ios-node', platform: 'ios' },
|
||||
files: expect.arrayContaining([
|
||||
expect.objectContaining({ path: 'CHECKSUMS.sha256' }),
|
||||
]),
|
||||
});
|
||||
expect((launcherStat.mode & 0o111) !== 0).toBe(true);
|
||||
|
||||
await rm(tempDir, { recursive: true, force: true });
|
||||
@@ -99,12 +107,20 @@ describe('writeCompanionReleaseBundle', () => {
|
||||
});
|
||||
|
||||
expect(result.signaturePath).toBe(`${outputDir}/CHECKSUMS.sha256.sig`);
|
||||
expect(result.releaseManifestPath).toBe(`${outputDir}/RELEASE_MANIFEST.json`);
|
||||
|
||||
const checksumsRaw = await readFile(result.checksumsPath, 'utf8');
|
||||
const signatureRaw = await readFile(result.signaturePath!, 'utf8');
|
||||
const bundleManifestRaw = await readFile(result.releaseManifestPath, 'utf8');
|
||||
const signatureLine = signatureRaw.split('\n').find((line) => line.startsWith('signature='));
|
||||
expect(signatureLine).toBeTruthy();
|
||||
expect(signatureRaw).toContain('key_id=test-key');
|
||||
expect(JSON.parse(bundleManifestRaw)).toMatchObject({
|
||||
signature: {
|
||||
path: 'CHECKSUMS.sha256.sig',
|
||||
keyId: 'test-key',
|
||||
},
|
||||
});
|
||||
|
||||
const signature = Buffer.from(String(signatureLine).replace('signature=', ''), 'base64');
|
||||
const verified = verify(
|
||||
|
||||
@@ -16,6 +16,7 @@ export interface WriteCompanionReleaseBundleResult {
|
||||
readmePath: string;
|
||||
checksumsPath: string;
|
||||
signaturePath?: string;
|
||||
releaseManifestPath: string;
|
||||
}
|
||||
|
||||
function shSingleQuote(value: string): string {
|
||||
@@ -171,6 +172,7 @@ export async function writeCompanionReleaseBundle(
|
||||
const launcherPath = `${input.outputDir}/run-companion.sh`;
|
||||
const readmePath = `${input.outputDir}/README.md`;
|
||||
const checksumsPath = `${input.outputDir}/CHECKSUMS.sha256`;
|
||||
const releaseManifestPath = `${input.outputDir}/RELEASE_MANIFEST.json`;
|
||||
const manifestBody = `${JSON.stringify(input.manifest, null, 2)}\n`;
|
||||
const launcherBody = createLauncherScript(input.manifest);
|
||||
const readmeBody = createReadme(input.manifest);
|
||||
@@ -201,6 +203,29 @@ export async function writeCompanionReleaseBundle(
|
||||
].filter(Boolean).join('\n');
|
||||
await writeFile(signaturePath, `${signatureBody}\n`, 'utf8');
|
||||
}
|
||||
const releaseManifest = {
|
||||
schemaVersion: 1,
|
||||
generatedAt: input.manifest.generatedAt,
|
||||
bundle: {
|
||||
nodeId: input.manifest.node.nodeId,
|
||||
platform: input.manifest.node.platform,
|
||||
role: input.manifest.node.role,
|
||||
gatewayUrl: input.manifest.gateway.url,
|
||||
},
|
||||
files: [
|
||||
{ path: 'companion.bootstrap.json', sha256: createHash('sha256').update(manifestBody, 'utf8').digest('hex') },
|
||||
{ path: 'run-companion.sh', sha256: createHash('sha256').update(launcherBody, 'utf8').digest('hex') },
|
||||
{ path: 'README.md', sha256: createHash('sha256').update(readmeBody, 'utf8').digest('hex') },
|
||||
{ path: 'CHECKSUMS.sha256', sha256: createHash('sha256').update(checksumsPayload, 'utf8').digest('hex') },
|
||||
],
|
||||
signature: signaturePath ? {
|
||||
path: 'CHECKSUMS.sha256.sig',
|
||||
algorithm: 'sha256',
|
||||
encoding: 'base64',
|
||||
keyId: input.signingKeyId ?? undefined,
|
||||
} : undefined,
|
||||
};
|
||||
await writeFile(releaseManifestPath, `${JSON.stringify(releaseManifest, null, 2)}\n`, 'utf8');
|
||||
|
||||
return {
|
||||
outputDir: input.outputDir,
|
||||
@@ -209,5 +234,6 @@ export async function writeCompanionReleaseBundle(
|
||||
readmePath,
|
||||
checksumsPath,
|
||||
signaturePath,
|
||||
releaseManifestPath,
|
||||
};
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user