@tangle-network/agent-interface 0.19.0 → 0.21.0

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

@@ -0,0 +1,151 @@
+import { defineAgentCandidateBundle } from "./agent-candidate.js";
+export const candidateSha = (digit) => `sha256:${digit.repeat(64)}`;
+export const candidateGit = (digit) => digit.repeat(40);
+export function candidateFixture() {
+    return defineAgentCandidateBundle({
+        schemaVersion: 1,
+        kind: "agent-candidate-bundle",
+        digestAlgorithm: "rfc8785-sha256",
+        profile: {
+            name: "repository-agent",
+            harness: "codex",
+            model: {
+                default: "openai/gpt-5.4",
+                reasoningEffort: "high",
+            },
+            prompt: { systemPrompt: "Solve the repository task." },
+            resources: {
+                files: [
+                    {
+                        path: ".agent/policy.json",
+                        resource: {
+                            kind: "inline",
+                            name: "policy",
+                            content: "{}",
+                            sha256: candidateSha("b"),
+                            byteLength: 2,
+                        },
+                    },
+                ],
+                failOnError: true,
+            },
+        },
+        code: {
+            kind: "git-patch",
+            repository: {
+                kind: "github",
+                owner: "tangle-network",
+                repo: "agent-runtime",
+            },
+            baseCommit: candidateGit("1"),
+            baseTree: candidateGit("2"),
+            candidateTree: candidateGit("4"),
+            patch: {
+                format: "git-diff-binary",
+                artifact: {
+                    encoding: "base64",
+                    content: "ZGlmZiAtLWdpdA==",
+                    sha256: candidateSha("5"),
+                    byteLength: 10,
+                },
+            },
+        },
+        execution: {
+            harness: "codex",
+            harnessVersion: "0.1.0",
+            launch: {
+                kind: "candidate-entrypoint",
+                interpreter: "node",
+                entrypoint: "dist/agent.js",
+                args: [{ kind: "public", value: "--mode=benchmark" }],
+            },
+            instructionDelivery: { kind: "argv-append" },
+            cwd: { workspace: "candidate", path: "." },
+            env: {
+                NODE_ENV: { kind: "public", value: "production" },
+            },
+            environment: {
+                kind: "pinned-container",
+                container: { image: "node:22", indexDigest: candidateSha("6") },
+            },
+            workspace: {
+                schemaVersion: 1,
+                kind: "agent-candidate-workspace-snapshot",
+                digest: candidateSha("c"),
+                material: {
+                    schemaVersion: 1,
+                    kind: "agent-candidate-workspace-manifest",
+                    files: [
+                        {
+                            path: "dist/agent.js",
+                            mode: 0o755,
+                            sha256: candidateSha("d"),
+                            byteLength: 42,
+                        },
+                    ],
+                },
+                manifest: {
+                    encoding: "base64",
+                    content: "e30=",
+                    sha256: candidateSha("c"),
+                    byteLength: 2,
+                },
+                archive: {
+                    encoding: "base64",
+                    content: "e30=",
+                    sha256: candidateSha("e"),
+                    byteLength: 2,
+                },
+            },
+            isolation: {
+                network: "disabled",
+                remoteIntegrations: "disabled",
+                candidateSecrets: "disabled",
+            },
+        },
+        knowledge: {
+            snapshotId: "knowledge-17",
+            manifest: {
+                locator: {
+                    kind: "s3",
+                    bucket: "agent-candidate-artifacts",
+                    key: "knowledge/knowledge-17.json",
+                    region: "us-east-1",
+                },
+                sha256: candidateSha("7"),
+                byteLength: 42,
+            },
+        },
+        memory: {
+            mode: "isolated",
+            scope: "task",
+        },
+        lineage: {
+            source: "optimizer",
+            parentDigests: [candidateSha("8")],
+            runIds: ["r360-search"],
+            profileDiffIds: ["profile-diff-3"],
+            modelSnapshots: ["openai/gpt-5.4-2026-06-15"],
+            benchmark: {
+                name: "pier",
+                version: "0.3",
+                splitDigest: candidateSha("9"),
+            },
+            spend: {
+                proposal: {
+                    costUsd: 3.5,
+                    inputTokens: 100,
+                    outputTokens: 20,
+                    modelCalls: 2,
+                },
+                evaluation: {
+                    costUsd: 9,
+                    inputTokens: 900,
+                    outputTokens: 200,
+                    modelCalls: 8,
+                },
+            },
+        },
+        digest: candidateSha("a"),
+    });
+}

package/dist/agent-profile.d.ts

@@ -6,6 +6,7 @@
  * formats internally. This is the canonical home; `@tangle-network/sandbox`
  * re-exports these symbols for backward compatibility.
  */
+import type { HarnessType } from "./harness.js";
 /**
  * Permission policy value for a capability.
  */
@@ -230,6 +231,19 @@ export interface AgentProfile {
     tags?: string[];
     prompt?: AgentProfilePrompt;
     model?: AgentProfileModelHints;
+    /**
+     * Preferred execution harness for this profile — the coding-CLI runtime that
+     * materializes and runs it (`claude-code`, `codex`, `opencode`, `pi`, …).
+     *
+     * This is an optional PREFERENCE, not part of profile IDENTITY: the same
+     * profile still runs on any harness, and an executor MAY override it (e.g. the
+     * leaderboard's `harness × model` axis sweeps a profile across every harness,
+     * and a supervisor spawning a worker may pick a harness per subtask). When
+     * unset, the caller/executor chooses. Formalizes what runtimes already read as
+     * `profile.harness`; making it typed also lets an improvement loop optimize
+     * harness routing as a first-class lever.
+     */
+    harness?: HarnessType;
     permissions?: Record<string, AgentProfilePermission>;
     tools?: Record<string, boolean>;
     mcp?: Record<string, AgentProfileMcpServer>;

package/dist/harness.d.ts

@@ -2,10 +2,13 @@ import { z } from "zod";
 /**
  * The execution runner for an agent — WHICH runtime materializes and runs an `AgentProfile`.
  *
- * Harness is an EXECUTION concern chosen by the caller/executor per run, NOT part of the portable
- * profile identity: the same `AgentProfile` (prompt/model/skills/tools/mcp/subagents) runs on any
- * harness. This is the single shared enum every layer references instead of keeping its own copy
- * (session control, the profile materializer, the cli-bridge backends, VB profile specs).
+ * Harness is an EXECUTION concern, not part of profile IDENTITY: the same `AgentProfile`
+ * (prompt/model/skills/tools/mcp/subagents) runs on any harness. A profile MAY carry an optional
+ * `harness` PREFERENCE (`AgentProfile.harness`), but the caller/executor can always override it per
+ * run — the leaderboard's `harness × model` axis sweeps one profile across every harness, and a
+ * supervisor may pick a harness per spawned worker. This is the single shared enum every layer
+ * references instead of keeping its own copy (session control, the profile materializer, the
+ * cli-bridge backends, VB profile specs).
  *
  * `cli-base` is the router-backed mode — a plain multi-turn router call (a reviewer, a cheap judge,
  * a one-shot) with no full coding-agent harness. The rest are full agentic harnesses run in a

package/dist/index.d.ts

@@ -600,6 +600,8 @@ export interface SdkProviderAdapter {
     respondToInteraction?(response: InteractionResponse): Promise<void>;
 }
 export * from "./interaction.js";
+export * from "./agent-candidate.js";
+export * from "./agent-candidate-schema.js";
 export * from "./agent-profile.js";
 export * from "./profile-diff.js";
 export * from "./harness.js";

package/dist/index.js

@@ -123,6 +123,8 @@ export function resolveNativeWebTools(tools) {
     return posture;
 }
 export * from "./interaction.js";
+export * from "./agent-candidate.js";
+export * from "./agent-candidate-schema.js";
 export * from "./agent-profile.js";
 export * from "./profile-diff.js";
 export * from "./harness.js";

package/dist/interaction.d.ts

@@ -124,9 +124,9 @@ export declare const InteractionSubjectSchema: z.ZodDiscriminatedUnion<[z.ZodObj
 }, z.core.$strip>], "type">;
 export type InteractionSubject = z.infer<typeof InteractionSubjectSchema>;
 export declare const InteractionOutcomeSchema: z.ZodEnum<{
+    cancelled: "cancelled";
     accepted: "accepted";
     declined: "declined";
-    cancelled: "cancelled";
 }>;
 export type InteractionOutcome = z.infer<typeof InteractionOutcomeSchema>;
 /** Field values keyed by `InteractionField.name`. Validated against `answerSpec`. */
@@ -134,9 +134,9 @@ export declare const InteractionDataSchema: z.ZodRecord<z.ZodString, z.ZodUnion<
 export type InteractionData = z.infer<typeof InteractionDataSchema>;
 export declare const InteractionResolutionSchema: z.ZodObject<{
     outcome: z.ZodEnum<{
+        cancelled: "cancelled";
         accepted: "accepted";
         declined: "declined";
-        cancelled: "cancelled";
     }>;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
 }, z.core.$strip>;
@@ -207,9 +207,9 @@ export declare const InteractionRequestSchema: z.ZodObject<{
     }, z.core.$strip>;
     default: z.ZodOptional<z.ZodObject<{
         outcome: z.ZodEnum<{
+            cancelled: "cancelled";
             accepted: "accepted";
             declined: "declined";
-            cancelled: "cancelled";
         }>;
         data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
     }, z.core.$strip>>;
@@ -223,9 +223,9 @@ export declare const InteractionRequestSchema: z.ZodObject<{
 export type InteractionRequest = z.infer<typeof InteractionRequestSchema>;
 export declare const InteractionResponseSchema: z.ZodObject<{
     outcome: z.ZodEnum<{
+        cancelled: "cancelled";
         accepted: "accepted";
         declined: "declined";
-        cancelled: "cancelled";
     }>;
     data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
     id: z.ZodString;

package/dist/profile-diff.d.ts

@@ -1,5 +1,6 @@
 import type { AgentProfile } from "./agent-profile.js";
-export type AgentProfileDiffAxis = "identity" | "prompt" | "model" | "permissions" | "tools" | "mcp" | "connections" | "subagents" | "resources" | "hooks" | "modes" | "confidential" | "metadata" | "extensions";
+declare const agentProfileDiffPropertyAxes: readonly ["prompt", "model", "harness", "permissions", "tools", "mcp", "connections", "subagents", "resources", "hooks", "modes", "confidential", "metadata", "extensions"];
+export type AgentProfileDiffAxis = "identity" | (typeof agentProfileDiffPropertyAxes)[number];
 export type AgentProfileRemoveList = true | readonly string[];
 export interface AgentProfilePromptRemoval {
     systemPrompt?: true;
@@ -19,6 +20,7 @@ export interface AgentProfileDiffRemoval {
     tags?: AgentProfileRemoveList;
     prompt?: true | AgentProfilePromptRemoval;
     model?: AgentProfileRemoveList;
+    harness?: true;
     permissions?: AgentProfileRemoveList;
     tools?: AgentProfileRemoveList;
     mcp?: AgentProfileRemoveList;
@@ -59,3 +61,4 @@ export declare function defineAgentProfileDiff<T extends AgentProfileDiff>(diff:
 export declare function applyAgentProfileDiff(base: AgentProfile, diff: AgentProfileDiff): AgentProfile;
 export declare function changedAgentProfileAxes(diff: AgentProfileDiff): AgentProfileDiffAxis[];
 export declare function pruneAgentProfileDiff(diff: AgentProfileDiff, axesToRemove: readonly AgentProfileDiffAxis[]): AgentProfileDiff;
+export {};

package/dist/profile-diff.js

@@ -1,4 +1,22 @@
 import { mergeAgentProfiles } from "./agent-profile.js";
+const agentProfileDiffPropertyAxes = [
+    "prompt",
+    "model",
+    "harness",
+    "permissions",
+    "tools",
+    "mcp",
+    "connections",
+    "subagents",
+    "resources",
+    "hooks",
+    "modes",
+    "confidential",
+    "metadata",
+    "extensions",
+];
+const _agentProfileDiffPropertyAxesAreExhaustive = true;
+void _agentProfileDiffPropertyAxesAreExhaustive;
 export function defineAgentProfileDiff(diff) {
     return diff;
 }
@@ -90,7 +108,9 @@ function applyRemoval(profile, remove) {
         next.description = undefined;
         next.version = undefined;
     }
-    next.tags = removeValues(asMutable(next.tags), remove.tags);
+    if (remove.tags !== undefined) {
+        next.tags = removeValues(asMutable(next.tags), remove.tags);
+    }
     if (remove.prompt === true) {
         next.prompt = undefined;
     }
@@ -103,18 +123,40 @@ function applyRemoval(profile, remove) {
             ? prompt
             : undefined;
     }
-    next.model = removeKeys(next.model, remove.model);
-    next.permissions = removeKeys(next.permissions, remove.permissions);
-    next.tools = removeKeys(next.tools, remove.tools);
-    next.mcp = removeKeys(next.mcp, remove.mcp);
-    next.subagents = removeKeys(next.subagents, remove.subagents);
-    next.resources = removeResources(next.resources, remove.resources);
-    next.hooks = removeKeys(next.hooks, remove.hooks);
-    next.modes = removeKeys(next.modes, remove.modes);
+    if (remove.model !== undefined) {
+        next.model = removeKeys(next.model, remove.model);
+    }
+    if (remove.harness !== undefined)
+        next.harness = undefined;
+    if (remove.permissions !== undefined) {
+        next.permissions = removeKeys(next.permissions, remove.permissions);
+    }
+    if (remove.tools !== undefined) {
+        next.tools = removeKeys(next.tools, remove.tools);
+    }
+    if (remove.mcp !== undefined) {
+        next.mcp = removeKeys(next.mcp, remove.mcp);
+    }
+    if (remove.subagents !== undefined) {
+        next.subagents = removeKeys(next.subagents, remove.subagents);
+    }
+    if (remove.resources !== undefined) {
+        next.resources = removeResources(next.resources, remove.resources);
+    }
+    if (remove.hooks !== undefined) {
+        next.hooks = removeKeys(next.hooks, remove.hooks);
+    }
+    if (remove.modes !== undefined) {
+        next.modes = removeKeys(next.modes, remove.modes);
+    }
     if (remove.confidential)
         next.confidential = undefined;
-    next.metadata = removeKeys(next.metadata, remove.metadata);
-    next.extensions = removeKeys(next.extensions, remove.extensions);
+    if (remove.metadata !== undefined) {
+        next.metadata = removeKeys(next.metadata, remove.metadata);
+    }
+    if (remove.extensions !== undefined) {
+        next.extensions = removeKeys(next.extensions, remove.extensions);
+    }
     if (next.connections && remove.connections !== undefined) {
         if (remove.connections === true) {
             next.connections = undefined;
@@ -138,21 +180,7 @@ export function changedAgentProfileAxes(diff) {
     if (set) {
         if (set.name || set.description || set.version || set.tags)
             axes.add("identity");
-        for (const axis of [
-            "prompt",
-            "model",
-            "permissions",
-            "tools",
-            "mcp",
-            "connections",
-            "subagents",
-            "resources",
-            "hooks",
-            "modes",
-            "confidential",
-            "metadata",
-            "extensions",
-        ]) {
+        for (const axis of agentProfileDiffPropertyAxes) {
             if (set[axis] !== undefined)
                 axes.add(axis);
         }
@@ -161,21 +189,7 @@ export function changedAgentProfileAxes(diff) {
     if (remove) {
         if (remove.identity || remove.tags)
             axes.add("identity");
-        for (const axis of [
-            "prompt",
-            "model",
-            "permissions",
-            "tools",
-            "mcp",
-            "connections",
-            "subagents",
-            "resources",
-            "hooks",
-            "modes",
-            "confidential",
-            "metadata",
-            "extensions",
-        ]) {
+        for (const axis of agentProfileDiffPropertyAxes) {
             if (remove[axis] !== undefined)
                 axes.add(axis);
         }
@@ -187,36 +201,22 @@ export function pruneAgentProfileDiff(diff, axesToRemove) {
     const set = diff.set ? { ...diff.set } : undefined;
     const remove = diff.remove ? { ...diff.remove } : undefined;
     if (removeSet.has("identity") && set) {
-        set.name = undefined;
-        set.description = undefined;
-        set.version = undefined;
-        set.tags = undefined;
+        delete set.name;
+        delete set.description;
+        delete set.version;
+        delete set.tags;
     }
     if (removeSet.has("identity") && remove) {
-        remove.identity = undefined;
-        remove.tags = undefined;
+        delete remove.identity;
+        delete remove.tags;
     }
-    for (const axis of [
-        "prompt",
-        "model",
-        "permissions",
-        "tools",
-        "mcp",
-        "connections",
-        "subagents",
-        "resources",
-        "hooks",
-        "modes",
-        "confidential",
-        "metadata",
-        "extensions",
-    ]) {
+    for (const axis of agentProfileDiffPropertyAxes) {
         if (!removeSet.has(axis))
             continue;
         if (set)
-            set[axis] = undefined;
+            delete set[axis];
         if (remove)
-            remove[axis] = undefined;
+            delete remove[axis];
     }
     return {
         ...diff,

package/dist/profile-schema.d.ts

@@ -221,6 +221,7 @@ export declare const agentProfileDiffRemovalSchema: z.ZodObject<{
         instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
     }, z.core.$strip>]>>;
     model: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+    harness: z.ZodOptional<z.ZodLiteral<true>>;
     permissions: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
     tools: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
     mcp: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
@@ -270,6 +271,24 @@ export declare const agentProfileSchema: z.ZodObject<{
         }>>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
+    harness: z.ZodOptional<z.ZodEnum<{
+        "claude-code": "claude-code";
+        claude: "claude";
+        claudish: "claudish";
+        nanoclaw: "nanoclaw";
+        codex: "codex";
+        opencode: "opencode";
+        "kimi-code": "kimi-code";
+        kimi: "kimi";
+        pi: "pi";
+        gemini: "gemini";
+        hermes: "hermes";
+        openclaw: "openclaw";
+        amp: "amp";
+        "factory-droids": "factory-droids";
+        acp: "acp";
+        "cli-base": "cli-base";
+    }>>;
     permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodEnum<{
         allow: "allow";
         ask: "ask";

package/dist/profile-schema.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { harnessTypeSchema } from "./harness.js";
 import { SANDBOX_SIZE_PRESET_NAMES, } from "./sandbox-size.js";
 export const agentProfilePermissionValueSchema = z.enum([
     "allow",
@@ -116,6 +117,7 @@ export const agentProfileDiffRemovalSchema = z.object({
     tags: removeListSchema.optional(),
     prompt: z.union([z.literal(true), agentProfilePromptRemovalSchema]).optional(),
     model: removeListSchema.optional(),
+    harness: z.literal(true).optional(),
     permissions: removeListSchema.optional(),
     tools: removeListSchema.optional(),
     mcp: removeListSchema.optional(),
@@ -140,6 +142,7 @@ export const agentProfileSchema = z.object({
     tags: z.array(z.string()).optional(),
     prompt: agentProfilePromptSchema.optional(),
     model: agentProfileModelHintsSchema.optional(),
+    harness: harnessTypeSchema.optional(),
     permissions: z.record(z.string(), agentProfilePermissionSchema).optional(),
     tools: z.record(z.string(), z.boolean()).optional(),
     mcp: z.record(z.string(), agentProfileMcpServerSchema).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "type": "module",
   "license": "MIT",
   "main": "./dist/index.js",