@tangle-network/agent-interface 5.6.0 → 5.7.0

package/dist/harness.d.ts

@@ -1,27 +1,16 @@
 import { z } from "zod";
 /**
- * The execution runner for an agent — WHICH runtime materializes and runs an `AgentProfile`.
+ * Recognized execution identities, not a deployment's list of installed runners.
+ * A profile's authored harness remains part of its canonical identity; execution
+ * receipts record authored identity, effective identity and selected harness
+ * separately. Retiring an executable must not invalidate historical profiles,
+ * sessions or receipts. Availability is admitted against the selected deployment.
  *
- * This enum describes an EXECUTION concern. When an `AgentProfile` authors a `harness`
- * preference, that field participates in its canonical identity like every other parsed profile
- * field. A caller or executor may override the preference for one run, but the execution receipt
- * preserves the authored identity, effective identity, and selected harness separately. 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
- * sandbox or locally via the CLI bridge.
- *
- * `forge` (tailcallhq/forgecode) and `cursor` (cursor-agent) are multi-provider CLI harnesses with
- * no vendor lock, so they carry no entry in the capability tables and resolve as router-backed.
- *
- * `prime` (PrimeIntellect-ai/prime-agent) is the prime fork of the pi line — the RLM
- * IPython-kernel harness. It is a distinct harness from `pi`: the fork's wire protocol has
- * diverged (its daemon rejects pi-line clients), so the two are not interchangeable at run time.
+ * `cli-base` names router-backed execution without a full coding-agent harness.
+ * `prime` is a distinct Pi-line fork with a different native wire protocol; its
+ * sessions are not interchangeable with Pi sessions. A shared identity does not
+ * assert protocol, model, profile-control or native-resume compatibility.
  */
-export type HarnessType = "claude-code" | "nanoclaw" | "codex" | "opencode" | "kimi-code" | "pi" | "prime" | "gemini" | "hermes" | "openclaw" | "amp" | "factory-droids" | "forge" | "cursor" | "acp" | "cli-base";
-/** Runtime validator for {@link HarnessType}. Kept in lockstep with the type by the drift guard below. */
 export declare const harnessTypeSchema: z.ZodEnum<{
     acp: "acp";
     amp: "amp";
@@ -40,3 +29,5 @@ export declare const harnessTypeSchema: z.ZodEnum<{
     pi: "pi";
     prime: "prime";
 }>;
+/** One declaration owns runtime validation and the compile-time vocabulary. */
+export type HarnessType = z.infer<typeof harnessTypeSchema>;

package/dist/harness.js

@@ -1,5 +1,16 @@
 import { z } from "zod";
-/** Runtime validator for {@link HarnessType}. Kept in lockstep with the type by the drift guard below. */
+/**
+ * Recognized execution identities, not a deployment's list of installed runners.
+ * A profile's authored harness remains part of its canonical identity; execution
+ * receipts record authored identity, effective identity and selected harness
+ * separately. Retiring an executable must not invalidate historical profiles,
+ * sessions or receipts. Availability is admitted against the selected deployment.
+ *
+ * `cli-base` names router-backed execution without a full coding-agent harness.
+ * `prime` is a distinct Pi-line fork with a different native wire protocol; its
+ * sessions are not interchangeable with Pi sessions. A shared identity does not
+ * assert protocol, model, profile-control or native-resume compatibility.
+ */
 export const harnessTypeSchema = z.enum([
     "claude-code",
     "nanoclaw",
@@ -18,5 +29,3 @@ export const harnessTypeSchema = z.enum([
     "acp",
     "cli-base",
 ]);
-const _harnessSchemaMatchesType = true;
-void _harnessSchemaMatchesType;

package/dist/index.d.ts

@@ -36,6 +36,7 @@ export * from "./agent-execution-preparation.js";
 export * from "./agent-workspace-lease.js";
 export * from "./deep-freeze.js";
 export * from "./profile-diff.js";
+export * from "./profile-provenance.js";
 export * from "./harness.js";
 export * from "./harness-capabilities.js";
 export * from "./profile-schema.js";

package/dist/index.js

@@ -34,6 +34,7 @@ export * from "./agent-execution-preparation.js";
 export * from "./agent-workspace-lease.js";
 export * from "./deep-freeze.js";
 export * from "./profile-diff.js";
+export * from "./profile-provenance.js";
 export * from "./harness.js";
 export * from "./harness-capabilities.js";
 export * from "./profile-schema.js";

package/dist/profile-provenance.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Provenance for inline profile resources.
+ *
+ * A profile that must materialize synchronously carries its skills as exact
+ * inline bytes. The record beside each one names the file and commit the bytes
+ * came from and their SHA-256, so an edit to either the inline copy or the
+ * source shows up as a mismatch instead of a silent change of behavior.
+ * Records live at `extensions[<profile name>].resourceProvenance`.
+ */
+import type { AgentProfile, AgentProfileResourceRef } from "./agent-profile.js";
+/** One file at one commit. */
+export interface AgentProfileResourceSource {
+    /** `owner/repo`. */
+    repository: string;
+    /** Full commit SHA: a branch or tag can move under the recorded bytes. */
+    ref: string;
+    path: string;
+}
+/** The record a profile keeps for one inline resource. */
+export interface AgentProfileResourceProvenance extends AgentProfileResourceSource {
+    /** Name of the inline resource the bytes were mounted as. */
+    name: string;
+    /** Lowercase hex SHA-256 of the content's UTF-8 bytes. */
+    sha256: string;
+}
+export type AgentProfileInlineResource = Extract<AgentProfileResourceRef, {
+    kind: "inline";
+}>;
+/** Reads the exact bytes of a source file, e.g. `git show <ref>:<path>` or the GitHub contents API. */
+export type ReadAgentProfileResourceSource = (source: AgentProfileResourceSource) => Promise<string>;
+/** Mount `content` as an inline skill and return the provenance record to keep beside it. */
+export declare function mountSkill(source: AgentProfileResourceSource & {
+    name: string;
+}, content: string): {
+    skill: AgentProfileInlineResource;
+    provenance: AgentProfileResourceProvenance;
+};
+/**
+ * Every reason a profile's provenance records do not hold; empty when they do.
+ *
+ * Each record must be pinned to a commit and name inline resources whose bytes
+ * hash to it. Inline resources without a record are not checked: a record is
+ * the producer's claim, and only claims are verified. With `read`, the source file at that commit must hash to it too,
+ * which catches a record that was rewritten together with the inline copy.
+ */
+export declare function verifyResourceProvenance(profile: AgentProfile, options?: {
+    namespace?: string;
+    read?: ReadAgentProfileResourceSource;
+}): Promise<string[]>;

package/dist/profile-provenance.js

@@ -0,0 +1,123 @@
+/**
+ * Provenance for inline profile resources.
+ *
+ * A profile that must materialize synchronously carries its skills as exact
+ * inline bytes. The record beside each one names the file and commit the bytes
+ * came from and their SHA-256, so an edit to either the inline copy or the
+ * source shows up as a mismatch instead of a silent change of behavior.
+ * Records live at `extensions[<profile name>].resourceProvenance`.
+ */
+import { gitObjectSchema, sha256Utf8 } from "./agent-candidate-schema-common.js";
+/** Mount `content` as an inline skill and return the provenance record to keep beside it. */
+export function mountSkill(source, content) {
+    if (!gitObjectSchema.safeParse(source.ref).success) {
+        throw new Error(`mountSkill ${source.name}: ref must be a full commit SHA, got "${source.ref}"`);
+    }
+    return {
+        skill: { kind: "inline", name: source.name, content },
+        provenance: {
+            name: source.name,
+            repository: source.repository,
+            ref: source.ref,
+            path: source.path,
+            sha256: contentSha256(content),
+        },
+    };
+}
+/**
+ * Every reason a profile's provenance records do not hold; empty when they do.
+ *
+ * Each record must be pinned to a commit and name inline resources whose bytes
+ * hash to it. Inline resources without a record are not checked: a record is
+ * the producer's claim, and only claims are verified. With `read`, the source file at that commit must hash to it too,
+ * which catches a record that was rewritten together with the inline copy.
+ */
+export async function verifyResourceProvenance(profile, options = {}) {
+    const namespace = options.namespace ?? profile.name;
+    if (namespace === undefined)
+        return ["profile has no name to locate its provenance records"];
+    const records = profile.extensions?.[namespace]?.resourceProvenance;
+    if (records === undefined)
+        return [];
+    if (!Array.isArray(records))
+        return [`extensions.${namespace}.resourceProvenance must be an array`];
+    const inline = inlineResourcesByName(profile);
+    const problems = [];
+    for (const [index, record] of records.entries()) {
+        const at = `extensions.${namespace}.resourceProvenance[${index}]`;
+        if (!isProvenanceRecord(record)) {
+            problems.push(`${at}: needs string name, repository, ref, path and a 64-hex sha256`);
+            continue;
+        }
+        if (!gitObjectSchema.safeParse(record.ref).success) {
+            problems.push(`${at} (${record.name}): ref "${record.ref}" is not a full commit SHA`);
+        }
+        const mounted = inline.get(record.name) ?? [];
+        if (mounted.length === 0) {
+            problems.push(`${at} (${record.name}): no inline resource has this name`);
+        }
+        for (const content of mounted) {
+            const actual = contentSha256(content);
+            if (actual !== record.sha256) {
+                problems.push(`${at} (${record.name}): inline bytes hash to ${actual}, record says ${record.sha256}`);
+            }
+        }
+        if (options.read !== undefined) {
+            let source;
+            try {
+                source = await options.read(record);
+            }
+            catch (error) {
+                problems.push(`${at} (${record.name}): cannot read ${record.repository}@${record.ref}:${record.path}: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            const actual = contentSha256(source);
+            if (actual !== record.sha256) {
+                problems.push(`${at} (${record.name}): ${record.repository}@${record.ref}:${record.path} hashes to ${actual}, record says ${record.sha256}`);
+            }
+        }
+    }
+    return problems;
+}
+function contentSha256(content) {
+    return sha256Utf8(content).slice("sha256:".length);
+}
+function isProvenanceRecord(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const record = value;
+    return (["name", "repository", "ref", "path"].every((key) => typeof record[key] === "string" && record[key] !== "") &&
+        typeof record.sha256 === "string" &&
+        /^[a-f0-9]{64}$/.test(record.sha256));
+}
+/**
+ * Inline contents by name. A record names a resource but not its kind, and
+ * `mountSkill` records skills, so a skill of that name wins; other kinds are
+ * matched only when no skill has the name, so a same-named command or file
+ * cannot fail a skill's record.
+ */
+function inlineResourcesByName(profile) {
+    const resources = profile.resources;
+    const others = [
+        ...(resources?.files?.map((mount) => mount.resource) ?? []),
+        ...(resources?.tools ?? []),
+        ...(resources?.agents ?? []),
+        ...(resources?.commands ?? []),
+        typeof resources?.instructions === "object" ? resources.instructions : undefined,
+    ];
+    const skills = byName(resources?.skills ?? []);
+    for (const [name, contents] of byName(others)) {
+        if (!skills.has(name))
+            skills.set(name, contents);
+    }
+    return skills;
+}
+function byName(refs) {
+    const map = new Map();
+    for (const ref of refs) {
+        if (ref?.kind !== "inline")
+            continue;
+        map.set(ref.name, [...(map.get(ref.name) ?? []), ref.content]);
+    }
+    return map;
+}

package/package.json

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