@byok-sdk/protocol 0.25.0 → 0.26.0-rc.1

package/dist/messages.d.ts

@@ -301,6 +301,19 @@ export declare const TaskOfferWithToolsetsPayloadSchema: z.ZodObject<{
     requiredToolsets: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
 export type TaskOfferWithToolsetsPayload = z.infer<typeof TaskOfferWithToolsetsPayloadSchema>;
+/**
+ * How an Agent Attempt uses its Agent home. `memory-reader` runs the Attempt
+ * in its own run directory, `<home>/.byok/runs/<taskId>/`, beside other
+ * reader Attempts and at most one writer Attempt. The home stays an ancestor
+ * of that cwd, so the runtime still finds the persona and memory. Absent means
+ * a writer: the Attempt runs in the canonical home, and one home has at most
+ * one writer at a time. The SDK does not make memory read-only; a reader
+ * terminal reports memory changes in `agentHomeMemoryChange`. A host sends this
+ * field only to a device that advertises `agent-home-readers`: the Agent
+ * offers are strict, so an older daemon cannot accept it.
+ */
+export declare const AgentHomeAccessSchema: z.ZodLiteral<"memory-reader">;
+export type AgentHomeAccess = z.infer<typeof AgentHomeAccessSchema>;
 /**
  * Strict additive offer for a durable host-owned Agent. An older daemon that
  * does not advertise `agent-home-contract` skips this distinct message type
@@ -320,6 +333,7 @@ export declare const TaskOfferForAgentPayloadSchema: z.ZodObject<{
         agentId: z.ZodString;
         profileRevision: z.ZodString;
     }, z.core.$strict>;
+    homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
     requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     runtime: z.ZodOptional<z.ZodEnum<{
         claude: "claude";
@@ -385,6 +399,7 @@ export declare const TaskOfferForAgentWithEgressPayloadSchema: z.ZodObject<{
         agentId: z.ZodString;
         profileRevision: z.ZodString;
     }, z.core.$strict>;
+    homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
     requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     runtime: z.ZodOptional<z.ZodEnum<{
         claude: "claude";
@@ -487,6 +502,7 @@ export declare const TaskOfferForAgentWithEgressFreshPayloadSchema: z.ZodObject<
         agentId: z.ZodString;
         profileRevision: z.ZodString;
     }, z.core.$strict>;
+    homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
     requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     runtime: z.ZodOptional<z.ZodEnum<{
         claude: "claude";
@@ -593,6 +609,7 @@ export declare const TaskOfferPreparedPayloadSchema: z.ZodObject<{
         agentId: z.ZodString;
         profileRevision: z.ZodString;
     }, z.core.$strict>;
+    homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
     requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     runtime: z.ZodOptional<z.ZodEnum<{
         claude: "claude";
@@ -1496,6 +1513,56 @@ export declare const TerminalPreparedObservationSchema: z.ZodObject<{
     maxPromptTokens: z.ZodNumber;
 }, z.core.$strict>;
 export type TerminalPreparedObservation = z.infer<typeof TerminalPreparedObservationSchema>;
+/**
+ * The task-free Agent-home projection (`agent.home_projection`) that the
+ * device had already applied when an Agent Attempt started. The writer lease
+ * keeps a new projection out of the home until the Attempt ends, so this is
+ * the persona the Attempt ran with. The SDK does not compare it with the
+ * offer's `agentRef.profileRevision`: the host decides whether a mismatch
+ * matters. Absent when the task was not Agent-bound, or when the home had no
+ * applied projection record.
+ */
+export declare const TerminalAgentHomeProjectionSchema: z.ZodObject<{
+    profileRevision: z.ZodString;
+    projectionHash: z.ZodString;
+}, z.core.$strict>;
+export type TerminalAgentHomeProjection = z.infer<typeof TerminalAgentHomeProjectionSchema>;
+/** Maximum memory files one reader digest covers: `MEMORY.md` plus every entry under `notes/`. */
+export declare const AGENT_HOME_MEMORY_DIGEST_MAX_FILES = 256;
+/** Maximum bytes of memory files one reader digest reads. */
+export declare const AGENT_HOME_MEMORY_DIGEST_MAX_BYTES: number;
+/** Maximum length of one changed memory path, relative to the Agent home. */
+export declare const AGENT_HOME_MEMORY_PATH_MAX_LENGTH = 1024;
+/**
+ * Memory-change evidence of one `memory-reader` Attempt. The device hashes
+ * `MEMORY.md` and every file under `notes/` when the reader starts and again
+ * at its terminal, and compares the two digests.
+ *
+ * - `unchanged`: the digests are equal.
+ * - `reader-attributed`: the digests differ and no writer Attempt of the home
+ *   overlapped this reader. A reader Attempt changed memory: this one, or
+ *   another reader that overlapped it.
+ * - `unattributed`: the digests differ and a writer Attempt overlapped this
+ *   reader, so the change has no single source.
+ * - `unmeasured`: the digest bound was exceeded, or a read failed.
+ *
+ * `paths` lists the changed files relative to the home, with `/` separators.
+ * The device sees only Attempts it runs; a host that writes memory files
+ * itself while readers run makes the attribution ambiguous. Absent on writer
+ * terminals and on a claimed failure before the Attempt became active.
+ */
+export declare const TerminalAgentHomeMemoryChangeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    outcome: z.ZodLiteral<"unchanged">;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"reader-attributed">;
+    paths: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"unattributed">;
+    paths: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"unmeasured">;
+}, z.core.$strict>], "outcome">;
+export type TerminalAgentHomeMemoryChange = z.infer<typeof TerminalAgentHomeMemoryChangeSchema>;
 /**
  * daemon -> server: task finished successfully.
  *
@@ -1525,6 +1592,7 @@ export type TerminalPreparedObservation = z.infer<typeof TerminalPreparedObserva
 export declare const TaskCompletePayloadSchema: z.ZodObject<{
     harnessId: z.ZodOptional<z.ZodString>;
     summary: z.ZodString;
+    finalMessage: z.ZodOptional<z.ZodString>;
     sessionRef: z.ZodString;
     artifactRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
         blobId: z.ZodString;
@@ -1557,6 +1625,21 @@ export declare const TaskCompletePayloadSchema: z.ZodObject<{
         agentId: z.ZodString;
         profileRevision: z.ZodString;
     }, z.core.$strict>>;
+    agentHomeProjection: z.ZodOptional<z.ZodObject<{
+        profileRevision: z.ZodString;
+        projectionHash: z.ZodString;
+    }, z.core.$strict>>;
+    agentHomeMemoryChange: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        outcome: z.ZodLiteral<"unchanged">;
+    }, z.core.$strict>, z.ZodObject<{
+        outcome: z.ZodLiteral<"reader-attributed">;
+        paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        outcome: z.ZodLiteral<"unattributed">;
+        paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        outcome: z.ZodLiteral<"unmeasured">;
+    }, z.core.$strict>], "outcome">>;
 }, z.core.$strip>;
 export type TaskCompletePayload = z.infer<typeof TaskCompletePayloadSchema>;
 /** daemon -> server: task failed. */
@@ -1591,6 +1674,21 @@ export declare const TaskFailPayloadSchema: z.ZodObject<{
         agentId: z.ZodString;
         profileRevision: z.ZodString;
     }, z.core.$strict>>;
+    agentHomeProjection: z.ZodOptional<z.ZodObject<{
+        profileRevision: z.ZodString;
+        projectionHash: z.ZodString;
+    }, z.core.$strict>>;
+    agentHomeMemoryChange: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        outcome: z.ZodLiteral<"unchanged">;
+    }, z.core.$strict>, z.ZodObject<{
+        outcome: z.ZodLiteral<"reader-attributed">;
+        paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        outcome: z.ZodLiteral<"unattributed">;
+        paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        outcome: z.ZodLiteral<"unmeasured">;
+    }, z.core.$strict>], "outcome">>;
 }, z.core.$strip>;
 export type TaskFailPayload = z.infer<typeof TaskFailPayloadSchema>;
 /**
@@ -1633,6 +1731,21 @@ export declare const TaskCancelledPayloadSchema: z.ZodObject<{
         agentId: z.ZodString;
         profileRevision: z.ZodString;
     }, z.core.$strict>>;
+    agentHomeProjection: z.ZodOptional<z.ZodObject<{
+        profileRevision: z.ZodString;
+        projectionHash: z.ZodString;
+    }, z.core.$strict>>;
+    agentHomeMemoryChange: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        outcome: z.ZodLiteral<"unchanged">;
+    }, z.core.$strict>, z.ZodObject<{
+        outcome: z.ZodLiteral<"reader-attributed">;
+        paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        outcome: z.ZodLiteral<"unattributed">;
+        paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        outcome: z.ZodLiteral<"unmeasured">;
+    }, z.core.$strict>], "outcome">>;
 }, z.core.$strip>;
 export type TaskCancelledPayload = z.infer<typeof TaskCancelledPayloadSchema>;
 /**
@@ -1798,6 +1911,7 @@ declare const TASK_OFFER_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>;
+        homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
         requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         runtime: z.ZodOptional<z.ZodEnum<{
             claude: "claude";
@@ -1857,6 +1971,7 @@ declare const TASK_OFFER_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>;
+        homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
         requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         runtime: z.ZodOptional<z.ZodEnum<{
             claude: "claude";
@@ -1952,6 +2067,7 @@ declare const TASK_OFFER_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>;
+        homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
         requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         runtime: z.ZodOptional<z.ZodEnum<{
             claude: "claude";
@@ -2037,6 +2153,7 @@ declare const TASK_OFFER_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>;
+        homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
         requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         runtime: z.ZodOptional<z.ZodEnum<{
             claude: "claude";
@@ -2246,6 +2363,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>;
+        homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
         requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         runtime: z.ZodOptional<z.ZodEnum<{
             claude: "claude";
@@ -2305,6 +2423,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>;
+        homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
         requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         runtime: z.ZodOptional<z.ZodEnum<{
             claude: "claude";
@@ -2400,6 +2519,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>;
+        homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
         requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         runtime: z.ZodOptional<z.ZodEnum<{
             claude: "claude";
@@ -2485,6 +2605,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>;
+        homeAccess: z.ZodOptional<z.ZodLiteral<"memory-reader">>;
         requiredToolsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         runtime: z.ZodOptional<z.ZodEnum<{
             claude: "claude";
@@ -3091,6 +3212,7 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
     readonly 'task.complete': z.ZodObject<{
         harnessId: z.ZodOptional<z.ZodString>;
         summary: z.ZodString;
+        finalMessage: z.ZodOptional<z.ZodString>;
         sessionRef: z.ZodString;
         artifactRefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
             blobId: z.ZodString;
@@ -3123,6 +3245,21 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>>;
+        agentHomeProjection: z.ZodOptional<z.ZodObject<{
+            profileRevision: z.ZodString;
+            projectionHash: z.ZodString;
+        }, z.core.$strict>>;
+        agentHomeMemoryChange: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            outcome: z.ZodLiteral<"unchanged">;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"reader-attributed">;
+            paths: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"unattributed">;
+            paths: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"unmeasured">;
+        }, z.core.$strict>], "outcome">>;
     }, z.core.$strip>;
     readonly 'task.fail': z.ZodObject<{
         recovery: z.ZodOptional<z.ZodObject<{
@@ -3155,6 +3292,21 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>>;
+        agentHomeProjection: z.ZodOptional<z.ZodObject<{
+            profileRevision: z.ZodString;
+            projectionHash: z.ZodString;
+        }, z.core.$strict>>;
+        agentHomeMemoryChange: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            outcome: z.ZodLiteral<"unchanged">;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"reader-attributed">;
+            paths: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"unattributed">;
+            paths: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"unmeasured">;
+        }, z.core.$strict>], "outcome">>;
     }, z.core.$strip>;
     readonly 'task.cancelled': z.ZodObject<{
         harnessId: z.ZodOptional<z.ZodString>;
@@ -3177,6 +3329,21 @@ export declare const MESSAGE_PAYLOAD_SCHEMAS: {
             agentId: z.ZodString;
             profileRevision: z.ZodString;
         }, z.core.$strict>>;
+        agentHomeProjection: z.ZodOptional<z.ZodObject<{
+            profileRevision: z.ZodString;
+            projectionHash: z.ZodString;
+        }, z.core.$strict>>;
+        agentHomeMemoryChange: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            outcome: z.ZodLiteral<"unchanged">;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"reader-attributed">;
+            paths: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"unattributed">;
+            paths: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"unmeasured">;
+        }, z.core.$strict>], "outcome">>;
     }, z.core.$strip>;
     readonly 'task.approval_resolved': z.ZodObject<{
         approvalId: z.ZodString;

package/dist/version.d.ts

@@ -37,6 +37,14 @@ export declare const MAILBOX_READ_AHEAD_CAPABILITY = "mailbox-read-ahead";
 export declare const PROTOCOL_VERSION = 2;
 /** Host declares that this device accepts only Agent-bound offer variants. */
 export declare const STRICT_AGENT_ONLY_CAPABILITY: 'strict-agent-only';
+/**
+ * The device runs `homeAccess: 'memory-reader'` Agent offers: each reader
+ * Attempt gets its own run directory under the Agent home, and readers are
+ * counted apart from the one writer. The Agent offers are strict, so a host
+ * must refuse a reader offer to a device without this flag before it creates
+ * the task.
+ */
+export declare const AGENT_HOME_READERS_CAPABILITY: 'agent-home-readers';
 /**
  * Capability flags exchanged during the connection handshake (`conn.hello` /
  * `conn.ack`). Additional flags may be introduced without a protocol version
@@ -116,5 +124,5 @@ export declare const STRICT_AGENT_ONLY_CAPABILITY: 'strict-agent-only';
  * cannot accidentally execute the instruction without the required tools.
  */
 export declare const CUSTOM_HARNESS_CAPABILITY: 'custom-harness';
-export declare const CAPABILITY_FLAGS: readonly ['steer', 'blob-upload', 'interactive-approval', 'approval_resolved', 'approval-targeting', 'result-document', 'dispatch-selection', "provider-profile-binding", 'toolset-selection', 'agent-home-contract', "strict-agent-only", "agent-egress-policy", "agent-egress-reliable-ack", "agent-message-egress", "agent-egress-fresh-session", "agent-content-workspace-read", "agent-content-transcript-read", "agent-content-artifact-read", "agent-home-projection", "agent-input-preparation-v9", "terminal-projection-selection", "host-mcp-task-context", "custom-harness", "mailbox-read-ahead", "provider-provisioning.v1", "agent-memory-intent.v1"];
+export declare const CAPABILITY_FLAGS: readonly ['steer', 'blob-upload', 'interactive-approval', 'approval_resolved', 'approval-targeting', 'result-document', 'dispatch-selection', "provider-profile-binding", 'toolset-selection', 'agent-home-contract', "agent-home-readers", "strict-agent-only", "agent-egress-policy", "agent-egress-reliable-ack", "agent-message-egress", "agent-egress-fresh-session", "agent-content-workspace-read", "agent-content-transcript-read", "agent-content-artifact-read", "agent-home-projection", "agent-input-preparation-v9", "terminal-projection-selection", "host-mcp-task-context", "custom-harness", "mailbox-read-ahead", "provider-provisioning.v1", "agent-memory-intent.v1"];
 export type CapabilityFlag = (typeof CAPABILITY_FLAGS)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/protocol",
-  "version": "0.25.0",
+  "version": "0.26.0-rc.1",
   "description": "BYOK SDK wire protocol: envelope schema, message types, and codec helpers",
   "type": "module",
   "license": "MIT",