@qilin-agent/acp 0.0.0-stage → 3.1.4

package/lib/types/codec.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pure translation between the harness lifecycle and the automation-only ACP wire.
+ * @module @qilin-agent/acp/codec
+ */
+import type { StopReason } from '@agentclientprotocol/sdk';
+import type { TurnEndReason } from '@qilin-agent/session';
+/**
+ * Map a harness turn ending to ACP's terminal reason vocabulary.
+ * @param reason - harness turn outcome.
+ * @returns the closest legal ACP stop reason.
+ */
+export declare function turnEndToStopReason(reason: TurnEndReason): StopReason;
+//# sourceMappingURL=codec.d.ts.map

package/lib/types/content.d.ts

@@ -0,0 +1,50 @@
+/** ACP wire-content admission and projection owned by the ACP adapter. @module */
+import type { ContentBlock as AcpContentBlock } from '@agentclientprotocol/sdk';
+import type { Context } from '@qilin-agent/kylin';
+import type { ModelSelection } from '@qilin-agent/agent';
+import type { ContentBlock } from '@qilin-agent/llm';
+/** Content-admission failure category used by the protocol handler. */
+export type AcpContentFailureKind = 'invalid' | 'internal';
+/** Error with a stable ACP request-failure category and no raw binary payload. */
+export declare class AcpContentError extends Error {
+    /** Whether the bridge should report invalid params or an internal failure. */
+    readonly kind: AcpContentFailureKind;
+    /**
+     * @param message - safe protocol-facing detail without inline binary data.
+     * @param kind - request-failure category.
+     * @param options - optional causal chain for diagnostics.
+     */
+    constructor(message: string, kind: AcpContentFailureKind, options?: ErrorOptions);
+}
+/**
+ * Determine whether initialization may truthfully advertise inline image prompts.
+ * Unknown service, route, capability, or deployment media support is negative.
+ * @param ctx - bridge context carrying optional attachment and model services.
+ * @param provider - configured provider route used for newly created sessions.
+ * @param model - configured exact model id used for newly created sessions.
+ * @returns whether this bridge can admit images at initialization time.
+ */
+export declare function supportsAcpImagePrompts(ctx: Context, provider: string | undefined, model: string | undefined): Promise<boolean>;
+/**
+ * Admit one ACP prompt into ordered durable core content.
+ * Every wire block and image is validated before the ordered image batch starts
+ * writing; cancellation after a successful content-addressed write may leave an
+ * unreachable object but never queues a late user message.
+ * @param ctx - bridge context carrying attachment and model services.
+ * @param route - selection pinned to the accepted prompt.
+ * @param prompt - untrusted ACP prompt blocks in wire order.
+ * @param imageEnabled - capability result advertised during initialization.
+ * @param signal - admission cancellation signal.
+ * @returns core content with durable image references in wire order.
+ */
+export declare function admitAcpPrompt(ctx: Context, route: ModelSelection | undefined, prompt: readonly AcpContentBlock[], imageEnabled: boolean, signal: AbortSignal): Promise<ContentBlock[]>;
+/**
+ * Translate one committed assistant block to ACP wire content.
+ * Images are re-read and integrity-verified before inline base64 delivery;
+ * unsupported core output blocks stay off the automation wire.
+ * @param ctx - bridge context carrying the authoritative attachment store.
+ * @param block - committed core assistant block.
+ * @returns ACP text/image content, or undefined for non-output blocks.
+ */
+export declare function assistantBlockToAcp(ctx: Context, block: ContentBlock): Promise<AcpContentBlock | undefined>;
+//# sourceMappingURL=content.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Automation-only Agent Client Protocol server over JSON-RPC stdio.
+ *
+ * The bridge exposes persistent harness sessions to trusted programmatic
+ * clients. It carries standard configuration, MCP mounts, prompt content,
+ * committed semantic updates, cancellation, and one-shot permission decisions;
+ * presentation and human-interaction features stay with the harness's UI modules.
+ *
+ * @module @qilin-agent/acp
+ */
+import type { Context } from '@qilin-agent/kylin';
+import Schema from '@qilin-agent/schemastery';
+import { type Stream } from '@agentclientprotocol/sdk';
+export declare const name = "acp";
+/** Core services required by the standard automation controls. */
+export declare const inject: string[];
+/** Plugin config: the provider/model selection used for each ACP-created agent. */
+export interface AcpConfig {
+    /** Provider route for created agents. */
+    provider?: string;
+    /** Model name for created agents. */
+    model?: string;
+    /** Maximum summaries returned by one session/list page. */
+    sessionListPageSize?: number;
+    /** Runtime-only transport override; production uses stdio. */
+    stream?: Stream;
+}
+export declare const Config: Schema<AcpConfig>;
+/**
+ * Mount the automation-only ACP server.
+ * @param ctx - Cordis context carrying the agent factory and session events.
+ * @param config - Initial provider/model selection and optional test transport.
+ */
+export declare function apply(ctx: Context, config: AcpConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/mcp.d.ts

@@ -0,0 +1,15 @@
+/** Standard ACP MCP-server declarations translated into Agent-scoped QILIN MCP clients. */
+import type { Context } from '@qilin-agent/kylin';
+import type { McpServer } from '@agentclientprotocol/sdk';
+/** Caller-correctable MCP declaration failure. */
+export declare class AcpMcpConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate and mount one session's complete standard MCP server list before Agent publication.
+ * @param agentCtx - unpublished Agent scope that owns the MCP clients and tools.
+ * @param servers - stable ACP stdio or HTTP server declarations.
+ * @param sessionCwd - canonical primary workspace used by stdio servers.
+ */
+export declare function mountAcpMcpServers(agentCtx: Context, servers: readonly McpServer[], sessionCwd: string): Promise<void>;
+//# sourceMappingURL=mcp.d.ts.map

package/lib/types/model-control.d.ts

@@ -0,0 +1,62 @@
+/** Standard ACP session configuration over one Agent's model selection. */
+import type { Context } from '@qilin-agent/kylin';
+import type { SessionConfigOption } from '@agentclientprotocol/sdk';
+import { type ModelSelection, type ModelSelectionRef } from '@qilin-agent/agent';
+import { type LlmRuntime } from '@qilin-agent/llm';
+/** Caller-correctable session configuration failure. */
+export declare class AcpModelConfigError extends Error {
+    constructor(message: string);
+}
+/** Project and mutate one Agent's provider/model/reasoning selection through ACP config options. */
+export declare class AcpModelControl {
+    private readonly llm;
+    /** Scoped selection reference consumed by Agent request assembly. */
+    readonly selection: ModelSelectionRef;
+    private tail;
+    private selected;
+    private turnSelection;
+    private hasResolvedState;
+    constructor(llm: LlmRuntime, initial: ModelSelection | undefined);
+    /**
+     * Install request/prompt consistency listeners in the unpublished Agent scope.
+     * @param agentCtx - Agent scope that consumes this selection.
+     */
+    install(agentCtx: Context): void;
+    /**
+     * Snapshot the selection attached to the next accepted ACP prompt.
+     * @returns a detached future selection, or undefined when listeners supply the route.
+     */
+    snapshot(): ModelSelection | undefined;
+    /**
+     * Pin one admitted ACP message's selection for every step in its turn.
+     * @param turn - admitted Agent turn.
+     * @param selection - exact prompt-admission selection.
+     */
+    pinTurn(turn: number, selection: ModelSelection): void;
+    /**
+     * Release only the exact completed turn's routing override.
+     * @param turn - completed Agent turn.
+     */
+    releaseTurn(turn: number): void;
+    /**
+     * Return the complete standard config-option state after prior mutations settle.
+     * @param signal - optional catalog and exact-model cancellation.
+     * @returns all current standard configuration options.
+     */
+    options(signal?: AbortSignal): Promise<SessionConfigOption[]>;
+    /**
+     * Set one advertised option and return the complete resulting option state.
+     * @param configId - standard option id.
+     * @param value - opaque selected value returned by a previous option state.
+     * @param signal - optional catalog and exact-model cancellation.
+     * @returns all standard options after the serialized mutation.
+     */
+    set(configId: string, value: unknown, signal?: AbortSignal): Promise<SessionConfigOption[]>;
+    /** Keep concurrent client mutations in receive order without wedging after rejection. */
+    private serialize;
+    /** Build detached model choices and the dependent reasoning option. */
+    private state;
+    /** Validate an exact route and retain only Agent-owned selection fields. */
+    private resolveSelection;
+}
+//# sourceMappingURL=model-control.d.ts.map

package/lib/types/session.d.ts

@@ -0,0 +1,128 @@
+/** One standard ACP session's Agent, configuration, prompt, update, and teardown lifecycle. */
+import type { Context } from '@qilin-agent/kylin';
+import { type McpServer, type PromptRequest, type PromptResponse, type SessionConfigOption, type SessionNotification } from '@agentclientprotocol/sdk';
+import type { Agent, AgentOptions, AgentStatus, ModelSelection } from '@qilin-agent/agent';
+import { type UserMessage } from '@qilin-agent/llm';
+import { type Session, type SessionEvent, type SessionId } from '@qilin-agent/session';
+/** Inputs shared by fresh and resumed ACP session construction. */
+interface AcpSessionBuildOptions {
+    cwd: string;
+    mcpServers: readonly McpServer[];
+    agentOptions: AgentOptions;
+    fallbackSelection: ModelSelection | undefined;
+    signal: AbortSignal;
+    notify: (notification: SessionNotification) => Promise<void>;
+}
+/** Fresh ACP session construction inputs. */
+export interface CreateAcpSessionOptions extends AcpSessionBuildOptions {
+    sessionId: SessionId;
+}
+/** Persisted ACP session construction inputs. */
+export interface ResumeAcpSessionOptions extends AcpSessionBuildOptions {
+    sessionId: SessionId;
+}
+/**
+ * Per-session ACP module. It owns the unpublished Agent composition, selected
+ * route, one-prompt admission slot, ordered standard updates, and memoized
+ * quiescent teardown.
+ */
+export declare class AcpSession {
+    private readonly ctx;
+    private readonly notify;
+    /** The exact top-level Agent owned by this ACP session. */
+    readonly agent: Agent;
+    private readonly modelControl;
+    private outputTail;
+    private inflight;
+    private closing;
+    private readonly pendingSelections;
+    private constructor();
+    private readonly disposeAgent;
+    /**
+     * Compose a fresh Agent and all requested MCP clients before publication.
+     * @param ctx - ACP plugin context with Agent, LLM, and persistence services.
+     * @param options - fresh session identity, workspace, route, MCP, and notifier.
+     * @returns the fully composed per-session module.
+     */
+    static create(ctx: Context, options: CreateAcpSessionOptions): Promise<AcpSession>;
+    /**
+     * Restore a persisted Agent and compose the request's fresh MCP connections.
+     * @param ctx - ACP plugin context with Agent, LLM, and persistence services.
+     * @param options - persisted identity, workspace, fallback route, MCP, and notifier.
+     * @returns the restored per-session module.
+     */
+    static resume(ctx: Context, options: ResumeAcpSessionOptions): Promise<AcpSession>;
+    /**
+     * Whether this module owns an exact Agent reference.
+     * @param agent - Agent observed on a scoped runtime event.
+     * @returns true only for this session's owned Agent.
+     */
+    owns(agent: Agent): boolean;
+    /**
+     * Whether this module owns an exact Session reference.
+     * @param session - Session observed on a durable event.
+     * @returns true only for this session's owned Session.
+     */
+    ownsSession(session: Session): boolean;
+    /**
+     * Return the complete standard model configuration state.
+     * @param signal - optional request cancellation.
+     * @returns provider-grouped model and exact-model reasoning options.
+     */
+    configOptions(signal?: AbortSignal): Promise<SessionConfigOption[]>;
+    /**
+     * Apply one standard configuration option to later ACP turns.
+     * @param configId - advertised standard option id.
+     * @param value - selected standard option value.
+     * @param signal - optional request cancellation.
+     * @returns the complete resulting option state.
+     */
+    setConfig(configId: string, value: unknown, signal?: AbortSignal): Promise<SessionConfigOption[]>;
+    /** Resolve topology state off-chain, then serialize its notification without blocking execution updates. */
+    topologyChanged(): void;
+    /**
+     * Admit one prompt and settle after the root, descendants, and updates finish.
+     * @param params - standard ACP prompt request for this session.
+     * @param imageEnabled - connection capability advertised at initialization.
+     * @param requestSignal - JSON-RPC request cancellation signal.
+     * @returns the correlated standard stop reason after ordered updates drain.
+     */
+    prompt(params: PromptRequest, imageEnabled: boolean, requestSignal?: AbortSignal): Promise<PromptResponse>;
+    /** Cancel the active prompt, or autonomous work when no ACP prompt exists. */
+    cancel(): void;
+    /**
+     * Process one durable event and enqueue its standard ACP projections.
+     * @param session - exact event-owning Session.
+     * @param event - committed durable event.
+     */
+    onSessionEvent(session: Session, event: SessionEvent): void;
+    /**
+     * Correlate an accepted user message with its Agent turn and pinned route.
+     * @param message - claimed durable inbox message.
+     * @param turn - allocated Agent turn.
+     */
+    onInboxClaimed(message: UserMessage, turn: number): void;
+    /**
+     * Correlate an Agent interval failure with the active ACP prompt.
+     * @param error - original same-process failure.
+     */
+    onAgentError(error: unknown): void;
+    /**
+     * Complete cancelled activity without following a later root driver.
+     * @param status - the emitted transition, which may precede a reentrant wake.
+     */
+    onAgentStatus(status: AgentStatus): void;
+    /** Await every update queued before this call. */
+    drainUpdates(): Promise<void>;
+    /**
+     * Cancel, drain, flush, and dispose this session once.
+     * @param detail - cancellation detail for any prompt still in admission.
+     * @returns the shared quiescent teardown promise.
+     */
+    close(detail: string): Promise<void>;
+    private assertActive;
+    private cancelPrompt;
+    private settleAfterQuiescence;
+}
+export {};
+//# sourceMappingURL=session.d.ts.map

package/lib/types/updates.d.ts

@@ -0,0 +1,26 @@
+/** Standard ACP updates derived from committed QILIN session events. */
+import type { Context } from '@qilin-agent/kylin';
+import type { SessionUpdate } from '@agentclientprotocol/sdk';
+import type { Session, SessionEvent } from '@qilin-agent/session';
+/**
+ * Convert one committed assistant message and its context usage in block order.
+ * @param ctx - bridge context carrying attachment and token-meter services.
+ * @param session - durable session used for context pressure.
+ * @param event - committed assistant message event.
+ * @returns ordered standard thought, message, and optional usage updates.
+ */
+export declare function assistantUpdates(ctx: Context, session: Session, event: SessionEvent<'assistant/message'>): Promise<SessionUpdate[]>;
+/**
+ * Start one generic ACP tool lifecycle from the durable call fact.
+ * @param event - committed QILIN tool-call event.
+ * @returns the standard generic tool-call update.
+ */
+export declare function toolCallUpdate(event: SessionEvent<'tool/call'>): SessionUpdate;
+/**
+ * Finish one generic ACP tool lifecycle from its committed model-facing result.
+ * @param ctx - bridge context carrying the attachment store.
+ * @param event - committed QILIN tool-result event.
+ * @returns the standard completed or failed tool-call update.
+ */
+export declare function toolResultUpdate(ctx: Context, event: SessionEvent<'tool/result'>): Promise<SessionUpdate>;
+//# sourceMappingURL=updates.d.ts.map

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@qilin-agent/acp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Automation-only Agent Client Protocol server for driving QiLin agents over JSON-RPC stdio",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/acp/acp"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.4.0",
+    "@qilin-agent/brand": "3.1.4",
+    "@qilin-agent/schemastery": "~3.18.3"
+  },
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/attachment": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/session-persistence": "3.1.4",
+    "@qilin-agent/mcp-client": "3.1.4",
+    "@qilin-agent/token-meter": "3.1.4",
+    "@qilin-agent/user-approval": "3.1.4"
+  },
+  "peerDependenciesMeta": {
+    "@qilin-agent/token-meter": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/agent-loop": "3.1.4",
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/agent-loop-testkit": "3.1.4",
+    "@qilin-agent/attachment": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/mcp-client": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/session-persistence": "3.1.4",
+    "@qilin-agent/session-projection": "3.1.4",
+    "@qilin-agent/tools": "3.1.4",
+    "@qilin-agent/user-approval": "3.1.4",
+    "@qilin-agent/session-persistence-jsonl": "3.1.4",
+    "@qilin-agent/token-meter": "3.1.4"
+  }
 }