Skip to content
← Public packages

@kody/origin

Inspect Cursor Origin repositories, pull requests, and installations with a saved Origin App.

FollowFork

Files

AGENTS.md

146 lines · 4.2 KB · Markdown

@kody/origin — agent notes

Human setup and intent live in 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

ItemDefaultNotes
LaneOrigin App JWT → installation tokenVia secret_jwt_sign (EdDSA).
SecretoriginAppPrivateKeyPKCS#8 private key; never returned from helpers.
StorageoriginAppId, originInstallationIdReadable ids via ./settings.
Host / capabilityapi.cursor.com, secret_jwt_signRequired 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

ExportImport
package overviewkody:@kody/origin
accountskody:@kody/origin/accounts
rate-limitkody:@kody/origin/rate-limit
authkody:@kody/origin/auth
installationskody:@kody/origin/installations
reposkody:@kody/origin/repos
pullskody:@kody/origin/pulls
requestkody:@kody/origin/request
settingskody:@kody/origin/settings
typeskody:@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):

import describeOrigin from 'kody:@kody/origin'

export default async function main() {
	return await describeOrigin()
	// => { package: '@kody/origin', secretSetupUrl, ... }
}

Rate limit (Origin App):

import getOriginRateLimit from 'kody:@kody/origin/rate-limit'

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

Mutation preview (no write):

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:

import { listOriginPulls } from 'kody:@kody/origin/pulls'

export default async function main() {
	return await listOriginPulls({
		ownerSlug: 'example-owner',
		repoName: 'example',
	})
}

Create pull (preview first):

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:

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.