Package manifest

A package's package.json is its manifest. It names the package, lists what it exports, and declares everything Minion runs for it: jobs, event subscriptions, webhooks and a web app. Minion checks the manifest on every save and returns each problem as a plain sentence the agent can fix.

The file set itself is checked too: at most 200 files, 256 KB per file and 2 MB in total, UTF-8 text, relative paths inside the package, and a README.md.

A complete example

{
  "name": "@acme/billing",
  "exports": {
    ".": "./src/index.ts",
    "./digest": "./src/digest.ts",
    "./on-error": "./src/on-error.ts",
    "./on-paid": "./src/on-paid.ts",
    "./app": "./src/app.ts"
  },
  "minion": {
    "description": "Invoices, reminders and the billing dashboard",
    "tags": ["billing", "stripe"],
    "dependencies": { "@acme/stripe-client": "*" },
    "jobs": [{ "name": "daily", "export": "./digest", "cron": "0 8 * * *", "timezone": "America/Vancouver" }],
    "subscriptions": { "run.error.recorded": { "export": "./on-error", "filters": { "source": "job" } } },
    "emits": { "@acme/invoice.paid": { "description": "An invoice was paid." } },
    "webhooks": [{ "name": "stripe", "export": "./on-paid", "responseMode": "ack" }],
    "app": { "export": "./app", "access": "members", "description": "Billing dashboard" }
  }
}

name

Always @<your organization's slug>/<name>. The name is lowercase letters, numbers, ., _ or -, up to 64 characters. Another organization's scope is refused.

exports

What other code can import, and what jobs, subscriptions, webhooks and the app run. Keys are . or start with ./; values point at a .ts, .tsx, .js, .mjs, .mts or .jsx file in the package.

"exports": { ".": "./src/index.ts", "./digest": "./src/digest.ts" }

A single string is shorthand for { ".": "…" }. Import an export from any code in the organization:

import main from 'minion:@acme/billing'
import digest from 'minion:@acme/billing/digest'

minion.description and minion.tags

A one-line description (up to 200 characters) and up to 10 tags (32 characters each). Search uses both, so agents can find the package later.

minion.dependencies

Other packages in your organization this one imports with minion:@…. The value is always "*": the latest published version when this package is published. A package can't depend on itself or on another organization's package.

minion.jobs

Scheduled runs. Each job runs the default export of export.

• name (required): lowercase letters, numbers and -, unique in the package.
• cron (required): five fields, e.g. 0 8 * * *.
• timezone: an IANA timezone such as Europe/Lisbon. UTC if left out.
• export: one of the package's export keys. Default ..
• params: an object passed to the export on every run.

Jobs come from the runnable version. See Jobs, workflows, and webhooks .

minion.subscriptions

Run an export when an event fires. Keys are topics: a platform topic (list them with minion.events.topicsList(), e.g. run.error.recorded) or a package topic in your scope (@acme/invoice.paid). Up to 20 topics.

"subscriptions": { "run.error.recorded": { "export": "./on-error", "filters": { "source": "job" } } }

filters narrows which events are delivered. See Package subscriptions and events .

minion.emits

The package topics this package dispatches with minion.events.dispatch(), each @<scope>/lower.dot.case with an optional description. Up to 20.

minion.webhooks

Inbound webhooks: a provider POSTs to a secret URL and an export runs. Up to 20 per package.

• name (required): lowercase letters, numbers and -, unique in the package.
• export: the export that handles the request. Default ..
• responseMode: ack (default) answers at once and runs the export in the background; sync waits for the export and returns its response.
• inputMode: request (default) passes the HTTP request; params passes the parsed body.
• rateLimitPerMinute: default 60, up to 600.
• verification, replay, challenge: signature checks (HMAC, verify tokens), replay windows and provider handshakes.

You never handle the URL itself: mint a handle and let the provider's setup use it. See Inbound webhooks .

minion.app

Give the package a web page. export names one of the package's exports; access is members (default) or public; description is optional, up to 200 characters.

"app": { "export": "./app", "access": "public", "description": "Sign the launch guestbook" }

The app is served at https://<org slug>.runminion.run/<name>/, and the package's page in Minion shows the address with an Open app link. See Package apps .

When changes take effect

Saving creates a new version and runs the checks. What runs (jobs, subscriptions, webhooks and the app) always comes from the package's runnable version: the locked version if an owner or admin locked one, otherwise the latest published version.