@gajae-code/ai 0.16.7 → 0.17.1

package/src/providers/devin-acp.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Devin CLI provider — an ACP (Agent Client Protocol) client.
+ *
+ * Devin CLI exposes no raw model-inference endpoint. Its programmatic surface is
+ * `devin acp`: an Agent Client Protocol server over stdio that runs the whole
+ * agent (https://docs.devin.ai/cli/reference/commands#devin-acp). GJC therefore
+ * speaks ACP as the *client* and treats Devin as an agent-level provider:
+ *
+ * - GJC spawns `devin acp` and speaks ACP over the child's stdio.
+ * - One ACP session is reused for the lifetime of a GJC conversation, keyed by
+ *   `providerSessionId` and stored in `providerSessionState`; `close()` kills
+ *   the child process at session teardown.
+ * - Devin owns conversation history, so only the newest user turn is forwarded.
+ * - Devin executes its own tools. `session/update` tool calls are rendered as
+ *   display-only `toolCall` blocks and every turn terminates with
+ *   `stopReason: "stop"`, so GJC never re-executes a Devin tool call.
+ * - `session/request_permission` is answered from an explicit policy, never
+ *   silently: see {@link DevinAcpPermissionMode}.
+ *
+ * Boundary (documented in docs/devin-provider.md): GJC tools, skills, workflows,
+ * hooks, and permission prompts for GJC's own tools do not apply inside a Devin
+ * turn; GJC maintenance work (compaction, handoff, branch summaries) and utility
+ * one-shots are refused rather than forwarded to Devin; and Devin bills its own
+ * account/ACU usage.
+ */
+import { type ContentBlock, type PermissionOption, type SessionConfigOption, type StopReason } from "@agentclientprotocol/sdk";
+import type { AssistantMessageEventStream as AssistantMessageEventStreamType, Context, Model, StreamOptions } from "../types";
+/** Environment variable overriding the Devin executable GJC spawns. */
+export declare const DEVIN_ACP_CLI_ENV = "GJC_DEVIN_CLI_PATH";
+/** Environment variable selecting how GJC answers Devin permission requests. */
+export declare const DEVIN_ACP_PERMISSION_MODE_ENV = "GJC_DEVIN_PERMISSION_MODE";
+/** Executable that serves `devin acp` when nothing overrides it. */
+export declare const DEVIN_ACP_DEFAULT_CLI = "devin";
+/**
+ * Placeholder base URL. The ACP transport never issues an HTTP request, but a
+ * model record must carry a non-empty base URL through the model registry.
+ */
+export declare const DEVIN_ACP_BASE_URL = "acp://devin-cli";
+/**
+ * Conservative catalog defaults. ACP exposes no per-model token metadata, and
+ * GJC never sends conversation history to an ACP agent, so these values are
+ * display-only for this provider rather than a transport budget.
+ */
+export declare const DEVIN_ACP_CONTEXT_WINDOW = 200000;
+export declare const DEVIN_ACP_MAX_TOKENS = 64000;
+/**
+ * How GJC answers Devin's `session/request_permission` prompts.
+ *
+ * - `"allow"` (default) selects `allow_once`. A request that offers no
+ *   `allow_once` is cancelled: GJC never grants a persistent approval on its own.
+ * - `"deny"` selects `reject_once` before `reject_always`.
+ *
+ * Neither mode escalates persistently on its own, and an unrecognized
+ * `GJC_DEVIN_PERMISSION_MODE` value fails closed to `"deny"`.
+ */
+export type DevinAcpPermissionMode = "allow" | "deny";
+/** A permission request Devin raised for one of its own tool calls. */
+export interface DevinAcpPermissionRequest {
+    sessionId: string;
+    toolCallId: string;
+    title: string;
+    kind?: string;
+    rawInput?: unknown;
+    options: ReadonlyArray<{
+        optionId: string;
+        name: string;
+        kind: string;
+    }>;
+}
+/** Selected option id, or `cancelled` to answer with ACP `outcome: cancelled`. */
+export type DevinAcpPermissionDecision = {
+    optionId: string;
+} | {
+    cancelled: true;
+};
+/** Explicit decision callback; replaces the built-in permission mode policy. */
+export type DevinAcpPermissionHandler = (request: DevinAcpPermissionRequest) => Promise<DevinAcpPermissionDecision> | DevinAcpPermissionDecision;
+/** Provider configuration threaded through `StreamOptions.devinAcp`. */
+export interface DevinAcpConfig {
+    /** Executable serving `devin acp`. Defaults to {@link DEVIN_ACP_CLI_ENV} or `devin`. */
+    cliPath?: string;
+    /** Extra argv inserted before the `acp` verb. */
+    cliArgs?: readonly string[];
+    /** Working directory for the agent process. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /**
+     * Overrides the permission policy for this request. Any value other than
+     * `"allow"` fails closed to `"deny"`, including out-of-type values from
+     * untyped callers.
+     */
+    permissionMode?: DevinAcpPermissionMode;
+    /** Explicit permission decisions. When absent, the configured mode decides. */
+    permissionHandler?: DevinAcpPermissionHandler;
+}
+/**
+ * Devin ACP stream options. Every provider-specific field lives on
+ * `StreamOptions.devinAcp`; the alias exists so `ApiOptionsMap` can name this
+ * API's option type like every other API does.
+ */
+export type DevinAcpOptions = StreamOptions;
+/** Map an ACP tool kind to the display tool name GJC renders. */
+export declare function devinAcpDisplayToolName(kind: string | null | undefined, name?: string | null): string;
+/**
+ * Copy a tool-call `rawInput` payload into a transcript-safe `arguments` record.
+ *
+ * ACP payloads arrive through JSON-RPC, so they are already JSON-shaped; this
+ * only wraps non-objects and refuses to stage an unbounded payload.
+ */
+export declare function devinAcpToolArguments(rawInput: unknown): Record<string, unknown>;
+/** Map an ACP prompt stop reason onto GJC's assistant stop reason. */
+export declare function devinAcpStopReason(stopReason: StopReason): "stop" | "length" | "aborted";
+/** Flatten ACP select option groups into `{ id, name }` model entries. */
+export declare function devinAcpSelectOptions(options: Extract<SessionConfigOption, {
+    type: "select";
+}>["options"]): Array<{
+    id: string;
+    name: string;
+}>;
+/**
+ * Select the option matching the configured policy.
+ *
+ * `allow` grants a single action and never a persistent one: when the agent
+ * offers no `allow_once`, the request is cancelled rather than escalated to
+ * `allow_always`. `deny` may fall back to `reject_always`, because a persistent
+ * refusal only reduces what the agent may do.
+ */
+export declare function devinAcpSelectPermissionOption(options: ReadonlyArray<PermissionOption>, mode: DevinAcpPermissionMode): {
+    optionId: string;
+} | null;
+/** Resolve the permission policy from an explicit config value or the environment. */
+export declare function devinAcpResolvePermissionMode(configured: DevinAcpPermissionMode | undefined, env?: Record<string, string | undefined>): DevinAcpPermissionMode;
+/** Build the ACP prompt content blocks for the newest user turn. */
+export declare function devinAcpPromptBlocks(context: Context, supportsImages: boolean): ContentBlock[];
+/**
+ * Stable identity for the cached ACP child.
+ *
+ * `cwd` is part of the identity on purpose: `/move` changes `process.cwd()`, and a
+ * cached child keeps the directory it was spawned in, so a cwd change must miss the
+ * cache and respawn instead of running Devin's tools in the abandoned tree.
+ */
+export declare function devinAcpBridgeIdentity(conversationId: string | undefined, cwd: string, argv: readonly string[]): string;
+export declare const streamDevinAcp: (model: Model<"devin-acp">, context: Context, options?: DevinAcpOptions) => AssistantMessageEventStreamType;
+/**
+ * Discover the account's Devin models over ACP.
+ *
+ * `devin models list --format json` is deliberately not parsed: its schema is
+ * undocumented, while the session's own `model` config option is the
+ * authoritative ACP surface for the authenticated account and enterprise
+ * allowlists. Returns `null` when the CLI is missing, unauthenticated, or the
+ * agent advertises no model selector — which the model registry treats as
+ * "no dynamic models".
+ */
+export declare function fetchDevinAcpModels(config?: {
+    cliPath?: string;
+    cliArgs?: readonly string[];
+    cwd?: string;
+}): Promise<Model<"devin-acp">[] | null>;