# @kody/origin — agent notes Human setup and intent live in [`README.md`](./README.md). This file is for agents: imports, smoke checks, snippets, and edge cases. Secrets by **name** only — never paste private keys or tokens. Do not disable live webhooks or jobs (this package has jobs disabled by design). ## Auth | Item | Default | Notes | | --- | --- | --- | | Lane | Origin App JWT → installation token | Via `secret_jwt_sign` (`EdDSA`). | | Secret | `originAppPrivateKey` | PKCS#8 private key; never returned from helpers. | | Storage | `originAppId`, `originInstallationId` | Readable ids via `./settings`. | | Host / capability | `api.cursor.com`, `secret_jwt_sign` | Required on the secret. | Cloud Agents API keys (`crsr_` / `cursorApiKey`) are **not** Origin credentials. A `401` missing Bearer usually means the wrong credential kind. ### Multiple Origin Apps Every export accepts optional `account` / `integrationName` (default `origin`) and `secretName`. Extra apps use a distinct namespace — for example `origin-work` — which reads secret `originAppPrivateKey-origin-work` and storage keys `originAppId-origin-work` / `originInstallationId-origin-work`. Or pass `secretName` explicitly. `account` is an alias for `integrationName`. When more than one installation is visible and none is saved, helpers throw instead of picking one. ## Mutations and dryRun Create/update/merge helpers, settings writes, and REST methods other than `GET` / `HEAD` / `OPTIONS` require: - `dryRun: true` — validate and return a preview; Origin is not written - `confirm: true` — perform the live write Internal installation-token minting is auth, not a caller-facing mutation. ## Import paths | Export | Import | | --- | --- | | package overview | `kody:@kody/origin` | | accounts | `kody:@kody/origin/accounts` | | rate-limit | `kody:@kody/origin/rate-limit` | | auth | `kody:@kody/origin/auth` | | installations | `kody:@kody/origin/installations` | | repos | `kody:@kody/origin/repos` | | pulls | `kody:@kody/origin/pulls` | | request | `kody:@kody/origin/request` | | settings | `kody:@kody/origin/settings` | | types | `kody:@kody/origin/types` | Prefer static `kody:@kody/origin/...` imports from `execute`. Do not lead with `packages.invoke`. Named helpers (for example `createOriginPull`) are available alongside each module's default export. ## Smoke test (read-only) Package overview (no credentials): ```js import describeOrigin from 'kody:@kody/origin' export default async function main() { return await describeOrigin() // => { package: '@kody/origin', secretSetupUrl, ... } } ``` Rate limit (Origin App): ```js import getOriginRateLimit from 'kody:@kody/origin/rate-limit' export default async function main() { return await getOriginRateLimit() } ``` Mutation preview (no write): ```js import originRequest from 'kody:@kody/origin/request' export default async function main() { return await originRequest({ method: 'POST', path: '/repos/example-owner', body: { name: 'example' }, dryRun: true, }) } ``` ## Common snippets List pulls: ```js import { listOriginPulls } from 'kody:@kody/origin/pulls' export default async function main() { return await listOriginPulls({ ownerSlug: 'example-owner', repoName: 'example', }) } ``` Create pull (preview first): ```js import { createOriginPull } from 'kody:@kody/origin/pulls' export default async function main() { return await createOriginPull({ ownerSlug: 'example-owner', repoName: 'example', title: 'Example', head: 'topic', base: 'main', dryRun: true, }) } ``` Alternate Origin App namespace: ```js import getOriginRateLimit from 'kody:@kody/origin/rate-limit' export default async function main() { return await getOriginRateLimit({ integrationName: 'origin-work' }) } ``` ## Edge cases / fork notes - Origin tokens last at most 15 minutes; this package mints them per call. - Repositories Origin mirrors in from GitHub are outside the installation. - Native Origin repos and repos Origin mirrors out to GitHub are in scope. - Artifacts remains the durable home for Kody package source. - Never paste Ed25519 private keys, installation tokens, or `cursorApiKey` values into chat, README, or package storage.