@bbigbang/core 0.1.0

package/dist/services/workspaceToolExecutionUtils.js

@@ -0,0 +1,895 @@
+import path from 'node:path';
+import { WorkspaceToolServiceError } from './workspaceToolErrors.js';
+const ONE_SHOT_POLL_INTERVAL_MS = 250;
+const ONE_SHOT_TIMEOUT_MS = 120_000;
+const WORKSPACE_TOOL_RUN_EVENT_PAYLOAD_MAX_CHARS = 16_000;
+const WORKSPACE_TOOL_RUN_ARTIFACT_MAX_COUNT = 50;
+const WORKSPACE_TOOL_RUN_ARTIFACT_PATH_MAX_CHARS = 1_000;
+const WORKSPACE_TOOL_RUN_ARTIFACTS_MAX_CHARS = 16_000;
+const WORKSPACE_TOOL_RUN_EVENT_BASE64_MIN_CHARS = 2048;
+const WORKSPACE_TOOL_RUN_EVENT_BASE64_PLACEHOLDER = '[omitted base64 data]';
+const WORKSPACE_TOOL_RUN_EVENT_BASE64_FRAGMENT_PATTERN = new RegExp(`[A-Za-z0-9+/]{${WORKSPACE_TOOL_RUN_EVENT_BASE64_MIN_CHARS},}={0,2}`, 'g');
+const WORKSPACE_TOOL_RUN_EVENT_WRAPPED_BASE64_FRAGMENT_PATTERN = /(^|[^A-Za-z0-9+/])((?:[A-Za-z0-9+/]{64,}(?:(?:\\r|\\n|\\t|[\r\n\t ])+)){1,}[A-Za-z0-9+/]{64,}={0,2})(?=$|[^A-Za-z0-9+/=])/g;
+export const CLI_STOP_CLEANUP_TIMEOUT_MS = 5_000;
+const WORKSPACE_TOOL_RUN_EVENT_TYPES = new Set([
+    'log',
+    'progress',
+    'result',
+    'error',
+    'artifact',
+]);
+export function getPublishedWorkspaceToolBundleRoot(toolId, revision) {
+    return path.posix.join('.workspace-tool-published', toolId, `r${revision}`);
+}
+function normalizeWorkspaceToolMediaRelativePath(rawPath) {
+    const trimmed = rawPath.trim();
+    if (/^data:/i.test(trimmed) || /;base64,/i.test(trimmed))
+        return null;
+    const compact = trimmed.replace(/\s+/g, '');
+    if (compact.length >= WORKSPACE_TOOL_RUN_EVENT_BASE64_MIN_CHARS
+        && compact.length % 4 === 0
+        && /^[A-Za-z0-9+/]+={0,2}$/.test(compact)) {
+        return null;
+    }
+    const normalized = path.posix.normalize(trimmed.replace(/\\/g, '/'));
+    if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../') || path.posix.isAbsolute(normalized)) {
+        return null;
+    }
+    return normalized;
+}
+export function getWorkspaceToolMediaRelativePathCandidates(tool, rawPath, options) {
+    const normalized = normalizeWorkspaceToolMediaRelativePath(rawPath);
+    if (!normalized)
+        return [];
+    const sourceBundleRoot = normalizeWorkspaceToolMediaRelativePath(tool.sourceBundleRoot);
+    const publishedBundleRoot = getPublishedWorkspaceToolBundleRoot(tool.toolId, tool.revision);
+    const candidates = [];
+    const push = (candidate) => {
+        const normalizedValue = normalizeWorkspaceToolMediaRelativePath(candidate.relativePath);
+        if (!normalizedValue)
+            return;
+        if (candidates.some((existing) => existing.relativePath === normalizedValue))
+            return;
+        candidates.push({ ...candidate, relativePath: normalizedValue });
+    };
+    if (normalized === publishedBundleRoot || normalized.startsWith(`${publishedBundleRoot}/`)) {
+        push({
+            relativePath: normalized,
+            allowedRelativeRoot: publishedBundleRoot,
+            source: 'published',
+        });
+    }
+    else if (sourceBundleRoot && (normalized === sourceBundleRoot || normalized.startsWith(`${sourceBundleRoot}/`))) {
+        const suffix = normalized.slice(sourceBundleRoot.length).replace(/^\/+/, '');
+        push({
+            relativePath: suffix ? path.posix.join(publishedBundleRoot, suffix) : publishedBundleRoot,
+            allowedRelativeRoot: publishedBundleRoot,
+            source: 'published',
+        });
+    }
+    else {
+        push({
+            relativePath: path.posix.join(publishedBundleRoot, normalized),
+            allowedRelativeRoot: publishedBundleRoot,
+            source: 'published',
+        });
+    }
+    if (options?.includeWorkspaceFallback) {
+        push({ relativePath: normalized, source: 'workspace_fallback' });
+    }
+    return candidates;
+}
+export function runRowToInfo(row, actionKind) {
+    return {
+        runId: row.runId,
+        toolId: row.toolId,
+        toolRevision: row.toolRevision ?? null,
+        actionId: row.actionId,
+        actionKind,
+        terminalId: row.terminalId ?? null,
+        status: row.status,
+        params: parseJsonRecord(row.paramsJson),
+        exitCode: row.exitCode ?? null,
+        signal: row.signal ?? null,
+        startedAt: row.startedAt,
+        endedAt: row.endedAt ?? null,
+        requestedByUserId: row.requestedByUserId ?? null,
+        requestedByUsername: row.requestedByUsername ?? null,
+        requestedByAgentId: row.requestedByAgentId ?? null,
+        requestedByAgentName: row.requestedByAgentName ?? null,
+        executionTargetKind: row.executionTargetKind ?? null,
+        executionAgentId: row.executionAgentId ?? null,
+        executionNodeId: row.executionNodeId ?? null,
+        executionHostname: row.executionHostname ?? null,
+        executionWorkspacePath: row.executionWorkspacePath ?? null,
+    };
+}
+export function runEventRowToInfo(row) {
+    return {
+        eventId: row.eventId,
+        runId: row.runId,
+        toolId: row.toolId,
+        sequence: row.sequence,
+        type: row.eventType,
+        level: row.level ?? null,
+        summary: row.summary ?? null,
+        payload: parseJsonRecord(row.payloadJson),
+        artifacts: parseWorkspaceToolRunArtifactRefs(row.artifactsJson),
+        createdAt: row.createdAt,
+    };
+}
+export function validateManifestConsistency(workspaceRoot, manifestPath, manifest) {
+    const expected = `.agent-tools/${manifest.slug}/tool.json`;
+    if (manifestPath !== expected) {
+        throw new WorkspaceToolServiceError(`Manifest path must be ${expected}.`, 400);
+    }
+    normalizeWorkspaceRelativePath(workspaceRoot, manifestPath);
+}
+export function validateManifestCwds(workspaceRoot, manifest, sourceBundleRoot) {
+    if (manifest.defaultCwd) {
+        resolveToolPath(workspaceRoot, manifest.defaultCwd);
+    }
+    if (manifest.env?.cwd) {
+        resolveToolPath(workspaceRoot, manifest.env.cwd);
+    }
+    if (manifest.cli?.entry) {
+        resolveToolBundlePath(workspaceRoot, sourceBundleRoot, manifest.cli.entry, 'Tool CLI entry');
+    }
+    if (manifest.runtime?.entry) {
+        resolveToolBundlePath(workspaceRoot, sourceBundleRoot, manifest.runtime.entry, 'Tool runtime entry');
+    }
+    if (manifest.runtime?.logDir) {
+        normalizeWorkspaceRelativePath(workspaceRoot, manifest.runtime.logDir);
+    }
+    for (const action of manifest.actions) {
+        if (action.cwd) {
+            resolveToolPath(workspaceRoot, action.cwd);
+        }
+    }
+}
+export function resolveToolBundlePath(workspaceRoot, bundleRoot, candidate, label) {
+    const trimmed = candidate.trim();
+    if (!trimmed || path.isAbsolute(trimmed)) {
+        throw new WorkspaceToolServiceError(`${label} must stay inside the tool bundle.`, 400);
+    }
+    const bundleAbsolutePath = resolveToolPath(workspaceRoot, bundleRoot);
+    const absolutePath = path.resolve(bundleAbsolutePath, trimmed);
+    const relativePath = path.relative(bundleAbsolutePath, absolutePath);
+    if (relativePath === '..' || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
+        throw new WorkspaceToolServiceError(`${label} must stay inside the tool bundle.`, 400);
+    }
+    return absolutePath;
+}
+export function normalizeWorkspaceRelativePath(workspaceRoot, requestedPath) {
+    const normalized = requestedPath.trim();
+    if (!normalized) {
+        throw new WorkspaceToolServiceError('manifest_path is required.', 400);
+    }
+    const absolutePath = resolveToolPath(workspaceRoot, normalized);
+    const relativePath = path.relative(workspaceRoot, absolutePath).replace(/\\/g, '/');
+    if (!relativePath || relativePath.startsWith('../') || relativePath === '..') {
+        throw new WorkspaceToolServiceError('Tool path must remain inside the agent workspace.', 400);
+    }
+    return { absolutePath, relativePath };
+}
+export function resolveToolPath(workspaceRoot, candidate) {
+    const absolutePath = path.isAbsolute(candidate)
+        ? path.normalize(candidate)
+        : path.resolve(workspaceRoot, candidate);
+    const relativePath = path.relative(workspaceRoot, absolutePath);
+    if (relativePath === '..' || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
+        throw new WorkspaceToolServiceError('Tool path must remain inside the agent workspace.', 400);
+    }
+    return absolutePath;
+}
+export function resolveToolCwd(workspaceRoot, manifest, action, sourceBundleRoot, publishedBundleRoot) {
+    const requested = action.cwd?.trim() || manifest.env?.cwd?.trim() || manifest.defaultCwd?.trim() || publishedBundleRoot;
+    return rewriteWorkspaceToolPathToPublished(workspaceRoot, requested, sourceBundleRoot, publishedBundleRoot);
+}
+export function buildWorkspaceToolStartupCommand(params) {
+    const command = params.action.command?.trim()
+        ? substituteCommand(params.action.command, params.actionParams)
+        : buildWorkspaceToolCliCommand(params.manifest, params.action, params.actionParams, {
+            workspaceRoot: params.workspaceRoot,
+            publishedBundleRoot: params.publishedBundleRoot,
+        });
+    return applyWorkspaceToolExecutionEnv(command, params.manifest.env);
+}
+export function buildWorkspaceToolRuntimeCommand(params) {
+    const entry = params.manifest.runtime?.entry?.trim() || params.manifest.cli?.entry?.trim();
+    if (!entry)
+        return '';
+    const executable = resolveToolBundlePath(params.workspaceRoot, params.publishedBundleRoot, entry, 'Tool runtime entry');
+    const command = [
+        shellEscape(executable),
+        'runtime',
+        '--tool-id',
+        shellEscape(params.toolId),
+        '--revision',
+        shellEscape(params.revision),
+        '--log-dir',
+        shellEscape(resolveToolPath(params.workspaceRoot, params.logDir)),
+    ].join(' ');
+    return applyWorkspaceToolExecutionEnv(command, params.manifest.env);
+}
+function buildWorkspaceToolCliCommand(manifest, action, actionParams, paths) {
+    const entry = manifest.cli?.entry?.trim();
+    if (!entry)
+        return '';
+    const subcommand = workspaceToolCliSubcommandForAction(action);
+    const executable = resolveToolBundlePath(paths.workspaceRoot, paths.publishedBundleRoot, entry, 'Tool CLI entry');
+    return [
+        shellEscape(executable),
+        ...subcommand.map((part) => shellEscape(part)),
+        '--action-id',
+        shellEscape(action.actionId),
+        '--params-json',
+        shellEscape(JSON.stringify(actionParams)),
+    ].join(' ');
+}
+function workspaceToolCliSubcommandForAction(action) {
+    if (action.kind === 'start')
+        return ['start'];
+    if (action.kind === 'restart')
+        return ['start'];
+    if (action.kind === 'status')
+        return ['status'];
+    if (action.kind === 'stop')
+        return ['stop'];
+    return ['action', action.actionId];
+}
+function applyWorkspaceToolExecutionEnv(command, env) {
+    const trimmedCommand = command.trim();
+    if (!trimmedCommand || !env)
+        return trimmedCommand;
+    const envAssignments = Object.entries(env.vars ?? {})
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `${key}=${shellEscape(value)}`);
+    const prefix = envAssignments.join(' ');
+    if (env.condaEnv) {
+        return [
+            prefix,
+            `conda run -n ${shellEscape(env.condaEnv)} --no-capture-output sh -lc ${shellEscape(trimmedCommand)}`,
+        ].filter(Boolean).join(' ');
+    }
+    if (prefix) {
+        return `${prefix} sh -lc ${shellEscape(trimmedCommand)}`;
+    }
+    return trimmedCommand;
+}
+export function rewriteWorkspaceToolCommandPaths(workspaceRoot, command, sourceBundleRoot, publishedBundleRoot) {
+    if (!command.trim())
+        return command;
+    if (!sourceBundleRoot.trim())
+        return command;
+    const replacements = [
+        [sourceBundleRoot, publishedBundleRoot],
+        [resolveToolPath(workspaceRoot, sourceBundleRoot), resolveToolPath(workspaceRoot, publishedBundleRoot)],
+    ];
+    return replacements.reduce((current, [from, to]) => replaceAll(current, from, to), command);
+}
+function rewriteWorkspaceToolPathToPublished(workspaceRoot, candidate, sourceBundleRoot, publishedBundleRoot) {
+    if (!sourceBundleRoot.trim()) {
+        return resolveToolPath(workspaceRoot, candidate);
+    }
+    const publishedBundleAbsolutePath = resolveToolPath(workspaceRoot, publishedBundleRoot);
+    const sourceBundleAbsolutePath = resolveToolPath(workspaceRoot, sourceBundleRoot);
+    const candidateAbsolutePath = resolveToolPath(workspaceRoot, candidate);
+    const candidateRelativeToSource = path.relative(sourceBundleAbsolutePath, candidateAbsolutePath);
+    if (candidateRelativeToSource
+        && candidateRelativeToSource !== '..'
+        && !candidateRelativeToSource.startsWith(`..${path.sep}`)) {
+        return path.join(publishedBundleAbsolutePath, candidateRelativeToSource);
+    }
+    if (candidateAbsolutePath === sourceBundleAbsolutePath) {
+        return publishedBundleAbsolutePath;
+    }
+    return candidateAbsolutePath;
+}
+function replaceAll(input, from, to) {
+    return input.split(from).join(to);
+}
+export function formatBoundedJsonPreview(value, limit) {
+    const text = JSON.stringify(value, null, 2);
+    return truncateText(text, limit);
+}
+export function formatBoundedTextPreview(value, limit) {
+    const text = value?.trim();
+    if (!text)
+        return null;
+    return truncateText(scrubWorkspaceToolInlineBinaryText(text), limit);
+}
+function truncateText(value, limit) {
+    if (value.length <= limit)
+        return value;
+    return `${value.slice(0, Math.max(0, limit - 3))}...`;
+}
+export function normalizeActionParams(action, inputParams) {
+    const fields = action.paramsSchema ?? [];
+    const next = {};
+    for (const field of fields) {
+        const rawValue = Object.prototype.hasOwnProperty.call(inputParams, field.name)
+            ? inputParams[field.name]
+            : field.defaultValue;
+        const input = field.input ?? 'text';
+        if (field.required && isMissingWorkspaceToolParamValue(rawValue, input)) {
+            throw new WorkspaceToolServiceError(`Parameter "${field.name}" is required.`, 400);
+        }
+        if (rawValue === undefined)
+            continue;
+        if (input === 'number' && rawValue !== null && rawValue !== '') {
+            const numeric = typeof rawValue === 'number' ? rawValue : Number(rawValue);
+            if (!Number.isFinite(numeric)) {
+                throw new WorkspaceToolServiceError(`Parameter "${field.name}" must be a number.`, 400);
+            }
+            if (typeof field.min === 'number' && numeric < field.min) {
+                throw new WorkspaceToolServiceError(`Parameter "${field.name}" must be at least ${field.min}.`, 400);
+            }
+            if (typeof field.max === 'number' && numeric > field.max) {
+                throw new WorkspaceToolServiceError(`Parameter "${field.name}" must be at most ${field.max}.`, 400);
+            }
+            next[field.name] = numeric;
+            continue;
+        }
+        if (input === 'checkbox') {
+            next[field.name] = rawValue === true || rawValue === 'true' || rawValue === 1;
+            continue;
+        }
+        if (input === 'select') {
+            if (rawValue === null || rawValue === '')
+                continue;
+            const textValue = String(rawValue);
+            if (field.options?.length && !field.options.some((option) => option.value === textValue)) {
+                throw new WorkspaceToolServiceError(`Parameter "${field.name}" has an invalid value.`, 400);
+            }
+            next[field.name] = textValue;
+            continue;
+        }
+        if (input === 'multiselect') {
+            if (rawValue === null || rawValue === '')
+                continue;
+            if (!Array.isArray(rawValue)) {
+                throw new WorkspaceToolServiceError(`Parameter "${field.name}" must be an array.`, 400);
+            }
+            const values = normalizeStringArrayParam(field.name, rawValue);
+            const validOptions = new Set((field.options ?? []).map((option) => option.value));
+            if (validOptions.size > 0 && values.some((value) => !validOptions.has(value))) {
+                throw new WorkspaceToolServiceError(`Parameter "${field.name}" has an invalid value.`, 400);
+            }
+            next[field.name] = values;
+            continue;
+        }
+        if (input === 'tags') {
+            if (rawValue === null || rawValue === '')
+                continue;
+            next[field.name] = normalizeTagParam(field.name, rawValue);
+            continue;
+        }
+        if (input === 'date') {
+            if (rawValue === null || rawValue === '')
+                continue;
+            if (typeof rawValue !== 'string' || !isValidWorkspaceToolDateParam(rawValue)) {
+                throw new WorkspaceToolServiceError(`Parameter "${field.name}" must be a YYYY-MM-DD date.`, 400);
+            }
+            if (typeof field.min === 'string' && rawValue < field.min) {
+                throw new WorkspaceToolServiceError(`Parameter "${field.name}" must be on or after ${field.min}.`, 400);
+            }
+            if (typeof field.max === 'string' && rawValue > field.max) {
+                throw new WorkspaceToolServiceError(`Parameter "${field.name}" must be on or before ${field.max}.`, 400);
+            }
+            next[field.name] = rawValue;
+            continue;
+        }
+        if (input === 'file') {
+            if (rawValue === null || rawValue === '')
+                continue;
+            if (field.multiple === true) {
+                if (!Array.isArray(rawValue)) {
+                    throw new WorkspaceToolServiceError(`Parameter "${field.name}" must be an array of uploaded file refs.`, 400);
+                }
+                next[field.name] = rawValue.map((item) => normalizeUploadedFileRefParam(field.name, item, field.maxBytes));
+            }
+            else {
+                if (Array.isArray(rawValue)) {
+                    throw new WorkspaceToolServiceError(`Parameter "${field.name}" must be a single uploaded file ref.`, 400);
+                }
+                next[field.name] = normalizeUploadedFileRefParam(field.name, rawValue, field.maxBytes);
+            }
+            continue;
+        }
+        if (input === 'textarea') {
+            if (rawValue === null || rawValue === '')
+                continue;
+            if (typeof rawValue !== 'string') {
+                throw new WorkspaceToolServiceError(`Parameter "${field.name}" must be a string.`, 400);
+            }
+            next[field.name] = rawValue;
+            continue;
+        }
+        next[field.name] = rawValue;
+    }
+    return next;
+}
+function isMissingWorkspaceToolParamValue(value, input) {
+    if (value === undefined || value === null || value === '')
+        return true;
+    if ((input === 'multiselect' || input === 'tags') && Array.isArray(value) && value.length === 0)
+        return true;
+    if (input === 'file' && Array.isArray(value) && value.length === 0)
+        return true;
+    return false;
+}
+function normalizeUploadedFileRefParam(fieldName, value, maxBytes) {
+    if (!isPlainRecord(value)) {
+        throw new WorkspaceToolServiceError(`Parameter "${fieldName}" must be an uploaded file ref.`, 400);
+    }
+    const assetId = normalizeUploadedAssetId(value.assetId)
+        ?? normalizeUploadedAssetId(value.attachmentId)
+        ?? normalizeUploadedAssetId(extractAttachmentIdFromUri(value.uri));
+    if (!assetId) {
+        throw new WorkspaceToolServiceError(`Parameter "${fieldName}" must reference an uploaded asset.`, 400);
+    }
+    const filename = typeof value.filename === 'string' && value.filename.trim()
+        ? value.filename.trim()
+        : 'upload.bin';
+    const sizeBytes = typeof value.sizeBytes === 'number' && Number.isFinite(value.sizeBytes) && value.sizeBytes >= 0
+        ? Math.floor(value.sizeBytes)
+        : undefined;
+    if (maxBytes !== undefined && sizeBytes !== undefined && sizeBytes > maxBytes) {
+        throw new WorkspaceToolServiceError(`Parameter "${fieldName}" file exceeds ${maxBytes} bytes.`, 400);
+    }
+    return {
+        assetId,
+        attachmentId: assetId,
+        uri: `attachment:${assetId}`,
+        filename,
+        ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+        ...(typeof value.kind === 'string' ? { kind: value.kind } : {}),
+        ...(typeof value.scopeType === 'string' ? { scopeType: value.scopeType } : {}),
+        ...(typeof value.scopeId === 'string' ? { scopeId: value.scopeId } : {}),
+    };
+}
+function normalizeUploadedAssetId(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim();
+    return /^[a-f0-9-]{36}$/i.test(normalized) ? normalized.toLowerCase() : null;
+}
+function extractAttachmentIdFromUri(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim();
+    if (!normalized.startsWith('attachment:'))
+        return null;
+    return normalized.slice('attachment:'.length).trim();
+}
+function normalizeStringArrayParam(fieldName, value) {
+    const result = [];
+    const seen = new Set();
+    for (const item of value) {
+        if (typeof item !== 'string') {
+            throw new WorkspaceToolServiceError(`Parameter "${fieldName}" must contain only strings.`, 400);
+        }
+        if (seen.has(item))
+            continue;
+        seen.add(item);
+        result.push(item);
+    }
+    return result;
+}
+function normalizeTagParam(fieldName, value) {
+    const rawItems = Array.isArray(value)
+        ? value
+        : typeof value === 'string'
+            ? value.split(/[,\n]/u)
+            : [];
+    if (!Array.isArray(value) && typeof value !== 'string') {
+        throw new WorkspaceToolServiceError(`Parameter "${fieldName}" must be a string or string array.`, 400);
+    }
+    const result = [];
+    const seen = new Set();
+    for (const item of rawItems) {
+        if (typeof item !== 'string') {
+            throw new WorkspaceToolServiceError(`Parameter "${fieldName}" must contain only strings.`, 400);
+        }
+        const tag = item.trim();
+        if (!tag || seen.has(tag))
+            continue;
+        seen.add(tag);
+        result.push(tag);
+    }
+    return result;
+}
+function isValidWorkspaceToolDateParam(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const [year, month, day] = value.split('-').map(Number);
+    if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day))
+        return false;
+    const parsed = new Date(Date.UTC(year, month - 1, day));
+    return parsed.getUTCFullYear() === year
+        && parsed.getUTCMonth() === month - 1
+        && parsed.getUTCDate() === day;
+}
+function substituteCommand(command, params) {
+    return command.replace(/\{\{\s*([a-zA-Z0-9_-]+)\s*\}\}/g, (_match, name) => shellEscape(params[name]));
+}
+export function shellEscape(value) {
+    if (value === undefined || value === null)
+        return "''";
+    const text = typeof value === 'string'
+        ? value
+        : typeof value === 'number' || typeof value === 'boolean'
+            ? String(value)
+            : JSON.stringify(value);
+    return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+export function parseStateRowJson(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return normalizeStateRow(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+export function extractWorkspaceToolBusinessStatus(state) {
+    const value = state?.fields?.status;
+    return typeof value === 'string' && value.trim()
+        ? value.trim().toLowerCase()
+        : null;
+}
+export function parseStateRowFromOutput(raw, strict) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        if (strict) {
+            throw new WorkspaceToolServiceError('Status action returned empty output.', 400);
+        }
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (isJsonlEventEnvelope(parsed)) {
+            return parseStateRowFromJsonlEvent(parsed);
+        }
+        return normalizeStateRow(parsed, { rejectUnsupportedMediaKinds: true });
+    }
+    catch (error) {
+        if (error instanceof WorkspaceToolServiceError) {
+            throw error;
+        }
+        const eventState = parseStateRowFromJsonlOutput(trimmed);
+        if (eventState)
+            return eventState;
+        if (strict) {
+            throw new WorkspaceToolServiceError('Status action output must be a single JSON object.', 400);
+        }
+        return null;
+    }
+}
+export function parseStateRowFromJsonlOutput(raw) {
+    let latestState = null;
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const candidate = parseStateRowFromJsonlEvent(parsed);
+        if (candidate)
+            latestState = candidate;
+    }
+    return latestState;
+}
+export function parseStateRowFromJsonlEvent(value) {
+    if (!isPlainRecord(value))
+        return null;
+    const eventType = typeof value.type === 'string' ? value.type.trim() : '';
+    if (eventType !== 'state')
+        return null;
+    if (isPlainRecord(value.state)) {
+        return normalizeStateRow(value.state, { rejectUnsupportedMediaKinds: true });
+    }
+    return normalizeStateRow(value, { rejectUnsupportedMediaKinds: true });
+}
+export function isJsonlEventEnvelope(value) {
+    return isPlainRecord(value) && typeof value.type === 'string';
+}
+export function normalizeWorkspaceToolRunEventEnvelope(value) {
+    if (!isJsonlEventEnvelope(value))
+        return null;
+    const eventType = value.type.trim();
+    if (!WORKSPACE_TOOL_RUN_EVENT_TYPES.has(eventType))
+        return null;
+    const artifacts = normalizeWorkspaceToolRunArtifacts(value);
+    const artifactsJson = serializeBoundedRunEventArtifacts(artifacts);
+    const summary = typeof value.summary === 'string' && value.summary.trim()
+        ? scrubWorkspaceToolInlineBinaryText(value.summary.trim()).slice(0, 1000)
+        : null;
+    return {
+        eventType,
+        level: typeof value.level === 'string' && value.level.trim() ? value.level.trim().slice(0, 64) : null,
+        summary,
+        payloadJson: serializeBoundedRunEventPayload(value, artifacts),
+        artifactsJson,
+    };
+}
+function normalizeWorkspaceToolRunArtifacts(value) {
+    const rawArtifacts = Array.isArray(value.artifacts)
+        ? value.artifacts
+        : value.type === 'artifact' && typeof value.path === 'string'
+            ? [value]
+            : [];
+    const artifacts = [];
+    for (const raw of rawArtifacts) {
+        if (artifacts.length >= WORKSPACE_TOOL_RUN_ARTIFACT_MAX_COUNT)
+            break;
+        if (!isPlainRecord(raw) || typeof raw.path !== 'string')
+            continue;
+        const normalizedPath = normalizeWorkspaceToolMediaRelativePath(raw.path);
+        if (!normalizedPath)
+            continue;
+        if (normalizedPath.length > WORKSPACE_TOOL_RUN_ARTIFACT_PATH_MAX_CHARS)
+            continue;
+        artifacts.push({
+            path: normalizedPath,
+            label: typeof raw.label === 'string' && raw.label.trim() ? raw.label.trim().slice(0, 200) : undefined,
+            mimeType: typeof raw.mimeType === 'string' && raw.mimeType.trim() ? raw.mimeType.trim().slice(0, 200) : undefined,
+            sizeBytes: typeof raw.sizeBytes === 'number' && Number.isFinite(raw.sizeBytes) && raw.sizeBytes >= 0
+                ? Math.floor(raw.sizeBytes)
+                : undefined,
+        });
+    }
+    return artifacts;
+}
+function serializeBoundedRunEventArtifacts(artifacts) {
+    if (artifacts.length === 0)
+        return null;
+    const bounded = [];
+    for (const artifact of artifacts) {
+        const next = [...bounded, artifact];
+        const serialized = JSON.stringify(next);
+        if (serialized.length > WORKSPACE_TOOL_RUN_ARTIFACTS_MAX_CHARS)
+            break;
+        bounded.push(artifact);
+    }
+    return bounded.length > 0 ? JSON.stringify(bounded) : null;
+}
+function serializeBoundedRunEventPayload(value, artifacts) {
+    const payloadSource = { ...value };
+    delete payloadSource.artifacts;
+    if (value.type === 'artifact') {
+        delete payloadSource.path;
+        delete payloadSource.label;
+        delete payloadSource.mimeType;
+        delete payloadSource.sizeBytes;
+    }
+    if (artifacts.length > 0) {
+        payloadSource.artifacts = artifacts;
+    }
+    const payload = scrubInlineBinaryPayload(stripUndefinedValues(payloadSource));
+    const serialized = JSON.stringify(payload);
+    if (!serialized)
+        return null;
+    if (serialized.length <= WORKSPACE_TOOL_RUN_EVENT_PAYLOAD_MAX_CHARS)
+        return serialized;
+    return JSON.stringify({
+        type: value.type,
+        level: typeof value.level === 'string' ? value.level : undefined,
+        summary: typeof value.summary === 'string' ? scrubWorkspaceToolInlineBinaryText(value.summary) : undefined,
+        truncated: true,
+        preview: scrubInlineBinaryString(serialized.slice(0, WORKSPACE_TOOL_RUN_EVENT_PAYLOAD_MAX_CHARS)),
+    });
+}
+export function scrubWorkspaceToolInlineBinaryText(value) {
+    return scrubInlineBinaryString(value);
+}
+function scrubInlineBinaryPayload(value) {
+    if (typeof value === 'string')
+        return scrubInlineBinaryString(value);
+    if (Array.isArray(value))
+        return value.map((item) => scrubInlineBinaryPayload(item));
+    if (!isPlainRecord(value))
+        return value;
+    const result = {};
+    for (const [key, raw] of Object.entries(value)) {
+        result[key] = scrubInlineBinaryPayload(raw);
+    }
+    return result;
+}
+function scrubInlineBinaryString(value) {
+    let scrubbed = value.replace(/data:[^,;]+(?:;[^,;]+)*;base64,[a-z0-9+/=\r\n]+/gi, WORKSPACE_TOOL_RUN_EVENT_BASE64_PLACEHOLDER);
+    scrubbed = scrubbed.replace(WORKSPACE_TOOL_RUN_EVENT_WRAPPED_BASE64_FRAGMENT_PATTERN, (match, prefix, candidate) => {
+        const compact = compactBase64Candidate(String(candidate));
+        return compact.length >= WORKSPACE_TOOL_RUN_EVENT_BASE64_MIN_CHARS
+            && compact.length % 4 === 0
+            && /^[A-Za-z0-9+/]+={0,2}$/.test(compact)
+            ? `${prefix}${WORKSPACE_TOOL_RUN_EVENT_BASE64_PLACEHOLDER}`
+            : match;
+    });
+    scrubbed = scrubbed.replace(WORKSPACE_TOOL_RUN_EVENT_BASE64_FRAGMENT_PATTERN, (match) => {
+        const compact = compactBase64Candidate(match);
+        return compact.length >= WORKSPACE_TOOL_RUN_EVENT_BASE64_MIN_CHARS
+            && compact.length % 4 === 0
+            && /^[A-Za-z0-9+/]+={0,2}$/.test(compact)
+            ? WORKSPACE_TOOL_RUN_EVENT_BASE64_PLACEHOLDER
+            : match;
+    });
+    if (scrubbed !== value)
+        return scrubbed;
+    const compact = compactBase64Candidate(value);
+    if (compact.length >= WORKSPACE_TOOL_RUN_EVENT_BASE64_MIN_CHARS
+        && compact.length % 4 === 0
+        && /^[A-Za-z0-9+/]+={0,2}$/.test(compact)) {
+        return WORKSPACE_TOOL_RUN_EVENT_BASE64_PLACEHOLDER;
+    }
+    return value;
+}
+function compactBase64Candidate(value) {
+    return value.replace(/(?:\\r|\\n|\\t|\s+)/g, '');
+}
+function stripUndefinedValues(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => stripUndefinedValues(item));
+    }
+    if (!isPlainRecord(value))
+        return value;
+    const result = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (raw === undefined)
+            continue;
+        result[key] = stripUndefinedValues(raw);
+    }
+    return result;
+}
+export function parseWorkspaceToolRunArtifactRefs(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return null;
+        return parsed.filter((item) => isPlainRecord(item) && typeof item.path === 'string');
+    }
+    catch {
+        return null;
+    }
+}
+export function normalizeStateRow(value, options) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const rawFields = isPlainRecord(record.fields) ? record.fields : record;
+    const rawMedia = isPlainRecord(record.media) ? record.media : {};
+    const media = {};
+    for (const [slot, raw] of Object.entries(rawMedia)) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const item = raw;
+        if (options?.rejectUnsupportedMediaKinds && item.kind !== 'workspace_path') {
+            throw new WorkspaceToolServiceError(`Tool state media slot "${slot}" must use kind "workspace_path".`, 400);
+        }
+        if (item.kind === 'workspace_path' && typeof item.value === 'string') {
+            media[slot] = { kind: item.kind, value: item.value };
+        }
+    }
+    return {
+        fields: { ...rawFields },
+        media,
+    };
+}
+export function validateStateRowForManifest(manifest, state) {
+    for (const [slotName, media] of Object.entries(state.media ?? {})) {
+        if (media.kind !== 'workspace_path') {
+            throw new WorkspaceToolServiceError(`Tool state media slot "${slotName}" must use kind "workspace_path".`, 400);
+        }
+        if (path.isAbsolute(media.value)) {
+            throw new WorkspaceToolServiceError(`Tool state media slot "${slotName}" must stay inside the agent workspace.`, 400);
+        }
+    }
+    const declaredSlots = new Map((manifest.view.mediaSlots ?? []).map((slot) => [slot.name, slot.kind]));
+    for (const [slotName, media] of Object.entries(state.media ?? {})) {
+        const expectedKind = declaredSlots.get(slotName);
+        if (!expectedKind)
+            continue;
+        if (media.kind !== expectedKind) {
+            throw new WorkspaceToolServiceError(`Tool state media slot "${slotName}" must use kind "${expectedKind}".`, 400);
+        }
+    }
+}
+export function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function serializeJson(value) {
+    if (value == null)
+        return null;
+    return JSON.stringify(value);
+}
+export function isWorkspaceFileNotFoundError(error) {
+    const message = String(error?.message ?? error).toLowerCase();
+    return message.startsWith('not_found:');
+}
+export function parseJsonRecord(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return isPlainRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function buildDeletedWorkspaceToolSlug(toolId, slug) {
+    return `__deleted__/${toolId}/${slug}`;
+}
+export async function waitForTerminalExit(terminalBroker, nodeId, terminalId, options) {
+    const deadline = Date.now() + (options?.timeoutMs ?? ONE_SHOT_TIMEOUT_MS);
+    while (Date.now() < deadline) {
+        const snapshot = await terminalBroker.snapshotTerminal(nodeId, terminalId);
+        options?.onSnapshot?.(snapshot);
+        if (snapshot.terminal.exited) {
+            return snapshot;
+        }
+        await sleep(ONE_SHOT_POLL_INTERVAL_MS);
+    }
+    throw new WorkspaceToolServiceError(options?.timeoutMessage ?? 'Timed out waiting for tool action to finish.', 504);
+}
+export function deriveTerminalRunCompletion(source) {
+    switch (source.kind) {
+        case 'result_event':
+            return { status: 'completed', exitCode: 0, signal: null };
+        case 'error_event':
+            return { status: 'failed', exitCode: source.exitCode ?? null, signal: source.signal ?? null };
+        case 'timeout':
+            return { status: 'timed_out', exitCode: null, signal: 'timeout' };
+        case 'missing_terminal':
+            return { status: 'failed', exitCode: null, signal: 'missing_terminal' };
+        case 'cancelled':
+            return { status: 'cancelled', exitCode: source.exitCode ?? null, signal: source.signal ?? null };
+        case 'terminal_exit': {
+            const signal = normalizeTerminalExitSignal(source.signal);
+            const explicitExitCode = source.exitCode ?? null;
+            const exitCode = explicitExitCode ?? (signal == null && !source.disposed ? 0 : null);
+            if (signal) {
+                return { status: 'cancelled', exitCode, signal };
+            }
+            if (source.disposed && explicitExitCode == null) {
+                return { status: 'cancelled', exitCode: null, signal: null };
+            }
+            return { status: exitCode === 0 ? 'completed' : 'failed', exitCode, signal: null };
+        }
+    }
+}
+export function deriveOneShotRunCompletion(snapshot) {
+    return deriveTerminalRunCompletion({
+        kind: 'terminal_exit',
+        exitCode: snapshot.terminal.exitCode,
+        signal: snapshot.terminal.signal,
+        disposed: false,
+    });
+}
+function normalizeTerminalExitSignal(signal) {
+    if (signal == null || signal === '0') {
+        return null;
+    }
+    return signal;
+}
+export async function closeTerminalBestEffort(terminalBroker, nodeId, terminalId) {
+    try {
+        await terminalBroker.closeTerminal(nodeId, terminalId);
+    }
+    catch {
+        // The terminal may already be gone. Cleanup is best-effort.
+    }
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}