# Shared Resources Track ## Purpose This track defines how OpenScout should model broker-owned resources that multiple agents and humans can safely share over time. The goal is to move browser sessions, persistent contexts, files, notes, and later credential handles out of harness-specific state and into durable runtime records owned by the local broker. This is a local-first OpenScout track. The broker is the source of truth. Surfaces can project state, but they should not invent resource ownership or lifecycle rules on their own. ## Goals - Make shared resources first-class broker objects with stable IDs, ownership, permissions, and lifecycle state. - Support browser sessions that can survive shell restarts and be reopened from a persistent context. - Support shared files and artifacts as durable broker records, not just files on disk. - Add a lightweight notes layer for operator and agent collaboration without forcing a full document system. - Reserve a clean path for future credential handles and other sensitive broker-managed resources. - Keep the implementation aligned with the existing local broker/runtime model in `packages/runtime` and the shell/helper split in `docs/ARCHITECTURE.md`. ## Non-Goals - Do not build a generic remote asset manager. - Do not make the shell or harness the owner of resource state. - Do not turn every file on disk into a broker resource. - Do not solve collaborative editing or full document CRDT semantics in this track. - Do not add cross-machine syncing before the local broker model is stable. ## Proposed Resource Model The broker should own one normalized `resources` concept, with typed records underneath it. ### Core Fields - `id`: stable unique ID - `kind`: `browser_session`, `browser_context`, `file`, `artifact`, `note`, `credential_handle` - `title`: human-readable label - `owner_id`: actor or agent that created or owns the resource - `workspace_id`: current broker/workspace scope - `state`: lifecycle state - `visibility`: `private`, `workspace`, `shared`, `restricted` - `access_policy`: explicit access rule set - `created_at`, `updated_at`, `last_used_at` - `metadata`: JSON for type-specific details ### Type-Specific Payloads - Browser session: `session_id`, `browser_provider`, `live_url`, `context_id`, `tab_ids` - Browser context: `origin`, `domain`, `cookie_scope`, `storage_scope`, `bb_context_id` or equivalent backend handle - File/artifact: `mime_type`, `size_bytes`, `sha256`, `storage_key`, `source_message_id`, `source_invocation_id` - Note: `body`, `markdown`, `linked_record_id`, `pinned` - Credential handle: `provider`, `secret_ref`, `scope`, `rotation_state`, `redacted_preview` ### Suggested State Machine - `creating` - `active` - `idle` - `expired` - `closed` - `archived` - `revoked` for sensitive handles The important rule is that state transitions are broker-owned and observable. A browser tab closing or a shell exiting should not implicitly delete the record. ## Lifecycle And Ownership ### Browser Sessions - A browser session is created when an agent or human opens a shared browser surface through the broker. - A browser session may reference a persistent browser context, but the context must be separate from the live session. - Closing the last visible tab should not necessarily destroy the persistent context. - If the browser backend dies or the shell restarts, the broker should be able to reopen the session from the durable context. - Session usage should be tracked separately from session existence so billing, auditing, and cleanup can be added later. ### Persistent Browser Contexts - Contexts are the durable login/storage boundary. - Contexts are named and workspace-scoped. - A context should be reattachable by any authorized actor, but only if policy allows it. - Duplicate context names should be rejected or require explicit replacement semantics. ### Files And Artifacts - Shared files are immutable broker records once published. - If a user or agent wants a new version, create a new artifact record and link it to the prior version. - The broker should preserve source provenance: who uploaded it, from which message or work item, and under what resource scope. - Long-term storage can live in the support directory or object storage later, but the broker record stays canonical. ### Notes - Notes are lightweight broker records attached to work, browser resources, or workspace scope. - Notes should support pinning, linking, and search, but not full freeform document editing in v1. - A note can summarize a browser context, a debugging session, or a decision trail. ### Credential Handles - Credential handles should never expose raw secret material to the shell surface. - They should point to a secret reference or secure local store entry. - The broker may surface status and ownership, but only the owning actor or an explicitly authorized actor should be able to rebind or revoke them. - This track should define the placeholder schema now so credential support can be added later without changing the resource model. ## Access Rules - The broker is the only writer for resource state. - A resource has exactly one canonical owner, even if many actors can view it. - Visibility should be explicit and default to the least permissive reasonable scope. - A resource may be shared by policy, but sharing must be represented as data, not inferred from a UI list. - Read access should be cheap and broad enough for the shell to render inventory. - Write access should be narrow and enforced in the broker, not in the client. ### Practical Policy Rules - The creator owns the initial resource unless the broker assigns ownership through workflow. - Workspace members can read workspace-visible resources unless the resource kind is restricted. - Sensitive handles are never broadcast in full; only metadata and access status may be shown. - The broker should preserve an audit trail of share, revoke, reopen, and archive actions. ## Runtime And Schema Direction The current runtime schema in `packages/runtime/src/schema.ts` already has the right shape to extend: - `conversations` - `messages` - `invocations` - `flights` - `bindings` - `deliveries` - `collaboration_records` - `events` This track should add a resource layer adjacent to those records, not replace them. ### Suggested Tables - `resources` - `resource_events` - `resource_acl_entries` - `browser_sessions` - `browser_contexts` - `resource_versions` ### Suggested Normalization - `resources` stores the stable identity and lifecycle. - `browser_sessions` stores live-session fields and backend handles. - `browser_contexts` stores persistent login/storage contexts. - `resource_versions` links artifacts and notes over time. - `resource_acl_entries` records explicit sharing and revocation. The broker should expose resource records through the same local API surface that already serves conversations and work items. ## CLI Implications The CLI should make resource ownership visible without forcing users into the desktop shell. Recommended commands: - `scout resources list` - `scout resources open ` - `scout resources share --with ` - `scout resources revoke --from ` - `scout resources archive ` - `scout resources notes add ` - `scout browser contexts list` - `scout browser contexts reopen ` The first pass should prioritize read and inspect commands over mutation commands. If a resource can be opened or reused, the CLI should show the path to do that quickly. ## UI Implications ### Native Shell - The sidebar should surface a resource inventory summary, not just agent status. - Browser contexts should be visible as reusable operational assets, not hidden implementation details. - Shared files and artifacts should be searchable and filterable by kind, owner, and recency. - Notes should appear as attached context on work items, browser contexts, and files. ### Desktop Or Web Surfaces - Surface the current state of shared browser sessions and persistent contexts. - Show whether a resource is active, idle, expired, or revoked. - Make ownership and sharing clear enough that the user can trust what will persist across restarts. ### Operator Experience - The UI should answer: what do I have, who owns it, who can see it, and can I reuse it? - Resource creation should be an explicit action, not a side effect of opening a tool. - If a browser context is reused, the user should see that it is the same context, not a fresh anonymous tab. ## Rollout Phases ### Phase 1 - Add read-only broker inventory for resources. - Add resource IDs and metadata plumbing. - Model browser contexts separately from browser sessions. - Render resource inventory in the shell. ### Phase 2 - Add create/share/revoke flows for browser contexts and shared files. - Attach provenance to artifacts and notes. - Add cleanup and expiration policies for idle browser sessions. ### Phase 3 - Add credential handle records and redacted status views. - Add versioned artifacts and richer notes linking. - Add broker-level auditing for access changes. ## Testing And Verification - Verify resource records survive broker restarts. - Verify a persistent browser context can be reopened after the shell is closed. - Verify revocation removes access without deleting canonical history. - Verify shared files and notes preserve provenance and ownership. - Verify the shell renders a consistent inventory from broker state alone. - Add regression tests for duplicate context naming, stale session recovery, and revoked access. ## Risks - Browser backend semantics may differ between local and remote implementations, so the resource model must stay backend-agnostic. - If ownership is not explicit, shared resources will become ambiguous and hard to clean up. - If files and artifacts are conflated, versioning will become brittle. - If notes become a document editor too early, the track will sprawl. - Credential handles can leak sensitive data if the redaction boundary is not enforced in the broker. ## Open Questions - Should browser contexts live in the same broker database as collaboration records, or in a dedicated resource store with foreign keys back to the core tables? - What is the minimum access policy language needed for v1: owner-only, workspace-visible, or named grants? - Should shared files be immutable by default, or can certain artifact kinds be updated in place? - How much of the notes model should be attached to collaboration records versus separate resource records? - Should credential handles be designed around local OS keychain primitives from the start, or abstracted behind a broker secret reference first? ## Implementation Guidance The root architectural rule is simple: shared resources should feel like durable broker records with a UI, not like tool output that happened to persist somewhere. If a user can reopen it, share it, revoke it, or inspect it later, it belongs in the broker model.