@tangle-network/agent-interface 0.31.0 → 0.32.0

package/README.md

@@ -62,6 +62,13 @@ const provider: AgentEnvironmentProvider = {
 };
 ```
 
+## Exact process environments
+
+Providers may expose the optional `exactProcess` capability for isolated, reproducible process execution.
+It is separate from agent-backed `create()` because it guarantees a fresh environment, immutable image identity, explicit resources, bounded exact-byte file reads, shell-free argv, replacement process environment, recoverable output and terminal reason, bounded network access, and collision-safe idempotent recovery without starting a provider-managed agent.
+Higher-level runtimes can use this primitive for measured candidates without making candidate lifecycle part of the provider contract.
+Providers must omit the capability unless every property is enforced on their real execution path.
+
 ## Frozen improvement candidates
 
 `AgentCandidateBundle` is the portable output of an improvement run: a recursively strict profile, an explicit disabled/no-op/changed code result, a shell-free launch, optional knowledge, isolated memory, ancestry, and spend.

package/dist/agent-candidate-code-schema.js

@@ -174,6 +174,16 @@ export const agentCandidateExecutionSchema = z
 })
     .strict()
     .superRefine((execution, ctx) => {
+    const requiresPath = execution.launch.kind === "container-command"
+        ? !execution.launch.executable.startsWith("/")
+        : execution.launch.interpreter !== undefined;
+    if (requiresPath && !execution.env?.PATH?.value.trim()) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["env", "PATH"],
+            message: "relative candidate executables require an explicit public PATH",
+        });
+    }
     if (execution.env?.TANGLE_CANDIDATE_TASK_PATH !== undefined) {
         ctx.addIssue({
             code: "custom",

package/dist/agent-candidate-execution-plan-schema.js

@@ -320,6 +320,13 @@ export const agentCandidateExecutionPlanMaterialSchema = z
 })
     .strict()
     .superRefine((material, ctx) => {
+    if (!material.launch.executable.startsWith("/") && !material.launch.env.PATH?.value.trim()) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["launch", "env", "PATH"],
+            message: "relative execution-plan executables require an explicit public PATH",
+        });
+    }
     const routeIds = material.model.routes.map((route) => route.kind === "mode" || route.kind === "subagent"
         ? `${route.kind}:${route.name}`
         : route.kind);

package/dist/agent-candidate.test-fixture.d.ts

@@ -71,6 +71,10 @@ export declare function candidateFixture(): {
                 kind: "public";
                 value: string;
             };
+            PATH: {
+                kind: "public";
+                value: string;
+            };
         };
         environment: {
             kind: "pinned-container";

package/dist/agent-candidate.test-fixture.js

@@ -62,6 +62,7 @@ export function candidateFixture() {
             cwd: { workspace: "candidate", path: "." },
             env: {
                 NODE_ENV: { kind: "public", value: "production" },
+                PATH: { kind: "public", value: "/usr/local/bin:/usr/bin:/bin" },
             },
             environment: {
                 kind: "pinned-container",

package/dist/environment-provider.d.ts

@@ -1,4 +1,5 @@
 import type { AgentProfile, AgentProfileCapabilities, AgentProfileValidationResult } from "./agent-profile.js";
+import type { AgentCandidateTermination } from "./agent-candidate.js";
 import type { InputPart, StreamEvent, TokenUsage } from "./index.js";
 /** Portable profile reference: inline profile or provider catalog id. */
 export type AgentProfileRef = AgentProfile | string;
@@ -48,6 +49,128 @@ export interface ExecResult {
     stdout: string;
     stderr: string;
 }
+export type AgentExactProcessEgressMode = "blocked" | "strict";
+/**
+ * Outbound network policy for an exact process environment. `blocked` denies
+ * every protocol. `strict` permits only the named domains; direct-address,
+ * alternate-protocol, and cross-environment bypasses must fail.
+ */
+export type AgentExactProcessEgressPolicy = {
+    mode: "blocked";
+} | {
+    mode: "strict";
+    allowDomains: readonly string[];
+};
+/** Explicit portable limits for an exact process environment. */
+export interface AgentExactProcessResources {
+    /** Positive CPU core count. */
+    cpu: number;
+    /** Positive integer mebibytes of memory. */
+    memoryMb: number;
+    /** Positive integer mebibytes of disk. */
+    diskMb: number;
+}
+/** Terminal or running state reported by an exact process host. */
+export interface AgentExactProcessStatus {
+    pid: number;
+    running: boolean;
+    /** -1 while running; the exact process exit code after termination. */
+    exitCode: number;
+    exitSignal?: string;
+    /** Required after termination; absent only while running. */
+    termination?: AgentCandidateTermination;
+}
+/** Recoverable handle for one shell-free process. */
+export interface AgentExactProcess {
+    readonly pid: number;
+    status(): Promise<AgentExactProcessStatus>;
+    wait(): Promise<AgentCandidateTermination>;
+    /** Force-stop the full process tree. Idempotent after the process exits. */
+    kill(): Promise<void>;
+    /** Each iteration replays buffered UTF-8 stdout, then continues until exit. */
+    stdout(): AsyncIterable<string>;
+    /** Each iteration replays buffered UTF-8 stderr, then continues until exit. */
+    stderr(): AsyncIterable<string>;
+}
+/** Shell-free launch whose environment replaces, rather than extends, ambient variables. */
+export interface AgentExactProcessLaunch {
+    /** Absolute path unless {@link env} supplies an explicit `PATH`. */
+    executable: string;
+    args: readonly string[];
+    cwd: string;
+    env: Readonly<Record<string, string>>;
+    stdin?: string;
+    /** Positive integer milliseconds, or zero to disable the process timeout. */
+    timeoutMs: number;
+}
+export interface AgentExactProcessManager {
+    list(): Promise<AgentExactProcessStatus[]>;
+    get(pid: number): Promise<AgentExactProcess | null>;
+    /** Providers must honor the abort signal when supplied. */
+    spawn(input: AgentExactProcessLaunch, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentExactProcess>;
+}
+/**
+ * Fresh environment with no provider-managed user workload.
+ *
+ * Authenticated provider control services may exist, but no customer workload
+ * ingress or provider-managed user process may exist. The launched process
+ * sees only its supplied environment variables, with no ambient or injected
+ * secrets.
+ */
+export interface AgentExactProcessEnvironment {
+    readonly id: string;
+    readonly provider: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly process: AgentExactProcessManager;
+    /** Write exact bytes to an absolute path with a POSIX mode from 0 through 07777. Providers must honor the abort signal when supplied. */
+    writeFile(path: string, bytes: Uint8Array, options: {
+        mode: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Read exact bytes or fail before content is loaded when the file exceeds maxBytes. */
+    readFile(path: string, options: {
+        maxBytes: number;
+        signal?: AbortSignal;
+    }): Promise<Uint8Array>;
+    destroy(): Promise<void>;
+}
+export interface AgentExactProcessEnvironmentQuery {
+    /** Every supplied key/value must match persisted environment metadata exactly. */
+    metadata?: Record<string, unknown>;
+    providerOptions?: Record<string, unknown>;
+}
+/** Input for a fresh environment with no provider-managed agent process. */
+export interface CreateAgentExactProcessEnvironmentInput {
+    /** Provider-specific immutable image reference. */
+    image: string;
+    egress: AgentExactProcessEgressPolicy;
+    /** Positive integer milliseconds. */
+    maxLifetimeMs: number;
+    /** Positive integer milliseconds when supplied. */
+    provisionTimeoutMs?: number;
+    /** Required limits; exact execution never inherits provider defaults. */
+    resources: AgentExactProcessResources;
+    metadata: Record<string, unknown>;
+    idempotencyKey: string;
+    signal?: AbortSignal;
+    /** Provider-native fields may narrow, but never weaken, the isolation contract. */
+    providerOptions?: Record<string, unknown>;
+}
+/** Optional all-or-nothing exact process capability of an environment provider. */
+export interface AgentExactProcessProvider {
+    /**
+     * Repeating the same idempotency key and input returns the same environment.
+     * Reusing the key with any different create input must fail.
+     * Unsupported egress modes must fail instead of weakening the policy.
+     */
+    create(input: CreateAgentExactProcessEnvironmentInput): Promise<AgentExactProcessEnvironment>;
+    /** Ordinary environments must return null. */
+    get(id: string): Promise<AgentExactProcessEnvironment | null>;
+    /** Return every matching exact environment; providers own any native pagination. */
+    list(query?: AgentExactProcessEnvironmentQuery): Promise<AgentExactProcessEnvironment[]>;
+}
 export interface CheckpointRequest {
     name?: string;
     metadata?: Record<string, unknown>;
@@ -165,6 +288,10 @@ export interface AgentEnvironmentCapabilities {
     placement: boolean;
     usage: boolean;
     confidential: boolean;
+    /** Present only when {@link AgentEnvironmentProvider.exactProcess} is implemented. */
+    exactProcess?: {
+        egress: readonly AgentExactProcessEgressMode[];
+    };
 }
 export interface CreateAgentEnvironmentInput {
     profile: AgentProfileRef;
@@ -182,6 +309,7 @@ export interface CreateAgentEnvironmentInput {
 }
 export interface AgentEnvironmentProvider {
     readonly name: string;
+    readonly exactProcess?: AgentExactProcessProvider;
     capabilities(): AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>;
     validateProfile?(profile: AgentProfileRef): AgentProfileValidationResult | Promise<AgentProfileValidationResult>;
     create(input: CreateAgentEnvironmentInput): Promise<AgentEnvironment>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",