Repository navigation
Description
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://pairfor 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/
ghor 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 URLspr://<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
- Phase A: Resolver +
skill://+pr://(view + diff family) backed by existing GitHub/GitLab code; IPC only. - Phase B: Terminal link handler + document in
skills/orca-cliandskills/orchestration. - 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:
pr:///issue://with diff sub-paths and line selectors- Shared rendered cache (soft/hard TTL) aligned with PR refresh
skill:///rule://for prompt-stable skill referenceslocal://worktree-scoped scratch for multi-agent handoffsagent://addressable orchestration outputs- Click-to-inject resource URLs in terminal (extend OSC routing beyond
file://) - LSP diagnostics dedup after agent-driven edits (OMP
lsp.diagnosticsDeduplicate) - Context compaction with recoverable
artifact://-style placeholders for long sessions - 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.
Activity