@chipschat/protocol 0.0.0-stage → 1.0.0

package/dist/src/context-files.d.ts

@@ -0,0 +1,304 @@
+/**
+ * An agent's context (ADR 0134): the files its harness builds it from at every turn, apart from
+ * the room — who it is, how it works, what it knows of the person it serves — listed in Chips and
+ * edited there, in the harness's own files.
+ *
+ * Chips adds no context of its own and knows nothing of any harness's files. A harness that
+ * declares `context_files` sends a copy of each agent's set, and of its own (what its agents share,
+ * and what a new agent starts with), and keeps them current; each file says what it is called,
+ * what its row says, whether it may be edited, and whether the agent reads a shared one instead of
+ * its own. A person's edit goes down the harness's socket as a `context.edit` frame, and is done
+ * when the harness sends its copy back answering it, or refused when the file changed under it.
+ *
+ * At most eight files are shown: a harness names the rest in `not_shown`, and the page says Chips
+ * does not show them. A file over 64 KB is named there too. Neither is lost in silence: a ninth
+ * file, or a larger text, is refused.
+ *
+ * The copies live in a registry, not the log: what a person wrote about themselves is not
+ * replayed to every device, and an edit is never sent to a harness twice.
+ */
+import { z } from "zod";
+/** The most files an agent's page, or a harness's, shows. The rest are named in `not_shown`. */
+export declare const CONTEXT_FILES_SHOWN = 8;
+/** The most a file's text may hold, in UTF-8 bytes. A larger one is named in `not_shown`. */
+export declare const CONTEXT_FILE_BYTES = 65536;
+/** The most files `not_shown` names. */
+export declare const CONTEXT_NOT_SHOWN_MAX = 64;
+/**
+ * How long an edit waits for its harness's answer: the minute a fork or a new agent has. After it
+ * the edit is missed, and the person is told the harness hasn't answered; an answer after it still
+ * counts.
+ */
+export declare const CONTEXT_EDIT_WAIT_MS = 60000;
+/** The code an edit is refused with when the file changed after the person opened it. */
+export declare const STALE_CONTEXT = "stale_context";
+/**
+ * What a file is for, so the same kind of file wears the same mark on every harness. The one word
+ * list harnesses share; it picks a row's mark and nothing else.
+ */
+export declare const CONTEXT_ROLES: readonly ["identity", "instructions", "about_you", "memory", "other"];
+export declare const contextRole: z.ZodEnum<{
+    memory: "memory";
+    other: "other";
+    identity: "identity";
+    instructions: "instructions";
+    about_you: "about_you";
+}>;
+export type ContextRole = z.infer<typeof contextRole>;
+/** The size of a text in UTF-8 bytes. */
+export declare function contextBytes(text: string): number;
+export declare const contextFile: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodString;
+    about: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<{
+        memory: "memory";
+        other: "other";
+        identity: "identity";
+        instructions: "instructions";
+        about_you: "about_you";
+    }>>;
+    text: z.ZodOptional<z.ZodString>;
+    hash: z.ZodOptional<z.ZodString>;
+    editable: z.ZodBoolean;
+    why_read_only: z.ZodOptional<z.ZodString>;
+    shared: z.ZodOptional<z.ZodString>;
+    replaceable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ContextFile = z.infer<typeof contextFile>;
+export declare const sharedContextFile: z.ZodObject<{
+    id: z.ZodString;
+    used_by: z.ZodOptional<z.ZodInt>;
+    for_new_agents: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodString;
+    title: z.ZodString;
+    about: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<{
+        memory: "memory";
+        other: "other";
+        identity: "identity";
+        instructions: "instructions";
+        about_you: "about_you";
+    }>>;
+    text: z.ZodOptional<z.ZodString>;
+    hash: z.ZodOptional<z.ZodString>;
+    editable: z.ZodBoolean;
+    why_read_only: z.ZodOptional<z.ZodString>;
+    shared: z.ZodOptional<z.ZodString>;
+    replaceable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SharedContextFile = z.infer<typeof sharedContextFile>;
+export declare const notShownFile: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    reason: z.ZodEnum<{
+        count: "count";
+        too_large: "too_large";
+    }>;
+}, z.core.$strip>;
+export type NotShownFile = z.infer<typeof notShownFile>;
+export declare const contextAnswer: {
+    answers: z.ZodOptional<z.ZodString>;
+    refuses: z.ZodOptional<z.ZodObject<{
+        edit_id: z.ZodString;
+        reason: z.ZodEnum<{
+            failed: "failed";
+            changed: "changed";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+};
+export declare const agentContextPut: z.ZodObject<{
+    answers: z.ZodOptional<z.ZodString>;
+    refuses: z.ZodOptional<z.ZodObject<{
+        edit_id: z.ZodString;
+        reason: z.ZodEnum<{
+            failed: "failed";
+            changed: "changed";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    files: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodString;
+        about: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodEnum<{
+            memory: "memory";
+            other: "other";
+            identity: "identity";
+            instructions: "instructions";
+            about_you: "about_you";
+        }>>;
+        text: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+        editable: z.ZodBoolean;
+        why_read_only: z.ZodOptional<z.ZodString>;
+        shared: z.ZodOptional<z.ZodString>;
+        replaceable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    not_shown: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        reason: z.ZodEnum<{
+            count: "count";
+            too_large: "too_large";
+        }>;
+    }, z.core.$strip>>>;
+    read_note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentContextPut = z.infer<typeof agentContextPut>;
+export declare const harnessContextPut: z.ZodObject<{
+    answers: z.ZodOptional<z.ZodString>;
+    refuses: z.ZodOptional<z.ZodObject<{
+        edit_id: z.ZodString;
+        reason: z.ZodEnum<{
+            failed: "failed";
+            changed: "changed";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    shared: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        used_by: z.ZodOptional<z.ZodInt>;
+        for_new_agents: z.ZodOptional<z.ZodBoolean>;
+        name: z.ZodString;
+        title: z.ZodString;
+        about: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodEnum<{
+            memory: "memory";
+            other: "other";
+            identity: "identity";
+            instructions: "instructions";
+            about_you: "about_you";
+        }>>;
+        text: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+        editable: z.ZodBoolean;
+        why_read_only: z.ZodOptional<z.ZodString>;
+        shared: z.ZodOptional<z.ZodString>;
+        replaceable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    not_shown: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        reason: z.ZodEnum<{
+            count: "count";
+            too_large: "too_large";
+        }>;
+    }, z.core.$strip>>>;
+    new_agents_note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HarnessContextPut = z.infer<typeof harnessContextPut>;
+export declare const contextEditAsk: z.ZodObject<{
+    name: z.ZodString;
+    text: z.ZodString;
+    base_hash: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ContextEditAsk = z.infer<typeof contextEditAsk>;
+export declare const CONTEXT_EDIT_STATES: readonly ["waiting", "saved", "changed", "failed", "missed"];
+export declare const contextEditState: z.ZodEnum<{
+    waiting: "waiting";
+    saved: "saved";
+    failed: "failed";
+    missed: "missed";
+    changed: "changed";
+}>;
+export type ContextEditState = z.infer<typeof contextEditState>;
+export declare const contextEditView: z.ZodObject<{
+    edit_id: z.ZodString;
+    name: z.ZodString;
+    state: z.ZodEnum<{
+        waiting: "waiting";
+        saved: "saved";
+        failed: "failed";
+        missed: "missed";
+        changed: "changed";
+    }>;
+    asked_at: z.ZodISODateTime;
+    answered_at: z.ZodOptional<z.ZodISODateTime>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ContextEditView = z.infer<typeof contextEditView>;
+export declare const agentContextView: z.ZodObject<{
+    agent_id: z.ZodString;
+    harness_id: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodString;
+        about: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodEnum<{
+            memory: "memory";
+            other: "other";
+            identity: "identity";
+            instructions: "instructions";
+            about_you: "about_you";
+        }>>;
+        text: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+        editable: z.ZodBoolean;
+        why_read_only: z.ZodOptional<z.ZodString>;
+        shared: z.ZodOptional<z.ZodString>;
+        replaceable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    not_shown: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        reason: z.ZodEnum<{
+            count: "count";
+            too_large: "too_large";
+        }>;
+    }, z.core.$strip>>;
+    read_note: z.ZodOptional<z.ZodString>;
+    read_at: z.ZodISODateTime;
+    away: z.ZodBoolean;
+}, z.core.$strip>;
+export type AgentContextView = z.infer<typeof agentContextView>;
+export declare const harnessContextView: z.ZodObject<{
+    harness_id: z.ZodString;
+    shared: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        used_by: z.ZodOptional<z.ZodInt>;
+        for_new_agents: z.ZodOptional<z.ZodBoolean>;
+        name: z.ZodString;
+        title: z.ZodString;
+        about: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodEnum<{
+            memory: "memory";
+            other: "other";
+            identity: "identity";
+            instructions: "instructions";
+            about_you: "about_you";
+        }>>;
+        text: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+        editable: z.ZodBoolean;
+        why_read_only: z.ZodOptional<z.ZodString>;
+        shared: z.ZodOptional<z.ZodString>;
+        replaceable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    not_shown: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        reason: z.ZodEnum<{
+            count: "count";
+            too_large: "too_large";
+        }>;
+    }, z.core.$strip>>;
+    new_agents_note: z.ZodOptional<z.ZodString>;
+    read_at: z.ZodISODateTime;
+    away: z.ZodBoolean;
+}, z.core.$strip>;
+export type HarnessContextView = z.infer<typeof harnessContextView>;
+export declare const contextEditFrame: z.ZodObject<{
+    frame: z.ZodLiteral<"context.edit">;
+    edit_id: z.ZodString;
+    harness_id: z.ZodString;
+    agent_id: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    text: z.ZodString;
+    base_hash: z.ZodNullable<z.ZodString>;
+    asked_by: z.ZodString;
+    asked_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ContextEditFrame = z.infer<typeof contextEditFrame>;
+//# sourceMappingURL=context-files.d.ts.map

package/dist/src/context-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-files.d.ts","sourceRoot":"","sources":["../../src/context-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,gGAAgG;AAChG,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,wCAAwC;AACxC,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,yFAAyF;AACzF,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,aAAa,uEAAwE,CAAC;AACnG,eAAO,MAAM,WAAW;;;;;;EAAwB,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAmBtD,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AA0CD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;iBAQ2D,CAAC;AACpF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;iBAsB3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,YAAY;;;;;;;iBAM+C,CAAC;AACzE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,eAAO,MAAM,aAAa;;;;;;;;;;CAczB,CAAC;AAmBF,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW8D,CAAC;AAC3F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkBkD,CAAC;AACjF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,cAAc;;;;iBAY8D,CAAC;AAC1F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB,8DAA+D,CAAC;AAChG,eAAO,MAAM,gBAAgB;;;;;;EAA8B,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,eAAe;;;;;;;;;;;;;iBAWgD,CAAC;AAC7E,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUwC,CAAC;AACtE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBASyC,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,eAAO,MAAM,gBAAgB;;;;;;;;;;iBAgB1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/src/context-files.js

@@ -0,0 +1,247 @@
+/**
+ * An agent's context (ADR 0134): the files its harness builds it from at every turn, apart from
+ * the room — who it is, how it works, what it knows of the person it serves — listed in Chips and
+ * edited there, in the harness's own files.
+ *
+ * Chips adds no context of its own and knows nothing of any harness's files. A harness that
+ * declares `context_files` sends a copy of each agent's set, and of its own (what its agents share,
+ * and what a new agent starts with), and keeps them current; each file says what it is called,
+ * what its row says, whether it may be edited, and whether the agent reads a shared one instead of
+ * its own. A person's edit goes down the harness's socket as a `context.edit` frame, and is done
+ * when the harness sends its copy back answering it, or refused when the file changed under it.
+ *
+ * At most eight files are shown: a harness names the rest in `not_shown`, and the page says Chips
+ * does not show them. A file over 64 KB is named there too. Neither is lost in silence: a ninth
+ * file, or a larger text, is refused.
+ *
+ * The copies live in a registry, not the log: what a person wrote about themselves is not
+ * replayed to every device, and an edit is never sent to a harness twice.
+ */
+import { z } from "zod";
+import { id, isoTimestamp } from "./primitives.js";
+/** The most files an agent's page, or a harness's, shows. The rest are named in `not_shown`. */
+export const CONTEXT_FILES_SHOWN = 8;
+/** The most a file's text may hold, in UTF-8 bytes. A larger one is named in `not_shown`. */
+export const CONTEXT_FILE_BYTES = 65_536;
+/** The most files `not_shown` names. */
+export const CONTEXT_NOT_SHOWN_MAX = 64;
+/**
+ * How long an edit waits for its harness's answer: the minute a fork or a new agent has. After it
+ * the edit is missed, and the person is told the harness hasn't answered; an answer after it still
+ * counts.
+ */
+export const CONTEXT_EDIT_WAIT_MS = 60_000;
+/** The code an edit is refused with when the file changed after the person opened it. */
+export const STALE_CONTEXT = "stale_context";
+/**
+ * What a file is for, so the same kind of file wears the same mark on every harness. The one word
+ * list harnesses share; it picks a row's mark and nothing else.
+ */
+export const CONTEXT_ROLES = ["identity", "instructions", "about_you", "memory", "other"];
+export const contextRole = z.enum(CONTEXT_ROLES);
+/**
+ * A file's own name, one path segment (SEC-14): no slash either way, no NUL, not `.` or `..`. A
+ * harness writes a person's edit to the file the edit names, under the agent's folder; a name that
+ * climbed out of it would write wherever a stranger's server, or a man in the middle on the plain
+ * network link, cared to say. Every name a file is written under is one of these; a file that is
+ * only named as not shown may be called anything, since nothing is written under it.
+ */
+const ONE_SEGMENT = /^(?!\.{1,2}$)[^/\\\0]+$/;
+const fileName = z
+    .string()
+    .min(1)
+    .max(255)
+    .regex(ONE_SEGMENT, "a file's own name: one segment, no slash, not `.` or `..`");
+const shownName = z.string().min(1).max(255);
+const title = z.string().min(1).max(80);
+const hash = z.string().min(1).max(128);
+/** The size of a text in UTF-8 bytes. */
+export function contextBytes(text) {
+    return new TextEncoder().encode(text).length;
+}
+const fileFields = {
+    name: fileName.describe("Its own name, shown small under the title: `PERSONA.md`."),
+    title: title.describe("What its row says, in the harness's words: `Who it is`."),
+    about: z.string().max(200).optional().describe("The row's line. Absent: the text's first line."),
+    role: contextRole.optional().describe("What it is for, which picks its mark. Absent: `other`."),
+    text: z
+        .string()
+        .optional()
+        .describe("Its text. Absent only for a file the agent reads from its harness's set (`shared`)."),
+    hash: hash
+        .optional()
+        .describe("The harness's own hash of `text`, which an edit names as what it was made from."),
+    editable: z.boolean().describe("Whether a person may change it from Chips."),
+    why_read_only: z
+        .string()
+        .max(120)
+        .optional()
+        .describe("Why it may not be, in the harness's words: `Built into Lathe`."),
+    shared: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("The `id` of a file in the harness's own set that this agent reads instead of a file of its own."),
+    replaceable: z
+        .boolean()
+        .optional()
+        .describe("For a `shared` file: whether the agent may be given its own, begun from the shared text."),
+};
+function textFits(file) {
+    return file.text === undefined || contextBytes(file.text) <= CONTEXT_FILE_BYTES;
+}
+export const contextFile = z
+    .object(fileFields)
+    .refine((file) => file.text !== undefined || file.shared !== undefined, {
+    message: "A file has its text, or names the shared file the agent reads.",
+})
+    .refine(textFits, {
+    message: "A file's text is 64 KB at most: name a larger one in `not_shown`.",
+})
+    .describe("One file an agent is built from, as its harness names it (ADR 0134).");
+export const sharedContextFile = z
+    .object({
+    ...fileFields,
+    id: z.string().min(1).max(64).describe("What an agent's file names in `shared`."),
+    used_by: z
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("How many of its agents read it, `0` when none does now. Left out: no agent reads it, and each new agent is given a copy of its own (`for_new_agents`)."),
+    for_new_agents: z
+        .boolean()
+        .optional()
+        .describe("Whether a new agent starts with it, or with a copy of it."),
+})
+    .refine((file) => file.text !== undefined, { message: "A shared file has its text." })
+    .refine(textFits, {
+    message: "A file's text is 64 KB at most: name a larger one in `not_shown`.",
+})
+    .describe("One file of a harness's own set: read by several of its agents, or copied into a new one (ADR 0134).");
+export const notShownFile = z
+    .object({
+    name: shownName,
+    title: title.optional(),
+    reason: z.enum(["count", "too_large"]).describe("Past the eighth, or over 64 KB."),
+})
+    .describe("A file the agent has that Chips does not show (ADR 0134).");
+export const contextAnswer = {
+    answers: id("edit")
+        .optional()
+        .describe("The edit this copy answers: saved, and this is the file as it is now."),
+    refuses: z
+        .object({
+        edit_id: id("edit"),
+        reason: z
+            .enum(["changed", "failed"])
+            .describe("`changed`: the file was changed since the edit's version. `failed`: otherwise."),
+        message: z.string().min(1).max(300).optional().describe("What went wrong, for the person."),
+    })
+        .optional()
+        .describe("An edit not made. The copy beside it is the file as it is now."),
+};
+/**
+ * When the agent reads its files, in its harness's words, for the foot under them on its page (ADR
+ * 0238): a harness that reads them only when a conversation starts says so, and what a change
+ * waits for. Absent: Chips says the harness gives them at the start of every turn.
+ */
+const readNote = z
+    .string()
+    .min(1)
+    .max(300)
+    .describe("When the agent reads these, in the harness's words: `Hermes reads these when a conversation starts.` Absent: at the start of every turn.");
+function uniqueNames(files) {
+    return new Set(files.map((file) => file.name)).size === files.length;
+}
+export const agentContextPut = z
+    .object({
+    files: z
+        .array(contextFile)
+        .max(CONTEXT_FILES_SHOWN)
+        .refine(uniqueNames, { message: "Each file is named once." })
+        .describe("The agent's files, in the order its page shows them: eight at most."),
+    not_shown: z.array(notShownFile).max(CONTEXT_NOT_SHOWN_MAX).optional(),
+    read_note: readNote.optional(),
+    ...contextAnswer,
+})
+    .describe("`PUT /v1/agents/:id/context`: a harness's copy of one of its agents' files.");
+export const harnessContextPut = z
+    .object({
+    shared: z
+        .array(sharedContextFile)
+        .max(CONTEXT_FILES_SHOWN)
+        .refine(uniqueNames, { message: "Each file is named once." })
+        .refine((files) => new Set(files.map((file) => file.id)).size === files.length, {
+        message: "Each shared file has its own id.",
+    }),
+    not_shown: z.array(notShownFile).max(CONTEXT_NOT_SHOWN_MAX).optional(),
+    new_agents_note: z
+        .string()
+        .min(1)
+        .max(300)
+        .optional()
+        .describe("What else a new agent starts with, in the harness's words, for its page."),
+    ...contextAnswer,
+})
+    .describe("`PUT /v1/harnesses/:id/context`: a harness's copy of its own set.");
+export const contextEditAsk = z
+    .object({
+    name: fileName.describe("The file to change."),
+    text: z.string().refine((text) => contextBytes(text) <= CONTEXT_FILE_BYTES, {
+        message: "A file's text is 64 KB at most.",
+    }),
+    base_hash: hash
+        .nullable()
+        .describe("The version the person changed, as the copy they read said. `null` to give the agent its own of a shared file."),
+})
+    .describe("`POST /v1/agents/:id/context/edits` and `/v1/harnesses/:id/context/edits`.");
+export const CONTEXT_EDIT_STATES = ["waiting", "saved", "changed", "failed", "missed"];
+export const contextEditState = z.enum(CONTEXT_EDIT_STATES);
+export const contextEditView = z
+    .object({
+    edit_id: id("edit"),
+    name: fileName,
+    state: contextEditState.describe("`missed` once `CONTEXT_EDIT_WAIT_MS` has passed with no answer; read, never stored."),
+    asked_at: isoTimestamp,
+    answered_at: isoTimestamp.optional(),
+    message: z.string().max(300).optional().describe("The harness's words, for a failure."),
+})
+    .describe("An edit a person asked for, and what became of it (ADR 0134).");
+export const agentContextView = z
+    .object({
+    agent_id: id("agent"),
+    harness_id: id("harness"),
+    files: z.array(contextFile),
+    not_shown: z.array(notShownFile),
+    read_note: readNote.optional(),
+    read_at: isoTimestamp.describe("When the harness last sent its copy."),
+    away: z.boolean().describe("No socket of the harness hears edits now: read, but not saved."),
+})
+    .describe("`GET /v1/agents/:id/context`, for the harness's owner.");
+export const harnessContextView = z
+    .object({
+    harness_id: id("harness"),
+    shared: z.array(sharedContextFile),
+    not_shown: z.array(notShownFile),
+    new_agents_note: z.string().optional(),
+    read_at: isoTimestamp,
+    away: z.boolean(),
+})
+    .describe("`GET /v1/harnesses/:id/context`, for the harness's owner.");
+export const contextEditFrame = z
+    .object({
+    frame: z.literal("context.edit"),
+    edit_id: id("edit"),
+    harness_id: id("harness"),
+    agent_id: id("agent")
+        .optional()
+        .describe("The agent whose file it is; absent for the harness's own."),
+    name: fileName,
+    text: z.string(),
+    base_hash: hash.nullable().describe("`null`: make the agent its own, from the shared file."),
+    asked_by: id("person"),
+    asked_at: isoTimestamp,
+})
+    .describe("A person changed a context file (ADR 0134). Sent to a harness's socket that said `context` in its `hello`, now or never: it is not in the log. The harness answers with its copy, `answers` or `refuses` naming `edit_id`.");
+//# sourceMappingURL=context-files.js.map

package/dist/src/context-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-files.js","sourceRoot":"","sources":["../../src/context-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEnD,gGAAgG;AAChG,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,6FAA6F;AAC7F,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AACzC,wCAAwC;AACxC,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AACxC;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAC3C,yFAAyF;AACzF,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC;AACnG,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAGjD;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,yBAAyB,CAAC;AAC9C,MAAM,QAAQ,GAAG,CAAC;KACf,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,KAAK,CAAC,WAAW,EAAE,2DAA2D,CAAC,CAAC;AACnF,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC7C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACxC,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAExC,yCAAyC;AACzC,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,GAAG;IACjB,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,0DAA0D,CAAC;IACnF,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,yDAAyD,CAAC;IAChF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;IAChG,IAAI,EAAE,WAAW,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;IAC/F,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,qFAAqF,CACtF;IACH,IAAI,EAAE,IAAI;SACP,QAAQ,EAAE;SACV,QAAQ,CAAC,iFAAiF,CAAC;IAC9F,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IAC5E,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,gEAAgE,CAAC;IAC7E,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,EAAE;SACV,QAAQ,CACP,iGAAiG,CAClG;IACH,WAAW,EAAE,CAAC;SACX,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CACP,0FAA0F,CAC3F;CACJ,CAAC;AAEF,SAAS,QAAQ,CAAC,IAA4C;IAC5D,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,kBAAkB,CAAC;AAClF,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC;KACzB,MAAM,CAAC,UAAU,CAAC;KAClB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE;IACtE,OAAO,EAAE,gEAAgE;CAC1E,CAAC;KACD,MAAM,CAAC,QAAQ,EAAE;IAChB,OAAO,EAAE,mEAAmE;CAC7E,CAAC;KACD,QAAQ,CAAC,sEAAsE,CAAC,CAAC;AAGpF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,CAAC;IACN,GAAG,UAAU;IACb,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,yCAAyC,CAAC;IACjF,OAAO,EAAE,CAAC;SACP,GAAG,EAAE;SACL,WAAW,EAAE;SACb,QAAQ,EAAE;SACV,QAAQ,CACP,wJAAwJ,CACzJ;IACH,cAAc,EAAE,CAAC;SACd,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CAAC,2DAA2D,CAAC;CACzE,CAAC;KACD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAAC;KACrF,MAAM,CAAC,QAAQ,EAAE;IAChB,OAAO,EAAE,mEAAmE;CAC7E,CAAC;KACD,QAAQ,CACP,sGAAsG,CACvG,CAAC;AAGJ,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC;KAC1B,MAAM,CAAC;IACN,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE;IACvB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,iCAAiC,CAAC;CACnF,CAAC;KACD,QAAQ,CAAC,2DAA2D,CAAC,CAAC;AAGzE,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC;SAChB,QAAQ,EAAE;SACV,QAAQ,CAAC,uEAAuE,CAAC;IACpF,OAAO,EAAE,CAAC;SACP,MAAM,CAAC;QACN,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC;QACnB,MAAM,EAAE,CAAC;aACN,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;aAC3B,QAAQ,CAAC,gFAAgF,CAAC;QAC7F,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;KAC5F,CAAC;SACD,QAAQ,EAAE;SACV,QAAQ,CAAC,gEAAgE,CAAC;CAC9E,CAAC;AAEF;;;;GAIG;AACH,MAAM,QAAQ,GAAG,CAAC;KACf,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,CACP,0IAA0I,CAC3I,CAAC;AAEJ,SAAS,WAAW,CAAC,KAA2C;IAC9D,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,MAAM,CAAC;AACvE,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,CAAC;IACN,KAAK,EAAE,CAAC;SACL,KAAK,CAAC,WAAW,CAAC;SAClB,GAAG,CAAC,mBAAmB,CAAC;SACxB,MAAM,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC;SAC5D,QAAQ,CAAC,qEAAqE,CAAC;IAClF,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,QAAQ,EAAE;IACtE,SAAS,EAAE,QAAQ,CAAC,QAAQ,EAAE;IAC9B,GAAG,aAAa;CACjB,CAAC;KACD,QAAQ,CAAC,6EAA6E,CAAC,CAAC;AAG3F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC;KAC/B,MAAM,CAAC;IACN,MAAM,EAAE,CAAC;SACN,KAAK,CAAC,iBAAiB,CAAC;SACxB,GAAG,CAAC,mBAAmB,CAAC;SACxB,MAAM,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC;SAC5D,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,MAAM,EAAE;QAC9E,OAAO,EAAE,kCAAkC;KAC5C,CAAC;IACJ,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,QAAQ,EAAE;IACtE,eAAe,EAAE,CAAC;SACf,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,0EAA0E,CAAC;IACvF,GAAG,aAAa;CACjB,CAAC;KACD,QAAQ,CAAC,mEAAmE,CAAC,CAAC;AAGjF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,CAAC;IACN,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,kBAAkB,EAAE;QAC1E,OAAO,EAAE,iCAAiC;KAC3C,CAAC;IACF,SAAS,EAAE,IAAI;SACZ,QAAQ,EAAE;SACV,QAAQ,CACP,gHAAgH,CACjH;CACJ,CAAC;KACD,QAAQ,CAAC,4EAA4E,CAAC,CAAC;AAG1F,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAChG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;AAG5D,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,CAAC;IACN,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC;IACnB,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,gBAAgB,CAAC,QAAQ,CAC9B,qFAAqF,CACtF;IACD,QAAQ,EAAE,YAAY;IACtB,WAAW,EAAE,YAAY,CAAC,QAAQ,EAAE;IACpC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;CACxF,CAAC;KACD,QAAQ,CAAC,+DAA+D,CAAC,CAAC;AAG7E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,CAAC;IACN,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC;IACrB,UAAU,EAAE,EAAE,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;IAC3B,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC;IAChC,SAAS,EAAE,QAAQ,CAAC,QAAQ,EAAE;IAC9B,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IACtE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,gEAAgE,CAAC;CAC7F,CAAC;KACD,QAAQ,CAAC,wDAAwD,CAAC,CAAC;AAGtE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,UAAU,EAAE,EAAE,CAAC,SAAS,CAAC;IACzB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC;IAClC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC;IAChC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACtC,OAAO,EAAE,YAAY;IACrB,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;CAClB,CAAC;KACD,QAAQ,CAAC,2DAA2D,CAAC,CAAC;AAGzE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC;IAChC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC;IACnB,UAAU,EAAE,EAAE,CAAC,SAAS,CAAC;IACzB,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC;SAClB,QAAQ,EAAE;SACV,QAAQ,CAAC,2DAA2D,CAAC;IACxE,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,SAAS,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;IAC5F,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC;IACtB,QAAQ,EAAE,YAAY;CACvB,CAAC;KACD,QAAQ,CACP,4NAA4N,CAC7N,CAAC"}