clinkx 0.2.0 → 0.2.1

package/clinkx-workflows/dist/artifacts.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Artifact storage and ordered context threading.
+ */
+import type { NormalizedWorkflowDefinition, NormalizedStage, NormalizedCall } from "./definition-normalizer.js";
+import type { PromptBudgetContributor } from "./prompt-budget.js";
+import type { ValidatorRegistry } from "./validators/index.js";
+export interface ValidatedJsonOutput {
+    readonly parsed: unknown;
+    readonly serialized: string;
+    readonly sizeBytes: number;
+}
+export interface ArtifactRecord {
+    readonly stageId: string;
+    readonly callId: string;
+    readonly reference: string;
+    readonly filePath: string;
+    readonly filename: string;
+    readonly sizeBytes: number;
+    readonly parsed: unknown;
+}
+export interface OmittedArtifactRecord {
+    readonly stageId: string;
+    readonly callId: string;
+    readonly reference: string;
+    readonly reason: string;
+}
+export interface ContextArtifacts {
+    readonly absoluteFilePaths: readonly string[];
+    readonly context: string | undefined;
+    readonly contributors: readonly PromptBudgetContributor[];
+    readonly artifacts: readonly ArtifactRecord[];
+    readonly omissions: readonly OmittedArtifactRecord[];
+}
+/**
+ * Recursively strip keys ending in `_id` from a parsed JSON structure
+ * to prevent identity leakage in anonymized context.
+ * Objects: strip `_id` keys, recurse into remaining values.
+ * Arrays: recurse into each element.
+ * Primitives: return as-is.
+ */
+export declare function stripIdentityFields(parsed: unknown): unknown;
+export declare class ArtifactStore {
+    private readonly runDir;
+    private readonly validatorRegistry;
+    private readonly artifactRoot;
+    private readonly artifactsByReference;
+    private readonly omissionsByReference;
+    constructor(runDir: string, validatorRegistry: ValidatorRegistry);
+    get artifactsDir(): string;
+    validateJsonOutput(stageId: string, callId: string, validatorSchemaId: string, outputText: string): ValidatedJsonOutput;
+    writeCallArtifact(options: {
+        readonly stage: NormalizedStage;
+        readonly call: NormalizedCall;
+        readonly stageIndex: number;
+        readonly callIndex: number;
+        readonly validated: ValidatedJsonOutput;
+    }): ArtifactRecord;
+    writeStageAggregate(stage: NormalizedStage, stageIndex: number): string | undefined;
+    noteFailedCall(stageId: string, callId: string, reason: string): void;
+    seedArtifact(record: ArtifactRecord): void;
+    seedFailedCall(stageId: string, callId: string, reason: string): void;
+    buildContext(definition: NormalizedWorkflowDefinition, refs: readonly string[] | undefined): ContextArtifacts;
+    buildAnonymizedContext(definition: NormalizedWorkflowDefinition, refs: readonly string[] | undefined, rotationIndex?: number): ContextArtifacts;
+    private collectReference;
+}

package/clinkx-workflows/dist/artifacts.js

@@ -0,0 +1,268 @@
+/**
+ * Artifact storage and ordered context threading.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { WorkflowError } from "./errors.js";
+import { renderContextSummary } from "./template.js";
+import { createPathContributor } from "./prompt-budget.js";
+/**
+ * Recursively strip keys ending in `_id` from a parsed JSON structure
+ * to prevent identity leakage in anonymized context.
+ * Objects: strip `_id` keys, recurse into remaining values.
+ * Arrays: recurse into each element.
+ * Primitives: return as-is.
+ */
+export function stripIdentityFields(parsed) {
+    if (parsed == null || typeof parsed !== "object") {
+        return parsed;
+    }
+    if (Array.isArray(parsed)) {
+        return parsed.map((element) => stripIdentityFields(element));
+    }
+    const obj = parsed;
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        if (!key.endsWith("_id")) {
+            result[key] = stripIdentityFields(obj[key]);
+        }
+    }
+    return result;
+}
+export class ArtifactStore {
+    runDir;
+    validatorRegistry;
+    artifactRoot;
+    artifactsByReference = new Map();
+    omissionsByReference = new Map();
+    constructor(runDir, validatorRegistry) {
+        this.runDir = runDir;
+        this.validatorRegistry = validatorRegistry;
+        this.artifactRoot = join(runDir, "artifacts");
+        mkdirSync(this.artifactRoot, { recursive: true });
+    }
+    get artifactsDir() {
+        return this.artifactRoot;
+    }
+    validateJsonOutput(stageId, callId, validatorSchemaId, outputText) {
+        let parsed;
+        try {
+            parsed = JSON.parse(outputText);
+        }
+        catch (error) {
+            throw new WorkflowError(`Invalid JSON output for ${stageId}.${callId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const validator = this.validatorRegistry.get(validatorSchemaId);
+        if (validator == null) {
+            throw new WorkflowError(`Unknown validator schema "${validatorSchemaId}" for ${stageId}.${callId}`);
+        }
+        const result = validator.schema.safeParse(parsed);
+        if (!result.success) {
+            throw new WorkflowError(`Validation failed for ${stageId}.${callId} against ${validatorSchemaId}: ` +
+                result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "));
+        }
+        const serialized = `${JSON.stringify(result.data, null, 2)}\n`;
+        const sizeBytes = Buffer.byteLength(serialized, "utf-8");
+        if (validator.maxBytes != null && sizeBytes > validator.maxBytes) {
+            throw new WorkflowError(`Validated output for ${stageId}.${callId} exceeds ${String(validator.maxBytes)} bytes ` +
+                `(got ${String(sizeBytes)} bytes)`);
+        }
+        return { parsed: result.data, serialized, sizeBytes };
+    }
+    writeCallArtifact(options) {
+        const stageDir = join(this.artifactRoot, options.stage.id);
+        mkdirSync(stageDir, { recursive: true });
+        const filename = `${ordinal(options.callIndex + 1)}-${options.call.id}.json`;
+        const filePath = join(stageDir, filename);
+        writeFileSync(filePath, options.validated.serialized, "utf-8");
+        const record = {
+            stageId: options.stage.id,
+            callId: options.call.id,
+            reference: `${options.stage.id}.${options.call.id}`,
+            filePath,
+            filename,
+            sizeBytes: options.validated.sizeBytes,
+            parsed: options.validated.parsed,
+        };
+        this.artifactsByReference.set(record.reference, record);
+        return record;
+    }
+    writeStageAggregate(stage, stageIndex) {
+        const stageArtifacts = stage.calls
+            .map((call) => this.artifactsByReference.get(`${stage.id}.${call.id}`))
+            .filter((artifact) => artifact != null);
+        if (stageArtifacts.length === 0) {
+            return undefined;
+        }
+        const aggregatePath = join(this.artifactRoot, `${ordinal(stageIndex + 1)}-${stage.id}.json`);
+        const payload = {
+            stage_id: stage.id,
+            artifacts: stageArtifacts.map((artifact) => ({
+                call_id: artifact.callId,
+                file: artifact.filename,
+                output: artifact.parsed,
+            })),
+        };
+        writeFileSync(aggregatePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+        return aggregatePath;
+    }
+    noteFailedCall(stageId, callId, reason) {
+        const reference = `${stageId}.${callId}`;
+        this.omissionsByReference.set(reference, {
+            stageId,
+            callId,
+            reference,
+            reason,
+        });
+    }
+    seedArtifact(record) {
+        this.artifactsByReference.set(record.reference, record);
+    }
+    seedFailedCall(stageId, callId, reason) {
+        this.noteFailedCall(stageId, callId, reason);
+    }
+    buildContext(definition, refs) {
+        if (refs == null || refs.length === 0) {
+            return {
+                absoluteFilePaths: [],
+                context: undefined,
+                contributors: [],
+                artifacts: [],
+                omissions: [],
+            };
+        }
+        const artifacts = [];
+        const omissions = [];
+        const seenArtifacts = new Set();
+        const seenOmissions = new Set();
+        const perStage = new Map();
+        for (const ref of refs) {
+            const dot = ref.indexOf(".");
+            if (dot === -1) {
+                const stage = definition.stages.find((candidate) => candidate.id === ref);
+                if (stage == null) {
+                    throw new WorkflowError(`Unknown stage reference "${ref}" while building context`);
+                }
+                for (const call of stage.calls) {
+                    this.collectReference(`${stage.id}.${call.id}`, artifacts, omissions, seenArtifacts, seenOmissions);
+                }
+            }
+            else {
+                this.collectReference(ref, artifacts, omissions, seenArtifacts, seenOmissions);
+            }
+        }
+        for (const artifact of artifacts) {
+            const group = perStage.get(artifact.stageId) ?? [];
+            group.push(artifact);
+            perStage.set(artifact.stageId, group);
+        }
+        const summaryParts = [];
+        for (const [stageId, stageArtifacts] of perStage) {
+            summaryParts.push(renderContextSummary(stageId, stageArtifacts.map((artifact) => ({
+                filename: artifact.filename,
+                sizeBytes: artifact.sizeBytes,
+            }))));
+        }
+        if (omissions.length > 0) {
+            summaryParts.push(`Omitted failed outputs: ${omissions.map((omission) => omission.reference).join(", ")}.`);
+        }
+        return {
+            absoluteFilePaths: artifacts.map((artifact) => artifact.filePath),
+            context: summaryParts.length > 0 ? summaryParts.join(" ") : undefined,
+            contributors: artifacts.map((artifact) => createPathContributor(`context_from:${artifact.reference}`, artifact.filePath, "context")),
+            artifacts,
+            omissions,
+        };
+    }
+    buildAnonymizedContext(definition, refs, rotationIndex = 0) {
+        const base = this.buildContext(definition, refs);
+        if (base.artifacts.length === 0) {
+            return base;
+        }
+        if (base.artifacts.length > 26) {
+            throw new WorkflowError("Anonymous aliasing supports at most 26 artifacts (A-Z)");
+        }
+        const anonDir = join(this.artifactRoot, "anonymous");
+        mkdirSync(anonDir, { recursive: true });
+        const aliasedArtifacts = [];
+        const aliasedPaths = [];
+        const perStage = new Map();
+        for (let i = 0; i < base.artifacts.length; i++) {
+            const artifact = base.artifacts[i];
+            const letter = String.fromCharCode(65 + (i % 26));
+            const aliasFilename = `${letter}.json`;
+            const aliasPath = join(anonDir, aliasFilename);
+            const content = JSON.stringify(stripIdentityFields(artifact.parsed), null, 2) + "\n";
+            writeFileSync(aliasPath, content, "utf-8");
+            aliasedPaths.push(aliasPath);
+            aliasedArtifacts.push({
+                ...artifact,
+                filePath: aliasPath,
+                filename: aliasFilename,
+            });
+            const group = perStage.get(artifact.stageId) ?? [];
+            group.push({ filename: aliasFilename, sizeBytes: artifact.sizeBytes });
+            perStage.set(artifact.stageId, group);
+        }
+        // Rotate file presentation order to mitigate position bias across reviewers.
+        // The alias→candidate mapping is stable; only the order changes.
+        const effectiveRotation = aliasedPaths.length > 0
+            ? ((rotationIndex % aliasedPaths.length) + aliasedPaths.length) % aliasedPaths.length
+            : 0;
+        const rotatedPaths = effectiveRotation === 0
+            ? aliasedPaths
+            : [...aliasedPaths.slice(effectiveRotation), ...aliasedPaths.slice(0, effectiveRotation)];
+        // Build summary text in rotated order so the text matches rotatedPaths.
+        const rotatedArtifacts = effectiveRotation === 0
+            ? aliasedArtifacts
+            : [...aliasedArtifacts.slice(effectiveRotation), ...aliasedArtifacts.slice(0, effectiveRotation)];
+        const rotatedPerStage = new Map();
+        for (const artifact of rotatedArtifacts) {
+            const group = rotatedPerStage.get(artifact.stageId) ?? [];
+            group.push({ filename: artifact.filename, sizeBytes: artifact.sizeBytes });
+            rotatedPerStage.set(artifact.stageId, group);
+        }
+        const summaryParts = [];
+        for (const [stageId, stageArtifacts] of rotatedPerStage) {
+            const fileList = stageArtifacts
+                .map((a) => {
+                const letter = a.filename.replace(".json", "");
+                const sizeKb = Math.ceil(a.sizeBytes / 1024);
+                return `Answer ${letter} (${String(sizeKb)}KB)`;
+            })
+                .join(", ");
+            summaryParts.push(`Stage ${stageId} outputs: ${fileList}. ` +
+                "Read these files to synthesize your response.");
+        }
+        if (base.omissions.length > 0) {
+            const anonymizedOmissions = base.omissions.map((_o, idx) => `omitted_${idx + 1}`);
+            summaryParts.push(`Omitted failed outputs: ${anonymizedOmissions.join(", ")}.`);
+        }
+        return {
+            absoluteFilePaths: rotatedPaths,
+            context: summaryParts.length > 0 ? summaryParts.join(" ") : undefined,
+            contributors: aliasedArtifacts.map((artifact, index) => createPathContributor(`context_from:answer_${String.fromCharCode(65 + index)}`, artifact.filePath, "context")),
+            artifacts: aliasedArtifacts,
+            omissions: base.omissions,
+        };
+    }
+    collectReference(reference, artifacts, omissions, seenArtifacts, seenOmissions) {
+        const artifact = this.artifactsByReference.get(reference);
+        if (artifact != null) {
+            if (!seenArtifacts.has(reference)) {
+                artifacts.push(artifact);
+                seenArtifacts.add(reference);
+            }
+            return;
+        }
+        const omission = this.omissionsByReference.get(reference);
+        if (omission != null && !seenOmissions.has(reference)) {
+            omissions.push(omission);
+            seenOmissions.add(reference);
+        }
+    }
+}
+function ordinal(value) {
+    return String(value).padStart(2, "0");
+}
+//# sourceMappingURL=artifacts.js.map

package/clinkx-workflows/dist/artifacts.js.map

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

package/clinkx-workflows/dist/backend.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Backend abstraction for the workflow engine.
+ *
+ * Allows the engine to call clink either via:
+ * - Child process MCP transport (ClinkSession — existing)
+ * - In-process direct call (LocalClinkBackend — new)
+ */
+export interface ToolCallResult {
+    readonly content: ReadonlyArray<{
+        readonly type: string;
+        readonly text?: string | undefined;
+    }>;
+    readonly isError?: boolean | undefined;
+}
+export interface ClinkBackend {
+    /** Advertised cli_name values. */
+    readonly cliNames: string[];
+    /** Advertised role values. */
+    readonly roleNames: string[];
+    /** Whether the backend has been terminated. */
+    readonly isTerminated: boolean;
+    /** Whether the backend's child process died unexpectedly (only relevant for child-process backends). */
+    readonly hasChildDied: boolean;
+    /** Initialize the backend (connect to child, etc). No-op for in-process backends. */
+    connect(): Promise<void>;
+    /** Call the clink tool. */
+    callTool(args: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<ToolCallResult>;
+    /** Shut down the backend. */
+    terminate(): Promise<void>;
+}

package/clinkx-workflows/dist/backend.js

@@ -0,0 +1,9 @@
+/**
+ * Backend abstraction for the workflow engine.
+ *
+ * Allows the engine to call clink either via:
+ * - Child process MCP transport (ClinkSession — existing)
+ * - In-process direct call (LocalClinkBackend — new)
+ */
+export {};
+//# sourceMappingURL=backend.js.map

package/clinkx-workflows/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/clinkx-workflows/dist/child-env.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Child environment builder for clinkx-workflows.
+ *
+ * Builds a sanitized environment for the ClinkX child process:
+ * 1. Start with process.env (inherit parent env)
+ * 2. Scrub ALL CLINKX_* vars and config-discovery vars (XDG_CONFIG_HOME)
+ * 3. Re-inject ONLY explicit workflow-owned controls from config
+ *
+ * Baseline OS env (PATH, HOME, USER, LANG, TMPDIR) is NEVER scrubbed.
+ * Dead knobs (CLINKX_TIMEOUT_SECONDS, CLINKX_IDLE_TIMEOUT_*) are NEVER set.
+ */
+export interface ChildEnvOverrides {
+    readonly allowedRoots: string;
+    readonly configPath?: string | undefined;
+    readonly logLevel?: string | undefined;
+}
+/**
+ * Build a sanitized environment for the ClinkX child process.
+ *
+ * @param overrides - Runtime overrides (allowedRoots is required)
+ * @returns A clean env record suitable for child_process.spawn
+ */
+export declare function buildChildEnv(overrides: ChildEnvOverrides): Record<string, string>;

package/clinkx-workflows/dist/child-env.js

@@ -0,0 +1,53 @@
+/**
+ * Child environment builder for clinkx-workflows.
+ *
+ * Builds a sanitized environment for the ClinkX child process:
+ * 1. Start with process.env (inherit parent env)
+ * 2. Scrub ALL CLINKX_* vars and config-discovery vars (XDG_CONFIG_HOME)
+ * 3. Re-inject ONLY explicit workflow-owned controls from config
+ *
+ * Baseline OS env (PATH, HOME, USER, LANG, TMPDIR) is NEVER scrubbed.
+ * Dead knobs (CLINKX_TIMEOUT_SECONDS, CLINKX_IDLE_TIMEOUT_*) are NEVER set.
+ */
+import { CHILD_ENV_SCRUB_PREFIX, CHILD_ENV_SCRUB_EXTRA, DEAD_KNOBS, getChildMaxConcurrent, getChildMaxResponseChars, getChildMaxOutputBytes, getChildMaxPromptBytes, getChildConfigPath, getLogLevel, } from "./config.js";
+/**
+ * Build a sanitized environment for the ClinkX child process.
+ *
+ * @param overrides - Runtime overrides (allowedRoots is required)
+ * @returns A clean env record suitable for child_process.spawn
+ */
+export function buildChildEnv(overrides) {
+    const env = {};
+    const deadKnobSet = new Set(DEAD_KNOBS);
+    const scrubExtra = new Set(CHILD_ENV_SCRUB_EXTRA);
+    // Step 1: Copy parent env, scrubbing CLINKX_* and config-discovery vars
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value == null)
+            continue;
+        // Scrub all CLINKX_* vars
+        if (key.startsWith(CHILD_ENV_SCRUB_PREFIX))
+            continue;
+        // Scrub config-discovery vars
+        if (scrubExtra.has(key))
+            continue;
+        env[key] = value;
+    }
+    // Step 2: Re-inject workflow-owned controls (never dead knobs)
+    env["CLINKX_MAX_CONCURRENT"] = String(getChildMaxConcurrent());
+    env["CLINKX_MAX_RESPONSE_CHARS"] = String(getChildMaxResponseChars());
+    env["CLINKX_MAX_OUTPUT_BYTES"] = String(getChildMaxOutputBytes());
+    env["CLINKX_MAX_PROMPT_BYTES"] = String(getChildMaxPromptBytes());
+    env["CLINKX_ALLOWED_ROOTS"] = overrides.allowedRoots;
+    env["CLINKX_LOG_LEVEL"] = overrides.logLevel ?? getLogLevel();
+    // Optional: workflow-owned config path
+    const configPath = overrides.configPath ?? getChildConfigPath();
+    if (configPath != null) {
+        env["CLINKX_CONFIG_PATH"] = configPath;
+    }
+    // Safety: ensure dead knobs are never present
+    for (const knob of deadKnobSet) {
+        delete env[knob];
+    }
+    return env;
+}
+//# sourceMappingURL=child-env.js.map

package/clinkx-workflows/dist/child-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-env.js","sourceRoot":"","sources":["../src/child-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,UAAU,EACV,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EAClB,WAAW,GACZ,MAAM,aAAa,CAAC;AAQrB;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,SAA4B;IACxD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAS,UAAU,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,qBAAqB,CAAC,CAAC;IAE1D,wEAAwE;IACxE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,IAAI,KAAK,IAAI,IAAI;YAAE,SAAS;QAE5B,0BAA0B;QAC1B,IAAI,GAAG,CAAC,UAAU,CAAC,sBAAsB,CAAC;YAAE,SAAS;QAErD,8BAA8B;QAC9B,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAElC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACnB,CAAC;IAED,+DAA+D;IAC/D,GAAG,CAAC,uBAAuB,CAAC,GAAG,MAAM,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAC/D,GAAG,CAAC,2BAA2B,CAAC,GAAG,MAAM,CAAC,wBAAwB,EAAE,CAAC,CAAC;IACtE,GAAG,CAAC,yBAAyB,CAAC,GAAG,MAAM,CAAC,sBAAsB,EAAE,CAAC,CAAC;IAClE,GAAG,CAAC,yBAAyB,CAAC,GAAG,MAAM,CAAC,sBAAsB,EAAE,CAAC,CAAC;IAClE,GAAG,CAAC,sBAAsB,CAAC,GAAG,SAAS,CAAC,YAAY,CAAC;IACrD,GAAG,CAAC,kBAAkB,CAAC,GAAG,SAAS,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC;IAE9D,uCAAuC;IACvC,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,IAAI,kBAAkB,EAAE,CAAC;IAChE,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;QACvB,GAAG,CAAC,oBAAoB,CAAC,GAAG,UAAU,CAAC;IACzC,CAAC;IAED,8CAA8C;IAC9C,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/clinkx-workflows/dist/clink-client.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Clink client wrapper for clinkx-workflows.
+ *
+ * Provides callClink() — the typed interface for calling the child's
+ * clink tool and parsing its response into output_text + debug_metadata.
+ *
+ * Key behaviors:
+ * - Always sets debug: true on internal calls
+ * - Parses MCP text content blocks robustly (no positional assumptions)
+ * - Strips host _meta.progressToken from child calls (progress isolation)
+ * - Maps child -32602 to InvalidCallError
+ * - Maps child isError: true to CallExecutionError
+ * - Only output_text is stored/threaded/hashed
+ */
+import type { ClinkBackend, ToolCallResult } from "./backend.js";
+/** Parsed result from a clink call. */
+export interface ClinkCallResult {
+    /** Primary output text (for storage/threading/hashing). */
+    readonly outputText: string;
+    /** Optional _debug metadata block (parsed JSON, or null). */
+    readonly debugMetadata: Record<string, unknown> | null;
+}
+/**
+ * Build the tool arguments for a child clink call.
+ *
+ * Ensures debug: true is always set and strips any _meta.progressToken
+ * to prevent child from emitting progress to the host.
+ */
+export declare function buildCallArgs(input: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Parse the MCP tool call result into output_text and debug_metadata.
+ *
+ * Does NOT assume positional ordering — scans all text content blocks
+ * and identifies the _debug block by JSON-parsing each one.
+ */
+export declare function parseCallResult(result: ToolCallResult): ClinkCallResult;
+/**
+ * Call the child's clink tool and return parsed output.
+ *
+ * @param session - Active ClinkBackend
+ * @param input - Tool input arguments (ClinkInput shape)
+ * @param signal - Optional AbortSignal for cancellation
+ * @param context - Stage/call context for error attribution
+ * @returns Parsed clink call result
+ * @throws InvalidCallError on child -32602
+ * @throws CallExecutionError on child isError: true
+ */
+export declare function callClink(session: ClinkBackend, input: Record<string, unknown>, signal?: AbortSignal, context?: {
+    stageId: string;
+    callId: string;
+}, timeoutMs?: number): Promise<ClinkCallResult>;