@tangle-network/agent-interface 1.5.0 → 1.7.0

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

@@ -8407,6 +8407,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
         "agent-profile": "agent-profile";
         memory: "memory";
         knowledge: "knowledge";
+        "rollout-policy": "rollout-policy";
     }>], z.ZodEnum<{
         prompt: "prompt";
         tools: "tools";
@@ -8418,6 +8419,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
         "agent-profile": "agent-profile";
         memory: "memory";
         knowledge: "knowledge";
+        "rollout-policy": "rollout-policy";
     }>>;
     proposedAt: z.ZodISODateTime;
     findings: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodCustom<AgentCandidateJsonValue, AgentCandidateJsonValue>>>;
@@ -14120,6 +14122,7 @@ export declare const agentImprovementActivationSchema: z.ZodObject<{
             "agent-profile": "agent-profile";
             memory: "memory";
             knowledge: "knowledge";
+            "rollout-policy": "rollout-policy";
         }>;
         identity: z.ZodString;
         expectedBaseDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -14135,6 +14138,7 @@ export declare const agentImprovementActivationSchema: z.ZodObject<{
             "agent-profile": "agent-profile";
             memory: "memory";
             knowledge: "knowledge";
+            "rollout-policy": "rollout-policy";
         }>;
         identity: z.ZodString;
         expectedBaseDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -14165,6 +14169,7 @@ export declare const agentImprovementActivationResultSchema: z.ZodObject<{
                 "agent-profile": "agent-profile";
                 memory: "memory";
                 knowledge: "knowledge";
+                "rollout-policy": "rollout-policy";
             }>;
             identity: z.ZodString;
             beforeDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -14181,6 +14186,7 @@ export declare const agentImprovementActivationResultSchema: z.ZodObject<{
                 "agent-profile": "agent-profile";
                 memory: "memory";
                 knowledge: "knowledge";
+                "rollout-policy": "rollout-policy";
             }>;
             identity: z.ZodString;
             beforeDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -14200,6 +14206,7 @@ export declare const agentImprovementActivationResultSchema: z.ZodObject<{
                 "agent-profile": "agent-profile";
                 memory: "memory";
                 knowledge: "knowledge";
+                "rollout-policy": "rollout-policy";
             }>;
             identity: z.ZodString;
             currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -14215,6 +14222,7 @@ export declare const agentImprovementActivationResultSchema: z.ZodObject<{
                 "agent-profile": "agent-profile";
                 memory: "memory";
                 knowledge: "knowledge";
+                "rollout-policy": "rollout-policy";
             }>;
             identity: z.ZodString;
             currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -14233,6 +14241,7 @@ export declare const agentImprovementActivationResultSchema: z.ZodObject<{
                 "agent-profile": "agent-profile";
                 memory: "memory";
                 knowledge: "knowledge";
+                "rollout-policy": "rollout-policy";
             }>;
             identity: z.ZodString;
             currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
@@ -14248,6 +14257,7 @@ export declare const agentImprovementActivationResultSchema: z.ZodObject<{
                 "agent-profile": "agent-profile";
                 memory: "memory";
                 knowledge: "knowledge";
+                "rollout-policy": "rollout-policy";
             }>;
             identity: z.ZodString;
             currentDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { AGENT_IMPROVEMENT_SURFACES } from "./agent-candidate.js";
 import { agentCandidateBundleSchema } from "./agent-candidate-schema.js";
 import { agentCandidateLineageSchema } from "./agent-candidate-lineage-schema.js";
 import { agentCandidateBenchmarkSuiteInputsSchema } from "./agent-candidate-task-schema.js";
@@ -7,18 +8,7 @@ import { refineAgentExecutionWithinLimits } from "./agent-execution-limits.js";
 import { agentCandidateMaterializationReceiptSchema, agentCandidateRunReceiptSchema, } from "./agent-candidate-receipt-schema.js";
 import { agentCandidateEvaluationPolicySchema, canonicalJsonObjectSchema, createMeasuredComparisonIdentityRegistry, measuredComparisonCommonShape, refineMeasuredComparisonSummary, } from "./agent-improvement-measurement-schema.js";
 import { agentProfileImprovementExecutionRefSchema, agentProfileImprovementMeasuredComparisonSchema, changedProfileImprovementSurfaces, } from "./agent-profile-improvement-schema.js";
-const improvementSurfaceSchema = z.enum([
-    "prompt",
-    "skills",
-    "tools",
-    "mcp",
-    "hooks",
-    "subagents",
-    "agent-profile",
-    "memory",
-    "code",
-    "knowledge",
-]);
+const improvementSurfaceSchema = z.enum(AGENT_IMPROVEMENT_SURFACES);
 export const agentCandidateExperimentSchema = z
     .object({
     kind: z.literal("agent-candidate-experiment"),

package/dist/agent-candidate.d.ts

@@ -709,7 +709,16 @@ export interface AgentCandidateRunReceipt {
     benchmarkResult: AgentCandidateBenchmarkResultEvidence;
     digest: Sha256Digest;
 }
-export type AgentImprovementSurface = "prompt" | "skills" | "tools" | "mcp" | "hooks" | "subagents" | "agent-profile" | "memory" | "code" | "knowledge";
+/**
+ * Every surface an improvement proposal can name. One owner: the validator
+ * ({@link agentCandidatePromotionSchema}'s surface enum) and every producer read this
+ * list, so a new surface cannot be proposable in one place and unnameable in another.
+ *
+ * `rollout-policy` is the inference-time structural-rollout dials
+ * (`profile.extensions['structural-rollout']`); `knowledge` is the corpus lane.
+ */
+export declare const AGENT_IMPROVEMENT_SURFACES: readonly ["prompt", "skills", "tools", "mcp", "hooks", "subagents", "agent-profile", "memory", "code", "knowledge", "rollout-policy"];
+export type AgentImprovementSurface = (typeof AGENT_IMPROVEMENT_SURFACES)[number];
 /** One paired Runtime execution from the exact signed experiment. */
 export interface AgentCandidateExperimentMeasurement {
     baseline: CandidateExecutionEvidence;

package/dist/agent-candidate.js

@@ -1,3 +1,24 @@
+/**
+ * Every surface an improvement proposal can name. One owner: the validator
+ * ({@link agentCandidatePromotionSchema}'s surface enum) and every producer read this
+ * list, so a new surface cannot be proposable in one place and unnameable in another.
+ *
+ * `rollout-policy` is the inference-time structural-rollout dials
+ * (`profile.extensions['structural-rollout']`); `knowledge` is the corpus lane.
+ */
+export const AGENT_IMPROVEMENT_SURFACES = Object.freeze([
+    "prompt",
+    "skills",
+    "tools",
+    "mcp",
+    "hooks",
+    "subagents",
+    "agent-profile",
+    "memory",
+    "code",
+    "knowledge",
+    "rollout-policy",
+]);
 /** Declare a candidate bundle while retaining literal inference. */
 export function defineAgentCandidateBundle(bundle) {
     return bundle;

package/dist/environment-runtime.d.ts

@@ -7,7 +7,7 @@ import type { TokenUsage } from "./execution-types.js";
 import { type InteractionAcknowledgement, type InteractionCapabilities, type InteractionResponseCommand, type RequestedInteractions } from "./interaction.js";
 import { type ContextTransferReceipt, type ContextTransferRequest, type NativeContextBoundaryProof, type NativeContextContinuationRequest, type NativeContextContinuationTurn } from "./portable-context.js";
 import { type AgentRunCancellationAcknowledgement, type AgentRunCancellationRequest, type AgentRunControlRef } from "./runtime-control.js";
-import type { AgentWorkspaceBranching } from "./workspace-branching.js";
+import type { AgentWorkspaceBranching, AgentWorkspaceBranchingProvider } from "./workspace-branching.js";
 import type { AgentEnvironmentQuery, AgentEnvironmentStatus, AgentEnvironmentSummary, AgentProfileRef, AgentSessionStatus, CheckpointRef, CheckpointRequest, ExecRequest, ExecResult, ForkRequest, PlacementInfo, ResourceRequest, WorkspaceRequest } from "./environment-requests.js";
 import type { AgentExactProcessEgressMode, AgentExactProcessProvider } from "./environment-exact-process.js";
 import type { AgentEnvironmentObservation } from "./environment-observation.js";
@@ -997,6 +997,15 @@ export declare function createAgentEnvironmentWithIdempotency<T extends object>(
 export interface AgentEnvironmentProvider {
     readonly name: string;
     readonly exactProcess?: AgentExactProcessProvider;
+    /**
+     * Reconstruct a source-scoped branching handle after a coordinator restart.
+     *
+     * This surface is intentionally separate from an environment-owned handle:
+     * lookup and cleanup requests identify operations, not their source. The
+     * provider owns source resolution and the underlying platform calls. A
+     * returned handle is bound to that source and must reject other scopes.
+     */
+    readonly workspaceBranching?: AgentWorkspaceBranchingProvider;
     capabilities(): AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>;
     validateProfile?(profile: AgentProfileRef): AgentProfileValidationResult | Promise<AgentProfileValidationResult>;
     /**

package/dist/harness-capabilities.d.ts

@@ -61,6 +61,15 @@ export interface ModelReasoningCapability {
  * lower ceiling caps the list there. Pass `model` from your catalog; omit it for the harness-only set.
  */
 export declare function reasoningEffortsFor(harness: HarnessType, model?: ModelReasoningCapability | null): readonly ReasoningEffort[];
+/**
+ * The native control token a harness applies for one canonical effort, or `null` when it applies
+ * none. `effort: null` (nothing requested) is always `null`.
+ *
+ * One owner for both sides of the check: the adapter that builds the harness argv and the caller
+ * that verifies the receipt read this function, so a CLI that renames a rung moves both at once
+ * instead of turning into a refused run.
+ */
+export declare function nativeReasoningControl(harness: HarnessType, effort: ReasoningEffort | null): string | null;
 /** Whether the harness's runner honors a per-turn MODEL override (vs. picking the model itself). */
 export declare function harnessHonorsModel(harness: HarnessType): boolean;
 /** Whether the harness's runner honors a reasoning-EFFORT override (vs. dropping it). */

package/dist/harness-capabilities.js

@@ -123,8 +123,8 @@ export function snapHarnessToModel(harness, modelId) {
  *   - claude-code: `--effort` accepts `low|medium|high|xhigh|max`; canonical `ultracode` maps to
  *     native `max`. It cannot express `none` or `minimal`, and an unsupported value is warned about
  *     and silently replaced with the default rather than rejected — so the set must not overstate.
- *   - pi: `--thinking` accepts `off|minimal|low|medium|high|xhigh|max`; canonical `none` maps to
- *     `off` and `ultracode` to `max`.
+ *   - pi: `--thinking` accepts `off|minimal|low|medium|high|xhigh`; canonical `none` maps to
+ *     `off` and `ultracode` clamps to `xhigh`, its top rung.
  *   - prime: the prime fork of the pi line accepts the same `--thinking` set
  *     (`off|minimal|low|medium|high|xhigh|max`); canonical `none` maps to `off` and `ultracode` to
  *     `max`.
@@ -186,6 +186,70 @@ export function reasoningEffortsFor(harness, model) {
     }
     return efforts;
 }
+// ── Native reasoning control (the exact token the harness process receives) ───
+/**
+ * Canonical effort → the harness's OWN control token, or `null` when the harness applies no
+ * native reasoning control for that request. This is the value a materialization receipt carries
+ * as `reasoningEffort.applied`, so a caller can check that the effort it asked for reached the
+ * process instead of trusting an echo of its own request.
+ *
+ * Read from the argv builders that actually spawn each CLI, not from help text:
+ *   - claude-code — `--effort <value>`; it cannot express `none` or `minimal`, so both clamp to
+ *     `low`, and `ultracode` becomes its ceiling `max`.
+ *   - codex — `-c model_reasoning_effort="<value>"`; it takes the canonical rungs directly and
+ *     names its ceiling `ultra`.
+ *   - pi — `--thinking <value>`; `none` becomes `off` and `ultracode` clamps to `xhigh`, the
+ *     highest rung the pi line accepts.
+ *   - prime — `--thinking <value>`; the fork carries `max` above `xhigh`, so `ultracode` reaches
+ *     `max`. This is the one rung where prime and pi differ.
+ *   - kimi-code — the control is the FLAG itself, `--thinking` or `--no-thinking`, because kimi's
+ *     thinking switch is binary. `medium` is its default and passes no flag at all.
+ *   - opencode — the router-backed variant name is the canonical rung unchanged.
+ *
+ * A harness with no entry applies NO native control: either it derives thinking from the model
+ * (gemini's `--thinking-budget`) or it plumbs no thinking flag at all (see
+ * {@link harnessHonorsEffort}). Both answer `null`, which is what their receipts carry — so an
+ * unknown harness is never asserted to have applied a control it cannot apply.
+ */
+const harnessNativeReasoningControl = {
+    "claude-code": (effort) => {
+        if (effort === "none" || effort === "minimal")
+            return "low";
+        return effort === "ultracode" ? "max" : effort;
+    },
+    codex: (effort) => (effort === "ultracode" ? "ultra" : effort),
+    pi: (effort) => {
+        if (effort === "none")
+            return "off";
+        return effort === "ultracode" ? "xhigh" : effort;
+    },
+    prime: (effort) => {
+        if (effort === "none")
+            return "off";
+        return effort === "ultracode" ? "max" : effort;
+    },
+    "kimi-code": (effort) => {
+        if (effort === "medium")
+            return null;
+        return effort === "none" || effort === "minimal" || effort === "low"
+            ? "--no-thinking"
+            : "--thinking";
+    },
+    opencode: (effort) => effort,
+};
+/**
+ * The native control token a harness applies for one canonical effort, or `null` when it applies
+ * none. `effort: null` (nothing requested) is always `null`.
+ *
+ * One owner for both sides of the check: the adapter that builds the harness argv and the caller
+ * that verifies the receipt read this function, so a CLI that renames a rung moves both at once
+ * instead of turning into a refused run.
+ */
+export function nativeReasoningControl(harness, effort) {
+    if (effort === null)
+        return null;
+    return harnessNativeReasoningControl[harness]?.(effort) ?? null;
+}
 // ── Per-turn selector support (does the harness honor the chat pickers?) ──────
 /**
  * Harnesses whose runner DROPS a per-turn selector — grounded in the cli-bridge adapter audit, NOT a

package/dist/workspace-cleanup.d.ts

@@ -81,5 +81,20 @@ export interface AgentWorkspaceBranching {
         signal?: AbortSignal;
     }): Promise<WorkspaceCleanupAcknowledgement>;
 }
+/**
+ * Provider-level entry point for reconstructing branch operations by source.
+ *
+ * Environment handles are process-local views. A coordinator that restarts
+ * must obtain a fresh source-scoped handle before it looks up or cleans a
+ * checkpoint or fork. The returned handle must reject a resource that does
+ * not belong to its source scope. Providers return null when the source is
+ * absent, the resolved environment id does not match, or the deployment
+ * cannot prove the complete branching surface.
+ */
+export interface AgentWorkspaceBranchingProvider {
+    forEnvironment(sourceEnvironmentId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentWorkspaceBranching | null>;
+}
 /** Bind cleanup confirmation to the exact provider resource and operation. */
 export declare function workspaceCleanupAcknowledgementMatches(request: WorkspaceCleanupRequest, acknowledgement: WorkspaceCleanupAcknowledgement): boolean;

package/package.json

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