[kentcdodds]

Summary

Live probes after #1035 still show ~600–1100 ms of platform overhead per packages.invoke / invokeChecked call for a trivial export, while a static kody:@scope/pkg/export import costs ~0 ms per call after bundling. Month-to-date Analytics Engine (kody_usage_events) shows package_export averaging ~4.3 s with ~75% of samples ≥ 700 ms — nested dynamic runs are expensive at scale.

This PR flips agent-facing defaults to static imports first, cheapens the remaining warm dynamic path, and documents systemic D1/observability budgets so overhead does not multiply unchecked as user count grows.

Measurements (part 1)

In-sandbox probe (github/accounts, heykody.dev, this session):

Path	Call 1	Call 2	Call 3
Static import	0 ms	0 ms	0 ms
packages.invoke	1063 ms	657 ms	646 ms
packages.invokeChecked	590 ms	583 ms	650 ms

Analytics Engine (UTC month-to-date, success, weighted by _sample_interval):

metric	samples	avg ms	≥ 700 ms share
execute	~60k	~2495	mixed (includes user work)
package_export	~9.5k	~4322	~75%

Use dynamic invoke only when you need: fresh published-export semantics without republishing the caller; target-package runtime (packageContext / packageSecrets / nested packages); or mediated cross-package storage. Otherwise static import is equivalent for library-like reuse (and packageStorage() still works via bundler provenance).

Guidance flip (part 2)

• Execute tool description + MCP server lifecycle/convention fragments
• Search package entity detail: ## Import vs invoke (static first) + per-export Prefer: static snippet
• docs/use/execute.md, docs/use/packages.md, package lifecycle/authoring/integration guides
• Contributing packages-and-manifests copy

Cheapening (part 3)

• Kind-aware resolveSavedPackage (one D1 hit for kodyId)
• 60s source-row cache before manifest cache keying
• Published-artifact KV payload isolate cache (D1 identity row stays authoritative)
• Insert-first idempotency claim on the fresh-key path
• package_export metering via waitUntil when available

Systemic recommendation

See docs/contributing/per-call-platform-overhead.md:

• Per-call D1 budgets for execute / static composition / invoke*
• Watch kody_usage_events package_export avg and ≥700 ms share, and the execute:package_export volume ratio
• Every new awaited D1 write is users × calls — require a budget note in PRs

System recap — extends existing primitives (medium risk)

Mode: recap · Base: main @ 05e1f2f5 · Head: b2a974c8

Classification: extends — agent-facing MCP/search guidance and warm
package-invoke hot-path caching/claim ordering change; no new primitives.

Primitives touched

Primitive	Group	Impact
mcp-server	surfaces	extends — static-import-first execute/MCP/search copy
saved-packages	assistant	extends — source-row warm cache; invoke guidance
bundle-artifacts-kv	storage	extends — KV payload isolate cache for published artifacts
capabilities-execute	runtime	extends — package_export metering via waitUntil

System map

Agents discover packages through MCP search/execute; this PR steers them to
static kody:@ imports and cheapens the remaining dynamic invoke path's D1/KV
hops.

Legend: green = composes (wiring only) · amber = extended by this PR · red =
new primitive · gray = context (unchanged, included only when an edge crosses
it).

flowchart LR
	mcpServer["mcp-server<br/>MCP endpoint"]:::extended
	savedPackages["saved-packages<br/>Saved packages"]:::extended
	bundleKv["bundle-artifacts-kv<br/>Bundle artifacts KV"]:::extended
	capabilitiesExecute["capabilities-execute<br/>Capabilities execute runtime"]:::extended
	mcpServer -->|"Import vs invoke search detail"| savedPackages
	mcpServer -->|"static kody:@ default in execute tool"| capabilitiesExecute
	savedPackages -->|"kind-aware resolve + source-row cache"| capabilitiesExecute
	capabilitiesExecute -->|"warm KV artifact payload cache"| bundleKv
	capabilitiesExecute -->|"insert-first idempotency + waitUntil metering"| savedPackages
	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

Agent default

- packages.invokeChecked({ kodyId, exportName, params })
+ import fn from "kody:@scope/package/export"
+ // invokeChecked only for fresh-version / target-runtime edge cases

Warm invokeChecked

- SELECT idempotency then INSERT OR IGNORE
+ INSERT OR IGNORE first (fresh-key path); SELECT only on conflict
- await recordUsage(package_export) on response path
+ waitUntil(recordUsage) when available

Invariants

Per-user isolation unchanged: package resolve, idempotency rows, artifact KV
keys, and usage events remain scoped by userId.

  

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 20d4b769-075e-4036-a3c4-2b750985bfb1

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}