Custom Executors

A custom executor replaces provider execution for one or more model declarations. Use one when a model isn’t in Pi’s catalog, needs a private transport, or requires provider-specific behavior outside the shared HTTP contract. Policies stay independent — they choose a model, Router Core dispatches to whatever executor that model declares.

Return A Completion

import { createRouter, type RouterExecutor } from "@dari/router-core";

const acmeExecutor: RouterExecutor = {
  async execute({ request, model, decision, signal }) {
    const result = await acme.generate({
      model: model.id,
      input: request.items,
      reasoningEffort: decision.reasoningEffort,
      signal,
    });
    return {
      type: "complete",
      output: {
        content: [{ type: "text", text: result.text }],
        finishReason: "stop",
        usage: { inputTokens: result.inputTokens, outputTokens: result.outputTokens },
      },
    };
  },
};

const router = createRouter({
  models: [{ id: "acme/private-model", executor: "acme" }],
  policy: ({ candidates }) => ({ model: candidates[0]!.id }),
  executors: { acme: acmeExecutor },
});

Completion content can include text, tool calls, reasoning, and hosted web_search calls. Finish reason must be stop, length, or tool_calls.

Return A Stream

Stream event types

The normalized stream contract uses seven event types:

type RouterStreamEvent =
  | { type: "text_delta"; index: number; delta: string }
  | { type: "tool_call_start"; index: number; id: string; name: string }
  | { type: "tool_call_delta"; index: number; delta: string }
  | { type: "tool_call_end"; index: number }
  | { type: "reasoning_delta"; index: number; delta: string }
  | {
      type: "reasoning_end";
      index: number;
      redacted?: boolean;
      source?: RouterProviderIdentity;
      itemId?: string;
      continuation?: ProviderContinuationState;
    }
  | { type: "finish"; finishReason: "stop" | "length" | "tool_calls"; usage?: RouterUsage };

reasoning_delta streams readable thinking text; reasoning_end closes the block and may carry the provider identity and stable item ID used to sign plain reasoning, or an encrypted continuation. Redacted thinking is a bare reasoning_end with redacted: true and no prior deltas.Router Core validates ordering: tool calls must start before their deltas end, an index can’t mix text, reasoning, and open tool calls, open tools and open reasoning blocks must close before finish, and nothing follows finish.

const streamingExecutor: RouterExecutor = {
  execute() {
    return {
      type: "stream",
      events: {
        async *[Symbol.asyncIterator]() {
          yield { type: "text_delta", index: 0, delta: "Hello" } as const;
          yield { type: "text_delta", index: 0, delta: " world" } as const;
          yield { type: "finish", finishReason: "stop", usage: { inputTokens: 10, outputTokens: 2 } } as const;
        },
      },
    };
  },
};

Declare Capabilities

Custom models need explicit capability metadata so Router Core knows which requests they can handle:

import type { RouterModel } from "@dari/router-core";

const model = {
  id: "acme/private-model",
  executor: "acme",
  provider: "acme",
  api: "private-rpc",
  reasoningEfforts: ["off", "high"],
  defaultReasoningEffort: "off",
  capabilities: { imageInput: true, toolUse: true, structuredOutput: true, streaming: true },
} satisfies RouterModel;

The satisfies RouterModel ascription matters for standalone declarations: without it, reasoningEfforts infers as string[] and the object no longer type-checks when passed to createRouter. Objects written inline inside models: [...] are contextually typed and don’t need it. When omitted: provider defaults to the prefix before /, API defaults to the executor name, reasoning efforts default to ["off"], all capabilities default to false.

Cancellation And Cleanup

The executor receives the same AbortSignal as the policy. Request cancellation or response-body cancellation abort it. Router Core calls return() on the stream iterator when streaming ends early. Release transport resources in a finally block.

Retry And Fallback

The executor owns same-model retries — Router Core doesn’t classify provider errors or decide what’s retryable. Cross-model fallback belongs to createRouter: with fallback: { enabled: true }, when the selected model’s executor call fails, the router retries once on the first other eligible candidate before returning an error. requiresDifferentProvider: true restricts the fallback to another provider. The response reports the model that actually served — in dari_routing and the X-Router-Selected-Model header — and if the fallback model doesn’t support the decision’s reasoning effort, its own default effort is used. A lease pinning the failed primary is dropped so the next turn selects fresh.

const router = createRouter({
  models,
  policy,
  runtime: pi,
  fallback: { enabled: true, requiresDifferentProvider: true },
});

For richer behavior — error classification, retry budgets, billing-aware fallback chains — host the phased API yourself or use the managed platform.

Get Started

Build A Router

Advanced

Custom Executors

Return A Completion

Return A Stream

Declare Capabilities

Cancellation And Cleanup

Retry And Fallback

​Return A Completion

​Return A Stream

​Declare Capabilities

​Cancellation And Cleanup

​Retry And Fallback

Return A Completion

Return A Stream

Declare Capabilities

Cancellation And Cleanup

Retry And Fallback