@abot-ai/runtime 1.0.0

package/dist/src/runtime/attachments/store.js

@@ -0,0 +1,169 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { normalizeRuntimeAttachmentMimeType, resolveRuntimeAttachmentMimeType, } from "../../shared/attachments.js";
+export const DEFAULT_MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+const ATTACHMENT_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+const SAFE_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertSafeOwnerSegment(value) {
+    if (!SAFE_SEGMENT_PATTERN.test(value) ||
+        value === "." ||
+        value === "..") {
+        throw new Error("attachment_owner_invalid");
+    }
+}
+export function parseRuntimeAttachmentReferences(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("attachments_must_be_array");
+    }
+    return value.map((entry) => {
+        if (!isRecord(entry)) {
+            throw new Error("attachment_must_be_object");
+        }
+        if (typeof entry.id !== "string" ||
+            typeof entry.mimeType !== "string" ||
+            typeof entry.storageRef !== "string") {
+            throw new Error("attachment_reference_invalid");
+        }
+        if ("data" in entry || "base64" in entry || "content" in entry) {
+            throw new Error("attachment_inline_payload_unsupported");
+        }
+        if (entry.kind !== "image" && entry.kind !== "file") {
+            throw new Error("attachment_kind_unsupported");
+        }
+        const mimeType = normalizeRuntimeAttachmentMimeType(entry.mimeType);
+        const supported = resolveRuntimeAttachmentMimeType(mimeType);
+        if (!supported || supported.kind !== entry.kind) {
+            throw new Error("attachment_mime_unsupported");
+        }
+        return {
+            id: entry.id,
+            kind: entry.kind,
+            mimeType,
+            storageRef: entry.storageRef,
+            ...(typeof entry.name === "string" ? { name: entry.name } : {}),
+            ...(typeof entry.size === "number" ? { size: entry.size } : {}),
+        };
+    });
+}
+export function createFileAttachmentStore(options) {
+    const rootDir = resolve(options.attachmentsDir);
+    const maxAttachmentBytes = options.maxAttachmentBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES;
+    const assertSupported = (attachment) => {
+        if (!ATTACHMENT_ID_PATTERN.test(attachment.id)) {
+            throw new Error("attachment_id_invalid");
+        }
+        const supported = resolveRuntimeAttachmentMimeType(attachment.mimeType);
+        if (!supported || supported.kind !== attachment.kind) {
+            throw new Error("attachment_mime_unsupported");
+        }
+        if (attachment.size !== undefined &&
+            (!Number.isFinite(attachment.size) ||
+                attachment.size < 0 ||
+                attachment.size > maxAttachmentBytes)) {
+            throw new Error("attachment_size_invalid");
+        }
+    };
+    const resolveStorageRefPath = (storageRef) => {
+        if (!storageRef ||
+            storageRef.startsWith("/") ||
+            storageRef.includes("\0")) {
+            throw new Error("attachment_storage_ref_invalid");
+        }
+        const absolutePath = resolve(rootDir, storageRef);
+        const relativePath = relative(rootDir, absolutePath);
+        if (relativePath.startsWith("..") || relativePath === "") {
+            throw new Error("attachment_storage_ref_outside_root");
+        }
+        return { absolutePath, relativePath };
+    };
+    const resolveStorageRef = (storageRef) => {
+        return resolveStorageRefPath(storageRef).absolutePath;
+    };
+    const assertStorageRefOwner = (attachment, sessionId) => {
+        if (!sessionId) {
+            return;
+        }
+        assertSafeOwnerSegment(sessionId);
+        const { relativePath } = resolveStorageRefPath(attachment.storageRef);
+        const [owner] = relativePath.split(/[\\/]/u);
+        if (owner !== sessionId) {
+            throw new Error("attachment_session_mismatch");
+        }
+    };
+    const normalizeReference = async (attachment, options = {}) => {
+        assertSupported(attachment);
+        const mimeType = normalizeRuntimeAttachmentMimeType(attachment.mimeType);
+        assertStorageRefOwner(attachment, options.sessionId);
+        const absolutePath = resolveStorageRef(attachment.storageRef);
+        const fileStat = await stat(absolutePath);
+        if (!fileStat.isFile()) {
+            throw new Error("attachment_storage_ref_not_file");
+        }
+        if (fileStat.size > maxAttachmentBytes) {
+            throw new Error("attachment_size_exceeded");
+        }
+        return {
+            id: attachment.id,
+            kind: attachment.kind,
+            mimeType,
+            storageRef: attachment.storageRef,
+            ...(attachment.name ? { name: attachment.name } : {}),
+            size: attachment.size ?? fileStat.size,
+        };
+    };
+    return {
+        async saveAttachment(input) {
+            const mimeType = normalizeRuntimeAttachmentMimeType(input.mimeType);
+            const supported = resolveRuntimeAttachmentMimeType(mimeType);
+            if (!supported || supported.kind !== input.kind) {
+                throw new Error("attachment_type_unsupported");
+            }
+            if (input.bytes.byteLength > maxAttachmentBytes) {
+                throw new Error("attachment_size_exceeded");
+            }
+            assertSafeOwnerSegment(input.sessionId);
+            assertSafeOwnerSegment(input.requestId);
+            const id = `att-${Date.now()}-${randomUUID().slice(0, 8)}`;
+            const storageRef = join(input.sessionId, input.requestId, `${id}${supported.extension}`);
+            const absolutePath = resolveStorageRef(storageRef);
+            await mkdir(dirname(absolutePath), { recursive: true });
+            await writeFile(absolutePath, input.bytes);
+            return {
+                id,
+                kind: input.kind,
+                mimeType,
+                storageRef,
+                ...(input.name ? { name: input.name } : {}),
+                size: input.bytes.byteLength,
+            };
+        },
+        async validateAttachmentReferences(attachments, options = {}) {
+            return Promise.all(attachments.map((attachment) => normalizeReference(attachment, options)));
+        },
+        async resolveAttachment(attachment) {
+            const metadata = await normalizeReference(attachment);
+            return {
+                metadata,
+                absolutePath: resolveStorageRef(metadata.storageRef),
+            };
+        },
+        async deleteAttachment(attachment, options = {}) {
+            assertSupported(attachment);
+            assertStorageRefOwner(attachment, options.sessionId);
+            await rm(resolveStorageRef(attachment.storageRef), {
+                force: true,
+            });
+        },
+        async deleteSessionAttachments(sessionId) {
+            assertSafeOwnerSegment(sessionId);
+            await rm(resolveStorageRef(sessionId), { recursive: true, force: true });
+        },
+    };
+}

package/dist/src/runtime/capabilities/configured-tool-registry.d.ts

@@ -0,0 +1,3 @@
+import type { ToolModuleDeclaration } from "../../capabilities/tool-types.js";
+import type { RuntimeConfig, ToolRegistry } from "../ports.js";
+export declare function createConfiguredToolRegistry(config: RuntimeConfig | undefined, modules: readonly ToolModuleDeclaration[]): ToolRegistry;

package/dist/src/runtime/capabilities/configured-tool-registry.js

@@ -0,0 +1,40 @@
+import { createToolRegistry as createToolRegistryInstance } from "../../capabilities/registry.js";
+import { executeToolCall } from "../../capabilities/tool-executor.js";
+import { createRuntimeToolPathResolver } from "./runtime-target-path.js";
+export function createConfiguredToolRegistry(config, modules) {
+    const baseRegistry = createToolRegistryInstance({ modules });
+    const getImplementations = () => baseRegistry.getImplementations();
+    const prepareSharedState = (sharedState = {}) => config
+        ? {
+            ...sharedState,
+            runtimePaths: {
+                rootDir: config.paths.rootDir,
+                runtimeDir: config.paths.runtimeDir,
+                agentWorkDir: config.paths.agentWorkDir,
+                sessionsDir: config.paths.sessionsDir,
+                workspaceDir: config.paths.workspaceDir,
+                sharedDir: config.paths.sharedDir,
+                compiledDir: config.paths.compiledDir,
+                traceFile: config.paths.traceFile,
+            },
+        }
+        : { ...sharedState };
+    return {
+        listDefinitions: () => baseRegistry.getDefinitions(),
+        listNormalInvocations: () => baseRegistry.getNormalInvocations(),
+        getDefinition: (name) => baseRegistry.getByName(name),
+        getAdapter: (name) => baseRegistry.getAdapterByName(name),
+        hasToolsAvailable: baseRegistry.hasToolsAvailable,
+        getImplementations,
+        prepareSharedState,
+        execute: (call, options) => {
+            const sharedState = prepareSharedState(options?.sharedState);
+            return executeToolCall(call, {
+                ...options,
+                sharedState,
+                runtimePathResolver: createRuntimeToolPathResolver(sharedState.runtimePaths),
+                implementations: getImplementations(),
+            });
+        },
+    };
+}

package/dist/src/runtime/capabilities/request-bound-tool-registry.d.ts

@@ -0,0 +1,11 @@
+import type { ToolModelInvoker, ToolRequestAttachment } from "../../capabilities/tool-types.js";
+import type { ToolRegistry } from "../ports.js";
+/**
+ * Adds trusted request services to an already config-filtered Tool Registry.
+ * Tools remain opaque to the request flow.
+ */
+export declare function bindRequestToolRegistry(params: Readonly<{
+    registry: ToolRegistry;
+    modelInvoker: ToolModelInvoker;
+    requestAttachments?: readonly ToolRequestAttachment[];
+}>): ToolRegistry;

package/dist/src/runtime/capabilities/request-bound-tool-registry.js

@@ -0,0 +1,80 @@
+/**
+ * Adds trusted request services to an already config-filtered Tool Registry.
+ * Tools remain opaque to the request flow.
+ */
+export function bindRequestToolRegistry(params) {
+    const registry = params.registry;
+    let normalInvocations;
+    let normalInvocationsResolved = false;
+    let availableTools;
+    let availableToolsResolved = false;
+    function resolveNormalInvocations() {
+        if (!normalInvocationsResolved) {
+            normalInvocations = registry.listNormalInvocations?.();
+            normalInvocationsResolved = true;
+        }
+        return normalInvocations;
+    }
+    function resolveAvailableTools() {
+        if (!availableToolsResolved) {
+            availableTools = projectAvailableTools(resolveNormalInvocations());
+            availableToolsResolved = true;
+        }
+        return availableTools;
+    }
+    return Object.freeze({
+        listDefinitions: () => registry.listDefinitions(),
+        ...(registry.listNormalInvocations
+            ? { listNormalInvocations: () => resolveNormalInvocations() }
+            : {}),
+        getDefinition: (name) => registry.getDefinition(name),
+        ...(registry.getAdapter
+            ? { getAdapter: (name) => registry.getAdapter(name) }
+            : {}),
+        hasToolsAvailable: () => registry.hasToolsAvailable(),
+        getImplementations: () => registry.getImplementations(),
+        prepareSharedState: (sharedState) => {
+            const requestAvailableTools = resolveAvailableTools();
+            const requestState = {
+                ...(sharedState ?? {}),
+                ...(requestAvailableTools !== undefined
+                    ? { availableTools: requestAvailableTools }
+                    : {}),
+                ...(params.requestAttachments && params.requestAttachments.length > 0
+                    ? { requestAttachments: params.requestAttachments }
+                    : {}),
+            };
+            return registry.prepareSharedState
+                ? registry.prepareSharedState(requestState)
+                : requestState;
+        },
+        execute: (call, options) => registry.execute(call, {
+            ...options,
+            modelInvoker: params.modelInvoker,
+        }),
+    });
+}
+function projectAvailableTools(registrations) {
+    if (registrations === undefined)
+        return undefined;
+    const entries = registrations.flatMap((registration) => registration.contract.operations.map((operation) => Object.freeze({
+        toolName: registration.toolName,
+        operationId: operation.operationId,
+        summary: operation.summary,
+        catalogGroups: Object.freeze([
+            ...(registration.definition.catalogGroups ?? ["other"]),
+        ]),
+        effect: operation.effect,
+    })));
+    entries.sort(compareAvailableTools);
+    return Object.freeze(entries);
+}
+function compareAvailableTools(left, right) {
+    const byOperation = compareAscii(left.operationId, right.operationId);
+    return byOperation !== 0
+        ? byOperation
+        : compareAscii(left.toolName, right.toolName);
+}
+function compareAscii(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/src/runtime/capabilities/request-runtime-tool-registry.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeConfig, ToolRegistry } from "../ports.js";
+import type { BoundRequestModelInvocationContext } from "../request/contracts.js";
+import type { ToolRequestAttachment } from "../../capabilities/tool-types.js";
+/**
+ * Binds the runtime's globally configured tools to one request. Exact
+ * capability availability is narrowed separately by declarative role config.
+ * This boundary contains no orchestration-policy selection.
+ */
+export declare function createRequestRuntimeToolRegistry(params: Readonly<{
+    request: BoundRequestModelInvocationContext;
+    requestAttachments?: readonly ToolRequestAttachment[];
+    runtimeConfig?: RuntimeConfig;
+    toolRegistryOverride?: ToolRegistry;
+}>): ToolRegistry;

package/dist/src/runtime/capabilities/request-runtime-tool-registry.js

@@ -0,0 +1,18 @@
+import { createRequestToolModelInvoker } from "../adapters/request-tool-model-invoker.js";
+import { createConfiguredToolRegistry } from "./configured-tool-registry.js";
+import { bindRequestToolRegistry } from "./request-bound-tool-registry.js";
+/**
+ * Binds the runtime's globally configured tools to one request. Exact
+ * capability availability is narrowed separately by declarative role config.
+ * This boundary contains no orchestration-policy selection.
+ */
+export function createRequestRuntimeToolRegistry(params) {
+    return bindRequestToolRegistry({
+        registry: params.toolRegistryOverride ??
+            createConfiguredToolRegistry(params.runtimeConfig, []),
+        modelInvoker: createRequestToolModelInvoker(params.request),
+        ...(params.requestAttachments
+            ? { requestAttachments: params.requestAttachments }
+            : {}),
+    });
+}

package/dist/src/runtime/capabilities/runtime-target-path.d.ts

@@ -0,0 +1,42 @@
+import type { RuntimeToolPathErrorCode, RuntimeToolPathResolver, ToolExecutionSharedState } from "../../capabilities/tool-types.js";
+export declare const RUNTIME_TOOL_PATH_ERROR_CODES: Readonly<{
+    readonly REQUIRED: "runtime_tool_path_required";
+    readonly NULL_BYTE: "runtime_tool_path_null_byte";
+    readonly LOCATION_REQUIRED: "runtime_tool_path_location_required";
+    readonly ROOT_UNAVAILABLE: "runtime_tool_path_root_unavailable";
+    readonly WORKSPACE_UNAVAILABLE: "runtime_tool_path_workspace_unavailable";
+    readonly OUTSIDE_CONFIGURED_ROOTS: "runtime_tool_path_outside_configured_roots";
+    readonly SYMLINK_ESCAPE: "runtime_tool_path_symlink_escape";
+    readonly CANONICALIZATION_FAILED: "runtime_tool_path_canonicalization_failed";
+    readonly TRAVERSAL: "runtime_tool_path_traversal";
+    readonly OUTSIDE_WORKING_DIRECTORY: "runtime_tool_path_outside_working_directory";
+}>;
+/** A stable machine-readable path-policy failure with a compatible message. */
+export declare class RuntimeToolPathError extends TypeError {
+    readonly code: RuntimeToolPathErrorCode;
+    constructor(code: RuntimeToolPathErrorCode, message?: string);
+}
+/**
+ * Qualifies one manifest-owned operation target against the canonical Worker
+ * call directory. Every ordinary relative target that is not already rooted
+ * at that directory is prefixed; explicit workspace-relative and absolute
+ * forms retain their current meaning only when they resolve inside that exact
+ * physical directory. The returned value remains a logical tool target.
+ */
+export declare function scopeRuntimeTargetPath(params: Readonly<{
+    rawPath: string;
+    workingDirectory?: string;
+    sharedState: ToolExecutionSharedState;
+}>): string;
+/**
+ * Resolves a manifest-declared target parameter without knowing which plugin
+ * owns it. Relative paths are rooted at agentWorkDir; the explicit
+ * `workspace/...` namespace is rooted at workspaceDir when configured.
+ */
+export declare function resolveRuntimeTargetPath(rawPath: string, sharedState: ToolExecutionSharedState): string;
+/**
+ * Creates the single host-owned path authority injected into plugin handlers.
+ * Plugins choose which declared roots they need; normalization, containment
+ * and symlink handling remain identical for every plugin.
+ */
+export declare function createRuntimeToolPathResolver(runtimePaths?: ToolExecutionSharedState["runtimePaths"]): RuntimeToolPathResolver;

package/dist/src/runtime/capabilities/runtime-target-path.js

@@ -0,0 +1,261 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, parse, posix, relative, resolve, sep, } from "node:path";
+export const RUNTIME_TOOL_PATH_ERROR_CODES = Object.freeze({
+    REQUIRED: "runtime_tool_path_required",
+    NULL_BYTE: "runtime_tool_path_null_byte",
+    LOCATION_REQUIRED: "runtime_tool_path_location_required",
+    ROOT_UNAVAILABLE: "runtime_tool_path_root_unavailable",
+    WORKSPACE_UNAVAILABLE: "runtime_tool_path_workspace_unavailable",
+    OUTSIDE_CONFIGURED_ROOTS: "runtime_tool_path_outside_configured_roots",
+    SYMLINK_ESCAPE: "runtime_tool_path_symlink_escape",
+    CANONICALIZATION_FAILED: "runtime_tool_path_canonicalization_failed",
+    TRAVERSAL: "runtime_tool_path_traversal",
+    OUTSIDE_WORKING_DIRECTORY: "runtime_tool_path_outside_working_directory",
+});
+/** A stable machine-readable path-policy failure with a compatible message. */
+export class RuntimeToolPathError extends TypeError {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.name = "RuntimeToolPathError";
+        this.code = code;
+    }
+}
+function throwRuntimeToolPathError(code, message = code) {
+    throw new RuntimeToolPathError(code, message);
+}
+function configuredRoot(value) {
+    const trimmed = value?.trim();
+    return trimmed ? resolve(trimmed) : undefined;
+}
+function isWithinRoot(target, root) {
+    const rel = relative(root, target);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+/**
+ * Qualifies one manifest-owned operation target against the canonical Worker
+ * call directory. Every ordinary relative target that is not already rooted
+ * at that directory is prefixed; explicit workspace-relative and absolute
+ * forms retain their current meaning only when they resolve inside that exact
+ * physical directory. The returned value remains a logical tool target.
+ */
+export function scopeRuntimeTargetPath(params) {
+    const workingDirectory = params.workingDirectory?.trim();
+    if (!workingDirectory) {
+        return params.rawPath;
+    }
+    const requested = params.rawPath.trim();
+    if (!requested) {
+        throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.REQUIRED, "runtime_target_path_missing");
+    }
+    const normalizedTarget = normalizeLogicalPath(requested);
+    const normalizedWorkingDirectory = normalizeLogicalPath(workingDirectory);
+    if (hasTraversalSegment(normalizedTarget) ||
+        hasTraversalSegment(normalizedWorkingDirectory) ||
+        isAbsolute(normalizedWorkingDirectory)) {
+        throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.TRAVERSAL, "runtime_target_path_traversal");
+    }
+    const normalized = posix.normalize(normalizedTarget);
+    const scoped = isAbsolute(normalized) ||
+        normalized === "workspace" ||
+        normalized.startsWith("workspace/") ||
+        normalized === normalizedWorkingDirectory ||
+        normalized.startsWith(`${normalizedWorkingDirectory}/`)
+        ? normalized
+        : posix.join(normalizedWorkingDirectory, normalized);
+    // Validate the exact logical value that every downstream consumer receives,
+    // then enforce the call-owned physical scope for explicit forms as well.
+    const resolvedWorkingDirectory = resolveRuntimeTargetPath(normalizedWorkingDirectory, params.sharedState);
+    const resolvedTarget = resolveRuntimeTargetPath(scoped, params.sharedState);
+    if (!isWithinRoot(resolvedTarget, resolvedWorkingDirectory)) {
+        throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.OUTSIDE_WORKING_DIRECTORY, "runtime_target_path_outside_working_directory");
+    }
+    return scoped;
+}
+function normalizeLogicalPath(value) {
+    return value.replaceAll("\\", "/");
+}
+function hasTraversalSegment(value) {
+    return value.split("/").includes("..");
+}
+/**
+ * Resolves a manifest-declared target parameter without knowing which plugin
+ * owns it. Relative paths are rooted at agentWorkDir; the explicit
+ * `workspace/...` namespace is rooted at workspaceDir when configured.
+ */
+export function resolveRuntimeTargetPath(rawPath, sharedState) {
+    const requested = rawPath.trim();
+    if (!requested) {
+        throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.REQUIRED, "runtime_target_path_missing");
+    }
+    try {
+        return resolveRuntimeToolPath(requested, {
+            roots: configuredRuntimeToolPathRoots(sharedState.runtimePaths),
+            allowedLocations: DEFAULT_TOOL_PATH_LOCATIONS,
+        }).absolutePath;
+    }
+    catch (error) {
+        rethrowLegacyRuntimeTargetPathError(error);
+    }
+}
+function resolveThroughExistingAncestor(target) {
+    let cursor = target;
+    const missingSuffix = [];
+    while (true) {
+        try {
+            return resolve(realpathSync(cursor), ...missingSuffix);
+        }
+        catch {
+            try {
+                lstatSync(cursor);
+            }
+            catch (error) {
+                if (!isMissingPathError(error)) {
+                    throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.CANONICALIZATION_FAILED);
+                }
+                const parent = dirname(cursor);
+                if (parent === cursor) {
+                    throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.CANONICALIZATION_FAILED);
+                }
+                missingSuffix.unshift(basename(cursor));
+                cursor = parent;
+                continue;
+            }
+            // The entry exists but cannot be canonicalized. This includes broken or
+            // looping symlinks; never downgrade those cases to lexical containment.
+            throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.SYMLINK_ESCAPE);
+        }
+    }
+}
+function isMissingPathError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        (error.code === "ENOENT" || error.code === "ENOTDIR"));
+}
+const DEFAULT_TOOL_PATH_LOCATIONS = Object.freeze([
+    "agent_work",
+    "workspace",
+]);
+function configuredRuntimeToolPathRoots(runtimePaths = {}) {
+    return Object.freeze({
+        agent_work: configuredRoot(runtimePaths.agentWorkDir),
+        workspace: configuredRoot(runtimePaths.workspaceDir),
+        runtime_root: configuredRoot(runtimePaths.rootDir),
+    });
+}
+function rethrowLegacyRuntimeTargetPathError(error) {
+    if (!(error instanceof RuntimeToolPathError))
+        throw error;
+    const legacyMessage = {
+        [RUNTIME_TOOL_PATH_ERROR_CODES.REQUIRED]: "runtime_target_path_missing",
+        [RUNTIME_TOOL_PATH_ERROR_CODES.NULL_BYTE]: "runtime_target_path_missing",
+        [RUNTIME_TOOL_PATH_ERROR_CODES.ROOT_UNAVAILABLE]: "runtime_target_agent_work_dir_missing",
+        [RUNTIME_TOOL_PATH_ERROR_CODES.WORKSPACE_UNAVAILABLE]: "runtime_target_path_workspace_unavailable",
+        [RUNTIME_TOOL_PATH_ERROR_CODES.OUTSIDE_CONFIGURED_ROOTS]: "runtime_target_path_outside_configured_roots",
+        [RUNTIME_TOOL_PATH_ERROR_CODES.SYMLINK_ESCAPE]: "runtime_target_path_symlink_escape",
+        [RUNTIME_TOOL_PATH_ERROR_CODES.CANONICALIZATION_FAILED]: "runtime_target_path_canonicalization_failed",
+    };
+    throw new RuntimeToolPathError(error.code, legacyMessage[error.code] ?? error.message);
+}
+function resolveRuntimeToolPath(rawPath, options) {
+    const requested = typeof rawPath === "string"
+        ? rawPath
+        : options.requirePath === true
+            ? undefined
+            : options.defaultPath;
+    if (!requested?.trim()) {
+        throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.REQUIRED);
+    }
+    if (requested.includes("\0")) {
+        throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.NULL_BYTE);
+    }
+    const allowed = Object.freeze([...(options.allowedLocations ?? DEFAULT_TOOL_PATH_LOCATIONS)].filter((location, index, values) => values.indexOf(location) === index));
+    if (allowed.length === 0) {
+        throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.LOCATION_REQUIRED);
+    }
+    const availableRoots = allowed.flatMap((location) => {
+        if (location === "host_system")
+            return [];
+        const root = options.roots[location];
+        return root ? [{ location, root }] : [];
+    });
+    const normalized = normalizeLogicalPath(requested);
+    const workspaceRelative = normalized === "workspace"
+        ? ""
+        : normalized.startsWith("workspace/")
+            ? normalized.slice("workspace/".length)
+            : undefined;
+    let selected;
+    let lexicalTarget;
+    if (workspaceRelative !== undefined) {
+        const workspace = availableRoots.find(({ location }) => location === "workspace");
+        if (!workspace) {
+            throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.WORKSPACE_UNAVAILABLE);
+        }
+        selected = workspace;
+        lexicalTarget = resolve(workspace.root, workspaceRelative);
+    }
+    else if (isAbsolute(requested)) {
+        lexicalTarget = resolve(requested);
+        const rootedMatch = availableRoots
+            .filter(({ root }) => isWithinRoot(lexicalTarget, root))
+            .sort((left, right) => right.root.length - left.root.length)[0];
+        if (rootedMatch) {
+            selected = rootedMatch;
+        }
+        else if (allowed.includes("host_system")) {
+            selected = { location: "host_system", root: parse(lexicalTarget).root };
+        }
+        else {
+            throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.OUTSIDE_CONFIGURED_ROOTS);
+        }
+    }
+    else {
+        const rootedDefault = availableRoots.find(({ location }) => location === "agent_work") ??
+            availableRoots[0];
+        if (!rootedDefault) {
+            throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.ROOT_UNAVAILABLE);
+        }
+        selected = rootedDefault;
+        lexicalTarget = resolve(selected.root, normalized === "." ? "" : normalized);
+    }
+    if (!isWithinRoot(lexicalTarget, selected.root)) {
+        throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.OUTSIDE_CONFIGURED_ROOTS);
+    }
+    const absolutePath = resolveThroughExistingAncestor(lexicalTarget);
+    const canonicalRoot = resolveThroughExistingAncestor(selected.root);
+    if (!isWithinRoot(absolutePath, canonicalRoot)) {
+        throwRuntimeToolPathError(RUNTIME_TOOL_PATH_ERROR_CODES.SYMLINK_ESCAPE);
+    }
+    const relativePath = relative(canonicalRoot, absolutePath).replaceAll(sep, "/");
+    const logicalPath = selected.location === "workspace"
+        ? relativePath
+            ? `workspace/${relativePath}`
+            : "workspace"
+        : selected.location === "host_system"
+            ? absolutePath
+            : relativePath || ".";
+    return Object.freeze({
+        location: selected.location,
+        rootPath: canonicalRoot,
+        absolutePath,
+        relativePath,
+        logicalPath,
+    });
+}
+/**
+ * Creates the single host-owned path authority injected into plugin handlers.
+ * Plugins choose which declared roots they need; normalization, containment
+ * and symlink handling remain identical for every plugin.
+ */
+export function createRuntimeToolPathResolver(runtimePaths = {}) {
+    const roots = configuredRuntimeToolPathRoots(runtimePaths);
+    return Object.freeze({
+        resolve(rawPath, options = {}) {
+            return resolveRuntimeToolPath(rawPath, {
+                roots,
+                ...options,
+            });
+        },
+    });
+}