[kentcdodds]

Why

Working GitHub through Kody (the ship-pr loop) surfaced repeated friction: the {{secret:name}} placeholder is documented only in docs/use/, not where agents look mid-flow; a bare kody is not defined ReferenceError gives no hint that import { kody } from 'kody:runtime' is required; repo_open_session rejects the camelCase field spellings agents guess first; and the ship-pr skill had no merge step, so every agent reinvented the merge call.

What

• docs/guides/secret-backed-integration.md: new "Using a saved secret in fetch" section documenting the {{secret:name}} / {{secret:name|scope=user}} placeholder with a worked example and safety rules.
• secret_list / secret_set capability descriptions now mention the placeholder form, so agents discover it from the capability itself.
• getExecutionErrorDetails recognizes X is not defined ReferenceErrors for kody:runtime exports (kody, secretHeaders, …) and returns a runtime_import_missing detail whose next step spells out the exact import to add. Unknown identifiers stay unhinted.
• repoTargetSchema accepts kodyId / packageId as aliases for the snake_case fields and normalizes them, ending the guess-fail-retry round trip.
• .agents/skills/ship-pr/SKILL.md references the new kody:@kentcdodds/github-pr-tools/merge-pr and get-pr-checks package exports (published separately as a Kody package update).

Companion package update (already published)

@kentcdodds/github-pr-tools gained merge-pr, get-pr-checks, and a github-client export (ghRestFetch / ghGraphQL / getGhTokenPlaceholder), and its token discovery now prefers github-kentAccessToken, githubAccessToken, githubPersonalAccessToken, githubToken, then any secret matching /github.*(token|pat)/i, with an explicit getGhTokenPlaceholder(tokenSecretName) override.

System recap — extends existing primitives (medium risk)

Mode: recap · Base: main @ 5339aa9c · Head: ee256fa2

Classification: extends — two capability contracts gain additive behavior (a new execution-error detail kind and input alias normalization); no primitives added.

Primitives touched

Primitive	Group	Impact
capabilities-execute	runtime	extends — new runtime_import_missing error detail kind with import hint
repo-sessions	runtime	extends — repo_open_session target accepts camelCase aliases
capability-registry	runtime	composes — richer secret_list / secret_set descriptions

System map

flowchart LR
	mcpServer["mcp-server"]:::untouched
	capabilitiesExecute["capabilities-execute"]:::extended
	repoSessions["repo-sessions"]:::extended
	capabilityRegistry["capability-registry"]:::touched
	secrets["secrets"]:::untouched
	mcpServer --> capabilityRegistry
	capabilityRegistry --> capabilitiesExecute
	capabilityRegistry --> repoSessions
	capabilitiesExecute --> secrets
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Before / after

before: execute error  → "Error: kody is not defined"
after:  execute error  → "Error: kody is not defined
                          Next step: add `import { kody } from 'kody:runtime'` …"

before: repo_open_session target { kodyId } → validation error, retry required
after:  repo_open_session target { kodyId } → normalized to { kody_id }, succeeds

Testing

• Unit tests added for the runtime_import_missing parser (hinted exports, prefixed message, unknown-identifier passthrough) and for camelCase alias normalization in repo_open_session inputs.
• Package exports smoke-tested live through execute: get-pr-checks on PR Deslop round 2: real bug fixes — env binding stripping, D1 param limit, silent catches, missing 401 handling #672 (passing, 6 checks), ghRestFetch repo lookup, and merge-pr input validation.

  

Summary by CodeRabbit

• New Features

  • Added clearer guidance for using saved secrets in outbound requests, including placeholder syntax and approved-host behavior.
  • Improved error reporting when code references a missing runtime import, with more actionable hints.

• Bug Fixes

  • Accepted camelCase aliases for repository target fields, while keeping the same normalized output.
  • Expanded coverage for missing-import errors to avoid generic or misleading messages.

• Documentation

  • Updated setup and usage notes for secret handling and PR merge instructions.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds documentation and capability description updates for referencing saved secrets via {{secret:name}} placeholders in fetch calls, expands ship-pr skill merge instructions, normalizes camelCase aliases (packageId/kodyId) into snake_case for repo target schema validation, and adds executor detection for missing kody:runtime import errors.

Changes

Secret placeholder documentation and skill guidance

Layer / File(s)	Summary
Secret placeholder usage docs and capability descriptions docs/guides/secret-backed-integration.md, packages/worker/src/mcp/capabilities/secrets/secret-list.ts, packages/worker/src/mcp/capabilities/secrets/secret-set.ts	Adds a "Using a saved secret in fetch" doc section with placeholder syntax, scope pinning, and usage rules; updates secret_list/secret_set descriptions to reference placeholder resolution for approved hosts.
ship-pr skill merge instructions .agents/skills/ship-pr/SKILL.md	Expands merge-pr instructions with required input shape, CI deploy watching guidance, and Discord follow-up message content.

Repo target camelCase alias normalization

Layer / File(s)	Summary
Repo target schema normalization packages/worker/src/mcp/capabilities/repo/repo-shared.ts, packages/worker/src/mcp/capabilities/repo/repo-open-session.node.test.ts	Introduces repoTargetShapeSchema and normalizeRepoTargetAliases, wraps repoTargetSchema in z.preprocess to convert packageId/kodyId into package_id/kody_id; adds a test verifying camelCase alias parsing.

Executor missing runtime import detection

Layer / File(s)	Summary
runtime_import_missing detection packages/worker/src/mcp/executor.ts, packages/worker/src/mcp/executor.node.test.ts	Adds a runtime_import_missing variant to ExecutionErrorDetails, a known export names set, and parseMissingRuntimeExportMessage helper wired into getExecutionErrorDetails; adds tests covering kody/secretHeaders detection and unknown identifiers.

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related PRs

• kentcdodds/kody#483: Both PRs modify the same secret capability description texts in secret-list.ts and secret-set.ts.
• kentcdodds/kody#590: Both PRs update the merge-pr instructions in the same ship-pr SKILL.md file.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main usability fixes: secret placeholders, runtime import hints, and camelCase repo target aliases.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/kody-github-friction-4ed0

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔎 Preview deployed: https://kody-pr-674.kody-a99.workers.dev

Worker: kody-pr-674
D1: kody-pr-674-db
KV: kody-pr-674-oauth-kv

Mocks:

• cloudflare: https://kody-pr-674-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-674-mock-cloudflare)