Package README

@north-light/plugin lets an application add commands to the crtr CLI, and so to every agent that runs it. You write one typed command tree. The package turns it into a Fetch handler, a commands.json manifest, and the archive that crtr pkg plugin install --endpoint reads. You do not write a manifest, a route table, or a plugin.json.

It is a server-side authoring kit, not a runtime: the handler is a standard Fetch { fetch } default export that you deploy on whatever host serves one. It does not run agents; an agent calls your command the way it calls any other crtr command, and crtr makes an HTTP request to your endpoint. Plugins that need no server, such as local executables, are installed from a marketplace instead; see the plugin docs.

Docs · Commands · Deploying · Official marketplace · crouter repository

Install

npm install @north-light/plugin

The package is ESM-only. Import it from an ES module or use dynamic import() from CommonJS. To try a plugin you also need the crtr CLI: npm install -g @north-light/cli, then run crtr once to sign in to a model provider.

Define a plugin

Create src/crtr-plugin.ts:

import {
  createFetchHandler,
  defineBranch,
  defineLeaf,
  definePlugin,
  field,
  LeafError,
  param,
} from '@north-light/plugin';

export const plugin = definePlugin({
  name: 'acme',
  description: 'Manage Acme applications.',
  whenToUse: 'you need to create or inspect an Acme application.',
  summary: 'Acme application management',
  rootEntry: {
    concept: 'an Acme application',
    description: 'Create and inspect applications.',
    whenToUse: 'the task is about an Acme application.',
  },
  commands: {
    app: defineBranch({
      description: 'Create and inspect applications.',
      whenToUse: 'you are working with an application.',
      summary: 'application operations',
      children: {
        create: defineLeaf({
          description: 'Create an Acme application.',
          whenToUse: 'an application does not exist yet.',
          summary: 'create an application',
          params: {
            name: param.positional('The application name.', { required: true }),
            region: param.enum(['us-east', 'eu-west'], 'The region for the application.', { default: 'us-east' }),
          },
          output: {
            appId: field.string('The created application id.'),
            url: field.string('The application URL.'),
          },
          effects: ['Creates an Acme application.'],
          handler(input) {
            if (input.name === 'taken') {
              throw new LeafError({
                code: 'name_taken',
                message: 'That application name is already in use.',
                status: 409,
                field: 'name',
              });
            }
            return {
              appId: `app_${input.name}`,
              url: `https://${input.name}.${input.region ?? 'us-east'}.acme.example.com`,
            };
          },
        }),
      },
    }),
  },
});

export default {
  fetch: createFetchHandler(plugin, { token: process.env.ACME_CRTR_TOKEN }),
};

The handler input is inferred from params: name is required and region is optional. Deploy the default export at the URL crtr reaches. The same URL handles GET archive requests and POST command requests.

Install into crtr

Set the same bearer token on the machine that runs crtr, then install the handler's actual mount path:

export ACME_CRTR_TOKEN='replace-with-a-secret'
crtr pkg plugin install --endpoint https://acme.example.com/crtr --name acme --auth-env ACME_CRTR_TOKEN
crtr acme app create my-app --region eu-west

export covers commands you type yourself. An agent's crtr acme … runs inside its broker, whose env comes from the profile env store, not from your shell — so for agents, store the token there too: echo -n "$ACME_CRTR_TOKEN" | crtr profile env set <profile> --name ACME_CRTR_TOKEN. Nodes launched under that profile from then on carry it.

Use the actual mount path in --endpoint. The generated archive declares command paths below that path, while crtr stores the origin for later command calls. Installing only https://acme.example.com would send calls to the origin root instead of /crtr.

Serving as an app registered in the directory

An app that serves commands to people who connected it passes directory authentication instead of a static token:

import { createFetchHandler, createNodeHandler } from '@north-light/plugin';

const handler = createFetchHandler(plugin, {
  auth: { issuer: 'https://directory.example', audience: 'https://acme.example.com/crtr', providerId: CLIENT_ID },
  requests,
});

providerId is the app's client id (its OAuth client id), bare or as app:<id>. The directory mints scopes as <provider id>:<group>, so the kit requires <providerId>:<group> on each leaf. Without providerId it requires <plugin name>:<group>, which only a first-party provider whose name equals its id carries — every call from any other app answers 403 scope_missing, and the error's next names the id to set.

On Node, Express or Nest, mount the Fetch handler with createNodeHandler(handler, { bodyLimit?, origin? }). It turns the request into a Fetch Request (using req.rawBody when the framework buffered it, else the stream), refuses a body over bodyLimit (default 65536 bytes) with 413 before the handler runs, streams the response with its repeated headers and set-cookie, and answers 500 if the handler throws. In Nest, a controller method is @All(['', '*path']) serve(@Req() req, @Res() res) { return node(req, res); }; with node:http, createServer((req, res) => void node(req, res)). Pass origin when the public origin differs from the Host header.

Metered provider tools

With directory authentication, configure createFetchHandler(plugin, { auth, receipts: { provider: 'app:acme', rates: { send: { usdPerUnit: 0.01 } }, outbox } }). provider must be the provider's authenticated app:<id> principal, not the plugin name. Rate keys and emitted receipt tool values are command paths after the plugin name: send for crtr acme send, or messages send for crtr acme messages send. A handler calls ctx.meter({ units, unit }) to emit a Crtr-Receipt; the provider persists and posts that same receipt to the directory ledger.

To answer a rate limit, throw a LeafError with retryAfter (seconds, or a Date): throw new LeafError({ code: 'rate_limited', status: 429, message: 'Slow down.', retryAfter: 30 }) answers 429 with Retry-After: 30. headers: { 'X-RateLimit-Reset': '…' } sets any other response header; Content-Type, Content-Length, Content-Encoding, Transfer-Encoding and Crtr-Receipt belong to the kit. For a side-effect leaf the kit passes the headers to requests.store as answer.headers (lowercase names); a store that keeps and returns them makes a repeated request answer with the same headers.

For side-effect leaves, provide requests: { record, read, store, delete }. record(requestId, identity) atomically inserts both the id and {sub, grantee} from the verified caller (or null for a legacy static-token plugin); read(requestId) returns {identity, recordedAt, answer}. The kit refuses a repeated id from a different caller rather than replaying another person's result. store saves the result and receipt transactionally with the outbox. For provider logging, onAnswer(event) receives one metadata-only event per answered leaf POST (principal-chain fields, request/run ids, relative tool, status, duration, receipt id, replay flag); it never receives bearer tokens, arguments, or result bodies, and a logging failure does not alter the answer. createCallerVerifier(auth) is exported for providers that verify requests outside the Fetch handler.

Reference

The plugin guide covers commands, parameters, output, errors and streaming, deployment, and bundles and documents.

@north-light/api: defines the command-manifest schema this package emits.
@north-light/identity: verifies the directory-minted tokens the handler checks under auth.
@north-light/sdk: the application client; a plugin and an SDK app are often the same service.
Main repository: the crtr CLI, the crtrd daemon,.