@agent-native/core 0.64.1 → 0.66.0

package/dist/agent/harness/acp-adapter.d.ts

@@ -0,0 +1,145 @@
+/**
+ * ACP (Agent Client Protocol) harness adapter.
+ *
+ * Lets Agent-Native act as an ACP *client* and drive a local coding agent —
+ * Gemini CLI, Claude Code, or any other ACP-compliant agent — through the
+ * existing {@link AgentHarnessAdapter} substrate. The agent runs as a local
+ * subprocess that owns its own loop, tools, and workspace filesystem access,
+ * which is exactly the shape ACP was designed for. See:
+ * https://agentclientprotocol.com
+ *
+ * Scope: this adapter targets *local* coding. The agent is spawned as a child
+ * process and speaks newline-delimited JSON-RPC over stdio. It reuses whatever
+ * local CLI login the agent already has (e.g. `gemini`/`claude` auth in the
+ * user's home dir) by inheriting the parent environment. It is not a hosted or
+ * sandboxed transport, and it is not a chat/A2A transport.
+ *
+ * The protocol transport and framing are handled by the official
+ * `@zed-industries/agent-client-protocol` package, loaded lazily as an optional
+ * dependency so apps that never use ACP do not pay for it. Everything in this
+ * file beyond the thin spawn/connection glue is pure mapping logic between ACP
+ * `session/update` notifications and {@link AgentHarnessEvent}s.
+ */
+import type { AgentHarnessAdapter, AgentHarnessEvent, AgentHarnessMessage, AgentHarnessPermissionMode } from "./types.js";
+/**
+ * The optional package that carries the ACP protocol transport. Loaded lazily;
+ * `resolveAgentHarness` surfaces a clear install error when it is missing.
+ */
+export declare const ACP_PACKAGE = "@zed-industries/agent-client-protocol";
+export interface AcpHarnessAdapterOptions {
+    /** Adapter id, e.g. "acp:gemini". Defaults to "acp". */
+    name?: string;
+    /** Human-readable label for pickers. */
+    label?: string;
+    /** Short description for pickers and diagnostics. */
+    description?: string;
+    /** Executable to spawn (the ACP agent binary), e.g. "gemini" or "npx". */
+    command?: string;
+    /** Arguments passed to the agent binary, e.g. ["--experimental-acp"]. */
+    args?: string[];
+    /**
+     * Extra environment variables for the agent process. Merged over the parent
+     * environment, which the agent inherits so it can reuse the user's local CLI
+     * login.
+     */
+    env?: Record<string, string>;
+    /** Default working directory when a turn does not specify one. */
+    cwd?: string;
+    /** Hint shown when the optional ACP package is missing. */
+    installPackage?: string;
+}
+export declare function createAcpHarnessAdapter(options: AcpHarnessAdapterOptions): AgentHarnessAdapter;
+/** Build the ACP prompt content blocks for a turn. */
+export declare function buildAcpPromptBlocks(input: {
+    prompt?: string;
+    messages?: AgentHarnessMessage[];
+}): Array<{
+    type: "text";
+    text: string;
+}>;
+/**
+ * Translate a single ACP `session/update` payload into harness events. Pure and
+ * stateless; the caller supplies a resolver for tool titles seen on earlier
+ * `tool_call` updates so completion events can be labelled.
+ */
+export declare function acpUpdateToHarnessEvents(update: AcpSessionUpdate, titleFor?: (toolCallId: string) => string | undefined): AgentHarnessEvent[];
+/** Extract displayable text from an ACP content block. */
+export declare function acpContentBlockToText(block: AcpContentBlock | undefined): string;
+/** Derive file-change events from a tool call's `diff` content blocks. */
+export declare function acpFileChangeEventsFromToolContent(content: AcpToolCallContent[] | undefined | null): AgentHarnessEvent[];
+/**
+ * Map an Agent-Native permission mode onto a decision for an ACP permission
+ * request, using the tool-call kind the agent reports. Reads always run; edits
+ * run under `allow-edits`; everything risky prompts unless `allow-all`.
+ */
+export declare function acpAutoPermissionDecision(kind: string | undefined, mode: AgentHarnessPermissionMode): "allow" | "prompt";
+/**
+ * Pick the option id to return for an ACP permission request. Prefers the
+ * "once" variant so approvals do not silently become "always".
+ */
+export declare function selectAcpPermissionOption(options: AcpPermissionOption[], approved: boolean): string | undefined;
+/**
+ * Resolve a path requested by the agent against the session workspace, refusing
+ * anything that escapes it. The agent already has its own filesystem tools;
+ * this `fs/*` surface is a scoped convenience, not an arbitrary read/write hole.
+ */
+export declare function resolveAcpWorkspacePath(cwd: string, requestedPath: string): string;
+interface AcpContentBlock {
+    type: string;
+    text?: string;
+    uri?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+interface AcpToolCallContent {
+    type: string;
+    content?: AcpContentBlock;
+    path?: string;
+    oldText?: string | null;
+    newText?: string;
+    terminalId?: string;
+}
+interface AcpPlanEntry {
+    content?: string;
+    status?: string;
+    priority?: string;
+}
+export type AcpSessionUpdate = {
+    sessionUpdate: "agent_message_chunk" | "user_message_chunk" | "agent_thought_chunk";
+    content: AcpContentBlock;
+} | {
+    sessionUpdate: "tool_call";
+    toolCallId: string;
+    title: string;
+    kind?: string;
+    status?: string;
+    content?: AcpToolCallContent[];
+    rawInput?: Record<string, unknown>;
+    rawOutput?: Record<string, unknown>;
+    locations?: unknown[];
+} | {
+    sessionUpdate: "tool_call_update";
+    toolCallId: string;
+    title?: string | null;
+    kind?: string | null;
+    status?: string | null;
+    content?: AcpToolCallContent[] | null;
+    rawInput?: Record<string, unknown>;
+    rawOutput?: Record<string, unknown>;
+} | {
+    sessionUpdate: "plan";
+    entries: AcpPlanEntry[];
+} | {
+    sessionUpdate: "available_commands_update";
+    availableCommands: unknown[];
+} | {
+    sessionUpdate: "current_mode_update";
+    currentModeId: string;
+};
+interface AcpPermissionOption {
+    optionId: string;
+    name: string;
+    kind: "allow_once" | "allow_always" | "reject_once" | "reject_always";
+}
+export {};
+//# sourceMappingURL=acp-adapter.d.ts.map

package/dist/agent/harness/acp-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-adapter.d.ts","sourceRoot":"","sources":["../../../src/agent/harness/acp-adapter.ts"],"names":[],"mappings":"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"}