@get-bb/plugin-sdk 0.4.24 → 0.4.28

package/bundled-types/bb-plugin-sdk-internal-host-policy.d.ts

@@ -7,15 +7,6 @@
 
 import { z } from 'zod';
 
-/**
- * Core `bb` CLI top-level command names (plus commander's built-in help).
- * Core commands win these names; plugin scaffolding rejects them. Maintained
- * by hand and checked against the real Commander program by
- * apps/cli/src/__tests__/plugin-cli-proxy.test.ts.
- *
- * "automation" and "connect" are intentionally absent: builtin plugins own
- * those top-level commands and the CLI proxies them.
- */
 declare const RESERVED_BB_CLI_COMMANDS: readonly string[];
 
 /** Input-form entry: a path, or a path with options. */
@@ -70,22 +61,6 @@ interface ProviderNativeRootsInputLike {
     readonly project?: readonly ProviderNativeRootInput[];
 }
 
-/**
- * How completely a provider can clone one of its sessions — the single
- * vocabulary shared by the provider declaration
- * (`bb.providers.register`), the server→daemon
- * `bridgeLaunch`, and the bridge's `initialize` handshake.
- *
- * - `"none"`: sessions cannot be cloned at all.
- * - `"tip"`: only the current end of a session can be cloned (ACP
- *   `session/fork`), so thread fork works but edit-past-message rewind
- *   cannot.
- * - `"checkpoint"`: a session can be recreated at an earlier point, which is
- *   what edit-past-message rewind needs.
- *
- * The values are ordered least to most capable: a declaration is a ceiling
- * the handshake may narrow but never widen.
- */
 declare const PROVIDER_FORK_VALUES: readonly ["none", "tip", "checkpoint"];
 type ProviderFork = (typeof PROVIDER_FORK_VALUES)[number];
 

package/bundled-types/bb-plugin-sdk-provider-bridge-acp.d.ts

@@ -62,20 +62,6 @@ declare const availableModelSchema: z.ZodObject<{
 }, z.core.$strip>;
 type AvailableModel = z.infer<typeof availableModelSchema>;
 
-/**
- * Declarative presentation a bridge attaches to an item at `item.open` (and
- * re-states on `item.close`, whose item is the full terminal shape). The
- * assembler persists it on the canonical item so the row renders after the
- * plugin is uninstalled or upgraded, and so mobile renders every kind without
- * plugin code. The same schema as the persisted field
- * (`threadEventItemPresentationSchema` in @bb/domain) — one vocabulary, no
- * translation.
- *
- * Optional in grammar v3 while rows persisted before bridges stamped it are
- * upgraded at read time; it becomes required together with the
- * `legacy-tool-item-backfill` migration that stamps those rows and retires
- * that adapter.
- */
 declare const deltaPresentationSchema: z.ZodObject<{
     detail: z.ZodOptional<z.ZodString>;
     icon: z.ZodObject<{
@@ -250,30 +236,19 @@ declare const deltaItemShapeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "type">;
 type DeltaItemShape = z.infer<typeof deltaItemShapeSchema>;
 
-/** Where this bridge process may keep files, scoped to the owning plugin. */
 interface ProviderBridgeContext {
-    /** The plugin that ships this bridge. */
     pluginId: string;
-    /** Persistent, per-plugin, survives daemon restarts and plugin updates. */
     dataDir: string;
-    /** This process only; removed when it exits. */
     tempDir: string;
 }
 interface ProviderBridgeDefinition {
-    /** One decoded stdin line of the Provider Bridge Protocol. */
     handleLine: (line: string) => void;
-    /**
-     * Called once before the first line is read, with the process's
-     * plugin-scoped directories. Omit it when the bridge keeps no files.
-     */
     start?: (context: ProviderBridgeContext) => void;
-    /** Stdin closed: the runtime is gone and the bridge must shut down. */
     onClose?: () => void;
     onSigterm?: () => void;
     onSigint?: () => void;
 }
 interface ProviderBridgeEntry extends ProviderBridgeDefinition {
-    /** Bumped when the bootstrap↔bridge contract changes incompatibly. */
     experimental_apiVersion: 1;
 }
 
@@ -311,37 +286,19 @@ type ProviderUsageResult = z.infer<typeof providerUsageResultSchema>;
 
 declare const experimental_providerBridge: ProviderBridgeEntry;
 
-/**
- * What an agent's own dialect knows about keeping it healthy: how a user
- * signs in, whether bb can install it, and where its account and usage live.
- * ACP standardizes none of it, so a generic bridge can only report whether
- * the executable exists — everything richer belongs to the agent, and is
- * therefore the dialect's (see `dialect.ts`), never a bb provider id's.
- */
 interface AcpMaintenanceDialect {
-    /** The shell command that signs the user in. */
     loginCommand: string;
-    /** How bb installs or updates the agent, when it can. */
     installer(): {
         command: string;
         args: string[];
         displayCommand: string;
     };
-    /** The signed-in account, or null when the agent is not signed in. */
     readAccount(): Promise<{
         email: string | null;
     } | null>;
-    /** The agent's usage windows, for the usage surfaces. */
     readUsage(): Promise<ProviderUsageResult>;
 }
 
-/**
- * Zod schemas for the subset of the Agent Client Protocol (ACP) that BB
- * consumes — https://agentclientprotocol.com. The bridge validates agent
- * traffic with these before forwarding, and the adapter re-validates the
- * `update` payloads it translates into thread events.
- */
-
 declare const acpToolKindSchema: z.ZodEnum<{
     delete: "delete";
     edit: "edit";
@@ -440,170 +397,53 @@ declare const acpToolCallUpdateEventSchema: z.ZodPipe<z.ZodTransform<unknown, un
 }, z.core.$loose>>;
 type AcpToolCallUpdateEvent = z.infer<typeof acpToolCallUpdateEventSchema>;
 
-/**
- * ACP tool call → grammar v3 item shape + presentation.
- *
- * An ACP agent describes a tool call with a native kind enum and a human
- * title. The kind maps straight onto the core kinds: `execute` → `command`,
- * `edit`/`delete` → `fileChange`, `read` → `fileRead`, `search` → `search`,
- * `fetch` → `webFetch`, `think` → `reasoning`; everything else — `other`,
- * `move`, an agent that sent no kind — is a generic `tool` whose `tool` slot
- * names the kind. The title is never a tool name: it rides
- * `presentation.title`.
- *
- * A core shape has required fields the agent does not always fill (Cursor's
- * `read` and `fetch` calls carry an empty `rawInput` and no `locations`). A
- * kind whose shape cannot be built honestly stays a generic `tool` that
- * presents as its kind ("Reading file" with the agent's title), so a row is
- * never a `fileRead` without a path or a `webFetch` without a URL.
- *
- * The command / file-change decision is `tool-call-operation.ts`'s, which the
- * permission mapping shares, so an approval row and its timeline item never
- * disagree (#1803).
- */
-
-/** A tool call's item shape plus the presentation that rides its lifecycle. */
 interface AcpClassifiedToolCall {
     item: DeltaItemShape;
     presentation: DeltaPresentation;
 }
 interface AcpCommandResult {
-    /** The process exit code the agent reported; absent when it reported none. */
     exitCode?: number;
-    /** The command's output text; absent when the agent reported none. */
     output?: string;
 }
 
-/**
- * Per-agent dialects: the vendor side channels of an ACP agent.
- *
- * The ACP wire schema (`wire.ts`) parses only the protocol. What an agent
- * puts beside the protocol is a dialect: grok stamps `_meta["x.ai/tool"]` on
- * every tool event, Cursor reports its sub-agents through a vendor JSON-RPC
- * request (`cursor/task`) that the protocol has no place for. A dialect is a
- * small, per-agent module that reads those channels and answers the few
- * questions the shared translator asks. The shared schema never learns a
- * vendor key, and a dialect never changes what a protocol field means.
- *
- * Version 1 of the protocol has no sub-agent concept at all (`session/fork`
- * is unstable and unrelated), so every delegation an ACP agent reports is
- * vendor-specific and belongs here rather than in the classifier.
- *
- * The dialect is selected per session from the agent's launch command. An
- * agent with no dialect of its own gets the generic one, which answers
- * nothing and leaves every decision to the protocol fields.
- */
-
-/**
- * The programmatic identity of a tool call, when the agent reports one
- * outside the protocol's unstable `name` field: the tool's own name and, for
- * an agent that sends the `kind` late (grok puts it on the first update, a
- * few milliseconds after the `tool_call`), the kind at open, so the opened
- * shape and the closed shape agree.
- */
 interface AcpToolIdentity {
     name?: string;
     kind?: AcpToolKind;
 }
-/** What a dialect learned about a sub-agent the agent launched. */
 interface AcpDelegationReport {
-    /** The tool call the delegation belongs to. */
     toolCallId: string;
-    /** The child's provider-native id. */
     childRef: string;
-    /** The row headline: what the sub-agent was asked to do. */
     label: string;
-    /** A sub-agent type or model the row can name, when the agent says. */
     detail?: string;
 }
 interface AcpDialect {
-    /** Stable id, for logs and tests. */
     readonly id: string;
-    /**
-     * The tool identity a tool_call / tool_call_update carries in the agent's
-     * side channel, if any. The translator fills an absent protocol `name` and
-     * `kind` from it; a protocol value always wins over the dialect's.
-     */
     toolIdentity?(event: AcpToolCallUpdateEvent): AcpToolIdentity | undefined;
-    /**
-     * The agent's own classification of a tool call, when its side channel
-     * says something the protocol fields cannot. Returning `undefined` leaves
-     * the shared classifier in charge — which is the normal answer.
-     */
     classifyToolCall?(event: AcpToolCallUpdateEvent): AcpClassifiedToolCall | undefined;
-    /**
-     * A command result carried in the agent's non-standard rawOutput shape.
-     * Returning `undefined` leaves the shared ACP result parser in charge.
-     */
     commandResult?(event: AcpToolCallUpdateEvent): AcpCommandResult | undefined;
-    /**
-     * A command event with the agent's non-standard result fields normalized
-     * into the shared ACP result shapes. The hook runs only after the call has
-     * classified as a command; existing shared result fields must win.
-     */
     normalizeCommandEvent?(event: AcpToolCallUpdateEvent): AcpToolCallUpdateEvent;
-    /**
-     * A vendor JSON-RPC request the agent sends to the client. A dialect that
-     * answers one returns the JSON-RPC result to reply with (`{}` is a valid
-     * acknowledgement) and, optionally, what the request reported. A request
-     * no dialect claims stays an unsupported method.
-     */
     handleClientRequest?(method: string, params: unknown): AcpClientRequestOutcome | undefined;
-    /**
-     * How bb keeps this agent healthy: sign-in, installation, account and
-     * usage. ACP standardizes none of it, so an agent without one reports only
-     * whether its executable exists.
-     */
     maintenance?: AcpMaintenanceDialect;
 }
 interface AcpClientRequestOutcome {
-    /** The JSON-RPC result the bridge replies with. */
     result: Record<string, unknown>;
-    /** A sub-agent the request reported, if it reported one. */
     delegation?: AcpDelegationReport;
 }
 
-/**
- * What one installed ACP agent can actually do (Q21).
- *
- * A provider declaration states its capabilities before any agent has spoken,
- * so bb declared one answer for every ACP agent and got them wrong: the ACP
- * tier offered `session/fork` for five agents, of which the two bb has since
- * read the wire for support none of it. A declaration above what the agent
- * answers is not a missing feature — the bridge refuses the fork only after
- * bb created the fork thread, so the thread dies on start (get-bb/bb#1833).
- *
- * The agent already reports the truth: `initialize` returns
- * `agentCapabilities`. This probe asks it. It runs on the host, because the
- * agent is a host-local executable, and it is deliberately cheap and
- * disposable: spawn, initialize, read the reply, kill. It never starts a
- * session and never prompts.
- */
-
 interface AcpAgentProbeRequest {
     command: string;
     args: readonly string[];
-    /** Extra environment the agent's launch spec asks for. */
     env?: Record<string, string>;
-    /** Where to run the probe; the agent may refuse to start without one. */
     cwd: string;
     timeoutMs?: number;
 }
-/** What the agent said about itself, or why bb could not ask. */
 type AcpAgentProbe = {
     reachable: true;
-    /** The agent implements the unstable `session/fork`. */
     fork: boolean;
 } | {
     reachable: false;
     reason: string;
 };
-/**
- * Ask one agent what it supports. Never throws: an agent that is missing,
- * broken, or too slow is a `reachable: false` answer with the reason, which
- * the caller reports as "bb could not verify this agent" rather than as a
- * capability.
- */
 declare function probeAcpAgent(request: AcpAgentProbeRequest): Promise<AcpAgentProbe>;
 declare const acpAgentProbeSchema: z.ZodType<AcpAgentProbe>;
 
@@ -717,48 +557,8 @@ declare const acpLaunchSpecSchema: z.ZodObject<{
 }, z.core.$strict>;
 type AcpLaunchSpec = z.infer<typeof acpLaunchSpecSchema>;
 
-/**
- * Agent CLI model catalog.
- *
- * Cursor's `cursor-agent --list-models` prints one
- * `id - Display Name` line per model,
- * OpenCode's `opencode models` prints one bare id per line, and Grok's
- * `grok models` prints a bulleted list. These ids can encode reasoning effort:
- * `gpt-5.3-codex-low`, bare `gpt-5.3-codex` for medium, `gpt-5.5-extra-high`
- * as an alternate xhigh spelling, with an optional `-fast` service tail after
- * the effort token (`gpt-5.3-codex-low-fast`). This module groups those raw
- * variants into bb model families so the picker offers one clean entry per
- * family with selectable reasoning efforts, and resolves a (family, effort,
- * serviceTier) selection back to the exact raw id at session launch — by table
- * lookup, never string synthesis, because effort spellings vary per family.
- *
- * The `-fast` tail is a service tier, not a separate model: both the normal
- * and fast raw ids for a given effort collapse into one family, and the bb
- * "Fast mode" toggle (serviceTier) selects between them at launch.
- *
- * Cursor's "thinking" marker (appearing as an infix `…-thinking-medium` or a
- * suffix `…-medium-thinking` / `…-thinking`) is folded into the reasoning
- * ladder too: thinking variants keep their effort, and the model's
- * non-thinking variants collapse onto a single "none" (thinking-off) level at
- * the bottom of the ladder. So one "Opus 4.8" entry offers None, Low … Max
- * instead of separate "Opus 4.8" and "Opus 4.8 Thinking" rows. An explicit
- * `-none` effort id (e.g. `gpt-5.5-none`) is the same "none" level.
- *
- * Display names are stripped of noise the picker renders elsewhere or doesn't
- * need — the per-model effort word and "Thinking" marker (reasoning has its
- * own control), the redundant `1M` context tag, the `(NO ZDR)` data-retention
- * marker, and Cursor's own `(default)`/`(current)` annotations.
- */
-
 interface AgentModelCatalog {
     models: AvailableModel[];
-    /**
-     * Exact raw agent id for the family identified by its default-variant id
-     * (`AvailableModel.id`) at the given effort and service tier. Picks the
-     * `-fast` id when `serviceTier` is "fast" and the family has one, otherwise
-     * the normal id. `reasoningLevel` omitted falls back to the family's default
-     * effort. Returns undefined when the family or requested effort is unknown.
-     */
     resolveVariant(args: {
         model: string;
         reasoningLevel?: ReasoningLevel;