@themoltnet/pi-runtime 0.4.0 → 0.5.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;
 
 /**
@@ -576,10 +578,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 +688,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 +720,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 +742,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>>;
@@ -1134,6 +1142,32 @@ 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';
+    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 {