dsh-github-router 0.1.0

package/lib/routes/html.js

@@ -0,0 +1,250 @@
+/**
+ * PR/issue page HTML route.
+ *
+ * SECURITY: pages are parsed with JSON.parse ONLY, applied to exact
+ * `<script type="application/json">` islands (react-app.embeddedData).
+ * Nothing is ever evaluated or executed. Extraction walks the parsed JSON
+ * with a bounded BFS and copies a whitelist of fields (title, body text,
+ * state, author, dates, review/discussion items) — CSRF tokens, sessions,
+ * and everything else in the payload are dropped on the floor. Inputs and
+ * every extracted text are byte-capped.
+ * @module dsh-github-router/routes/html
+ */
+import { fetchText } from '../net.js'
+import { stripHtml } from '../util.js'
+
+const SCRIPT_RE = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi
+const MAX_ISLAND_BYTES = 4194304
+const MAX_WALK_DEPTH = 10
+const MAX_WALK_NODES = 40000
+const MAX_BODY_CHARS = 20000
+const MAX_ITEMS = 60
+
+/** Pull every application/json script island out of a GitHub HTML page. */
+export function extractEmbeddedData(html) {
+  const out = []
+  const source = String(html ?? '').slice(0, MAX_ISLAND_BYTES)
+  SCRIPT_RE.lastIndex = 0
+  let match
+  while ((match = SCRIPT_RE.exec(source)) !== null) {
+    const attrs = match[1]
+    const body = match[2]
+    if (!/type\s*=\s*["']application\/json["']/i.test(attrs)) continue
+    try {
+      const parsed = JSON.parse(body)
+      out.push(parsed)
+    } catch { /* not a valid JSON island — skip, never evaluate */ }
+  }
+  return out
+}
+
+/** Bounded BFS collecting { key, value } pairs matching a predicate. */
+export function walkJson(root, predicate, options = {}) {
+  const maxDepth = options.maxDepth ?? MAX_WALK_DEPTH
+  const maxNodes = options.maxNodes ?? MAX_WALK_NODES
+  const seen = new WeakSet()
+  const hits = []
+  let visited = 0
+  const visit = (node, depth, key) => {
+    // The predicate runs for every node — scalars included — so key-based
+    // matchers see `{key: "scalar"}` entries too. The hits cap is checked
+    // BEFORE pushing so scalar-heavy trees cannot blow past maxNodes.
+    if (hits.length >= maxNodes) return
+    if (predicate(key, node, depth)) hits.push({ key, value: node })
+    if (node === null || typeof node !== 'object' || seen.has(node)) return
+    if (visited >= maxNodes) return
+    visited += 1
+    seen.add(node)
+    if (depth > maxDepth) return
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; i += 1) visit(node[i], depth + 1, i)
+    } else {
+      for (const [k, v] of Object.entries(node)) visit(v, depth + 1, k)
+    }
+  }
+  visit(root, 0, null)
+  return hits
+}
+
+function isPrLike(node) {
+  return (
+    node !== null &&
+    typeof node === 'object' &&
+    Number.isInteger(node.number) &&
+    typeof node.title === 'string' &&
+    ('additions' in node || 'headRefName' in node || 'headRef' in node)
+  )
+}
+
+function isIssueLike(node) {
+  return (
+    node !== null &&
+    typeof node === 'object' &&
+    Number.isInteger(node.number) &&
+    typeof node.title === 'string' &&
+    ('bodyHTML' in node || 'body' in node) &&
+    !('additions' in node) &&
+    !('headRefName' in node)
+  )
+}
+
+function bodyOf(node, cap) {
+  const raw = typeof node.bodyHTML === 'string' ? node.bodyHTML : typeof node.body === 'string' ? node.body : ''
+  return stripHtml(raw).slice(0, cap)
+}
+
+function loginOf(node) {
+  if (node && typeof node === 'object' && node.author && typeof node.author === 'object') {
+    return typeof node.author.login === 'string' ? node.author.login : null
+  }
+  if (node && typeof node === 'object' && node.user && typeof node.user === 'object') {
+    return typeof node.user.login === 'string' ? node.user.login : null
+  }
+  return null
+}
+
+/** Find the best PR-shaped node across all embedded JSON payloads. */
+export function prFromPayloads(objects) {
+  const candidates = []
+  for (const obj of objects) {
+    for (const { key, value } of walkJson(obj, (k, v) => isPrLike(v))) {
+      candidates.push({ key, value })
+    }
+  }
+  if (candidates.length === 0) return null
+  // Prefer nodes reachable under a `pullRequest` key; then the richest shape.
+  candidates.sort((a, b) => {
+    const ak = a.key === 'pullRequest' ? 0 : 1
+    const bk = b.key === 'pullRequest' ? 0 : 1
+    if (ak !== bk) return ak - bk
+    return b.value.title.length - a.value.title.length
+  })
+  const pr = candidates[0].value
+  const refName = (v) => (v && typeof v === 'object' && typeof v.name === 'string' ? v.name : null)
+  const shaOf = (v) => (v && typeof v === 'object' && typeof v.oid === 'string' ? v.oid : null)
+  return {
+    title: pr.title,
+    body: bodyOf(pr, MAX_BODY_CHARS),
+    state: typeof pr.state === 'string' ? pr.state : null,
+    author: loginOf(pr),
+    additions: typeof pr.additions === 'number' ? pr.additions : null,
+    deletions: typeof pr.deletions === 'number' ? pr.deletions : null,
+    changedFiles: typeof pr.changedFiles === 'number' ? pr.changedFiles : typeof pr.changed_files === 'number' ? pr.changed_files : null,
+    createdAt: typeof pr.createdAt === 'string' ? pr.createdAt : null,
+    updatedAt: typeof pr.updatedAt === 'string' ? pr.updatedAt : null,
+    mergedAt: typeof pr.mergedAt === 'string' ? pr.mergedAt : typeof pr.merged_at === 'string' ? pr.merged_at : null,
+    baseRef: typeof pr.baseRefName === 'string' ? pr.baseRefName : refName(pr.baseRef ?? pr.base),
+    headRef: typeof pr.headRefName === 'string' ? pr.headRefName : refName(pr.headRef ?? pr.head),
+    baseSha: typeof pr.baseRefOid === 'string' ? pr.baseRefOid : shaOf(pr.baseRef ?? pr.base),
+    headSha: typeof pr.headRefOid === 'string' ? pr.headRefOid : shaOf(pr.headRef ?? pr.head),
+    url: typeof pr.url === 'string' && /^https:\/\//.test(pr.url) ? pr.url : typeof pr.permalink === 'string' ? pr.permalink : null,
+  }
+}
+
+/** Find the best issue-shaped node across all embedded JSON payloads. */
+export function issueFromPayloads(objects) {
+  const candidates = []
+  for (const obj of objects) {
+    for (const { key, value } of walkJson(obj, (k, v) => isIssueLike(v))) {
+      candidates.push({ key, value })
+    }
+  }
+  if (candidates.length === 0) return null
+  candidates.sort((a, b) => {
+    const ak = a.key === 'issue' ? 0 : 1
+    const bk = b.key === 'issue' ? 0 : 1
+    if (ak !== bk) return ak - bk
+    return b.value.title.length - a.value.title.length
+  })
+  const issue = candidates[0].value
+  return {
+    title: issue.title,
+    body: bodyOf(issue, MAX_BODY_CHARS),
+    state: typeof issue.state === 'string' ? issue.state : null,
+    stateReason: typeof issue.stateReason === 'string' ? issue.stateReason : null,
+    author: loginOf(issue),
+    createdAt: typeof issue.createdAt === 'string' ? issue.createdAt : null,
+    updatedAt: typeof issue.updatedAt === 'string' ? issue.updatedAt : null,
+    closedAt: typeof issue.closedAt === 'string' ? issue.closedAt : null,
+    commentsCount: Number.isInteger(issue.commentsCount) ? issue.commentsCount : Number.isInteger(issue.comments?.totalCount) ? issue.comments.totalCount : null,
+    url: typeof issue.url === 'string' && /^https:\/\//.test(issue.url) ? issue.url : null,
+  }
+}
+
+function timelineItem(node) {
+  if (node === null || typeof node !== 'object') return null
+  const type = typeof node.__typename === 'string' ? node.__typename : null
+  if (type === 'IssueComment') {
+    return { kind: 'comment', author: loginOf(node), createdAt: node.createdAt ?? null, body: bodyOf(node, MAX_BODY_CHARS), url: node.url ?? null }
+  }
+  if (type === 'PullRequestReview') {
+    return { kind: 'review', author: loginOf(node), createdAt: node.submittedAt ?? node.createdAt ?? null, state: node.state ?? null, body: bodyOf(node, MAX_BODY_CHARS), url: node.url ?? null }
+  }
+  if (type === 'PullRequestReviewThread' && Array.isArray(node.comments?.nodes)) {
+    const items = []
+    for (const c of node.comments.nodes) {
+      if (c === null || typeof c !== 'object') continue
+      items.push({ kind: 'review-comment', author: loginOf(c), createdAt: c.createdAt ?? null, body: bodyOf(c, MAX_BODY_CHARS), path: c.path ?? null, diffHunk: typeof c.diffHunk === 'string' ? c.diffHunk.slice(0, 4000) : null, url: c.url ?? null })
+    }
+    return items.length > 0 ? items : null
+  }
+  return null
+}
+
+/**
+ * Discussion and review items from timelineItems / reviewThreads arrays in
+ * the payloads. Only whitelisted shapes are copied.
+ */
+export function discussionFromPayloads(objects) {
+  const items = []
+  const seen = new Set()
+  const considerNodes = (nodes) => {
+    if (!Array.isArray(nodes)) return
+    for (const node of nodes) {
+      const mapped = timelineItem(node)
+      const list = Array.isArray(mapped) ? mapped : mapped !== null ? [mapped] : []
+      for (const item of list) {
+        const key = JSON.stringify(item)
+        if (seen.has(key)) continue
+        seen.add(key)
+        items.push(item)
+        if (items.length >= MAX_ITEMS) return
+      }
+      if (items.length >= MAX_ITEMS) return
+    }
+  }
+  for (const obj of objects) {
+    for (const { value } of walkJson(obj, (k, v) => (k === 'timelineItems' || k === 'reviewThreads') && v !== null && typeof v === 'object' && Array.isArray(v.nodes))) {
+      considerNodes(value.nodes)
+      if (items.length >= MAX_ITEMS) break
+    }
+    if (items.length >= MAX_ITEMS) break
+  }
+  return items
+}
+
+/**
+ * Fetch one PR/issue HTML page through the net layer and parse it.
+ * Returns the parsed view or null when the page cannot be fetched/parsed.
+ */
+export async function fetchAndParsePage(owner, repo, number, kind, call) {
+  const url = `https://github.com/${owner}/${repo}/${kind}/${number}`
+  const raw = await call.fetchImpl(url, {
+    headers: {
+      accept: 'text/html,application/xhtml+xml',
+      'user-agent': 'dsh-github-router/0.1.0',
+    },
+    timeoutMs: call.timeoutMs,
+    proxy: call.proxy,
+    signal: call.signal,
+    maxBytes: 4194304,
+    retries: 0,
+  })
+  if (!raw.ok) {
+    const err = new Error(`GitHub page returned HTTP ${raw.status}`)
+    err.code = 'HTTP'
+    throw err
+  }
+  const objects = extractEmbeddedData(raw.body.toString('utf8'))
+  return { objects, pr: prFromPayloads(objects), issue: issueFromPayloads(objects), discussion: discussionFromPayloads(objects) }
+}

package/lib/routes/mirror.js

@@ -0,0 +1,55 @@
+/**
+ * Raw-content mirror route. Mirrors are OFF by default: they are third
+ * parties that see requested paths and serve file bytes, so the user must
+ * explicitly configure and enable them. When enabled, each configured base
+ * yields two candidate URLs per file (raw.githubusercontent.com passthrough
+ * and the github.com /raw/ route).
+ * @module dsh-github-router/routes/mirror
+ */
+import { fetchText } from '../net.js'
+
+export function rawUrl(owner, repo, ref, path) {
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${path}`
+}
+
+export function githubRawRouteUrl(owner, repo, ref, path) {
+  return `https://github.com/${owner}/${repo}/raw/${ref}/${path}`
+}
+
+/** All mirror candidate URLs for one file, in configured mirror order. */
+export function mirrorCandidates(owner, repo, ref, path, mirrors) {
+  const out = []
+  const raw = rawUrl(owner, repo, ref, path)
+  const viaGithub = githubRawRouteUrl(owner, repo, ref, path)
+  for (const mirror of mirrors ?? []) {
+    const base = String(mirror).replace(/\/+$/, '')
+    if (base.length === 0 || !/^https?:\/\//.test(base)) continue
+    out.push(`${base}/${raw}`)
+    out.push(`${base}/${viaGithub}`)
+  }
+  return out
+}
+
+/** Try each mirror candidate in order; returns the first usable body. */
+export async function fetchViaMirrors(owner, repo, ref, path, mirrors, call) {
+  const errors = []
+  for (const url of mirrorCandidates(owner, repo, ref, path, mirrors)) {
+    try {
+      const raw = await fetchText(url, {
+        headers: { accept: 'text/plain', 'user-agent': 'dsh-github-router/0.1.0' },
+        timeoutMs: call.timeoutMs,
+        signal: call.signal,
+        maxBytes: call.maxBytes,
+        retries: 0,
+      })
+      if (raw.ok) return { content: raw.text, truncated: raw.truncated, url, size: raw.body.length }
+      errors.push(`${url} -> HTTP ${raw.status}`)
+    } catch (error) {
+      errors.push(`${url} -> ${String(error && error.code ? error.code + ': ' : '')}${String(error && error.message ? error.message : error)}`)
+      if (call.signal && call.signal.aborted) throw error
+    }
+  }
+  const err = new Error(`all mirrors failed: ${errors.join('; ').slice(0, 500)}`)
+  err.code = 'MIRROR_FAILED'
+  throw err
+}

package/lib/skill.js

@@ -0,0 +1,44 @@
+/**
+ * The `github-router` skill: teaches the agent to use the github_* tools
+ * instead of shell curl/gh/git for GitHub reads, and how to diagnose
+ * connectivity with one probe call.
+ * @module dsh-github-router/skill
+ */
+
+const SKILL = {
+  name: 'github-router',
+  description:
+    'Read GitHub repositories through the github_* tools (probe, pr, issue, file, api) with internal multi-route fallback (API, gh CLI, git protocol, page HTML, mirrors) — read-only, never writes or pushes.',
+  whenToUse:
+    'When a task needs GitHub data (PR review, issue triage, file inspection, repo metadata) and especially when shell-side curl / gh / git / Invoke-WebRequest fails with TLS, proxy, or permission errors.',
+  source: 'custom',
+  invocation: { modelInvocable: true, userInvocable: true },
+  content: `# github-router
+
+## Use the tools
+- \`github_probe\` — one call reports which routes are live (api direct/proxy, gh CLI, git, page HTML, mirrors) with timings and a recommendation. Call it FIRST when GitHub access fails or is slow; do not retry shell commands.
+- \`github_pr\` — load a pull request: metadata, description, discussion (issue + inline review comments), reviews, commits, changed files, and the unified diff. Toggle parts with includeDiscussion/includeReviews/includeCommits/includeFiles/includeDiff and cap sizes with maxDiffBytes / maxItems. Pass \`localRepo\` (or rely on session-cwd auto-detection) to read commits/diff from a local clone with zero network.
+- \`github_issue\` — load an issue with body, labels, and comments.
+- \`github_file\` — read one file (or list a directory) at a branch/tag/sha; returns content, size, truncation state, and the serving route.
+- \`github_api\` — READ-ONLY escape hatch: any api.github.com GET path (e.g. /repos/o/r/commits). Always GET; there is no write verb.
+
+## Why not curl / gh / git in a shell
+The DSH shell sandbox frequently breaks GitHub access (TLS credential resets, proxy misrouting, permission errors), and retrying costs many turns. The github_* tools run in the host process and route internally: api.github.com → gh CLI → git protocol → PR/issue page HTML parse → user-configured mirrors, returning per-part route attribution and failure notes in ONE call. Do NOT escalate sandbox permissions for GitHub reads — call the tools.
+
+## Reviewing a PR (the common case)
+1. \`github_pr\` for the full picture (meta + discussion + commits + files + diff).
+2. \`github_file\` for specific files at the PR head sha when the diff cap is too small.
+3. \`github_probe\` when everything failed, to see which routes are live before any retry.
+For PRs in a local clone, pass \`localRepo\` pointing at the checkout — commits/diff then come from local git with no network at all.
+
+## Security and limits
+- Every tool is read-only: no writes, pushes, comments, or mutations exist anywhere in the plugin.
+- Anonymous API use is rate-limited (60 requests/hour per IP); configure a GitHub token in Settings → Plugins → dsh-github-router (token or GITHUB_TOKEN env) for 5000/hour. Responses are cached to save quota.
+- Mirrors are OFF by default (third parties see requested paths); enable them in settings only if you accept that.
+- Token values are redacted in all tool output.
+`,
+}
+
+export function registerSkill(ctx) {
+  ctx.skills.register(SKILL)
+}

package/lib/tools/api.js

@@ -0,0 +1,101 @@
+/**
+ * `github_api` — the escape hatch: a validated GET-only pass-through to
+ * api.github.com with caching and rate-limit surfacing. There is no other
+ * verb; paths are strictly validated; query values are sanitized.
+ * @module dsh-github-router/tools/api
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { attemptLadder, buildRuntime } from '../core/runtime.js'
+import { renderApi } from '../render.js'
+import { guardApiPath } from '../util.js'
+
+const QUERY_VALUE_RE = /^[\u0020-\u007e\u00a0-\uffff]*$/
+
+function sanitizeQuery(query) {
+  if (query === undefined || query === null) return undefined
+  if (typeof query !== 'object' || Array.isArray(query)) throw new Error('query must be an object of string/number/boolean values')
+  const out = {}
+  const keys = Object.keys(query)
+  if (keys.length > 20) throw new Error('query must have at most 20 entries')
+  for (const key of keys) {
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(key)) throw new Error(`invalid query key "${key}"`)
+    const value = query[key]
+    if (value === undefined || value === null) continue
+    if (typeof value === 'string' && value.length <= 1024 && QUERY_VALUE_RE.test(value)) {
+      out[key] = value
+    } else if (typeof value === 'number' && Number.isFinite(value)) {
+      out[key] = value
+    } else if (typeof value === 'boolean') {
+      out[key] = value ? 'true' : 'false'
+    } else {
+      throw new Error(`query value for "${key}" must be a short string, finite number, or boolean`)
+    }
+  }
+  return out
+}
+
+export function registerApiTool(ctx, options) {
+  ctx.tools.register(
+    defineTool({
+      name: 'github_api',
+      description:
+        'READ-ONLY escape hatch for any api.github.com GET endpoint not covered by the specialized tools. Path must be a plain relative API path (e.g. "/repos/octocat/Hello-World/commits"); the method is always GET — no write, mutation, or body exists. Query values are sanitized; responses are cached briefly, rate-limit headers are surfaced, and errors carry a stable code. Prefer github_pr / github_issue / github_file for common reads.',
+      parameters: {
+        path: { type: 'string', description: 'api.github.com relative path starting with "/", e.g. "/repos/{owner}/{repo}/commits?per_page=5" — pass paging via the query parameter instead.' },
+        query: { type: 'object', additionalProperties: true, description: 'Optional query parameters as an object, e.g. {"per_page": 30, "sha": "main"} (max 20 entries; string/number/boolean values).' },
+        forceRefresh: { type: 'boolean', description: 'Bypass the plugin cache and re-fetch (default false).' },
+      },
+      output: {
+        schema: { type: 'object', additionalProperties: true },
+        render: (_args, value) => renderApi(value),
+      },
+      timeoutMs: 60_000,
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        try {
+          const path = guardApiPath(args && args.path)
+          const query = sanitizeQuery(args && args.query)
+          const runtime = buildRuntime(ctx, options())
+          const token = await runtime.resolveToken()
+          const attempt = await attemptLadder(
+            (proxy) =>
+              runtime.api.getJson(path, {
+                token,
+                signal: exec && exec.signal,
+                proxy,
+                cache: runtime.cache,
+                ttlMs: options().cacheTtlSeconds.meta,
+                forceRefresh: args && args.forceRefresh === true,
+                fetchImpl: runtime.fetchImpl,
+                query,
+              }),
+            options(),
+          )
+          const value = attempt.value
+          const { _headers, _status, cached: _cached, ...rest } = Array.isArray(value) ? {} : value
+          const clean = Array.isArray(value) ? [...value] : rest
+          const out = {
+            path,
+            status: _status ?? 200,
+            rateLimit: _headers && _headers['x-ratelimit-remaining'] !== undefined ? String(_headers['x-ratelimit-remaining']) : null,
+            json: clean !== undefined && typeof clean === 'object' ? clean : null,
+            text: typeof clean === 'string' ? clean : null,
+            truncated: false,
+            via: attempt.via,
+          }
+          // Lossless-JSON guarantee: the tool contract rejects undefined
+          // values; the round-trip strips any that slip through.
+          return JSON.parse(JSON.stringify(out))
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          const code = error && error.code ? error.code : 'ERROR'
+          return { error: `${code}: ${message}`, path: args && args.path ? String(args.path) : undefined }
+        }
+      },
+      presentCall: (args) => ({
+        card: 'generic',
+        title: 'github_api' + (args && args.path ? ' ' + args.path : ''),
+      }),
+    }),
+  )
+}

package/lib/tools/file.js

@@ -0,0 +1,48 @@
+/**
+ * `github_file` — read-only file content with api/raw/mirror/git routing.
+ * @module dsh-github-router/tools/file
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { aggregateFile } from '../core/file.js'
+import { renderFile } from '../render.js'
+import { sessionCwd } from '../util.js'
+
+export function registerFileTool(ctx, options) {
+  ctx.tools.register(
+    defineTool({
+      name: 'github_file',
+      description:
+        'Read a file (or directory listing) from a GitHub repository READ-ONLY. Routes internally: api.github.com contents → raw.githubusercontent.com (direct/proxy) → user-configured mirrors (off by default) → git protocol (plugin fetch cache, or a local clone via localRepo/session cwd). Returns the content with size, truncation state, and the route that served it. Directories return their entry list.',
+      parameters: {
+        owner: { type: 'string', description: 'Repository owner (user or org).' },
+        repo: { type: 'string', description: 'Repository name.' },
+        path: { type: 'string', description: 'Repository-relative file or directory path, e.g. "src/index.js".' },
+        ref: { type: 'string', description: 'Branch, tag, or full commit sha (default "HEAD").' },
+        maxBytes: { type: 'number', description: 'Content cap in bytes, 4096..8388608 (default 262144).' },
+        localRepo: { type: 'string', description: 'Optional path to a local clone; content is read via git show without network.' },
+        forceRefresh: { type: 'boolean', description: 'Bypass the plugin cache and re-fetch (default false).' },
+      },
+      output: {
+        schema: { type: 'object', additionalProperties: true },
+        render: (_args, value) => renderFile(value),
+      },
+      timeoutMs: 120_000,
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        try {
+          return await aggregateFile(ctx, options(), {
+            ...(args ?? {}),
+            cwd: sessionCwd(exec),
+            signal: exec && exec.signal,
+          })
+        } catch (error) {
+          return { error: error instanceof Error ? error.message : String(error) }
+        }
+      },
+      presentCall: (args) => ({
+        card: 'generic',
+        title: `github_file ${args && args.owner ? args.owner : '?'}/${args && args.repo ? args.repo : '?'}${args && args.path ? ' ' + args.path : ''}`,
+      }),
+    }),
+  )
+}

package/lib/tools/issue.js

@@ -0,0 +1,46 @@
+/**
+ * `github_issue` — read-only issue loading with the same route chain.
+ * @module dsh-github-router/tools/issue
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { aggregateIssue } from '../core/issue.js'
+import { renderIssue } from '../render.js'
+import { sessionCwd } from '../util.js'
+
+export function registerIssueTool(ctx, options) {
+  ctx.tools.register(
+    defineTool({
+      name: 'github_issue',
+      description:
+        'Load a GitHub issue READ-ONLY, routing api.github.com (direct/proxy) → gh CLI → the issue page HTML parse internally, with metadata, body, labels, and comments plus per-part route attribution. Use instead of shell curl/gh for issue reads; never writes or comments.',
+      parameters: {
+        owner: { type: 'string', description: 'Repository owner (user or org).' },
+        repo: { type: 'string', description: 'Repository name.' },
+        number: { type: 'number', description: 'Issue number.' },
+        maxComments: { type: 'number', description: 'Cap for comments, 5..200 (default 50).' },
+        forceRefresh: { type: 'boolean', description: 'Bypass the plugin cache and re-fetch (default false).' },
+      },
+      output: {
+        schema: { type: 'object', additionalProperties: true },
+        render: (_args, value) => renderIssue(value),
+      },
+      timeoutMs: 90_000,
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        try {
+          return await aggregateIssue(ctx, options(), {
+            ...(args ?? {}),
+            cwd: sessionCwd(exec),
+            signal: exec && exec.signal,
+          })
+        } catch (error) {
+          return { error: error instanceof Error ? error.message : String(error) }
+        }
+      },
+      presentCall: (args) => ({
+        card: 'generic',
+        title: `github_issue ${args && args.owner ? args.owner : '?'}/${args && args.repo ? args.repo : '?'}${args && args.number ? '#' + args.number : ''}`,
+      }),
+    }),
+  )
+}

package/lib/tools/pr.js

@@ -0,0 +1,56 @@
+/**
+ * `github_pr` — one call to load a pull request across every route:
+ * api.github.com → gh CLI → page HTML parse → git protocol. Returns
+ * metadata, discussion, reviews, commits, changed files, and the diff with
+ * per-part route attribution. Read-only; no write capability exists.
+ * @module dsh-github-router/tools/pr
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { aggregatePr } from '../core/pr.js'
+import { renderPr } from '../render.js'
+import { sessionCwd } from '../util.js'
+
+export function registerPrTool(ctx, options) {
+  ctx.tools.register(
+    defineTool({
+      name: 'github_pr',
+      description:
+        'Load a GitHub pull request READ-ONLY across every available route, internally routing api.github.com (direct/proxy) → gh CLI → the PR page HTML (strict JSON embeddedData parse) → git protocol (plugin fetch cache or a local clone), and returning metadata, description, discussion/review comments, reviews, commits, changed files, and the diff with per-part route attribution. Use this instead of shell curl/gh/git for PR reads — it never writes, pushes, or comments, and one call replaces many failed shell attempts. Parts can be toggled (includeDiscussion/includeReviews/includeCommits/includeFiles/includeDiff) and capped (maxDiffBytes/maxItems). When the local machine already has the repository cloned and fetched, pass localRepo (or the session cwd is auto-detected) to read commits/diff from the local clone with zero network.',
+      parameters: {
+        owner: { type: 'string', description: 'Repository owner (user or org), e.g. "octocat".' },
+        repo: { type: 'string', description: 'Repository name, e.g. "Hello-World".' },
+        number: { type: 'number', description: 'Pull request number.' },
+        includeDiscussion: { type: 'boolean', description: 'Include issue comments and inline review comments (default true).' },
+        includeReviews: { type: 'boolean', description: 'Include formal review summaries (default true).' },
+        includeCommits: { type: 'boolean', description: 'Include the commit list (default true).' },
+        includeFiles: { type: 'boolean', description: 'Include the changed-files list (default true).' },
+        includeDiff: { type: 'boolean', description: 'Include the unified diff (default true).' },
+        maxDiffBytes: { type: 'number', description: 'Cap for the diff in bytes, 4096..1048576 (default 65536).' },
+        maxItems: { type: 'number', description: 'Cap per list (discussion/reviews/commits/files), 5..200 (default 50).' },
+        localRepo: { type: 'string', description: 'Optional path to a local clone of the repo; commits/diff are read from it (log/diff/show only — never fetched, never written).' },
+        forceRefresh: { type: 'boolean', description: 'Bypass the plugin cache and re-fetch (default false).' },
+      },
+      output: {
+        schema: { type: 'object', additionalProperties: true },
+        render: (_args, value) => renderPr(value),
+      },
+      timeoutMs: 120_000,
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        try {
+          return await aggregatePr(ctx, options(), {
+            ...(args ?? {}),
+            cwd: sessionCwd(exec),
+            signal: exec && exec.signal,
+          })
+        } catch (error) {
+          return { error: error instanceof Error ? error.message : String(error) }
+        }
+      },
+      presentCall: (args) => ({
+        card: 'generic',
+        title: `github_pr ${args && args.owner ? args.owner : '?'}/${args && args.repo ? args.repo : '?'}${args && args.number ? '#' + args.number : ''}`,
+      }),
+    }),
+  )
+}

package/lib/tools/probe.js

@@ -0,0 +1,42 @@
+/**
+ * `github_probe` — the connectivity matrix. One call, no shell retries.
+ * @module dsh-github-router/tools/probe
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { aggregateProbe } from '../core/probe.js'
+import { renderProbe } from '../render.js'
+
+export function registerProbeTool(ctx, options) {
+  ctx.tools.register(
+    defineTool({
+      name: 'github_probe',
+      description:
+        'Probe every GitHub route once from the host side and report which ones are live (api.github.com direct/proxy, gh CLI installed/authed, git ls-remote, github.com page direct/proxy, mirrors, token presence) with timings and a recommended route chain. Call this first when GitHub access fails or is slow instead of retrying shell commands; read-only, short timeouts, no side effects.',
+      parameters: {
+        owner: { type: 'string', description: 'Optional repository owner to probe against.' },
+        repo: { type: 'string', description: 'Optional repository name to probe against.' },
+        prNumber: { type: 'number', description: 'Optional PR number; git-ls-remote then probes refs/pull/N/head.' },
+      },
+      output: {
+        schema: { type: 'object', additionalProperties: true },
+        render: (_args, value) => renderProbe(value),
+      },
+      timeoutMs: 90_000,
+      isConcurrencySafe: () => true,
+      async execute(args, exec) {
+        try {
+          return await aggregateProbe(ctx, options(), {
+            ...(args ?? {}),
+            _signal: exec && exec.signal,
+          })
+        } catch (error) {
+          return { error: error instanceof Error ? error.message : String(error) }
+        }
+      },
+      presentCall: (args) => ({
+        card: 'generic',
+        title: 'github_probe' + (args && args.owner ? ' ' + args.owner : ''),
+      }),
+    }),
+  )
+}