vgxness 0.1.0

package/dist/runs/execution-planning.js

@@ -0,0 +1,117 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { planWorktreeSandbox } from './sandbox-worktree-planning.js';
+const filesystemCategories = new Set(['read', 'edit', 'external-directory']);
+export function planExecutionIsolation(input) {
+    const { operation, decision } = input;
+    const strategy = selectStrategy(operation, decision);
+    const sandbox = worktreeSandboxPlan(operation, strategy, input.gitBoundaryInspector);
+    const realpathHardeningRequired = requiresRealpathHardening(operation);
+    const requiredApprovals = approvalRequirements(operation, decision);
+    const requiredConditions = conditionRequirements(operation, decision, realpathHardeningRequired, sandbox);
+    const limitations = planLimitations(operation, decision, strategy, sandbox);
+    return {
+        strategy,
+        pathConstraints: pathConstraints(operation),
+        ...(sandbox === undefined ? {} : { sandbox }),
+        realpathHardeningRequired,
+        requiredApprovals,
+        requiredConditions,
+        limitations,
+        executable: decision.decision === 'allow' && sandbox?.decision !== 'rejected',
+        executesProvider: false,
+        createsWorktree: false,
+    };
+}
+function selectStrategy(operation, decision) {
+    if (operation.sandboxStrategy === 'worktree')
+        return 'worktree';
+    if (decision.decision === 'deny') {
+        return operation.category === 'external-directory' || operation.external === true
+            ? 'process-sandbox'
+            : 'workspace';
+    }
+    if (operation.category === 'shell' || operation.category === 'network' || operation.category === 'provider-tool' || operation.privileged === true) {
+        return 'process-sandbox';
+    }
+    if (operation.category === 'edit' || operation.category === 'git' || operation.destructive === true) {
+        return 'worktree';
+    }
+    return 'workspace';
+}
+function pathConstraints(operation) {
+    return {
+        ...(operation.workspaceRoot === undefined ? {} : { workspaceRoot: operation.workspaceRoot }),
+        ...(operation.targetPath === undefined ? {} : { targetPath: operation.targetPath }),
+        enforceWorkspaceBoundary: operation.category !== 'external-directory',
+        allowExternalPaths: false,
+    };
+}
+function requiresRealpathHardening(operation) {
+    return filesystemCategories.has(operation.category)
+        || operation.workspaceRoot !== undefined
+        || operation.targetPath !== undefined;
+}
+function approvalRequirements(operation, decision) {
+    const approvals = [];
+    if (decision.decision === 'ask')
+        approvals.push(`human-approval:${decision.reason}`);
+    if (operation.destructive === true)
+        approvals.push('destructive-operation-approval');
+    if (operation.external === true || operation.category === 'external-directory')
+        approvals.push('external-access-approval');
+    if (operation.privileged === true)
+        approvals.push('privileged-operation-approval');
+    if (operation.ambiguous === true)
+        approvals.push('clarify-ambiguous-operation');
+    return [...new Set(approvals)];
+}
+function conditionRequirements(operation, decision, realpathHardeningRequired, sandbox) {
+    const conditions = ['permission-decision-recorded'];
+    if (decision.decision === 'deny')
+        conditions.push('blocked-by-policy-before-execution');
+    if (sandbox?.decision === 'rejected')
+        conditions.push(`blocked-by-sandbox-planning:${sandbox.reason ?? 'unknown'}`);
+    if (decision.decision === 'ask')
+        conditions.push('approved-before-execution');
+    if (realpathHardeningRequired)
+        conditions.push('resolve-realpath-and-recheck-workspace-boundary-before-execution');
+    if (operation.category === 'edit' || operation.category === 'git' || operation.destructive === true)
+        conditions.push('isolated-worktree-or-equivalent-before-mutation');
+    if (operation.category === 'shell' || operation.category === 'network' || operation.category === 'provider-tool')
+        conditions.push('sandboxed-process-or-equivalent-before-provider-execution');
+    return conditions;
+}
+function planLimitations(operation, decision, strategy, sandbox) {
+    const limitations = [
+        'planning-only: no command, provider tool, worktree, sandbox, directory, or filesystem mutation is performed',
+    ];
+    if (strategy === 'worktree')
+        limitations.push('worktree is a planned isolation target only; creation is future executor work');
+    if (strategy === 'process-sandbox')
+        limitations.push('process-sandbox is a planned isolation target only; launch/enforcement is future executor work');
+    if (decision.decision === 'deny')
+        limitations.push(`permission policy denies execution: ${decision.reason}`);
+    if (sandbox?.decision === 'rejected')
+        limitations.push(`sandbox planning rejects execution: ${sandbox.audit.validationSummary}`);
+    if (operation.category === 'external-directory')
+        limitations.push('external directory execution remains denied by default even when a stronger future sandbox is selected');
+    return limitations;
+}
+function worktreeSandboxPlan(operation, strategy, gitBoundaryInspector) {
+    if (strategy !== 'worktree')
+        return undefined;
+    if (operation.workspaceRoot === undefined || operation.targetPath === undefined)
+        return undefined;
+    return planWorktreeSandbox({
+        workspaceRoot: operation.workspaceRoot,
+        targetPath: operation.targetPath,
+        gitBoundaryInspector: gitBoundaryInspector ?? defaultGitBoundaryInspector,
+    });
+}
+const defaultGitBoundaryInspector = ({ workspaceRoot }) => {
+    if (existsSync(join(workspaceRoot, '.git'))) {
+        return { status: 'compatible', reason: 'workspace git metadata is present' };
+    }
+    return { status: 'uncertain', reason: 'workspace git metadata could not be proven safe without shell execution' };
+};

package/dist/runs/operation-execution.js

@@ -0,0 +1 @@
+export {};

package/dist/runs/operation-retry.js

@@ -0,0 +1,124 @@
+const defaultRetryPolicy = { mode: 'never' };
+const operationRetryPolicyModes = ['never', 'after-abandoned', 'after-failure', 'after-failure-or-abandoned'];
+const allowedRetryableStatuses = ['failed', 'abandoned'];
+export function defaultOperationRetryPolicy() {
+    return defaultRetryPolicy;
+}
+export function parseOperationRetryPolicy(input) {
+    if (input === undefined) {
+        return { ok: true, policy: defaultRetryPolicy };
+    }
+    if (!isRecord(input) || Array.isArray(input)) {
+        return { ok: false, errors: ['Retry policy must be an object'] };
+    }
+    const allowedKeys = new Set(['mode', 'retryableStatuses']);
+    const unknownKeys = Object.keys(input).filter((key) => !allowedKeys.has(key));
+    const errors = unknownKeys.map((key) => `Unknown retry policy field: ${key}`);
+    const mode = input.mode;
+    if (!isOperationRetryPolicyMode(mode)) {
+        errors.push('Retry policy mode must be one of: never, after-abandoned, after-failure, after-failure-or-abandoned');
+    }
+    if ('retryableStatuses' in input) {
+        const retryableStatuses = input.retryableStatuses;
+        if (!Array.isArray(retryableStatuses)) {
+            errors.push('Retry policy retryableStatuses must be an array');
+        }
+        else {
+            const invalidStatuses = retryableStatuses.filter((status) => !isAllowedRetryableStatus(status));
+            if (invalidStatuses.length > 0) {
+                errors.push(`Retry policy retryableStatuses contains invalid retryable status: ${invalidStatuses.map(String).join(', ')}`);
+            }
+            if (new Set(retryableStatuses).size !== retryableStatuses.length) {
+                errors.push('Retry policy retryableStatuses must not contain duplicates');
+            }
+            if (isOperationRetryPolicyMode(mode) && invalidStatuses.length === 0) {
+                const expectedStatuses = retryableStatusesFor({ mode });
+                if (!sameStatuses(retryableStatuses, expectedStatuses)) {
+                    errors.push(`Retry policy retryableStatuses must match mode ${mode}: ${expectedStatuses.length === 0 ? '[]' : expectedStatuses.join(', ')}`);
+                }
+            }
+        }
+    }
+    if (errors.length > 0 || !isOperationRetryPolicyMode(mode)) {
+        return { ok: false, errors };
+    }
+    return { ok: true, policy: { mode } };
+}
+export function evaluateOperationRetry(input) {
+    const policy = input.policy ?? defaultRetryPolicy;
+    const retryableStatuses = retryableStatusesFor(policy);
+    const attempts = [...input.attempts].sort(compareAttempts);
+    const activeAttempt = attempts.find((attempt) => attempt.status === 'reserved');
+    if (activeAttempt !== undefined) {
+        const latestAttempt = attempts.at(-1);
+        return {
+            allowed: false,
+            policy,
+            reasonCode: 'active_attempt_reserved',
+            reason: `Retry blocked because attempt ${activeAttempt.id} is still reserved`,
+            evaluatedAttemptCount: attempts.length,
+            retryableStatuses,
+            activeAttempt,
+            ...(latestAttempt === undefined ? {} : { latestAttempt }),
+        };
+    }
+    const latestAttempt = attempts.at(-1);
+    if (latestAttempt === undefined) {
+        return {
+            allowed: true,
+            policy,
+            reasonCode: 'initial_attempt_allowed',
+            reason: 'No previous operation attempt exists for this approval',
+            evaluatedAttemptCount: 0,
+            retryableStatuses,
+        };
+    }
+    if (latestAttempt.status === 'succeeded') {
+        return block(policy, retryableStatuses, attempts.length, latestAttempt, 'already_succeeded', `Retry blocked because latest attempt ${latestAttempt.id} already succeeded`);
+    }
+    if (policy.mode === 'never') {
+        return block(policy, retryableStatuses, attempts.length, latestAttempt, 'retry_disabled', `Retry blocked by policy never after ${latestAttempt.status}`);
+    }
+    if (retryableStatuses.includes(latestAttempt.status)) {
+        return {
+            allowed: true,
+            policy,
+            reasonCode: 'status_allowed_by_policy',
+            reason: `Retry allowed by policy ${policy.mode} after ${latestAttempt.status}`,
+            evaluatedAttemptCount: attempts.length,
+            retryableStatuses,
+            latestAttempt,
+        };
+    }
+    return block(policy, retryableStatuses, attempts.length, latestAttempt, 'status_not_allowed_by_policy', `Retry blocked by policy ${policy.mode} after ${latestAttempt.status}`);
+}
+function block(policy, retryableStatuses, evaluatedAttemptCount, latestAttempt, reasonCode, reason) {
+    return { allowed: false, policy, reasonCode, reason, evaluatedAttemptCount, retryableStatuses, latestAttempt };
+}
+function retryableStatusesFor(policy) {
+    switch (policy.mode) {
+        case 'after-abandoned':
+            return ['abandoned'];
+        case 'after-failure':
+            return ['failed'];
+        case 'after-failure-or-abandoned':
+            return ['failed', 'abandoned'];
+        case 'never':
+            return [];
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isOperationRetryPolicyMode(value) {
+    return typeof value === 'string' && operationRetryPolicyModes.includes(value);
+}
+function isAllowedRetryableStatus(value) {
+    return typeof value === 'string' && allowedRetryableStatuses.includes(value);
+}
+function sameStatuses(actual, expected) {
+    return actual.length === expected.length && actual.every((status) => expected.includes(status));
+}
+function compareAttempts(a, b) {
+    return a.attemptSequence - b.attemptSequence || a.reservedAt.localeCompare(b.reservedAt) || a.id.localeCompare(b.id);
+}