@diff-review-system/drs 4.0.1 → 5.0.0-rc.1

package/dist/pi/sdk.js

@@ -1,12 +1,19 @@
 import { randomUUID } from 'crypto';
 import { spawn } from 'child_process';
-import { isAbsolute, join, resolve } from 'path';
+import { constants } from 'fs';
+import { access, mkdir, readFile as readFsFile, unlink, writeFile as writeFsFile, } from 'fs/promises';
+import { homedir } from 'os';
+import { isAbsolute, join, relative, resolve, sep } from 'path';
+import { fileURLToPath } from 'url';
 import { Type } from '@sinclair/typebox';
-import { AuthStorage, createAgentSession, DefaultResourceLoader, getAgentDir, ModelRegistry, SettingsManager, SessionManager, } from '@earendil-works/pi-coding-agent';
+import { AuthStorage, createAgentSession, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, DefaultResourceLoader, getAgentDir, ModelRegistry, SettingsManager, SessionManager, } from '@earendil-works/pi-coding-agent';
 import { writeJsonOutput } from '../lib/write-json-output.js';
-import { writeArtifactOutput } from '../lib/html-artifact.js';
+import { extractHtmlDocument, writeArtifactOutput } from '../lib/html-artifact.js';
 import { isReviewArtifactPayload } from '../lib/review-artifact.js';
 import { resolveWithinWorkingDir } from '../lib/path-utils.js';
+import { AgentFilesystemAuthorizer, validateAgentPermissions, validateAgentValidation, } from '../lib/agent-permissions.js';
+import { formatOkfValidationErrors, validateOkfBundle, validateOkfDocument, } from '../lib/okf-wiki.js';
+import { OUTPUT_PATHS } from '../lib/output-paths.js';
 const DEFAULT_GIT_DIFF_MAX_BYTES = 120_000;
 const HARD_GIT_DIFF_MAX_BYTES = 500_000;
 const GIT_DIFF_STDERR_MAX_BYTES = 16_384;
@@ -15,6 +22,44 @@ function asRecord(value) {
         ? value
         : {};
 }
+function parseAgentPermissions(value) {
+    if (value === undefined)
+        return undefined;
+    validateAgentPermissions(value, 'Pi runtime permissions');
+    return value;
+}
+function parseAgentValidation(value) {
+    if (value === undefined)
+        return undefined;
+    validateAgentValidation(value, 'Pi runtime validation');
+    return value;
+}
+function toPosixPath(value) {
+    return sep === '/' ? value : value.split(sep).join('/');
+}
+function resolvePiToolPath(workingDir, requestedPath) {
+    let normalized = requestedPath.replace(/[\u00A0\u2000-\u200A\u202F\u205F\u3000]/gu, ' ');
+    if (normalized.startsWith('@'))
+        normalized = normalized.slice(1);
+    if (normalized === '~')
+        normalized = homedir();
+    else if (normalized.startsWith('~/') ||
+        (process.platform === 'win32' && normalized.startsWith('~\\'))) {
+        normalized = join(homedir(), normalized.slice(2));
+    }
+    if (/^file:\/\//u.test(normalized))
+        normalized = fileURLToPath(normalized);
+    return isAbsolute(normalized) ? resolve(normalized) : resolve(workingDir, normalized);
+}
+function allowsAggregateReadTools(permissions) {
+    return Boolean(permissions &&
+        (permissions.deny?.length ?? 0) === 0 &&
+        permissions.allow.some((pattern) => pattern.replaceAll('\\', '/').replace(/^\.\//u, '') === '**'));
+}
+function allowsFullRepositoryRead(permissions) {
+    return Boolean(allowsAggregateReadTools(permissions) &&
+        permissions?.roots.some((root) => root.replaceAll('\\', '/').replace(/\/$/u, '') === '.'));
+}
 function asString(value) {
     return typeof value === 'string' ? value : undefined;
 }
@@ -593,6 +638,11 @@ class PiSessionRuntime {
     sessions = new Map();
     sessionApi;
     constructor(config) {
+        const permissions = parseAgentPermissions(config.permissions);
+        const validation = parseAgentValidation(config.validation);
+        if (validation && !permissions?.filesystem?.write && !permissions?.filesystem?.delete) {
+            throw new Error('Pi runtime validation requires filesystem write or delete permissions.');
+        }
         this.runtimeConfig = {
             tools: asRecord(config.tools),
             agent: asRecord(config.agent),
@@ -602,6 +652,8 @@ class PiSessionRuntime {
             thinkingLevel: asString(config.thinkingLevel),
             fixChecks: parseFixChecks(config.fixChecks),
             traceCollector: config.traceCollector,
+            permissions,
+            validation,
             retry: asRecord(config.retry),
         };
         this.authStorage = AuthStorage.create();
@@ -729,34 +781,211 @@ class PiSessionRuntime {
     }
     resolveTools(_cwd, agentTools) {
         const tools = [];
+        const filesystemPermissions = this.runtimeConfig.permissions?.filesystem;
+        const aggregateReadsAllowed = !filesystemPermissions?.read || allowsAggregateReadTools(filesystemPermissions.read);
         if (this.isToolEnabled('Read', true, agentTools)) {
             tools.push('read');
         }
-        if (this.isToolEnabled('Bash', true, agentTools)) {
+        if (this.runtimeConfig.permissions?.shell !== false &&
+            this.isToolEnabled('Bash', true, agentTools)) {
             tools.push('bash');
         }
-        if (this.isToolEnabled('Edit', false, agentTools)) {
+        if ((!filesystemPermissions || filesystemPermissions.write !== undefined) &&
+            this.isToolEnabled('Edit', false, agentTools)) {
             tools.push('edit');
         }
-        if (this.isToolEnabled('Write', false, agentTools)) {
+        if ((!filesystemPermissions || filesystemPermissions.write !== undefined) &&
+            this.isToolEnabled('Write', false, agentTools)) {
             tools.push('write');
         }
-        if (this.isToolEnabled('Grep', true, agentTools)) {
+        if (aggregateReadsAllowed && this.isToolEnabled('Grep', true, agentTools)) {
             tools.push('grep');
         }
-        if (this.isToolEnabled('Glob', true, agentTools)) {
+        if (aggregateReadsAllowed && this.isToolEnabled('Glob', true, agentTools)) {
             tools.push('find');
             tools.push('ls');
         }
-        if (tools.length === 0) {
-            tools.push('read', 'bash');
+        return tools;
+    }
+    resolvePermissionTools(workingDir, agentTools) {
+        const filesystemPermissions = this.runtimeConfig.permissions?.filesystem;
+        if (!filesystemPermissions)
+            return [];
+        const authorizer = new AgentFilesystemAuthorizer(workingDir, filesystemPermissions);
+        const tools = [];
+        if (filesystemPermissions.read && this.isToolEnabled('Read', true, agentTools)) {
+            const readTool = createReadToolDefinition(workingDir, {
+                operations: {
+                    access: async (filePath) => {
+                        await authorizer.authorize('read', filePath);
+                        await access(filePath, constants.R_OK);
+                    },
+                    readFile: async (filePath) => {
+                        await authorizer.authorize('read', filePath);
+                        return readFsFile(filePath);
+                    },
+                },
+            });
+            const executeRead = readTool.execute.bind(readTool);
+            readTool.execute = async (toolCallId, params, signal, onUpdate, context) => {
+                await authorizer.authorize('read', resolvePiToolPath(workingDir, params.path));
+                return executeRead(toolCallId, params, signal, onUpdate, context);
+            };
+            tools.push(readTool);
+        }
+        if (filesystemPermissions.read && allowsAggregateReadTools(filesystemPermissions.read)) {
+            if (this.isToolEnabled('Grep', true, agentTools)) {
+                const grepTool = createGrepToolDefinition(workingDir);
+                const executeGrep = grepTool.execute.bind(grepTool);
+                grepTool.execute = async (toolCallId, params, signal, onUpdate, context) => {
+                    await authorizer.authorize('read', resolvePiToolPath(workingDir, params.path ?? '.'));
+                    return executeGrep(toolCallId, params, signal, onUpdate, context);
+                };
+                tools.push(grepTool);
+            }
+            if (this.isToolEnabled('Glob', true, agentTools)) {
+                const findTool = createFindToolDefinition(workingDir);
+                const executeFind = findTool.execute.bind(findTool);
+                findTool.execute = async (toolCallId, params, signal, onUpdate, context) => {
+                    if (isAbsolute(params.pattern) ||
+                        params.pattern.replaceAll('\\', '/').split('/').includes('..')) {
+                        throw new Error(`Agent find pattern must stay within its search root: ${params.pattern}`);
+                    }
+                    await authorizer.authorize('read', resolvePiToolPath(workingDir, params.path ?? '.'));
+                    return executeFind(toolCallId, params, signal, onUpdate, context);
+                };
+                tools.push(findTool);
+                const lsTool = createLsToolDefinition(workingDir);
+                const executeLs = lsTool.execute.bind(lsTool);
+                lsTool.execute = async (toolCallId, params, signal, onUpdate, context) => {
+                    await authorizer.authorize('read', resolvePiToolPath(workingDir, params.path ?? '.'));
+                    return executeLs(toolCallId, params, signal, onUpdate, context);
+                };
+                tools.push(lsTool);
+            }
+        }
+        if (filesystemPermissions.write && this.isToolEnabled('Write', false, agentTools)) {
+            const writeTool = createWriteToolDefinition(workingDir, {
+                operations: {
+                    mkdir: async (directory) => mkdir(directory, { recursive: true }).then(() => undefined),
+                    writeFile: async (filePath, content) => {
+                        await authorizer.authorize('write', filePath);
+                        this.validateProposedWrite(workingDir, filePath, content);
+                        await writeFsFile(filePath, content, 'utf-8');
+                    },
+                },
+            });
+            const executeWrite = writeTool.execute.bind(writeTool);
+            writeTool.execute = async (toolCallId, params, signal, onUpdate, context) => {
+                const filePath = await authorizer.authorize('write', resolvePiToolPath(workingDir, params.path));
+                this.validateProposedWrite(workingDir, filePath, params.content);
+                const result = await executeWrite(toolCallId, params, signal, onUpdate, context);
+                return this.appendAfterMutationValidation(workingDir, filePath, result);
+            };
+            tools.push(writeTool);
+        }
+        if (filesystemPermissions.write && this.isToolEnabled('Edit', false, agentTools)) {
+            const editTool = createEditToolDefinition(workingDir, {
+                operations: {
+                    access: async (filePath) => {
+                        if (filesystemPermissions.read)
+                            await authorizer.authorize('read', filePath);
+                        await access(filePath, constants.R_OK | constants.W_OK);
+                    },
+                    readFile: async (filePath) => {
+                        if (filesystemPermissions.read)
+                            await authorizer.authorize('read', filePath);
+                        return readFsFile(filePath);
+                    },
+                    writeFile: async (filePath, content) => {
+                        await authorizer.authorize('write', filePath);
+                        this.validateProposedWrite(workingDir, filePath, content);
+                        await writeFsFile(filePath, content, 'utf-8');
+                    },
+                },
+            });
+            const executeEdit = editTool.execute.bind(editTool);
+            editTool.execute = async (toolCallId, params, signal, onUpdate, context) => {
+                const resolvedPath = resolvePiToolPath(workingDir, params.path);
+                const filePath = await authorizer.authorize('write', resolvedPath);
+                if (filesystemPermissions.read)
+                    await authorizer.authorize('read', resolvedPath);
+                const result = await executeEdit(toolCallId, params, signal, onUpdate, context);
+                return this.appendAfterMutationValidation(workingDir, filePath, result);
+            };
+            tools.push(editTool);
+        }
+        if (filesystemPermissions.delete && this.isToolEnabled('delete_file', false, agentTools)) {
+            tools.push({
+                name: 'delete_file',
+                label: 'delete_file',
+                description: 'Delete one file permitted by the current workflow policy.',
+                parameters: Type.Object({ path: Type.String({ minLength: 1 }) }),
+                execute: async (_toolCallId, params) => {
+                    const filePath = await authorizer.authorize('delete', params.path);
+                    await unlink(filePath);
+                    const result = {
+                        content: [{ type: 'text', text: `Deleted ${params.path}` }],
+                        details: { path: params.path },
+                    };
+                    return this.appendAfterMutationValidation(workingDir, filePath, result);
+                },
+            });
         }
         return tools;
     }
+    validateProposedWrite(workingDir, filePath, content) {
+        for (const validator of this.runtimeConfig.validation?.afterMutation ?? []) {
+            const root = resolveWithinWorkingDir(workingDir, validator.root, 'access');
+            const relativePath = relative(root, filePath);
+            if (relativePath === '' ||
+                relativePath === '..' ||
+                relativePath.startsWith(`..${sep}`) ||
+                isAbsolute(relativePath))
+                continue;
+            if (validator.name === 'okf-document') {
+                const validation = validateOkfDocument(content, toPosixPath(relativePath));
+                if (!validation.valid) {
+                    const errors = validation.errors
+                        .map((issue) => `- ${issue.path ?? relativePath}: [${issue.code}] ${issue.message}`)
+                        .join('\n');
+                    throw new Error(`Proposed write failed ${validator.name} validation:\n${errors}`);
+                }
+            }
+        }
+    }
+    async appendAfterMutationValidation(workingDir, filePath, result) {
+        const feedback = [];
+        for (const validator of this.runtimeConfig.validation?.afterMutation ?? []) {
+            const root = resolveWithinWorkingDir(workingDir, validator.root, 'access');
+            const relativePath = relative(root, filePath);
+            if (relativePath === '' ||
+                relativePath === '..' ||
+                relativePath.startsWith(`..${sep}`) ||
+                isAbsolute(relativePath))
+                continue;
+            if (validator.name === 'okf-document') {
+                const validation = await validateOkfBundle(workingDir, validator.root);
+                feedback.push(validation.valid
+                    ? `OKF bundle validation passed with ${validation.warnings.length} warning(s).`
+                    : `OKF bundle validation found ${validation.errors.length} error(s):\n${formatOkfValidationErrors(validation)}`);
+            }
+        }
+        if (feedback.length === 0)
+            return result;
+        return {
+            ...result,
+            content: [...result.content, { type: 'text', text: feedback.join('\n') }],
+        };
+    }
     resolveSkillSearchPaths(cwd) {
         const configuredPaths = this.runtimeConfig.skillSearchPaths ?? [];
         if (configuredPaths.length === 0) {
-            return [join(cwd, '.drs', 'skills'), join(cwd, '.pi', 'skills')];
+            return [
+                join(cwd, '.agents', 'skills'),
+                join(cwd, '.drs', 'skills'),
+                join(cwd, '.pi', 'skills'),
+            ];
         }
         return configuredPaths.map((skillPath) => normalizeSkillPath(cwd, skillPath));
     }
@@ -765,18 +994,30 @@ class PiSessionRuntime {
     }
     resolveCustomTools(workingDir, agentTools) {
         const customTools = [];
-        if (this.isToolEnabled('write_json_output', true, agentTools)) {
+        const filesystemPermissions = this.runtimeConfig.permissions?.filesystem;
+        const authorizer = filesystemPermissions
+            ? new AgentFilesystemAuthorizer(workingDir, filesystemPermissions)
+            : undefined;
+        if ((!filesystemPermissions || filesystemPermissions.write !== undefined) &&
+            this.isToolEnabled('write_json_output', true, agentTools)) {
             customTools.push({
                 name: 'write_json_output',
                 label: 'write_json_output',
                 description: 'Validate and write structured JSON output for DRS agents.',
                 parameters: Type.Object({
-                    outputType: Type.Union([Type.Literal('describe_output'), Type.Literal('review_output')]),
+                    outputType: Type.Literal('describe_output'),
                     payload: Type.Any(),
                     pretty: Type.Optional(Type.Boolean()),
                     indent: Type.Optional(Type.Number({ minimum: 2, maximum: 8 })),
                 }),
                 execute: async (_toolCallId, params) => {
+                    const outputPath = OUTPUT_PATHS[params.outputType];
+                    const filePath = authorizer
+                        ? await authorizer.authorize('write', outputPath)
+                        : resolveWithinWorkingDir(workingDir, outputPath, 'write');
+                    const jsonValue = typeof params.payload === 'string' ? JSON.parse(params.payload) : params.payload;
+                    const spacing = params.pretty === false ? undefined : (params.indent ?? 2);
+                    this.validateProposedWrite(workingDir, filePath, JSON.stringify(jsonValue, null, spacing));
                     const pointer = await writeJsonOutput({
                         outputType: params.outputType,
                         payload: params.payload,
@@ -784,14 +1025,16 @@ class PiSessionRuntime {
                         indent: params.indent,
                         workingDir,
                     });
-                    return {
+                    const result = {
                         content: [{ type: 'text', text: JSON.stringify(pointer) }],
                         details: pointer,
                     };
+                    return this.appendAfterMutationValidation(workingDir, filePath, result);
                 },
             });
         }
-        if (this.isToolEnabled('write_artifact_output', false, agentTools)) {
+        if ((!filesystemPermissions || filesystemPermissions.write !== undefined) &&
+            this.isToolEnabled('write_artifact_output', false, agentTools)) {
             customTools.push({
                 name: 'write_artifact_output',
                 label: 'write_artifact_output',
@@ -801,19 +1044,26 @@ class PiSessionRuntime {
                     content: Type.String({ minLength: 1 }),
                 }),
                 execute: async (_toolCallId, params) => {
+                    const filePath = authorizer
+                        ? await authorizer.authorize('write', params.outputPath)
+                        : resolveWithinWorkingDir(workingDir, params.outputPath, 'write');
+                    const html = extractHtmlDocument(params.content);
+                    this.validateProposedWrite(workingDir, filePath, html);
                     const pointer = await writeArtifactOutput({
                         outputPath: params.outputPath,
                         content: params.content,
                         workingDir,
                     });
-                    return {
+                    const result = {
                         content: [{ type: 'text', text: JSON.stringify(pointer) }],
                         details: pointer,
                     };
+                    return this.appendAfterMutationValidation(workingDir, filePath, result);
                 },
             });
         }
-        if (this.isToolEnabled('git_diff', false, agentTools)) {
+        if ((!filesystemPermissions?.read || allowsFullRepositoryRead(filesystemPermissions.read)) &&
+            this.isToolEnabled('git_diff', false, agentTools)) {
             customTools.push({
                 name: 'git_diff',
                 label: 'git_diff',
@@ -883,6 +1133,7 @@ class PiSessionRuntime {
                 execute: async (_toolCallId, params) => {
                     const { readFile } = await import('fs/promises');
                     try {
+                        await authorizer?.authorize('read', params.artifactPath);
                         const fullPath = resolveWithinWorkingDir(workingDir, params.artifactPath, 'read');
                         const raw = JSON.parse(await readFile(fullPath, 'utf-8'));
                         if (findingIdParamProvided(params)) {
@@ -932,7 +1183,9 @@ class PiSessionRuntime {
                 },
             });
         }
-        if (this.isToolEnabled('drs_check', false, agentTools) && this.runtimeConfig.fixChecks) {
+        if (this.runtimeConfig.permissions?.shell !== false &&
+            this.isToolEnabled('drs_check', false, agentTools) &&
+            this.runtimeConfig.fixChecks) {
             const configuredChecks = this.runtimeConfig.fixChecks;
             customTools.push({
                 name: 'drs_check',
@@ -1004,6 +1257,7 @@ class PiSessionRuntime {
         const resourceLoader = new DefaultResourceLoader({
             cwd,
             agentDir: getAgentDir(),
+            noExtensions: this.runtimeConfig.permissions !== undefined,
             noSkills: true,
             additionalSkillPaths: skillSearchPaths,
             skillsOverride: configuredSkillNames.size > 0
@@ -1038,7 +1292,10 @@ class PiSessionRuntime {
                 },
             })
             : undefined;
-        const customTools = this.resolveCustomTools(cwd, settings.tools);
+        const customTools = [
+            ...this.resolveCustomTools(cwd, settings.tools),
+            ...this.resolvePermissionTools(cwd, settings.tools),
+        ];
         const tools = [
             ...this.resolveTools(cwd, settings.tools),
             ...customTools.map((tool) => tool.name),