@tangle-network/agent-interface 5.0.0 → 5.2.0

package/README.md

@@ -399,3 +399,19 @@ Rollback creates a new guarded revision; historical pins remain immutable.
    `qualification: 'fixture'` or `'native-binary'` honestly. A fixture is not proof
    of an external CLI binary or deployed volume. Complete native-binary and
    deployment qualification before advertising those stronger guarantees.
+
+
+### Pinned knowledge sources
+
+`AgentProfile.resources.knowledge` carries up to `MAX_PROFILE_KNOWLEDGE_SOURCES`
+immutable `{ sourceId, generation }` Hub references. A generation is an exact
+`kg_` SHA-256 identity, never a mutable `latest` alias. A source may appear only
+once. These references participate in snapshots, candidate identity, profile
+merges/diffs and the `knowledge` materialization axis. An overlay can explicitly
+repin a source; a diff can remove it by source ID.
+
+References contain neither corpus content nor authorization. The execution host
+must validate source ownership and active generation bindings for its own runtime
+before admitting a knowledge tool. A profile copied to another owner does not
+confer access. Hosts unable to resolve the saved pins must fail closed rather than
+inline JSON into instructions, substitute a newer generation or silently omit them.

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

@@ -375,6 +375,10 @@ export declare const agentCandidateFileMountSchema: z.ZodObject<{
     executable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const agentCandidateResourcesSchema: z.ZodObject<{
+    knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        sourceId: z.ZodString;
+        generation: z.ZodString;
+    }, z.core.$strict>>>;
     files: z.ZodOptional<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         resource: z.ZodDiscriminatedUnion<[z.ZodObject<{

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { agentProfileKnowledgeRefsSchema } from "./profile-knowledge.js";
 import { agentCandidateGitHubRepositorySchema, gitObjectSchema, isSafeRelativePath, isWellFormedUnicode, looksLikeCredential, sha256DigestSchema, } from "./agent-candidate-schema-common.js";
 import { agentImprovementSourceSchema } from "./agent-improvement-source.js";
 const base64Alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -234,6 +235,7 @@ export const agentCandidateFileMountSchema = z
     .strict();
 export const agentCandidateResourcesSchema = z
     .object({
+    knowledge: agentProfileKnowledgeRefsSchema.optional(),
     files: z.array(agentCandidateFileMountSchema).optional(),
     tools: z.array(agentCandidateResourceRefSchema).optional(),
     skills: z.array(agentCandidateResourceRefSchema).optional(),

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

@@ -76,6 +76,10 @@ export declare const agentCandidateProfileSchema: z.ZodObject<{
         maxSteps: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
     resources: z.ZodOptional<z.ZodObject<{
+        knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            sourceId: z.ZodString;
+            generation: z.ZodString;
+        }, z.core.$strict>>>;
         files: z.ZodOptional<z.ZodArray<z.ZodObject<{
             path: z.ZodString;
             resource: z.ZodDiscriminatedUnion<[z.ZodObject<{

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

@@ -67,6 +67,10 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
                 maxSteps: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strict>>>;
             resources: z.ZodOptional<z.ZodObject<{
+                knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    sourceId: z.ZodString;
+                    generation: z.ZodString;
+                }, z.core.$strict>>>;
                 files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     path: z.ZodString;
                     resource: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -932,6 +936,10 @@ export declare const agentCandidateExperimentSchema: z.ZodObject<{
                 maxSteps: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strict>>>;
             resources: z.ZodOptional<z.ZodObject<{
+                knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    sourceId: z.ZodString;
+                    generation: z.ZodString;
+                }, z.core.$strict>>>;
                 files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     path: z.ZodString;
                     resource: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -3897,6 +3905,10 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                     maxSteps: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strict>>>;
                 resources: z.ZodOptional<z.ZodObject<{
+                    knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        sourceId: z.ZodString;
+                        generation: z.ZodString;
+                    }, z.core.$strict>>>;
                     files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         path: z.ZodString;
                         resource: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -4762,6 +4774,10 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                     maxSteps: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strict>>>;
                 resources: z.ZodOptional<z.ZodObject<{
+                    knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        sourceId: z.ZodString;
+                        generation: z.ZodString;
+                    }, z.core.$strict>>>;
                     files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         path: z.ZodString;
                         resource: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -9301,6 +9317,10 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                         maxSteps: z.ZodOptional<z.ZodNumber>;
                     }, z.core.$strict>>>;
                     resources: z.ZodOptional<z.ZodObject<{
+                        knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                            sourceId: z.ZodString;
+                            generation: z.ZodString;
+                        }, z.core.$strict>>>;
                         files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                             path: z.ZodString;
                             resource: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -10166,6 +10186,10 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                         maxSteps: z.ZodOptional<z.ZodNumber>;
                     }, z.core.$strict>>>;
                     resources: z.ZodOptional<z.ZodObject<{
+                        knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                            sourceId: z.ZodString;
+                            generation: z.ZodString;
+                        }, z.core.$strict>>>;
                         files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                             path: z.ZodString;
                             resource: z.ZodDiscriminatedUnion<[z.ZodObject<{

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

@@ -71,6 +71,10 @@ export declare const agentCandidateBundleSchema: z.ZodObject<{
             maxSteps: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>>;
         resources: z.ZodOptional<z.ZodObject<{
+            knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                sourceId: z.ZodString;
+                generation: z.ZodString;
+            }, z.core.$strict>>>;
             files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 path: z.ZodString;
                 resource: z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/agent-candidate.d.ts

@@ -37,6 +37,18 @@ export interface AgentCandidateArtifactRef {
     sha256: Sha256Digest;
     byteLength: number;
 }
+/** Reads one content-addressed object through an authorized closed-locator resolver. */
+export interface AgentCandidateArtifactPort {
+    read(ref: AgentCandidateArtifactRef): Promise<Uint8Array>;
+    /** Stream an artifact without materializing its complete contents. */
+    readStream?(ref: AgentCandidateArtifactRef, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<Uint8Array>;
+    /** Find an already stored object by its exact content digest and length. */
+    locate?(object: Pick<AgentCandidateArtifactRef, "sha256" | "byteLength">, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentCandidateArtifactRef | undefined>;
+}
 /** Bytes embedded directly in a candidate manifest. */
 export interface AgentCandidateEmbeddedArtifact {
     encoding: "base64";

package/dist/agent-execution-preparation-receipt.d.ts

@@ -108,6 +108,7 @@ export declare const agentExecutionPreparationAxisResultSchema: z.ZodObject<{
         harness: "harness";
         hooks: "hooks";
         instructions: "instructions";
+        knowledge: "knowledge";
         mcp: "mcp";
         metadata: "metadata";
         modelDefault: "modelDefault";
@@ -260,6 +261,7 @@ export declare const agentExecutionPreparationReceiptSchema: z.ZodObject<{
             harness: "harness";
             hooks: "hooks";
             instructions: "instructions";
+            knowledge: "knowledge";
             mcp: "mcp";
             metadata: "metadata";
             modelDefault: "modelDefault";

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

@@ -9,7 +9,7 @@ import type { AgentProfile } from "./agent-profile.js";
  * can only add text must report the requested replacement as unsatisfied rather
  * than acknowledge it.
  */
-export declare const AGENT_PROFILE_MATERIALIZATION_AXES: readonly ["name", "description", "version", "tags", "systemPrompt", "appendSystemPrompt", "instructions", "modelDefault", "modelSmall", "modelProvider", "modelReasoningEffort", "modelMaxVisibleOutputTokens", "modelMaxReasoningTokens", "modelMaxTotalOutputTokens", "modelMetadata", "harness", "seats", "permissions", "tools", "mcp", "connections", "subagents", "files", "resourceTools", "skills", "resourceAgents", "commands", "resourceInstructions", "resourceFailOnError", "hooks", "modes", "confidential", "metadata", "extensions"];
+export declare const AGENT_PROFILE_MATERIALIZATION_AXES: readonly ["name", "description", "version", "tags", "systemPrompt", "appendSystemPrompt", "instructions", "modelDefault", "modelSmall", "modelProvider", "modelReasoningEffort", "modelMaxVisibleOutputTokens", "modelMaxReasoningTokens", "modelMaxTotalOutputTokens", "modelMetadata", "harness", "seats", "permissions", "tools", "mcp", "connections", "subagents", "files", "resourceTools", "skills", "resourceAgents", "commands", "knowledge", "resourceInstructions", "resourceFailOnError", "hooks", "modes", "confidential", "metadata", "extensions"];
 /** One exact leaf of the public AgentProfile contract. */
 export type AgentProfileMaterializationAxis = (typeof AGENT_PROFILE_MATERIALIZATION_AXES)[number];
 /** Compatibility name used by runtimes that distinguish canonical axes. */

package/dist/agent-profile-materialization.js

@@ -36,6 +36,7 @@ export const AGENT_PROFILE_MATERIALIZATION_AXES = [
     "skills",
     "resourceAgents",
     "commands",
+    "knowledge",
     "resourceInstructions",
     "resourceFailOnError",
     "hooks",
@@ -146,6 +147,11 @@ const AXIS_DESCRIPTORS = [
         rootPath: "/resources/commands",
         value: (profile) => profile.resources?.commands,
     },
+    {
+        axis: "knowledge",
+        rootPath: "/resources/knowledge",
+        value: (profile) => profile.resources?.knowledge,
+    },
     {
         axis: "resourceInstructions",
         rootPath: "/resources/instructions",

package/dist/agent-profile.d.ts

@@ -59,7 +59,16 @@ export interface AgentProfileFileMount {
 /**
  * Provider-neutral resource bundle.
  */
+export declare const MAX_PROFILE_KNOWLEDGE_SOURCES = 16;
+/** Immutable Hub source generation. This is public identity, never retrieval authority. */
+export interface AgentProfileKnowledgeRef {
+    sourceId: string;
+    generation: string;
+}
 export interface AgentProfileResources {
+    /** Owner-authorized source generations resolved by the execution host before admission.
+     * Source content and credentials must never be inlined into a profile or prompt. */
+    knowledge?: AgentProfileKnowledgeRef[];
     /**
      * Generic files to materialize into the agent workspace before execution.
      */

package/dist/agent-profile.js

@@ -31,6 +31,10 @@ export function defineGitHubResource(path, options = {}) {
         ...(options.name === undefined ? {} : { name: options.name }),
     };
 }
+/**
+ * Provider-neutral resource bundle.
+ */
+export const MAX_PROFILE_KNOWLEDGE_SOURCES = 16;
 /**
  * Portable reasoning/thinking effort. Backends map it to their native control at materialization:
  * codex `model_reasoning_effort`, kimi `--thinking`/`--no-thinking`, claude thinking budget.
@@ -126,6 +130,16 @@ function mergeOptionalArrays(base, overlay) {
         return undefined;
     return [...(base ?? []), ...(overlay ?? [])];
 }
+/** A source has one effective immutable generation; an overlay explicitly repins it. */
+function mergeKnowledgeRefs(base, overlay) {
+    if (!base && !overlay)
+        return undefined;
+    const refs = new Map();
+    for (const ref of [...(base ?? []), ...(overlay ?? [])]) {
+        refs.set(ref.sourceId, { ...ref });
+    }
+    return [...refs.values()];
+}
 /**
  * Merge two public AgentProfile values.
  *
@@ -151,6 +165,7 @@ export function mergeAgentProfiles(base, overlay) {
         : undefined;
     const mergedResources = base?.resources || overlay?.resources
         ? assignDefined(base?.resources, overlay?.resources, {
+            knowledge: mergeKnowledgeRefs(base?.resources?.knowledge, overlay?.resources?.knowledge),
             files: mergeOptionalArrays(base?.resources?.files, overlay?.resources?.files),
             tools: mergeOptionalArrays(base?.resources?.tools, overlay?.resources?.tools),
             skills: mergeOptionalArrays(base?.resources?.skills, overlay?.resources?.skills),

package/dist/environment-interactive-control.d.ts

@@ -102,6 +102,7 @@ export declare const AgentInteractiveSessionRefSchema: z.ZodObject<{
                 harness: "harness";
                 hooks: "hooks";
                 instructions: "instructions";
+                knowledge: "knowledge";
                 mcp: "mcp";
                 metadata: "metadata";
                 modelDefault: "modelDefault";
@@ -278,6 +279,7 @@ export declare const AgentInteractiveSessionControlClaimRequestSchema: z.ZodObje
                     harness: "harness";
                     hooks: "hooks";
                     instructions: "instructions";
+                    knowledge: "knowledge";
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
@@ -447,6 +449,7 @@ export declare const AgentInteractiveSessionControlClaimAcknowledgementSchema: z
                     harness: "harness";
                     hooks: "hooks";
                     instructions: "instructions";
+                    knowledge: "knowledge";
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
@@ -637,6 +640,7 @@ export declare const AgentInteractiveSessionStatusSchema: z.ZodDiscriminatedUnio
                     harness: "harness";
                     hooks: "hooks";
                     instructions: "instructions";
+                    knowledge: "knowledge";
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
@@ -786,6 +790,7 @@ export declare const AgentInteractiveSessionStatusSchema: z.ZodDiscriminatedUnio
                     harness: "harness";
                     hooks: "hooks";
                     instructions: "instructions";
+                    knowledge: "knowledge";
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
@@ -943,6 +948,7 @@ export declare const AgentInteractiveSessionStatusSchema: z.ZodDiscriminatedUnio
                     harness: "harness";
                     hooks: "hooks";
                     instructions: "instructions";
+                    knowledge: "knowledge";
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
@@ -1105,6 +1111,7 @@ export declare const AgentInteractiveSessionStopCommandSchema: z.ZodObject<{
                     harness: "harness";
                     hooks: "hooks";
                     instructions: "instructions";
+                    knowledge: "knowledge";
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
@@ -1276,6 +1283,7 @@ export declare const AgentInteractiveSessionStopAcknowledgementSchema: z.ZodObje
                     harness: "harness";
                     hooks: "hooks";
                     instructions: "instructions";
+                    knowledge: "knowledge";
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
@@ -1463,6 +1471,7 @@ export declare const AgentInteractiveSessionPromptCommandSchema: z.ZodObject<{
                     harness: "harness";
                     hooks: "hooks";
                     instructions: "instructions";
+                    knowledge: "knowledge";
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";
@@ -1633,6 +1642,7 @@ export declare const AgentInteractiveSessionPromptAcknowledgementSchema: z.ZodOb
                     harness: "harness";
                     hooks: "hooks";
                     instructions: "instructions";
+                    knowledge: "knowledge";
                     mcp: "mcp";
                     metadata: "metadata";
                     modelDefault: "modelDefault";

package/dist/environment-interactive-start.d.ts

@@ -126,6 +126,10 @@ export declare const AgentInteractiveSessionStartSchema: z.ZodObject<{
             metadata?: Record<string, unknown> | undefined;
         }>, unknown>>>;
         resources: z.ZodOptional<z.ZodObject<{
+            knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                sourceId: z.ZodString;
+                generation: z.ZodString;
+            }, z.core.$strict>>>;
             files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 path: z.ZodString;
                 resource: z.ZodUnion<readonly [z.ZodObject<{

package/dist/environment-runtime.d.ts

@@ -1,7 +1,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 { AgentCandidateArtifactPort, Sha256Digest } from "./agent-candidate.js";
 import type { AgentProfile, AgentProfileCapabilities, AgentProfileValidationResult } from "./agent-profile.js";
 import type { InputPart } from "./parts.js";
 import type { StreamEvent } from "./stream-events.js";
@@ -149,6 +149,10 @@ export declare const AgentTurnInputSchema: z.ZodObject<{
             metadata?: Record<string, unknown> | undefined;
         }>, unknown>>>;
         resources: z.ZodOptional<z.ZodObject<{
+            knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                sourceId: z.ZodString;
+                generation: z.ZodString;
+            }, z.core.$strict>>>;
             files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 path: z.ZodString;
                 resource: z.ZodUnion<readonly [z.ZodObject<{
@@ -516,6 +520,10 @@ export declare const AgentTurnInputSchema: z.ZodObject<{
                 metadata?: Record<string, unknown> | undefined;
             }>, unknown>>>;
             resources: z.ZodOptional<z.ZodObject<{
+                knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    sourceId: z.ZodString;
+                    generation: z.ZodString;
+                }, z.core.$strict>>>;
                 files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     path: z.ZodString;
                     resource: z.ZodUnion<readonly [z.ZodObject<{
@@ -1358,13 +1366,15 @@ export interface AgentEnvironmentCapabilities {
         /** The provider exposes the exact continued run before terminal output. */
         admissionControl?: boolean;
     };
-    /** Present only when fresh-session portable context transfer is durable. */
+    /** Durable portable-context lookup and independently qualified fresh-session admission. */
     contextTransfer?: {
         freshSession: boolean;
         requestIdempotency: boolean;
         lookup: boolean;
         /** get(id, { contextTransfer }) verifies the durable receipt and enables only its first turn. */
         attach?: boolean;
+        /** Restores accepted snapshot refs before native admission. Absent or false means unsupported. */
+        workspaceSnapshot?: boolean;
     };
     /** Absent when the provider cannot originate or answer interactions. */
     interactions?: InteractionCapabilities;
@@ -1521,6 +1531,7 @@ export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
         requestIdempotency: z.ZodBoolean;
         lookup: z.ZodBoolean;
         attach: z.ZodOptional<z.ZodBoolean>;
+        workspaceSnapshot: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     interactions: z.ZodOptional<z.ZodObject<{
         kinds: z.ZodArray<z.ZodString>;
@@ -1925,6 +1936,10 @@ export declare const AgentEnvironmentGetOptionsSchema: z.ZodObject<{
                 metadata?: Record<string, unknown> | undefined;
             }>, unknown>>>;
             resources: z.ZodOptional<z.ZodObject<{
+                knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    sourceId: z.ZodString;
+                    generation: z.ZodString;
+                }, z.core.$strict>>>;
                 files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     path: z.ZodString;
                     resource: z.ZodUnion<readonly [z.ZodObject<{
@@ -2185,6 +2200,8 @@ export interface AgentEnvironmentProvider {
 export interface AgentContextTransferProvider {
     transfer(request: ContextTransferRequest, options?: {
         signal?: AbortSignal;
+        /** Authorized source artifacts for this attempt; never part of the accepted wire request. */
+        artifacts?: AgentCandidateArtifactPort;
     }): Promise<ContextTransferResult>;
     lookup(request: ContextTransferRequest, options?: {
         signal?: AbortSignal;

package/dist/environment-runtime.js

@@ -199,6 +199,7 @@ export const AgentEnvironmentCapabilitiesSchema = z
         requestIdempotency: z.boolean(),
         lookup: z.boolean(),
         attach: z.boolean().optional(),
+        workspaceSnapshot: z.boolean().optional(),
     })
         .optional(),
     interactions: InteractionCapabilitiesSchema.optional(),
@@ -318,14 +319,16 @@ export const AgentEnvironmentCapabilitiesSchema = z
             message: "native continuation requires retained control for early admission",
         });
     }
-    if (capabilities.contextTransfer !== undefined &&
-        (!capabilities.contextTransfer.freshSession ||
-            !capabilities.contextTransfer.requestIdempotency ||
-            !capabilities.contextTransfer.lookup)) {
+    const contextTransfer = capabilities.contextTransfer;
+    if (contextTransfer !== undefined &&
+        (!contextTransfer.lookup ||
+            (contextTransfer.freshSession && !contextTransfer.requestIdempotency) ||
+            ((contextTransfer.attach === true || contextTransfer.workspaceSnapshot === true) &&
+                (!contextTransfer.freshSession || !contextTransfer.requestIdempotency)))) {
         refinement.addIssue({
             code: "custom",
             path: ["contextTransfer"],
-            message: "context transfer requires fresh-session admission, request idempotency, and lookup together",
+            message: "context transfer requires durable lookup; fresh admission, attachment, and snapshot transfer require fresh-session admission and request idempotency together",
         });
     }
     const durableBranching = [

package/dist/portable-context-transfer.d.ts

@@ -236,6 +236,10 @@ export declare const ContextTransferRequestSchema: z.ZodObject<{
             metadata?: Record<string, unknown> | undefined;
         }>, unknown>>>;
         resources: z.ZodOptional<z.ZodObject<{
+            knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                sourceId: z.ZodString;
+                generation: z.ZodString;
+            }, z.core.$strict>>>;
             files: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 path: z.ZodString;
                 resource: z.ZodUnion<readonly [z.ZodObject<{

package/dist/profile-diff.d.ts

@@ -8,6 +8,7 @@ export interface AgentProfilePromptRemoval {
     instructions?: AgentProfileRemoveList;
 }
 export interface AgentProfileResourceRemoval {
+    knowledge?: AgentProfileRemoveList;
     files?: AgentProfileRemoveList;
     tools?: AgentProfileRemoveList;
     skills?: AgentProfileRemoveList;

package/dist/profile-diff.js

@@ -30,6 +30,7 @@ const agentProfilePromptDiffPropertyAxes = [
 const _agentProfilePromptDiffPropertyAxesAreExhaustive = true;
 void _agentProfilePromptDiffPropertyAxesAreExhaustive;
 const agentProfileResourceDiffPropertyAxes = [
+    "knowledge",
     "files",
     "tools",
     "skills",
@@ -178,6 +179,12 @@ function removeResources(resources, removal) {
     if (removal === true)
         return undefined;
     const next = { ...resources };
+    if (removal.knowledge === true)
+        delete next.knowledge;
+    else if (removal.knowledge !== undefined) {
+        const removeSet = new Set(removal.knowledge);
+        setOrDelete(next, "knowledge", next.knowledge?.filter((ref) => !removeSet.has(ref.sourceId)));
+    }
     if (removal.files !== undefined) {
         if (removal.files === true) {
             delete next.files;
@@ -199,6 +206,7 @@ function removeResources(resources, removal) {
     if (removal.failOnError)
         delete next.failOnError;
     for (const key of [
+        "knowledge",
         "files",
         "tools",
         "skills",

package/dist/profile-knowledge.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+/** Immutable Hub generation identities, never aliases such as latest or a caller's scope. */
+export declare const agentProfileKnowledgeRefSchema: z.ZodObject<{
+    sourceId: z.ZodString;
+    generation: z.ZodString;
+}, z.core.$strict>;
+export declare const agentProfileKnowledgeRefsSchema: z.ZodArray<z.ZodObject<{
+    sourceId: z.ZodString;
+    generation: z.ZodString;
+}, z.core.$strict>>;

package/dist/profile-knowledge.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { MAX_PROFILE_KNOWLEDGE_SOURCES, } from "./agent-profile.js";
+/** Immutable Hub generation identities, never aliases such as latest or a caller's scope. */
+export const agentProfileKnowledgeRefSchema = z.strictObject({
+    sourceId: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/),
+    generation: z.string().regex(/^kg_[a-f0-9]{64}$/),
+});
+export const agentProfileKnowledgeRefsSchema = z
+    .array(agentProfileKnowledgeRefSchema)
+    .max(MAX_PROFILE_KNOWLEDGE_SOURCES)
+    .superRefine((refs, context) => {
+    const seen = new Set();
+    refs.forEach((ref, index) => {
+        if (seen.has(ref.sourceId))
+            context.addIssue({
+                code: "custom",
+                path: [index, "sourceId"],
+                message: "A profile must pin exactly one generation per knowledge source",
+            });
+        seen.add(ref.sourceId);
+    });
+});

package/dist/profile-schema.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+export { agentProfileKnowledgeRefSchema, agentProfileKnowledgeRefsSchema, } from "./profile-knowledge.js";
 import { type AgentProfile, type AgentProfileMetadata, type AgentTrainingTask, type AgentProfileMcpServer } from "./agent-profile.js";
 import type { AgentProfileDiff } from "./profile-diff.js";
 import { type SandboxSizePreset } from "./sandbox-size.js";
@@ -39,6 +40,10 @@ export declare const agentProfileFileMountSchema: z.ZodObject<{
     executable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const agentProfileResourcesSchema: z.ZodObject<{
+    knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        sourceId: z.ZodString;
+        generation: z.ZodString;
+    }, z.core.$strict>>>;
     files: z.ZodOptional<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         resource: z.ZodUnion<readonly [z.ZodObject<{
@@ -319,6 +324,7 @@ export declare const agentProfilePromptRemovalSchema: z.ZodObject<{
     instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strict>;
 export declare const agentProfileResourceRemovalSchema: z.ZodObject<{
+    knowledge: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
     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>]>>;
@@ -344,6 +350,7 @@ export declare const agentProfileDiffRemovalSchema: z.ZodObject<{
     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<{
+        knowledge: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodArray<z.ZodString>]>>;
         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>]>>;
@@ -575,6 +582,10 @@ export declare const agentProfileSchema: z.ZodObject<{
         metadata?: Record<string, unknown> | undefined;
     }>, unknown>>>;
     resources: z.ZodOptional<z.ZodObject<{
+        knowledge: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            sourceId: z.ZodString;
+            generation: z.ZodString;
+        }, z.core.$strict>>>;
         files: z.ZodOptional<z.ZodArray<z.ZodObject<{
             path: z.ZodString;
             resource: z.ZodUnion<readonly [z.ZodObject<{

package/dist/profile-schema.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { agentProfileKnowledgeRefsSchema } from "./profile-knowledge.js";
+export { agentProfileKnowledgeRefSchema, agentProfileKnowledgeRefsSchema, } from "./profile-knowledge.js";
 import { REASONING_EFFORTS, TRAINED_MODEL_PREFIX, trainedModelIdForArtifact, } from "./agent-profile.js";
 import { canonicalCandidateDigest, sha256DigestSchema, environmentNameSchema, headerNameSchema, isSafeExecutable, isSafeRelativePath, isWellFormedUnicode, looksLikeCredential, } from "./agent-candidate-schema-common.js";
 import { harnessTypeSchema } from "./harness.js";
@@ -82,6 +84,7 @@ export const agentProfileFileMountSchema = z.strictObject({
     executable: z.boolean().optional(),
 });
 export const agentProfileResourcesSchema = z.strictObject({
+    knowledge: agentProfileKnowledgeRefsSchema.optional(),
     files: z.array(agentProfileFileMountSchema).optional(),
     tools: z.array(agentProfileResourceRefSchema).optional(),
     skills: z.array(agentProfileResourceRefSchema).optional(),
@@ -306,6 +309,7 @@ export const agentProfilePromptRemovalSchema = z.strictObject({
     instructions: removeListSchema.optional(),
 });
 export const agentProfileResourceRemovalSchema = z.strictObject({
+    knowledge: removeListSchema.optional(),
     files: removeListSchema.optional(),
     tools: removeListSchema.optional(),
     skills: removeListSchema.optional(),

package/package.json

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