Keep 0.7.2 apps working with 0.8 daemons

[boudra]

Linked issue

Pre-release compatibility review. Refs #3411, #4215, #4354, #4242, #4436.

Type of change

• Bug fix
• New feature
• Enhancement
• Refactor
• Docs

Reasoning

A phone app can remain on 0.7.2 for weeks after its desktop host updates to 0.8. Plugin timeline rows currently make that app reject timeline fetches and drop live events. Fork-PR setup also introduces a status that the old app cannot parse.

The daemon now checks hello.capabilities.plugin_timeline_items before delivering plugin rows through live streams, canonical/projected fetches, rewind replay, and provider-subagent streams/fetches. Filtering merged plugin rows also removes their new collapsed: "identity" value from old-client responses. Pagination windows and cursors remain canonical. Current clients advertise support.

hello.capabilities.workspace_setup_blocked preserves blocked for current clients and maps it to failed with update/approval guidance for old clients. Both setup progress and status responses are adapted per socket, including sockets sharing one retained session. Stored state stays unchanged. External agent-tool and MCP worktree broadcasts also enter this boundary: emitExternalSessionMessage → wsServer.broadcast → Session.publish → Session.emit.

The five incorrect v0.7.3 feature tags present in this checkout now say v0.8.0. Review of #4354 and #4242 confirms that hub.execute intentionally has daemon-wide agent authority. Authorization remains unchanged; the public security guide explicitly includes model, thinking, and provider permission modes that bypass approval prompts, distinguishing those from daemon credential permissions.

Goals

• Keep existing agents readable and live on a published 0.7.2 client against a 0.8 daemon.
• Preserve plugin rows and blocked setup state for capable clients.
• Keep compatibility adaptation at the daemon's client delivery boundary.

Non-goals

• No persistence or replica-cache changes. readTimeline already deletes undecodable cache rows and returns a cache miss (Revert #4421 and narrow the cache restore fix #4436).
• No new Hub permission or restriction of its intended execution authority.
• Defer the optional unknown-item notice. A pure z.union([knownItems, z.looseObject({type: z.string()})]) compiles with the pinned zod-aot, but also accepts malformed known items. Its overlapping string tag would spread loss of type narrowing across shared protocol consumers. Excluding known tags and introducing a separately normalized client wire type is larger than the small release fix requested here. Wire validation remains strict.

QA

CI passed on 5518eacab: CI completed successfully with Linux/Windows server tests, SDK tests, all four Playwright shards, typecheck, lint, and formatting. Docker and Nix Linux/macOS builds also passed. All applicable checks are green; unrelated jobs were skipped by path filtering. Review threads are resolved.

Failing first: added the plugin mixed-socket repro, ran it before changing the gate, and observed:

plugin timeline items are sent only to clients that advertise support
AssertionError: expected true to be false
expect(legacyLiveItems.some((item) => item.type === "plugin")).toBe(false)

Added the blocked-setup mixed-socket repro before implementing its gate:

blocked setup remains readable on mixed-capability sockets sharing a session
Expected: { status: "failed", error: "Workspace setup is blocked ... Update Paseo ..." }
Received: { status: "blocked", error: null }

Targeted automated checks: only the four changed test files were run, never the full local suite.

npx vitest run --config packages/server/vitest.config.ts packages/server/src/server/selective-timeline-delivery.e2e.test.ts --bail=1
Test Files  1 passed (1)
Tests       7 passed (7)

npx vitest run packages/server/src/server/wire-compat.test.ts --bail=1
Test Files  1 passed (1)
Tests       7 passed (7)

npx vitest run packages/protocol/src/messages.wire-compat.test.ts --bail=1
Test Files  1 passed (1)
Tests       13 passed (13)

npx vitest run packages/client/src/daemon-client.test.ts --bail=1
Test Files  1 passed (1)
Tests       120 passed (120)

npm run build:server  # exit 0
npm run typecheck    # exit 0, all workspaces
npm run lint
Found 0 warnings and 0 errors.
npm run format      # exit 0

The WebSocket coverage exercises persisted plugin appends, both timeline projections, mixed capabilities on a shared session in both connection orders, provider-child live delivery and fetches, and real rewind reconstruction from a controllable provider adapter. The setup progress test publishes through the public session boundary and verifies per-source adaptation without mutating the snapshot. The existing attention test needed workspace ownership and directory subscriptions added to its fixture to match the current delivery contract; it now passes without changing attention behavior.

Manual published-client QA: installed npm's @getpaseo/client@0.7.2 into a separate temporary prefix, including its published 0.7.2 protocol dependency. A temporary source harness started createTestPaseoDaemon on 127.0.0.1:0, with an isolated PASEO_HOME, daemon version 0.8.0-beta.1, and a real Codex provider. Connected the published old client and current source client before creating the agent.

The current plugin-examples/timeline-items example is client-only. Copied it into the isolated directory and added this temporary server contribution so its rows were persisted through the actual plugin-session append RPC:

server.on("agent.created", async (event, context) => {
  const timeline = context.paseo.agents.ref(event.agent.id).timeline;
  for (const status of ["pending", "completed"] as const) {
    await timeline.append({
      type: "plugin", id: "compat-task", kind: "pi-task-list", version: 1,
      data: { tasks: [{ text: "Compatibility QA", status }] },
    });
  }
});

Installed that copy with installDirectoryPlugin. Its temporary manifest requirement was >=0.8.0-beta.1; the original example's stable >=0.8.0 requirement correctly rejects the beta. No example files were changed in this PR. Sent the real agent: Reply with exactly COMPAT_OK. Do not use any tools.

Commands and observed output (temporary paths and the generated agent ID omitted):

npm install --prefix <temporary-prefix> --no-audit --no-fund @getpaseo/client@0.7.2
added 7 packages in 1s

npx tsx packages/server/src/server/compat-072-qa.tmp.ts
Isolated daemon {"port":33109,"home":"<isolated-home>","version":"0.8.0-beta.1"}
Installed plugin {"id":"pi-tasks-timeline","path":"<isolated-plugin>","enabled":true,"status":"running"}
Real provider agent created <agent-id>
Fetch after persisted plugin append {"oldTypes":[],"currentTypes":["plugin"],"currentCollapsed":[["identity"]],"sameWindow":true}
Published 0.7.2 client live and fetch {"liveTypes":["user_message","assistant_message","assistant_message"],"fetchTypes":["user_message","assistant_message","assistant_message"],"error":null}
PASS: published 0.7.2 parses live assistant messages and timeline fetches while current client sees persisted plugin rows and identity merges.
Stopped isolated daemon

Also seeded persisted fork provenance before daemon startup, then fetched setup status through both real clients:

{
  "old": {
    "status": "failed",
    "error": "Workspace setup is blocked pending approval of code from a fork pull request. Update Paseo to review and run setup."
  },
  "current": {
    "status": "blocked",
    "error": null,
    "blockedSource": {
      "kind": "change_request", "forge": "github", "number": 42,
      "headRepository": "contributor/project"
    }
  }
}

This verifies the restart/status path with fork provenance; an actual remote fork checkout and its live setup UI were not exercised. Live setup progress is covered at the session boundary. Only the isolated daemon was stopped; existing services were untouched. The temporary harness is not part of the diff.

Fallback compiler probe:

AOT union + loose object compiled: 1
Unknown type accepted: true
Malformed known type also accepted: true

Platform	Tested	Notes
iOS	No	Published client protocol exercised in Node; no device UI run
Android	No	Published client protocol exercised in Node; no device UI run
Web	CI	All four Playwright regression shards; no manual UI run
Desktop macOS	CI build	Desktop build passed; no manual macOS run
Desktop Windows	CI server tests	Server suite passed; no manual Windows run
Desktop Linux	Daemon/SDK and CI	Isolated source daemon, real provider, published old client, Ubuntu server suite and builds; no Electron UI run

Compatibility in the other direction is unchanged: new clients only add optional hello capability keys, which older daemons already accept. No wire member becomes required, narrower, or removed. The remaining risk is another newly introduced union member elsewhere; this PR verifies the two release findings above, not an exhaustive historical protocol audit.

Checklist

• One focused change
• npm run typecheck passes
• npm run lint passes
• npm run format passes
• QA evidence
• Tests added or updated where it made sense

[greptile-apps]

Greptile Summary

This PR preserves compatibility between v0.7.2 clients and v0.8 daemons by adapting newly introduced timeline items and workspace setup states at the client-delivery boundary.

• Advertises explicit capabilities for plugin timeline items and blocked workspace setup states.
• Filters plugin rows from legacy live streams, timeline fetches, rewind replay, and provider-subagent delivery while preserving canonical pagination metadata.
• Converts blocked setup snapshots to the legacy failed shape on a per-socket basis without mutating stored state.
• Adds mixed-capability WebSocket coverage and corrects compatibility-version documentation.
• Clarifies the authority granted by hub.execute.

Confidence Score: 5/5

The PR appears safe to merge; no actionable compatibility, security, or repository-rule issue remains.

The current implementation gates newly introduced timeline rows and setup states per receiving socket while preserving canonical state and pagination metadata. The three previous findings are not outstanding: all threads are resolved, and the recent changes also move E2E conditionals into helpers and convert the identified arrow helpers to function declarations.

Important Files Changed

Filename	Overview
packages/server/src/server/session.ts	Centralizes capability-aware filtering of timeline items and per-socket adaptation of blocked workspace setup messages.
packages/server/src/server/selective-timeline-delivery.e2e.test.ts	Adds mixed-capability coverage across live delivery, fetches, provider subagents, rewind replay, and setup status; the previously reported test-style violations are resolved.
packages/protocol/src/client-capabilities.ts	Defines optional capability keys for the two v0.8 wire additions.
packages/client/src/daemon-client.ts	Makes current clients advertise support for plugin timeline items and blocked setup states.
packages/protocol/src/messages.wire-compat.test.ts	Documents and verifies the legacy incompatibility of plugin rows, identity merges, and blocked setup snapshots.
packages/server/src/server/wire-compat.test.ts	Verifies per-source setup adaptation and preservation of the canonical snapshot.
public-docs/hub/security.md	Clarifies that hub execution authority includes provider-mode configuration that may bypass approval prompts.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  D[Canonical daemon state] --> S[Session delivery boundary]
  S --> C{Client capabilities}
  C -->|plugin_timeline_items| N[Current client receives plugin rows]
  C -->|No plugin capability| L[Legacy client receives filtered timeline]
  C -->|workspace_setup_blocked| B[Current client receives blocked state]
  C -->|No blocked capability| F[Legacy client receives failed compatibility state]

Loading

_{Reviews (2): Last reviewed commit: "test(protocol): clarify compatibility te..." | Re-trigger Greptile}