Package README

@crouter/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 @crouter/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 @crouter/cli && crtr sys setup.

Define a plugin

Create src/crtr-plugin.ts:

import {
  createFetchHandler,
  defineBranch,
  defineLeaf,
  definePlugin,
  field,
  LeafError,
  param,
} from '@crouter/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.

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.

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.

Related

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

License

GPL-3.0-only.