Extending Your Agent

Soleri agents follow a three-layer model:

1. Engine (@soleri/core) — vault, brain, planner, curator, loops, governance. Updated via npm update.
2. Agent shell (src/index.ts) — persona, activation, domain facades. Generated by forge.
3. User extensions (src/extensions/) — your custom ops, facades, middleware, and hooks. Never touched by upgrades.

Extensions are additive — they can’t break the engine. npm update @soleri/core is always safe.

Getting started

If your agent was scaffolded with Soleri v5.10+, the src/extensions/ directory already exists. For older agents:

npx @soleri/cli extend init

This creates:

src/extensions/
  index.ts              # Extension manifest (auto-discovered at startup)
  ops/example.ts        # Example custom op
  facades/              # Custom facades (empty)
  middleware/            # Middleware (empty)

Adding custom ops

Custom ops are merged into your agent’s core facade alongside the 200+ built-in ops.

npx @soleri/cli extend add-op summarize_pr

Then implement your logic in src/extensions/ops/summarize-pr.ts:

import { z } from 'zod';
import type { OpDefinition, AgentRuntime } from '@soleri/core';

export function createSummarizePrOp(runtime: AgentRuntime): OpDefinition {
  return {
    name: 'summarize_pr',
    description: 'Summarize a GitHub PR using vault context.',
    auth: 'read',
    schema: z.object({
      prUrl: z.string().describe('GitHub PR URL'),
    }),
    handler: async (params) => {
      const context = runtime.brain.search(params.prUrl as string, { limit: 5 });
      return { summary: '...', relatedPatterns: context };
    },
  };
}

Register it in src/extensions/index.ts:

import { createSummarizePrOp } from './ops/summarize-pr.js';

export default function loadExtensions(runtime) {
  return {
    ops: [createSummarizePrOp(runtime)],
  };
}

Adding custom facades

Facades are separate MCP tools. Use them to group related ops under a distinct namespace.

npx @soleri/cli extend add-facade github

This creates src/extensions/facades/github.ts with a facade named {agent-id}_github. Register it in src/extensions/index.ts under the facades array.

Adding middleware

Middleware wraps all ops across all facades with before/after hooks.

npx @soleri/cli extend add-middleware audit-logger

Middleware follows the onion model:

• before hooks run first → last (outermost middleware sees raw params)
• after hooks run last → first (outermost middleware sees final result)

import type { OpMiddleware } from '@soleri/core';

export const auditLogger: OpMiddleware = {
  name: 'audit-logger',
  before: async (ctx) => {
    console.error(`[audit] ${ctx.facade}.${ctx.op} called`);
    return ctx.params;
  },
  after: async (ctx) => {
    console.error(`[audit] ${ctx.facade}.${ctx.op} returned`);
    return ctx.result;
  },
};

Lifecycle hooks

export default function loadExtensions(runtime) {
  return {
    hooks: {
      onStartup: async (rt) => {
        // Runs after runtime init, before MCP server starts
      },
      onShutdown: async (rt) => {
        // Runs on SIGTERM/SIGINT before process exits
      },
    },
  };
}

What NOT to edit

File	Why
src/index.ts	Regenerated by forge on upgrades
src/activation/	Managed by activation system
node_modules/@soleri/core/	Overwritten by npm update

Keep all customization in src/extensions/.

Upgrading

npm update @soleri/core    # Engine upgrades — your extensions are untouched
npx @soleri/cli upgrade    # CLI upgrades

Other extension commands

Command	What it does
npx @soleri/cli add-domain <name>	Add a domain facade with 5 ops
npx @soleri/cli install-knowledge <path>	Import a knowledge bundle into the vault
npx @soleri/cli hooks add-pack full	Add quality gate hooks
npx @soleri/cli governance --preset moderate	Set vault governance policy

For full command documentation, see CLI Reference. For configuration details, see Customizing Your Agent.