npm - @tangle-network/agent-interface - Versions diffs - 3.1.2 → 3.2.0 - Mend

@tangle-network/agent-interface 3.1.2 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +67 -0
package/dist/index.d.ts +1 -0
package/dist/index.js +1 -0
package/dist/learning-state.d.ts +488 -0
package/dist/learning-state.js +154 -0
package/package.json +6 -1

package/README.md CHANGED Viewed

@@ -323,3 +323,70 @@ Adapters emit `native.session.observed` with `provider` and `nativeSessionId` af
 The execution owner binds the observation to its execution and keeps it private.
 Public `session.updated` events retain their resume-key semantics and do not establish native identity.
 Native identity does not establish artifact capture completeness.
+### Optional native learning state interchange
+`@tangle-network/agent-interface/learning-state` describes an **opt-in** boundary
+between a host's existing durable state owner and one explicitly configured
+harness adapter. Native harness memory stays the default. This module creates no
+store, tools, provider connection, profile fields, or automatic synchronization.
+Hindsight memory branches and QMD source snapshots keep their existing
+`agent-knowledge` owners and references; do not copy their facts into a second
+file database to satisfy this contract.
+`AgentLearningIdentity` names an authenticated workspace, stable state, and
+personal member/agent or shared group/agent scope. A thread, native session,
+profile revision, or authority digest is not that identity. The host derives it
+from authenticated context and verifies the persisted root/volume binding;
+passing schema validation does not authorize access. Session and turn IDs belong
+in invocation provenance. Two turns need immutable per-turn state pins plus the
+state owner's lease or compare-and-swap, not an uncoordinated shared writable home.
+`AgentLearningManifest` references the existing owner's exact revision and
+content digest. The `files` field is only a bounded, protected-home-compatible
+text exchange subset: `USER.md` preferences, `MEMORY.md` facts,
+`memory/YYYY-MM-DD.md` notes, and `skills/<slug>/SKILL.md` procedure sources. These
+are interchange names, never a claim about a harness's actual native paths or a
+universal memory model. An adapter must explicitly map and verify this subset.
+A native-only adapter may leave `files` empty and preserve opaque native state
+references instead. Opaque references must resolve privately to verified bytes;
+they must not contain paths, credentials, or access tokens.
+A manifest digest uses the existing canonical candidate JSON/SHA-256 primitives.
+Inventory order is immaterial; exact text, provenance, scope and owner revision
+are bound. Content digests establish bytes, not factual truth or authorization.
+Imported content retains `source.trust: 'untrusted'`. Skill text may be retained
+and exposed as personal context under the caller's existing policy; this never
+automatically activates executable resources, expands permissions, or promotes a
+shared skill catalog. Those effects remain behind the existing profile/authority
+and promotion gates.
+`AgentLearningExport` binds one idempotent operation to the exact immutable base
+digest, harness, and adapter ID/revision. Files are explicit observed deltas;
+omission is not deletion, and `content: null` is a tombstone. The durable owner
+must retain deletion evidence or refuse a tombstone it cannot persist. Retrying
+an operation requires the same bytes and digest. A three-way merge may retain
+unrelated concurrent edits; edit/edit or edit/delete collisions must be explicit,
+never last-writer-wins. Apply with CAS against the latest owner revision, record
+the durable receipt through the existing owner's transaction/journal, then
+publish success. A plan or local checkpoint is not a remote durability receipt.
+Rollback creates a new guarded revision; historical pins remain immutable.
+#### Adding a harness adapter
+1. Declare exact harness and adapter ID/revision. Import and export kinds are
+   separate explicit lists. Missing support is refused; a new harness inherits
+   no learning capability from its session, filesystem, or skill support.
+2. Bind authenticated stable identity to actual retained storage. Define native
+   scope, lease/exclusive-access rules, resume, relocation and cleanup behavior.
+   Keep native-only state intact without exporting the whole home or credentials.
+3. Prefer native preservation. Add portable mappings only when intentionally
+   configured and lossless for the declared subset. State which native data is
+   opaque or unsupported; do not pretend every harness field maps one-to-one.
+4. Exercise a real filesystem fixture across write, session restart and restored
+   root; cover stale CAS, concurrent edits, explicit deletion, replay, conflict,
+   rollback, malformed/oversized input, symlinks and cross-scope isolation.
+5. Bind `nativeState.conformanceDigest` to retained evidence and label
+   `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.

package/dist/index.d.ts CHANGED Viewed

@@ -43,3 +43,4 @@ export * from "./sandbox-size.js";
 export { CONTRACT_MAX_ARRAY_LENGTH, CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH, CONTRACT_MAX_IDENTIFIER_LENGTH, CONTRACT_MAX_JSON_BYTES, CONTRACT_MAX_JSON_DEPTH, CONTRACT_MAX_JSON_NODES, CONTRACT_MAX_MAP_ENTRIES, CONTRACT_MAX_STRING_LENGTH, boundedEventContentJsonSchema, boundedEventContentRecordSchema, boundedEventContentStringSchema, isBoundedEventContentJson, } from "./contract-limits.js";
 export { AgentEnvironmentEgressPolicySchema } from "./environment-requests.js";
 export * from "./native-session-event.js";
+export * from "./learning-state.js";

package/dist/index.js CHANGED Viewed

@@ -45,3 +45,4 @@ export {
 CONTRACT_MAX_ARRAY_LENGTH, CONTRACT_MAX_CONFIDENTIAL_ATTESTATION_QUOTE_LENGTH, CONTRACT_MAX_IDENTIFIER_LENGTH, CONTRACT_MAX_JSON_BYTES, CONTRACT_MAX_JSON_DEPTH, CONTRACT_MAX_JSON_NODES, CONTRACT_MAX_MAP_ENTRIES, CONTRACT_MAX_STRING_LENGTH, boundedEventContentJsonSchema, boundedEventContentRecordSchema, boundedEventContentStringSchema, isBoundedEventContentJson, } from "./contract-limits.js";
 export { AgentEnvironmentEgressPolicySchema } from "./environment-requests.js";
 export * from "./native-session-event.js";
+export * from "./learning-state.js";

package/dist/learning-state.d.ts ADDED Viewed

@@ -0,0 +1,488 @@
+/** Optional protected-home-compatible text interchange, not a universal native-memory format.
+ * Native harness memory, optional provider adapters, AgentProfile and session history retain their owners.
+ * The host authenticates identity and resolves opaque references; schemas confer no authority.
+ */
+import { z } from "zod";
+import type { Sha256Digest } from "./agent-candidate.js";
+export declare const AgentLearningIdentitySchema: z.ZodObject<{
+    workspaceId: z.ZodString;
+    stateId: z.ZodString;
+    scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"personal">;
+        memberId: z.ZodString;
+        agentId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"shared">;
+        groupId: z.ZodString;
+        agentId: z.ZodString;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export type AgentLearningIdentity = z.infer<typeof AgentLearningIdentitySchema>;
+export declare const AGENT_LEARNING_FILE_KINDS: readonly ["fact", "preference", "note", "skill-source"];
+export type AgentLearningFileKind = (typeof AGENT_LEARNING_FILE_KINDS)[number];
+/** Exact allowlist, never a general filesystem or configuration mount. */
+export declare function agentLearningFileKind(path: string): AgentLearningFileKind | null;
+export declare const AgentLearningFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    kind: z.ZodEnum<{
+        fact: "fact";
+        note: "note";
+        preference: "preference";
+        "skill-source": "skill-source";
+    }>;
+    content: z.ZodNullable<z.ZodString>;
+    source: z.ZodObject<{
+        harness: 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";
+        }>;
+        revision: z.ZodString;
+        trust: z.ZodLiteral<"untrusted">;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type AgentLearningFile = z.infer<typeof AgentLearningFileSchema>;
+/** A host-resolved reference to exact native state, never a path or credential value. */
+export declare const AgentLearningNativeRefSchema: z.ZodObject<{
+    harness: 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";
+    }>;
+    format: z.ZodString;
+    revision: z.ZodString;
+    reference: z.ZodString;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+export type AgentLearningNativeRef = z.infer<typeof AgentLearningNativeRefSchema>;
+declare const materialSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    identity: z.ZodObject<{
+        workspaceId: z.ZodString;
+        stateId: z.ZodString;
+        scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"personal">;
+            memberId: z.ZodString;
+            agentId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"shared">;
+            groupId: z.ZodString;
+            agentId: z.ZodString;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>;
+    revision: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodEnum<{
+            fact: "fact";
+            note: "note";
+            preference: "preference";
+            "skill-source": "skill-source";
+        }>;
+        content: z.ZodNullable<z.ZodString>;
+        source: z.ZodObject<{
+            harness: 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";
+            }>;
+            revision: z.ZodString;
+            trust: z.ZodLiteral<"untrusted">;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    native: z.ZodArray<z.ZodObject<{
+        harness: 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";
+        }>;
+        format: z.ZodString;
+        revision: z.ZodString;
+        reference: z.ZodString;
+        digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AgentLearningManifestMaterial = z.infer<typeof materialSchema>;
+/** Canonical digest ignores inventory order; file bytes and provenance remain exact. */
+export declare function agentLearningManifestDigest(value: AgentLearningManifestMaterial): Sha256Digest;
+export declare const AgentLearningManifestSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    identity: z.ZodObject<{
+        workspaceId: z.ZodString;
+        stateId: z.ZodString;
+        scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"personal">;
+            memberId: z.ZodString;
+            agentId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"shared">;
+            groupId: z.ZodString;
+            agentId: z.ZodString;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>;
+    revision: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodEnum<{
+            fact: "fact";
+            note: "note";
+            preference: "preference";
+            "skill-source": "skill-source";
+        }>;
+        content: z.ZodNullable<z.ZodString>;
+        source: z.ZodObject<{
+            harness: 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";
+            }>;
+            revision: z.ZodString;
+            trust: z.ZodLiteral<"untrusted">;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    native: z.ZodArray<z.ZodObject<{
+        harness: 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";
+        }>;
+        format: z.ZodString;
+        revision: z.ZodString;
+        reference: z.ZodString;
+        digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>>;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+export type AgentLearningManifest = z.infer<typeof AgentLearningManifestSchema>;
+/** Detach and freeze an exact turn pin. A retry must persist/reuse this pin, not reread head. */
+export declare function snapshotAgentLearningManifest(value: unknown): AgentLearningManifest;
+declare const exportMaterialSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    operationId: z.ZodString;
+    identity: z.ZodObject<{
+        workspaceId: z.ZodString;
+        stateId: z.ZodString;
+        scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"personal">;
+            memberId: z.ZodString;
+            agentId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"shared">;
+            groupId: z.ZodString;
+            agentId: z.ZodString;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>;
+    baseDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    harness: 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";
+    }>;
+    adapter: z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodString;
+    }, z.core.$strict>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodEnum<{
+            fact: "fact";
+            note: "note";
+            preference: "preference";
+            "skill-source": "skill-source";
+        }>;
+        content: z.ZodNullable<z.ZodString>;
+        source: z.ZodObject<{
+            harness: 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";
+            }>;
+            revision: z.ZodString;
+            trust: z.ZodLiteral<"untrusted">;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    native: z.ZodArray<z.ZodObject<{
+        harness: 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";
+        }>;
+        format: z.ZodString;
+        revision: z.ZodString;
+        reference: z.ZodString;
+        digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AgentLearningExportMaterial = z.infer<typeof exportMaterialSchema>;
+export declare function agentLearningExportDigest(value: AgentLearningExportMaterial): Sha256Digest;
+export declare const AgentLearningExportSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    operationId: z.ZodString;
+    identity: z.ZodObject<{
+        workspaceId: z.ZodString;
+        stateId: z.ZodString;
+        scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"personal">;
+            memberId: z.ZodString;
+            agentId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"shared">;
+            groupId: z.ZodString;
+            agentId: z.ZodString;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>;
+    baseDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    harness: 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";
+    }>;
+    adapter: z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodString;
+    }, z.core.$strict>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        kind: z.ZodEnum<{
+            fact: "fact";
+            note: "note";
+            preference: "preference";
+            "skill-source": "skill-source";
+        }>;
+        content: z.ZodNullable<z.ZodString>;
+        source: z.ZodObject<{
+            harness: 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";
+            }>;
+            revision: z.ZodString;
+            trust: z.ZodLiteral<"untrusted">;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    native: z.ZodArray<z.ZodObject<{
+        harness: 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";
+        }>;
+        format: z.ZodString;
+        revision: z.ZodString;
+        reference: z.ZodString;
+        digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+    }, z.core.$strict>>;
+    digest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+}, z.core.$strict>;
+export type AgentLearningExport = z.infer<typeof AgentLearningExportSchema>;
+/** Capabilities are properties of a particular adapter and tested format, not harness folklore. */
+export declare const AgentLearningCapabilitiesSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    harness: 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";
+    }>;
+    adapter: z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodString;
+    }, z.core.$strict>;
+    importKinds: z.ZodArray<z.ZodEnum<{
+        fact: "fact";
+        note: "note";
+        preference: "preference";
+        "skill-source": "skill-source";
+    }>>;
+    exportKinds: z.ZodArray<z.ZodEnum<{
+        fact: "fact";
+        note: "note";
+        preference: "preference";
+        "skill-source": "skill-source";
+    }>>;
+    nativeState: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"unsupported">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"preserved">;
+        format: z.ZodString;
+        conformanceDigest: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        qualification: z.ZodEnum<{
+            fixture: "fixture";
+            "native-binary": "native-binary";
+        }>;
+    }, z.core.$strict>], "status">;
+}, z.core.$strict>;
+export type AgentLearningCapabilities = z.infer<typeof AgentLearningCapabilitiesSchema>;
+/** No capability by omission. Text preservation does not activate executable skills or profile authority. */
+export declare function unsupportedAgentLearningCapabilities(input: Pick<AgentLearningCapabilities, "harness" | "adapter"> & {
+    reason: string;
+}): AgentLearningCapabilities;
+export {};

package/dist/learning-state.js ADDED Viewed

@@ -0,0 +1,154 @@
+/** Optional protected-home-compatible text interchange, not a universal native-memory format.
+ * Native harness memory, optional provider adapters, AgentProfile and session history retain their owners.
+ * The host authenticates identity and resolves opaque references; schemas confer no authority.
+ */
+import { z } from "zod";
+import { canonicalCandidateDigest, isWellFormedUnicode, sha256DigestSchema } from "./agent-candidate-schema-common.js";
+import { harnessTypeSchema } from "./harness.js";
+import { deepFreeze } from "./deep-freeze.js";
+const id = z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+const revision = z.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+const adapter = z.strictObject({ id, revision });
+export const AgentLearningIdentitySchema = z.strictObject({
+    workspaceId: id,
+    stateId: id,
+    scope: z.discriminatedUnion("kind", [
+        z.strictObject({ kind: z.literal("personal"), memberId: id, agentId: id }),
+        z.strictObject({ kind: z.literal("shared"), groupId: id, agentId: id }),
+    ]),
+});
+export const AGENT_LEARNING_FILE_KINDS = ["fact", "preference", "note", "skill-source"];
+const fileKind = z.enum(AGENT_LEARNING_FILE_KINDS);
+/** Exact allowlist, never a general filesystem or configuration mount. */
+export function agentLearningFileKind(path) {
+    if (path === "MEMORY.md")
+        return "fact";
+    if (path === "USER.md")
+        return "preference";
+    if (/^skills\/[a-z0-9][a-z0-9-]{0,63}\/SKILL\.md$/.test(path))
+        return "skill-source";
+    const note = /^memory\/(\d{4}-\d{2}-\d{2})\.md$/.exec(path);
+    if (note) {
+        const date = new Date(`${note[1]}T00:00:00.000Z`);
+        if (Number.isFinite(date.getTime()) && date.toISOString().slice(0, 10) === note[1])
+            return "note";
+    }
+    return null;
+}
+export const AgentLearningFileSchema = z.strictObject({
+    path: z.string().min(1).max(100),
+    kind: fileKind,
+    /** Null is an explicit tombstone. Omission from an export never deletes a file. */
+    content: z.string().max(131_072).refine(isWellFormedUnicode).nullable(),
+    source: z.strictObject({
+        harness: harnessTypeSchema,
+        revision,
+        /** Origin metadata is evidence of provenance, not truth or trusted instructions. */
+        trust: z.literal("untrusted"),
+    }),
+}).superRefine((file, ctx) => {
+    if (agentLearningFileKind(file.path) !== file.kind) {
+        ctx.addIssue({ code: "custom", path: ["path"], message: "learned file path does not match its portable kind" });
+    }
+    const limits = { fact: 16_000, preference: 4_000, note: 12_000, "skill-source": 32_000 };
+    if (file.content !== null && [...file.content].length > limits[file.kind]) {
+        ctx.addIssue({ code: "custom", path: ["content"], message: "learned file exceeds its character budget" });
+    }
+});
+/** A host-resolved reference to exact native state, never a path or credential value. */
+export const AgentLearningNativeRefSchema = z.strictObject({
+    harness: harnessTypeSchema,
+    format: id,
+    revision,
+    reference: id,
+    digest: sha256DigestSchema,
+});
+const files = z.array(AgentLearningFileSchema).max(1_024).superRefine((value, ctx) => {
+    if (new Set(value.map((file) => file.path)).size !== value.length) {
+        ctx.addIssue({ code: "custom", message: "learned file paths must be unique" });
+    }
+    if (value.reduce((size, file) => size + new TextEncoder().encode(file.content ?? "").length, 0) > 8 * 1024 * 1024) {
+        ctx.addIssue({ code: "custom", message: "learned state exceeds its byte budget" });
+    }
+});
+const native = z.array(AgentLearningNativeRefSchema).max(64).superRefine((value, ctx) => {
+    if (new Set(value.map((ref) => `${ref.harness}:${ref.format}`)).size !== value.length) {
+        ctx.addIssue({ code: "custom", message: "native state references must be unique by harness and format" });
+    }
+});
+const materialSchema = z.strictObject({
+    version: z.literal(1),
+    identity: AgentLearningIdentitySchema,
+    /** Exact existing owner revision (e.g. protected-home Git commit), not a second revision store. */
+    revision,
+    files,
+    native,
+});
+/** Canonical digest ignores inventory order; file bytes and provenance remain exact. */
+export function agentLearningManifestDigest(value) {
+    const parsed = materialSchema.parse(value);
+    return canonicalCandidateDigest({ ...parsed,
+        files: [...parsed.files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0),
+        native: [...parsed.native].sort((a, b) => `${a.harness}:${a.format}` < `${b.harness}:${b.format}` ? -1 : 1),
+    });
+}
+export const AgentLearningManifestSchema = materialSchema.extend({ digest: sha256DigestSchema })
+    .superRefine(({ digest, ...material }, ctx) => {
+    if (ctx.issues.length)
+        return;
+    if (digest !== agentLearningManifestDigest(material)) {
+        ctx.addIssue({ code: "custom", path: ["digest"], message: "learned manifest digest does not match its material" });
+    }
+});
+/** Detach and freeze an exact turn pin. A retry must persist/reuse this pin, not reread head. */
+export function snapshotAgentLearningManifest(value) {
+    return deepFreeze(AgentLearningManifestSchema.parse(structuredClone(value)));
+}
+const exportMaterialSchema = z.strictObject({
+    version: z.literal(1),
+    operationId: id,
+    identity: AgentLearningIdentitySchema,
+    baseDigest: sha256DigestSchema,
+    harness: harnessTypeSchema,
+    adapter,
+    /** Explicit deltas only. Never infer deletion from absence or a partial native listing. */
+    files,
+    native,
+});
+export function agentLearningExportDigest(value) {
+    const parsed = exportMaterialSchema.parse(value);
+    return canonicalCandidateDigest({ ...parsed,
+        files: [...parsed.files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0),
+        native: [...parsed.native].sort((a, b) => `${a.harness}:${a.format}` < `${b.harness}:${b.format}` ? -1 : 1),
+    });
+}
+export const AgentLearningExportSchema = exportMaterialSchema.extend({ digest: sha256DigestSchema })
+    .superRefine(({ digest, ...material }, ctx) => {
+    if (ctx.issues.length)
+        return;
+    if (digest !== agentLearningExportDigest(material)) {
+        ctx.addIssue({ code: "custom", path: ["digest"], message: "learned export digest does not match its material" });
+    }
+    if (material.files.some((file) => file.source.harness !== material.harness) || material.native.some((ref) => ref.harness !== material.harness)) {
+        ctx.addIssue({ code: "custom", message: "export provenance must name its declared harness" });
+    }
+});
+const kinds = z.array(fileKind).max(AGENT_LEARNING_FILE_KINDS.length).refine((value) => new Set(value).size === value.length);
+/** Capabilities are properties of a particular adapter and tested format, not harness folklore. */
+export const AgentLearningCapabilitiesSchema = z.strictObject({
+    version: z.literal(1),
+    harness: harnessTypeSchema,
+    adapter,
+    importKinds: kinds,
+    exportKinds: kinds,
+    nativeState: z.discriminatedUnion("status", [
+        z.strictObject({ status: z.literal("unsupported"), reason: z.string().min(1).max(512) }),
+        z.strictObject({ status: z.literal("preserved"), format: id, conformanceDigest: sha256DigestSchema,
+            qualification: z.enum(["fixture", "native-binary"]) }),
+    ]),
+});
+/** No capability by omission. Text preservation does not activate executable skills or profile authority. */
+export function unsupportedAgentLearningCapabilities(input) {
+    return deepFreeze(AgentLearningCapabilitiesSchema.parse({ version: 1, harness: input.harness, adapter: input.adapter, importKinds: [], exportKinds: [],
+        nativeState: { status: "unsupported", reason: input.reason } }));
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -61,6 +61,11 @@
       "import": "./dist/profile-kb/index.js",
       "types": "./dist/profile-kb/index.d.ts",
       "default": "./dist/profile-kb/index.js"
+    },
+    "./learning-state": {
+      "import": "./dist/learning-state.js",
+      "types": "./dist/learning-state.d.ts",
+      "default": "./dist/learning-state.js"
     }
   },
   "repository": {