Skip to content

[Feature]: Agent-addressable resource URLs (pr://, skill://, local://) and orca:// deep links #4419

Description

@artile

Problem or use case

Orca already integrates deeply with GitHub/GitLab (PR panels, review comments, gh/GraphQL clients, PR cache, worktrees) and discovers agent skills in the UI, but agents running in terminals cannot address those resources with stable virtual URLs. Today:

  • Deep links are mostly app navigation (orca://pair for runtime pairing; Settings subsection deep links), not agent-readable resources.
  • Terminal and markdown links resolve file:// into the worktree, but there is no equivalent for PRs, issues, skills, or session scratch artifacts.
  • Each agent turn re-fetches PR context via shell/gh or long prose in prompts, which is slow, rate-limit-heavy, and hard to paginate.

oh-my-pi solves this with an internal URL router: schemes like pr://, issue://, skill://, and local:// resolve to rendered content backed by a local SQLite cache, session artifacts, or bounded filesystem roots. Agents read these URLs like files; line selectors (pr://42/diff/all:200-400) keep token use bounded.

Orca’s multi-agent IDE model (Claude, Codex, Pi, orchestration) would benefit from the same virtual resource layer in the main process, wired to existing GitHub/GitLab and skills infrastructure—not a second copy of gh per terminal.

Proposed solution

1. Main-process resource resolver

Add a shared ResourceResolver (name TBD) in the main process with pluggable protocol handlers, similar to OMP’s InternalUrlRouter:

Scheme Resolves to Notes
pr:// / issue:// Rendered PR/issue markdown + diff sub-resources Delegate to existing work-item-details / client.ts; GitLab-aware via hosted-review types
skill:// DiscoveredSkill.skillFilePath Reuse src/shared/skills.ts discovery
local:// or worktree:// Bounded scratch under worktree/session artifacts Traversal-safe; writable for orchestration handoffs
agent:// Named outputs from orchestration / agent-hook runs Coordinator → worker handoff

PR diff family (high value for review):

  • pr://<n>/diff — changed-file listing with per-file hint URLs
  • pr://<n>/diff/<i> — single-file hunk (1-indexed)
  • pr://<n>/diff/all — full unified diff, pageable with line selectors

Caching: extend or align with existing pr-cache / pr-refresh-coordinator using soft/hard TTL (return cached + background refresh), so UI and agents share invalidation.

IPC: resources:resolve(url, { cwd, worktreeId, signal }) returning { content, contentType, notes, immutable? }.

2. Agent and UI bridges

  • Terminal OSC / link click: map review/PR links to pr://owner/repo/n (inject into active agent input or open review tab + copy URL).
  • Quick commands / orchestration skills: templates with pr://{{currentPr}}, skill://orchestration.
  • Pi/OMP compatibility: Pi sessions already understand pr://; Orca supplies default repo from worktree cwd in resolve context.
  • orca:// product deep links (parallel track): orca://worktree/<id>/review, orca://pr/<owner>/<repo>/<n>, orca://file/<path>#L42 — same resolver, different render target (panel vs markdown text).

3. Phased rollout

  1. Phase A: Resolver + skill:// + pr:// (view + diff family) backed by existing GitHub/GitLab code; IPC only.
  2. Phase B: Terminal link handler + document in skills/orca-cli and skills/orchestration.
  3. Phase C: orca:// UI deep links + optional SQLite render cache dedicated to agent reads.

4. Security

  • Reject empty/./.. path segments on network-backed URLs (match OMP hardening).
  • local:// must not escape worktree/session root (realpath + boundary checks).
  • Read-only schemes must not be writable via the resolver.

Alternatives or additional context

Reference implementation: oh-my-pi packages/coding-agent/src/internal-urls/ (router.ts, issue-pr-protocol.ts, local-protocol.ts, github-cache.ts). System prompt documents URL shapes in system-prompt.md.

Orca already has: rich PR/issue fetching, GitLab support, skills discovery UI, orchestration, file:// routing for preview/terminal, orca://pair, agent hooks. This feature surfaces that stack to agents—not replace it.

Top harness ideas worth prioritizing after the core resolver:

  1. pr:// / issue:// with diff sub-paths and line selectors
  2. Shared rendered cache (soft/hard TTL) aligned with PR refresh
  3. skill:// / rule:// for prompt-stable skill references
  4. local:// worktree-scoped scratch for multi-agent handoffs
  5. agent:// addressable orchestration outputs
  6. Click-to-inject resource URLs in terminal (extend OSC routing beyond file://)
  7. LSP diagnostics dedup after agent-driven edits (OMP lsp.diagnosticsDeduplicate)
  8. Context compaction with recoverable artifact://-style placeholders for long sessions
  9. MCP reconnect circuit breaker for SSH/runtime hosts

Out of scope for v1: embedding full OMP read tool inside Orca; eval notebook / hashline edit mode (overlap with existing orchestration skill and review UI).

Docs: add docs/agent-resource-urls.md with scheme grammar, IPC contract, and GitLab mapping when implementation starts.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestsize/lLarge PR (≤2500 added lines, ≤50 files)

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions