@hunterzhu/pulse-adapters 0.5.1 → 0.7.0

package/dist/providers/normalize.js

@@ -39,8 +39,33 @@ function summarizeProviderError(raw) {
 function truncateProviderDetail(value) {
     return value.length <= 500 ? value : `${value.slice(0, 497)}...`;
 }
+const NETWORK_CAUSE_CODES = new Set([
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'UND_ERR_CONNECT_TIMEOUT',
+]);
+/**
+ * Keep the stable PROVIDER_NETWORK_ERROR code and retryable=true, appending only
+ * whitelisted low-level cause codes. Arbitrary codes, messages, URLs and credentials
+ * on the cause chain are ignored.
+ */
 export function providerNetworkError(cause) {
-    return Object.assign(new Error('PROVIDER_NETWORK_ERROR'), { code: 'PROVIDER_NETWORK_ERROR', retryable: true, cause });
+    const reasons = [];
+    let node = cause;
+    for (let depth = 0; depth < 4 && node !== null && typeof node === 'object'; depth += 1) {
+        const code = node.code;
+        if (typeof code === 'string' && NETWORK_CAUSE_CODES.has(code) && !reasons.includes(code))
+            reasons.push(code);
+        const name = node.name;
+        if ((name === 'TimeoutError' || name === 'AbortError') && !reasons.includes(name))
+            reasons.push(name);
+        node = node.cause;
+    }
+    const message = reasons.length > 0 ? `PROVIDER_NETWORK_ERROR (${reasons.join(', ')})` : 'PROVIDER_NETWORK_ERROR';
+    return Object.assign(new Error(message), { code: 'PROVIDER_NETWORK_ERROR', retryable: true, cause });
 }
 export function providerResponseError(detail) {
     return Object.assign(new Error(`PROVIDER_RESPONSE_INVALID: ${detail}`), { code: 'PROVIDER_RESPONSE_INVALID', retryable: true });
@@ -402,7 +427,7 @@ const DSML_INVOKE_PATTERN = /<\uFF5C+DSML\uFF5C+\s*invoke\s+name="([^"]+)"\s*\/?
 const DSML_PARAMETER_OPEN = /<\uFF5C+DSML\uFF5C+\s*parameter\b/;
 const DSML_PARAMETER_CLOSE = /<\/\uFF5C+DSML\uFF5C+\s*parameter>/;
 const DSML_PARAMETER_PATTERN = /<\uFF5C+DSML\uFF5C+\s*parameter\s+name="([^"]+)"\s+string="(true|false)"\s*>([\s\S]*?)<\/\uFF5C+DSML\uFF5C+\s*parameter>/;
-export function normalizeAnthropicResponse(response) {
+export function normalizeAnthropicResponse(response, aliases = new Map()) {
     const root = providerRecord(response, 'Anthropic response');
     if (!Array.isArray(root.content))
         throw providerResponseError('Anthropic response content must be an array');
@@ -411,7 +436,8 @@ export function normalizeAnthropicResponse(response) {
     const toolBlocks = blocks.filter((block) => providerRecord(block, 'Anthropic content block').type === 'tool_use');
     const toolCalls = (root.stop_reason === 'max_tokens' ? [] : toolBlocks).map((block, index) => {
         const value = providerRecord(block, 'Anthropic tool block');
-        return { toolCallId: `pulse-tool-${index + 1}`, name: requiredProviderString(value.name, 'Anthropic tool name'), input: parseJson(value.input) };
+        const providerName = requiredProviderString(value.name, 'Anthropic tool name');
+        return { toolCallId: `pulse-tool-${index + 1}`, name: aliases.get(providerName) ?? providerName, input: parseJson(value.input), ...(typeof value.id === 'string' ? { providerToolCallId: value.id, providerToolName: providerName, providerToolArguments: JSON.stringify(value.input) } : {}) };
     });
     const refusalBlock = blocks.find((block) => block.type === 'refusal' && typeof block.text === 'string');
     const refusal = refusalBlock?.text;

package/dist/providers/openai-compat.d.ts

@@ -11,9 +11,11 @@ export declare class OpenAICompatibleAdapter implements ProviderAdapter {
         request: LLMRequestProjection;
         signal: AbortSignal;
         onObservation?: (chunk: string) => void;
+        onReasoning?: (chunk: string) => void;
         model?: string;
         outputSchema?: JsonValue;
         maxOutputTokens?: number;
+        beforeRetryAttempt?: () => Promise<void>;
     }): Promise<LLMResult>;
 }
 export declare function toOpenAIMessages(request: LLMRequestProjection, provider?: string): Array<Record<string, unknown>>;

package/dist/providers/openai-compat.js

@@ -9,7 +9,13 @@ export class OpenAICompatibleAdapter {
     constructor(id, config) {
         this.id = id;
         this.config = config;
-        this.baseURL = config.baseURL ?? 'https://api.openai.com/v1';
+        let baseURL = config.baseURL ?? (config.provider === 'ollama' ? 'http://127.0.0.1:11434/v1' : 'https://api.openai.com/v1');
+        if (config.provider === 'ollama') {
+            const url = new URL(baseURL);
+            if (url.pathname === '/' && !url.search && !url.hash)
+                baseURL = baseURL.replace(/\/$/, '') + '/v1';
+        }
+        this.baseURL = baseURL;
     }
     async executeAttempt(params) {
         const streaming = params.onObservation !== undefined;
@@ -37,6 +43,8 @@ export class OpenAICompatibleAdapter {
                 for (const ev of streamEvents) {
                     if (ev.type === 'text_delta')
                         params.onObservation?.(ev.text);
+                    if (ev.type === 'reasoning_delta')
+                        params.onReasoning?.(ev.text);
                     if (ev.type === 'refusal_delta')
                         params.onObservation?.(ev.refusal);
                 }
@@ -75,6 +83,7 @@ export class OpenAICompatibleAdapter {
                 throw Object.assign(new Error('Provider request was cancelled.'), { code: 'PROVIDER_REQUEST_CANCELLED', retryable: false, cause });
             if (sentReasoning && this.probe.reasoningParameterRejected(cause)) {
                 this.probe.markReasoningUnsupported(this.config.provider, canonical.model);
+                await params.beforeRetryAttempt?.();
                 return this.executeAttempt(params);
             }
             if (cause instanceof Error && 'code' in cause && typeof cause.code === 'string' && 'retryable' in cause && typeof cause.retryable === 'boolean')

package/dist/providers/runtime-executor.d.ts

@@ -1,9 +1,16 @@
-import type { EffectExecutor, ModelRouteRequirements, ModelRouter } from '@hunterzhu/pulse-runtime';
+import type { EffectExecutor, LLMRequestProjection, LLMResult, ModelRouteRequirements, ModelRouter } from '@hunterzhu/pulse-runtime';
 import type { ProviderAdapter } from './types.js';
 export declare function createModelEffectExecutor(config: {
+    resolveImage?: (ref: string, agentId: string, privacy: LLMRequestProjection['privacy']) => string | Promise<string>;
     router: ModelRouter;
     providers: ReadonlyMap<string, ProviderAdapter>;
     requirements?: ModelRouteRequirements;
     maxConcurrentByProvider?: Readonly<Record<string, number>>;
     maxConcurrentByModel?: Readonly<Record<string, number>>;
+    modelBudget?: () => {
+        limit: number;
+        used: number;
+    };
+    beforeProviderAttempt?: (purpose?: string) => Promise<void>;
+    afterProviderAttempt?: (usage: LLMResult['usage'], receiptId?: string) => Promise<void>;
 }): EffectExecutor;

package/dist/providers/runtime-executor.js

@@ -1,4 +1,5 @@
-import { assignRuntimeToolCallIds, ModelFallbackController, OutputValidationError, estimateProjectionTokens, stableSerialize, validateAdapterResult, validateJsonSchema, modelFallbackError, runtimeErrorFromCause } from '@hunterzhu/pulse-runtime';
+import { randomUUID } from 'node:crypto';
+import { assignRuntimeToolCallIds, contentHash, ModelFallbackController, OutputValidationError, estimateProjectionTokens, stableSerialize, validateAdapterResult, validateJsonSchema, modelFallbackError, runtimeErrorFromCause } from '@hunterzhu/pulse-runtime';
 class AsyncSlot {
     limit;
     active = 0;
@@ -142,11 +143,13 @@ export function createModelEffectExecutor(config) {
         if (effect.kind !== 'llm')
             throw new Error(`UNSUPPORTED_EFFECT_KIND:${effect.kind}`);
         const input = effect.input && typeof effect.input === 'object' && !Array.isArray(effect.input) ? effect.input : {};
-        const task = input.task;
+        const task = input.request?.images?.length ? 'vision' : input.task;
         const request = input.request;
         if (typeof task !== 'string' || !request || typeof request !== 'object' || Array.isArray(request))
             throw new Error('INVALID_LLM_EFFECT_INPUT');
         const projection = request;
+        const purpose = effect.key?.startsWith('progress-review') ? 'progress-review' : effect.key === 'safety-review' ? 'approval' : effect.key?.startsWith('verify-task') ? 'final-verification' : effect.key?.startsWith('verify-stage') || task === 'verify' ? 'verification' : task === 'plan' ? 'planning' : 'work';
+        let providerAttempts = 0;
         const observations = [];
         const usage = new Map();
         const slotWaitMs = new Map();
@@ -157,7 +160,7 @@ export function createModelEffectExecutor(config) {
         const structuredSchema = structuredRequirement && typeof structuredRequirement === 'object' && !Array.isArray(structuredRequirement) ? structuredRequirement.schema : undefined;
         if (structuredSchema !== undefined && (input.outputSchema === undefined || stableSerialize(structuredSchema) !== stableSerialize(input.outputSchema)))
             return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: { code: 'STRUCTURED_OUTPUT_CONTRACT_MISMATCH', message: 'requirements.structuredOutput.schema must equal outputSchema.' } };
-        const routeRequirements = { ...config.requirements, ...(typeof dynamicRequirements.toolCalling === 'boolean' ? { toolCalling: dynamicRequirements.toolCalling } : {}), ...(typeof dynamicRequirements.structuredOutput === 'boolean' ? { structuredOutput: dynamicRequirements.structuredOutput } : structuredSchema === undefined ? {} : { structuredOutput: true }), ...(dynamicRequirements.reasoning === 'low' || dynamicRequirements.reasoning === 'medium' || dynamicRequirements.reasoning === 'high' ? { reasoning: dynamicRequirements.reasoning } : {}), ...(typeof dynamicRequirements.maxOutputTokens === 'number' ? { maxOutputTokens: dynamicRequirements.maxOutputTokens } : {}), ...(typeof dynamicRequirements.contextSize === 'number' ? { contextSize: dynamicRequirements.contextSize } : {}) };
+        const routeRequirements = { ...(projection.images?.length ? { imageInput: true } : {}), ...config.requirements, ...(typeof dynamicRequirements.toolCalling === 'boolean' ? { toolCalling: dynamicRequirements.toolCalling } : {}), ...(typeof dynamicRequirements.structuredOutput === 'boolean' ? { structuredOutput: dynamicRequirements.structuredOutput } : structuredSchema === undefined ? {} : { structuredOutput: true }), ...(dynamicRequirements.reasoning === 'low' || dynamicRequirements.reasoning === 'medium' || dynamicRequirements.reasoning === 'high' ? { reasoning: dynamicRequirements.reasoning } : {}), ...(typeof dynamicRequirements.maxOutputTokens === 'number' ? { maxOutputTokens: dynamicRequirements.maxOutputTokens } : {}), ...(typeof dynamicRequirements.contextSize === 'number' ? { contextSize: dynamicRequirements.contextSize } : {}) };
         const routeDiagnostics = config.router.diagnostics(task, projection.privacy, routeRequirements, estimateProjectionTokens(projection) + (typeof routeRequirements.maxOutputTokens === 'number' ? routeRequirements.maxOutputTokens : 0));
         const candidates = config.router.routeProjection(task, projection, routeRequirements);
         const attemptNo = Math.max(1, effect.attemptNo);
@@ -193,6 +196,7 @@ export function createModelEffectExecutor(config) {
             }
             slotWaitMs.set(attempt.attemptId, Math.max(0, Date.now() - slotStartedAt));
             const releases = [providerRelease, modelRelease];
+            let providerStartedAt;
             let feedbackRecorded = false;
             const recordFeedback = (outcome, quality) => {
                 if (feedbackRecorded)
@@ -202,15 +206,47 @@ export function createModelEffectExecutor(config) {
             };
             try {
                 const startedAt = Date.now();
+                const usageReceiptId = randomUUID();
+                const streamAttempt = { no: attemptNo, emitted: false };
                 const onObservation = (chunk) => {
+                    streamAttempt.emitted = true;
                     const observation = { type: 'chunk', data: chunk };
                     if (emitObservation)
                         emitObservation(observation);
                     else
                         observations.push(observation);
                 };
-                const output = assignRuntimeToolCallIds(validateAdapterResult(await provider.executeAttempt({ request: projection, signal, model: attempt.candidate.id, ...(input.outputSchema === undefined ? {} : { outputSchema: input.outputSchema }), ...(typeof routeRequirements.maxOutputTokens === 'number' ? { maxOutputTokens: routeRequirements.maxOutputTokens } : {}), onObservation })), effect.id);
-                const measuredUsage = { ...(output.usage ?? {}), visibleOutputChars: output.text.length, latencyMs: output.usage?.latencyMs ?? Math.max(0, Date.now() - startedAt), ...(output.usage?.uncachedInputTokens === undefined && output.usage?.inputTokens !== undefined && output.usage.cachedInputTokens !== undefined ? { uncachedInputTokens: Math.max(0, output.usage.inputTokens - output.usage.cachedInputTokens) } : {}) };
+                const onReasoning = emitObservation === undefined ? undefined : (chunk) => {
+                    streamAttempt.emitted = true;
+                    emitObservation({ type: 'chunk', data: { kind: 'reasoning', text: chunk, task, modelId: attempt.candidate.id, providerId: attempt.candidate.providerId, attemptNo: streamAttempt.no } });
+                };
+                emitObservation?.({ type: 'trace', data: { kind: 'llm.attempt', task, purpose, modelId: attempt.candidate.id, providerId: attempt.candidate.providerId, attemptNo, fallback: attemptNo > 1 } });
+                const images = projection.images === undefined ? undefined : await Promise.all(projection.images.map(async (image) => {
+                    if (image.data)
+                        return image;
+                    if (!projection.contextSpec.artifactRefs?.includes(image.ref) || !config.resolveImage)
+                        throw Object.assign(new Error('IMAGE_RESOLVER_REQUIRED'), { retryable: false });
+                    return { ...image, data: await config.resolveImage(image.ref, effect.agentId, projection.privacy) };
+                }));
+                const hydrated = images === undefined ? projection : { ...projection, images };
+                signal.throwIfAborted();
+                await config.beforeProviderAttempt?.(purpose);
+                providerStartedAt = Date.now();
+                providerAttempts++;
+                const budget = config.modelBudget?.();
+                const blocks = budget ? [...hydrated.blocks, { kind: 'policy', content: `Host model-call ledger: limit=${budget.limit}, used=${budget.used} (including this request), remaining=${Math.max(0, budget.limit - budget.used)}. This is shared by planning, tools' approval reviews, retries, compaction and final verification. Reserve at least two requests for verification. Produce an incremental usable deliverable now; do not spend the remaining allowance on discovery or start another run.` }] : hydrated.blocks;
+                const budgeted = budget ? { ...hydrated, blocks, projectionHash: contentHash(blocks) } : hydrated;
+                const output = assignRuntimeToolCallIds(validateAdapterResult(await provider.executeAttempt({ request: budgeted, signal, model: attempt.candidate.id, ...(input.outputSchema === undefined ? {} : { outputSchema: input.outputSchema }), ...(typeof routeRequirements.maxOutputTokens === 'number' ? { maxOutputTokens: routeRequirements.maxOutputTokens } : {}), onObservation, ...(onReasoning === undefined ? {} : { onReasoning }), ...(config.beforeProviderAttempt === undefined ? {} : { beforeRetryAttempt: async () => {
+                            await config.beforeProviderAttempt(purpose);
+                            providerAttempts++;
+                            if (!streamAttempt.emitted)
+                                return;
+                            streamAttempt.no += 1;
+                            streamAttempt.emitted = false;
+                            emitObservation?.({ type: 'trace', data: { kind: 'llm.attempt', task, purpose, modelId: attempt.candidate.id, providerId: attempt.candidate.providerId, attemptNo: streamAttempt.no, fallback: true } });
+                        } }) })), effect.id);
+                const measuredUsage = { ...(output.usage ?? {}), outputTruncated: output.finishReason === 'length', visibleOutputChars: output.text.length, latencyMs: output.usage?.latencyMs ?? Math.max(0, Date.now() - startedAt), ...(output.usage?.uncachedInputTokens === undefined && output.usage?.inputTokens !== undefined && output.usage.cachedInputTokens !== undefined ? { uncachedInputTokens: Math.max(0, output.usage.inputTokens - output.usage.cachedInputTokens) } : {}) };
+                await config.afterProviderAttempt?.(measuredUsage, usageReceiptId);
                 usage.set(attempt.attemptId, measuredUsage);
                 if (output.finishReason === 'length' && input.outputSchema !== undefined)
                     throw Object.assign(new OutputValidationError('adapter', 'OUTPUT_TRUNCATED', 'Model output reached its token limit; incomplete output was rejected.', { outputTokens: output.usage?.outputTokens ?? null, reasoningTokens: output.usage?.reasoningTokens ?? null, visibleOutputChars: output.text.length, maxOutputTokens: routeRequirements.maxOutputTokens ?? config.requirements?.maxOutputTokens ?? null }), { retryable: false });
@@ -234,7 +270,16 @@ export function createModelEffectExecutor(config) {
                 return output;
             }
             catch (cause) {
-                recordFeedback('failed', 0);
+                // Transport failure still consumed time. Preserve measured timing, but
+                // never invent token counts or costs when the provider returned none.
+                if (providerStartedAt !== undefined) {
+                    const measured = usage.get(attempt.attemptId) ?? { latencyMs: Math.max(1, Date.now() - providerStartedAt) };
+                    usage.set(attempt.attemptId, measured);
+                    usage.set(effect.attemptId, measured);
+                }
+                const stopped = cause && typeof cause === 'object' && 'code' in cause && /^(?:TASK_MODEL_CALL_BUDGET_|AI_APPROVAL_DENIED|APPROVAL_DENIED|TOOL_CANCELLED)/.test(String(cause.code));
+                if (!stopped)
+                    recordFeedback('failed', 0);
                 if (signal.aborted)
                     throw modelFallbackError({ retryable: false, localClosed: true, sideEffectState: 'none', cause });
                 const retryable = cause && typeof cause === 'object' && 'retryable' in cause && typeof cause.retryable === 'boolean' ? cause.retryable : true;
@@ -264,13 +309,13 @@ export function createModelEffectExecutor(config) {
             return { result: { text: '', toolCalls: [], finishReason: 'error' }, candidate, attempts: [{ effectId: effect.id, attemptId: effect.attemptId, attemptNo, candidate }], failed: { ...error, ...(canFallback && fallbackError?.retryable !== false && error.retryable !== false ? { retryable: true } : {}) } };
         });
         if ('schemaRejected' in result)
-            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: { code: 'OUTPUT_SCHEMA_VIOLATION', message: 'Provider output did not match the declared schema.', ...(canFallback ? { retryable: true } : {}) }, metadata: candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics), rejectedOutput: { value: result.schemaRejected, privacy: projection.privacy, derivedFrom: [...(effect.derivedFrom ?? [])] } };
+            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: { code: 'OUTPUT_SCHEMA_VIOLATION', message: 'Provider output did not match the declared schema.', ...(canFallback ? { retryable: true } : {}) }, metadata: { ...candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics), providerAttempts }, rejectedOutput: { value: result.schemaRejected, privacy: projection.privacy, derivedFrom: [...(effect.derivedFrom ?? [])] } };
         if ('refused' in result)
-            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: { code: 'MODEL_REFUSAL', message: result.result.refusal ?? 'Provider refused the request.', ...(result.retryable ? { retryable: true } : {}) }, metadata: candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics) };
+            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: { code: 'MODEL_REFUSAL', message: result.result.refusal ?? 'Provider refused the request.', ...(result.retryable ? { retryable: true } : {}) }, metadata: { ...candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics), providerAttempts } };
         if ('failed' in result)
-            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: result.failed, metadata: candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics) };
+            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: result.failed, metadata: { ...candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics), providerAttempts } };
         const modelValue = input.outputSchema !== undefined || typeof input.schema === 'string' ? (result.result.structured ?? result.result.text) : result.result;
         const value = toJson(modelValue);
-        return { value, privacy: projection.privacy, sideEffectState: 'none', executionState: 'succeeded', metadata: candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics), ...(observations.length ? { observations } : {}) };
+        return { value, privacy: projection.privacy, sideEffectState: 'none', executionState: 'succeeded', metadata: { ...candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics), providerAttempts }, ...(observations.length ? { observations } : {}) };
     };
 }

package/dist/providers/types.d.ts

@@ -12,9 +12,11 @@ export interface ProviderAdapter {
         request: LLMRequestProjection;
         signal: AbortSignal;
         onObservation?: (chunk: string) => void;
+        onReasoning?: (chunk: string) => void;
         model?: string;
         outputSchema?: JsonValue;
         maxOutputTokens?: number;
+        beforeRetryAttempt?: () => Promise<void>;
     }): Promise<LLMResult>;
 }
 export interface ProviderPresetConfig {

package/dist/tools/installation-dependencies.d.ts

@@ -0,0 +1,4 @@
+/** Host workspaces and linked aliases need dependencies; unrelated scripts do not. */
+export declare function workspaceUsesInstallationDependencies(workspace: string, roots: string[]): Promise<boolean>;
+/** Host installation only. Never resolve grants from model argv or workspace links. */
+export declare function installationDependencyRoots(): Promise<string[]>;

package/dist/tools/installation-dependencies.js

@@ -0,0 +1,59 @@
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, parse, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Host workspaces and linked aliases need dependencies; unrelated scripts do not. */
+export async function workspaceUsesInstallationDependencies(workspace, roots) {
+    const contains = (root, path) => {
+        const child = relative(root, path);
+        return child === '' || child !== '..' && !child.startsWith(`..${sep}`) && !isAbsolute(child);
+    };
+    if (roots.some(root => contains(dirname(root), workspace)))
+        return true;
+    const modules = await realpath(join(workspace, 'node_modules')).catch(() => undefined);
+    if (!modules)
+        return false;
+    if (roots.some(root => contains(root, modules)))
+        return true;
+    // An ordinary project can link individual packages rather than its entire
+    // node_modules directory. Inspect only metadata inside that workspace tree.
+    if (!contains(workspace, modules))
+        return false;
+    for (const entry of await readdir(modules, { withFileTypes: true })) {
+        const path = join(modules, entry.name);
+        const target = await realpath(path).catch(() => undefined);
+        if (target && roots.some(root => contains(root, target)))
+            return true;
+        if (entry.name.startsWith('@') && entry.isDirectory() && target && contains(workspace, target)) {
+            for (const name of await readdir(path)) {
+                const scoped = await realpath(join(path, name)).catch(() => undefined);
+                if (scoped && roots.some(root => contains(root, scoped)))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** Host installation only. Never resolve grants from model argv or workspace links. */
+export async function installationDependencyRoots() {
+    const roots = new Set();
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 12 && directory !== homedir() && directory !== parse(directory).root; depth++) {
+        const manifest = await readFile(join(directory, 'package.json'), 'utf8').then(text => JSON.parse(text)).catch(() => undefined);
+        const candidates = [...(manifest ? [join(directory, 'node_modules')] : []), ...(basename(directory) === 'node_modules' ? [directory] : [])];
+        for (const candidate of candidates) {
+            const physical = await realpath(candidate).catch(() => undefined);
+            // Installation links may point to an installed module store, never a
+            // source checkout, home or root. Keep the lexical module directory too:
+            // Node must inspect package aliases before resolving their real targets.
+            if (!physical || basename(physical) !== 'node_modules' || !(await stat(physical)).isDirectory())
+                continue;
+            roots.add(candidate);
+            roots.add(physical);
+        }
+        if (manifest?.workspaces || basename(directory) === 'node_modules' && !directory.includes(`${join('node_modules', '.pnpm')}`))
+            break;
+        directory = dirname(directory);
+    }
+    return [...roots];
+}

package/dist/tools/registry.js

@@ -1,4 +1,4 @@
-import { isSideEffectful } from '@hunterzhu/pulse-runtime';
+import { extractToolImage, isSideEffectful } from '@hunterzhu/pulse-runtime';
 function toJson(value, seen = new Set()) {
     if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number')
         return value;
@@ -102,7 +102,10 @@ export function createToolEffectExecutor(registry) {
             value = null;
             artifact = artifactOutput(detailed.output);
         }
-        return { value, ...(detailed.normalized === undefined ? {} : { normalized: toJson(detailed.normalized) }), ...(artifact === undefined ? {} : { artifact }), ...(summary === undefined ? {} : { summary }), sideEffectState: isSideEffectful(definition.manifest.sideEffectPolicy) ? 'applied' : 'none', executionState: 'succeeded', ...(executionRef === undefined ? {} : { executionRef }), metadata: { toolVersion: detailed.manifest.version, retrySafety: detailed.manifest.retrySafety, defaultTimeoutMs: detailed.manifest.defaultTimeoutMs, observationCount: observations.length, ...(artifact === undefined ? {} : { artifactMediaType: artifact.mediaType }) }, ...(observations.length ? { observations } : {}) };
+        const image = extractToolImage(value);
+        value = image.value;
+        artifact = image.artifact ?? artifact;
+        return { value, ...(detailed.normalized === undefined ? {} : { normalized: image.artifact ? value : toJson(detailed.normalized) }), ...(artifact === undefined ? {} : { artifact }), ...(summary === undefined ? {} : { summary }), sideEffectState: isSideEffectful(definition.manifest.sideEffectPolicy) ? 'applied' : 'none', executionState: 'succeeded', ...(executionRef === undefined ? {} : { executionRef }), metadata: { toolVersion: detailed.manifest.version, retrySafety: detailed.manifest.retrySafety, defaultTimeoutMs: detailed.manifest.defaultTimeoutMs, observationCount: observations.length, ...(artifact === undefined ? {} : { artifactMediaType: artifact.mediaType }) }, ...(observations.length ? { observations } : {}) };
     };
 }
 export async function reconcileToolEffect(registry, effect, signal) {

package/dist/tools/sandbox-initialization.d.ts

@@ -1,2 +1,2 @@
 import { type SandboxRuntimeConfig } from '@anthropic-ai/sandbox-runtime';
-export declare function initializeShellSandbox(policy: SandboxRuntimeConfig, platform?: NodeJS.Platform): Promise<void>;
+export declare function initializeShellSandbox(policy: SandboxRuntimeConfig, platform?: NodeJS.Platform, signal?: AbortSignal): Promise<void>;

package/dist/tools/sandbox-initialization.js

@@ -1,17 +1,73 @@
-import { SandboxManager } from '@anthropic-ai/sandbox-runtime';
-export async function initializeShellSandbox(policy, platform = process.platform) {
+import { realpath } from 'node:fs/promises';
+import { win32 } from 'node:path';
+import { setImmediate } from 'node:timers/promises';
+import { SandboxManager, expandWindowsFsPaths, getWindowsSandboxUserStatusAsync, resolveSrtWin, stampWindowsAcl } from '@anthropic-ai/sandbox-runtime';
+const windowsAclBatchSize = 8;
+async function windowsDenyBatches(policy) {
+    const fs = policy.filesystem;
+    // Credential-derived file denies belong to the SDK's own convergence pass.
+    if (!fs || fs.disabled || policy.credentials)
+        return undefined;
+    const reads = expandWindowsFsPaths(fs.denyRead ?? [], { mode: 'deny' });
+    const writes = expandWindowsFsPaths(fs.denyWrite ?? [], { mode: 'deny' });
+    if (reads.length + writes.length <= windowsAclBatchSize)
+        return undefined;
+    // Resolve aliases before merging masks: a later write-only deny must never
+    // downgrade a read deny on the same physical object. Let the SDK handle
+    // missing paths and its placeholder lifecycle without changing semantics.
+    const physical = await Promise.all([...reads, ...writes].map(path => realpath(path).catch(() => undefined)));
+    if (physical.some(path => path === undefined))
+        return undefined;
+    const targets = new Map();
+    physical.forEach((path, index) => {
+        const key = win32.normalize(path).toLowerCase();
+        if (!targets.has(key))
+            targets.set(key, { path: path, read: index < reads.length });
+    });
+    const batches = [];
+    const entries = [...targets.values()];
+    for (let offset = 0; offset < entries.length; offset += windowsAclBatchSize) {
+        const batch = { denyRead: [], denyWrite: [] };
+        for (const target of entries.slice(offset, offset + windowsAclBatchSize))
+            (target.read ? batch.denyRead : batch.denyWrite).push(target.path);
+        batches.push(batch);
+    }
+    return batches.length > 1 ? batches : undefined;
+}
+export async function initializeShellSandbox(policy, platform = process.platform, signal) {
+    signal?.throwIfAborted();
+    const batches = platform === 'win32' ? await windowsDenyBatches(policy) : undefined;
+    signal?.throwIfAborted();
+    const initial = batches ? { ...policy, filesystem: { ...policy.filesystem, ...batches[0] } } : policy;
     try {
-        await SandboxManager.initialize(policy, undefined, false);
+        await SandboxManager.initialize(initial, undefined, false);
     }
     catch (error) {
-        // A cold Windows sandbox account can time out during the WFP readiness
-        // probe. Retry that probe once after cleanup, before any command is run.
-        // A failed isolation check, ACL error, or second timeout still fails closed.
+        // Retry only the cold WFP readiness probe, before any command is run.
         if (platform !== 'win32' || !error || typeof error !== 'object'
             || !('code' in error) || error.code !== 'srt_win_timeout'
             || !('subcommand' in error) || error.subcommand !== 'wfp')
             throw error;
         await SandboxManager.reset();
-        await SandboxManager.initialize(policy, undefined, false);
+        await SandboxManager.initialize(initial, undefined, false);
+    }
+    signal?.throwIfAborted();
+    if (!batches)
+        return;
+    const srtWin = resolveSrtWin(policy.windows?.srtWin);
+    const status = await getWindowsSandboxUserStatusAsync({ srtWin });
+    if (!status.provisioned || !status.sid)
+        throw new Error('Windows sandbox not provisioned');
+    for (const batch of batches.slice(1)) {
+        signal?.throwIfAborted();
+        stampWindowsAcl({ ...batch, sandboxUserSid: status.sid, holderPid: process.pid, srtWin });
+        await setImmediate();
     }
+    signal?.throwIfAborted();
+    // Additional batches use the SAME holder PID. The SDK's reset() releases all
+    // ledger holds for that PID, including partial batches after failure. The
+    // first batch ensures its cleanup bookkeeping is active even without grants.
+    // Publish the full declared policy only once every native deny has landed;
+    // the SDK's cached deny list is only a per-exec deduplication optimization.
+    SandboxManager.updateConfig(policy);
 }

package/dist/tools/shell-output.d.ts

@@ -0,0 +1,23 @@
+/** Bounded memory observation plus a separately bounded, private durable byte stream. */
+export declare class ShellOutput {
+    private readonly memoryLimit;
+    private readonly directory?;
+    private readonly diskLimit;
+    private readonly keepTail;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    private streams;
+    constructor(memoryLimit: number, directory?: string | undefined, diskLimit?: number, keepTail?: boolean);
+    append(name: 'stdout' | 'stderr', chunk: Buffer): void;
+    text(name: 'stdout' | 'stderr'): string;
+    finish(): Record<string, {
+        id: string;
+        bytes: number;
+        storedBytes: number;
+        sha256: string;
+        storedSha256: string;
+        omittedStart: number;
+        omittedEnd: number;
+        complete: boolean;
+        error?: string;
+    }>;
+}

package/dist/tools/shell-output.js

@@ -0,0 +1,82 @@
+import { closeSync, mkdirSync, openSync, writeSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+/** Bounded memory observation plus a separately bounded, private durable byte stream. */
+export class ShellOutput {
+    memoryLimit;
+    directory;
+    diskLimit;
+    keepTail;
+    id = randomUUID();
+    streams = new Map();
+    constructor(memoryLimit, directory, diskLimit = 16 * 1024 * 1024, keepTail = true) {
+        this.memoryLimit = memoryLimit;
+        this.directory = directory;
+        this.diskLimit = diskLimit;
+        this.keepTail = keepTail;
+    }
+    append(name, chunk) {
+        let s = this.streams.get(name);
+        if (!s) {
+            s = { head: Buffer.alloc(0), tail: Buffer.alloc(0), bytes: 0, stored: 0, hash: createHash('sha256'), storedHash: createHash('sha256') };
+            if (this.directory)
+                try {
+                    mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+                    s.fd = openSync(join(this.directory, `${this.id}-${name}.log`), 'wx', 0o600);
+                }
+                catch {
+                    s.error = 'OUTPUT_ARCHIVE_OPEN_FAILED';
+                }
+            this.streams.set(name, s);
+        }
+        s.bytes += chunk.length;
+        s.hash.update(chunk);
+        const half = this.keepTail ? Math.floor(this.memoryLimit / 2) : this.memoryLimit;
+        if (s.head.length < half)
+            s.head = Buffer.concat([s.head, chunk.subarray(0, half - s.head.length)]);
+        if (this.keepTail)
+            s.tail = Buffer.concat([s.tail, chunk]).subarray(-Math.max(1, this.memoryLimit - half));
+        if (s.fd !== undefined && !s.error)
+            try {
+                const kept = chunk.subarray(0, Math.max(0, this.diskLimit - s.stored));
+                let offset = 0;
+                while (offset < kept.length)
+                    offset += writeSync(s.fd, kept, offset, kept.length - offset);
+                s.storedHash.update(kept);
+                s.stored += offset;
+                if (kept.length < chunk.length)
+                    s.error = 'OUTPUT_ARCHIVE_LIMIT';
+            }
+            catch {
+                s.error = 'OUTPUT_ARCHIVE_WRITE_FAILED';
+            }
+    }
+    text(name) {
+        const s = this.streams.get(name);
+        if (!s || this.memoryLimit === 0)
+            return '';
+        // When the output fits, tail contains the suffix after the head without a gap.
+        const tail = s.bytes <= this.memoryLimit ? s.tail.subarray(Math.max(0, s.tail.length - (s.bytes - s.head.length))) : s.tail;
+        let bytes = Buffer.concat([s.head, tail]).subarray(0, this.memoryLimit);
+        while (bytes.length && bytes.toString('utf8').endsWith('\ufffd'))
+            bytes = bytes.subarray(0, -1);
+        return bytes.toString('utf8');
+    }
+    finish() {
+        const output = {};
+        for (const [name, s] of this.streams) {
+            if (s.fd !== undefined) {
+                try {
+                    closeSync(s.fd);
+                }
+                catch {
+                    s.error = 'OUTPUT_ARCHIVE_CLOSE_FAILED';
+                }
+                ;
+                delete s.fd;
+            }
+            output[name] = { id: `${this.id}-${name}.log`, bytes: s.bytes, storedBytes: s.stored, sha256: s.hash.digest('hex'), storedSha256: s.storedHash.digest('hex'), omittedStart: s.head.length, omittedEnd: Math.max(s.head.length, s.bytes - s.tail.length), complete: !!this.directory && s.stored === s.bytes && !s.error, ...(s.error ? { error: s.error } : {}) };
+        }
+        return output;
+    }
+}

package/dist/tools/shell.d.ts

@@ -1,3 +1,4 @@
+import { ShellOutput } from './shell-output.js';
 export interface ShellResult {
     code: number | null;
     stdout: string;
@@ -5,6 +6,7 @@ export interface ShellResult {
     truncated: boolean;
     timedOut: boolean;
     aborted: boolean;
+    outputArchive?: ReturnType<ShellOutput['finish']>;
 }
 /** Read-only prerequisite probe; never provisions accounts or changes permissions. */
 export declare function checkShellSandbox(): Promise<{
@@ -15,6 +17,8 @@ export declare function quoteWindowsArgument(value: string): string;
 /** Build the command text expected by srt without interpreting model argv as shell syntax. */
 export declare function encodeSandboxCommand(command: string, args: string[], platform?: NodeJS.Platform): string;
 export declare function decodeUtf8WithinByteLimit(value: Buffer, maxBytes: number): string;
+/** Deterministic argv validation, shared by pre-approval and actual execution. */
+export declare function validateShellInvocation(command: string, args?: string[]): void;
 export declare function runShell(command: string, args?: string[], options?: {
     cwd?: string;
     signal?: AbortSignal;
@@ -22,4 +26,6 @@ export declare function runShell(command: string, args?: string[], options?: {
     maxOutputBytes?: number;
     env?: NodeJS.ProcessEnv;
     allowedDomains?: string[];
+    outputDirectory?: string;
+    maxArchiveBytes?: number;
 }): Promise<ShellResult>;