@tangle-network/agent-interface 0.30.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-outcome-schema.d.ts

@@ -12,8 +12,8 @@ export declare const agentCandidateModelSettlementCallSchema: z.ZodObject<{
     generationId: z.ZodString;
     traceSpanId: z.ZodString;
     status: z.ZodEnum<{
-        succeeded: "succeeded";
         failed: "failed";
+        succeeded: "succeeded";
     }>;
     model: z.ZodString;
     startedAtMs: z.ZodNumber;
@@ -30,8 +30,8 @@ export declare const agentCandidateModelSettlementMaterialSchema: z.ZodObject<{
         generationId: z.ZodString;
         traceSpanId: z.ZodString;
         status: z.ZodEnum<{
-            succeeded: "succeeded";
             failed: "failed";
+            succeeded: "succeeded";
         }>;
         model: z.ZodString;
         startedAtMs: z.ZodNumber;
@@ -79,7 +79,7 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
             callId: string;
             generationId: string;
             traceSpanId: string;
-            status: "succeeded" | "failed";
+            status: "failed" | "succeeded";
             model: string;
             startedAtMs: number;
             endedAtMs: number;
@@ -114,7 +114,7 @@ export declare const agentCandidateModelSettlementEvidenceSchema: z.ZodObject<{
             callId: string;
             generationId: string;
             traceSpanId: string;
-            status: "succeeded" | "failed";
+            status: "failed" | "succeeded";
             model: string;
             startedAtMs: number;
             endedAtMs: number;

package/dist/agent-candidate-promotion-schema.d.ts

@@ -2266,7 +2266,7 @@ export declare const candidateExecutionEvidenceSchema: z.ZodObject<{
                     callId: string;
                     generationId: string;
                     traceSpanId: string;
-                    status: "succeeded" | "failed";
+                    status: "failed" | "succeeded";
                     model: string;
                     startedAtMs: number;
                     endedAtMs: number;
@@ -2301,7 +2301,7 @@ export declare const candidateExecutionEvidenceSchema: z.ZodObject<{
                     callId: string;
                     generationId: string;
                     traceSpanId: string;
-                    status: "succeeded" | "failed";
+                    status: "failed" | "succeeded";
                     model: string;
                     startedAtMs: number;
                     endedAtMs: number;
@@ -4991,7 +4991,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                             callId: string;
                             generationId: string;
                             traceSpanId: string;
-                            status: "succeeded" | "failed";
+                            status: "failed" | "succeeded";
                             model: string;
                             startedAtMs: number;
                             endedAtMs: number;
@@ -5026,7 +5026,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                             callId: string;
                             generationId: string;
                             traceSpanId: string;
-                            status: "succeeded" | "failed";
+                            status: "failed" | "succeeded";
                             model: string;
                             startedAtMs: number;
                             endedAtMs: number;
@@ -6342,7 +6342,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                             callId: string;
                             generationId: string;
                             traceSpanId: string;
-                            status: "succeeded" | "failed";
+                            status: "failed" | "succeeded";
                             model: string;
                             startedAtMs: number;
                             endedAtMs: number;
@@ -6377,7 +6377,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                             callId: string;
                             generationId: string;
                             traceSpanId: string;
-                            status: "succeeded" | "failed";
+                            status: "failed" | "succeeded";
                             model: string;
                             startedAtMs: number;
                             endedAtMs: number;
@@ -9249,7 +9249,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                 callId: string;
                                 generationId: string;
                                 traceSpanId: string;
-                                status: "succeeded" | "failed";
+                                status: "failed" | "succeeded";
                                 model: string;
                                 startedAtMs: number;
                                 endedAtMs: number;
@@ -9284,7 +9284,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                 callId: string;
                                 generationId: string;
                                 traceSpanId: string;
-                                status: "succeeded" | "failed";
+                                status: "failed" | "succeeded";
                                 model: string;
                                 startedAtMs: number;
                                 endedAtMs: number;
@@ -10600,7 +10600,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                 callId: string;
                                 generationId: string;
                                 traceSpanId: string;
-                                status: "succeeded" | "failed";
+                                status: "failed" | "succeeded";
                                 model: string;
                                 startedAtMs: number;
                                 endedAtMs: number;
@@ -10635,7 +10635,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                 callId: string;
                                 generationId: string;
                                 traceSpanId: string;
-                                status: "succeeded" | "failed";
+                                status: "failed" | "succeeded";
                                 model: string;
                                 startedAtMs: number;
                                 endedAtMs: number;
@@ -11242,6 +11242,10 @@ export declare const agentImprovementActivationSchema: z.ZodObject<{
     reviewDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     experimentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
     candidateBundleDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    intent: z.ZodEnum<{
+        "activate-candidate": "activate-candidate";
+        "restore-baseline": "restore-baseline";
+    }>;
     targets: z.ZodTuple<[z.ZodObject<{
         surface: z.ZodEnum<{
             prompt: "prompt";
@@ -11276,5 +11280,130 @@ export declare const agentImprovementActivationSchema: z.ZodObject<{
     fundingOwner: z.ZodString;
     authorizedBy: z.ZodString;
     authorizedAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+export declare const agentImprovementActivationResultSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"agent-improvement-activation-result">;
+    idempotencyKey: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    attemptedAt: z.ZodISODateTime;
+    completedAt: z.ZodISODateTime;
+    outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"applied">;
+        transactionId: z.ZodString;
+        targets: z.ZodTuple<[z.ZodObject<{
+            surface: z.ZodEnum<{
+                prompt: "prompt";
+                tools: "tools";
+                mcp: "mcp";
+                subagents: "subagents";
+                hooks: "hooks";
+                skills: "skills";
+                "agent-profile": "agent-profile";
+                memory: "memory";
+                code: "code";
+                knowledge: "knowledge";
+            }>;
+            identity: z.ZodString;
+            beforeDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            afterDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>], z.ZodObject<{
+            surface: z.ZodEnum<{
+                prompt: "prompt";
+                tools: "tools";
+                mcp: "mcp";
+                subagents: "subagents";
+                hooks: "hooks";
+                skills: "skills";
+                "agent-profile": "agent-profile";
+                memory: "memory";
+                code: "code";
+                knowledge: "knowledge";
+            }>;
+            identity: z.ZodString;
+            beforeDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+            afterDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"already-applied">;
+        targets: z.ZodTuple<[z.ZodObject<{
+            surface: z.ZodEnum<{
+                prompt: "prompt";
+                tools: "tools";
+                mcp: "mcp";
+                subagents: "subagents";
+                hooks: "hooks";
+                skills: "skills";
+                "agent-profile": "agent-profile";
+                memory: "memory";
+                code: "code";
+                knowledge: "knowledge";
+            }>;
+            identity: z.ZodString;
+            currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>], z.ZodObject<{
+            surface: z.ZodEnum<{
+                prompt: "prompt";
+                tools: "tools";
+                mcp: "mcp";
+                subagents: "subagents";
+                hooks: "hooks";
+                skills: "skills";
+                "agent-profile": "agent-profile";
+                memory: "memory";
+                code: "code";
+                knowledge: "knowledge";
+            }>;
+            identity: z.ZodString;
+            currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"conflict">;
+        targets: z.ZodTuple<[z.ZodObject<{
+            surface: z.ZodEnum<{
+                prompt: "prompt";
+                tools: "tools";
+                mcp: "mcp";
+                subagents: "subagents";
+                hooks: "hooks";
+                skills: "skills";
+                "agent-profile": "agent-profile";
+                memory: "memory";
+                code: "code";
+                knowledge: "knowledge";
+            }>;
+            identity: z.ZodString;
+            currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>], z.ZodObject<{
+            surface: z.ZodEnum<{
+                prompt: "prompt";
+                tools: "tools";
+                mcp: "mcp";
+                subagents: "subagents";
+                hooks: "hooks";
+                skills: "skills";
+                "agent-profile": "agent-profile";
+                memory: "memory";
+                code: "code";
+                knowledge: "knowledge";
+            }>;
+            identity: z.ZodString;
+            currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"expired">;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"unsupported">;
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"failed">;
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"indeterminate">;
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>], "status">;
     digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
 }, z.core.$strict>;

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

@@ -750,6 +750,13 @@ export const agentImprovementReviewSchema = z
 })
     .strict()
     .refine(isCanonicalJsonValue, "review must contain only RFC 8785 JSON values");
+const improvementActivationTargetSchema = z
+    .object({
+    surface: improvementSurfaceSchema,
+    identity: z.string().min(1).max(500),
+    expectedBaseDigest: sha256DigestSchema,
+})
+    .strict();
 export const agentImprovementActivationSchema = z
     .object({
     kind: z.literal("agent-improvement-activation"),
@@ -757,26 +764,14 @@ export const agentImprovementActivationSchema = z
     reviewDigest: sha256DigestSchema,
     experimentDigest: sha256DigestSchema,
     candidateBundleDigest: sha256DigestSchema,
+    intent: z.enum(["activate-candidate", "restore-baseline"]),
     targets: z
-        .tuple([
-        z
-            .object({
-            surface: improvementSurfaceSchema,
-            identity: z.string().min(1).max(500),
-            expectedBaseDigest: sha256DigestSchema,
-        })
-            .strict(),
-    ])
-        .rest(z
-        .object({
-        surface: improvementSurfaceSchema,
-        identity: z.string().min(1).max(500),
-        expectedBaseDigest: sha256DigestSchema,
-    })
-        .strict()),
+        .tuple([improvementActivationTargetSchema])
+        .rest(improvementActivationTargetSchema),
     fundingOwner: z.string().min(1).max(500),
     authorizedBy: z.string().min(1).max(500),
     authorizedAt: z.iso.datetime(),
+    expiresAt: z.iso.datetime(),
     digest: sha256DigestSchema,
 })
     .strict()
@@ -789,7 +784,112 @@ export const agentImprovementActivationSchema = z
             message: "activation targets must be unique by surface and identity",
         });
     }
+    if (Date.parse(activation.expiresAt) <= Date.parse(activation.authorizedAt)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["expiresAt"],
+            message: "activation expiry must follow its authorization time",
+        });
+    }
     if (!isCanonicalJsonValue(activation)) {
         ctx.addIssue({ code: "custom", message: "activation must contain only RFC 8785 JSON values" });
     }
 });
+const improvementActivationTargetTransitionSchema = z
+    .object({
+    surface: improvementSurfaceSchema,
+    identity: z.string().min(1).max(500),
+    beforeDigest: sha256DigestSchema,
+    afterDigest: sha256DigestSchema,
+})
+    .strict();
+const improvementActivationTargetStateSchema = z
+    .object({
+    surface: improvementSurfaceSchema,
+    identity: z.string().min(1).max(500),
+    currentDigest: sha256DigestSchema,
+})
+    .strict();
+const improvementActivationOutcomeSchema = z.discriminatedUnion("status", [
+    z
+        .object({
+        status: z.literal("applied"),
+        transactionId: z.string().min(1).max(500),
+        targets: z
+            .tuple([improvementActivationTargetTransitionSchema])
+            .rest(improvementActivationTargetTransitionSchema),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("already-applied"),
+        targets: z
+            .tuple([improvementActivationTargetStateSchema])
+            .rest(improvementActivationTargetStateSchema),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("conflict"),
+        targets: z
+            .tuple([improvementActivationTargetStateSchema])
+            .rest(improvementActivationTargetStateSchema),
+    })
+        .strict(),
+    z.object({ status: z.literal("expired") }).strict(),
+    z
+        .object({
+        status: z.literal("unsupported"),
+        code: z.string().min(1).max(100),
+        message: z.string().min(1).max(2_000),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("failed"),
+        code: z.string().min(1).max(100),
+        message: z.string().min(1).max(2_000),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("indeterminate"),
+        code: z.string().min(1).max(100),
+        message: z.string().min(1).max(2_000),
+    })
+        .strict(),
+]);
+export const agentImprovementActivationResultSchema = z
+    .object({
+    kind: z.literal("agent-improvement-activation-result"),
+    idempotencyKey: sha256DigestSchema,
+    attemptedAt: z.iso.datetime(),
+    completedAt: z.iso.datetime(),
+    outcome: improvementActivationOutcomeSchema,
+    digest: sha256DigestSchema,
+})
+    .strict()
+    .superRefine((result, ctx) => {
+    if (Date.parse(result.completedAt) < Date.parse(result.attemptedAt)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["completedAt"],
+            message: "activation completion cannot predate its attempt",
+        });
+    }
+    const targets = "targets" in result.outcome ? result.outcome.targets : [];
+    const identities = targets.map((target) => `${target.surface}\u0000${target.identity}`);
+    if (new Set(identities).size !== identities.length) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["outcome", "targets"],
+            message: "activation outcome targets must be unique by surface and identity",
+        });
+    }
+    if (!isCanonicalJsonValue(result)) {
+        ctx.addIssue({
+            code: "custom",
+            message: "activation result must contain only RFC 8785 JSON values",
+        });
+    }
+});

package/dist/agent-candidate-receipt-schema.d.ts

@@ -1023,7 +1023,7 @@ export declare const agentCandidateRunReceiptSchema: z.ZodObject<{
                 callId: string;
                 generationId: string;
                 traceSpanId: string;
-                status: "succeeded" | "failed";
+                status: "failed" | "succeeded";
                 model: string;
                 startedAtMs: number;
                 endedAtMs: number;
@@ -1058,7 +1058,7 @@ export declare const agentCandidateRunReceiptSchema: z.ZodObject<{
                 callId: string;
                 generationId: string;
                 traceSpanId: string;
-                status: "succeeded" | "failed";
+                status: "failed" | "succeeded";
                 model: string;
                 startedAtMs: number;
                 endedAtMs: number;

package/dist/agent-candidate.d.ts

@@ -806,6 +806,7 @@ export interface AgentImprovementActivationTarget {
     /** Current target state that activation is allowed to replace. */
     expectedBaseDigest: Sha256Digest;
 }
+export type AgentImprovementActivationIntent = "activate-candidate" | "restore-baseline";
 /** Authority receipt permitting activation of one already-measured candidate. */
 export interface AgentImprovementActivation {
     kind: "agent-improvement-activation";
@@ -813,10 +814,56 @@ export interface AgentImprovementActivation {
     reviewDigest: Sha256Digest;
     experimentDigest: Sha256Digest;
     candidateBundleDigest: Sha256Digest;
+    intent: AgentImprovementActivationIntent;
     targets: [AgentImprovementActivationTarget, ...AgentImprovementActivationTarget[]];
     fundingOwner: string;
     authorizedBy: string;
     authorizedAt: string;
+    expiresAt: string;
+    digest: Sha256Digest;
+}
+export interface AgentImprovementActivationTargetTransition {
+    surface: AgentImprovementSurface;
+    identity: string;
+    beforeDigest: Sha256Digest;
+    afterDigest: Sha256Digest;
+}
+export interface AgentImprovementActivationTargetState {
+    surface: AgentImprovementSurface;
+    identity: string;
+    currentDigest: Sha256Digest;
+}
+export type AgentImprovementActivationOutcome = {
+    /** Every target changed atomically from the authorized state to the requested bundle. */
+    status: "applied";
+    transactionId: string;
+    targets: [
+        AgentImprovementActivationTargetTransition,
+        ...AgentImprovementActivationTargetTransition[]
+    ];
+} | {
+    /** No write occurred; targets are already desired or no longer match the authorized base. */
+    status: "already-applied" | "conflict";
+    targets: [
+        AgentImprovementActivationTargetState,
+        ...AgentImprovementActivationTargetState[]
+    ];
+} | {
+    status: "expired";
+} | {
+    /** `failed` proves no write; `indeterminate` means commit state must be reconciled. */
+    status: "unsupported" | "failed" | "indeterminate";
+    code: string;
+    message: string;
+};
+/** Immutable outcome of one idempotent, transaction-wide activation attempt. */
+export interface AgentImprovementActivationResult {
+    kind: "agent-improvement-activation-result";
+    /** The activation digest is also its stable retry key. */
+    idempotencyKey: Sha256Digest;
+    attemptedAt: string;
+    completedAt: string;
+    outcome: AgentImprovementActivationOutcome;
     digest: Sha256Digest;
 }
 /** Complete execution of one exact experiment attempt. */

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.30.0",
+  "version": "0.32.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",