@agentex/agent 0.0.17 → 0.0.19

package/README.md

@@ -44,22 +44,86 @@ console.log(result.raw);        // the final provider-native event, verbatim (es
 
 ## Built-in Providers
 
-| Provider   | CLI              | Description                                 |
-| ---------- | ---------------- | ------------------------------------------- |
-| `claude`   | `claude`         | Claude Code (Anthropic)                     |
-| `codex`    | `codex`          | Codex CLI (OpenAI)                          |
-| `gemini`   | `gemini`         | Gemini CLI (Google)                         |
-| `cursor`   | `agent`          | Cursor CLI agent                            |
-| `opencode` | `opencode`       | OpenCode                                    |
-| `pi`       | `pi`             | Pi CLI                                      |
-| `openclaw` | gateway HTTP     | OpenClaw HTTP-gateway agent                 |
-| `process`  | any executable   | Generic process executor (arbitrary binary) |
-
-Provider capabilities (sessions, skills, workspaces, MCP, model discovery, quota probing, instructions, concurrent send, cancel queued messages) are declared on each module's `capabilities` field — check `provider.capabilities` to branch on what's supported. Skill-aware providers also report:
+Providers fall into three tiers:
+
+- **Tier 1 — deep native:** `claude`, `codex`. Hand-built adapters over each CLI's richest protocol (Claude's stream-json, Codex's `app-server` JSON-RPC). Subscription-native, fullest feature set.
+- **Tier 2 — ACP:** `gemini`, `copilot`, plus any agent registered via [`acpProvider`](#custom--byok-providers) or `extends: "acp"` config. One shared, tested base over the open [Agent Client Protocol](https://agentclientprotocol.com) (JSON-RPC over stdio).
+- **Tier 3 — bespoke escape hatches:** `opencode` (HTTP/SSE daemon), `pi` (persistent RPC), `cursor` (one-shot), `openclaw` (HTTP gateway), `process` (any executable).
+
+| Provider   | Transport                              | Tier | Sessions  | Modes | Permissions |
+| ---------- | -------------------------------------- | ---- | --------- | ----- | ----------- |
+| `claude`   | `claude` CLI stream-json               | 1    | ✅ resume | —     | ✅          |
+| `codex`    | `codex app-server` JSON-RPC            | 1    | ✅ resume | ✅    | ✅          |
+| `gemini`   | `gemini --acp` (ACP)                   | 2    | ✅        | ✅    | ✅          |
+| `copilot`  | `copilot --acp` (ACP)                  | 2    | ✅        | ✅    | ✅          |
+| `opencode` | `opencode serve` HTTP + SSE            | 3    | ✅ resume | —     | —           |
+| `pi`       | persistent `pi --mode rpc`             | 3    | ✅ resume | —     | —           |
+| `cursor`   | `cursor-agent` stream-json (one-shot)  | 3    | —         | —     | —           |
+| `openclaw` | HTTP gateway                           | 3    | —         | —     | —           |
+| `process`  | any executable                         | 3    | —         | —     | —           |
+
+> `cursor` stays one-shot until `cursor-agent` ships an ACP mode; it can then move to Tier 2 via `extends: "acp"`.
+
+Capabilities (sessions, modes, skills, workspaces, MCP, model discovery, quota probing, instructions, concurrent send, cancel queued messages) are declared on each module's `capabilities` field — check `provider.capabilities` to branch on what's supported. ACP providers set `dynamicCapabilities: true` (their real capability set is negotiated at the ACP `initialize` handshake). Skill-aware providers also report:
 
 - `skillInventory` — `"provider-init"` for Claude's runtime inventory, `"local-discovery"` for Codex, or `"none"`.
 - `skillInvocation` — `"native-slash"` for Claude, `"expanded-prompt"` for Codex, `"configured-only"`, or `"unsupported"`.
 
+## Custom / BYOK providers
+
+Three ways to add providers without forking, all behind the same `getProvider` /
+`ProviderModule` surface. See [internal-docs/spec-provider-architecture.md](../../internal-docs/spec-provider-architecture.md)
+for the design.
+
+**Derived providers (config-extend).** Inherit a built-in with an env / command /
+model overlay — the canonical use is pointing Claude at an Anthropic-compatible
+gateway:
+
+```ts
+import { defineDerivedProvider, registerProvider, loadProvidersFromConfig } from "@agentex/agent";
+
+registerProvider(
+  defineDerivedProvider({
+    id: "zai",
+    extends: "claude",
+    env: { ANTHROPIC_BASE_URL: "https://api.z.ai/api/anthropic", ANTHROPIC_AUTH_TOKEN: "…" },
+    models: [{ id: "glm-5.1", name: "GLM 5.1" }],
+  }),
+);
+
+// …or load a whole map from config (also accepts Paseo's `agents.providers` nesting):
+loadProvidersFromConfig({
+  providers: {
+    zai: { extends: "claude", env: { ANTHROPIC_BASE_URL: "…" } },
+    "my-gemini": { extends: "acp", command: ["gemini", "--acp"] },
+  },
+});
+```
+
+**ACP agents.** Any agent speaking the [Agent Client Protocol](https://agentclientprotocol.com)
+is a few lines:
+
+```ts
+import { acpProvider, registerProvider } from "@agentex/agent";
+
+registerProvider(acpProvider({ id: "my-agent", command: ["my-agent", "--acp"] }));
+```
+
+`acpProvider` also accepts `transformers` (`modes` / `modeId`) to absorb a
+specific agent's quirks without forking the base.
+
+**Remote HTTP gateways.** For an "agent behind a URL", `httpAgentProvider` gives
+you gateway-URL resolution, session-key round-trip, `auth_required` mapping, and
+timeouts:
+
+```ts
+import { httpAgentProvider, registerProvider } from "@agentex/agent";
+
+registerProvider(
+  httpAgentProvider({ providerType: "my-gw", defaultBaseUrl: "http://localhost:3001", runPath: "/api/agent/run" }),
+);
+```
+
 ## Execution Context
 
 Only `prompt` is required. Everything else has sensible defaults.
@@ -189,7 +253,7 @@ Variants:
 - `thinking` — Agent's internal reasoning (`text`)
 - `tool_call` — Agent invoked a tool (`toolCallId: string | null`, `name`, `input`)
 - `unknown` — Fallback for unrecognized wire events (`subtype` = the provider's `type` field). Forward-compat access to new CLI events via `raw` without a library update.
-- `tool_result` — Tool returned a result (`toolCallId: string | null`, `content`, `isError`, `exitCode: number | null`)
+- `tool_result` — Tool returned a result (`toolCallId: string | null`, `toolName: string | null`, `content`, `isError`, `exitCode: number | null`). `toolName` mirrors the matching `tool_call.name` (correlated for you), so you don't need your own `toolCallId → name` cache; null when no preceding `tool_call` was seen on the stream.
 - `rate_limit` — Provider reported rate-limit state (`status`, `limitType`, `resetAt`, `overageStatus`, `isUsingOverage`)
 - `permission_mode` — Permission mode change mid-session (`permissionMode: string`). Claude only, e.g., when the user accepts a plan and the session leaves `plan` mode.
 - `result` — Final result (`text`, `costUsd`, `isError`, `stopReason`, `terminalReason`, `numTurns`, `durationMs`)
@@ -198,7 +262,7 @@ Lifecycle events (via `onLifecycle`) report phases: `preparing`, `spawning`, `ru
 
 ### What each provider surfaces on stream events
 
-Verified live against `claude 2.1.116` and `codex-cli 0.122.0` (2026-04-21). Other providers emit stubs — see precedence table at the end of this section.
+Verified live against `claude 2.1.116` and `codex-cli 0.122.0` (2026-04-21). ACP providers (`gemini`, `copilot`) and the session-backed `opencode`/`pi` emit real, correlated events (assistant / thinking / tool_call / tool_result); `cursor` and `openclaw` still stub most IDs — see the precedence note at the end of this section.
 
 | Field on `StreamEvent` | Claude source                                      | Codex source                                     |
 | ---------------------- | -------------------------------------------------- | ------------------------------------------------ |
@@ -207,7 +271,7 @@ Verified live against `claude 2.1.116` and `codex-cli 0.122.0` (2026-04-21). Oth
 | `eventId`              | Top-level per-line `uuid`                          | **null** — Codex doesn't emit a per-event ID     |
 | `turnId`               | **null** — Claude doesn't model turns              | v2 app-server: native UUIDv7 from `params.turnId`. NDJSON: **null** — no turn id in legacy format |
 | `parentToolCallId`     | `parent_tool_use_id` (set for sub-agent messages)  | **null** — not emitted                           |
-| Tool correlation       | `tool_use.id` (`toolu_*`) ↔ `tool_result.tool_use_id` | `item.id` reappears on the same item's `item.completed` |
+| Tool correlation       | `tool_use.id` (`toolu_*`) ↔ `tool_result.tool_use_id`; the library stamps `tool_result.toolName` from the matching call | `item.id` reappears on the same item's `item.completed`; `toolName` set directly from the item type |
 | `tool_result.exitCode` | **null** (Claude doesn't expose shell exit codes)  | `item.exit_code` for `command_execution`         |
 | Assistant message span | One `message.id` may span multiple event lines (thinking + tool_use emitted separately with distinct `uuid`s) | One `item.completed` per agent message |
 
@@ -237,7 +301,7 @@ When in doubt, `raw` is the verbatim provider event — parse it yourself for an
 
 ### Other providers
 
-`cursor`, `gemini`, `opencode`, `pi`, `openclaw` emit the same `StreamEvent` shape but currently stub most IDs to `null`. Their `raw` field is populated; enrichment to match the Claude/Codex level of fidelity is tracked separately and has not been audited against live CLI output.
+`gemini` and `copilot` (ACP) and the session-backed `opencode` and `pi` emit real, correlated `StreamEvent`s — assistant text, thinking, and tool_call/tool_result with proper tool-call ids (ACP and Codex have no per-event/message ids, so those stay `null`). `cursor` and `openclaw` still emit the same `StreamEvent` shape with most ids stubbed to `null`; their `raw` field is populated. `cursor` will gain full fidelity when it moves to the ACP tier.
 
 ## Sessions (multi-turn)
 
@@ -265,7 +329,26 @@ await followUp.result;
 await session.close();
 ```
 
-`session.send()` returns a `SendHandle` with a synchronously-available `uuid` and a `result: Promise<TurnResult>`. `TurnResult` carries `summary`, `usage`, `costUsd`, and a `status` of `completed | failed | max_turns | max_budget | aborted`. Handle elicitations (MCP forms), hook callbacks, and interrupts through the corresponding `SessionContext` callbacks.
+`session.send()` returns a `SendHandle` with a synchronously-available `uuid` and a `result: Promise<TurnResult>`. `TurnResult` carries `summary`, `usage`, `costUsd`, and a `status` of `completed | failed | max_turns | max_budget | aborted | timeout`. Handle elicitations (MCP forms), hook callbacks, and interrupts through the corresponding `SessionContext` callbacks.
+
+### Bounding a turn (timeout / abort)
+
+`send()` takes an optional `SendOptions` to cap a single turn — the natural shape for scheduled / fire-and-forget runs where a cron firing every minute can't be allowed to run a multi-hour turn:
+
+```typescript
+// Hard cap this turn. On fire, the library interrupts the agent and resolves
+// `result` with status "timeout" — no consumer-side Promise.race needed.
+const { result } = await session.send("Summarize the repo.", { timeoutSec: 90 });
+const turn = await result;
+if (turn.status === "timeout") { /* mark the run timed-out */ }
+
+// Or abort just this turn (not the whole session) via an AbortSignal.
+const ac = new AbortController();
+const handle = await session.send("Long task…", { signal: ac.signal });
+ac.abort();                       // → result resolves with status "aborted"
+```
+
+`SendOptions.timeoutSec` overrides `ProviderConfig.timeoutSec`, which acts as the session-level default when no per-call value is given. The per-send `signal` is distinct from `SessionContext.signal`: the per-send one ends just that turn, the session-level one closes the whole session. Because a session runs a single underlying agent, a timeout/abort interrupts the active turn — so any concurrent sends coalesced into the same turn end with it.
 
 ### Concurrent send ("type while the agent is working")
 
@@ -310,6 +393,18 @@ else console.log("Too late — the agent already drained it.");
 
 > **Race note.** Cancellation is best-effort. If the CLI drained the message mid-turn (Claude's `query.ts` between-tool-batches drain) before your `cancel()` request landed, you get `{ cancelled: false }` — and the message will be visible to the model as a `<system-reminder>`. The library does not unmount what the model has already seen.
 
+### Graceful shutdown with `drain()`
+
+`close()` kills the process (SIGTERM → SIGKILL after `graceSec`, default 5) — fine for "stop now," wrong when a tool is mid-flight. `drain()` is the graceful stop: it refuses new `send()` calls (they throw), waits for any in-flight turn's `result` to settle, then closes. Use it for budget gates, `SIGTERM` handlers, and schedule pauses where a running turn should finish rather than be cut off.
+
+```typescript
+process.on("SIGTERM", async () => {
+  await session.drain();   // let the current turn finish, then close
+});
+```
+
+`drain()` is idempotent. Bump `ProviderConfig.graceSec` for sessions running legitimately long tools (test suites, long Bash) so `close()`/`drain()` don't hard-kill them prematurely.
+
 ## Plan Mode
 
 Run an agent in read-only "plan" mode — it investigates and proposes a plan but cannot edit files or run mutating commands. Same goal in both providers, **different mechanism** in each. Check `provider.capabilities.planMode` before relying on it.

package/dist/derived.d.ts

@@ -0,0 +1,69 @@
+import type { ProviderModel, ProviderModule } from "./types.js";
+/**
+ * Declarative configuration for a *derived* provider — a new provider id that
+ * inherits a built-in provider's behavior with an environment / command / model
+ * overlay. The canonical use is BYOK gateways: point Claude at an
+ * Anthropic-compatible endpoint (z.ai, Qwen, a local proxy) by extending
+ * `"claude"` and setting `env.ANTHROPIC_BASE_URL`, with no new code.
+ */
+export interface DerivedProviderConfig {
+    /** Unique id for the new provider (used with `getProvider`/`registerProvider`). */
+    id: string;
+    /** A registered provider to inherit from (e.g. "claude", "codex"). For ACP
+     *  agents use the config-file loader's `extends: "acp"` form instead. */
+    extends: string;
+    /** Display label (informational). */
+    label?: string;
+    /** Description (informational). */
+    description?: string;
+    /** Override the binary/command the base provider spawns. Per-call
+     *  `config.command` still wins. */
+    command?: string;
+    /** Environment overlay applied to every execute / session / auth / modes /
+     *  quota call (e.g. `ANTHROPIC_BASE_URL`). Per-call `ctx.env` overrides it. */
+    env?: Record<string, string>;
+    /** Replace the model list surfaced by `listModels()`. */
+    models?: ProviderModel[];
+    /** Default `config.modeId` applied when the caller doesn't set one. */
+    modeId?: string;
+    /** When `false`, `loadProvidersFromConfig` skips this entry. */
+    enabled?: boolean;
+}
+/** Thrown when a provider config object is malformed. Branch on it; don't parse. */
+export declare class MalformedProviderConfigError extends Error {
+    readonly path?: string;
+    constructor(message: string, path?: string);
+}
+/** Signature of the ACP factory registered by the ACP provider module. */
+export type AcpFactory = (config: {
+    id: string;
+    command: string[];
+    env?: Record<string, string>;
+    label?: string;
+    models?: ProviderModel[];
+    modeId?: string;
+}) => ProviderModule;
+/**
+ * Registered by `@agentex/agent`'s ACP provider module on import, so the
+ * config-file loader can build `extends: "acp"` providers without a hard
+ * dependency on the ACP SDK at the top of the module graph.
+ */
+export declare function registerAcpFactory(factory: AcpFactory): void;
+/** @internal — for tests. */
+export declare function getAcpFactory(): AcpFactory | null;
+/**
+ * Build a derived `ProviderModule` from a base provider plus an overlay. The
+ * returned module is NOT auto-registered — pass it to `registerProvider`, or
+ * use `loadProvidersFromConfig` which registers for you.
+ */
+export declare function defineDerivedProvider(cfg: DerivedProviderConfig): ProviderModule;
+/**
+ * Build provider modules from a config object and (by default) register them.
+ * Supports `extends: "<builtin>"` (env/command/model overlay) and
+ * `extends: "acp"` (build an ACP provider from `command`). Throws
+ * `MalformedProviderConfigError` on a bad shape.
+ */
+export declare function loadProvidersFromConfig(raw: unknown, options?: {
+    register?: boolean;
+}): ProviderModule[];
+//# sourceMappingURL=derived.d.ts.map

package/dist/derived.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived.d.ts","sourceRoot":"","sources":["../src/derived.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,aAAa,EACb,cAAc,EACf,MAAM,YAAY,CAAC;AAGpB;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,mFAAmF;IACnF,EAAE,EAAE,MAAM,CAAC;IACX;6EACyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;uCACmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,yDAAyD;IACzD,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;IACzB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,oFAAoF;AACpF,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBACX,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAK3C;AAED,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,KAAK,cAAc,CAAC;AAIrB;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAE5D;AAED,6BAA6B;AAC7B,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,qBAAqB,GAAG,cAAc,CAiEhF;AA+FD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/B,cAAc,EAAE,CA4DlB"}

package/dist/derived.js

@@ -0,0 +1,218 @@
+import { getProvider, registerProvider } from "./registry.js";
+/** Thrown when a provider config object is malformed. Branch on it; don't parse. */
+export class MalformedProviderConfigError extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.name = "MalformedProviderConfigError";
+        this.path = path;
+    }
+}
+let acpFactory = null;
+/**
+ * Registered by `@agentex/agent`'s ACP provider module on import, so the
+ * config-file loader can build `extends: "acp"` providers without a hard
+ * dependency on the ACP SDK at the top of the module graph.
+ */
+export function registerAcpFactory(factory) {
+    acpFactory = factory;
+}
+/** @internal — for tests. */
+export function getAcpFactory() {
+    return acpFactory;
+}
+/**
+ * Build a derived `ProviderModule` from a base provider plus an overlay. The
+ * returned module is NOT auto-registered — pass it to `registerProvider`, or
+ * use `loadProvidersFromConfig` which registers for you.
+ */
+export function defineDerivedProvider(cfg) {
+    if (!cfg.id || typeof cfg.id !== "string") {
+        throw new MalformedProviderConfigError("derived provider requires a non-empty string id");
+    }
+    if (cfg.extends === "acp") {
+        throw new MalformedProviderConfigError(`provider "${cfg.id}": extends "acp" is built by loadProvidersFromConfig (or acpProvider() directly), not defineDerivedProvider`, cfg.id);
+    }
+    const base = getProvider(cfg.extends); // throws on unknown base
+    const overlayEnv = (env) => ({
+        ...cfg.env,
+        ...env,
+    });
+    const overlayConfig = (config) => ({
+        ...config,
+        ...(cfg.command && !config?.command ? { command: cfg.command } : {}),
+        ...(cfg.modeId && !config?.modeId ? { modeId: cfg.modeId } : {}),
+    });
+    const capabilities = {
+        ...base.capabilities,
+        ...(cfg.models ? { modelDiscovery: true } : {}),
+    };
+    const derived = {
+        ...base,
+        type: cfg.id,
+        capabilities,
+        execute: (ctx) => base.execute({ ...ctx, env: overlayEnv(ctx.env), config: overlayConfig(ctx.config) }),
+        resolveAuth: (authCtx) => base.resolveAuth({
+            ...authCtx,
+            env: overlayEnv(authCtx?.env),
+            command: authCtx?.command ?? cfg.command,
+        }),
+    };
+    if (base.createSession) {
+        const baseCreate = base.createSession.bind(base);
+        derived.createSession = (ctx) => baseCreate({ ...ctx, env: overlayEnv(ctx.env), config: overlayConfig(ctx.config) });
+    }
+    if (cfg.models) {
+        const models = cfg.models;
+        derived.listModels = async () => models;
+    }
+    else if (base.listModels) {
+        const baseList = base.listModels.bind(base);
+        derived.listModels = (opts) => baseList(opts);
+    }
+    if (base.listModes) {
+        const baseModes = base.listModes.bind(base);
+        derived.listModes = (opts) => baseModes({ ...opts, env: overlayEnv(opts?.env), config: overlayConfig(opts?.config) });
+    }
+    if (base.checkQuota) {
+        const baseQuota = base.checkQuota.bind(base);
+        derived.checkQuota = (qctx) => baseQuota({ ...qctx, env: overlayEnv(qctx?.env), config: overlayConfig(qctx?.config) });
+    }
+    return derived;
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function toCommandArray(command, path) {
+    if (typeof command === "string") {
+        const parts = command.trim().split(/\s+/).filter(Boolean);
+        if (parts.length === 0)
+            throw new MalformedProviderConfigError(`${path}.command is empty`, path);
+        return parts;
+    }
+    if (Array.isArray(command) && command.every((c) => typeof c === "string") && command.length > 0) {
+        return command;
+    }
+    throw new MalformedProviderConfigError(`${path}.command must be a non-empty string or string[] for an ACP provider`, path);
+}
+function toCommandString(command, path) {
+    if (command === undefined)
+        return undefined;
+    if (typeof command === "string")
+        return command;
+    if (Array.isArray(command)) {
+        // agentex's `config.command` is a single binary (args go through the agent's
+        // own config), so a multi-element array would silently drop everything past
+        // the binary — reject it rather than mislead. (ACP providers use the array
+        // form via the `extends: "acp"` branch instead.)
+        if (command.length === 1 && typeof command[0] === "string")
+            return command[0];
+        throw new MalformedProviderConfigError(`${path}.command for a non-ACP provider must be a single binary string; got an array of ${command.length} (use extends: "acp" for binary+args)`, path);
+    }
+    return undefined;
+}
+function validateEnv(env, path) {
+    if (env === undefined)
+        return undefined;
+    if (!isRecord(env))
+        throw new MalformedProviderConfigError(`${path}.env must be an object`, path);
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (typeof v !== "string") {
+            throw new MalformedProviderConfigError(`${path}.env.${k} must be a string`, path);
+        }
+        out[k] = v;
+    }
+    return out;
+}
+function validateModels(models, path) {
+    if (models === undefined)
+        return undefined;
+    if (!Array.isArray(models))
+        throw new MalformedProviderConfigError(`${path}.models must be an array`, path);
+    return models.map((m, i) => {
+        if (!isRecord(m) || typeof m["id"] !== "string") {
+            throw new MalformedProviderConfigError(`${path}.models[${i}] must have a string id`, path);
+        }
+        return {
+            id: m["id"],
+            name: typeof m["name"] === "string" ? m["name"] : m["id"],
+            ...(typeof m["provider"] === "string" ? { provider: m["provider"] } : {}),
+        };
+    });
+}
+/** Locate the providers map, accepting `{ providers }` or Paseo's
+ *  `{ agents: { providers } }` nesting. */
+function findProvidersMap(raw) {
+    if (!isRecord(raw))
+        throw new MalformedProviderConfigError("config must be an object");
+    if (isRecord(raw["providers"]))
+        return raw["providers"];
+    if (isRecord(raw["agents"]) && isRecord(raw["agents"]["providers"])) {
+        return raw["agents"]["providers"];
+    }
+    throw new MalformedProviderConfigError("config must contain a `providers` (or `agents.providers`) object");
+}
+/**
+ * Build provider modules from a config object and (by default) register them.
+ * Supports `extends: "<builtin>"` (env/command/model overlay) and
+ * `extends: "acp"` (build an ACP provider from `command`). Throws
+ * `MalformedProviderConfigError` on a bad shape.
+ */
+export function loadProvidersFromConfig(raw, options) {
+    const register = options?.register ?? true;
+    const providersMap = findProvidersMap(raw);
+    const built = [];
+    for (const [id, value] of Object.entries(providersMap)) {
+        const path = `providers.${id}`;
+        if (!isRecord(value))
+            throw new MalformedProviderConfigError(`${path} must be an object`, path);
+        const entry = value;
+        if (entry.enabled === false)
+            continue;
+        if (typeof entry.extends !== "string" || entry.extends.length === 0) {
+            throw new MalformedProviderConfigError(`${path}.extends must be a non-empty string`, path);
+        }
+        const label = typeof entry.label === "string" ? entry.label : undefined;
+        const description = typeof entry.description === "string" ? entry.description : undefined;
+        const env = validateEnv(entry.env, path);
+        const models = validateModels(entry.models, path);
+        const modeId = typeof entry.modeId === "string" ? entry.modeId : undefined;
+        let provider;
+        if (entry.extends === "acp") {
+            if (!acpFactory) {
+                throw new MalformedProviderConfigError(`${path}: ACP providers require the ACP module — import it (e.g. \`@agentex/agent\`'s acp provider) before loading ACP configs`, path);
+            }
+            provider = acpFactory({
+                id,
+                command: toCommandArray(entry.command, path),
+                ...(env ? { env } : {}),
+                ...(label ? { label } : {}),
+                ...(models ? { models } : {}),
+                ...(modeId ? { modeId } : {}),
+            });
+        }
+        else {
+            const command = toCommandString(entry.command, path);
+            provider = defineDerivedProvider({
+                id,
+                extends: entry.extends,
+                ...(label ? { label } : {}),
+                ...(description ? { description } : {}),
+                ...(command ? { command } : {}),
+                ...(env ? { env } : {}),
+                ...(models ? { models } : {}),
+                ...(modeId ? { modeId } : {}),
+            });
+        }
+        built.push(provider);
+    }
+    if (register) {
+        // Register only after every entry validates, so a bad entry doesn't leave a
+        // half-applied config registered.
+        for (const provider of built)
+            registerProvider(provider);
+    }
+    return built;
+}
+//# sourceMappingURL=derived.js.map

package/dist/derived.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived.js","sourceRoot":"","sources":["../src/derived.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAiC9D,oFAAoF;AACpF,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAC5C,IAAI,CAAU;IACvB,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAYD,IAAI,UAAU,GAAsB,IAAI,CAAC;AAEzC;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAmB;IACpD,UAAU,GAAG,OAAO,CAAC;AACvB,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAA0B;IAC9D,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC1C,MAAM,IAAI,4BAA4B,CAAC,iDAAiD,CAAC,CAAC;IAC5F,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QAC1B,MAAM,IAAI,4BAA4B,CACpC,aAAa,GAAG,CAAC,EAAE,6GAA6G,EAChI,GAAG,CAAC,EAAE,CACP,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,yBAAyB;IAEhE,MAAM,UAAU,GAAG,CAAC,GAA4B,EAA0B,EAAE,CAAC,CAAC;QAC5E,GAAG,GAAG,CAAC,GAAG;QACV,GAAG,GAAG;KACP,CAAC,CAAC;IACH,MAAM,aAAa,GAAG,CAAC,MAAuB,EAAkB,EAAE,CAAC,CAAC;QAClE,GAAG,MAAM;QACT,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC,CAAC;IAEH,MAAM,YAAY,GAAyB;QACzC,GAAG,IAAI,CAAC,YAAY;QACpB,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC;IAEF,MAAM,OAAO,GAAmB;QAC9B,GAAG,IAAI;QACP,IAAI,EAAE,GAAG,CAAC,EAAE;QACZ,YAAY;QACZ,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CACf,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACvF,WAAW,EAAE,CAAC,OAAO,EAAE,EAAE,CACvB,IAAI,CAAC,WAAW,CAAC;YACf,GAAG,OAAO;YACV,GAAG,EAAE,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC;YAC7B,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,GAAG,CAAC,OAAO;SACzC,CAAC;KACL,CAAC;IAEF,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,OAAO,CAAC,aAAa,GAAG,CAAC,GAAG,EAAE,EAAE,CAC9B,UAAU,CAAC,EAAE,GAAG,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QAC1B,OAAO,CAAC,UAAU,GAAG,KAAK,IAAI,EAAE,CAAC,MAAM,CAAC;IAC1C,CAAC;SAAM,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,OAAO,CAAC,UAAU,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,OAAO,CAAC,SAAS,GAAG,CAAC,IAAI,EAAE,EAAE,CAC3B,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,OAAO,CAAC,UAAU,GAAG,CAAC,IAAI,EAAE,EAAE,CAC5B,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAkBD,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,cAAc,CAAC,OAAgB,EAAE,IAAY;IACpD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,4BAA4B,CAAC,GAAG,IAAI,mBAAmB,EAAE,IAAI,CAAC,CAAC;QACjG,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChG,OAAO,OAAmB,CAAC;IAC7B,CAAC;IACD,MAAM,IAAI,4BAA4B,CACpC,GAAG,IAAI,qEAAqE,EAC5E,IAAI,CACL,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,OAAgB,EAAE,IAAY;IACrD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,6EAA6E;QAC7E,4EAA4E;QAC5E,2EAA2E;QAC3E,iDAAiD;QACjD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,QAAQ;YAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;QAC9E,MAAM,IAAI,4BAA4B,CACpC,GAAG,IAAI,mFAAmF,OAAO,CAAC,MAAM,uCAAuC,EAC/I,IAAI,CACL,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,WAAW,CAAC,GAAY,EAAE,IAAY;IAC7C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,4BAA4B,CAAC,GAAG,IAAI,wBAAwB,EAAE,IAAI,CAAC,CAAC;IAClG,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,4BAA4B,CAAC,GAAG,IAAI,QAAQ,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC;QACpF,CAAC;QACD,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,cAAc,CAAC,MAAe,EAAE,IAAY;IACnD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,4BAA4B,CAAC,GAAG,IAAI,0BAA0B,EAAE,IAAI,CAAC,CAAC;IAC5G,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACzB,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,IAAI,4BAA4B,CAAC,GAAG,IAAI,WAAW,CAAC,yBAAyB,EAAE,IAAI,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO;YACL,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACzD,GAAG,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;2CAC2C;AAC3C,SAAS,gBAAgB,CAAC,GAAY;IACpC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,4BAA4B,CAAC,0BAA0B,CAAC,CAAC;IACvF,IAAI,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC,WAAW,CAAC,CAAC;IACxD,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,QAAQ,CAAE,GAAG,CAAC,QAAQ,CAA6B,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;QACjG,OAAQ,GAAG,CAAC,QAAQ,CAA6B,CAAC,WAAW,CAA4B,CAAC;IAC5F,CAAC;IACD,MAAM,IAAI,4BAA4B,CACpC,kEAAkE,CACnE,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,GAAY,EACZ,OAAgC;IAEhC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,IAAI,CAAC;IAC3C,MAAM,YAAY,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAqB,EAAE,CAAC;IAEnC,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,aAAa,EAAE,EAAE,CAAC;QAC/B,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,4BAA4B,CAAC,GAAG,IAAI,oBAAoB,EAAE,IAAI,CAAC,CAAC;QAChG,MAAM,KAAK,GAAG,KAAyB,CAAC;QAExC,IAAI,KAAK,CAAC,OAAO,KAAK,KAAK;YAAE,SAAS;QACtC,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpE,MAAM,IAAI,4BAA4B,CAAC,GAAG,IAAI,qCAAqC,EAAE,IAAI,CAAC,CAAC;QAC7F,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACxE,MAAM,WAAW,GAAG,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1F,MAAM,GAAG,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QAE3E,IAAI,QAAwB,CAAC;QAC7B,IAAI,KAAK,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;YAC5B,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,MAAM,IAAI,4BAA4B,CACpC,GAAG,IAAI,wHAAwH,EAC/H,IAAI,CACL,CAAC;YACJ,CAAC;YACD,QAAQ,GAAG,UAAU,CAAC;gBACpB,EAAE;gBACF,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC;gBAC5C,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9B,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACrD,QAAQ,GAAG,qBAAqB,CAAC;gBAC/B,EAAE;gBACF,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3B,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/B,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvB,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9B,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvB,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,4EAA4E;QAC5E,kCAAkC;QAClC,KAAK,MAAM,QAAQ,IAAI,KAAK;YAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,11 @@
 export { getProvider, listProviders, registerProvider } from "./registry.js";
+export { defineDerivedProvider, loadProvidersFromConfig, registerAcpFactory, MalformedProviderConfigError, } from "./derived.js";
+export type { DerivedProviderConfig, AcpFactory } from "./derived.js";
+export { acpProvider } from "./providers/acp/index.js";
+export type { AcpProviderConfig } from "./providers/acp/index.js";
+export type { AcpTransformers } from "./providers/acp/session.js";
+export { runHttpAgent, httpAgentProvider, httpAgentSessionCodec, } from "./providers/_shared/http-agent.js";
+export type { HttpAgentOptions } from "./providers/_shared/http-agent.js";
 export { renderTemplate } from "./utils/template.js";
 export { redactEnvForLogs } from "./utils/env.js";
 export { parseAskUserQuestion } from "./utils/ask-user-question.js";
@@ -23,7 +30,7 @@ export { getCodexTranscriptPath, readCodexTranscript, peekCodexTranscript, readC
 export type { GetCodexTranscriptPathOptions, CodexTranscriptLocation, ReadCodexTranscriptOptions, CodexTranscriptYield, CodexTranscriptLine, CodexPeekResult, } from "./providers/codex/transcript.js";
 export { installSkills, removeSkills, listInstalledSkills, resolveSkillsHome, resolveSkillsWorkspace, resolveNativeSkillsHome, resolveNativeSkillsWorkspace, ensureSkillSymlink, } from "./utils/skills.js";
 export { commandInventoryFromEvent, discoverSkillCommands, reconcileSkillCommands, formatSlashInvocation, invokeSkill, buildExpandedSkillPrompt, } from "./utils/skill-commands.js";
-export type { ProviderModule, ProviderCapabilities, ExecutionContext, ExecutionResult, ExecutionStatus, ProviderConfig, McpServerConfig, StreamEvent, SessionCodec, SessionState, TokenUsage, ModelUsage, RateLimitInfo, BaseStreamEventFields, LifecycleEvent, QuotaStatus, QuotaContext, AuthMethod, AuthSource, AuthOption, AuthReport, AuthResolveContext, AuthIdentity, AuthRequiredReason, BinaryStatus, ProviderModel, SessionContext, AgentSession, TurnResult, UserInputRequest, UserInputResponse, ElicitationRequest, ElicitationResponse, HookCallbackRequest, HookCallbackResponse, TranscriptOps, TranscriptYield, TranscriptPeek, FoundTranscript, } from "./types.js";
+export type { ProviderModule, ProviderCapabilities, AgentMode, ListModesOptions, ExecutionContext, ExecutionResult, ExecutionStatus, ProviderConfig, McpServerConfig, StreamEvent, SessionCodec, SessionState, TokenUsage, ModelUsage, RateLimitInfo, BaseStreamEventFields, LifecycleEvent, QuotaStatus, QuotaContext, AuthMethod, AuthSource, AuthOption, AuthReport, AuthResolveContext, AuthIdentity, AuthRequiredReason, BinaryStatus, ProviderModel, SessionContext, AgentSession, SendHandle, SendOptions, CancelResult, TurnResult, UserInputRequest, UserInputResponse, ElicitationRequest, ElicitationResponse, HookCallbackRequest, HookCallbackResponse, TranscriptOps, TranscriptYield, TranscriptPeek, FoundTranscript, } from "./types.js";
 export type { AskUserQuestion, QuestionOption, } from "./utils/ask-user-question.js";
 export type { ExitPlanModeRequest } from "./utils/exit-plan-mode.js";
 export type { SkillRuntime, SkillLocation, SkillChannel, InstallSkillsOptions, SkillInstallEntry, SkillInstallResult, RemoveSkillsOptions, SkillRemoveEntry, SkillRemoveResult, InstalledSkill, } from "./utils/skills.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1F,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,uBAAuB,EACvB,+BAA+B,EAC/B,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EACV,8BAA8B,EAC9B,wBAAwB,EACxB,2BAA2B,EAC3B,qBAAqB,EACrB,2BAA2B,EAC3B,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,gBAAgB,GACjB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,6BAA6B,EAC7B,uBAAuB,EACvB,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,GAChB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EACL,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,EACX,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,EACd,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,WAAW,EACX,YAAY,EACZ,UAAU,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,eAAe,EACf,cAAc,GACf,MAAM,8BAA8B,CAAC;AAEtC,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,YAAY,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,4BAA4B,EAC5B,2BAA2B,EAC3B,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,5 +1,8 @@
 // Functions
 export { getProvider, listProviders, registerProvider } from "./registry.js";
+export { defineDerivedProvider, loadProvidersFromConfig, registerAcpFactory, MalformedProviderConfigError, } from "./derived.js";
+export { acpProvider } from "./providers/acp/index.js";
+export { runHttpAgent, httpAgentProvider, httpAgentSessionCodec, } from "./providers/_shared/http-agent.js";
 export { renderTemplate } from "./utils/template.js";
 export { redactEnvForLogs } from "./utils/env.js";
 export { parseAskUserQuestion } from "./utils/ask-user-question.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1F,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,uBAAuB,EACvB,+BAA+B,EAC/B,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAU1C,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,gBAAgB,GACjB,MAAM,iCAAiC,CAAC;AAUzC,SAAS;AACT,OAAO,EACL,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,EACX,wBAAwB,GACzB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1F,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,uBAAuB,EACvB,+BAA+B,EAC/B,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAU1C,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,gBAAgB,GACjB,MAAM,iCAAiC,CAAC;AAUzC,SAAS;AACT,OAAO,EACL,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,EACX,wBAAwB,GACzB,MAAM,2BAA2B,CAAC"}

package/dist/providers/_shared/http-agent.d.ts

@@ -0,0 +1,39 @@
+import type { ExecutionContext, ExecutionResult, ProviderModule, SessionCodec } from "../../types.js";
+/**
+ * Reusable "remote HTTP agent" adapter — the pattern OpenClaw encodes and the
+ * shape any gateway-backed agent reuses: resolve a gateway URL (per-call command
+ * override → saved sessionParams → default), round-trip a session key through
+ * `sessionParams`, POST the prompt, map 401/403 to an `auth_required` event, and
+ * bound the request with an AbortController timeout.
+ */
+export interface HttpAgentOptions {
+    /** Provider id (used on events + the result). */
+    providerType: string;
+    /** Gateway base URL used when neither `config.command` nor a saved URL is set. */
+    defaultBaseUrl: string;
+    /** Path appended to the base URL for the run endpoint (e.g. "/api/agent/run"). */
+    runPath: string;
+    /** Recovery command surfaced on `auth_required` (e.g. "openclaw login"). */
+    loginCommand?: string;
+    /** Build the JSON request body. Default: `{ prompt, sessionKey?, model? }`. */
+    buildBody?: (input: {
+        prompt: string;
+        sessionKey: string | null;
+        model: string | null;
+    }) => Record<string, unknown>;
+    /** Pull the summary text from the gateway response. Default: summary ?? result ?? output. */
+    extractSummary?: (response: Record<string, unknown>) => string | null;
+    /** Pull the (possibly new) session key from the response. Default: `response.sessionKey ?? prev`. */
+    extractSessionKey?: (response: Record<string, unknown>, prev: string | null) => string | null;
+    /** Pull the model id from the response. Default: `response.model ?? fallback`. */
+    extractModel?: (response: Record<string, unknown>, fallback: string | null) => string | null;
+    /** Pull the cost from the response. Default: `response.costUsd` when numeric. */
+    extractCost?: (response: Record<string, unknown>) => number | null;
+}
+/** Execute a single turn against a remote HTTP agent gateway. */
+export declare function runHttpAgent(opts: HttpAgentOptions, ctx: ExecutionContext): Promise<ExecutionResult>;
+/** Session codec for HTTP-agent providers — round-trips `{ sessionKey, gatewayUrl }`. */
+export declare const httpAgentSessionCodec: SessionCodec;
+/** Build a `ProviderModule` for a remote HTTP agent gateway. */
+export declare function httpAgentProvider(opts: HttpAgentOptions): ProviderModule;
+//# sourceMappingURL=http-agent.d.ts.map

package/dist/providers/_shared/http-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-agent.d.ts","sourceRoot":"","sources":["../../../src/providers/_shared/http-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,YAAY,EACb,MAAM,gBAAgB,CAAC;AAGxB;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,cAAc,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpH,6FAA6F;IAC7F,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,IAAI,CAAC;IACtE,qGAAqG;IACrG,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,GAAG,IAAI,CAAC;IAC9F,kFAAkF;IAClF,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,GAAG,IAAI,CAAC;IAC7F,iFAAiF;IACjF,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,IAAI,CAAC;CACpE;AAgBD,iEAAiE;AACjE,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,CAAC,CAgM1B;AAED,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,EAAE,YAoBnC,CAAC;AAEF,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,cAAc,CA6BxE"}