@margay/ccl-core 1.5.0-alpha.4 → 1.5.1-alpha.2

package/dist/sdk/executionGuidance.js

@@ -0,0 +1,37 @@
+// Main and read-only agents share the boundary between using a capability and
+// investigating its implementation. Tool availability and permissions stay local.
+export const TOOL_EXECUTION_GUIDANCE = `Start from the requested outcome and the paths, tool descriptions, and usage instructions already supplied. When an available tool or CLI has enough information to perform the requested operation, call it through an authorized tool directly. Using a documented command does not itself require reading its implementation or requesting help first. Consult targeted help or source when required details are missing, an actual result needs diagnosis, or the task asks you to inspect or change the implementation.
+
+You can request multiple tool calls in a single response. Group necessary calls when their inputs are already known and they have no result dependencies or conflicting side effects. The host determines which calls can execute concurrently. If a call needs an earlier result, or the operations could interfere, wait for the earlier result before requesting the dependent call. After a batch returns, use its results together to determine what remains unresolved. Do not add unnecessary calls just to form a batch, or repeat a completed lookup unless missing information, changed state, or necessary verification warrants it.
+
+For investigation or design, gather the evidence needed to support the requested conclusions. A successful query may leave relevant documentation or implementation questions unresolved. Distinguish facts established by the evidence, information you have not checked, and absence confirmed within a checked scope. A field missing from a query response does not establish that documentation or another capability does not exist. Report unresolved information as unknown when further investigation is outside the requested scope.
+
+Keep exploration focused on the questions needed for the requested outcome; a lookup or execution task is not automatically a codebase investigation. Once that outcome and its necessary verification are complete, report them without extending the search to unrelated files or capabilities.`;
+/**
+ * Shared CLI/SDK execution guidance for the tools exposed by the caller.
+ * Pure text assembly: does not load tools, grant permissions, or alter persona.
+ * Pass canonical tool names from the effective pool, not display aliases.
+ */
+export function getExecutionGuidance(toolNames) {
+    const enabled = new Set(toolNames);
+    const fileGuidance = [];
+    for (const [name, operation] of [
+        ['Read', 'ordinary file reads'],
+        ['Edit', 'targeted file edits'],
+        ['Write', 'creating or replacing file contents'],
+        ['Glob', 'finding paths by filename pattern'],
+        ['Grep', 'searching file contents'],
+    ]) {
+        if (enabled.has(name))
+            fileGuidance.push(`For ${operation}, prefer ${name} when suitable.`);
+    }
+    if (enabled.has('Bash')) {
+        fileGuidance.push(`Use Bash for scripts, builds, tests, conversions, system commands, and metadata queries such as file permissions or directory sizes that the dedicated tools do not provide. For tasks combining inspection and execution, keep ordinary reads and searches in the available, suitable file tools; combining commands is not by itself a reason to use Bash for them. When a dedicated tool is unavailable or unsuitable, use an authorized equivalent. Keep file access and writes within the user's scope.`);
+    }
+    return [
+        ` - Use tools actually available in this session. Prefer a relevant dedicated tool when provided; examples elsewhere do not make an absent tool available. If neither the dedicated tool nor an authorized alternative is available, explain the missing capability.`,
+        ` - ${TOOL_EXECUTION_GUIDANCE}`,
+        ` - A permission denial is not a missing tool. Do not switch tools to bypass a denied operation; resolve the authorization or explain the limitation.`,
+        ...fileGuidance.map(item => `  - ${item}`),
+    ].join('\n');
+}

package/dist/sdk/index.d.ts

@@ -9,6 +9,8 @@ export { buildCliArgs, buildCliEnv, decideFailClosed, getSessionUsage, prepareSk
 export { query, queryHandleWithTransport } from './queryHandle.js';
 export { createSession, Session, type SessionOptions, type SessionControls, type Turn, type TurnResult, type InputMetadata } from './session.js';
 export type { InputProvenance } from './inputProvenance.js';
+export { readQueryLifecycle, type QueryLifecycleRead } from './queryLifecycle.js';
+export type { QueryLifecycleRecord, QueryLifecycleObservation, QueryLifecycleWrite } from './queryLifecycleTypes.js';
 export { RuntimeResourcesSchema, RuntimeResourceSchema, type RuntimeResources, type RuntimeResource } from './runtimeResources.js';
 export { createSdkMcpServer, tool, SdkMcpRegistry, type SdkMcpToolDefinition, type McpSdkServerConfigWithInstance, } from './mcpServer.js';
 export { defaultStoreDir, fileSessionStore } from './store.js';
@@ -16,3 +18,14 @@ export { spawnCliTransport } from './transport.js';
 export type { RecoveryDiagnostic } from './errorDiagnostics.js';
 export type { GatewayRequestPhase, GatewayRequestProgress } from './requestProgress.js';
 export type { AccumulatedUsage, CanUseToolContext, CanUseToolFn, CanUseToolResult, InitializationResult, LifecycleHooks, PendingApproval, PendingDecision, ProviderConfig, Query, QueryOptions, SDKEvent, SDKUserMessage, SessionStore, SessionLifecycleEvent, Transport, Usage, WireMessage, } from './types.js';
+export { getExecutionGuidance } from './executionGuidance.js';
+export { createBackgroundClient, BackgroundClientError, type BackgroundClientOptions } from './background.js';
+export type { BackgroundRun, BackgroundRunSpec, BackgroundRunLookup, BackgroundRunSelector, BackgroundRunEvent, BackgroundRunEvents, BackgroundRunAction, BackgroundRunApproval, BackgroundPermission, BackgroundRunSource } from './backgroundRunTypes.js';
+export { runCommandProcess, type CommandProcessInput, type CommandProcessResult } from './commandProcess.js';
+export { createCommandAdapter, type CommandAdapter, type CommandAdapterSpec, type CommandDefinition, type CommandOperation, type CommandOutcome, type CommandExecution, type JsonValue } from './commandAdapter.js';
+export { createOperationHost } from './operations/host.js';
+export type { OperationReference } from './operations/reference.js';
+export { createDurableCommandAdapter, type DurableCommandAdapterSpec } from './operations/command.js';
+export { OperationError, type OperationHost, type OperationHostOptions, type OperationState, type OperationView, type OperationEvent, type OperationAdapter, type OperationBinding, type OperationCapabilities, type OperationContext, type OperationInvocation, type OperationAdapterResult, type OperationPermissionRequest, type OperationPermissionDecision } from './operations/types.js';
+export { pendingApprovalIdentity, type PendingApprovalIdentity } from './pendingApprovalIdentity.js';
+export type { ScheduledOccurrence, OccurrenceCancelRequest, OccurrenceApprovalRequest, OccurrenceApprovalReceipt, OccurrenceLookup, OccurrenceEvents, OccurrenceEvent, OccurrenceExecution } from './scheduledOccurrenceTypes.js';

package/dist/sdk/index.js

@@ -8,7 +8,16 @@
 export { buildCliArgs, buildCliEnv, decideFailClosed, getSessionUsage, prepareSkillsWrappers, queryWithTransport, resumeWithDecision, } from './query.js';
 export { query, queryHandleWithTransport } from './queryHandle.js';
 export { createSession, Session } from './session.js';
+export { readQueryLifecycle } from './queryLifecycle.js';
 export { RuntimeResourcesSchema, RuntimeResourceSchema } from './runtimeResources.js';
 export { createSdkMcpServer, tool, SdkMcpRegistry, } from './mcpServer.js';
 export { defaultStoreDir, fileSessionStore } from './store.js';
 export { spawnCliTransport } from './transport.js';
+export { getExecutionGuidance } from './executionGuidance.js';
+export { createBackgroundClient, BackgroundClientError } from './background.js';
+export { runCommandProcess } from './commandProcess.js';
+export { createCommandAdapter } from './commandAdapter.js';
+export { createOperationHost } from './operations/host.js';
+export { createDurableCommandAdapter } from './operations/command.js';
+export { OperationError } from './operations/types.js';
+export { pendingApprovalIdentity } from './pendingApprovalIdentity.js';

package/dist/sdk/mcpServer.d.ts

@@ -1,3 +1,5 @@
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { ServerRequest, ServerNotification } from '@modelcontextprotocol/sdk/types.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { type JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
 import { type ZodRawShape } from 'zod/v4';
@@ -5,9 +7,12 @@ export type SdkMcpToolDefinition = {
     name: string;
     description: string;
     inputSchema: ZodRawShape;
-    handler: (args: Record<string, unknown>, extra: unknown) => Promise<unknown> | unknown;
+    handler: (args: Record<string, unknown>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => Promise<unknown> | unknown;
     annotations?: Record<string, unknown>;
+    /** Additional discovery terms, forwarded as MCP anthropic/searchHint metadata. */
     searchHint?: string;
+    /** Opt into supplying this tool's schema on the first request; does not grant permission. */
+    alwaysLoad?: boolean;
 };
 export type McpSdkServerConfigWithInstance = {
     name: string;
@@ -18,10 +23,7 @@ export type McpSdkServerConfigWithInstance = {
     [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;
+export declare function tool(name: string, description: string, inputSchema: ZodRawShape, handler: SdkMcpToolDefinition['handler'], extras?: Pick<SdkMcpToolDefinition, 'annotations' | 'searchHint' | 'alwaysLoad'>): 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(...)] })`.
@@ -41,6 +43,8 @@ export declare class SdkMcpRegistry {
     private readonly reply;
     private readonly transports;
     private readonly pending;
+    private readonly inbound;
+    private fail;
     private constructor();
     /** Connect every server's instance to a control transport. */
     static create(configs: McpSdkServerConfigWithInstance[], reply: (requestId: string, mcpResponse: JSONRPCMessage | undefined) => void): Promise<SdkMcpRegistry>;

package/dist/sdk/mcpServer.js

@@ -2,6 +2,7 @@
 // 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 { randomUUID } from 'node:crypto';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod/v4';
@@ -32,14 +33,20 @@ export function createSdkMcpServer(options) {
             description: t.description,
             inputSchema: z.toJSONSchema(z.object(t.inputSchema)),
             ...(t.annotations ? { annotations: t.annotations } : {}),
+            ...(t.searchHint !== undefined || t.alwaysLoad !== undefined ? {
+                _meta: {
+                    ...(t.searchHint !== undefined ? { 'anthropic/searchHint': t.searchHint } : {}),
+                    ...(t.alwaysLoad !== undefined ? { 'anthropic/alwaysLoad': t.alwaysLoad } : {}),
+                },
+            } : {}),
         })),
     }));
-    server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+    server.setRequestHandler(CallToolRequestSchema, async ({ params }, extra) => {
         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 ?? {}), {});
+        const out = await t.handler((params.arguments ?? {}), extra);
         return toCallToolResult(out);
     });
     return { name: options.name, version: options.version, tools, instance: server };
@@ -80,6 +87,15 @@ export class SdkMcpRegistry {
     reply;
     transports = new Map();
     pending = new Map();
+    inbound = new Map();
+    fail(internalId, message) {
+        const entry = this.pending.get(internalId);
+        if (!entry)
+            return;
+        this.pending.delete(internalId);
+        this.inbound.delete(JSON.stringify([entry.server, entry.originalId]));
+        this.reply(entry.requestId, { jsonrpc: '2.0', id: entry.originalId, error: { code: -32000, message } });
+    }
     constructor(reply) {
         this.reply = reply;
     }
@@ -91,10 +107,11 @@ export class SdkMcpRegistry {
                 continue;
             const transport = new SdkControlServerTransport(message => {
                 const id = messageId(message);
-                if (id !== undefined && reg.pending.has(id)) {
-                    const requestId = reg.pending.get(id);
+                const entry = typeof id === 'string' ? reg.pending.get(id) : undefined;
+                if (entry && entry.server === cfg.name) {
                     reg.pending.delete(id);
-                    reg.reply(requestId, message);
+                    reg.inbound.delete(JSON.stringify([cfg.name, entry.originalId]));
+                    reg.reply(entry.requestId, { ...message, id: entry.originalId });
                 }
             });
             await cfg.instance.connect(transport);
@@ -121,14 +138,39 @@ export class SdkMcpRegistry {
             return;
         }
         const id = messageId(message);
-        if (id !== undefined)
-            this.pending.set(id, requestId);
-        transport.onmessage?.(message);
-        if (id === undefined)
+        if (id !== undefined) {
+            const key = JSON.stringify([serverName, id]);
+            if (this.inbound.has(key)) {
+                this.reply(requestId, { jsonrpc: '2.0', id, error: { code: -32600, message: 'Duplicate active SDK MCP request id' } });
+                return;
+            }
+            // Private transport ids isolate servers, late responses and original id=0 cancellation
+            // (some MCP SDK versions incorrectly treat numeric zero as absent).
+            const internalId = randomUUID();
+            this.inbound.set(key, internalId);
+            this.pending.set(internalId, { requestId, server: serverName, originalId: id });
+            transport.onmessage?.({ ...message, id: internalId });
+        }
+        else {
+            if ('method' in message && message.method === 'notifications/cancelled') {
+                const originalId = message.params?.requestId;
+                const internalId = this.inbound.get(JSON.stringify([serverName, originalId]));
+                if (internalId) {
+                    transport.onmessage?.({ ...message, params: { ...message.params, requestId: internalId } });
+                    // The MCP server suppresses its response after cancellation; release the control waiter.
+                    this.fail(internalId, 'SDK MCP request cancelled; effects may be unknown');
+                }
+            }
+            else
+                transport.onmessage?.(message);
             this.reply(requestId, undefined);
+        }
     }
     async close() {
         for (const t of this.transports.values())
             await t.close();
+        for (const id of this.pending.keys())
+            this.fail(id, 'SDK MCP transport closed; effects may be unknown');
+        this.transports.clear();
     }
 }

package/dist/sdk/operations/command.d.ts

@@ -0,0 +1,24 @@
+import type { JsonValue } from '../commandAdapter.js';
+import { type CommandDefinition } from '../commandAdapter.js';
+import type { OperationAdapter, OperationContext } from './types.js';
+export type DurableCommandAdapterSpec = {
+    adapterId: string;
+    adapterVersion: string;
+    targetIdentity: string;
+    execute: CommandDefinition;
+    query?: CommandDefinition;
+    /** Only these host-declared environment entries may rotate without changing definition identity. */
+    credentialEnv?: readonly string[];
+    credentialRef?: string;
+    verificationRef?: JsonValue;
+    idempotency?: {
+        scope: string;
+        retentionMs: number;
+    };
+    verifyIdentity: (operation: OperationContext, signal: AbortSignal) => Promise<{
+        targetIdentity: string;
+        adapterVersion: string;
+    } | null>;
+};
+/** Register a fixed command with the durable host; credentials are resolved by its trusted resolver. */
+export declare function createDurableCommandAdapter(spec: DurableCommandAdapterSpec): OperationAdapter;

package/dist/sdk/operations/command.js

@@ -0,0 +1,48 @@
+import { createCommandAdapter, restoreCommandOperation } from '../commandAdapter.js';
+import { resolve } from 'node:path';
+import { operationClone, operationDigest, asOperationJson } from './json.js';
+/** Register a fixed command with the durable host; credentials are resolved by its trusted resolver. */
+export function createDurableCommandAdapter(spec) {
+    const credentialEnv = [...new Set(spec.credentialEnv ?? [])].sort();
+    if (credentialEnv.length && !spec.credentialRef)
+        throw new Error('Rotating command credentials require a stable credentialRef');
+    const execute = operationClone({ ...spec.execute, cwd: resolve(spec.execute.cwd ?? process.cwd()), inheritEnv: spec.execute.inheritEnv ?? false });
+    const query = spec.query ? operationClone({ ...spec.query, cwd: resolve(spec.query.cwd ?? process.cwd()), inheritEnv: spec.query.inheritEnv ?? false }) : undefined;
+    const definition = (command) => {
+        if (!command)
+            return null;
+        const env = command.inheritEnv ? { ...process.env, ...command.env } : { ...command.env };
+        return { ...command, env: Object.fromEntries(Object.entries(env).filter(([key]) => !credentialEnv.includes(key))) };
+    };
+    const binding = { adapterId: spec.adapterId, adapterVersion: spec.adapterVersion, targetIdentity: spec.targetIdentity,
+        definitionDigest: operationDigest({ execute: definition(execute), query: definition(query), credentialEnv,
+            credentialRef: spec.credentialRef ?? null, verificationRef: spec.verificationRef ?? null, idempotency: spec.idempotency ?? null }) };
+    const capabilities = { replay: spec.idempotency ? 'idempotent' : 'never', query: !!query,
+        ...(spec.idempotency ? { idempotency: operationClone(spec.idempotency) } : {}) };
+    const verifyIdentity = spec.verifyIdentity;
+    async function invoke(invocation, kind) {
+        const original = invocation.operation;
+        const adapter = createCommandAdapter({ ...binding, execute, query, idempotency: capabilities.idempotency,
+            verifyIdentity: async () => {
+                const identity = await verifyIdentity(original, invocation.signal);
+                return identity?.targetIdentity === binding.targetIdentity && identity?.adapterVersion === binding.adapterVersion;
+            } });
+        const record = { operationId: original.operationId, requestKey: original.requestKey,
+            adapterId: binding.adapterId, adapterVersion: binding.adapterVersion, targetIdentity: binding.targetIdentity,
+            bindingDigest: original.binding.definitionDigest, inputDigest: original.inputDigest, input: original.input, createdAt: original.createdAt };
+        const operation = restoreCommandOperation(adapter, record, invocation.previouslyDispatched || kind === 'query');
+        const execution = kind === 'query'
+            ? await adapter.queryOutcome(operation, { signal: invocation.signal })
+            : invocation.previouslyDispatched
+                ? await adapter.retry(operation, { signal: invocation.signal, authorize: async () => true })
+                : await adapter.execute(operation, { signal: invocation.signal });
+        return { outcome: execution.outcome, result: asOperationJson(execution.outcome),
+            process: execution.process ? asOperationJson(execution.process) : null,
+            ...(execution.process ? { dispatch: execution.process.dispatch } : {}) };
+    }
+    return {
+        binding, capabilities, verifyIdentity,
+        execute: invocation => invoke(invocation, 'execute'),
+        ...(query ? { queryOutcome: (invocation) => invoke(invocation, 'query') } : {}),
+    };
+}

package/dist/sdk/operations/host.d.ts

@@ -0,0 +1,3 @@
+import { type OperationHost, type OperationHostOptions } from './types.js';
+/** Shared lifecycle core for SDK hosts and CCL's CLI/tool entry points. */
+export declare function createOperationHost(options: OperationHostOptions): OperationHost;