Add dynamic package runtime invocation

[kentcdodds]

Summary

• Expose packages.invoke from kody:runtime for package runtime contexts.
• Route dynamic package calls through the existing package invocation service so callers resolve the target package's current published export at runtime.
• Preserve same-user/package runtime context, add nested invocation depth protection, avoid runtime import cycles, and document idempotency behavior.
• Include parent runtime identity in generated nested idempotency keys so different parent exports sharing a domain idempotency key do not suppress each other.
• Tighten package runtime typechecking so packages.invoke requires one package identifier and one export alias, and declare the existing storage, email, and workflows runtime exports in the ambient module.
• Document when to use dynamic invocation for event subscribers/workflows/agents versus static kody:@ imports for library-like pinned bundle behavior.

Testing

• npx vitest run --config vitest.node.config.ts packages/worker/src/repo/checks.node.test.ts packages/worker/src/package-invocations/service.node.test.ts packages/worker/src/mcp/run-codemode-registry.node.test.ts
• npx vitest run --config vitest.node.config.ts packages/worker/src/package-invocations/service.node.test.ts
• npx vitest run --config vitest.node.config.ts packages/worker/src/package-invocations/service.node.test.ts packages/worker/src/mcp/run-codemode-registry.node.test.ts packages/worker/src/package-runtime/module-graph.node.test.ts
• npx vitest run --config vitest.node.config.ts packages/worker/src/mcp/capabilities/apps/apps-domain.node.test.ts packages/worker/src/mcp/server-instructions.node.test.ts packages/worker/src/mcp/tools/search-format.node.test.ts packages/worker/src/package-invocations/service.node.test.ts packages/worker/src/mcp/run-codemode-registry.node.test.ts packages/worker/src/package-runtime/module-graph.node.test.ts
• npm run format:check
• npm run typecheck
• npm run lint (passes with existing unrelated warning in packages/worker/src/email/inbound.workers.test.ts)
• npm run validate (passes after latest review fixes: format, lint, typecheck, 110 unit/worker test files, 3 Playwright E2E tests, and 2 MCP E2E tests)

  

Summary by CodeRabbit

• New Features

  • Runtime packages.invoke() to call owned packages dynamically from running code, with nested-depth limiting and deterministic auto idempotency keys; runtime exposes a packages helper.

• Documentation

  • Detailed guides on dynamic invocation semantics, error/resolution behavior, idempotency, security/depth safeguards, and migration notes for switching from static imports.

• Tests

  • Expanded tests covering invocation, nesting/depth, idempotency, missing-package/export errors, and runtime preconditions.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces dynamic package invocation (packages.invoke) to the kody runtime, enabling same-user packages to call each other's published exports at runtime without static imports. It includes depth limiting (max 8), automatic idempotency key derivation, comprehensive integration across job/retriever/app/service execution layers, and updated type support.

Changes

Dynamic Package Runtime Invocation

Layer / File(s)	Summary
Types, Contracts & Input Parsing packages/worker/src/mcp/run-codemode-registry.ts, packages/worker/src/package-invocations/service.ts, packages/worker/src/repo/checks.ts	New types PackageInvokeInput, PackageInvokeTools, PackageRuntimeContext, and input parsing helpers normalize package identifiers, export names, params, idempotency keys, and topics.
Core Package Runtime Invocation packages/worker/src/package-invocations/service.ts	createPackageRuntimeInvokeTools implements nested invoke flow with auth/context validation, depth enforcement (max 8), deterministic idempotency key generation, and runtimeDebug/packageContext construction. invokeSavedPackageModule refactored to construct packageContext and runtimeDebug objects. Both invokePackageExportForPackageRuntime and invokePackageExport updated to track and propagate runtimeInvokeDepth.
Codemode Runtime & Helper Prelude packages/worker/src/mcp/run-codemode-registry.ts	Introduces packagesHelperPrelude factory and conditionally registers package_invoke codemode tool. Threads packageInvokeTools and packageInvokeDepth through buildCodemodeFns → buildCodemodeProvider → runModuleWithRegistry → runBundledModuleWithRegistry. Helper prelude injected into execution and exposed via globalThis.__kodyRuntime.packages.
Execution Context Integration packages/worker/src/jobs/service.ts, packages/worker/src/package-retrievers/service.ts, packages/worker/src/package-runtime/package-app.ts, packages/worker/src/package-runtime/package-service.ts	Jobs/retrievers construct callerContext, packageContext, runtimeDebug, and packageInvokeTools before calling runBundledModuleWithRegistry. Package-app implements PackageAppRuntimeBridge.packageInvoke() bridge method. Package-service uses dynamic imports to avoid initialization cycles.
Runtime Module & Type System packages/worker/src/package-runtime/module-graph.ts, packages/worker/src/repo/checks.ts	Generated runtime module exports packages from global runtime. Type-checking prelude declares KodyPackagesInvokeInput, KodyPackagesRuntime types and exports packages from ambient kody:runtime module.
Tests & Documentation docs/contributing/packages-and-manifests.md, docs/use/packages.md, packages/worker/src/mcp/run-codemode-registry.node.test.ts, packages/worker/src/package-invocations/service.node.test.ts, packages/worker/src/package-runtime/module-graph.node.test.ts	Unit tests verify helper injection, dynamic invocation with nested depth tracking, error codes for missing packages/exports, and depth/context enforcement. User docs explain packages.invoke usage, idempotency behavior, and migration from static imports.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• kentcdodds/kody#275: Directly related; both implement and wire package invocation capabilities and touch package-invocations and runtime execution paths.
• kentcdodds/kody#208: Related changes to the repo typecheck prelude and execute-harness globals.
• kentcdodds/kody#250: Related updates to package runtime module generation and tests.

Poem

🐰 I hopped through code to make packages sing,

dynamic calls now bounce on a runtime string,
eight hops deep and keys that never clash,
idempotent echoes keep each call brash,
a rabbit cheers as exports link and spring!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add dynamic package runtime invocation' clearly and concisely summarizes the main feature addition across the changeset: exposing packages.invoke functionality to package runtime contexts for dynamic runtime invocation of saved packages.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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/package-runtime-packages-export

---

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 and usage tips.}

[github-actions]

🔎 Preview deployed: https://kody-pr-429.kentcdodds.workers.dev

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

Mocks:

• cloudflare: https://kody-pr-429-mock-cloudflare.kentcdodds.workers.dev/__mocks (kody-pr-429-mock-cloudflare)

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/worker/src/repo/checks.ts`:
- Around line 215-229: The KodyPackagesInvokeInput currently makes package
identifiers and export names optional so callers like packages.invoke({})
typecheck; change the input to require exactly one package identifier and
exactly one export alias by introducing two small union types (e.g.,
PackageIdentity = { packageId: string; package_id?: never } | { package_id:
string; packageId?: never } and ExportIdentity = { exportName: string;
export_name?: never } | { export_name: string; exportName?: never }) and then
compose KodyPackagesInvokeInput from PackageIdentity & ExportIdentity plus the
remaining optional fields (params, idempotencyKey/idempotency_key, topic,
kodyId/kody_id). Update the KodyPackagesRuntime.invoke signature to accept this
stricter KodyPackagesInvokeInput so callers must supply one package id alias and
one export alias.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0fd8f041-89eb-45fb-a0a2-36a27cbf959e

📥 Commits

Reviewing files that changed from the base of the PR and between b4ab025 and 7ca811b.

📒 Files selected for processing (13)

• docs/contributing/packages-and-manifests.md
• docs/use/packages.md
• packages/worker/src/jobs/service.ts
• packages/worker/src/mcp/run-codemode-registry.node.test.ts
• packages/worker/src/mcp/run-codemode-registry.ts
• packages/worker/src/package-invocations/service.node.test.ts
• packages/worker/src/package-invocations/service.ts
• packages/worker/src/package-retrievers/service.ts
• packages/worker/src/package-runtime/module-graph.node.test.ts
• packages/worker/src/package-runtime/module-graph.ts
• packages/worker/src/package-runtime/package-app.ts
• packages/worker/src/package-runtime/package-service.ts
• packages/worker/src/repo/checks.ts

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 26d3743. Configure here.}