@chipschat/protocol 0.0.0-stage → 1.0.1

package/dist/src/agent-context-windows.d.ts

@@ -0,0 +1,235 @@
+/**
+ * An agent's context window (ADR 0146): how full it is, a person's Compact now, and the limit it
+ * compacts itself at, shown and changed on the agent's page in Chips and kept by its harness.
+ *
+ * Nothing about a context window is Chips'. A harness that declares `context_windows` sends a copy
+ * of each agent's: how many tokens it holds and its model's window, whether it is compacting, when
+ * it last compacted and from how much to how much, whether it takes a Compact now, and the limit it
+ * compacts itself at with the limits a person may pick, and how full its last long turn got.
+ * Chips puts the numbers into words itself.
+ *
+ * A person asks two things of it, each going down the harness's socket and answered by its next
+ * copy, as a model's change is (ADR 0140): Compact now, as `context_window.compact`, answered when
+ * the harness takes it on and done when a copy says it compacted since; and a new limit, as
+ * `context_window.change`. The copies live in a registry, not the log, one row per agent with the
+ * last of each ask beside it. When a copy says the agent compacted, Chips writes a quiet line in
+ * its room, `context.compacted`.
+ */
+import { z } from "zod";
+/** The most limits an agent's copy offers. */
+export declare const WINDOW_LIMIT_CHOICES_MAX = 12;
+/**
+ * How long either ask waits for its harness's answer: the minute a model's change has. After it
+ * the ask is missed, and the person is told the harness hasn't answered; an answer after it still
+ * counts, and a new ask may be made.
+ */
+export declare const WINDOW_ASK_WAIT_MS = 60000;
+export declare const COMPACTED_BY: readonly ["asked", "itself"];
+export declare const lastCompaction: z.ZodObject<{
+    at: z.ZodISODateTime;
+    from: z.ZodInt;
+    to: z.ZodInt;
+    by: z.ZodEnum<{
+        asked: "asked";
+        itself: "itself";
+    }>;
+}, z.core.$strip>;
+export type LastCompaction = z.infer<typeof lastCompaction>;
+/** How many times a long turn may say it compacted itself, at most. */
+export declare const LONG_TURN_FOLDS_MAX = 1000;
+export declare const longTurn: z.ZodObject<{
+    at: z.ZodISODateTime;
+    peak: z.ZodInt;
+    folds: z.ZodInt;
+}, z.core.$strip>;
+export type LongTurn = z.infer<typeof longTurn>;
+export declare const windowLimit: z.ZodObject<{
+    at: z.ZodNullable<z.ZodInt>;
+    choices: z.ZodArray<z.ZodInt>;
+    default: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
+    may_turn_off: z.ZodBoolean;
+}, z.core.$strip>;
+export type WindowLimit = z.infer<typeof windowLimit>;
+export declare const agentContextWindowPut: z.ZodObject<{
+    answers: z.ZodOptional<z.ZodString>;
+    refuses: z.ZodOptional<z.ZodObject<{
+        change_id: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    used: z.ZodInt;
+    window: z.ZodInt;
+    model: z.ZodOptional<z.ZodString>;
+    as_of: z.ZodISODateTime;
+    compacting: z.ZodOptional<z.ZodEnum<{
+        queued: "queued";
+        running: "running";
+    }>>;
+    last: z.ZodOptional<z.ZodObject<{
+        at: z.ZodISODateTime;
+        from: z.ZodInt;
+        to: z.ZodInt;
+        by: z.ZodEnum<{
+            asked: "asked";
+            itself: "itself";
+        }>;
+    }, z.core.$strip>>;
+    long_turn: z.ZodOptional<z.ZodObject<{
+        at: z.ZodISODateTime;
+        peak: z.ZodInt;
+        folds: z.ZodInt;
+    }, z.core.$strip>>;
+    compacts: z.ZodBoolean;
+    why_not: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodObject<{
+        at: z.ZodNullable<z.ZodInt>;
+        choices: z.ZodArray<z.ZodInt>;
+        default: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
+        may_turn_off: z.ZodBoolean;
+    }, z.core.$strip>>;
+    editable: z.ZodBoolean;
+    why_read_only: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentContextWindowPut = z.infer<typeof agentContextWindowPut>;
+/** The copy as Chips keeps it: what the harness sent, without what it answered. */
+export type AgentContextWindowCopy = Omit<AgentContextWindowPut, "answers" | "refuses">;
+export declare const windowLimitAsk: z.ZodObject<{
+    at: z.ZodNullable<z.ZodInt>;
+}, z.core.$strip>;
+export type WindowLimitAsk = z.infer<typeof windowLimitAsk>;
+export declare const WINDOW_CHANGE_STATES: readonly ["waiting", "saved", "failed", "missed"];
+export declare const windowChangeState: z.ZodEnum<{
+    waiting: "waiting";
+    saved: "saved";
+    failed: "failed";
+    missed: "missed";
+}>;
+export type WindowChangeState = z.infer<typeof windowChangeState>;
+export declare const windowChangeView: z.ZodObject<{
+    change_id: z.ZodString;
+    state: z.ZodEnum<{
+        waiting: "waiting";
+        saved: "saved";
+        failed: "failed";
+        missed: "missed";
+    }>;
+    at: z.ZodNullable<z.ZodInt>;
+    asked_at: z.ZodISODateTime;
+    answered_at: z.ZodOptional<z.ZodISODateTime>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WindowChangeView = z.infer<typeof windowChangeView>;
+/**
+ * What became of a Compact now: `waiting` for the harness; `taken`, answered and under way;
+ * `done`, a copy says it compacted since or stopped compacting; `failed`, refused; `missed`, no
+ * answer within `WINDOW_ASK_WAIT_MS`.
+ */
+export declare const COMPACTION_STATES: readonly ["waiting", "taken", "done", "failed", "missed"];
+export declare const compactionState: z.ZodEnum<{
+    waiting: "waiting";
+    failed: "failed";
+    missed: "missed";
+    taken: "taken";
+    done: "done";
+}>;
+export type CompactionState = z.infer<typeof compactionState>;
+export declare const compactionView: z.ZodObject<{
+    change_id: z.ZodString;
+    state: z.ZodEnum<{
+        waiting: "waiting";
+        failed: "failed";
+        missed: "missed";
+        taken: "taken";
+        done: "done";
+    }>;
+    asked_at: z.ZodISODateTime;
+    answered_at: z.ZodOptional<z.ZodISODateTime>;
+    done_at: z.ZodOptional<z.ZodISODateTime>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CompactionView = z.infer<typeof compactionView>;
+export declare const agentContextWindowView: z.ZodObject<{
+    read_at: z.ZodISODateTime;
+    away: z.ZodBoolean;
+    change: z.ZodOptional<z.ZodObject<{
+        change_id: z.ZodString;
+        state: z.ZodEnum<{
+            waiting: "waiting";
+            saved: "saved";
+            failed: "failed";
+            missed: "missed";
+        }>;
+        at: z.ZodNullable<z.ZodInt>;
+        asked_at: z.ZodISODateTime;
+        answered_at: z.ZodOptional<z.ZodISODateTime>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    compaction: z.ZodOptional<z.ZodObject<{
+        change_id: z.ZodString;
+        state: z.ZodEnum<{
+            waiting: "waiting";
+            failed: "failed";
+            missed: "missed";
+            taken: "taken";
+            done: "done";
+        }>;
+        asked_at: z.ZodISODateTime;
+        answered_at: z.ZodOptional<z.ZodISODateTime>;
+        done_at: z.ZodOptional<z.ZodISODateTime>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    used: z.ZodInt;
+    window: z.ZodInt;
+    model: z.ZodOptional<z.ZodString>;
+    as_of: z.ZodISODateTime;
+    compacting: z.ZodOptional<z.ZodEnum<{
+        queued: "queued";
+        running: "running";
+    }>>;
+    last: z.ZodOptional<z.ZodObject<{
+        at: z.ZodISODateTime;
+        from: z.ZodInt;
+        to: z.ZodInt;
+        by: z.ZodEnum<{
+            asked: "asked";
+            itself: "itself";
+        }>;
+    }, z.core.$strip>>;
+    long_turn: z.ZodOptional<z.ZodObject<{
+        at: z.ZodISODateTime;
+        peak: z.ZodInt;
+        folds: z.ZodInt;
+    }, z.core.$strip>>;
+    compacts: z.ZodBoolean;
+    why_not: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodObject<{
+        at: z.ZodNullable<z.ZodInt>;
+        choices: z.ZodArray<z.ZodInt>;
+        default: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
+        may_turn_off: z.ZodBoolean;
+    }, z.core.$strip>>;
+    editable: z.ZodBoolean;
+    why_read_only: z.ZodOptional<z.ZodString>;
+    agent_id: z.ZodString;
+    harness_id: z.ZodString;
+}, z.core.$strip>;
+export type AgentContextWindowView = z.infer<typeof agentContextWindowView>;
+export declare const windowCompactFrame: z.ZodObject<{
+    frame: z.ZodLiteral<"context_window.compact">;
+    change_id: z.ZodString;
+    harness_id: z.ZodString;
+    agent_id: z.ZodString;
+    asked_by: z.ZodString;
+    asked_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type WindowCompactFrame = z.infer<typeof windowCompactFrame>;
+export declare const windowChangeFrame: z.ZodObject<{
+    frame: z.ZodLiteral<"context_window.change">;
+    change_id: z.ZodString;
+    harness_id: z.ZodString;
+    agent_id: z.ZodString;
+    at: z.ZodNullable<z.ZodInt>;
+    asked_by: z.ZodString;
+    asked_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type WindowChangeFrame = z.infer<typeof windowChangeFrame>;
+//# sourceMappingURL=agent-context-windows.d.ts.map

package/dist/src/agent-context-windows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-context-windows.d.ts","sourceRoot":"","sources":["../../src/agent-context-windows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,8CAA8C;AAC9C,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AASzC,eAAO,MAAM,YAAY,8BAA+B,CAAC;AAEzD,eAAO,MAAM,cAAc;;;;;;;;iBAWgB,CAAC;AAC5C,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,eAAO,MAAM,QAAQ;;;;iBAYlB,CAAC;AACJ,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,eAAO,MAAM,WAAW;;;;;iBAoCyD,CAAC;AAClF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AA+CtD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0B/B,CAAC;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,qBAAqB,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;AAExF,eAAO,MAAM,cAAc;;iBAMkE,CAAC;AAC9F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,oBAAoB,mDAAoD,CAAC;AACtF,eAAO,MAAM,iBAAiB;;;;;EAA+B,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;iBAW8D,CAAC;AAC5F,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,2DAA4D,CAAC;AAC3F,eAAO,MAAM,eAAe;;;;;;EAA4B,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,cAAc;;;;;;;;;;;;;iBAWsE,CAAC;AAClG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAYqD,CAAC;AACzF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,eAAO,MAAM,kBAAkB;;;;;;;iBAW5B,CAAC;AACJ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,eAAO,MAAM,iBAAiB;;;;;;;;iBAc3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/src/agent-context-windows.js

@@ -0,0 +1,213 @@
+/**
+ * An agent's context window (ADR 0146): how full it is, a person's Compact now, and the limit it
+ * compacts itself at, shown and changed on the agent's page in Chips and kept by its harness.
+ *
+ * Nothing about a context window is Chips'. A harness that declares `context_windows` sends a copy
+ * of each agent's: how many tokens it holds and its model's window, whether it is compacting, when
+ * it last compacted and from how much to how much, whether it takes a Compact now, and the limit it
+ * compacts itself at with the limits a person may pick, and how full its last long turn got.
+ * Chips puts the numbers into words itself.
+ *
+ * A person asks two things of it, each going down the harness's socket and answered by its next
+ * copy, as a model's change is (ADR 0140): Compact now, as `context_window.compact`, answered when
+ * the harness takes it on and done when a copy says it compacted since; and a new limit, as
+ * `context_window.change`. The copies live in a registry, not the log, one row per agent with the
+ * last of each ask beside it. When a copy says the agent compacted, Chips writes a quiet line in
+ * its room, `context.compacted`.
+ */
+import { z } from "zod";
+import { id, isoTimestamp } from "./primitives.js";
+/** The most limits an agent's copy offers. */
+export const WINDOW_LIMIT_CHOICES_MAX = 12;
+/**
+ * How long either ask waits for its harness's answer: the minute a model's change has. After it
+ * the ask is missed, and the person is told the harness hasn't answered; an answer after it still
+ * counts, and a new ask may be made.
+ */
+export const WINDOW_ASK_WAIT_MS = 60_000;
+/** A limit: the percent of the window at which the agent compacts itself. */
+const percent = z.int().min(1).max(99);
+const tokens = z.int().nonnegative();
+const ascending = (choices) => choices.every((each, at) => at === 0 || each > (choices[at - 1] ?? 0));
+export const COMPACTED_BY = ["asked", "itself"];
+export const lastCompaction = z
+    .object({
+    at: isoTimestamp.describe("When it finished compacting."),
+    from: tokens.describe("The tokens it held before."),
+    to: tokens.describe("The tokens it held after."),
+    by: z
+        .enum(COMPACTED_BY)
+        .describe("`asked`: a person asked, from Chips or elsewhere. `itself`: at its limit, or full."),
+})
+    .describe("The agent's last compaction.");
+/** How many times a long turn may say it compacted itself, at most. */
+export const LONG_TURN_FOLDS_MAX = 1000;
+export const longTurn = z
+    .object({
+    at: isoTimestamp.describe("When the turn ended."),
+    peak: tokens.describe("The most it held at once during the turn, as its harness counted it."),
+    folds: z
+        .int()
+        .nonnegative()
+        .max(LONG_TURN_FOLDS_MAX)
+        .describe("How many times it compacted itself during the turn."),
+})
+    .describe("Its last long turn: the last whose height passed half its window. A copy between turns reads low for an agent that holds little between them; this is how full it got while working.");
+export const windowLimit = z
+    .object({
+    at: percent
+        .nullable()
+        .describe("The percent of the window it compacts itself at, one of `choices`. `null`: only when asked, or when its harness must."),
+    choices: z
+        .array(percent)
+        .min(1)
+        .max(WINDOW_LIMIT_CHOICES_MAX)
+        .refine(ascending, { message: "The limits go up, each named once." })
+        .describe("The limits a person may pick, lowest first: twelve at most."),
+    default: percent
+        .nullable()
+        .optional()
+        .describe("The harness's own limit, marked among the choices; `null` when its own is only when asked."),
+    may_turn_off: z.boolean().describe("Whether a person may pick only when asked (`at: null`)."),
+})
+    .refine((limit) => limit.at === null || limit.choices.includes(limit.at), {
+    path: ["at"],
+    message: "`at` is one of `choices`, or `null`.",
+})
+    .refine((limit) => limit.at !== null || limit.may_turn_off, {
+    path: ["at"],
+    message: "`at` is `null` only for a limit that may be turned off.",
+})
+    .refine((limit) => limit.default === undefined ||
+    limit.default === null ||
+    limit.choices.includes(limit.default), { path: ["default"], message: "`default` is one of `choices`." })
+    .describe("The limit an agent compacts itself at, and what a person may pick.");
+const copyFields = {
+    used: tokens.describe("The tokens the agent holds now, as its harness counts them."),
+    window: z.int().positive().describe("Its model's context window, in tokens."),
+    model: z.string().min(1).max(120).optional().describe("The model whose window it is."),
+    as_of: isoTimestamp.describe("When `used` was measured."),
+    compacting: z
+        .enum(["queued", "running"])
+        .optional()
+        .describe("While it compacts: `queued`, waiting for its turn to end; `running`, under way. Absent otherwise."),
+    last: lastCompaction.optional(),
+    long_turn: longTurn
+        .optional()
+        .describe("Absent when its harness has seen no long turn of it, or keeps no record of one."),
+    compacts: z.boolean().describe("Whether it takes a Compact now from Chips."),
+    why_not: z
+        .string()
+        .min(1)
+        .max(120)
+        .optional()
+        .describe("Why not, in the harness's words, only when it doesn't `compacts`."),
+    limit: windowLimit
+        .optional()
+        .describe("Absent: its harness keeps its own limit and offers no other."),
+    editable: z.boolean().describe("Whether a person may change its limit from Chips."),
+    why_read_only: z
+        .string()
+        .min(1)
+        .max(120)
+        .optional()
+        .describe("Why not, in the harness's words, only when it is not `editable`."),
+};
+const whyNotOnlyWhenNot = (copy) => copy.why_not === undefined || !copy.compacts;
+const whyOnlyWhenReadOnly = (copy) => copy.why_read_only === undefined || !copy.editable;
+export const agentContextWindowPut = z
+    .object({
+    ...copyFields,
+    answers: id("change")
+        .optional()
+        .describe("The ask this copy answers: a limit set, or a Compact now taken on, and this is the agent as it is now."),
+    refuses: z
+        .object({
+        change_id: id("change"),
+        message: z.string().min(1).max(300).optional().describe("Why not, for the person."),
+    })
+        .optional()
+        .describe("An ask not done. The copy beside it is the agent as it is now."),
+})
+    .refine(whyNotOnlyWhenNot, {
+    path: ["why_not"],
+    message: "Say why not only for an agent that takes no Compact now.",
+})
+    .refine(whyOnlyWhenReadOnly, {
+    path: ["why_read_only"],
+    message: "Say why only for a limit that can't be changed.",
+})
+    .describe("`PUT /v1/agents/:id/context-window`: a harness's copy of one of its agents' context window.");
+export const windowLimitAsk = z
+    .object({
+    at: percent
+        .nullable()
+        .describe("One of the copy's limit `choices`, or `null` for only when asked."),
+})
+    .describe("`POST /v1/agents/:id/context-window/changes`: the limit it compacts itself at.");
+export const WINDOW_CHANGE_STATES = ["waiting", "saved", "failed", "missed"];
+export const windowChangeState = z.enum(WINDOW_CHANGE_STATES);
+export const windowChangeView = z
+    .object({
+    change_id: id("change"),
+    state: windowChangeState.describe("`missed` once `WINDOW_ASK_WAIT_MS` has passed with no answer; read, never stored."),
+    at: percent.nullable(),
+    asked_at: isoTimestamp,
+    answered_at: isoTimestamp.optional(),
+    message: z.string().max(300).optional().describe("The harness's words, for a refusal."),
+})
+    .describe("The last limit a person asked of an agent, and what became of it (ADR 0146).");
+/**
+ * What became of a Compact now: `waiting` for the harness; `taken`, answered and under way;
+ * `done`, a copy says it compacted since or stopped compacting; `failed`, refused; `missed`, no
+ * answer within `WINDOW_ASK_WAIT_MS`.
+ */
+export const COMPACTION_STATES = ["waiting", "taken", "done", "failed", "missed"];
+export const compactionState = z.enum(COMPACTION_STATES);
+export const compactionView = z
+    .object({
+    change_id: id("change"),
+    state: compactionState.describe("`missed` once `WINDOW_ASK_WAIT_MS` has passed with no answer; read, never stored."),
+    asked_at: isoTimestamp,
+    answered_at: isoTimestamp.optional(),
+    done_at: isoTimestamp.optional(),
+    message: z.string().max(300).optional().describe("The harness's words, for a refusal."),
+})
+    .describe("The last Compact now a person asked of an agent, and what became of it (ADR 0146).");
+export const agentContextWindowView = z
+    .object({
+    agent_id: id("agent"),
+    harness_id: id("harness"),
+    ...copyFields,
+    read_at: isoTimestamp.describe("When the harness last sent its copy."),
+    away: z
+        .boolean()
+        .describe("No socket of the harness hears asks now: read, not compacted or changed."),
+    change: windowChangeView.optional(),
+    compaction: compactionView.optional(),
+})
+    .describe("`GET /v1/agents/:id/context-window`, for the harness's owner or an admin.");
+export const windowCompactFrame = z
+    .object({
+    frame: z.literal("context_window.compact"),
+    change_id: id("change"),
+    harness_id: id("harness"),
+    agent_id: id("agent"),
+    asked_by: id("person"),
+    asked_at: isoTimestamp,
+})
+    .describe("A person asked an agent to compact its context now (ADR 0146). Sent to a harness's socket that said `context_windows` in its `hello`, now or never: it is not in the log. The harness answers at once with the agent's copy, `answers` naming `change_id` with `compacting` set, or `refuses`; and sends a copy again when it is done.");
+export const windowChangeFrame = z
+    .object({
+    frame: z.literal("context_window.change"),
+    change_id: id("change"),
+    harness_id: id("harness"),
+    agent_id: id("agent"),
+    at: percent
+        .nullable()
+        .describe("One of the copy's limit `choices`, or `null` for only when asked."),
+    asked_by: id("person"),
+    asked_at: isoTimestamp,
+})
+    .describe("A person changed the limit an agent compacts itself at (ADR 0146). Sent to a harness's socket that said `context_windows` in its `hello`, now or never: it is not in the log. The harness answers with the agent's copy, `answers` or `refuses` naming `change_id`.");
+//# sourceMappingURL=agent-context-windows.js.map

package/dist/src/agent-context-windows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-context-windows.js","sourceRoot":"","sources":["../../src/agent-context-windows.ts"],"names":[],"mappings":"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"}

package/dist/src/agent-heartbeats.d.ts

@@ -0,0 +1,106 @@
+/**
+ * An agent's heartbeat (ADR 0143): a turn its harness starts on its own every so often, switched
+ * on or off and timed on the agent's page in Chips, and kept by its harness.
+ *
+ * Nothing about a heartbeat is Chips'. A harness that declares `heartbeats` sends a copy of each
+ * agent's: whether it is on, how often it beats in minutes, the intervals a person may pick, and
+ * whether a person may change it. Chips puts the minutes into words itself. A person's change goes
+ * down the harness's socket as a `heartbeat.change` frame, and is done when the harness sends its
+ * copy back answering it, or refused with its words.
+ *
+ * The copies live in a registry, not the log, as a model's do (ADR 0140): one row per agent,
+ * holding the last change asked of it. What a heartbeat says in a room is an ordinary message,
+ * marked `heartbeat` on `message.post`.
+ */
+import { z } from "zod";
+/** The most intervals an agent's copy offers. */
+export declare const HEARTBEAT_CHOICES_MAX = 12;
+/** The longest interval, in minutes: a week. */
+export declare const HEARTBEAT_EVERY_MAX = 10080;
+/**
+ * How long a change waits for its harness's answer: the minute a model's change has. After it the
+ * change is missed, and the person is told the harness hasn't answered; an answer after it still
+ * counts, and a new change may be asked.
+ */
+export declare const HEARTBEAT_CHANGE_WAIT_MS = 60000;
+export declare const agentHeartbeatPut: z.ZodObject<{
+    answers: z.ZodOptional<z.ZodString>;
+    refuses: z.ZodOptional<z.ZodObject<{
+        change_id: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    on: z.ZodBoolean;
+    every: z.ZodInt;
+    choices: z.ZodArray<z.ZodInt>;
+    editable: z.ZodBoolean;
+    why_read_only: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AgentHeartbeatPut = z.infer<typeof agentHeartbeatPut>;
+/** The copy as Chips keeps it: what the harness sent, without what it answered. */
+export type AgentHeartbeatCopy = Omit<AgentHeartbeatPut, "answers" | "refuses">;
+export declare const heartbeatChangeAsk: z.ZodObject<{
+    on: z.ZodBoolean;
+    every: z.ZodOptional<z.ZodInt>;
+}, z.core.$strip>;
+export type HeartbeatChangeAsk = z.infer<typeof heartbeatChangeAsk>;
+export declare const HEARTBEAT_CHANGE_STATES: readonly ["waiting", "saved", "failed", "missed"];
+export declare const heartbeatChangeState: z.ZodEnum<{
+    waiting: "waiting";
+    saved: "saved";
+    failed: "failed";
+    missed: "missed";
+}>;
+export type HeartbeatChangeState = z.infer<typeof heartbeatChangeState>;
+export declare const heartbeatChangeView: z.ZodObject<{
+    change_id: z.ZodString;
+    state: z.ZodEnum<{
+        waiting: "waiting";
+        saved: "saved";
+        failed: "failed";
+        missed: "missed";
+    }>;
+    on: z.ZodBoolean;
+    every: z.ZodInt;
+    asked_at: z.ZodISODateTime;
+    answered_at: z.ZodOptional<z.ZodISODateTime>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HeartbeatChangeView = z.infer<typeof heartbeatChangeView>;
+export declare const agentHeartbeatView: z.ZodObject<{
+    read_at: z.ZodISODateTime;
+    away: z.ZodBoolean;
+    change: z.ZodOptional<z.ZodObject<{
+        change_id: z.ZodString;
+        state: z.ZodEnum<{
+            waiting: "waiting";
+            saved: "saved";
+            failed: "failed";
+            missed: "missed";
+        }>;
+        on: z.ZodBoolean;
+        every: z.ZodInt;
+        asked_at: z.ZodISODateTime;
+        answered_at: z.ZodOptional<z.ZodISODateTime>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    on: z.ZodBoolean;
+    every: z.ZodInt;
+    choices: z.ZodArray<z.ZodInt>;
+    editable: z.ZodBoolean;
+    why_read_only: z.ZodOptional<z.ZodString>;
+    agent_id: z.ZodString;
+    harness_id: z.ZodString;
+}, z.core.$strip>;
+export type AgentHeartbeatView = z.infer<typeof agentHeartbeatView>;
+export declare const heartbeatChangeFrame: z.ZodObject<{
+    frame: z.ZodLiteral<"heartbeat.change">;
+    change_id: z.ZodString;
+    harness_id: z.ZodString;
+    agent_id: z.ZodString;
+    on: z.ZodBoolean;
+    every: z.ZodInt;
+    asked_by: z.ZodString;
+    asked_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type HeartbeatChangeFrame = z.infer<typeof heartbeatChangeFrame>;
+//# sourceMappingURL=agent-heartbeats.d.ts.map

package/dist/src/agent-heartbeats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-heartbeats.d.ts","sourceRoot":"","sources":["../../src/agent-heartbeats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,iDAAiD;AACjD,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,gDAAgD;AAChD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAsC/C,eAAO,MAAM,iBAAiB;;;;;;;;;;;iBAmBkE,CAAC;AACjG,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,mFAAmF;AACnF,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;AAEhF,eAAO,MAAM,kBAAkB;;;iBAOkD,CAAC;AAClF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,eAAO,MAAM,uBAAuB,mDAAoD,CAAC;AACzF,eAAO,MAAM,oBAAoB;;;;;EAAkC,CAAC;AACpE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;iBAc7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;iBASoD,CAAC;AACpF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,eAAO,MAAM,oBAAoB;;;;;;;;;iBAe9B,CAAC;AACJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}