Plugins

An AgentUse plugin is an installable package. A plugin can contribute executable extensions today, with other resource types such as skills and agents able to use the same package boundary in the future. An extension is a TypeScript or JavaScript module that exports one activation function. The function receives a stable API and registers events, providers, or provider patches. AgentUse waits for async activation before model discovery and execution begin.

import type { AgentUseExtension } from "agentuse/plugin-api";

const extension: AgentUseExtension = async (agentuse) => {
  agentuse.on("agent:complete", async (event) => {
    agentuse.log.info(`${event.agent.name} completed`);
  });

  agentuse.registerProvider({
    // provider definition
  });
};

export default extension;

Extensions run as trusted code with the same operating-system permissions as AgentUse. Review third-party plugins before installing them.

Loose project and global extensions

Single-file extensions are discovered automatically from the existing plugin directories:

.agentuse/plugins/*.{ts,js} for the current project.
$AGENTUSE_CONFIG_DIR/plugins/*.{ts,js} for every project (defaults to ~/.agentuse/plugins/*.{ts,js}).

Project registrations are scoped to the current asynchronous execution, so concurrent server runs from different projects do not share project providers or event handlers. The historical event-object format remains supported:

export default {
  "agent:complete": async (event) => {
    console.log(event.result.text);
  },
};

It is equivalent to calling agentuse.on("agent:complete", handler). New extensions should use the activation API.

Event API

agentuse.on(event, handler) returns a disposable registration. Handlers run sequentially in registration order and receive a context containing an abort signal. Logging stays on the activation API so handlers can close over agentuse.log.

const registration = agentuse.on("agent:complete", async (event, context) => {
  agentuse.log.info(`${event.agent.name}: ${event.result.text}`);
});

await registration.dispose();

There are three intercepting events and five observational events:

Event	Can affect execution?	Purpose
`tool:call`	Mutate `event.input`; return `{ block, reason, terminate }`	Inspect, rewrite, or deny a tool call before AgentUse policy and execution
`tool:result`	Return `{ output, isError }`	Rewrite the result passed back to the model or recover/convert an error
`agent:complete`	Return `{ text }`	Rewrite the final outward response before channels and callers receive it
`agent:start`	No	Observe an execution starting
`agent:error`	No	Observe a terminal execution error
`agent:suspend`	No	Observe suspension for human approval
`agent:resume`	No	Observe an approval or continuation resume
`model:fallback`	No	Observe a model fallback before the next attempt

Observational events and non-input fields are immutable snapshots. tool:call is the deliberate exception: every handler shares the same mutable input object, so later handlers, AgentUse approval policy, and the tool see prior mutations. Return-based transformations from tool:result and agent:complete are also chained through later handlers. A handler failure is logged and does not prevent later handlers from running.

Intercepting tools

agentuse.on("tool:call", async (event) => {
  if (event.toolName === "search") {
    event.input.limit ??= 10;
  }

  if (event.toolName === "bash" && event.input.command === "forbidden") {
    return { block: true, reason: "Blocked by project policy", terminate: true };
  }
});

agentuse.on("tool:result", async (event) => {
  if (event.toolName === "search" && !event.isError) {
    return { output: redactSecrets(event.output) };
  }
});

block denies the tool call. reason is returned to the model. terminate stops the agent loop after the denied result instead of allowing another model turn.

Transforming the final response

agentuse.on("agent:complete", async (event) => {
  return { text: addFooter(event.result.text) };
});

The replacement becomes the returned and delivered final text. The session timeline remains the raw streamed execution trace.

Event shapes

interface AgentReference {
  name: string;
  model: string;
  description?: string;
  filePath?: string;
}

interface AgentCompleteEvent {
  agent: AgentReference;
  result: {
    text: string;
    duration: number;
    tokens?: number;
    toolCalls: number;
    toolCallTraces?: ToolCallTrace[];
    finishReason?: string;
    finishReasons?: string[];
    hasTextOutput: boolean;
  };
  isSubAgent: boolean;
  consoleOutput: string;
}

interface AgentStartEvent {
  agent: AgentReference;
  sessionId?: string;
  trigger: "scheduled" | "manual" | "slack" | "api" | "onboarding";
}

interface AgentErrorEvent {
  agent: AgentReference;
  sessionId?: string;
  error: { name?: string; message: string; code?: string };
  duration: number;
}

interface AgentSuspendEvent {
  agent: AgentReference;
  sessionId: string;
  reason: "approval";
  toolCallId?: string;
  approvalUrl?: string;
}

interface AgentResumeEvent {
  agent: AgentReference;
  sessionId: string;
  reason: "approval" | "continue";
}

interface ModelFallbackEvent {
  agent: AgentReference;
  sessionId?: string;
  from: string;
  to: string;
  reason: string;
  attempt: number;
}

Provider API

Register a provider with a unique model prefix, model catalog, transport, and optional authentication and prompt behavior:

agentuse.registerProvider({
  id: "acme",
  name: "Acme Models",
  models: [
    {
      id: "acme-large",
      name: "Acme Large",
      input: ["text", "image"],
      reasoning: true,
      contextWindow: 128_000,
      maxOutputTokens: 16_384,
      cost: { input: 0, output: 0 },
      capabilities: { tools: true },
    },
  ],
  transport: {
    kind: "openai-responses",
    baseURL: "https://models.acme.test/v1",
  },
});

Models are addressed as acme:acme-large. Declared model limits and modalities participate in validation, context compaction, output-token limits, media tools, and agentuse models.

Model catalogs

Providers can declare models directly, inherit a built-in catalog, or discover models asynchronously during activation:

models: { inherit: "anthropic", include: ["claude-sonnet-*"] }

An adapter can retain those model IDs while replacing transport-specific metadata such as subscription pricing:

models: {
  inherit: "anthropic",
  patch: { cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } },
}

models: async ({ fetch, signal }) => {
  const response = await fetch("http://localhost:11434/v1/models", { signal });
  return convertModels(await response.json());
}

Transports

AgentUse includes declarative transports:

anthropic-messages
openai-responses
openai-chat-completions

Use custom when a provider needs a different protocol or a subprocess-backed runtime:

transport: {
  kind: "custom",
  apiVersion: 1,
  async *stream(request, context) {
    for await (const event of runCustomProtocol({
      modelId: context.modelId,
      messages: request.messages,
      tools: request.tools,
      signal: request.signal,
    })) {
      yield event;
    }
  },
}

The custom boundary is owned and versioned by AgentUse; extensions do not import AI SDK types or receive internal provider factories. A request contains normalized messages, function tools, tool choice, common sampling options, provider options, and an abort signal. Custom streams emit these events:

warning before any response output.
text-delta and reasoning-delta, with optional stable block IDs.
tool-call with an ID, name, and structured input.
Optional response-metadata or error events.
Exactly one terminal finish event with a normalized reason and optional token usage.

AgentUse adapts this contract to its internal model runtime. A stream that ends without finish is rejected. When the consumer cancels a run, the request’s abort signal fires and the stream’s iterator is closed, so check request.signal in long-running loops. If the custom transport speaks a known wire protocol, say so with protocol: "anthropic" or protocol: "openai". AgentUse then applies that protocol’s behavior, such as Anthropic output-token limits and which providerOptions block reaches the model. Omit it for a bespoke API.

transport: {
  kind: "custom",
  apiVersion: 1,
  protocol: "anthropic",
  async *stream(request, context) { /* ... */ },
}

Authentication

AgentUse core owns restrictive credential-file permissions, credential persistence, cross-process refresh locking, status reporting, and deletion. Plugins return opaque credentials and implement provider-specific login, refresh, and request resolution.

auth: {
  methods: [{
    id: "oauth",
    type: "oauth",
    name: "Acme SSO",
    environment: ["ACME_TOKEN"],

    async login(interaction, context) {
      await interaction.openBrowser({ url: authorizationUrl });
      const code = await interaction.prompt({
        message: "Paste the authorization code:",
        secret: true,
      });
      return exchangeCode(code, context.signal);
    },

    async refresh(credential, context) {
      return refreshToken(credential, context.signal);
    },

    resolve({ credential }, context) {
      const token = context.env.ACME_TOKEN ?? credential?.access;
      return token ? { bearerToken: token, source: "Acme OAuth" } : undefined;
    },
  }],
}

Login interaction is UI-neutral and supports browser authorization, device codes, prompts, selections, and notifications. The same plugin therefore works in the terminal, desktop app, server, and CI environments. Credentials with a numeric expires property are refreshed five minutes before expiry. AgentUse serializes refreshes and persists the returned credential before resolving request authentication. Declared environment credentials are resolved first, so an explicit process token is never blocked by an expired stored credential. When an adapter takes ownership of legacy provider OAuth, AgentUse moves it atomically into the adapter’s method-specific credential slot.

Readiness checks

A provider that needs something on the machine besides a credential, such as a bridged local CLI, declares an optional check(). AgentUse runs it for agentuse provider list, the dashboard Providers tab, and right after agentuse plugins install, and refuses to build a model for the provider while it fails, so an installed bridge never reports as connected when it cannot run.

agentuse.registerProvider({
  id: 'acme-cli',
  name: 'Acme CLI',
  models: discoverAcmeModels,
  transport: { kind: 'custom', apiVersion: 1, stream: streamAcme },
  async check({ env, signal }) {
    try {
      const version = await runAcme(['--version'], { env, signal });
      return { ok: true, detail: `acme ${version}` };
    } catch (error) {
      return {
        ok: false,
        message: `Acme CLI not found: ${error.message}.`,
        fix: 'npm install -g @acme/cli',
      };
    }
  },
});

detail is shown beside the connected badge. message says what is missing and fix is a command the user can run. A check that throws or takes longer than ten seconds counts as not ready. The dashboard Providers tab renders saved providers immediately, then updates each row as readiness and recent connection checks finish. A row distinguishes Connected, Not verified or Not checked, Reconnect required, Temporarily unavailable, and Not connected, so a stored credential is not presented as proof of a working connection. From the Plugins tab, open in Providers uses a ?provider= link that opens Settings with the matching provider row expanded.

Provider-owned prompts

Prompt contributions have stable IDs and ownership metadata:

prompts: {
  system() {
    return [{
      id: "identity",
      content: "You are the Acme coding agent.",
      position: "prepend",
      portable: false,
    }];
  },
}

Non-portable contributions are removed when model fallback crosses providers. Their IDs are scoped to the registering provider; extensions do not need to compare raw system-message strings.

Built-in provider adapters, patches, and overrides

A plugin can conditionally contribute a transport to an existing provider namespace. The adapter is evaluated before the built-in transport; when its predicate returns false, the built-in provider continues unchanged:

agentuse.registerProvider("openai", {
  name: "Acme SSO transport",
  models: {
    inherit: "openai",
    patch: { cost: { input: 0, output: 0 } },
  },
  transport: {
    kind: "openai-responses",
    baseURL: "https://models.acme.test/v1",
  },
  auth: { methods: [acmeSso] },
  async when(context) {
    return Boolean(await context.auth.resolve("sso"));
  },
  priority: 100,
});

Registering an adapter does not activate it by itself. Its when function receives the normal provider runtime context, including scoped authentication, and is evaluated whenever AgentUse selects provider behavior. If several adapters match, the highest priority wins; equal priorities retain plugin registration order. The selected adapter owns transport, authentication, model metadata, prompt contributions, and media capabilities for that request. If models is omitted, the existing provider catalog and model IDs are inherited unchanged. A plugin can patch a built-in endpoint without replacing its models:

agentuse.registerProvider("anthropic", {
  baseURL: "https://proxy.acme.test/anthropic",
  headers: { "X-Acme-Tenant": "engineering" },
});

A complete replacement must be explicit:

agentuse.registerProvider({
  id: "anthropic",
  name: "Acme Anthropic",
  override: true,
  models: { inherit: "anthropic" },
  transport: { kind: "anthropic-messages" },
});

Accidental built-in ID collisions are rejected. Registrations are removed when their plugin host is disposed.

Distributed packages

Curated provider plugins

AgentUse maintains a deliberately small, release-reviewed shortlist for the provider setup experience. These plugins remain third-party executable code: review their source and project status before installing them. Browse the current choices in Settings > Providers. Each provider card shows its publisher, reviewed version, installation source, and authentication requirements. Community providers maintain their own setup instructions; follow the linked repository for provider-specific credentials and limitations. Some providers use credentials managed by an external application rather than an AgentUse login. The shortlist is bundled with AgentUse rather than fetched from a mutable remote marketplace. A new or changed listing therefore goes through the normal AgentUse release review. The dashboard also exposes an advanced GitHub installation path. It requires an explicit tag or full commit, reads only package.json before showing consent, and installs the exact commit that was inspected. The resulting plugin is labelled Unreviewed. Installed provider plugins can be updated or removed from Settings > Providers; removing a package does not delete its saved credential. The v0.21 compatibility migration is narrower than normal installation: when AgentUse finds an Anthropic OAuth credential written by the removed core flow, it installs the pinned compatibility plugin and adopts the credential without interrupting the user. New users still choose the plugin explicitly. A Git repository package declares its resources in package.json:

{
  "name": "@example/agentuse-provider",
  "version": "1.0.0",
  "keywords": ["agentuse-plugin"],
  "peerDependencies": {
    "agentuse": "*"
  },
  "agentuse": {
    "apiVersion": 1,
    "extensions": ["./src/index.ts"],
    "providers": [
      { "id": "acme", "auth": ["oauth"] }
    ]
  }
}

agentuse.providers is optional static metadata for the dashboard’s safe pre-install preview. It does not register the provider; the extension still does that during activation. Extension entry paths must stay inside the plugin package. Runtime dependencies belong in dependencies. Git installation uses npm install --omit=dev --ignore-scripts; package lifecycle scripts never run implicitly.

Installing and managing packages

agentuse plugins install owner/repository
agentuse plugins install git:github.com/owner/repository@v1
agentuse plugins install https://github.com/owner/repository.git

agentuse plugins list
agentuse plugins update
agentuse plugins update @example/agentuse-provider
agentuse plugins remove @example/agentuse-provider
agentuse plugins uninstall @example/agentuse-provider  # alias

Use -l for project scope:

agentuse plugins install -l ./my-plugin
agentuse plugins install -l owner/repository
agentuse plugins list -l
agentuse plugins update -l
agentuse plugins remove -l @example/agentuse-provider

agentuse plugins install ./my-plugin links the local directory directly, globally by default or into the project with -l. AgentUse validates and activates its current working tree without cloning it, so the folder does not need to be a Git repository and uncommitted edits are available on the next process start. Updating a linked plugin revalidates its manifest; removing it only removes the registry record and never deletes the source directory. plugins update reports “already up to date” when a linked package’s version is unchanged or a source pinned to a tag or commit still resolves to the installed commit. Append a full commit SHA (./my-plugin@<sha>) to clone and pin a local Git checkout instead of linking it. Global packages live under $AGENTUSE_DATA_DIR/plugins, which defaults to ~/.local/share/agentuse/plugins. Managed project packages live under .agentuse/packages; linked plugins in either scope remain in their original directories. Both are recorded in .agentuse/plugins.json. agentuse plugins list --all-scopes displays every scope and marks linked entries. Git tags, branches, and commits can be selected with @ref. Updates retain the configured ref. Git installation and updates clone into staging, install safe runtime dependencies, compile and activate every entry, and only then replace the active checkout. A failed validation leaves the working version in place. The shorter agentuse install|update|list|remove commands remain as compatibility aliases.

Getting Started

Building

Running

Reference

Plugins

Plugins

Loose project and global extensions

Event API

Intercepting tools

Transforming the final response

Event shapes

Provider API

Model catalogs

Transports

Authentication

Readiness checks

Provider-owned prompts

Built-in provider adapters, patches, and overrides

Distributed packages

Curated provider plugins

Installing and managing packages

​Plugins

​Loose project and global extensions

​Event API

​Intercepting tools

​Transforming the final response

​Event shapes

​Provider API

​Model catalogs

​Transports

​Authentication

​Readiness checks

​Provider-owned prompts

​Built-in provider adapters, patches, and overrides

​Distributed packages

​Curated provider plugins

​Installing and managing packages

Plugins

Loose project and global extensions

Event API

Intercepting tools

Transforming the final response

Event shapes

Provider API

Model catalogs

Transports

Authentication

Readiness checks

Provider-owned prompts

Built-in provider adapters, patches, and overrides

Distributed packages

Curated provider plugins

Installing and managing packages