dsh-github-router 0.1.0

package/lib/core/pr.js

@@ -0,0 +1,429 @@
+/**
+ * PR aggregation: tries api.github.com → gh CLI → page HTML → git protocol,
+ * filling each requested part from the first route that can provide it and
+ * recording per-part route attribution plus every failure note. When no
+ * route can produce the metadata, the result is a structured error with the
+ * route matrix instead of a partial guess.
+ * @module dsh-github-router/core/pr
+ */
+import { effectiveProxy } from '../config.js'
+import { ghAuthed, ghPrDiff, ghPrView, ghVersion } from '../routes/gh.js'
+import { GitFetchCache, findLocalRepo, gitVersion, readCachePr, readLocalPr } from '../routes/git.js'
+import { fetchAndParsePage } from '../routes/html.js'
+import { guardByteCount, guardOwnerRepo, guardPrNumber, truncateText } from '../util.js'
+import { attemptLadder, buildRuntime, rateNote } from './runtime.js'
+
+const BODY_CAP = 20000
+
+function shapeApiPr(meta) {
+  return {
+    owner: meta.base && meta.base.repo ? meta.base.repo.owner.login : null,
+    repo: meta.base && meta.base.repo ? meta.base.repo.name : null,
+    number: meta.number ?? null,
+    title: meta.title ?? null,
+    body: truncateText(meta.body ?? '', BODY_CAP).text,
+    state: meta.state ?? null,
+    draft: meta.draft === true,
+    merged: meta.merged === true,
+    author: meta.user && meta.user.login ? meta.user.login : null,
+    additions: meta.additions ?? null,
+    deletions: meta.deletions ?? null,
+    changedFiles: meta.changed_files ?? null,
+    createdAt: meta.created_at ?? null,
+    updatedAt: meta.updated_at ?? null,
+    mergedAt: meta.merged_at ?? null,
+    baseRef: meta.base ? meta.base.ref : null,
+    headRef: meta.head ? meta.head.ref : null,
+    baseSha: meta.base ? meta.base.sha : null,
+    headSha: meta.head ? meta.head.sha : null,
+    url: meta.html_url ?? null,
+  }
+}
+
+function shapeGhPr(json) {
+  return {
+    owner: null,
+    repo: null,
+    number: null,
+    title: json.title ?? null,
+    body: truncateText(json.body ?? '', BODY_CAP).text,
+    state: json.state ?? null,
+    draft: json.isDraft === true,
+    merged: json.mergedAt !== null && json.mergedAt !== undefined,
+    author: json.author && json.author.login ? json.author.login : null,
+    additions: json.additions ?? null,
+    deletions: json.deletions ?? null,
+    changedFiles: json.changedFiles ?? null,
+    createdAt: json.createdAt ?? null,
+    updatedAt: json.updatedAt ?? null,
+    mergedAt: json.mergedAt ?? null,
+    baseRef: json.baseRefName ?? null,
+    headRef: json.headRefName ?? null,
+    baseSha: json.baseRefOid ?? null,
+    headSha: json.headRefOid ?? null,
+    url: null,
+  }
+}
+
+function shapeGhFiles(json) {
+  return Array.isArray(json) ? json.map((f) => ({ path: f.path ?? null, status: null, additions: f.additions ?? 0, deletions: f.deletions ?? 0 })) : []
+}
+
+function shapeGhCommits(json) {
+  if (!Array.isArray(json)) return []
+  return json.map((c) => ({
+    sha: c.oid ?? null,
+    author: Array.isArray(c.authors) && c.authors.length > 0 ? c.authors[0].login : null,
+    date: c.authoredDate ?? null,
+    message: truncateText(`${c.messageHeadline ?? ''}${c.messageBody ? '\n\n' + c.messageBody : ''}`, 2000).text,
+  }))
+}
+
+function shapeGhReviews(json) {
+  if (!Array.isArray(json)) return []
+  return json.map((r) => ({ author: r.author && r.author.login ? r.author.login : null, state: r.state ?? null, submittedAt: r.submittedAt ?? null, body: truncateText(r.body ?? '', BODY_CAP).text }))
+}
+
+function shapeGhComments(json) {
+  if (!Array.isArray(json)) return []
+  return json.map((c) => ({
+    kind: 'comment',
+    author: c.author && c.author.login ? c.author.login : null,
+    createdAt: c.createdAt ?? null,
+    body: truncateText(c.body ?? '', BODY_CAP).text,
+    path: null,
+    url: c.url ?? null,
+  }))
+}
+
+/** Cap one list at maxItems and report how many entries were dropped. */
+function capItems(items, maxItems, notes, label) {
+  if (items.length <= maxItems) return items
+  notes.push(`${label}: showing ${maxItems} of ${items.length}`)
+  return items.slice(0, maxItems)
+}
+
+export async function aggregatePr(ctx, options, args) {
+  const owner = guardOwnerRepo(args.owner, 'owner')
+  const repo = guardOwnerRepo(args.repo, 'repo')
+  const number = guardPrNumber(args.number, 'number')
+  const maxDiffBytes = guardByteCount(args.maxDiffBytes, 'maxDiffBytes', 65536, 4096, 1048576)
+  const maxItems = guardByteCount(args.maxItems, 'maxItems', 50, 5, 200)
+  const include = {
+    discussion: args.includeDiscussion !== false,
+    reviews: args.includeReviews !== false,
+    commits: args.includeCommits !== false,
+    files: args.includeFiles !== false,
+    diff: args.includeDiff !== false,
+  }
+  const forceRefresh = args.forceRefresh === true
+  const { cwd, signal } = args
+
+  const runtime = buildRuntime(ctx, options)
+  const { subprocess, fetchImpl, cache, api } = runtime
+  const token = await runtime.resolveToken()
+  const state = {
+    pr: null,
+    discussion: [],
+    reviews: [],
+    commits: [],
+    files: [],
+    diff: null,
+    diffTruncated: false,
+    routes: { meta: null, discussion: null, reviews: null, commits: null, files: null, diff: null },
+    notes: [],
+  }
+
+  // ------------------------------------------------------------ 1) api route
+  if (options.routes.api) {
+    try {
+      const attempt = await attemptLadder(
+        (proxy) =>
+          api.getJson(`/repos/${owner}/${repo}/pulls/${number}`, {
+            token,
+            signal,
+            proxy,
+            cache,
+            ttlMs: options.cacheTtlSeconds.meta,
+            forceRefresh,
+            fetchImpl,
+          }),
+        options,
+      )
+      const meta = attempt.value
+      state.pr = { ...shapeApiPr(meta), owner, repo, number }
+      state.routes.meta = 'api'
+      rateNote(meta._headers, state.notes)
+    } catch (error) {
+      state.notes.push(`api meta: ${String(error && error.message ? error.message : error).slice(0, 220)}`)
+    }
+  }
+
+  if (state.pr !== null) {
+    const apiGet = (path, query, ttl) =>
+      attemptLadder(
+        (proxy) => api.getJson(path, { token, signal, proxy, cache, ttlMs: ttl, forceRefresh, fetchImpl, query }),
+        options,
+      )
+    const settle = []
+    if (include.files) {
+      settle.push(
+        (async () => {
+          try {
+            const out = await apiGet(`/repos/${owner}/${repo}/pulls/${number}/files`, { per_page: 100 }, options.cacheTtlSeconds.content)
+            state.files = capItems(
+              (Array.isArray(out.value) ? out.value : []).map((f) => ({ path: f.filename ?? null, status: f.status ?? null, additions: f.additions ?? 0, deletions: f.deletions ?? 0 })),
+              maxItems,
+              state.notes,
+              'files',
+            )
+            state.routes.files = 'api'
+          } catch (error) {
+            state.notes.push(`api files: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
+          }
+        })(),
+      )
+    }
+    if (include.commits) {
+      settle.push(
+        (async () => {
+          try {
+            const out = await apiGet(`/repos/${owner}/${repo}/pulls/${number}/commits`, { per_page: 100 }, options.cacheTtlSeconds.content)
+            state.commits = capItems(
+              (Array.isArray(out.value) ? out.value : []).map((c) => ({
+                sha: c.sha ?? null,
+                author: c.author && c.author.login ? c.author.login : c.commit && c.commit.author ? c.commit.author.name : null,
+                date: c.commit && c.commit.author ? c.commit.author.date : null,
+                message: truncateText(c.commit ? c.commit.message ?? '' : '', 2000).text,
+              })),
+              maxItems,
+              state.notes,
+              'commits',
+            )
+            state.routes.commits = 'api'
+          } catch (error) {
+            state.notes.push(`api commits: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
+          }
+        })(),
+      )
+    }
+    if (include.reviews) {
+      settle.push(
+        (async () => {
+          try {
+            const out = await apiGet(`/repos/${owner}/${repo}/pulls/${number}/reviews`, { per_page: 100 }, options.cacheTtlSeconds.meta)
+            state.reviews = capItems(
+              (Array.isArray(out.value) ? out.value : []).map((r) => ({
+                author: r.user && r.user.login ? r.user.login : null,
+                state: r.state ?? null,
+                submittedAt: r.submitted_at ?? null,
+                body: truncateText(r.body ?? '', BODY_CAP).text,
+              })),
+              maxItems,
+              state.notes,
+              'reviews',
+            )
+            state.routes.reviews = 'api'
+          } catch (error) {
+            state.notes.push(`api reviews: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
+          }
+        })(),
+      )
+    }
+    if (include.discussion) {
+      settle.push(
+        (async () => {
+          try {
+            const out = await apiGet(`/repos/${owner}/${repo}/issues/${number}/comments`, { per_page: 100 }, options.cacheTtlSeconds.meta)
+            const comments = (Array.isArray(out.value) ? out.value : []).map((c) => ({
+              kind: 'comment',
+              author: c.user && c.user.login ? c.user.login : null,
+              createdAt: c.created_at ?? null,
+              body: truncateText(c.body ?? '', BODY_CAP).text,
+              path: null,
+              url: c.html_url ?? null,
+            }))
+            let inline = []
+            try {
+              const out2 = await apiGet(`/repos/${owner}/${repo}/pulls/${number}/comments`, { per_page: 100 }, options.cacheTtlSeconds.meta)
+              inline = (Array.isArray(out2.value) ? out2.value : []).map((c) => ({
+                kind: 'review-comment',
+                author: c.user && c.user.login ? c.user.login : null,
+                createdAt: c.created_at ?? null,
+                body: truncateText(c.body ?? '', BODY_CAP).text,
+                path: c.path ?? null,
+                url: c.html_url ?? null,
+              }))
+            } catch { /* inline comments are best-effort */ }
+            state.discussion = capItems([...inline, ...comments], maxItems, state.notes, 'discussion')
+            state.routes.discussion = 'api'
+          } catch (error) {
+            state.notes.push(`api discussion: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
+          }
+        })(),
+      )
+    }
+    if (include.diff) {
+      settle.push(
+        (async () => {
+          try {
+            const attempt = await attemptLadder(
+              (proxy) =>
+                api.getText(`/repos/${owner}/${repo}/pulls/${number}`, 'application/vnd.github.v3.diff', {
+                  token,
+                  signal,
+                  proxy,
+                  fetchImpl,
+                }),
+              options,
+            )
+            const capped = truncateText(attempt.value.text, maxDiffBytes)
+            state.diff = capped.text
+            state.diffTruncated = capped.truncated || attempt.value.truncated
+            state.routes.diff = 'api'
+          } catch (error) {
+            state.notes.push(`api diff: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
+          }
+        })(),
+      )
+    }
+    await Promise.allSettled(settle)
+  }
+
+  // ------------------------------------------------------------ 2) gh route
+  const needGh = state.pr === null || (include.files && state.files.length === 0) || (include.commits && state.commits.length === 0) || (include.reviews && state.reviews.length === 0) || (include.discussion && state.discussion.length === 0)
+  if (options.routes.gh && subprocess !== undefined && needGh) {
+    let ghUsable = false
+    try {
+      ghUsable = (await ghVersion(subprocess, signal)) && (await ghAuthed(subprocess, signal))
+    } catch { ghUsable = false }
+    if (ghUsable) {
+      try {
+        const g = await ghPrView(subprocess, owner, repo, number, { signal })
+        if (state.pr === null) {
+          state.pr = { ...shapeGhPr(g), owner, repo, number }
+          state.routes.meta = 'gh'
+        }
+        if (include.files && state.files.length === 0 && Array.isArray(g.files)) {
+          state.files = capItems(shapeGhFiles(g.files), maxItems, state.notes, 'files')
+          state.routes.files = 'gh'
+        }
+        if (include.commits && state.commits.length === 0) {
+          state.commits = capItems(shapeGhCommits(g.commits), maxItems, state.notes, 'commits')
+          state.routes.commits = 'gh'
+        }
+        if (include.reviews && state.reviews.length === 0) {
+          state.reviews = capItems(shapeGhReviews(g.reviews), maxItems, state.notes, 'reviews')
+          state.routes.reviews = 'gh'
+        }
+        if (include.discussion && state.discussion.length === 0) {
+          state.discussion = capItems(shapeGhComments(g.comments), maxItems, state.notes, 'discussion')
+          state.routes.discussion = 'gh'
+        }
+      } catch (error) {
+        state.notes.push(`gh pr view: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
+      }
+      if (include.diff && state.diff === null) {
+        try {
+          const d = await ghPrDiff(subprocess, owner, repo, number, { signal, maxStdout: maxDiffBytes })
+          state.diff = d.text
+          state.diffTruncated = d.truncated
+          state.routes.diff = 'gh'
+        } catch (error) {
+          state.notes.push(`gh pr diff: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
+        }
+      }
+    } else {
+      state.notes.push('gh route skipped: gh CLI not installed or not authenticated')
+    }
+  }
+
+  // ---------------------------------------------------------- 3) html route
+  if (options.routes.html && (state.pr === null || (include.discussion && state.discussion.length === 0))) {
+    try {
+      await attemptLadder(
+        async (proxy) => {
+          const parsed = await fetchAndParsePage(owner, repo, number, 'pull', {
+            fetchImpl,
+            proxy,
+            signal,
+            timeoutMs: proxy !== undefined ? options.proxyTimeoutMs : options.directTimeoutMs,
+          })
+          if (state.pr === null && parsed.pr !== null) {
+            state.pr = { ...parsed.pr, owner, repo, number }
+            state.routes.meta = 'html'
+          }
+          if (include.discussion && state.discussion.length === 0 && parsed.discussion.length > 0) {
+            state.discussion = capItems(parsed.discussion, maxItems, state.notes, 'discussion')
+            state.routes.discussion = 'html'
+          }
+        },
+        options,
+        { proxyFirst: true },
+      )
+    } catch (error) {
+      state.notes.push(`html page: ${String(error && error.message ? error.message : error).slice(0, 220)}`)
+    }
+  }
+
+  // ------------------------------------------------------------ 4) git route
+  if (options.routes.git && subprocess !== undefined && (state.commits.length === 0 || state.diff === null)) {
+    let gitUsable = false
+    try {
+      gitUsable = await gitVersion(subprocess, signal)
+    } catch { gitUsable = false }
+    if (gitUsable) {
+      try {
+        let read = null
+        let localDir = null
+        try {
+          localDir = await findLocalRepo(subprocess, cwd, owner, repo, options.repos, args.localRepo)
+          if (localDir !== null) read = await readLocalPr(subprocess, localDir, number, { signal, maxDiffBytes })
+        } catch (error) {
+          state.notes.push(`git local repo: ${String(error && error.message ? error.message : error).slice(0, 180)}`)
+        }
+        if (read === null) {
+          const cacheRepo = new GitFetchCache(subprocess, options.gitCacheDir)
+          const fetched = await cacheRepo.fetchPr(owner, repo, number, { proxy: effectiveProxy(options), signal })
+          read = await readCachePr(subprocess, fetched.dir, number, { signal, maxDiffBytes })
+          if (fetched.mergeError !== null) state.notes.push(`git: merge ref unavailable (${fetched.mergeError.slice(0, 120)}); diff falls back to head-only commits`)
+        }
+        if (read !== null && read !== undefined) {
+          if (include.commits && state.commits.length === 0 && read.commits.length > 0) {
+            state.commits = capItems(read.commits, maxItems, state.notes, 'commits')
+            state.routes.commits = 'git'
+          }
+          if (include.diff && state.diff === null && read.diff !== null) {
+            state.diff = read.diff
+            state.diffTruncated = read.diffTruncated
+            state.routes.diff = 'git'
+          }
+          for (const note of read.notes ?? []) if (note.length > 0) state.notes.push(`git: ${note.slice(0, 160)}`)
+        }
+      } catch (error) {
+        state.notes.push(`git route: ${String(error && error.message ? error.message : error).slice(0, 220)}`)
+      }
+    } else {
+      state.notes.push('git route skipped: git not available')
+    }
+  }
+
+  if (state.pr === null) {
+    return {
+      error: `all GitHub routes failed to load PR ${owner}/${repo}#${number}`,
+      routes: state.routes,
+      notes: state.notes,
+    }
+  }
+  return {
+    pr: state.pr,
+    discussion: state.discussion,
+    reviews: state.reviews,
+    commits: state.commits,
+    files: state.files,
+    diff: state.diff,
+    diffTruncated: state.diffTruncated,
+    routes: state.routes,
+    notes: state.notes,
+  }
+}

package/lib/core/probe.js

@@ -0,0 +1,121 @@
+/**
+ * Connectivity probe: runs every route once (short timeouts, GET only) and
+ * reports a matrix of what works from the HOST side, plus a recommended
+ * route chain. This is the first tool to call when GitHub access misbehaves
+ * — one call replaces a dozen shell retries.
+ * @module dsh-github-router/core/probe
+ */
+import { effectiveProxy } from '../config.js'
+import { ghAuthed, ghVersion } from '../routes/gh.js'
+import { gitLsRemote, gitVersion } from '../routes/git.js'
+import { guardOwnerRepo, guardPrNumber } from '../util.js'
+import { buildRuntime } from './runtime.js'
+
+const UA = { accept: 'text/html,application/xhtml+xml', 'user-agent': 'dsh-github-router/0.1.0' }
+
+export async function aggregateProbe(ctx, options, args) {
+  const runtime = buildRuntime(ctx, options)
+  const { subprocess, fetchImpl, api } = runtime
+  const signal = args._signal
+  const token = await runtime.resolveToken()
+  const owner = args.owner !== undefined && args.owner !== null && String(args.owner).trim() !== '' ? guardOwnerRepo(args.owner, 'owner') : null
+  const repo = args.repo !== undefined && args.repo !== null && String(args.repo).trim() !== '' ? guardOwnerRepo(args.repo, 'repo') : null
+  const number = args.prNumber !== undefined && args.prNumber !== null ? guardPrNumber(args.prNumber, 'prNumber') : null
+  const proxy = effectiveProxy(options)
+
+  const checks = []
+  const run = async (route, fn) => {
+    const t0 = Date.now()
+    try {
+      const detail = await fn()
+      checks.push({ route, ok: true, ms: Date.now() - t0, detail: String(detail ?? '').slice(0, 200) })
+    } catch (error) {
+      if (error && error.code === 'ABORTED') throw error
+      checks.push({
+        route,
+        ok: false,
+        ms: Date.now() - t0,
+        detail: String(`${error && error.code ? error.code + ': ' : ''}${error && error.message ? error.message : error}`).slice(0, 200),
+      })
+    }
+  }
+
+  checks.push({ route: 'token', ok: token !== undefined && token !== '', ms: 0, detail: token ? 'token configured' : 'no token — anonymous API limits (60/h) apply' })
+
+  const apiCheck = async (proxyUrl) => {
+    const out = await api.getJson('/rate_limit', { token, signal, proxy: proxyUrl, fetchImpl, ttlMs: 0 })
+    const remaining = out._headers && out._headers['x-ratelimit-remaining']
+    const limit = out._headers && out._headers['x-ratelimit-limit']
+    return `HTTP 200; rate limit remaining ${remaining ?? '?'}${limit !== undefined ? '/' + limit : ''}`
+  }
+  await run('api-direct', () => apiCheck(undefined))
+  if (proxy !== undefined) await run('api-proxy', () => apiCheck(proxy))
+
+  if (subprocess !== undefined) {
+    await run('gh-installed', async () => {
+      if (!(await ghVersion(subprocess, signal))) throw new Error('gh not on PATH')
+      return 'gh CLI present'
+    })
+    await run('gh-authed', async () => {
+      if (!(await ghAuthed(subprocess, signal))) throw new Error('gh auth status failed — run gh auth login')
+      return 'gh CLI authenticated'
+    })
+    await run('git-installed', async () => {
+      if (!(await gitVersion(subprocess, signal))) throw new Error('git not on PATH')
+      return 'git present'
+    })
+    if (owner !== null && repo !== null) {
+      await run('git-ls-remote', async () => {
+        const ref = number !== null ? `refs/pull/${number}/head` : 'HEAD'
+        const out = await gitLsRemote(subprocess, `https://github.com/${owner}/${repo}.git`, ref, { signal, proxy })
+        if (!out.ok) throw new Error(out.error ?? 'ls-remote failed')
+        return `ref ${ref} -> ${out.sha ?? 'unknown'}`
+      })
+    }
+  }
+
+  const page = owner !== null && repo !== null
+    ? `https://github.com/${owner}/${repo}${number !== null ? `/pull/${number}` : ''}`
+    : 'https://github.com'
+  const htmlCheck = async (proxyUrl) => {
+    const out = await fetchImpl(page, {
+      headers: UA,
+      timeoutMs: proxyUrl !== undefined ? options.proxyTimeoutMs : options.directTimeoutMs,
+      proxy: proxyUrl,
+      signal,
+      maxBytes: 65536,
+      retries: 0,
+    })
+    if (!out.ok) throw new Error(`HTTP ${out.status}`)
+    return `HTTP ${out.status} (${out.body.length} bytes)`
+  }
+  await run('html-direct', () => htmlCheck(undefined))
+  if (proxy !== undefined) await run('html-proxy', () => htmlCheck(proxy))
+
+  if (options.routes.mirror && options.mirrors.length > 0) {
+    await run('mirror', async () => {
+      const base = options.mirrors[0].replace(/\/+$/, '') + '/'
+      const out = await fetchImpl(base, { headers: UA, timeoutMs: options.directTimeoutMs, signal, maxBytes: 65536, retries: 0 })
+      if (!out.ok) throw new Error(`HTTP ${out.status}`)
+      return `mirror ${base} reachable (HTTP ${out.status})`
+    })
+  }
+
+  const live = checks.filter((c) => c.ok).map((c) => c.route)
+  const recommendation = []
+  if (live.includes('api-direct')) recommendation.push('api (direct) — richest data, primary route')
+  if (live.includes('api-proxy')) recommendation.push('api (proxy)')
+  if (live.includes('gh-authed')) recommendation.push('gh CLI — fallback for API failures')
+  if (live.includes('html-proxy') || live.includes('html-direct')) recommendation.push('page HTML parse — metadata + discussion fallback')
+  if (live.includes('git-ls-remote')) recommendation.push('git protocol — commits/diff/file fallback (survives HTTP blocks)')
+  if (live.includes('mirror')) recommendation.push('mirrors — raw file fallback')
+  if (recommendation.length === 0) recommendation.push('no route is live — GitHub is unreachable from this host; fix the proxy or network first')
+
+  return {
+    checks,
+    live,
+    recommendation,
+    proxy: proxy ?? null,
+    tokenConfigured: token !== undefined && token !== '',
+  }
+}

package/lib/core/runtime.js

@@ -0,0 +1,89 @@
+/**
+ * Per-call runtime assembly: cache, API client, transport binding, token
+ * resolution, and the direct→proxy attempt ladder each route uses.
+ * @module dsh-github-router/core/runtime
+ */
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { TtlCache } from '../cache.js'
+import { effectiveProxy } from '../config.js'
+import { fetchWithRetry } from '../net.js'
+import { GithubApi } from '../routes/api.js'
+
+/**
+ * Assemble the per-call runtime. Token resolution is memoized per tokenEnv
+ * so one PR aggregation does not re-read the credentials service per
+ * request.
+ */
+export function buildRuntime(ctx, options) {
+  const cache = new TtlCache()
+  const api = new GithubApi({
+    retries: options.retries,
+    directTimeoutMs: options.directTimeoutMs,
+    proxyTimeoutMs: options.proxyTimeoutMs,
+    maxBytes: options.maxBytes,
+  })
+  const fetchImpl = (url, o) => fetchWithRetry(url, o)
+  const credentials = ctx.get('credentials')
+  const tokenMemo = new Map()
+  const resolveToken = () => {
+    const literal = options.token
+    if (literal !== undefined && literal.length > 0) return Promise.resolve(literal)
+    const envName = options.tokenEnv
+    const hit = tokenMemo.get(envName)
+    if (hit !== undefined) return hit
+    const promise = (async () => {
+      if (credentials !== undefined && typeof credentials.resolve === 'function') {
+        try {
+          const resolved = await credentials.resolve(credentialRef(envName))
+          if (resolved && typeof resolved.value === 'string' && resolved.value.length > 0) return resolved.value
+        } catch { /* fall through to env */ }
+      }
+      const env = process.env[envName]
+      return typeof env === 'string' && env.length > 0 ? env : undefined
+    })()
+    tokenMemo.set(envName, promise)
+    return promise
+  }
+  return { cache, api, fetchImpl, resolveToken, subprocess: ctx.get('subprocess'), options }
+}
+
+/**
+ * Run one route function across the direct/proxy ladder. The order flips
+ * with `proxyFirst` (the page-HTML route empirically needs the proxy first
+ * on machines where direct TLS is reset). Aborts propagate; every other
+ * failure is collected so the next attempt can run.
+ */
+export async function attemptLadder(fn, options, spec = {}) {
+  const proxy = effectiveProxy(options)
+  const proxyFirst = spec.proxyFirst === true
+  const attempts = []
+  if (proxyFirst) {
+    if (proxy !== undefined) attempts.push(['proxy', proxy])
+    attempts.push(['direct', undefined])
+  } else {
+    attempts.push(['direct', undefined])
+    if (proxy !== undefined) attempts.push(['proxy', proxy])
+  }
+  const errors = []
+  for (const [label, proxyUrl] of attempts) {
+    try {
+      return { value: await fn(proxyUrl), via: label }
+    } catch (error) {
+      if (error && error.code === 'ABORTED') throw error
+      errors.push(`${label}: ${String(error && error.code ? error.code + ' — ' : '')}${String(error && error.message ? error.message : error)}`)
+    }
+  }
+  const err = new Error(errors.join(' | ').slice(0, 600))
+  err.code = 'ROUTE_FAILED'
+  err.attempts = errors
+  throw err
+}
+
+/** Surface the remaining-rate-limit note without exposing anything secret. */
+export function rateNote(headers, notes) {
+  if (headers && typeof headers === 'object' && typeof headers['x-ratelimit-remaining'] === 'string') {
+    const remaining = headers['x-ratelimit-remaining']
+    const limit = headers['x-ratelimit-limit']
+    notes.push(`api rate limit: ${remaining}${limit !== undefined ? '/' + limit : ''} requests remaining`)
+  }
+}

package/lib/guidance.js

@@ -0,0 +1,24 @@
+/**
+ * One compact system-prompt guidance section (the 100–129 tool-guidance
+ * band): GitHub reads go through the github_* tools, not the shell.
+ * @module dsh-github-router/guidance
+ */
+
+const SECTION_NAME = 'dsh-github-router:guidance'
+const SECTION_ORDER = 118
+
+const GUIDANCE_TEXT =
+  'GitHub reads (PR / issue / file / API data) should go through the github_* tools provided by the dsh-github-router plugin: ' +
+  'github_pr, github_issue, github_file, github_api, and github_probe for connectivity diagnosis. ' +
+  'Do not fight shell-side GitHub failures (curl / gh / git / Invoke-WebRequest) with retries or sandbox escalation — ' +
+  'the shell sandbox commonly breaks GitHub TLS/proxy access, while the tools run host-side and route internally ' +
+  '(api.github.com → gh CLI → git protocol → page HTML parse → configured mirrors), returning per-part route attribution in one call. ' +
+  'All github_* tools are read-only: they never write, push, comment, or mutate anything.'
+
+export function registerGuidance(ctx) {
+  ctx.systemPrompt.section({
+    name: SECTION_NAME,
+    order: SECTION_ORDER,
+    text: () => GUIDANCE_TEXT,
+  })
+}