Handbook

Task `playwright_read_items` v1

Deterministic, read-only batch read of enterprise items (Outlook, Teams, Workday, SharePoint, OneDrive) through an already-attached playwright session facade. Normalizes connector output into the source-neutral…

Updated

Task playwright_read_items v1

Summary

Deterministic, read-only batch read of enterprise items (Outlook, Teams, Workday, SharePoint, OneDrive) through an already-attached playwright session facade. Normalizes connector output into the source-neutral UnifiedItem / ReadResult wire shape (schema_version "1"). Does not call Microsoft Graph, Workday REST, SharePoint REST, or export cookies, storage state, tokens, or auth headers.

Read-only policy

Allowed: attach to an authorized session handle supplied by the host; navigate only within policy allowlists; read visible page metadata, DOM snapshots, and permitted read-only downloads; return redacted wire JSON.

Disallowed: send/reply/approve/submit/upload/delete/rename/move/share; form typing or submit clicks; cookie/storage/token/header export; private app APIs bypassing the browser session.

Inputs

Field Type Required Notes
session_ref string yes Opaque host session handle (not credentials).
source_system string yes One of outlook, teams, workday, sharepoint, onedrive.
source_kind string yes Connector-specific kind (e.g. inbox, channel_posts). For sharepoint, modern library kinds include library_viewport, library_columns, page_health, and library_scroll (plus classic news, list, library).
query object no Source-neutral filters (container, date bounds, text search); may be {}.
cursor string no Pagination cursor from a prior next_cursor.
limit integer no Max items per page; default applied by implementation.

See contract.json input_schema for types.

Output

On success, a ReadResult object:

Field Type Required Notes
schema_version string yes Must be "1".
source_system string yes Matches input source_system.
items array yes Wire UnifiedItem objects (secrets redacted).
next_cursor string no Present when more pages exist.

Each items[] entry includes at minimum: schema_version, item_id, source_system, item_type, source_kind; optional title, body_preview, body_text (policy-gated), actor, participants, timestamps, url, thread_id, container, state, attachments, provenance, raw_ref (non-secret locator only).

Examples

Minimal Outlook inbox read (offline fake session):

{
  "session_ref": "fake-session-1",
  "source_system": "outlook",
  "source_kind": "inbox",
  "query": {},
  "limit": 10
}

{
  "schema_version": "1",
  "source_system": "outlook",
  "items": [],
  "next_cursor": null
}

Failure modes

Structured PlaywrightError (kinds documented in forge_lcdl.playwright.errors):

Kind When
not_attached session_ref invalid or session not bound.
policy_denied URL, tool, or read disallowed by read-only policy.
invalid_query Unknown source_kind or malformed query.
navigation_error Approved navigation failed.
snapshot_error DOM/snapshot capture failed.
parse_failed Connector could not parse visible page into items.
source_unavailable Source UI unavailable or empty in a non-retryable way.

Contract validation failures surface as SchemaFailure when output wire JSON does not match contract.json output_schema.

Verification

  • JSON schema validation against contract.json output_schema after normalization.
  • Each items[] element: required unified fields; no secret-like keys in wire output (sanitize_for_wire).
  • source_system on every item matches the batch source_system.

Skipped-live behavior

  • Default pytest uses FakePlaywrightSession and static fixtures; no network, Graph, Workday APIs, or attached browser.
  • Tests marked playwright_live (when added) require an explicit env flag and attached session; skipped in CI.

Changelog

  • v1 — Initial read-only playwright batch read contract.