@tangle-network/agent-interface 0.18.0 → 0.20.0

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

@@ -601,6 +601,7 @@ export interface SdkProviderAdapter {
 }
 export * from "./interaction.js";
 export * from "./agent-profile.js";
+export * from "./profile-diff.js";
 export * from "./harness.js";
 export * from "./harness-capabilities.js";
 export * from "./profile-schema.js";

package/dist/index.js

@@ -124,6 +124,7 @@ export function resolveNativeWebTools(tools) {
 }
 export * from "./interaction.js";
 export * from "./agent-profile.js";
+export * from "./profile-diff.js";
 export * from "./harness.js";
 export * from "./harness-capabilities.js";
 export * from "./profile-schema.js";

package/dist/profile-diff.d.ts

@@ -0,0 +1,61 @@
+import type { AgentProfile } from "./agent-profile.js";
+export type AgentProfileDiffAxis = "identity" | "prompt" | "model" | "permissions" | "tools" | "mcp" | "connections" | "subagents" | "resources" | "hooks" | "modes" | "confidential" | "metadata" | "extensions";
+export type AgentProfileRemoveList = true | readonly string[];
+export interface AgentProfilePromptRemoval {
+    systemPrompt?: true;
+    instructions?: AgentProfileRemoveList;
+}
+export interface AgentProfileResourceRemoval {
+    files?: AgentProfileRemoveList;
+    tools?: AgentProfileRemoveList;
+    skills?: AgentProfileRemoveList;
+    agents?: AgentProfileRemoveList;
+    commands?: AgentProfileRemoveList;
+    instructions?: true;
+    failOnError?: true;
+}
+export interface AgentProfileDiffRemoval {
+    identity?: true;
+    tags?: AgentProfileRemoveList;
+    prompt?: true | AgentProfilePromptRemoval;
+    model?: AgentProfileRemoveList;
+    permissions?: AgentProfileRemoveList;
+    tools?: AgentProfileRemoveList;
+    mcp?: AgentProfileRemoveList;
+    connections?: AgentProfileRemoveList;
+    subagents?: AgentProfileRemoveList;
+    resources?: true | AgentProfileResourceRemoval;
+    hooks?: AgentProfileRemoveList;
+    modes?: AgentProfileRemoveList;
+    confidential?: true;
+    metadata?: AgentProfileRemoveList;
+    extensions?: AgentProfileRemoveList;
+}
+/**
+ * A portable profile improvement artifact.
+ *
+ * `set` is an AgentProfile overlay: profile arrays are appended with the same
+ * semantics as {@link mergeAgentProfiles}. `remove` deletes whole axes or named
+ * entries after the overlay is applied. This keeps the optimized unit the full
+ * AgentProfile instead of a benchmark-specific file mount.
+ */
+export interface AgentProfileDiff {
+    schemaVersion: 1;
+    kind: "agent-profile-diff";
+    id?: string;
+    title?: string;
+    description?: string;
+    rationale?: string;
+    source?: {
+        kind: "trace" | "frontier-author" | "human" | "optimizer" | "compound";
+        artifacts?: readonly string[];
+        notes?: readonly string[];
+    };
+    set?: AgentProfile;
+    remove?: AgentProfileDiffRemoval;
+    metadata?: Record<string, unknown>;
+}
+export declare function defineAgentProfileDiff<T extends AgentProfileDiff>(diff: T): T;
+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;

package/dist/profile-diff.js

@@ -0,0 +1,230 @@
+import { mergeAgentProfiles } from "./agent-profile.js";
+export function defineAgentProfileDiff(diff) {
+    return diff;
+}
+function asMutable(value) {
+    return value ? [...value] : undefined;
+}
+function removeKeys(record, removal) {
+    if (!record || removal === undefined)
+        return record;
+    if (removal === true)
+        return undefined;
+    const next = {
+        ...record,
+    };
+    for (const key of removal)
+        delete next[key];
+    return Object.keys(next).length > 0 ? next : undefined;
+}
+function removeValues(values, removal) {
+    if (!values || removal === undefined)
+        return values;
+    if (removal === true)
+        return undefined;
+    const removeSet = new Set(removal);
+    const next = values.filter((value) => !removeSet.has(value));
+    return next.length > 0 ? next : undefined;
+}
+function resourceName(resource) {
+    return resource.kind === "inline" ? resource.name : resource.name ?? resource.path;
+}
+function removeResourceRefs(refs, removal) {
+    if (!refs || removal === undefined)
+        return refs;
+    if (removal === true)
+        return undefined;
+    const removeSet = new Set(removal);
+    const next = refs.filter((ref) => {
+        const name = resourceName(ref);
+        return !(name && removeSet.has(name));
+    });
+    return next.length > 0 ? next : undefined;
+}
+function removeResources(resources, removal) {
+    if (!resources || removal === undefined)
+        return resources;
+    if (removal === true)
+        return undefined;
+    const next = { ...resources };
+    if (removal.files !== undefined) {
+        if (removal.files === true) {
+            next.files = undefined;
+        }
+        else {
+            const removeSet = new Set(removal.files);
+            next.files = next.files?.filter((file) => {
+                const name = resourceName(file.resource);
+                return !removeSet.has(file.path) && !(name && removeSet.has(name));
+            });
+        }
+    }
+    next.tools = removeResourceRefs(next.tools, removal.tools);
+    next.skills = removeResourceRefs(next.skills, removal.skills);
+    next.agents = removeResourceRefs(next.agents, removal.agents);
+    next.commands = removeResourceRefs(next.commands, removal.commands);
+    if (removal.instructions)
+        next.instructions = undefined;
+    if (removal.failOnError)
+        next.failOnError = undefined;
+    for (const key of [
+        "files",
+        "tools",
+        "skills",
+        "agents",
+        "commands",
+    ]) {
+        if (next[key]?.length === 0)
+            next[key] = undefined;
+    }
+    return Object.values(next).some((value) => value !== undefined)
+        ? next
+        : undefined;
+}
+function applyRemoval(profile, remove) {
+    if (!remove)
+        return profile;
+    const next = { ...profile };
+    if (remove.identity) {
+        next.name = undefined;
+        next.description = undefined;
+        next.version = undefined;
+    }
+    next.tags = removeValues(asMutable(next.tags), remove.tags);
+    if (remove.prompt === true) {
+        next.prompt = undefined;
+    }
+    else if (remove.prompt && next.prompt) {
+        const prompt = { ...next.prompt };
+        if (remove.prompt.systemPrompt)
+            prompt.systemPrompt = undefined;
+        prompt.instructions = removeValues(prompt.instructions, remove.prompt.instructions);
+        next.prompt = Object.values(prompt).some((value) => value !== undefined)
+            ? 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.confidential)
+        next.confidential = undefined;
+    next.metadata = removeKeys(next.metadata, remove.metadata);
+    next.extensions = removeKeys(next.extensions, remove.extensions);
+    if (next.connections && remove.connections !== undefined) {
+        if (remove.connections === true) {
+            next.connections = undefined;
+        }
+        else {
+            const removeSet = new Set(remove.connections);
+            const filtered = next.connections.filter((connection) => !removeSet.has(connection.connectionId) &&
+                !(connection.alias && removeSet.has(connection.alias)));
+            next.connections = filtered.length > 0 ? filtered : undefined;
+        }
+    }
+    return next;
+}
+export function applyAgentProfileDiff(base, diff) {
+    const merged = mergeAgentProfiles(base, diff.set) ?? {};
+    return applyRemoval(merged, diff.remove);
+}
+export function changedAgentProfileAxes(diff) {
+    const axes = new Set();
+    const set = diff.set;
+    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",
+        ]) {
+            if (set[axis] !== undefined)
+                axes.add(axis);
+        }
+    }
+    const remove = diff.remove;
+    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",
+        ]) {
+            if (remove[axis] !== undefined)
+                axes.add(axis);
+        }
+    }
+    return [...axes].sort();
+}
+export function pruneAgentProfileDiff(diff, axesToRemove) {
+    const removeSet = new Set(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;
+    }
+    if (removeSet.has("identity") && remove) {
+        remove.identity = undefined;
+        remove.tags = undefined;
+    }
+    for (const axis of [
+        "prompt",
+        "model",
+        "permissions",
+        "tools",
+        "mcp",
+        "connections",
+        "subagents",
+        "resources",
+        "hooks",
+        "modes",
+        "confidential",
+        "metadata",
+        "extensions",
+    ]) {
+        if (!removeSet.has(axis))
+            continue;
+        if (set)
+            set[axis] = undefined;
+        if (remove)
+            remove[axis] = undefined;
+    }
+    return {
+        ...diff,
+        ...(set && Object.values(set).some((value) => value !== undefined)
+            ? { set }
+            : { set: undefined }),
+        ...(remove && Object.values(remove).some((value) => value !== undefined)
+            ? { remove }
+            : { remove: undefined }),
+    };
+}

package/dist/profile-schema.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { AgentProfile } from "./agent-profile.js";
+import type { AgentProfileDiff } from "./profile-diff.js";
 import { type SandboxSizePreset } from "./sandbox-size.js";
 export declare const agentProfilePermissionValueSchema: z.ZodEnum<{
     allow: "allow";
@@ -199,6 +200,47 @@ export declare const agentProfileConnectionSchema: z.ZodObject<{
     capabilities: z.ZodArray<z.ZodString>;
     alias: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const agentProfilePromptRemovalSchema: z.ZodObject<{
+    systemPrompt: z.ZodOptional<z.ZodLiteral<true>>;
+    instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+}, z.core.$strip>;
+export declare const agentProfileResourceRemovalSchema: z.ZodObject<{
+    files: 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>]>>;
+    skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+    agents: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+    commands: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+    instructions: z.ZodOptional<z.ZodLiteral<true>>;
+    failOnError: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>;
+export declare const agentProfileDiffRemovalSchema: z.ZodObject<{
+    identity: z.ZodOptional<z.ZodLiteral<true>>;
+    tags: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+    prompt: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
+        systemPrompt: z.ZodOptional<z.ZodLiteral<true>>;
+        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>]>>;
+    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>]>>;
+    connections: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+    subagents: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+    resources: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
+        files: 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>]>>;
+        skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+        agents: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+        commands: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+        instructions: z.ZodOptional<z.ZodLiteral<true>>;
+        failOnError: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strip>]>>;
+    hooks: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+    modes: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+    confidential: z.ZodOptional<z.ZodLiteral<true>>;
+    metadata: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+    extensions: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
+}, z.core.$strip>;
 /**
  * The complete provider-neutral agent profile schema — the runtime validator for
  * the canonical {@link AgentProfile} TS contract. Kept structurally in lock-step
@@ -228,6 +270,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";
@@ -380,6 +440,7 @@ export declare const agentProfileSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodUndefined]>>>;
 }, z.core.$strip>;
+export declare const agentProfileDiffSchema: z.ZodType<AgentProfileDiff>;
 /**
  * A registered capability: a stable id paired with its canonical
  * {@link AgentProfile}. `definition` is the full profile (prompt/model/tools/

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",
@@ -97,6 +98,37 @@ export const agentProfileConnectionSchema = z.object({
     capabilities: z.array(z.string().min(1)).min(1),
     alias: z.string().min(1).optional(),
 });
+const removeListSchema = z.union([z.literal(true), z.array(z.string().min(1))]);
+export const agentProfilePromptRemovalSchema = z.object({
+    systemPrompt: z.literal(true).optional(),
+    instructions: removeListSchema.optional(),
+});
+export const agentProfileResourceRemovalSchema = z.object({
+    files: removeListSchema.optional(),
+    tools: removeListSchema.optional(),
+    skills: removeListSchema.optional(),
+    agents: removeListSchema.optional(),
+    commands: removeListSchema.optional(),
+    instructions: z.literal(true).optional(),
+    failOnError: z.literal(true).optional(),
+});
+export const agentProfileDiffRemovalSchema = z.object({
+    identity: z.literal(true).optional(),
+    tags: removeListSchema.optional(),
+    prompt: z.union([z.literal(true), agentProfilePromptRemovalSchema]).optional(),
+    model: removeListSchema.optional(),
+    permissions: removeListSchema.optional(),
+    tools: removeListSchema.optional(),
+    mcp: removeListSchema.optional(),
+    connections: removeListSchema.optional(),
+    subagents: removeListSchema.optional(),
+    resources: z.union([z.literal(true), agentProfileResourceRemovalSchema]).optional(),
+    hooks: removeListSchema.optional(),
+    modes: removeListSchema.optional(),
+    confidential: z.literal(true).optional(),
+    metadata: removeListSchema.optional(),
+    extensions: removeListSchema.optional(),
+});
 /**
  * The complete provider-neutral agent profile schema — the runtime validator for
  * the canonical {@link AgentProfile} TS contract. Kept structurally in lock-step
@@ -109,6 +141,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(),
@@ -125,6 +158,30 @@ export const agentProfileSchema = z.object({
         .record(z.string(), z.union([z.record(z.string(), z.unknown()), z.undefined()]))
         .optional(),
 });
+export const agentProfileDiffSchema = z.object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("agent-profile-diff"),
+    id: z.string().min(1).optional(),
+    title: z.string().min(1).optional(),
+    description: z.string().optional(),
+    rationale: z.string().optional(),
+    source: z
+        .object({
+        kind: z.enum([
+            "trace",
+            "frontier-author",
+            "human",
+            "optimizer",
+            "compound",
+        ]),
+        artifacts: z.array(z.string().min(1)).optional(),
+        notes: z.array(z.string()).optional(),
+    })
+        .optional(),
+    set: agentProfileSchema.optional(),
+    remove: agentProfileDiffRemovalSchema.optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
 const _agentProfileSchemaMatchesInterface = true;
 void _agentProfileSchemaMatchesInterface;
 export const capabilitySchema = z.object({

package/package.json

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