praxis-agent 0.40.0 → 0.42.0

package/dist/plugins/claude-plugin-runtime.js

@@ -1,3 +1,5 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
 import { cp, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
@@ -5,8 +7,34 @@ import { promisify } from 'node:util';
 import { parse as parseYaml } from 'yaml';
 import { countTokens } from '@anthropic-ai/tokenizer';
 import { claudePluginDataPath, materializeClaudePluginSource, readClaudePluginOptions, readClaudePluginMcpServerOptions, readClaudeSkillsDirectoryPlugins, replaceClaudePluginDirectory, readClaudeInstalledPlugins, validateClaudePluginUserConfig, } from './claude-plugin-marketplace.js';
-import { loadClaudePluginMcpb } from './claude-plugin-mcpb.js';
+import { CLAUDE_PLUGIN_MCPB_ARCHIVE_BYTES, loadClaudePluginMcpb, } from './claude-plugin-mcpb.js';
 const execFileAsync = promisify(execFile);
+async function boundedFileSha256(path) {
+    const metadata = await stat(path);
+    if (!metadata.isFile()) {
+        throw new Error(`MCPB archive must be a regular file: ${path}`);
+    }
+    if (metadata.size > CLAUDE_PLUGIN_MCPB_ARCHIVE_BYTES) {
+        throw new Error(`MCPB archive exceeds ${CLAUDE_PLUGIN_MCPB_ARCHIVE_BYTES} bytes`);
+    }
+    const source = createReadStream(path);
+    const hash = createHash('sha256');
+    let bytes = 0;
+    try {
+        for await (const chunk of source) {
+            const value = chunk;
+            bytes += value.byteLength;
+            if (bytes > CLAUDE_PLUGIN_MCPB_ARCHIVE_BYTES) {
+                throw new Error(`MCPB archive exceeds ${CLAUDE_PLUGIN_MCPB_ARCHIVE_BYTES} bytes`);
+            }
+            hash.update(value);
+        }
+        return hash.digest('hex');
+    }
+    finally {
+        source.destroy();
+    }
+}
 const PLUGIN_MANIFEST = join('.claude-plugin', 'plugin.json');
 const LEGACY_MANIFEST = 'plugin.json';
 const MAX_PLUGIN_FILES = 2_000;
@@ -139,6 +167,16 @@ function safePluginPath(pluginPath, candidate) {
     }
     return resolved;
 }
+async function canonicalPluginPath(pluginPath, candidate) {
+    const [root, resolved] = await Promise.all([
+        realpath(pluginPath),
+        realpath(candidate),
+    ]);
+    if (resolved !== root && !resolved.startsWith(`${root}/`)) {
+        throw new Error(`Plugin path escapes plugin root: ${candidate}`);
+    }
+    return resolved;
+}
 async function assertPluginPath(pluginPath, candidate) {
     let resolved;
     try {
@@ -462,7 +500,7 @@ async function loadLspServers(root, manifest, source, configRoot, environment, u
     }
     return [...definitions.values()];
 }
-async function loadPlugin(pluginPath, source, enabled, cwd, requireManifest = false, resourceScope, configRoot, environment = process.env, configId, readOnlyHooks = false, dataPlane) {
+async function loadPlugin(pluginPath, source, enabled, cwd, requireManifest = false, resourceScope, configRoot, environment = process.env, configId, readOnlyHooks = false, readOnlyExecutables = false, allowWorkspaceMcpb = true, dataPlane) {
     const canonical = await realpath(pluginPath);
     if (!(await isDirectory(canonical)))
         throw new Error(`Plugin path is not a directory: ${pluginPath}`);
@@ -480,7 +518,8 @@ async function loadPlugin(pluginPath, source, enabled, cwd, requireManifest = fa
         : [])
         .filter((value) => value.length > 0);
     const pluginData = claudePluginDataPath(configRoot ?? canonical, source);
-    if (configRoot !== undefined && !readOnlyHooks) {
+    const readOnlyComponents = readOnlyHooks || readOnlyExecutables;
+    if (configRoot !== undefined && !readOnlyComponents) {
         await mkdir(pluginData, { recursive: true });
     }
     const pluginEnvironment = pluginOptionEnvironment(canonical, pluginData, userConfig);
@@ -491,7 +530,7 @@ async function loadPlugin(pluginPath, source, enabled, cwd, requireManifest = fa
         environment: pluginEnvironment,
         ...(sensitiveValues.length === 0 ? {} : { sensitiveValues }),
     };
-    const scope = resourceScope ?? scopeForPath(canonical, cwd);
+    const scope = resourceScope ?? scopeForPath(canonical, await realpath(resolve(cwd)));
     const commandDefinitions = isRecord(manifest.commands)
         ? manifest.commands
         : undefined;
@@ -506,7 +545,7 @@ async function loadPlugin(pluginPath, source, enabled, cwd, requireManifest = fa
         ? [join(canonical, 'skills'), canonical]
         : pathList(manifest.skills, 'skills').map((path) => safePluginPath(canonical, path));
     const agentsRoots = pathList(manifest.agents, 'agents').map((path) => safePluginPath(canonical, path));
-    const [commands, skills, agents, lsp] = readOnlyHooks
+    const [commands, skills, agents, lsp] = readOnlyComponents
         ? [[], [], [], []]
         : await (async () => {
             const [commandFiles, skillFiles, agentFiles, loadedLsp] = await Promise.all([
@@ -524,7 +563,7 @@ async function loadPlugin(pluginPath, source, enabled, cwd, requireManifest = fa
             ]);
             return [...loadedText, loadedLsp];
         })();
-    if (commandDefinitions && !readOnlyHooks) {
+    if (commandDefinitions && !readOnlyComponents) {
         for (const [commandName, definition] of Object.entries(commandDefinitions)) {
             if (definition.content !== undefined) {
                 commands.push({
@@ -649,17 +688,61 @@ async function loadPlugin(pluginPath, source, enabled, cwd, requireManifest = fa
             if (typeof spec === 'string') {
                 const urlReference = isUrlReference(spec);
                 if ((urlReference &&
-                    (!/^https?:\/\//u.test(spec) || !isMcpbReference(spec))) ||
+                    (!/^https?:\/\//u.test(spec) ||
+                        !isMcpbReference(spec) ||
+                        (scope !== 'user' && !/^https:\/\//u.test(spec)))) ||
                     (!urlReference && isMcpbReference(spec) && !spec.startsWith('./'))) {
                     mcpErrors.push(`Invalid plugin MCPB reference at index ${index}: expected ./file.mcpb, ./file.dxt, or an exact-suffix HTTP(S) URL`);
                     continue;
                 }
                 if (isMcpbReference(spec)) {
+                    let mcpbPath;
+                    let sourceFingerprint;
+                    try {
+                        mcpbPath = urlReference
+                            ? join(canonical, '.claude-plugin', `plugin-mcpb-${index}.json`)
+                            : await canonicalPluginPath(canonical, safePluginPath(canonical, spec));
+                        sourceFingerprint = createHash('sha256')
+                            .update(urlReference ? spec : await boundedFileSha256(mcpbPath))
+                            .digest('hex');
+                    }
+                    catch (error) {
+                        mcpErrors.push(`Invalid plugin MCPB reference at index ${index}: ${error instanceof Error ? error.message : String(error)}`);
+                        continue;
+                    }
+                    const pluginExecutableSource = {
+                        kind: 'mcpb',
+                        source: spec,
+                        fingerprint: sourceFingerprint,
+                    };
+                    if (readOnlyExecutables) {
+                        mcp.push({
+                            path: mcpbPath,
+                            scope,
+                            plugin: true,
+                            value: {
+                                mcpServers: {
+                                    [`plugin:${manifest.name}:mcpb-${index}`]: {
+                                        type: 'mcpb-reference',
+                                        source: spec,
+                                        fingerprint: sourceFingerprint,
+                                    },
+                                },
+                            },
+                            environment: pluginEnvironment,
+                            pluginExecutableSource,
+                            sensitiveValues,
+                        });
+                        continue;
+                    }
+                    if (scope !== 'user' && !allowWorkspaceMcpb)
+                        continue;
                     try {
                         const loaded = await loadClaudePluginMcpb({
                             pluginRoot: canonical,
                             pluginData,
                             source: spec,
+                            requireHttps: scope !== 'user',
                             ...(configRoot === undefined ? {} : { configRoot }),
                             ...(dataPlane === undefined ? {} : { dataPlane }),
                             environment,
@@ -667,8 +750,14 @@ async function loadPlugin(pluginPath, source, enabled, cwd, requireManifest = fa
                                 ? readClaudePluginMcpServerOptions(configRoot, cwd, configId, bundleManifest.name, bundleManifest.user_config, dataPlane)
                                 : {},
                         });
+                        if (!urlReference &&
+                            createHash('sha256')
+                                .update(await boundedFileSha256(mcpbPath))
+                                .digest('hex') !== sourceFingerprint) {
+                            throw new Error(`Plugin MCPB source changed while loading: ${mcpbPath}`);
+                        }
                         mcp.push({
-                            path: join(canonical, '.claude-plugin', `plugin-mcpb-${index}.json`),
+                            path: mcpbPath,
                             scope,
                             plugin: true,
                             value: {
@@ -677,6 +766,7 @@ async function loadPlugin(pluginPath, source, enabled, cwd, requireManifest = fa
                                 },
                             },
                             environment: pluginEnvironment,
+                            pluginExecutableSource,
                             sensitiveValues: [...sensitiveValues, ...loaded.sensitiveValues],
                         });
                     }
@@ -840,7 +930,7 @@ export async function loadClaudePlugins(options) {
                 if (seen.has(canonical))
                     return null;
                 seen.add(canonical);
-                return await loadPlugin(canonical, candidate.source, candidate.enabled, options.cwd, false, candidate.resourceScope, options.configRoot, options.environment ?? process.env, candidate.configId, options.readOnlyHooks, options.dataPlane);
+                return await loadPlugin(canonical, candidate.source, candidate.enabled, options.cwd, false, candidate.resourceScope, options.configRoot, options.environment ?? process.env, candidate.configId, options.readOnlyHooks, options.readOnlyExecutables, options.allowWorkspaceMcpb, options.dataPlane);
             }
             catch (error) {
                 if (options.strictPluginDirectories &&

package/dist/providers/deadline-provider.d.ts

@@ -0,0 +1,16 @@
+import { type ModelProvider, type ModelRequest, type ModelStreamEvent } from '../core/runtime.js';
+export declare const DEFAULT_PROVIDER_DEADLINE_MS = 90000;
+export interface DeadlineModelProviderOptions {
+    provider: ModelProvider;
+    deadlineMs?: number;
+}
+/** Bounds each streamed completion while preserving the wrapped provider's API. */
+export declare class DeadlineModelProvider implements ModelProvider {
+    private readonly provider;
+    private readonly deadlineMs;
+    readonly model?: string;
+    constructor(options: DeadlineModelProviderOptions);
+    get capabilities(): ModelProvider['capabilities'];
+    complete(request: ModelRequest): AsyncIterable<ModelStreamEvent>;
+}
+//# sourceMappingURL=deadline-provider.d.ts.map

package/dist/providers/deadline-provider.js

@@ -0,0 +1,226 @@
+import { ModelProviderError, } from '../core/runtime.js';
+export const DEFAULT_PROVIDER_DEADLINE_MS = 90_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+function deferred() {
+    let resolve;
+    const promise = new Promise((promiseResolve) => {
+        resolve = promiseResolve;
+    });
+    return { promise, resolve };
+}
+/** Bounds each streamed completion while preserving the wrapped provider's API. */
+export class DeadlineModelProvider {
+    provider;
+    deadlineMs;
+    constructor(options) {
+        const deadlineMs = options.deadlineMs === undefined
+            ? DEFAULT_PROVIDER_DEADLINE_MS
+            : options.deadlineMs;
+        if (!Number.isFinite(deadlineMs) ||
+            !Number.isInteger(deadlineMs) ||
+            deadlineMs <= 0) {
+            throw new Error('Provider deadline must be a positive integer');
+        }
+        this.provider = options.provider;
+        this.deadlineMs = deadlineMs;
+        Object.defineProperty(this, 'model', {
+            configurable: false,
+            enumerable: true,
+            get: () => this.provider.model,
+        });
+    }
+    get capabilities() {
+        return this.provider.capabilities;
+    }
+    complete(request) {
+        let started = false;
+        let closed = false;
+        let interruption;
+        let controller;
+        let callerSignal;
+        let timer;
+        let deadlineStartedAt;
+        let underlying;
+        let cleanupStarted = false;
+        const interruptionDeferred = deferred();
+        const interruptionError = () => {
+            if (interruption?.kind === 'timeout') {
+                return new ModelProviderError('Provider request timed out', {
+                    kind: 'timeout',
+                    retryable: true,
+                    cause: interruption.cause,
+                });
+            }
+            return new ModelProviderError('Provider request cancelled', {
+                kind: 'cancelled',
+                retryable: false,
+                cause: interruption?.cause,
+            });
+        };
+        const bestEffortUnderlyingReturn = () => {
+            const iterator = underlying;
+            if (!iterator || cleanupStarted)
+                return;
+            cleanupStarted = true;
+            let returnMethod;
+            try {
+                returnMethod = iterator.return;
+            }
+            catch {
+                return;
+            }
+            if (!returnMethod)
+                return;
+            try {
+                const result = returnMethod.call(iterator);
+                if (result && typeof result.then === 'function') {
+                    void Promise.resolve(result).catch(() => undefined);
+                }
+            }
+            catch {
+                // Cleanup is best effort; preserve the original completion outcome.
+            }
+        };
+        const clearResources = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+            callerSignal?.removeEventListener('abort', onCallerAbort);
+        };
+        const finish = (outcome) => {
+            if (interruption !== undefined)
+                return;
+            interruption = outcome;
+            closed = true;
+            interruptionDeferred.resolve(outcome);
+            controller?.abort(outcome.cause);
+            clearResources();
+            if (outcome.kind !== 'return')
+                bestEffortUnderlyingReturn();
+        };
+        const onCallerAbort = () => finish({ kind: 'cancelled', cause: callerSignal?.reason });
+        const timeoutCause = new Error('Provider request timed out');
+        timeoutCause.name = 'TimeoutError';
+        const scheduleDeadline = () => {
+            if (deadlineStartedAt === undefined || closed)
+                return;
+            const elapsedMs = Math.max(0, performance.now() - deadlineStartedAt);
+            const remainingMs = this.deadlineMs - elapsedMs;
+            if (remainingMs <= 0) {
+                finish({ kind: 'timeout', cause: timeoutCause });
+                return;
+            }
+            timer = setTimeout(scheduleDeadline, Math.min(remainingMs, MAX_TIMER_DELAY_MS));
+        };
+        const start = () => {
+            if (started || closed)
+                return;
+            started = true;
+            controller = new AbortController();
+            callerSignal = request.signal;
+            if (callerSignal?.aborted)
+                onCallerAbort();
+            else
+                callerSignal?.addEventListener('abort', onCallerAbort, { once: true });
+            if (interruption !== undefined)
+                return;
+            deadlineStartedAt = performance.now();
+            scheduleDeadline();
+            const iterable = this.provider.complete({
+                ...request,
+                signal: controller.signal,
+            });
+            underlying = iterable[Symbol.asyncIterator]();
+            if (interruption !== undefined)
+                bestEffortUnderlyingReturn();
+        };
+        const next = async () => {
+            try {
+                start();
+            }
+            catch (error) {
+                if (interruption !== undefined)
+                    throw interruptionError();
+                closed = true;
+                clearResources();
+                bestEffortUnderlyingReturn();
+                throw error;
+            }
+            if (interruption?.kind === 'return')
+                return { done: true, value: undefined };
+            if (interruption !== undefined)
+                throw interruptionError();
+            if (closed || !underlying)
+                return { done: true, value: undefined };
+            let nextPromise;
+            try {
+                const result = underlying.next();
+                nextPromise = Promise.resolve(result);
+            }
+            catch (error) {
+                if (interruption !== undefined)
+                    throw interruptionError();
+                closed = true;
+                clearResources();
+                bestEffortUnderlyingReturn();
+                throw error;
+            }
+            if (interruption !== undefined) {
+                void nextPromise.catch(() => undefined);
+                throw interruptionError();
+            }
+            const result = await Promise.race([
+                nextPromise.then((value) => ({ type: 'result', value }), (error) => ({ type: 'error', error })),
+                interruptionDeferred.promise.then((outcome) => ({
+                    type: 'interruption',
+                    outcome,
+                })),
+            ]);
+            const observedInterruption = interruption ??
+                (result.type === 'interruption' ? result.outcome : undefined);
+            if (observedInterruption !== undefined) {
+                if (result.type === 'result')
+                    void nextPromise.catch(() => undefined);
+                if (observedInterruption.kind === 'return')
+                    return { done: true, value: undefined };
+                throw interruptionError();
+            }
+            if (result.type === 'error') {
+                closed = true;
+                clearResources();
+                bestEffortUnderlyingReturn();
+                throw result.error;
+            }
+            if (result.type === 'interruption') {
+                if (result.outcome.kind === 'return')
+                    return { done: true, value: undefined };
+                throw interruptionError();
+            }
+            if (result.value.done) {
+                closed = true;
+                clearResources();
+            }
+            return result.value;
+        };
+        const returnFromConsumer = async () => {
+            if (!started) {
+                closed = true;
+                return { done: true, value: undefined };
+            }
+            if (!closed) {
+                finish({ kind: 'return', cause: undefined });
+                bestEffortUnderlyingReturn();
+            }
+            return { done: true, value: undefined };
+        };
+        const result = {
+            [Symbol.asyncIterator]() {
+                return result;
+            },
+            next,
+            return: returnFromConsumer,
+        };
+        return result;
+    }
+}
+//# sourceMappingURL=deadline-provider.js.map

package/dist/providers/environment.d.ts

@@ -1,6 +1,7 @@
 export interface ProviderEnvironment {
     provider: 'openai' | 'anthropic';
     baseUrl: string;
+    deadlineMs: number;
     maxOutputTokens?: number;
     anthropicVersion?: string;
     webSearch?: boolean;

package/dist/providers/environment.js

@@ -1,9 +1,20 @@
 import { createAnthropicPromptCachePolicyResolver } from './anthropic-prompt-cache.js';
+import { DEFAULT_PROVIDER_DEADLINE_MS } from './deadline-provider.js';
 export function parseProviderEnvironment(environment) {
     const provider = environment.PRAXIS_PROVIDER ?? 'openai';
     if (provider !== 'openai' && provider !== 'anthropic') {
         throw new Error('PRAXIS_PROVIDER must be openai or anthropic');
     }
+    const rawDeadlineMs = environment.PRAXIS_PROVIDER_DEADLINE_MS;
+    if (rawDeadlineMs !== undefined &&
+        (!/^\d+$/.test(rawDeadlineMs) ||
+            Number(rawDeadlineMs) <= 0 ||
+            !Number.isSafeInteger(Number(rawDeadlineMs)))) {
+        throw new Error('PRAXIS_PROVIDER_DEADLINE_MS must be a positive safe integer');
+    }
+    const deadlineMs = rawDeadlineMs === undefined
+        ? DEFAULT_PROVIDER_DEADLINE_MS
+        : Number(rawDeadlineMs);
     const maxOutputTokens = environment.PRAXIS_MAX_OUTPUT_TOKENS;
     if (maxOutputTokens !== undefined &&
         (!/^\d+$/.test(maxOutputTokens) ||
@@ -47,6 +58,7 @@ export function parseProviderEnvironment(environment) {
             (provider === 'anthropic'
                 ? 'https://api.anthropic.com/v1'
                 : 'https://api.openai.com/v1'),
+        deadlineMs,
         ...(maxOutputTokens === undefined
             ? {}
             : { maxOutputTokens: Number(maxOutputTokens) }),

package/dist/providers/fallback-provider.js

@@ -6,6 +6,38 @@ function retryable(error) {
         error.retryable &&
         modelProviderErrorKind(error) !== 'prompt_too_long');
 }
+function cancellationError(signal) {
+    return new ModelProviderError('Provider request cancelled', {
+        kind: 'cancelled',
+        retryable: false,
+        cause: signal.reason,
+    });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw cancellationError(signal);
+}
+async function waitForRetry(delayMs, signal) {
+    throwIfAborted(signal);
+    if (delayMs <= 0)
+        return;
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            result();
+        };
+        const onAbort = () => finish(() => reject(cancellationError(signal)));
+        const timer = setTimeout(() => finish(resolve), delayMs);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+    });
+}
 /** Routes each complete request through Claude's retry-then-fallback policy. */
 export class FallbackModelProvider {
     active;
@@ -30,6 +62,7 @@ export class FallbackModelProvider {
         let lastError;
         for (const provider of this.providers()) {
             for (let attempt = 0; attempt < MAX_ATTEMPTS_PER_MODEL; attempt += 1) {
+                throwIfAborted(request.signal);
                 this.active = provider;
                 const attemptStartedAt = performance.now();
                 try {
@@ -73,6 +106,7 @@ export class FallbackModelProvider {
                     return;
                 }
                 catch (error) {
+                    throwIfAborted(request.signal);
                     lastError = error;
                     if (!retryable(error))
                         throw error;
@@ -89,8 +123,7 @@ export class FallbackModelProvider {
                                 error: modelProviderErrorKind(error),
                             };
                         }
-                        if (delay > 0)
-                            await new Promise((resolve) => setTimeout(resolve, delay));
+                        await waitForRetry(delay, request.signal);
                     }
                 }
             }

package/dist/security/workspace-trust.d.ts

@@ -0,0 +1,30 @@
+import type { JsonResource } from '../core/resources.js';
+export interface WorkspaceExecutableOrigin {
+    readonly kind: 'hook' | 'mcp';
+    readonly scope: 'project' | 'local';
+    readonly path: string;
+    readonly label: string;
+}
+export interface WorkspaceTrustInventory {
+    readonly canonicalPath: string;
+    readonly fingerprint: string;
+    readonly origins: readonly WorkspaceExecutableOrigin[];
+}
+export type WorkspaceTrustStatus = 'not-required' | 'trusted' | 'untrusted';
+export interface WorkspaceTrustAssessment extends WorkspaceTrustInventory {
+    readonly status: WorkspaceTrustStatus;
+}
+export declare function canonicalizeWorkspaceTrust(value: unknown, ancestors?: Set<object>): string;
+export declare function hasWorkspaceHooks(resource: JsonResource): boolean;
+export declare function hasWorkspaceMcpServers(resource: JsonResource): boolean;
+export declare function allowedWorkspaceHookSettings(resources: readonly JsonResource[], trusted: boolean): JsonResource[];
+export declare function allowedWorkspaceMcpResources(resources: readonly JsonResource[], trusted: boolean): JsonResource[];
+export declare function workspaceTrustInventory(options: {
+    cwd: string;
+    settings?: readonly JsonResource[];
+    mcp?: readonly JsonResource[];
+}): Promise<WorkspaceTrustInventory>;
+export declare function workspaceTrustDecisionKey(inventory: Pick<WorkspaceTrustInventory, 'canonicalPath' | 'fingerprint'>): string;
+export declare function assessWorkspaceTrust(inventory: WorkspaceTrustInventory, statePath: string): Promise<WorkspaceTrustAssessment>;
+export declare function persistWorkspaceTrust(assessment: WorkspaceTrustAssessment, statePath: string): Promise<void>;
+//# sourceMappingURL=workspace-trust.d.ts.map