@cjhyy/code-shell-core 0.7.1 → 0.8.1

package/dist/tool-system/session-tool-host.js

@@ -0,0 +1,167 @@
+import { ToolExecutor } from "./executor.js";
+import { PermissionClassifier } from "./permission.js";
+import { HookRegistry } from "../hooks/registry.js";
+import { buildToolVisibility } from "../engine/run-tooling.js";
+import { composePermissionRules } from "../engine/permission-controller.js";
+const FORBIDDEN_MODES = new Set(["bypassPermissions", "dontAsk"]);
+/**
+ * Whole-string match for an exposure pattern.
+ *
+ * Patterns are ANCHORED here rather than trusting the author to write `^…$`.
+ * An unanchored `action: "list"` would also admit `"invoke_list"` — a silent
+ * widening of a rule whose entire purpose is to narrow. Anchoring in one place
+ * makes the safe reading the only reading; an author who deliberately writes
+ * `^(list|open)$` gets the same result either way.
+ */
+function matchesWholeValue(source, value) {
+    let re;
+    try {
+        re = new RegExp(`^(?:${source})$`, "u");
+    }
+    catch {
+        // A malformed pattern must not silently permit everything.
+        return false;
+    }
+    return re.test(value);
+}
+function argsMatch(patterns, input) {
+    if (!patterns)
+        return true;
+    for (const [key, source] of Object.entries(patterns)) {
+        // Read own properties only: a model-supplied JSON body cannot smuggle a
+        // match through the prototype chain.
+        const value = Object.prototype.hasOwnProperty.call(input, key) ? input[key] : undefined;
+        // Only primitives are comparable. Objects/arrays are rejected rather than
+        // stringified — `String(["list"])` is `"list"`, which would let an array
+        // satisfy a scalar pattern.
+        if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+            return false;
+        }
+        if (!matchesWholeValue(source, String(value)))
+            return false;
+    }
+    return true;
+}
+export function createSessionToolHost(options) {
+    if (FORBIDDEN_MODES.has(options.permissionMode)) {
+        throw new Error(`SessionToolHost refuses permission mode '${options.permissionMode}': it short-circuits ` +
+            `PermissionClassifier, so CodeShell tool authorization would not actually run. ` +
+            `An external runtime's own permission mode is separate and unaffected.`);
+    }
+    const { registry, exposure } = options;
+    const hooks = options.hooks ?? new HookRegistry();
+    // Composed HERE, by the same function the Native Engine uses, so the two paths
+    // cannot drift. In particular this is what pulls in the user's own
+    // `settings.permissions.rules` — a deny the user wrote must bind an external
+    // runtime exactly as it binds the Native Engine.
+    const permission = new PermissionClassifier(composePermissionRules({
+        mode: options.permissionMode,
+        cwd: options.cwd,
+        presetRules: options.presetRules,
+        projectTrusted: options.projectTrusted,
+        ...(options.settingsScope ? { settingsScope: options.settingsScope } : {}),
+    }), options.permissionMode, options.approvalBackend);
+    // Every in-flight call is chained to this, so dispose() can actually stop work
+    // that is mid-execution or parked on an approval prompt (§13.4).
+    const lifetime = new AbortController();
+    const sessionSignal = options.signal
+        ? AbortSignal.any([options.signal, lifetime.signal])
+        : lifetime.signal;
+    const toolCtx = {
+        cwd: options.cwd,
+        toolRegistry: registry,
+        // The COMBINED signal, not just the caller's: a tool that cooperates with
+        // ctx.signal must observe session disposal too.
+        signal: sessionSignal,
+        // Caller-supplied host seams (panels, browser, askUser, …) come FIRST so the
+        // security-relevant fields below always win. Spreading them last would let a
+        // caller — or a careless refactor — set `toolVisibility: undefined` (which
+        // makes ToolExecutor skip its availability guard entirely), widen
+        // `allowedToolNames`, or re-introduce a permission mode the throw above
+        // just rejected.
+        ...options.contextOverrides,
+        sessionId: options.businessSessionId,
+        planMode: options.planMode,
+        permissionMode: options.permissionMode,
+        toolVisibility: buildToolVisibility(options.visibility),
+        // Belt and braces with the exposure check in execute(): the executor
+        // enforces this too, so a future refactor that loses one still fails closed.
+        allowedToolNames: new Set(exposure.toolNames),
+    };
+    const executor = new ToolExecutor(registry, permission, hooks);
+    executor.setContext(toolCtx);
+    executor.setSignal(sessionSignal);
+    let disposed = false;
+    const failClosed = (id, name, error) => ({
+        id,
+        toolName: name,
+        error,
+        isError: true,
+    });
+    return {
+        businessSessionId: options.businessSessionId,
+        toolContext: toolCtx,
+        listTools() {
+            if (disposed)
+                return [];
+            return registry
+                .getToolDefinitions()
+                .filter((definition) => exposure.toolNames.has(definition.name));
+        },
+        async execute(call, callSignal) {
+            if (disposed) {
+                return failClosed(call.id, call.name, "This tool session has been closed.");
+            }
+            if (!exposure.toolNames.has(call.name)) {
+                // Fail closed on a KNOWN-but-unexposed name too. Not listing a tool is a
+                // boundary, not a hint to the model.
+                return failClosed(call.id, call.name, `Tool ${call.name} is not exposed to this session. Do NOT retry this tool call.`);
+            }
+            const input = call.input && typeof call.input === "object" && !Array.isArray(call.input)
+                ? call.input
+                : {};
+            if (!argsMatch(exposure.argsPatterns?.get(call.name), input)) {
+                return failClosed(call.id, call.name, `Tool ${call.name} was called with arguments outside the scope exposed to this ` +
+                    `session. Do NOT retry this tool call with the same arguments.`);
+            }
+            // `sessionSignal` folds in the session lifetime and the caller-supplied
+            // signal; `callSignal` is the optional per-call one (an MCP cancellation).
+            if (sessionSignal.aborted || callSignal?.aborted) {
+                return failClosed(call.id, call.name, `Tool aborted before execution: ${call.name}`);
+            }
+            // Forward the per-call signal rather than only checking it at entry: an MCP
+            // cancellation arriving mid-flight has to actually stop the work.
+            //
+            // A `ToolExecutor` holds exactly one signal, and swapping it per call would
+            // race with concurrent calls carrying different signals. So a call that
+            // brings its own signal gets its own executor — cheap (it is a thin wrapper
+            // over the shared registry/permission/hooks) and free of shared mutable
+            // state. Calls without one use the shared executor unchanged.
+            if (!callSignal) {
+                // The one authorized path. Everything above only NARROWS what may reach it.
+                return await executor.executeSingle({
+                    id: call.id,
+                    toolName: call.name,
+                    args: input,
+                });
+            }
+            const scoped = new ToolExecutor(registry, permission, hooks);
+            scoped.setContext(toolCtx);
+            scoped.setSignal(AbortSignal.any([sessionSignal, callSignal]));
+            return await scoped.executeSingle({
+                id: call.id,
+                toolName: call.name,
+                args: input,
+            });
+        },
+        async dispose() {
+            // Order matters (§13.4): stop accepting new calls, THEN abort in-flight
+            // ones. Marking disposed without aborting would let a call that is already
+            // running — or parked on an approval prompt — continue and complete after
+            // the session is gone.
+            disposed = true;
+            lifetime.abort();
+            executor.setContext(undefined);
+        },
+    };
+}

package/dist/tool-system/testing/tool-registry-harness.d.ts

@@ -0,0 +1,31 @@
+import type { BuiltinTool } from "../builtin/index.js";
+import type { ToolContext } from "../context.js";
+import { ToolRegistry } from "../registry.js";
+import type { ToolResult } from "../../types.js";
+export interface FakeToolContextOptions {
+    cwd?: string;
+    sessionId?: string;
+    signal?: AbortSignal;
+    /** Shallow overrides for tool-family-specific host bridges. */
+    overrides?: Partial<ToolContext>;
+}
+export interface ToolRegistryHarnessOptions extends FakeToolContextOptions {
+    builtinTools?: readonly string[];
+    toolCatalog?: readonly BuiltinTool[];
+    registry?: ToolRegistry;
+    timeoutMs?: number;
+}
+export interface ToolRegistryHarness {
+    registry: ToolRegistry;
+    context: ToolContext;
+    execute(name: string, args?: Record<string, unknown>): Promise<ToolResult>;
+}
+/**
+ * Shared fake ToolContext for builtin integration tests. It intentionally
+ * supplies only stable harness defaults; tests opt into browser/workspace/MCP/
+ * sub-agent behavior through `overrides`, so missing host seams fail visibly.
+ */
+export declare function createFakeToolContext(registry: ToolRegistry, options?: FakeToolContextOptions): ToolContext;
+/** Build a real ToolRegistry and execute through its timeout/signal/result
+ * protocol while keeping host dependencies deterministic and injectable. */
+export declare function createToolRegistryHarness(options?: ToolRegistryHarnessOptions): ToolRegistryHarness;

package/dist/tool-system/testing/tool-registry-harness.js

@@ -0,0 +1,51 @@
+import { resolve } from "node:path";
+import { ToolRegistry } from "../registry.js";
+/**
+ * Shared fake ToolContext for builtin integration tests. It intentionally
+ * supplies only stable harness defaults; tests opt into browser/workspace/MCP/
+ * sub-agent behavior through `overrides`, so missing host seams fail visibly.
+ */
+export function createFakeToolContext(registry, options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const context = {
+        cwd,
+        setCwd(next) {
+            context.cwd = resolve(next);
+        },
+        llmConfig: {},
+        toolRegistry: registry,
+        planMode: false,
+        sessionId: options.sessionId ?? "tool-harness-session",
+        signal: options.signal,
+        allowBackgroundShells: false,
+        toolVisibility: { hasGoal: true },
+        engine: {
+            getPlanMode: () => context.planMode,
+            setPlanMode: (enabled) => {
+                context.planMode = enabled;
+            },
+        },
+        askUser: async () => "harness-answer",
+        ...options.overrides,
+    };
+    return context;
+}
+/** Build a real ToolRegistry and execute through its timeout/signal/result
+ * protocol while keeping host dependencies deterministic and injectable. */
+export function createToolRegistryHarness(options = {}) {
+    const registryOptions = {
+        ...(options.builtinTools ? { builtinTools: options.builtinTools } : {}),
+        ...(options.toolCatalog ? { toolCatalog: options.toolCatalog } : {}),
+    };
+    const registry = options.registry ?? new ToolRegistry(registryOptions);
+    const context = createFakeToolContext(registry, options);
+    return {
+        registry,
+        context,
+        execute: async (name, args = {}) => await registry.executeTool(name, args, {
+            ctx: context,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs ?? 5_000,
+        }),
+    };
+}

package/dist/tool-system/validation.d.ts

@@ -1,15 +1,22 @@
 /**
- * Lightweight tool input validation against a JSON Schema.
+ * Compatibility validator used by existing built-ins and third-party MCP
+ * schemas. It checks `required` presence and top-level primitive types only;
+ * changing that permissive contract would be a broad compatibility break.
  *
- * NOT a full JSON-Schema validator: it only checks `required` presence and
- * top-level primitive types (string/number/boolean). Arrays, objects, enums,
- * nested shapes, and formats are intentionally NOT validated — this is a
- * cheap pre-flight guard, not a substitute for the provider's own schema
- * enforcement. (Was previously labelled "Zod-based" and imported `z`, but
- * never used zod — corrected to avoid misleading readers.)
+ * Reviewed Panel App schemas use the fail-closed recursive validator exported
+ * later in this module (`validateToolArgsStrict`).
  */
 /**
  * Validate tool args against the tool's inputSchema.
  * Returns null if valid, error string if invalid.
  */
 export declare function validateToolArgs(toolName: string, args: Record<string, unknown>, schema: Record<string, unknown>): string | null;
+/**
+ * Fail-closed recursive validation for reviewed Panel App Agent tools.
+ *
+ * This deliberately lives beside the lightweight validator instead of
+ * changing its permissive compatibility contract for existing built-ins and
+ * third-party MCP schemas.
+ */
+export declare function validateToolInputSchemaStrict(schema: Record<string, unknown>): string | null;
+export declare function validateToolArgsStrict(toolName: string, args: Record<string, unknown>, schema: Record<string, unknown>): string | null;