Skip to content

feat(sessions): expose bounded page metadata - #199

Merged
SarthakWade merged 2 commits into
feat/194-headless-doctorfrom
feat/196-session-metadata
Sep 19, 2026
Merged

SarthakWade merged 2 commits into
feat/194-headless-doctorfrom
feat/196-session-metadata

Conversation

@SarthakWade

Copy link
Copy Markdown
Collaborator

Summary

  • preserve the ordered sessions array while adding fixed-shape URL, title, age, isolation, lifecycle, and truncation metadata
  • read metadata without focus changes, agent-control activation, semantic snapshots, or page JavaScript on WebKit and Chromium
  • sanitize HTTP(S) URLs, remove userinfo, bound all page-derived strings, and isolate per-session failures and close races
  • publish typed nested result contracts in the TypeScript and Python SDKs and record the cross-engine decision

Security

  • marks the command and every detail as untrusted page-derived content
  • exposes no cookies, storage, credentials, authentication state, process IDs, native IDs, or filesystem paths
  • queries engines after releasing shared state locks and returns controlled unavailable states without leaking errors

Validation

  • pnpm test
  • pnpm test:runtime
  • pnpm test:npm
  • Python SDK: 42 tests, mypy, and ruff
  • pnpm --filter @headless/web lint
  • pnpm --filter @headless/web build
  • pnpm --filter @headless/app build
  • Linux Chromium P2 E2E in a provisioned test image
  • focused real WKWebView normal and isolated session metadata flow

The full local macOS E2E currently stops before this scenario in the existing start-page address HUD accessibility click (Headless has no accessible windows). The focused WKWebView G4 flow passes.

Closes #196

@SarthakWade
SarthakWade added this pull request to stack #202 September 19, 2026 09:58

@yashranaway yashranaway left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

session.list stays additive at protocol 0.5. The name array is unchanged. Each detail is a fixed shape: name, isolated, ageMs, status, nullable http(s) URL and title, truncation flags, and untrustedContent: true.

URLs drop userinfo and anything that is not http/https. Title is capped at 1,000 bytes, URL at 8,192. The host lock is released before engine I/O. WebKit reads WKWebView on the main thread. Chromium uses Page.getNavigationHistory plus host navigation flags, not page JS. A session that errors stays unavailable instead of failing the whole list.

CI is green, including SDK generation. Stacks on #198.

@SarthakWade
SarthakWade merged commit 49f1b91 into main Sep 19, 2026
26 checks passed
@SarthakWade
SarthakWade deleted the feat/196-session-metadata branch September 19, 2026 11:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

G4: Expose bounded session metadata in session list

2 participants