@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/tool-system/path-policy.js

@@ -29,10 +29,12 @@
  * approval round-trip; it is not an authority to write anywhere on disk.
  * Callers must consult classifyPath before honoring acceptEdits.
  */
-import { realpathSync, existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, } from "node:fs";
+import { constants, realpathSync, existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, } from "node:fs";
+import { open } from "node:fs/promises";
 import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { dirname, isAbsolute, join, resolve as resolvePath, sep } from "node:path";
+const FINAL_WRITE_PATH_SNAPSHOT = Symbol("codeshell.finalWritePathSnapshot");
 /**
  * Default sensitive path patterns. These are evaluated AFTER home-expansion
  * and resolution, so a literal "$HOME/.ssh" and a symlink at /tmp/x → ~/.ssh
@@ -325,6 +327,65 @@ function safeRealpath(p) {
     }
     return abs;
 }
+/**
+ * Capture the concrete target approved by the executor's first path-policy
+ * pass. The snapshot is carried on the internal args object via a symbol, so
+ * it cannot collide with an LLM-supplied schema property or leak into logs.
+ */
+export function attachFinalWritePathSnapshot(args, filePath, workspaceRoot) {
+    const resolvedPath = safeRealpath(filePath);
+    const workspacePath = safeRealpath(workspaceRoot);
+    const snapshot = {
+        resolvedPath,
+        workspacePath,
+        insideWorkspace: isInsideDir(resolvedPath, workspacePath),
+    };
+    return { ...args, [FINAL_WRITE_PATH_SNAPSHOT]: snapshot };
+}
+export function getFinalWritePathSnapshot(args, filePath, workspaceRoot) {
+    const carried = args[FINAL_WRITE_PATH_SNAPSHOT];
+    if (carried && typeof carried === "object") {
+        return carried;
+    }
+    // Direct tool calls do not pass through ToolExecutor. Preserve that API by
+    // taking the baseline at handler entry, while still protecting Edit's
+    // read-to-write interval with a second check before its writeFile.
+    const resolvedPath = safeRealpath(filePath);
+    const workspacePath = safeRealpath(workspaceRoot);
+    return {
+        resolvedPath,
+        workspacePath,
+        insideWorkspace: isInsideDir(resolvedPath, workspacePath),
+    };
+}
+export function revalidateFinalWritePath(filePath, workspaceRoot, approved) {
+    const currentPath = safeRealpath(filePath);
+    const currentWorkspace = safeRealpath(workspaceRoot);
+    const sameTarget = normPath(currentPath) === normPath(approved.resolvedPath);
+    const sameWorkspace = normPath(currentWorkspace) === normPath(approved.workspacePath);
+    const crossedWorkspaceBoundary = approved.insideWorkspace && !isInsideDir(currentPath, currentWorkspace);
+    if (crossedWorkspaceBoundary || !sameTarget || !sameWorkspace) {
+        const reason = crossedWorkspaceBoundary
+            ? "final write path resolved outside the workspace after approval"
+            : "final write path changed after approval";
+        return {
+            error: `Error: ${reason}; refusing to write. ` +
+                `Approved target: ${approved.resolvedPath}. Current target: ${currentPath}`,
+        };
+    }
+    return { resolvedPath: currentPath };
+}
+/** Open the already-revalidated final path without following its last segment. */
+export async function writeFileNoFollow(filePath, content) {
+    const flags = constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW;
+    const handle = await open(filePath, flags, 0o666);
+    try {
+        await handle.writeFile(content, "utf-8");
+    }
+    finally {
+        await handle.close();
+    }
+}
 function isInsideDir(child, parent) {
     const c = normPath(child);
     const par = normPath(parent);

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

@@ -6,6 +6,55 @@ import { logger as rootPermLogger } from "../logging/logger.js";
 export interface ApprovalBackend {
     requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
 }
+/**
+ * Interactive-approval lifecycle observation (see
+ * PermissionClassifier.setApprovalEventListener). "requested" fires right
+ * before the backend prompt is awaited; "resolved" fires after the user (or
+ * backend policy) answered, with the outcome.
+ */
+export interface ApprovalLifecycleEvent {
+    phase: "requested" | "resolved";
+    toolName: string;
+    riskLevel: "low" | "medium" | "high";
+    approved?: boolean;
+    sessionId?: string;
+}
+export interface ApprovalRouteTarget {
+    connectionId: string;
+    sessionId: string;
+    generation: number;
+}
+export interface ApprovalConnectionHandler {
+    requestApproval(request: ApprovalRequest, target: ApprovalRouteTarget): Promise<ApprovalResult>;
+    ownershipLost?(targets: ApprovalRouteTarget[], reason: string): void;
+}
+export type ApprovalRegistrationResult = {
+    ok: true;
+    target: ApprovalRouteTarget;
+} | {
+    ok: false;
+    conflict: ApprovalRouteTarget;
+};
+/**
+ * Process-local connection owner router. Handlers are connection-scoped while
+ * session ownership is an explicit binding with a monotonic generation.
+ */
+export declare class ApprovalRouter {
+    private readonly handlers;
+    private readonly owners;
+    private readonly fallbackConnections;
+    private nextGeneration;
+    addConnection(connectionId: string, handler: ApprovalConnectionHandler, options?: {
+        claimUnownedSessions?: boolean;
+    }): () => void;
+    register(sessionId: string, connectionId: string): ApprovalRegistrationResult;
+    resolve(request: ApprovalRequest): Promise<ApprovalResult> | null;
+    matches(target: ApprovalRouteTarget): boolean;
+    current(sessionId: string): ApprovalRouteTarget | null;
+    release(sessionId: string, connectionId: string, reason?: string): void;
+    deregister(connectionId: string, reason?: string): void;
+    hasConnections(): boolean;
+}
 export declare class HeadlessApprovalBackend implements ApprovalBackend {
     private readonly mode;
     constructor(mode: "approve-all" | "deny-all" | "approve-read-only");
@@ -45,18 +94,22 @@ export declare const CLOSED_SESSION_TOMBSTONE_LIMIT = 4096;
  * the next time the user opens the project.
  */
 export declare class InteractiveApprovalBackend implements ApprovalBackend {
+    private readonly approvalRouter;
     private sessionStateById;
     private closedSessionIds;
     private promptFn;
     private legacyPromptTurn;
     private legacyContext;
+    constructor(approvalRouter?: ApprovalRouter);
     setPromptFn(fn: (request: ApprovalRequest) => Promise<ApprovalResult>): void;
+    clearPromptFn(): void;
     /**
      * Has someone installed a real prompt callback? Engine consults this
      * to decide whether to use the interactive backend (= talk to a UI)
      * or fall back to HeadlessApprovalBackend (= deny-all). Without it,
-     * the agent-server-stdio entry — which wires setInteractiveApprovalFn
-     * during server boot — would still fall through to deny-all because
+     * a protocol host registers its connection with ApprovalRouter during boot
+     * but before the first session is bound — without this check Engine would
+     * still fall through to deny-all because
      * the engine couldn't tell the difference. */
     hasPromptFn(): boolean;
     /** Inject the project root so persistence writes to the right settings file. */
@@ -107,10 +160,10 @@ export declare function pathRuleArgsPattern(absPath: string, scope: "file" | "di
  * JSON round-trip where a persisted RegExp comes back as a string.
  */
 export declare function ruleMatches(rule: PermissionRule, toolName: string, args: Record<string, unknown>): boolean;
+export declare function getApprovalRouter(): ApprovalRouter;
 export declare function getInteractiveApprovalBackend(): InteractiveApprovalBackend;
 export declare function openInteractiveApprovalSession(sessionId: string): void;
 export declare function clearInteractiveApprovalSession(sessionId: string): void;
-export declare function setInteractiveApprovalFn(fn: (request: ApprovalRequest) => Promise<ApprovalResult>): void;
 type BashSafetyLevel = "safe-read" | "safe-write" | "unsafe" | "dangerous";
 /**
  * True when an otherwise-safe-read shell segment must be downgraded to `unsafe`
@@ -145,8 +198,21 @@ export declare class PermissionClassifier {
      * tests and ad-hoc usages still write log lines.
      */
     private log;
+    private approvalStateListener?;
+    private approvalEventListener?;
+    private activeApprovalCount;
     constructor(rules: PermissionRule[], defaultMode?: PermissionMode, approvalBackend?: ApprovalBackend);
     setLogger(log: typeof rootPermLogger): void;
+    setApprovalStateListener(listener: ((waiting: boolean, toolName: string) => void) | undefined): void;
+    /**
+     * Observe interactive-approval lifecycle (requested → resolved). The engine
+     * wires this to the `notification` hook so plugins / settings hooks can
+     * react to "waiting for the user's decision" moments (system notification,
+     * IM ping, …). Listener errors are swallowed — observation must never
+     * affect the approval outcome.
+     */
+    setApprovalEventListener(listener: ((event: ApprovalLifecycleEvent) => void) | undefined): void;
+    private emitApprovalEvent;
     /** Replace mode + backend in place so live tool execution sees the change. */
     reconfigure(mode: PermissionMode, approvalBackend: ApprovalBackend, rules?: PermissionRule[]): void;
     getMode(): PermissionMode;