@margay/ccl-core 1.3.5-rc.6

package/dist/sdk/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ccl-sdk — embeddable SDK form of CCL.
+ *
+ * import { query, resumeWithDecision } from '@margay/ccl-core/sdk'
+ *
+ * for await (const event of query('...', { canUseTool, sessionId })) { ... }
+ */
+export { buildCliArgs, buildCliEnv, decideFailClosed, getSessionUsage, prepareSkillsWrappers, queryWithTransport, resumeWithDecision, } from './query.js';
+export { query, queryHandleWithTransport } from './queryHandle.js';
+export { createSdkMcpServer, tool, SdkMcpRegistry, type SdkMcpToolDefinition, type McpSdkServerConfigWithInstance, } from './mcpServer.js';
+export { defaultStoreDir, fileSessionStore } from './store.js';
+export { spawnCliTransport } from './transport.js';
+export type { AccumulatedUsage, CanUseToolContext, CanUseToolFn, CanUseToolResult, InitializationResult, LifecycleHooks, PendingApproval, PendingDecision, ProviderConfig, Query, QueryOptions, SDKEvent, SessionStore, Transport, Usage, WireMessage, } from './types.js';

package/dist/sdk/index.js

@@ -0,0 +1,12 @@
+/**
+ * ccl-sdk — embeddable SDK form of CCL.
+ *
+ * import { query, resumeWithDecision } from '@margay/ccl-core/sdk'
+ *
+ * for await (const event of query('...', { canUseTool, sessionId })) { ... }
+ */
+export { buildCliArgs, buildCliEnv, decideFailClosed, getSessionUsage, prepareSkillsWrappers, queryWithTransport, resumeWithDecision, } from './query.js';
+export { query, queryHandleWithTransport } from './queryHandle.js';
+export { createSdkMcpServer, tool, SdkMcpRegistry, } from './mcpServer.js';
+export { defaultStoreDir, fileSessionStore } from './store.js';
+export { spawnCliTransport } from './transport.js';

package/dist/sdk/mcpServer.d.ts

@@ -0,0 +1,52 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { type ZodRawShape } from 'zod/v4';
+export type SdkMcpToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: ZodRawShape;
+    handler: (args: Record<string, unknown>, extra: unknown) => Promise<unknown> | unknown;
+    annotations?: Record<string, unknown>;
+    searchHint?: string;
+};
+export type McpSdkServerConfigWithInstance = {
+    name: string;
+    version?: string;
+    tools?: SdkMcpToolDefinition[];
+    /** The live @modelcontextprotocol/sdk Server built from `tools`. */
+    instance?: Server;
+    [key: string]: unknown;
+};
+/** Define one in-process tool (Claude-Agent-SDK-compatible signature). */
+export declare function tool(name: string, description: string, inputSchema: ZodRawShape, handler: SdkMcpToolDefinition['handler'], extras?: {
+    annotations?: Record<string, unknown>;
+    searchHint?: string;
+}): SdkMcpToolDefinition;
+/**
+ * Build an in-process MCP server from host-defined JS tools. Returns a config carrying the live
+ * `@modelcontextprotocol/sdk` Server; pass it to `query({ sdkMcpServers: [createSdkMcpServer(...)] })`.
+ */
+export declare function createSdkMcpServer(options: {
+    name: string;
+    version?: string;
+    tools?: SdkMcpToolDefinition[];
+}): McpSdkServerConfigWithInstance;
+/**
+ * Bridges host in-process MCP servers to the control protocol. For each inbound `mcp_message`
+ * control_request from the CLI subprocess, routes the JSONRPC message to the matching server and
+ * replies to that request_id with the server's JSONRPC response. Request/response are correlated by
+ * JSONRPC id; notifications (no id) are acked immediately.
+ */
+export declare class SdkMcpRegistry {
+    private readonly reply;
+    private readonly transports;
+    private readonly pending;
+    private constructor();
+    /** Connect every server's instance to a control transport. */
+    static create(configs: McpSdkServerConfigWithInstance[], reply: (requestId: string, mcpResponse: JSONRPCMessage | undefined) => void): Promise<SdkMcpRegistry>;
+    get names(): string[];
+    has(serverName: string): boolean;
+    /** Handle one inbound `mcp_message` control_request. Never throws (fail-soft). */
+    handle(serverName: string, message: JSONRPCMessage, requestId: string): void;
+    close(): Promise<void>;
+}

package/dist/sdk/mcpServer.js

@@ -0,0 +1,134 @@
+// slice sdk-in-process-mcp-server (G1/S1) — host defines JS tools IN-PROCESS; the agent running in
+// the spawned CLI subprocess calls them over the control protocol (`mcp_message`). This file is
+// SELF-CONTAINED: tsconfig.sdk.json compiles only `sdk/**` (rootDir:sdk), so it may import ONLY
+// node_modules (never ../services or ../utils). The pass-through transport is therefore inlined.
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod/v4';
+/** Define one in-process tool (Claude-Agent-SDK-compatible signature). */
+export function tool(name, description, inputSchema, handler, extras) {
+    return { name, description, inputSchema, handler, ...(extras ?? {}) };
+}
+/** Normalize a handler return value into an MCP CallToolResult. */
+function toCallToolResult(result) {
+    if (result &&
+        typeof result === 'object' &&
+        'content' in result) {
+        return result;
+    }
+    const text = typeof result === 'string' ? result : JSON.stringify(result ?? null);
+    return { content: [{ type: 'text', text }] };
+}
+/**
+ * Build an in-process MCP server from host-defined JS tools. Returns a config carrying the live
+ * `@modelcontextprotocol/sdk` Server; pass it to `query({ sdkMcpServers: [createSdkMcpServer(...)] })`.
+ */
+export function createSdkMcpServer(options) {
+    const tools = options.tools ?? [];
+    const server = new Server({ name: options.name, version: options.version ?? '1.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map(t => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: z.toJSONSchema(z.object(t.inputSchema)),
+            ...(t.annotations ? { annotations: t.annotations } : {}),
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+        const t = tools.find(x => x.name === params.name);
+        if (!t) {
+            throw new Error(`SDK MCP tool '${params.name}' not found on server '${options.name}'`);
+        }
+        const out = await t.handler((params.arguments ?? {}), {});
+        return toCallToolResult(out);
+    });
+    return { name: options.name, version: options.version, tools, instance: server };
+}
+/** Minimal pass-through Transport for an in-process SDK MCP server (inlined; see file header). */
+class SdkControlServerTransport {
+    onSend;
+    closed = false;
+    onclose;
+    onerror;
+    onmessage;
+    constructor(onSend) {
+        this.onSend = onSend;
+    }
+    async start() { }
+    async send(message) {
+        if (this.closed)
+            throw new Error('Transport is closed');
+        this.onSend(message);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.onclose?.();
+    }
+}
+function messageId(message) {
+    return message.id;
+}
+/**
+ * Bridges host in-process MCP servers to the control protocol. For each inbound `mcp_message`
+ * control_request from the CLI subprocess, routes the JSONRPC message to the matching server and
+ * replies to that request_id with the server's JSONRPC response. Request/response are correlated by
+ * JSONRPC id; notifications (no id) are acked immediately.
+ */
+export class SdkMcpRegistry {
+    reply;
+    transports = new Map();
+    pending = new Map();
+    constructor(reply) {
+        this.reply = reply;
+    }
+    /** Connect every server's instance to a control transport. */
+    static async create(configs, reply) {
+        const reg = new SdkMcpRegistry(reply);
+        for (const cfg of configs) {
+            if (!cfg.instance)
+                continue;
+            const transport = new SdkControlServerTransport(message => {
+                const id = messageId(message);
+                if (id !== undefined && reg.pending.has(id)) {
+                    const requestId = reg.pending.get(id);
+                    reg.pending.delete(id);
+                    reg.reply(requestId, message);
+                }
+            });
+            await cfg.instance.connect(transport);
+            reg.transports.set(cfg.name, transport);
+        }
+        return reg;
+    }
+    get names() {
+        return [...this.transports.keys()];
+    }
+    has(serverName) {
+        return this.transports.has(serverName);
+    }
+    /** Handle one inbound `mcp_message` control_request. Never throws (fail-soft). */
+    handle(serverName, message, requestId) {
+        const transport = this.transports.get(serverName);
+        if (!transport) {
+            const id = messageId(message) ?? null;
+            this.reply(requestId, {
+                jsonrpc: '2.0',
+                id,
+                error: { code: -32601, message: `unknown SDK MCP server '${serverName}'` },
+            });
+            return;
+        }
+        const id = messageId(message);
+        if (id !== undefined)
+            this.pending.set(id, requestId);
+        transport.onmessage?.(message);
+        if (id === undefined)
+            this.reply(requestId, undefined);
+    }
+    async close() {
+        for (const t of this.transports.values())
+            await t.close();
+    }
+}

package/dist/sdk/query.d.ts

@@ -0,0 +1,91 @@
+/**
+ * ccl-sdk query() — the programmatic headless entry (issue P0-1) with the
+ * canUseTool permission callback (P0-2 including pending suspend/resume),
+ * session store integration (P0-3), provider mapping (P0-4), skills dirs
+ * (P1-5), lifecycle hooks (P1-6), and usage accumulation (P1-7).
+ *
+ * Architecture: the SDK is the HOST side of the stream-json control protocol
+ * that cli/print.ts already implements. We run the CLI as a managed
+ * subprocess (explicitly allowed by the issue's "进程内(或受管子进程)"),
+ * which keeps every user-visible CLI behavior — tools, skills, hooks, session
+ * persistence, gateway routing — byte-identical between CLI and SDK use.
+ *
+ * Pending suspend/resume mechanism (P0-2, zero CLI changes):
+ * - Suspend: on a `pending` callback result we persist the approval record,
+ *   terminate the subprocess WITHOUT answering the can_use_tool request, and
+ *   end the stream with a `suspended` event. The transcript on disk ends at
+ *   the assistant tool_use whose tool never ran.
+ * - Resume: resumeWithDecision() relaunches with --resume <sessionId> and
+ *   CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1. The CLI's resume path drops the
+ *   unresolved tool_use (filterUnresolvedToolUses) and auto-continues the
+ *   interrupted turn (cli/print.ts:1195), so the model re-issues the tool
+ *   call; the SDK intercepts the matching can_use_tool request and applies
+ *   the recorded decision — on allow, with EXACTLY the approved input (the
+ *   recorded pending input, or the host's updatedInput), regardless of what
+ *   the model re-generated. Deny works symmetrically. One-shot: the record
+ *   is deleted after it is applied.
+ */
+import type { CanUseToolFn, PendingDecision, QueryOptions, SDKEvent, SessionStore, Transport } from './types.js';
+/** Builds the CLI argv for a query. Exported for unit tests. */
+export declare function buildCliArgs(options: QueryOptions): string[];
+/** Builds subprocess env additions. Exported for unit tests. */
+export declare function buildCliEnv(options: QueryOptions): Record<string, string>;
+/**
+ * Wraps each skills dir as an ephemeral plugin (a temp dir whose `skills`
+ * entry symlinks to the user's dir) so the CLI loads it via --plugin-dir,
+ * its cwd-independent skill channel (P1-5). Exported for unit tests.
+ */
+export declare function prepareSkillsWrappers(skillsDirs: string[]): string[];
+type PermissionDecisionWire = {
+    behavior: 'allow';
+    updatedInput: Record<string, unknown>;
+    toolUseID: string;
+} | {
+    behavior: 'deny';
+    message: string;
+    interrupt?: boolean;
+    toolUseID: string;
+};
+type CallbackOutcome = {
+    kind: 'decision';
+    decision: PermissionDecisionWire;
+    failClosedReason?: string;
+} | {
+    kind: 'pending';
+};
+/**
+ * Fail-closed wrapper around the host's canUseTool callback (issue P0-2):
+ * throw, timeout, or an unrecognized return value all become deny, and the
+ * tool does not execute. `pending` is surfaced to the caller for suspend.
+ */
+export declare function decideFailClosed(callback: CanUseToolFn, toolName: string, input: Record<string, unknown>, context: {
+    toolUseId: string;
+    agentId?: string;
+}, timeoutMs: number): Promise<CallbackOutcome>;
+/**
+ * Core loop, transport-injectable for tests. Production callers use query()
+ * or resumeWithDecision().
+ */
+export declare function queryWithTransport(prompt: string | null, options: QueryOptions, transport: Transport): AsyncGenerator<SDKEvent>;
+/** Spawns the managed CLI subprocess for a set of options. Shared with the P1 Query handle. */
+export declare function spawnForOptions(options: QueryOptions): Transport;
+/**
+ * Run one prompt against a CCL agent session and stream JSON-serializable
+ * events. See QueryOptions for session resume, permission callback, model,
+ * provider, and tool configuration.
+ */
+export declare function query(prompt: string, options?: QueryOptions): AsyncGenerator<SDKEvent>;
+/**
+ * Resume a session suspended by a `pending` permission result and apply the
+ * owner's decision (issue P0-2 acceptance path). Cross-process: the pending
+ * record lives in the session store, the conversation in the CLI's
+ * transcript store — nothing is held in memory between suspend and resume.
+ *
+ * On allow, the suspended tool executes with exactly the recorded input (or
+ * decision.updatedInput if the owner amended it); on deny the model receives
+ * the denial and the session continues.
+ */
+export declare function resumeWithDecision(sessionId: string, decision: PendingDecision, options?: QueryOptions): AsyncGenerator<SDKEvent>;
+/** P1-7: accumulated usage for a session, across all queries that ran it. */
+export declare function getSessionUsage(sessionId: string, store?: SessionStore): ReturnType<SessionStore['getUsage']>;
+export {};