@tangle-network/agent-interface 2.16.0 → 2.18.0

package/README.md

@@ -5,6 +5,20 @@ agents, the sidecar, and provider adapters: capabilities, agent profiles,
 message parts, and harness descriptors. This is the canonical home for those
 shapes; higher-level packages import from here rather than redefining them.
 
+## Profile measurements
+
+`measureAgentProfile(profile)` returns the canonical profile digest and JSON byte size,
+per-prompt and inline resource UTF-8 bytes and logical lines, enabled/disabled tool and
+MCP declarations, and declared subagent counts. Resource rows use JSON Pointers;
+GitHub resource content has `bytes: null` and `lines: null` until independently resolved.
+The summary contains no prompt text, resource text, or server configuration.
+
+Store it with the existing profile record and cache by `profileDigest`. Measure authored
+and effective profiles separately, joined through their execution preparation or
+materialization receipts. The function does not load resources or estimate tokens.
+Its coverage explicitly leaves tokenization, materialization, and observed use unassessed.
+A capability declaration is not evidence that it was delivered, opened, or applied.
+
 ## Agent instances
 
 `AgentProfile` describes behavior. `AgentInstanceSpec` describes one optional managed Agent inside an existing execution environment. The environment remains the computer and security boundary, so it may host zero, one, or many Agent instances.
@@ -42,6 +56,12 @@ The public `AgentInstanceRecord` contains a credential-free profile identity, no
 
 ## Durable runs, interactions, and context
 
+`AgentTurnInput.profile` carries the exact `AgentProfile` for a turn through its canonical schema.
+Keep mounted resources and behavior in this typed field, separate from bounded `providerOptions` metadata.
+Providers must honor the profile or refuse it before dispatch; callers must not assume every provider supports per-turn profile changes.
+Provider-specific payload and capability limits still apply.
+
+
 `AgentRunControlRef` identifies a retained run without depending on a live JavaScript object and may carry the provider's admission digest so reconstruction can reject changed-input reuse.
 `RuntimeEventEnvelope` adds stable run, event, sequence, cursor, and timestamp fields around the existing `StreamEvent` union, and its runtime schema validates every canonical event variant.
 The `child-task` event reports one update of a provider-native child task (a subagent, worker, or delegated task) with a stable `childId`, an optional `parentChildId`, a lifecycle status, start and update times, and the runner, model, usage, and terminal reason when the provider reports them.

package/dist/agent-profile-measurements.d.ts

@@ -0,0 +1,57 @@
+import type { Sha256Digest } from "./agent-candidate.js";
+import type { AgentProfile } from "./agent-profile.js";
+/** UTF-8 source bytes and logical lines, without normalizing the supplied text. */
+export interface AgentProfileTextMeasurement {
+    /** RFC 6901 pointer into the measured profile. */
+    readonly path: string;
+    readonly bytes: number;
+    /** Empty text has zero lines; a final line terminator adds no empty line. */
+    readonly lines: number;
+}
+/** A resource declaration; external content has no measured size until resolved. */
+export interface AgentProfileResourceMeasurement {
+    /** RFC 6901 pointer to the resource or string instruction declaration. */
+    readonly path: string;
+    readonly kind: "inline" | "github";
+    readonly name?: string;
+    readonly bytes: number | null;
+    readonly lines: number | null;
+}
+/** Explicit capability declarations, independent of what a harness actually serves. */
+export interface AgentProfileCapabilityCounts {
+    readonly declared: number;
+    readonly enabled: number;
+    readonly disabled: number;
+}
+/**
+ * Content-free measurements of one exact AgentProfile value. Apply separately
+ * to authored and effective profiles, linked by their existing receipt digests.
+ * This declaration neither proves materialization nor observes capability use.
+ */
+export interface AgentProfileMeasurements {
+    readonly version: 1;
+    readonly basis: "profile-declaration";
+    readonly profileDigest: Sha256Digest;
+    /** Bytes of canonical profile JSON, not mounted context or billed input tokens. */
+    readonly canonicalBytes: number;
+    readonly prompt: readonly AgentProfileTextMeasurement[];
+    readonly tools: AgentProfileCapabilityCounts;
+    readonly mcp: AgentProfileCapabilityCounts;
+    readonly subagents: {
+        readonly declared: number;
+    };
+    readonly resources: readonly AgentProfileResourceMeasurement[];
+    readonly coverage: {
+        readonly tokens: "not-measured";
+        readonly materialization: "not-assessed";
+        readonly usage: "not-assessed";
+    };
+}
+/**
+ * Measure a canonical profile without resolving resources, reading files, or
+ * estimating tokens. Validates the same public profile contract used for
+ * identity. Cache by profileDigest; requesting another summary needs no scan.
+ * Results preserve declaration order and contain no prompt/resource content,
+ * server configuration, permission values, or secret references.
+ */
+export declare function measureAgentProfile(profile: AgentProfile): AgentProfileMeasurements;

package/dist/agent-profile-measurements.js

@@ -0,0 +1,80 @@
+import { canonicalAgentProfileDigest } from "./agent-execution-preparation.js";
+import { canonicalAgentProfileJson } from "./agent-profile-canonical.js";
+import { agentProfileSchema } from "./profile-schema.js";
+const utf8 = new TextEncoder();
+function textMeasurement(path, text) {
+    const breaks = text.match(/\r\n|\r|\n/g)?.length ?? 0;
+    return {
+        path,
+        bytes: utf8.encode(text).byteLength,
+        lines: text.length === 0 ? 0 : breaks + (/[\r\n]$/.test(text) ? 0 : 1),
+    };
+}
+function resourceMeasurement(path, resource) {
+    const text = resource.kind === "inline"
+        ? textMeasurement(path, resource.content)
+        : undefined;
+    return {
+        path,
+        kind: resource.kind,
+        ...(resource.name === undefined ? {} : { name: resource.name }),
+        bytes: text?.bytes ?? null,
+        lines: text?.lines ?? null,
+    };
+}
+function capabilityCounts(enabled) {
+    const count = enabled.filter(Boolean).length;
+    return { declared: enabled.length, enabled: count, disabled: enabled.length - count };
+}
+/**
+ * Measure a canonical profile without resolving resources, reading files, or
+ * estimating tokens. Validates the same public profile contract used for
+ * identity. Cache by profileDigest; requesting another summary needs no scan.
+ * Results preserve declaration order and contain no prompt/resource content,
+ * server configuration, permission values, or secret references.
+ */
+export function measureAgentProfile(profile) {
+    const value = agentProfileSchema.parse(profile);
+    const profileDigest = canonicalAgentProfileDigest(value);
+    const canonical = canonicalAgentProfileJson(value);
+    const prompt = [];
+    for (const key of ["systemPrompt", "appendSystemPrompt"]) {
+        const text = value.prompt?.[key];
+        if (text !== undefined)
+            prompt.push(textMeasurement(`/prompt/${key}`, text));
+    }
+    value.prompt?.instructions?.forEach((text, index) => {
+        prompt.push(textMeasurement(`/prompt/instructions/${index}`, text));
+    });
+    const resources = [];
+    value.resources?.files?.forEach((file, index) => {
+        resources.push(resourceMeasurement(`/resources/files/${index}/resource`, file.resource));
+    });
+    for (const group of ["tools", "skills", "agents", "commands"]) {
+        value.resources?.[group]?.forEach((resource, index) => {
+            resources.push(resourceMeasurement(`/resources/${group}/${index}`, resource));
+        });
+    }
+    const instructions = value.resources?.instructions;
+    if (instructions !== undefined) {
+        resources.push(typeof instructions === "string"
+            ? { kind: "inline", ...textMeasurement("/resources/instructions", instructions) }
+            : resourceMeasurement("/resources/instructions", instructions));
+    }
+    return {
+        version: 1,
+        basis: "profile-declaration",
+        profileDigest,
+        canonicalBytes: utf8.encode(canonical).byteLength,
+        prompt,
+        tools: capabilityCounts(Object.values(value.tools ?? {})),
+        mcp: capabilityCounts(Object.values(value.mcp ?? {}).map((server) => server.enabled !== false)),
+        subagents: { declared: Object.keys(value.subagents ?? {}).length },
+        resources,
+        coverage: {
+            tokens: "not-measured",
+            materialization: "not-assessed",
+            usage: "not-assessed",
+        },
+    };
+}

package/dist/environment-runtime.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import type { AgentRuntimeAttachments } from "./runtime-attachments.js";
 export { AgentRuntimeAttachmentsSchema, type AgentRuntimeAttachments } from "./runtime-attachments.js";
 import type { Sha256Digest } from "./agent-candidate.js";
-import type { AgentProfileCapabilities, AgentProfileValidationResult } from "./agent-profile.js";
+import type { AgentProfile, AgentProfileCapabilities, AgentProfileValidationResult } from "./agent-profile.js";
 import type { InputPart } from "./parts.js";
 import type { StreamEvent } from "./stream-events.js";
 import { type TokenUsage } from "./execution-types.js";
@@ -16,6 +16,8 @@ import type { AgentEnvironmentObservation } from "./environment-observation.js";
 import type { AgentInteractiveSession, AgentInteractiveSessionRef, AgentInteractiveSessionStart } from "./environment-interactive.js";
 import type { AgentTerminalSession, TerminalAttachRequest, TerminalAttachResult } from "./environment-terminal.js";
 export interface AgentTurnInput {
+    /** Exact behavior for this turn, separate from bounded provider metadata. */
+    profile?: AgentProfile;
     prompt?: string;
     parts?: InputPart[];
     sessionId?: string;
@@ -38,6 +40,201 @@ export interface AgentTurnInput {
     providerOptions?: Record<string, unknown>;
 }
 export declare const AgentTurnInputSchema: z.ZodObject<{
+    profile: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        prompt: z.ZodOptional<z.ZodObject<{
+            systemPrompt: z.ZodOptional<z.ZodString>;
+            appendSystemPrompt: z.ZodOptional<z.ZodString>;
+            instructions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        model: z.ZodOptional<z.ZodObject<{
+            default: z.ZodOptional<z.ZodString>;
+            small: z.ZodOptional<z.ZodString>;
+            provider: z.ZodOptional<z.ZodString>;
+            reasoningEffort: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                low: "low";
+                medium: "medium";
+                minimal: "minimal";
+                none: "none";
+                ultracode: "ultracode";
+                xhigh: "xhigh";
+            }>>;
+            maxVisibleOutputTokens: z.ZodOptional<z.ZodNumber>;
+            maxReasoningTokens: z.ZodOptional<z.ZodNumber>;
+            maxTotalOutputTokens: z.ZodOptional<z.ZodNumber>;
+            metadata: z.ZodOptional<z.ZodType<Record<string, unknown>, unknown, z.core.$ZodTypeInternals<Record<string, unknown>, unknown>>>;
+        }, z.core.$strict>>;
+        harness: z.ZodOptional<z.ZodEnum<{
+            acp: "acp";
+            amp: "amp";
+            "claude-code": "claude-code";
+            "cli-base": "cli-base";
+            codex: "codex";
+            cursor: "cursor";
+            "factory-droids": "factory-droids";
+            forge: "forge";
+            gemini: "gemini";
+            hermes: "hermes";
+            "kimi-code": "kimi-code";
+            nanoclaw: "nanoclaw";
+            openclaw: "openclaw";
+            opencode: "opencode";
+            pi: "pi";
+            prime: "prime";
+        }>>;
+        permissions: z.ZodOptional<z.ZodType<Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">>, unknown, z.core.$ZodTypeInternals<Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">>, unknown>>>;
+        tools: z.ZodOptional<z.ZodType<Record<string, boolean>, unknown, z.core.$ZodTypeInternals<Record<string, boolean>, unknown>>>;
+        mcp: z.ZodOptional<z.ZodType<Record<string, import("./agent-profile.js").AgentProfileMcpServer>, unknown, z.core.$ZodTypeInternals<Record<string, import("./agent-profile.js").AgentProfileMcpServer>, unknown>>>;
+        connections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            connectionId: z.ZodString;
+            capabilities: z.ZodArray<z.ZodString>;
+            alias: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        subagents: z.ZodOptional<z.ZodType<Record<string, {
+            description?: string | undefined;
+            prompt?: string | undefined;
+            model?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            maxSteps?: number | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            description?: string | undefined;
+            prompt?: string | undefined;
+            model?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            maxSteps?: number | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown>>>;
+        resources: z.ZodOptional<z.ZodObject<{
+            files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                resource: z.ZodUnion<readonly [z.ZodObject<{
+                    kind: z.ZodLiteral<"inline">;
+                    name: z.ZodString;
+                    content: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"github">;
+                    repository: z.ZodOptional<z.ZodString>;
+                    path: z.ZodString;
+                    ref: z.ZodOptional<z.ZodString>;
+                    name: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>]>;
+                executable: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>>;
+            tools: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            skills: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            agents: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            commands: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                name: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"github">;
+                repository: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                ref: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>]>>;
+            failOnError: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        hooks: z.ZodOptional<z.ZodType<Record<string, {
+            command: string;
+            timeoutMs?: number | undefined;
+            blocking?: boolean | undefined;
+            matcher?: string | undefined;
+            env?: Record<string, {
+                kind: "public";
+                value: string;
+            } | {
+                kind: "secret-ref";
+                key: string;
+                format?: "bearer" | "raw" | undefined;
+            }> | undefined;
+        }[]>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            command: string;
+            timeoutMs?: number | undefined;
+            blocking?: boolean | undefined;
+            matcher?: string | undefined;
+            env?: Record<string, {
+                kind: "public";
+                value: string;
+            } | {
+                kind: "secret-ref";
+                key: string;
+                format?: "bearer" | "raw" | undefined;
+            }> | undefined;
+        }[]>, unknown>>>;
+        modes: z.ZodOptional<z.ZodType<Record<string, {
+            description?: string | undefined;
+            model?: string | undefined;
+            prompt?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown, z.core.$ZodTypeInternals<Record<string, {
+            description?: string | undefined;
+            model?: string | undefined;
+            prompt?: string | undefined;
+            tools?: Record<string, boolean> | undefined;
+            permissions?: Record<string, "allow" | "ask" | "deny" | Record<string, "allow" | "ask" | "deny">> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }>, unknown>>>;
+        confidential: z.ZodOptional<z.ZodObject<{
+            tee: z.ZodOptional<z.ZodString>;
+            attestationNonce: z.ZodOptional<z.ZodString>;
+            sealed: z.ZodOptional<z.ZodBoolean>;
+            attestationRefresh: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        metadata: z.ZodOptional<z.ZodType<import("./agent-profile.js").AgentProfileMetadata, unknown, z.core.$ZodTypeInternals<import("./agent-profile.js").AgentProfileMetadata, unknown>>>;
+        extensions: z.ZodOptional<z.ZodType<Record<string, Record<string, unknown> | undefined>, unknown, z.core.$ZodTypeInternals<Record<string, Record<string, unknown> | undefined>, unknown>>>;
+    }, z.core.$strict>>;
     prompt: z.ZodOptional<z.ZodCustom<string, string>>;
     parts: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"text">;

package/dist/environment-runtime.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 export { AgentRuntimeAttachmentsSchema } from "./runtime-attachments.js";
 import { canonicalCandidateDigest, canonicalCandidateJson, } from "./agent-candidate-schema-common.js";
+import { agentProfileSchema } from "./profile-schema.js";
 import { TokenUsageSchema } from "./execution-types.js";
 import { InteractionCapabilitiesSchema, RequestedInteractionsSchema } from "./interaction.js";
 import { ContextTransferReceiptSchema, ContextTransferRequestSchema, NativeContextBoundaryProofSchema, NativeContextContinuationAcknowledgementSchema, NativeContextContinuationRequestSchema, nativeContextContinuationAcknowledgementMatches } from "./portable-context.js";
@@ -10,6 +11,7 @@ import { boundedEventContentJsonSchema, boundedEventContentRecordSchema, bounded
 import { InputPartSchema } from "./portable-context-shared.js";
 import { deepFreeze } from "./deep-freeze.js";
 export const AgentTurnInputSchema = z.strictObject({
+    profile: agentProfileSchema.optional(),
     // A prompt is what the agent is asked to do, so it is CONTENT: its size is set by the work,
     // not by the protocol. Held to the metadata bound it capped a manager's brief at 16,384
     // characters, which refused a director handing a checker a 27 KB patch to re-verify a measured

package/dist/index.d.ts

@@ -31,6 +31,7 @@ export * from "./agent-instance.js";
 export * from "./agent-profile-snapshot.js";
 export * from "./agent-profile-activation.js";
 export * from "./agent-profile-materialization.js";
+export * from "./agent-profile-measurements.js";
 export * from "./agent-execution-preparation.js";
 export * from "./agent-workspace-lease.js";
 export * from "./certified-context.js";

package/dist/index.js

@@ -29,6 +29,7 @@ export * from "./agent-instance.js";
 export * from "./agent-profile-snapshot.js";
 export * from "./agent-profile-activation.js";
 export * from "./agent-profile-materialization.js";
+export * from "./agent-profile-measurements.js";
 export * from "./agent-execution-preparation.js";
 export * from "./agent-workspace-lease.js";
 export * from "./certified-context.js";

package/package.json

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