@bbigbang/agent-node 0.1.0

package/dist/attachmentMaterializer.js

@@ -0,0 +1,230 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { log } from '@bbigbang/runtime-acp';
+import { buildConversationAssetCacheRoot, resolveScopedAssetCachePath } from './assetCachePaths.js';
+const DEFAULT_ASSET_FETCH_TIMEOUT_MS = 15_000;
+const DEFAULT_ASSET_MATERIALIZE_CONCURRENCY = 3;
+const DEFAULT_ASSET_MATERIALIZE_MAX_BYTES = 16 * 1024 * 1024;
+export class RuntimeAttachmentMaterializer {
+    sessionKey;
+    runtimeLabel;
+    assetAccessConfig;
+    assetCacheRoot;
+    fetchTimeoutMs;
+    maxBytes;
+    isCancelled;
+    onMaterialized;
+    abortControllers = new Set();
+    constructor(options) {
+        this.sessionKey = options.sessionKey;
+        this.runtimeLabel = options.runtimeLabel;
+        this.assetAccessConfig = options.assetAccessConfig;
+        this.assetCacheRoot = options.assetCacheRoot?.trim()
+            || (options.assetAccessConfig
+                ? buildConversationAssetCacheRoot(options.assetAccessConfig.agentId, options.assetAccessConfig.conversationId)
+                : null);
+        this.fetchTimeoutMs = options.fetchTimeoutMs ?? DEFAULT_ASSET_FETCH_TIMEOUT_MS;
+        this.maxBytes = options.maxBytes ?? DEFAULT_ASSET_MATERIALIZE_MAX_BYTES;
+        this.isCancelled = options.isCancelled ?? (() => false);
+        this.onMaterialized = options.onMaterialized;
+    }
+    get cacheRoot() {
+        return this.assetCacheRoot;
+    }
+    abort() {
+        if (this.abortControllers.size === 0)
+            return;
+        const controllers = Array.from(this.abortControllers);
+        this.abortControllers.clear();
+        for (const controller of controllers) {
+            controller.abort(new Error('Asset materialization cancelled'));
+        }
+    }
+    async materialize(attachments, context) {
+        if (!attachments?.length)
+            return [];
+        return mapWithConcurrencyLimit(attachments, DEFAULT_ASSET_MATERIALIZE_CONCURRENCY, (attachment) => this.materializeOne(attachment, context));
+    }
+    async materializeOne(attachment, context) {
+        if (this.isCancelled())
+            return attachment;
+        const assetId = normalizeOptionalString(attachment.assetId) ?? extractAttachmentIdFromUri(attachment.uri);
+        if (!assetId || !this.assetAccessConfig || !this.assetCacheRoot)
+            return attachment;
+        const absoluteTarget = resolveScopedAssetCachePath({
+            cacheRoot: this.assetCacheRoot,
+            preferredLocalPath: normalizeOptionalString(attachment.preferredLocalPath),
+            assetId,
+            filename: attachment.filename,
+        });
+        try {
+            await this.ensureAssetAccessAuthorized(assetId);
+            if (!fs.existsSync(absoluteTarget)) {
+                fs.mkdirSync(path.dirname(absoluteTarget), { recursive: true });
+                await this.fetchAuthorizedAssetToFile(assetId, absoluteTarget);
+            }
+            this.onMaterialized?.({
+                assetId,
+                conversationId: this.assetAccessConfig.conversationId,
+                runId: context?.runId ?? null,
+                localPath: absoluteTarget,
+                materializedAt: Date.now(),
+            });
+            return {
+                ...attachment,
+                uri: pathToFileURL(absoluteTarget).toString(),
+                preferredLocalPath: absoluteTarget,
+            };
+        }
+        catch (error) {
+            log.warn(`[${this.runtimeLabel}] asset materialization failed; falling back to attachment reference`, {
+                sessionKey: this.sessionKey,
+                assetId,
+                conversationId: this.assetAccessConfig.conversationId,
+                error: String(error?.message ?? error),
+                cancelled: this.isCancelled(),
+            });
+            return {
+                ...attachment,
+                preferredLocalPath: undefined,
+            };
+        }
+    }
+    async ensureAssetAccessAuthorized(assetId) {
+        const response = await this.fetchAuthorizedAsset(assetId, { metadataOnly: true });
+        await response.arrayBuffer();
+    }
+    async fetchAuthorizedAsset(assetId, options) {
+        if (!this.assetAccessConfig) {
+            throw new Error('Asset access is unavailable for this runtime.');
+        }
+        if (this.isCancelled()) {
+            throw new Error('Asset materialization cancelled');
+        }
+        const headers = {};
+        if (this.assetAccessConfig.authToken) {
+            headers.Authorization = `Bearer ${this.assetAccessConfig.authToken}`;
+        }
+        const abortController = new AbortController();
+        this.abortControllers.add(abortController);
+        const timeout = setTimeout(() => {
+            abortController.abort(new Error(`Asset materialization timed out after ${this.fetchTimeoutMs}ms`));
+        }, this.fetchTimeoutMs);
+        try {
+            const endpoint = options?.metadataOnly ? 'meta' : '';
+            const suffix = endpoint ? `/${endpoint}` : '';
+            const res = await fetch(`${this.assetAccessConfig.serverUrl}/api/assets/${encodeURIComponent(assetId)}${suffix}?agentId=${encodeURIComponent(this.assetAccessConfig.agentId)}&conversationId=${encodeURIComponent(this.assetAccessConfig.conversationId)}`, { headers, signal: abortController.signal });
+            if (!res.ok) {
+                throw new Error(`Failed to materialize asset ${assetId}: ${res.status}`);
+            }
+            return res;
+        }
+        finally {
+            clearTimeout(timeout);
+            this.abortControllers.delete(abortController);
+        }
+    }
+    async fetchAuthorizedAssetToFile(assetId, absoluteTarget) {
+        if (!this.assetAccessConfig) {
+            throw new Error('Asset access is unavailable for this runtime.');
+        }
+        if (this.isCancelled()) {
+            throw new Error('Asset materialization cancelled');
+        }
+        const headers = {};
+        if (this.assetAccessConfig.authToken) {
+            headers.Authorization = `Bearer ${this.assetAccessConfig.authToken}`;
+        }
+        const abortController = new AbortController();
+        this.abortControllers.add(abortController);
+        const timeout = setTimeout(() => {
+            abortController.abort(new Error(`Asset materialization timed out after ${this.fetchTimeoutMs}ms`));
+        }, this.fetchTimeoutMs);
+        const tempTarget = `${absoluteTarget}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        try {
+            const res = await fetch(`${this.assetAccessConfig.serverUrl}/api/assets/${encodeURIComponent(assetId)}?agentId=${encodeURIComponent(this.assetAccessConfig.agentId)}&conversationId=${encodeURIComponent(this.assetAccessConfig.conversationId)}`, { headers, signal: abortController.signal });
+            if (!res.ok) {
+                throw new Error(`Failed to materialize asset ${assetId}: ${res.status}`);
+            }
+            await writeResponseBodyToFile(res, tempTarget, this.maxBytes, abortController.signal, () => this.isCancelled());
+            if (this.isCancelled()) {
+                throw new Error('Asset materialization cancelled');
+            }
+            fs.renameSync(tempTarget, absoluteTarget);
+        }
+        catch (error) {
+            fs.rmSync(tempTarget, { force: true });
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+            this.abortControllers.delete(abortController);
+        }
+    }
+}
+export function extractAttachmentIdFromUri(uri) {
+    const normalized = normalizeOptionalString(uri);
+    if (!normalized || !normalized.startsWith('attachment:'))
+        return null;
+    return normalizeOptionalString(normalized.slice('attachment:'.length));
+}
+async function mapWithConcurrencyLimit(items, limit, worker) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const runWorker = async () => {
+        while (true) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            if (currentIndex >= items.length)
+                return;
+            results[currentIndex] = await worker(items[currentIndex], currentIndex);
+        }
+    };
+    const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, () => runWorker());
+    await Promise.all(workers);
+    return results;
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim();
+    return normalized ? normalized : null;
+}
+async function writeResponseBodyToFile(response, targetPath, maxBytes, signal, isCancelled) {
+    const contentLength = Number(response.headers.get('content-length') ?? '');
+    if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+        throw new Error(`Asset exceeds materialization limit of ${maxBytes} bytes`);
+    }
+    const body = response.body;
+    if (!body) {
+        const buffer = Buffer.from(await response.arrayBuffer());
+        if (buffer.length > maxBytes) {
+            throw new Error(`Asset exceeds materialization limit of ${maxBytes} bytes`);
+        }
+        fs.writeFileSync(targetPath, buffer);
+        return;
+    }
+    const fd = fs.openSync(targetPath, 'w');
+    let written = 0;
+    try {
+        const reader = body.getReader();
+        while (true) {
+            if (signal.aborted || isCancelled()) {
+                throw signal.reason instanceof Error ? signal.reason : new Error('Asset materialization cancelled');
+            }
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const chunk = Buffer.from(value);
+            written += chunk.length;
+            if (written > maxBytes) {
+                throw new Error(`Asset exceeds materialization limit of ${maxBytes} bytes`);
+            }
+            fs.writeSync(fd, chunk);
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}

package/dist/bigbangCli.js

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function resolveBigbangCliEntry() {
+    try {
+        const req = createRequire(import.meta.url);
+        return req.resolve('@bbigbang/cli');
+    }
+    catch {
+        const fallback = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../packages/bigbang-cli/src/index.ts');
+        return fs.existsSync(fallback) ? fallback : null;
+    }
+}
+export function isBigbangCliAvailable() {
+    return resolveBigbangCliEntry() !== null;
+}

package/dist/bigbangMessageSendDetection.js

@@ -0,0 +1,284 @@
+import { parseBigbangReceipts } from '@bbigbang/agent-command';
+export function getBigbangMessageSendInfo(item) {
+    if (item.type !== 'commandExecution' && item.type !== 'shellToolResult')
+        return null;
+    const command = normalizeOptionalString(item.command);
+    if (!command || !containsBigbangMessageSendInvocation(command))
+        return null;
+    const outputText = [
+        normalizeOptionalString(item.aggregatedOutput ?? undefined),
+        typeof item.output === 'string' ? normalizeOptionalString(item.output) : null,
+        typeof item.result === 'string' ? normalizeOptionalString(item.result) : null,
+    ].filter((value) => Boolean(value)).join('\n');
+    const receipts = parseBigbangReceipts(outputText).filter((receipt) => receipt.op === 'message.send' && receipt.ok === true);
+    const receipt = receipts.at(-1);
+    if (receipt) {
+        return { kind: receipt.kind, success: true };
+    }
+    const legacyMessageSentText = /\bMessage sent to [\s\S]*?\bMessage ID:\s*[^\s.]+/i.test(outputText);
+    const kindMatch = /(?:^|\s)--kind(?:=|\s+)(?:"([^"]+)"|'([^']+)'|([^\s"']+))/i.exec(command);
+    const kind = normalizeOptionalString(kindMatch?.[1] ?? kindMatch?.[2] ?? kindMatch?.[3])?.toLowerCase() ?? null;
+    if (legacyMessageSentText) {
+        return { kind, success: true };
+    }
+    return {
+        kind,
+        success: false,
+        failureKind: classifyBigbangMessageSendFailure(outputText, item),
+    };
+}
+function containsBigbangMessageSendInvocation(command) {
+    if (containsBigbangMessageSendShellPayload(command))
+        return true;
+    const payload = extractShellCommandStringPayload(command);
+    return payload ? containsBigbangMessageSendShellPayload(payload) : false;
+}
+function shellUnquotedTokens(command) {
+    const tokens = [];
+    let current = '';
+    let quote = null;
+    let tokenHasQuotedPart = false;
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index];
+        if (quote) {
+            tokenHasQuotedPart = true;
+            if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            tokenHasQuotedPart = true;
+            continue;
+        }
+        if (/\s|[;&|(){}]/.test(char)) {
+            if (current && !tokenHasQuotedPart)
+                tokens.push(current);
+            current = '';
+            tokenHasQuotedPart = false;
+            continue;
+        }
+        current += char;
+    }
+    if (current && !tokenHasQuotedPart)
+        tokens.push(current);
+    return tokens;
+}
+function extractShellCommandStringPayload(command) {
+    const words = shellWords(command);
+    for (let index = 0; index < words.length; index += 1) {
+        const word = words[index];
+        if (!/^(?:\/(?:usr\/)?bin\/)?(?:ba|z|fi)?sh$/.test(word.text))
+            continue;
+        for (let optionIndex = index + 1; optionIndex < words.length; optionIndex += 1) {
+            const option = words[optionIndex];
+            if (!/^-[A-Za-z]*c[A-Za-z]*$/.test(option.text))
+                continue;
+            return words[optionIndex + 1]?.text ?? null;
+        }
+    }
+    return null;
+}
+function containsBigbangMessageSendShellPayload(payload) {
+    return splitShellCommandSegments(payload)
+        .some((segment) => containsBigbangMessageSendAtCommandHead(segment));
+}
+function containsBigbangMessageSendAtCommandHead(segment) {
+    const tokens = shellUnquotedTokens(segment);
+    let index = 0;
+    while (index < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[index])) {
+        index += 1;
+    }
+    if (tokens[index] === 'command' || tokens[index] === 'exec')
+        index += 1;
+    if (tokens[index] === 'env') {
+        index += 1;
+        while (index < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[index])) {
+            index += 1;
+        }
+    }
+    return tokens[index] === 'bigbang'
+        && tokens[index + 1] === 'message'
+        && tokens[index + 2] === 'send';
+}
+function splitShellCommandSegments(value) {
+    const segments = [];
+    let current = '';
+    let quote = null;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        const next = value[index + 1];
+        if (quote) {
+            current += char;
+            if (char === quote && value[index - 1] !== '\\')
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            current += char;
+            continue;
+        }
+        if (char === ';' || (char === '&' && next === '&') || (char === '|' && next === '|')) {
+            if (current.trim())
+                segments.push(current);
+            current = '';
+            if ((char === '&' && next === '&') || (char === '|' && next === '|'))
+                index += 1;
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim())
+        segments.push(current);
+    return segments;
+}
+function shellWords(command) {
+    const words = [];
+    let current = '';
+    let quote = null;
+    let quoted = false;
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index];
+        if (quote) {
+            if (char === quote && command[index - 1] !== '\\') {
+                quote = null;
+                quoted = true;
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            quoted = true;
+            continue;
+        }
+        if (/\s|[;&|(){}]/.test(char)) {
+            if (current)
+                words.push({ text: current, quoted });
+            current = '';
+            quoted = false;
+            continue;
+        }
+        current += char;
+    }
+    if (current)
+        words.push({ text: current, quoted });
+    return words;
+}
+export function buildBigbangMessageSendRepairGuidance(failureKind) {
+    const header = 'Bigbang message-send failure guidance: do not blindly repeat the previous command.';
+    switch (failureKind) {
+        case 'response_lost':
+            return [
+                header,
+                'The previous `bigbang message send` result was ambiguous, likely a response-lost or transient transport failure without a posted receipt.',
+                'Reuse the original operation id only when rerunning the exact same original message command with identical target, kind, content, and attachments/panels/tools; otherwise it can conflict.',
+                'If you cannot exactly replay the original send, read the latest surface context first, then send a new final message only if one is still needed.',
+            ].join('\n');
+        case 'held_or_stale':
+            return [
+                header,
+                'The previous `bigbang message send` appears held, stale, suppressed, or otherwise non-posted.',
+                'Read the latest surface context or held draft details, revise the content if needed, then send again; do not treat the held draft as visible delivery.',
+            ].join('\n');
+        case 'validation_or_permission':
+            return [
+                header,
+                'The previous `bigbang message send` appears to have a validation, permission, not-found, or target/scope error.',
+                'Do not retry the same payload unchanged. Fix the target, scope, flags, permissions, or payload first, then send once.',
+            ].join('\n');
+        case 'operation_conflict':
+            return [
+                header,
+                'The previous `bigbang message send` hit `CLIENT_MESSAGE_ID_CONFLICT` or an operation-id conflict.',
+                'Do not blindly retry. Reuse that operation id only for the exact same target, kind, content, and attachments/panels/tools; use a new operation id only if you intentionally need to post a different new message.',
+            ].join('\n');
+        case 'panel_version_conflict':
+            return [
+                header,
+                'A related panel mutation appears to have a version conflict.',
+                'Read the latest panel state/events/rows, merge your intended change, and write with the current version; do not replay a stale panel mutation unchanged.',
+            ].join('\n');
+        case 'unknown_failure':
+            return [
+                header,
+                'The previous `bigbang message send` failed or produced no posted receipt, but the runtime could not classify the reason.',
+                'Inspect the command output, read the latest surface context if delivery is uncertain, and only send again when you can avoid duplicate or stale output.',
+            ].join('\n');
+    }
+}
+function classifyBigbangMessageSendFailure(outputText, item) {
+    const text = outputText.toLowerCase();
+    if (text.includes('client_message_id_conflict')
+        || text.includes('clientmessageid conflict')
+        || text.includes('operation-id conflict')
+        || text.includes('operation id conflict')) {
+        return 'operation_conflict';
+    }
+    if (text.includes('panel_version_conflict')
+        || text.includes('version conflict')
+        || text.includes('expected_version')
+        || text.includes('expected version')
+        || (text.includes('panel') && text.includes('conflict'))) {
+        return 'panel_version_conflict';
+    }
+    if (text.includes('draft held')
+        || text.includes('nothing was posted')
+        || text.includes('"held": true')
+        || text.includes('"stale": true')
+        || text.includes('newer messages exist')
+        || text.includes('held draft')
+        || text.includes('suppressed')) {
+        return 'held_or_stale';
+    }
+    if (text.includes('permission')
+        || text.includes('forbidden')
+        || text.includes('unauthorized')
+        || text.includes('not_found')
+        || text.includes('not found')
+        || text.includes('validation')
+        || text.includes('invalid_arg')
+        || text.includes('request_failed')
+        || text.includes('content must not be empty')
+        || text.includes('does not belong')
+        || text.includes('must not')
+        || text.includes('must be')
+        || text.includes('required option')
+        || text.includes('required field')
+        || text.includes('missing required')
+        || text.includes('invalid input')
+        || text.includes('invalid target')
+        || text.includes('unknown target')
+        || text.includes('cannot resolve')
+        || text.includes('400')
+        || text.includes('401')
+        || text.includes('403')
+        || text.includes('404')) {
+        return 'validation_or_permission';
+    }
+    if (text.includes('network_error')
+        || text.includes('network error')
+        || text.includes('server_5xx')
+        || text.includes('request to bigbang core failed')
+        || text.includes('econnreset')
+        || text.includes('econnrefused')
+        || text.includes('etimedout')
+        || text.includes('timed out')
+        || text.includes('502')
+        || text.includes('503')
+        || text.includes('504')) {
+        return 'response_lost';
+    }
+    const status = normalizeOptionalString(item.status)?.toLowerCase();
+    if (status === 'failed' || item.success === false || (typeof item.exitCode === 'number' && item.exitCode !== 0)) {
+        return 'unknown_failure';
+    }
+    return 'unknown_failure';
+}
+function normalizeOptionalString(value) {
+    const trimmed = value?.trim() ?? '';
+    return trimmed ? trimmed : null;
+}

package/dist/builtinSkillRoots.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BUILTIN_LIBRARY_DOCUMENTS_SKILL_ROOT_SENTINEL, BUILTIN_UI_PANEL_SKILL_ROOT_SENTINEL, BUILTIN_WORKSPACE_TOOL_SKILL_ROOT_SENTINEL, } from '@bbigbang/protocol';
+const AGENT_NODE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(AGENT_NODE_DIR, '../../..');
+const BUILTIN_SKILLS_ROOT = path.join(REPO_ROOT, 'skills');
+const BUILTIN_SKILL_LINK_ROOT = path.join(os.tmpdir(), 'bigbang-builtin-skill-roots');
+const BUILTIN_SKILL_SENTINELS = new Map([
+    [BUILTIN_WORKSPACE_TOOL_SKILL_ROOT_SENTINEL, 'workspace-tool-builder'],
+    [BUILTIN_UI_PANEL_SKILL_ROOT_SENTINEL, 'ui-panel'],
+    [BUILTIN_LIBRARY_DOCUMENTS_SKILL_ROOT_SENTINEL, 'library-documents'],
+]);
+export function expandSkillRoot(value) {
+    const trimmed = value.trim();
+    const builtinSkillName = BUILTIN_SKILL_SENTINELS.get(trimmed);
+    if (builtinSkillName) {
+        return ensureBuiltinSkillRoot(builtinSkillName);
+    }
+    return path.resolve(trimmed);
+}
+export function normalizeSkillRootsWithBuiltins(skillRoots) {
+    return skillRoots
+        .map((value) => value.trim())
+        .filter(Boolean)
+        .map((value) => expandSkillRoot(value))
+        .filter((value, index, list) => list.indexOf(value) === index);
+}
+function ensureBuiltinSkillRoot(skillName) {
+    const sourcePath = path.join(BUILTIN_SKILLS_ROOT, skillName);
+    const skillFile = path.join(sourcePath, 'SKILL.md');
+    if (!(fs.statSync(skillFile, { throwIfNoEntry: false })?.isFile() ?? false)) {
+        throw new Error(`Built-in ${skillName} skill is missing on agent-node: ${skillFile}`);
+    }
+    const rootPath = path.join(BUILTIN_SKILL_LINK_ROOT, skillName);
+    const linkPath = path.join(rootPath, skillName);
+    fs.mkdirSync(rootPath, { recursive: true });
+    const existing = fs.lstatSync(linkPath, { throwIfNoEntry: false });
+    if (existing) {
+        if (existing.isSymbolicLink()) {
+            const currentTarget = fs.readlinkSync(linkPath);
+            const resolvedTarget = path.resolve(rootPath, currentTarget);
+            if (resolvedTarget === sourcePath)
+                return rootPath;
+            fs.unlinkSync(linkPath);
+        }
+        else {
+            throw new Error(`Built-in ${skillName} skill link path is occupied: ${linkPath}`);
+        }
+    }
+    fs.symlinkSync(sourcePath, linkPath, 'dir');
+    return rootPath;
+}

package/dist/claudeConfig.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const CLAUDE_RUNTIME_DIRNAME = '.claude-runtime';
+export function getIsolatedClaudeConfigDir(workspaceRoot) {
+    return path.join(path.resolve(workspaceRoot), CLAUDE_RUNTIME_DIRNAME);
+}
+export function getIsolatedClaudeStatePath(workspaceRoot) {
+    return `${getIsolatedClaudeConfigDir(workspaceRoot)}.json`;
+}
+export function ensureIsolatedClaudeConfig(workspaceRoot) {
+    const configDir = getIsolatedClaudeConfigDir(workspaceRoot);
+    const statePath = getIsolatedClaudeStatePath(workspaceRoot);
+    fs.mkdirSync(configDir, { recursive: true });
+    writeJsonIfChanged(path.join(configDir, 'settings.json'), {});
+    writeJsonIfChanged(path.join(configDir, 'settings.local.json'), {});
+    writeJsonIfChanged(statePath, {});
+    // Keep Claude auth working without inheriting the user's full runtime config.
+    const defaultCredentialsPath = path.join(os.homedir(), '.claude', '.credentials.json');
+    const isolatedCredentialsPath = path.join(configDir, '.credentials.json');
+    if (!fs.existsSync(isolatedCredentialsPath) && fs.existsSync(defaultCredentialsPath)) {
+        fs.copyFileSync(defaultCredentialsPath, isolatedCredentialsPath);
+    }
+    return configDir;
+}
+function writeJsonIfChanged(filePath, value) {
+    const next = `${JSON.stringify(value, null, 2)}\n`;
+    const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+    if (current === next)
+        return;
+    fs.writeFileSync(filePath, next, 'utf8');
+}