Package lifecycle: reuse, execute, fork, or create

Use this guide to decide whether to reuse existing behavior, explore with execute, or create durable repo-backed package code. Use it before scheduling new package behavior.

Choose the smallest durable surface

Invoke an existing package or capability

Search first. If a built-in capability or saved package already does the work, invoke it instead of creating another implementation.

• Call discovered built-in capabilities through kody in execute.
• For a saved package export whose package name is known when the code is written, use a static kody:@scope/package/export import — the default for package reuse from execute and from other packages. Ad hoc execute bundles per call, so static imports from execute always see the current published version.
• When the target's name is data, use import(specifier) for a caller-owned or forked module. Exactly-once work uses workflows.

This is the default for an established operation whose behavior should stay owned by its existing capability or package.

Use execute for temporary one-off exploration

Use execute when the code is disposable: inspect an API response, test an assumption, transform a small result, or run a one-time operation after any required confirmation.

Keep the module focused and return structured evidence. Do not treat the ephemeral module as the durable source for behavior that must be maintained, reused, or evolved.

Ad hoc execute runs with the signed-in user's ambient authority: it can call discovered capabilities through kody. A saved package is the declared-authority unit. Secret mounts, host approval, integration allowlists, and kody.dependencies are the request, and agents cannot widen those. Outbound emissions (email, paid APIs, third-party writes) are not invertible; use a package dryRun and fresh user confirmation before a live mutation.

Fork a close public package before creating

Community listings are excluded from general search. When you need durable reusable behavior and nothing in the user's account fits, call communitySearch for a close public package.

If a listing is close to the user's goal:

1. Inspect it with communityGet.
2. Fork with communityFork (or point the user at one-click install on the listing detail page).
3. Review the forked source, adapt it to the user's intent (including human README.md / ## Intent and agent AGENTS.md), then publish. Publish checks require both files.

Do not reimplement from scratch when a public package is already close. Create a new package only when no suitable listing exists.

Create a repo-backed package

Create or extend a saved package when behavior is reusable, expected to evolve, or needs a named package-owned schedule that evolves with its implementation, and no suitable community listing (or existing saved package) covers it. If the implementation needs a library that does not fit a Worker isolate, keep this package as the orchestrator and offload the heavy process — see Offload work that does not fit a Worker isolate. The repo rooted at package.json is the durable source of truth. Package exports form the callable surface, while jobs, subscriptions, retrievers, and apps remain package-owned behavior.

Recurring schedules belong on a saved package under package.json#kody.jobs. Deferred one-shot work uses workflows.create({ runAt }) from execute or package runtime. See Workflows.

Use guide: "package_authoring" for package shape, required README.md + AGENTS.md, README ## Intent, per-export JSDoc (search Purpose), visibility guidance (personal-details hygiene before going public), and the secret-using package approval checklist (pending_secret_package_approvals is non-null only for unadopted community-forked packages; prefer communityForkAdopt after review, or bulk approval URLs when present). Use guide: "package_apps" when authoring or debugging a hosted package app, community fork of an app, or session handoff. Use guide: "platform_efficiency" for the unique Dynamic Worker day cost model (stated once; not copied into package docs).

When the OAuth token is coarser than the intended export — Gmail can send whenever it can create a draft — publish a thin package that only performs the allowed call, then lock it. Load locked_gmail_drafts for that pattern.

Signals to escalate from execute to a package

Move the behavior into a package when one or more of these become true:

• the user will run it again or other package code should reuse it
• it needs a named package-owned schedule that should evolve with the implementation, or another durable surface such as a subscription, service, app, workflow entrypoint, or package-owned storage
• the logic needs tests, multiple files, dependencies, review, or version history
• inputs, output, error handling, or integration behavior will evolve
• a one-off script has already been copied, repaired, or rerun
• you are calling a third-party product API with raw integration auth helpers (createAuthenticatedFetch or equivalent) beyond a cheap smoke test — integrations = auth; packages = how agents should call the product. Search for an existing wrapper package first, then communitySearch, then fork or create a thin helpers package

Do not create a package merely to wrap one clear call to an existing capability or package export. One-shot reminders and deferred work belong in workflows, not a new package.

Choose an authoring lane

Git lane for coding agents

When a normal filesystem and git client are available:

1. Call packageGetGitRemote. For a new package, pass create: true and a new kody_id; for an existing package, omit create.
2. Run the returned setup commands and clone into a temporary directory. Those commands set local git user.email and user.name from git_author (the signed-in Kody account). Do not invent a git identity.
3. Edit and test through the normal local development loop.
4. Commit and push the package repository.
5. Publish the pushed head with packagePublishExternalPush.

This lane supports binary assets, multi-file changes, local tests, and normal git review.

Tool-only lane

Without local filesystem or git access:

1. Create the complete UTF-8 text package with packageSave, or inspect an existing package with packageGet.
2. Use repoOpenSession, repoEditFiles, repoCommit, and repoRunChecks for repo-backed edits and validation.
3. Publish with repoPublishSession.

If the work needs binary assets, broad refactors, or a substantial local build/test loop, explain that it fits a coding-capable agent and confirm before continuing in the tool-only lane.

Test the scheduled wrapper before enabling its schedule

Scheduled behavior should not be its first real execution. Package job manifests do not supply params to their entrypoints, so structure the package with:

• a shared implementation that accepts explicit input
• an optional callable export that passes representative input to that implementation
• a no-argument scheduled wrapper that loads its own current configuration and calls the same implementation

Make the no-argument scheduled wrapper callable through package.json.exports, point the package job entry at that wrapper, and initially declare the package-owned job with "enabled": false.

After package checks and publishing succeed:

1. Inspect the published package and export contracts.

2. Call the scheduled wrapper from authenticated execute with a static import and no extra arguments. This verifies the same no-input contract the scheduler uses.

3. Optionally invoke the underlying callable export with representative input: realistic field shapes, boundary values, and the same configuration references the wrapper will load. Never put plaintext secrets in params.

4. Validate the structured results and the intended durable or external effects. Exercise an expected failure path when the operation is risky.

5. Only then change the job to "enabled": true, publish again, and verify the package/job detail reflects the enabled schedule.

   Republishing a package whose job still says "enabled": false does not disable a job that is already running. Manifest enabled is the create-time default and can turn a job on; use jobUpdate (or a package pause/resume export) to turn one off. This keeps fleet-wide package publishes from silently stopping a sweeper that an operator already enabled.

Example test call:

import scheduledReport from 'kody:@kentcdodds/daily-report/scheduled-report'

export default async function main() {
	return await scheduledReport()
}

For exports that send messages, write remote records, charge accounts, or make other external mutations, prefer a package-specific dryRun input. Implement it so the export performs validation and returns a preview while skipping the mutation. dryRun is a package contract, not an automatic Kody runtime flag; test the dry-run path first.

Immediately before any live external mutation, obtain explicit user confirmation that identifies the target and scope of the mutation. Do not infer confirmation from an earlier request, a successful dry run, or the agent's own assessment. After confirmation, perform only the confirmed call, then report the result. Require fresh confirmation if the target or scope changes.

Keep the schedule disabled when representative testing is inconclusive, credentials or host approval are missing, the result is unexpected, or the live mutation has not been explicitly confirmed by the user.

Delete a package

packageDelete permanently removes a saved package the signed-in user owns. Do not call it because a package is unused, failing, or over quota unless the owner explicitly asked to delete that package.

1. Load the package with packageGet or packageList.
2. Show the owner the package name and that delete removes jobs, storage, secrets, tokens, the public listing if one exists, and Artifacts repos. Existing forks keep their copies. This cannot be undone.
3. Wait for the owner to type the package name.
4. Call packageDelete with package_id and confirm_name matching that name exactly. The capability refuses and names the expected value when confirm_name is missing or wrong.

People can delete from /@username/{kodyId}/settings: choose Delete package, then type the package name in the modal.

Hiding (packageUpdate changes.hidden) and making a package private are not deletion.

Evolve the durable behavior

For later changes, inspect the current repo, preserve the package's intent, update tests and docs with the implementation, and repeat the disabled schedule/export test when the scheduled path or its inputs change. Publish only checked commits; do not patch generated runtime state as a substitute for changing the package source.