@themoltnet/pi-runtime 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -14,6 +14,7 @@ import { GrepToolInput } from '@earendil-works/pi-coding-agent';
 import { LoadSkillsResult } from '@earendil-works/pi-coding-agent';
 import { LsOperations } from '@earendil-works/pi-coding-agent';
 import { Model } from '@earendil-works/pi-ai';
+import { ModelRegistry } from '@earendil-works/pi-coding-agent';
 import { Readable } from 'node:stream';
 import { ReadOperations } from '@earendil-works/pi-coding-agent';
 import { ShellCommandAnalyzer } from '@themoltnet/shell-command-analyzer';
@@ -69,6 +70,8 @@ declare interface BuildAgentSessionArgs {
     piAuthDir: string;
     /** Resolved pi model handle (provider + model id). */
     modelHandle: Model<Api>;
+    /** Registry that resolved modelHandle, including custom providers/auth. */
+    modelRegistry?: ModelRegistry;
     /** Optional runtime-profile thinking/reasoning level applied at session start. */
     thinkingLevel?: PiThinkingLevel | null;
     /** Optional runtime-profile sampling temperature applied to provider requests. */
@@ -189,6 +192,8 @@ export declare interface CreateSubagentToolArgs {
     piAuthDir: string;
     /** Resolved pi model handle — subagents share it. */
     modelHandle: Model<Api>;
+    /** Registry that resolved modelHandle — subagents share it. */
+    modelRegistry?: ModelRegistry;
     /** Runtime-profile thinking/reasoning level — subagents inherit it. */
     thinkingLevel?: PiThinkingLevel | null;
     /** Runtime-profile sampling temperature — subagents inherit it. */
@@ -349,10 +354,7 @@ export declare function definePiTool(options: PiToolFactoryOptions): PiToolContr
 export declare function enabledPiToolNames(input: {
     tools: readonly ToolDefinition[];
     extensions?: readonly PiExtensionContribution[];
-    policy?: {
-        enforcement: ToolEnforcement;
-        allowedTools: ReadonlySet<string>;
-    };
+    policy?: ModelVisibleToolPolicy;
 }): string[] | undefined;
 
 /**
@@ -496,18 +498,11 @@ export declare interface ExecutePiTaskOptions {
      */
     maxBashTimeouts?: number;
     /**
-     * Number of correction turns allowed after the first invalid submit-output
-     * tool call. A value of 2 permits three invalid submit calls total before
-     * the attempt fails with output_validation_failed.
-     */
-    maxSubmitValidationRetries?: number;
-    /**
-     * Number of same-session re-prompts when the model ends its turn WITHOUT
-     * calling the submit-output tool at all (no captured payload and no
-     * exhausted validation budget). Distinct from
-     * `maxSubmitValidationRetries`, which recovers *invalid-args* submit calls.
-     * Each re-prompt names the submit tool and forbids a prose reply. When the
-     * budget is spent the attempt still fails with `submit_output_missing`.
+     * Number of same-session re-prompts when the model ends its turn without a
+     * valid submit-output call. A missing call receives the ordinary submit
+     * reminder; an invalid call receives its latest validation failure. When the
+     * budget is spent the attempt fails with the latest validation error, or
+     * `submit_output_missing` if the tool was never called.
      * Only applies to task types that register a submit tool. Default `3`. Set
      * to `0` to disable. See #1528.
      */
@@ -576,10 +571,7 @@ export declare interface ExecutePiTaskOptions {
     resolveVmTemplate?: () => Promise<ResolvedGondolinTemplate>;
 }
 
-export declare function filterModelVisibleTools(tools: readonly ToolDefinition[], policy?: {
-    enforcement: ToolEnforcement;
-    allowedTools: ReadonlySet<string>;
-}): ToolDefinition[];
+export declare function filterModelVisibleTools(tools: readonly ToolDefinition[], policy?: ModelVisibleToolPolicy): ToolDefinition[];
 
 /**
  * Resolve the main worktree root (where .moltnet/ lives — it's untracked,
@@ -689,10 +681,17 @@ export declare interface InjectTaskContextArgs {
 
 export declare function isKernelTool(name: string): boolean;
 
-export declare function isToolVisible(name: string, policy?: {
-    enforcement: ToolEnforcement;
-    allowedTools: ReadonlySet<string>;
-}): boolean;
+/**
+ * Check containment for already-resolved lexical or real paths.
+ *
+ * Callers that accept untrusted paths must resolve/realpath at their I/O
+ * boundary first; keeping the platform-specific relative-path rule here avoids
+ * subtly different `..` and absolute-path handling across runtime cleanup,
+ * session sync, and artifact staging.
+ */
+export declare function isResolvedPathInsideRoot(path: string, root: string): boolean;
+
+export declare function isToolVisible(name: string, policy?: ModelVisibleToolPolicy): boolean;
 
 export declare function loadCredentials(agentDir: string): VmCredentials;
 
@@ -714,20 +713,14 @@ export declare function materializePiExtensions(input: {
     runtime: PiRuntimeDefinition;
     context: PiToolContext;
     target: 'parent' | 'subagent';
-    policy?: {
-        enforcement: ToolEnforcement;
-        allowedTools: ReadonlySet<string>;
-    };
+    policy?: ModelVisibleToolPolicy;
 }): Promise<PiExtensionFactory[]>;
 
 export declare function materializePiTools(input: {
     runtime: PiRuntimeDefinition;
     context: PiToolContext;
     target: 'parent' | 'subagent';
-    policy?: {
-        enforcement: ToolEnforcement;
-        allowedTools: ReadonlySet<string>;
-    };
+    policy?: ModelVisibleToolPolicy;
 }): Promise<ToolDefinition[]>;
 
 /**
@@ -742,6 +735,14 @@ declare interface MissingShellCommand {
     dynamicTokenCount: number;
 }
 
+export declare interface ModelVisibleToolPolicy {
+    enforcement: ToolEnforcement;
+    allowedTools: ReadonlySet<string>;
+    allowedShellCommands?: readonly {
+        argvPrefix: readonly string[];
+    }[];
+}
+
 export declare const MOLTNET_TOOL_NAMES: readonly ["moltnet_pack_get", "moltnet_pack_create", "moltnet_pack_provenance", "moltnet_pack_render", "moltnet_rendered_pack_list", "moltnet_rendered_pack_get", "moltnet_diary_tags", "moltnet_list_entries", "moltnet_get_entry", "moltnet_search_entries", "moltnet_create_entry", "moltnet_get_task", "moltnet_list_task_attempts", "moltnet_list_task_messages", "moltnet_upload_task_artifact", "moltnet_list_task_artifacts", "moltnet_download_task_artifact", "moltnet_review_session_errors", "moltnet_host_exec"];
 
 declare type MoltNetAgent = Awaited<ReturnType<typeof connect>>;
@@ -948,10 +949,16 @@ export declare interface PiTaskExecutionPlan {
      */
     workspaceId: string | null;
     /**
-     * Branch to create or reopen for the workspace. `null` means no dedicated
-     * worktree is required.
+     * Branch to create or reopen for the workspace. `null` may instead mean a
+     * detached dedicated worktree when `workspaceRevision` is present.
      */
     worktreeBranch: string | null;
+    /**
+     * Immutable commit that must back the selected workspace. Shared mounts are
+     * verified against it; dedicated review worktrees are created detached at
+     * it. `null` preserves the existing branch-oriented behavior.
+     */
+    workspaceRevision?: string | null;
     /**
      * Base ref a NEW `worktreeBranch` is cut from. Used by `fork` continuations
      * to branch from the parent's tip instead of the default (main/HEAD). Ignored
@@ -1134,6 +1141,33 @@ declare interface RuntimeInstructorContext {
     guestWorkspace: string;
     /** Optional correlation id grouping this task with others. */
     correlationId: string | null;
+    /** Effective, session-start policy projected into model-visible guidance. */
+    toolPolicy?: RuntimeInstructorToolPolicy;
+    sandbox?: RuntimeInstructorSandbox;
+}
+
+declare interface RuntimeInstructorSandbox {
+    workspaceMode: 'shared_mount' | 'dedicated_worktree' | 'scratch_mount';
+    workspaceRevision?: string | null;
+    vfsShadowMode: 'none' | 'deny' | 'tmpfs';
+    vfsShadowPatterns: readonly string[];
+    nodeModulesWriteMode?: 'tmpfs';
+    verifiedExecutables: readonly string[];
+    allowedHosts: readonly string[];
+    allowedInternalHosts: readonly string[];
+}
+
+declare interface RuntimeInstructorToolPolicy {
+    enforcement: 'off' | 'watch' | 'enforce';
+    allowedTools: readonly string[];
+    allowedShellCommands: readonly {
+        argvPrefix: readonly string[];
+    }[];
+    unavailableTools?: readonly string[];
+    unavailableShellCommands?: readonly {
+        argvPrefix: readonly string[];
+    }[];
+    degraded: boolean;
 }
 
 export declare interface SandboxConfig {