forkit-connect 0.1.0

package/dist/ps-list-loader.d.ts

@@ -0,0 +1,5 @@
+type PsListModule = typeof import('ps-list');
+export declare function loadPsList(): Promise<PsListModule['default']>;
+export declare function listProcesses(): ReturnType<PsListModule['default']>;
+export {};
+//# sourceMappingURL=ps-list-loader.d.ts.map

package/dist/ps-list-loader.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPsList = loadPsList;
+exports.listProcesses = listProcesses;
+// `ps-list` is ESM-only; load it lazily so the CommonJS Connect build can still run.
+const importPsList = new Function('specifier', 'return import(specifier)');
+let cachedPsList = null;
+async function loadPsList() {
+    if (cachedPsList) {
+        return cachedPsList;
+    }
+    const module = await importPsList('ps-list');
+    cachedPsList = module.default;
+    return cachedPsList;
+}
+async function listProcesses() {
+    const psList = await loadPsList();
+    return await psList();
+}
+//# sourceMappingURL=ps-list-loader.js.map

package/dist/v1/agent-observation.d.ts

@@ -0,0 +1,42 @@
+export type ObservedAgentToolName = 'list_workspace_files' | 'read_workspace_file' | 'search_workspace_text' | 'run_workspace_command';
+export type ObservedAgentToolDecision = 'allowed' | 'blocked' | 'timed_out' | 'error';
+export interface ObservedAgentToolCallInput {
+    workspaceRoot: string;
+    toolName: ObservedAgentToolName;
+    path?: string | null;
+    query?: string | null;
+    command?: string | null;
+    args?: string[];
+    limit?: number | null;
+    timeoutMs?: number | null;
+    maxBytes?: number | null;
+    maxOutputBytes?: number | null;
+}
+export interface ObservedAgentToolMatch {
+    path: string;
+    line: number;
+    text: string;
+}
+export interface ObservedAgentToolCallOutput {
+    files?: string[];
+    content?: string;
+    matches?: ObservedAgentToolMatch[];
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number | null;
+    truncated?: boolean;
+}
+export interface ObservedAgentToolCallResult {
+    decision: ObservedAgentToolDecision;
+    toolName: ObservedAgentToolName;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    blockedReason: string | null;
+    metadata: Record<string, unknown>;
+    output: ObservedAgentToolCallOutput;
+}
+export declare function normalizeObservationWorkspaceRoot(workspaceRoot: string): string;
+export declare function hashObservationWorkspaceRoot(workspaceRoot: string): string;
+export declare function runObservedAgentToolCall(input: ObservedAgentToolCallInput): Promise<ObservedAgentToolCallResult>;
+//# sourceMappingURL=agent-observation.d.ts.map

package/dist/v1/agent-observation.js

@@ -0,0 +1,499 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeObservationWorkspaceRoot = normalizeObservationWorkspaceRoot;
+exports.hashObservationWorkspaceRoot = hashObservationWorkspaceRoot;
+exports.runObservedAgentToolCall = runObservedAgentToolCall;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const DEFAULT_LIST_LIMIT = 200;
+const DEFAULT_SEARCH_LIMIT = 50;
+const DEFAULT_READ_BYTES = 32 * 1024;
+const DEFAULT_COMMAND_TIMEOUT_MS = 8_000;
+const DEFAULT_COMMAND_OUTPUT_BYTES = 16 * 1024;
+const MAX_DEPTH = 6;
+const SEARCH_FILE_BYTES_LIMIT = 512 * 1024;
+const SKIPPED_DIRECTORY_NAMES = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.turbo',
+]);
+const READ_ONLY_COMMAND_ALLOWLIST = new Set(['git', 'rg', 'cat', 'head', 'tail', 'wc']);
+const GIT_ALLOWED_SUBCOMMANDS = new Set(['status', 'diff', 'log', 'show', 'branch', 'rev-parse']);
+const GIT_BLOCKED_FLAGS = new Set(['-C', '--git-dir', '--work-tree']);
+const RIPGREP_BLOCKED_FLAGS = new Set(['--pre', '--pre-glob']);
+const TAIL_ALLOWED_FLAGS = new Set(['-f', '-n']);
+const HEAD_ALLOWED_FLAGS = new Set(['-n']);
+const WC_ALLOWED_FLAGS = new Set(['-l', '-c', '-m', '-w']);
+function nowIso() {
+    return new Date().toISOString();
+}
+function hashText(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(value, 'utf8').digest('hex');
+}
+function sanitizeText(value, maxLength) {
+    return value.trim().slice(0, maxLength);
+}
+function boundedInt(value, fallback, min, max) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.floor(numeric)));
+}
+function pathToPosix(value) {
+    return value.split(node_path_1.default.sep).join('/');
+}
+function normalizeObservationWorkspaceRoot(workspaceRoot) {
+    const candidate = String(workspaceRoot || '').trim();
+    if (!candidate) {
+        throw new Error('WORKSPACE_ROOT_REQUIRED');
+    }
+    const resolved = node_fs_1.default.realpathSync.native(node_path_1.default.resolve(candidate));
+    const stats = node_fs_1.default.statSync(resolved);
+    if (!stats.isDirectory()) {
+        throw new Error('WORKSPACE_ROOT_NOT_DIRECTORY');
+    }
+    return resolved;
+}
+function hashObservationWorkspaceRoot(workspaceRoot) {
+    return hashText(normalizeObservationWorkspaceRoot(workspaceRoot));
+}
+function isInsideWorkspace(workspaceRoot, candidatePath) {
+    const relative = node_path_1.default.relative(workspaceRoot, candidatePath);
+    return relative === ''
+        || (!relative.startsWith('..') && !node_path_1.default.isAbsolute(relative));
+}
+function resolveScopedPath(workspaceRoot, candidate, allowWorkspaceRoot = true) {
+    const raw = String(candidate || '.').trim() || '.';
+    const absoluteCandidate = node_path_1.default.resolve(workspaceRoot, raw);
+    const absolutePath = node_fs_1.default.realpathSync.native(absoluteCandidate);
+    if (!isInsideWorkspace(workspaceRoot, absolutePath)) {
+        throw new Error('PATH_OUTSIDE_WORKSPACE');
+    }
+    const stats = node_fs_1.default.statSync(absolutePath);
+    if (!allowWorkspaceRoot && absolutePath === workspaceRoot) {
+        throw new Error('FILE_PATH_REQUIRED');
+    }
+    return {
+        absolutePath,
+        relativePath: absolutePath === workspaceRoot ? '.' : pathToPosix(node_path_1.default.relative(workspaceRoot, absolutePath)),
+        stats,
+    };
+}
+function collectWorkspaceFiles(workspaceRoot, directoryPath, limit) {
+    const results = [];
+    let truncated = false;
+    function walk(currentPath, depth) {
+        if (results.length >= limit || depth > MAX_DEPTH) {
+            truncated = truncated || results.length >= limit;
+            return;
+        }
+        const entries = node_fs_1.default.readdirSync(currentPath, { withFileTypes: true })
+            .sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            if (results.length >= limit) {
+                truncated = true;
+                break;
+            }
+            if (entry.name.startsWith('.DS_Store')) {
+                continue;
+            }
+            if (entry.isDirectory() && SKIPPED_DIRECTORY_NAMES.has(entry.name)) {
+                continue;
+            }
+            const absoluteEntryPath = node_path_1.default.join(currentPath, entry.name);
+            const relativeEntryPath = absoluteEntryPath === workspaceRoot
+                ? '.'
+                : pathToPosix(node_path_1.default.relative(workspaceRoot, absoluteEntryPath));
+            if (entry.isDirectory()) {
+                walk(absoluteEntryPath, depth + 1);
+                continue;
+            }
+            if (entry.isFile()) {
+                results.push(relativeEntryPath);
+            }
+        }
+    }
+    walk(directoryPath, 0);
+    return {
+        files: results,
+        truncated,
+    };
+}
+function readWorkspaceFile(workspaceRoot, candidatePath, maxBytes) {
+    const startedAt = nowIso();
+    const startedMs = Date.now();
+    const { absolutePath, relativePath, stats } = resolveScopedPath(workspaceRoot, candidatePath, false);
+    if (!stats.isFile()) {
+        throw new Error('FILE_PATH_REQUIRED');
+    }
+    const raw = node_fs_1.default.readFileSync(absolutePath);
+    const truncated = raw.byteLength > maxBytes;
+    const content = raw.subarray(0, maxBytes).toString('utf8');
+    return {
+        decision: 'allowed',
+        toolName: 'read_workspace_file',
+        startedAt,
+        finishedAt: nowIso(),
+        durationMs: Date.now() - startedMs,
+        blockedReason: null,
+        metadata: {
+            relative_path_hash: hashText(relativePath),
+            relative_path_depth: relativePath === '.' ? 0 : relativePath.split('/').length,
+            file_extension: node_path_1.default.extname(relativePath) || null,
+            bytes_requested: maxBytes,
+            bytes_available: raw.byteLength,
+            bytes_returned: Buffer.byteLength(content, 'utf8'),
+        },
+        output: {
+            content,
+            truncated,
+        },
+    };
+}
+function searchWorkspaceText(workspaceRoot, candidatePath, query, limit) {
+    const startedAt = nowIso();
+    const startedMs = Date.now();
+    const scopedPath = resolveScopedPath(workspaceRoot, candidatePath, true);
+    const matches = [];
+    let scannedFiles = 0;
+    let truncated = false;
+    const searchTargets = scopedPath.stats.isDirectory()
+        ? collectWorkspaceFiles(workspaceRoot, scopedPath.absolutePath, Math.max(limit * 4, limit))
+            .files
+            .map((relativePath) => node_path_1.default.join(workspaceRoot, relativePath))
+        : [scopedPath.absolutePath];
+    for (const absolutePath of searchTargets) {
+        if (matches.length >= limit) {
+            truncated = true;
+            break;
+        }
+        const stats = node_fs_1.default.statSync(absolutePath);
+        if (!stats.isFile() || stats.size > SEARCH_FILE_BYTES_LIMIT) {
+            continue;
+        }
+        scannedFiles += 1;
+        const relativePath = absolutePath === workspaceRoot ? '.' : pathToPosix(node_path_1.default.relative(workspaceRoot, absolutePath));
+        const content = node_fs_1.default.readFileSync(absolutePath, 'utf8');
+        const lines = content.split(/\r?\n/);
+        for (let index = 0; index < lines.length; index += 1) {
+            if (!lines[index]?.includes(query)) {
+                continue;
+            }
+            matches.push({
+                path: relativePath,
+                line: index + 1,
+                text: sanitizeText(String(lines[index]), 240),
+            });
+            if (matches.length >= limit) {
+                truncated = true;
+                break;
+            }
+        }
+    }
+    return {
+        decision: 'allowed',
+        toolName: 'search_workspace_text',
+        startedAt,
+        finishedAt: nowIso(),
+        durationMs: Date.now() - startedMs,
+        blockedReason: null,
+        metadata: {
+            query_hash: hashText(query),
+            query_length: query.length,
+            relative_path_hash: hashText(scopedPath.relativePath),
+            scanned_files: scannedFiles,
+            match_count: matches.length,
+        },
+        output: {
+            matches,
+            truncated,
+        },
+    };
+}
+function listWorkspaceFiles(workspaceRoot, candidatePath, limit) {
+    const startedAt = nowIso();
+    const startedMs = Date.now();
+    const scopedPath = resolveScopedPath(workspaceRoot, candidatePath, true);
+    if (!scopedPath.stats.isDirectory()) {
+        throw new Error('DIRECTORY_PATH_REQUIRED');
+    }
+    const { files, truncated } = collectWorkspaceFiles(workspaceRoot, scopedPath.absolutePath, limit);
+    return {
+        decision: 'allowed',
+        toolName: 'list_workspace_files',
+        startedAt,
+        finishedAt: nowIso(),
+        durationMs: Date.now() - startedMs,
+        blockedReason: null,
+        metadata: {
+            relative_path_hash: hashText(scopedPath.relativePath),
+            result_count: files.length,
+        },
+        output: {
+            files,
+            truncated,
+        },
+    };
+}
+function validateFlagSet(args, allowedFlags) {
+    for (const arg of args) {
+        if (!arg.startsWith('-')) {
+            continue;
+        }
+        if (!allowedFlags.has(arg) && ![...allowedFlags].some((candidate) => arg.startsWith(`${candidate}=`))) {
+            throw new Error('COMMAND_FLAG_NOT_ALLOWED');
+        }
+    }
+}
+function maybeValidatePathArgument(workspaceRoot, arg) {
+    const trimmed = arg.trim();
+    if (!trimmed)
+        return;
+    if (trimmed.includes('\u0000') || trimmed.includes('\n') || trimmed.includes('\r')) {
+        throw new Error('COMMAND_ARGUMENT_INVALID');
+    }
+    const looksAbsolute = node_path_1.default.isAbsolute(trimmed);
+    const looksRelative = trimmed === '.'
+        || trimmed === '..'
+        || trimmed.startsWith(`.${node_path_1.default.sep}`)
+        || trimmed.startsWith(`..${node_path_1.default.sep}`)
+        || trimmed.startsWith('./')
+        || trimmed.startsWith('../');
+    const containsPathSeparator = trimmed.includes(node_path_1.default.sep) || trimmed.includes('/');
+    const candidateAbsolutePath = node_path_1.default.resolve(workspaceRoot, trimmed);
+    const existsInWorkspace = node_fs_1.default.existsSync(candidateAbsolutePath);
+    if (!looksAbsolute && !looksRelative && !containsPathSeparator && !existsInWorkspace) {
+        return;
+    }
+    const pathToCheck = node_fs_1.default.existsSync(candidateAbsolutePath)
+        ? node_fs_1.default.realpathSync.native(candidateAbsolutePath)
+        : candidateAbsolutePath;
+    if (!isInsideWorkspace(workspaceRoot, pathToCheck)) {
+        throw new Error('COMMAND_PATH_OUTSIDE_WORKSPACE');
+    }
+}
+function validateWorkspaceCommand(workspaceRoot, command, args) {
+    if (!READ_ONLY_COMMAND_ALLOWLIST.has(command)) {
+        throw new Error('COMMAND_NOT_ALLOWED');
+    }
+    if (command === 'git') {
+        const subcommand = args.find((arg) => !arg.startsWith('-'));
+        if (!subcommand || !GIT_ALLOWED_SUBCOMMANDS.has(subcommand)) {
+            throw new Error('COMMAND_NOT_ALLOWED');
+        }
+        for (const arg of args) {
+            if (GIT_BLOCKED_FLAGS.has(arg) || arg.startsWith('--git-dir=') || arg.startsWith('--work-tree=')) {
+                throw new Error('COMMAND_FLAG_NOT_ALLOWED');
+            }
+            maybeValidatePathArgument(workspaceRoot, arg);
+        }
+        return;
+    }
+    if (command === 'rg') {
+        for (const arg of args) {
+            if (RIPGREP_BLOCKED_FLAGS.has(arg) || arg.startsWith('--pre=')) {
+                throw new Error('COMMAND_FLAG_NOT_ALLOWED');
+            }
+            maybeValidatePathArgument(workspaceRoot, arg);
+        }
+        return;
+    }
+    if (command === 'tail') {
+        validateFlagSet(args.filter((arg) => arg.startsWith('-')), TAIL_ALLOWED_FLAGS);
+    }
+    else if (command === 'head') {
+        validateFlagSet(args.filter((arg) => arg.startsWith('-')), HEAD_ALLOWED_FLAGS);
+    }
+    else if (command === 'wc') {
+        validateFlagSet(args.filter((arg) => arg.startsWith('-')), WC_ALLOWED_FLAGS);
+    }
+    else if (command === 'cat' && args.some((arg) => arg.startsWith('-'))) {
+        throw new Error('COMMAND_FLAG_NOT_ALLOWED');
+    }
+    for (const arg of args) {
+        if (arg.startsWith('-')) {
+            continue;
+        }
+        maybeValidatePathArgument(workspaceRoot, arg);
+    }
+}
+async function runWorkspaceCommand(workspaceRoot, command, args, timeoutMs, maxOutputBytes) {
+    const startedAt = nowIso();
+    const startedMs = Date.now();
+    validateWorkspaceCommand(workspaceRoot, command, args);
+    return new Promise((resolve) => {
+        const child = (0, node_child_process_1.spawn)(command, args, {
+            cwd: workspaceRoot,
+            env: {
+                ...process.env,
+                CI: process.env.CI || '1',
+            },
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let truncated = false;
+        let finished = false;
+        let timedOut = false;
+        const capture = (buffer, current, currentBytes) => {
+            if (currentBytes >= maxOutputBytes) {
+                truncated = true;
+                return { next: current, nextBytes: currentBytes };
+            }
+            const remainingBytes = maxOutputBytes - currentBytes;
+            const slice = buffer.subarray(0, remainingBytes);
+            if (slice.byteLength < buffer.byteLength) {
+                truncated = true;
+            }
+            return {
+                next: current + slice.toString('utf8'),
+                nextBytes: currentBytes + slice.byteLength,
+            };
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            setTimeout(() => child.kill('SIGKILL'), 250).unref();
+        }, timeoutMs);
+        child.stdout.on('data', (chunk) => {
+            const captured = capture(chunk, stdout, stdoutBytes);
+            stdout = captured.next;
+            stdoutBytes = captured.nextBytes;
+        });
+        child.stderr.on('data', (chunk) => {
+            const captured = capture(chunk, stderr, stderrBytes);
+            stderr = captured.next;
+            stderrBytes = captured.nextBytes;
+        });
+        child.on('error', (error) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            resolve({
+                decision: 'error',
+                toolName: 'run_workspace_command',
+                startedAt,
+                finishedAt: nowIso(),
+                durationMs: Date.now() - startedMs,
+                blockedReason: sanitizeText(error.message || 'Command execution failed.', 240),
+                metadata: {
+                    command,
+                    args_count: args.length,
+                    command_hash: hashText([command, ...args].join('\u001f')),
+                },
+                output: {
+                    stdout,
+                    stderr,
+                    exitCode: null,
+                    truncated,
+                },
+            });
+        });
+        child.on('close', (code) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            resolve({
+                decision: timedOut ? 'timed_out' : 'allowed',
+                toolName: 'run_workspace_command',
+                startedAt,
+                finishedAt: nowIso(),
+                durationMs: Date.now() - startedMs,
+                blockedReason: timedOut ? 'COMMAND_TIMED_OUT' : null,
+                metadata: {
+                    command,
+                    args_count: args.length,
+                    command_hash: hashText([command, ...args].join('\u001f')),
+                    timeout_ms: timeoutMs,
+                    stdout_bytes: stdoutBytes,
+                    stderr_bytes: stderrBytes,
+                },
+                output: {
+                    stdout,
+                    stderr,
+                    exitCode: code,
+                    truncated,
+                },
+            });
+        });
+    });
+}
+function blockedResult(toolName, blockedReason, metadata = {}) {
+    const startedAt = nowIso();
+    return {
+        decision: 'blocked',
+        toolName,
+        startedAt,
+        finishedAt: startedAt,
+        durationMs: 0,
+        blockedReason,
+        metadata,
+        output: {},
+    };
+}
+async function runObservedAgentToolCall(input) {
+    const workspaceRoot = normalizeObservationWorkspaceRoot(input.workspaceRoot);
+    try {
+        switch (input.toolName) {
+            case 'list_workspace_files':
+                return listWorkspaceFiles(workspaceRoot, input.path ?? '.', boundedInt(input.limit, DEFAULT_LIST_LIMIT, 1, 500));
+            case 'read_workspace_file':
+                return readWorkspaceFile(workspaceRoot, input.path, boundedInt(input.maxBytes, DEFAULT_READ_BYTES, 256, 256 * 1024));
+            case 'search_workspace_text': {
+                const query = String(input.query || '').trim();
+                if (!query) {
+                    return blockedResult('search_workspace_text', 'SEARCH_QUERY_REQUIRED');
+                }
+                return searchWorkspaceText(workspaceRoot, input.path ?? '.', query, boundedInt(input.limit, DEFAULT_SEARCH_LIMIT, 1, 200));
+            }
+            case 'run_workspace_command': {
+                const command = String(input.command || '').trim();
+                if (!command) {
+                    return blockedResult('run_workspace_command', 'COMMAND_REQUIRED');
+                }
+                return runWorkspaceCommand(workspaceRoot, command, Array.isArray(input.args) ? input.args.map((arg) => String(arg)) : [], boundedInt(input.timeoutMs, DEFAULT_COMMAND_TIMEOUT_MS, 250, 30_000), boundedInt(input.maxOutputBytes, DEFAULT_COMMAND_OUTPUT_BYTES, 512, 128 * 1024));
+            }
+            default:
+                return blockedResult(input.toolName, 'TOOL_NOT_SUPPORTED');
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const isBlocked = [
+            'WORKSPACE_ROOT_REQUIRED',
+            'WORKSPACE_ROOT_NOT_DIRECTORY',
+            'PATH_OUTSIDE_WORKSPACE',
+            'FILE_PATH_REQUIRED',
+            'DIRECTORY_PATH_REQUIRED',
+            'COMMAND_NOT_ALLOWED',
+            'COMMAND_FLAG_NOT_ALLOWED',
+            'COMMAND_ARGUMENT_INVALID',
+            'COMMAND_PATH_OUTSIDE_WORKSPACE',
+        ].includes(message);
+        return {
+            decision: isBlocked ? 'blocked' : 'error',
+            toolName: input.toolName,
+            startedAt: nowIso(),
+            finishedAt: nowIso(),
+            durationMs: 0,
+            blockedReason: isBlocked ? message : sanitizeText(message, 240),
+            metadata: {},
+            output: {},
+        };
+    }
+}
+//# sourceMappingURL=agent-observation.js.map