@chipschat/protocol 0.0.0-stage → 1.0.1

package/dist/src/agent-heartbeats.js

@@ -0,0 +1,111 @@
+/**
+ * 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";
+import { id, isoTimestamp } from "./primitives.js";
+/** The most intervals an agent's copy offers. */
+export const HEARTBEAT_CHOICES_MAX = 12;
+/** The longest interval, in minutes: a week. */
+export const HEARTBEAT_EVERY_MAX = 10_080;
+/**
+ * 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 const HEARTBEAT_CHANGE_WAIT_MS = 60_000;
+const minutes = z.int().min(1).max(HEARTBEAT_EVERY_MAX);
+const ascending = (choices) => choices.every((each, at) => at === 0 || each > (choices[at - 1] ?? 0));
+const copyFields = {
+    on: z.boolean().describe("Whether it beats now."),
+    every: minutes.describe("How often it beats, in minutes: one of `choices`, kept while it is off."),
+    choices: z
+        .array(minutes)
+        .min(1)
+        .max(HEARTBEAT_CHOICES_MAX)
+        .refine(ascending, { message: "The intervals go up, each named once." })
+        .describe("The intervals a person may pick, in minutes, shortest first: twelve at most."),
+    editable: z.boolean().describe("Whether a person may change it 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 beatsAChoice = (copy) => copy.choices.includes(copy.every);
+const whyOnlyWhenReadOnly = (copy) => copy.why_read_only === undefined || !copy.editable;
+export const agentHeartbeatPut = z
+    .object({
+    ...copyFields,
+    answers: id("change")
+        .optional()
+        .describe("The change this copy answers: made, 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("A change not made. The copy beside it is the agent as it is now."),
+})
+    .refine(beatsAChoice, { path: ["every"], message: "`every` is one of `choices`." })
+    .refine(whyOnlyWhenReadOnly, {
+    path: ["why_read_only"],
+    message: "Say why only for a heartbeat that can't be changed.",
+})
+    .describe("`PUT /v1/agents/:id/heartbeat`: a harness's copy of one of its agents' heartbeat.");
+export const heartbeatChangeAsk = z
+    .object({
+    on: z.boolean().describe("Whether it is to beat."),
+    every: minutes
+        .optional()
+        .describe("How often, one of `choices`. Left out: the copy's own `every`."),
+})
+    .describe("`POST /v1/agents/:id/heartbeat/changes`: on or off, and how often.");
+export const HEARTBEAT_CHANGE_STATES = ["waiting", "saved", "failed", "missed"];
+export const heartbeatChangeState = z.enum(HEARTBEAT_CHANGE_STATES);
+export const heartbeatChangeView = z
+    .object({
+    change_id: id("change"),
+    state: heartbeatChangeState.describe("`missed` once `HEARTBEAT_CHANGE_WAIT_MS` has passed with no answer; read, never stored."),
+    on: z.boolean(),
+    every: minutes,
+    asked_at: isoTimestamp,
+    answered_at: isoTimestamp.optional(),
+    message: z.string().max(300).optional().describe("The harness's words, for a refusal."),
+})
+    .describe("The last change a person asked of an agent's heartbeat, and what became of it (ADR 0143).");
+export const agentHeartbeatView = 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 changes now: read, not changed."),
+    change: heartbeatChangeView.optional(),
+})
+    .describe("`GET /v1/agents/:id/heartbeat`, for the harness's owner or an admin.");
+export const heartbeatChangeFrame = z
+    .object({
+    frame: z.literal("heartbeat.change"),
+    change_id: id("change"),
+    harness_id: id("harness"),
+    agent_id: id("agent"),
+    on: z.boolean(),
+    every: minutes.describe("One of the copy's `choices`: the copy's own when the person named none."),
+    asked_by: id("person"),
+    asked_at: isoTimestamp,
+})
+    .describe("A person switched an agent's heartbeat or changed how often it beats (ADR 0143). Sent to a harness's socket that said `heartbeats` 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-heartbeats.js.map

package/dist/src/agent-heartbeats.js.map

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

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

@@ -0,0 +1,158 @@
+/**
+ * An agent's model and effort (ADR 0140): what it runs on and how hard it thinks, chosen on its
+ * page in Chips and kept by its harness.
+ *
+ * Nothing about a model is Chips'. A harness that declares `models` sends a copy of each agent's:
+ * the model it runs on now and its effort, whether those are its own or the harness's default for
+ * it ("Same as J"), the models it may run on, each with its effort levels, lowest first, and every
+ * word a page shows for them. A person's change goes down the harness's socket as a `model.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 context files do (ADR 0134): one row per agent,
+ * holding the last change asked of it.
+ */
+import { z } from "zod";
+/** The most models an agent's copy offers. A harness sends the ones worth choosing. */
+export declare const MODEL_CHOICES_MAX = 40;
+/** The most effort levels a model has, one bar each. A harness sends its most useful eight. */
+export declare const EFFORT_LEVELS_MAX = 8;
+/**
+ * How long a change waits for its harness's answer: the minute a context edit 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 MODEL_CHANGE_WAIT_MS = 60000;
+export declare const effortLevel: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+export type EffortLevel = z.infer<typeof effortLevel>;
+export declare const modelChoice: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    efforts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    effort_default: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ModelChoice = z.infer<typeof modelChoice>;
+/** Whether `effort` is a level of the model `model` names among `choices`: absent for none. */
+export declare function effortFits(choices: readonly ModelChoice[], model: string, effort: string | undefined): boolean;
+export declare const modelDefault: z.ZodObject<{
+    label: z.ZodString;
+    model: z.ZodString;
+    effort: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ModelDefault = z.infer<typeof modelDefault>;
+export declare const agentModelPut: z.ZodObject<{
+    answers: z.ZodOptional<z.ZodString>;
+    refuses: z.ZodOptional<z.ZodObject<{
+        change_id: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    model: z.ZodString;
+    effort: z.ZodOptional<z.ZodString>;
+    own: z.ZodBoolean;
+    default: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        model: z.ZodString;
+        effort: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    choices: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        efforts: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+        effort_default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    editable: z.ZodBoolean;
+    why_read_only: z.ZodOptional<z.ZodString>;
+    followed_by: z.ZodOptional<z.ZodInt>;
+}, z.core.$strip>;
+export type AgentModelPut = z.infer<typeof agentModelPut>;
+/** The copy as Chips keeps it: what the harness sent, without what it answered. */
+export type AgentModelCopy = Omit<AgentModelPut, "answers" | "refuses">;
+export declare const modelChangeAsk: z.ZodObject<{
+    model: z.ZodNullable<z.ZodString>;
+    effort: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ModelChangeAsk = z.infer<typeof modelChangeAsk>;
+export declare const MODEL_CHANGE_STATES: readonly ["waiting", "saved", "failed", "missed"];
+export declare const modelChangeState: z.ZodEnum<{
+    waiting: "waiting";
+    saved: "saved";
+    failed: "failed";
+    missed: "missed";
+}>;
+export type ModelChangeState = z.infer<typeof modelChangeState>;
+export declare const modelChangeView: z.ZodObject<{
+    change_id: z.ZodString;
+    state: z.ZodEnum<{
+        waiting: "waiting";
+        saved: "saved";
+        failed: "failed";
+        missed: "missed";
+    }>;
+    model: z.ZodNullable<z.ZodString>;
+    effort: z.ZodNullable<z.ZodString>;
+    asked_at: z.ZodISODateTime;
+    answered_at: z.ZodOptional<z.ZodISODateTime>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ModelChangeView = z.infer<typeof modelChangeView>;
+export declare const agentModelView: 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";
+        }>;
+        model: z.ZodNullable<z.ZodString>;
+        effort: z.ZodNullable<z.ZodString>;
+        asked_at: z.ZodISODateTime;
+        answered_at: z.ZodOptional<z.ZodISODateTime>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    model: z.ZodString;
+    effort: z.ZodOptional<z.ZodString>;
+    own: z.ZodBoolean;
+    default: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        model: z.ZodString;
+        effort: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    choices: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        efforts: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+        effort_default: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    editable: z.ZodBoolean;
+    why_read_only: z.ZodOptional<z.ZodString>;
+    followed_by: z.ZodOptional<z.ZodInt>;
+    agent_id: z.ZodString;
+    harness_id: z.ZodString;
+}, z.core.$strip>;
+export type AgentModelView = z.infer<typeof agentModelView>;
+export declare const modelChangeFrame: z.ZodObject<{
+    frame: z.ZodLiteral<"model.change">;
+    change_id: z.ZodString;
+    harness_id: z.ZodString;
+    agent_id: z.ZodString;
+    model: z.ZodNullable<z.ZodString>;
+    effort: z.ZodNullable<z.ZodString>;
+    asked_by: z.ZodString;
+    asked_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ModelChangeFrame = z.infer<typeof modelChangeFrame>;
+//# sourceMappingURL=agent-models.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-models.d.ts","sourceRoot":"","sources":["../../src/agent-models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAM3C,eAAO,MAAM,WAAW;;;iBAKuD,CAAC;AAChF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,eAAO,MAAM,WAAW;;;;;;;;iBAqBgC,CAAC;AACzD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,+FAA+F;AAC/F,wBAAgB,UAAU,CACxB,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,OAAO,CAKT;AAED,eAAO,MAAM,YAAY;;;;iBAM0D,CAAC;AACpF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AA8CxD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsByE,CAAC;AACpG,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;AAExE,eAAO,MAAM,cAAc;;;iBASgE,CAAC;AAC5F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB,mDAAoD,CAAC;AACrF,eAAO,MAAM,gBAAgB;;;;;EAA8B,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,eAAO,MAAM,eAAe;;;;;;;;;;;;;iBAczB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBASoD,CAAC;AAChF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,gBAAgB;;;;;;;;;iBAa1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/src/agent-models.js

@@ -0,0 +1,171 @@
+/**
+ * An agent's model and effort (ADR 0140): what it runs on and how hard it thinks, chosen on its
+ * page in Chips and kept by its harness.
+ *
+ * Nothing about a model is Chips'. A harness that declares `models` sends a copy of each agent's:
+ * the model it runs on now and its effort, whether those are its own or the harness's default for
+ * it ("Same as J"), the models it may run on, each with its effort levels, lowest first, and every
+ * word a page shows for them. A person's change goes down the harness's socket as a `model.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 context files do (ADR 0134): one row per agent,
+ * holding the last change asked of it.
+ */
+import { z } from "zod";
+import { id, isoTimestamp } from "./primitives.js";
+/** The most models an agent's copy offers. A harness sends the ones worth choosing. */
+export const MODEL_CHOICES_MAX = 40;
+/** The most effort levels a model has, one bar each. A harness sends its most useful eight. */
+export const EFFORT_LEVELS_MAX = 8;
+/**
+ * How long a change waits for its harness's answer: the minute a context edit 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 const MODEL_CHANGE_WAIT_MS = 60_000;
+const modelId = z.string().min(1).max(200);
+const effortId = z.string().min(1).max(64);
+const label = z.string().min(1).max(80);
+export const effortLevel = z
+    .object({
+    id: effortId.describe("The harness's own word for it: `high`."),
+    label: z.string().min(1).max(40).describe("What its bar says: `High`."),
+})
+    .describe("One effort level of a model, as its harness names it (ADR 0140).");
+export const modelChoice = z
+    .object({
+    id: modelId.describe("The harness's own id for the model: `heron-2`, `lathe/heron-2`."),
+    label: label.describe("What its row says: `Heron 2`."),
+    efforts: z
+        .array(effortLevel)
+        .max(EFFORT_LEVELS_MAX)
+        .refine((levels) => new Set(levels.map((level) => level.id)).size === levels.length, {
+        message: "Each level is named once.",
+    })
+        .describe("Its effort levels, lowest first: eight at most, none for a model without any."),
+    effort_default: effortId
+        .optional()
+        .describe("The level it runs at when none is set, if the harness knows it."),
+})
+    .refine((choice) => choice.effort_default === undefined ||
+    choice.efforts.some((level) => level.id === choice.effort_default), { message: "A model's default level is one of its levels." })
+    .describe("One model an agent may run on (ADR 0140).");
+/** Whether `effort` is a level of the model `model` names among `choices`: absent for none. */
+export function effortFits(choices, model, effort) {
+    const choice = choices.find((each) => each.id === model);
+    if (choice === undefined)
+        return false;
+    if (effort === undefined)
+        return true;
+    return choice.efforts.some((level) => level.id === effort);
+}
+export const modelDefault = z
+    .object({
+    label: label.describe("What the switch says: `Same as J`, `Lathe's default`."),
+    model: modelId,
+    effort: effortId.optional(),
+})
+    .describe("What an agent runs on with no model or effort of its own (ADR 0140).");
+const copyFields = {
+    model: modelId.describe("The model it runs on now: an id among `choices`."),
+    effort: effortId
+        .optional()
+        .describe("The level it runs at now: one of its model's. Absent when its model has none."),
+    own: z
+        .boolean()
+        .describe("It has a model or an effort of its own. `false`: it runs on `default`."),
+    default: modelDefault
+        .optional()
+        .describe("What it runs on with none of its own. Absent: there is no Same as switch."),
+    choices: z
+        .array(modelChoice)
+        .min(1)
+        .max(MODEL_CHOICES_MAX)
+        .refine((choices) => new Set(choices.map((choice) => choice.id)).size === choices.length, {
+        message: "Each model is named once.",
+    })
+        .describe("The models it may run on: forty at most, its own among them."),
+    editable: z.boolean().describe("Whether a person may change it from Chips."),
+    why_read_only: z
+        .string()
+        .min(1)
+        .max(120)
+        .optional()
+        .describe("Why not, in the harness's words: `Lathe's own agent. Change it in Lathe.`"),
+    followed_by: z
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("How many agents have none of their own and run on this one's."),
+};
+const runsOnAChoice = (copy) => effortFits(copy.choices, copy.model, copy.effort);
+const defaultIsAChoice = (copy) => copy.default === undefined || effortFits(copy.choices, copy.default.model, copy.default.effort);
+export const agentModelPut = z
+    .object({
+    ...copyFields,
+    answers: id("change")
+        .optional()
+        .describe("The change this copy answers: made, 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("A change not made. The copy beside it is the agent as it is now."),
+})
+    .refine(runsOnAChoice, {
+    path: ["model"],
+    message: "The model is one of `choices`, and its effort one of that model's levels.",
+})
+    .refine(defaultIsAChoice, {
+    path: ["default"],
+    message: "The default's model is one of `choices`, and its effort one of that model's.",
+})
+    .describe("`PUT /v1/agents/:id/model`: a harness's copy of one of its agents' model and effort.");
+export const modelChangeAsk = z
+    .object({
+    model: modelId
+        .nullable()
+        .describe("The model to run on, one of `choices`. `null`, with `effort`: the default's."),
+    effort: effortId
+        .nullable()
+        .describe("One of that model's levels; `null` for a model with none, or for the default."),
+})
+    .describe("`POST /v1/agents/:id/model/changes`: both of its own, or both the default's.");
+export const MODEL_CHANGE_STATES = ["waiting", "saved", "failed", "missed"];
+export const modelChangeState = z.enum(MODEL_CHANGE_STATES);
+export const modelChangeView = z
+    .object({
+    change_id: id("change"),
+    state: modelChangeState.describe("`missed` once `MODEL_CHANGE_WAIT_MS` has passed with no answer; read, never stored."),
+    model: modelId.nullable(),
+    effort: effortId.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 change a person asked of an agent's model, and what became of it (ADR 0140).");
+export const agentModelView = 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 changes now: read, not changed."),
+    change: modelChangeView.optional(),
+})
+    .describe("`GET /v1/agents/:id/model`, for the harness's owner or an admin.");
+export const modelChangeFrame = z
+    .object({
+    frame: z.literal("model.change"),
+    change_id: id("change"),
+    harness_id: id("harness"),
+    agent_id: id("agent"),
+    model: modelId.nullable().describe("`null`, with `effort`: no model of its own, the default."),
+    effort: effortId.nullable(),
+    asked_by: id("person"),
+    asked_at: isoTimestamp,
+})
+    .describe("A person changed an agent's model or effort (ADR 0140). Sent to a harness's socket that said `models` 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-models.js.map

package/dist/src/agent-models.js.map

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

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

@@ -0,0 +1,76 @@
+/**
+ * Where an agent may be (ADR 0087, rules 1 and 7), in one place (agents review, findings 5 to 8).
+ *
+ * An agent is in one room at a time. Nine paths put an agent in a room: a person's add, a move, an
+ * unarchive, a room opened or claimed by key, a harness's attach, a fork's copy, a hand-off's
+ * home, an agent's first words, and the answer to a room asked of several. Each used to read where
+ * the agent was and then write, with its own version of the rule or none. Two at once, or a path
+ * that did not ask, left an agent in two rooms.
+ *
+ * The rule is this function. The store asks it inside the append's transaction, of every event
+ * that puts an agent in a room, whichever path wrote it: that is what makes it hold. The door asks
+ * it first, with the same facts, so a person is told why before anything is written. It lives
+ * with the protocol so that the conformance fake asks the same function, and cannot differ.
+ *
+ * What it says:
+ *
+ * - the room is there, and open: an archived room takes no agent until it is unarchived;
+ * - a Main room takes people and its Main agent, and no other agent;
+ * - the Main agent's place in its Main room is not taken by another;
+ * - a deleted agent is in no room again (ADR 0095);
+ * - the agent is in no other room, open or archived. An archived room's agents are released as it
+ *   is archived, so one still in such a room is one whose release has not been written yet, and it
+ *   is not put anywhere else until it has.
+ *
+ * What it leaves to the door, because Chips itself may do it: a Main agent put in a room that is
+ * not a Main room yet (its harness opens the room, then names it its home), and an agent archived
+ * in its harness (an unarchive brings back whoever the archive released).
+ */
+/** Why an agent may not be put in a room: the rule, in words, and where the agent is. */
+export interface PlaceRefusal {
+    readonly kind: "unknown_space" | "lead_room" | "room_closed" | "agent_elsewhere" | "agent_deleted";
+    readonly message: string;
+    /** For `agent_elsewhere`: the room the agent is in, where a client offers Move. */
+    readonly space_id?: string | undefined;
+}
+/** A room as the rule needs it. */
+export interface PlaceRoom {
+    readonly space_id: string;
+    readonly state: string;
+    /** A harness's home (ADR 0069): the Main room of its Main agent. */
+    readonly home: boolean;
+}
+export interface AgentPlacement {
+    /** The agent to be put in the room; `deleted` when a person deleted it (ADR 0095). */
+    readonly agent: {
+        readonly id: string;
+        readonly lead: boolean;
+        readonly deleted?: boolean;
+    };
+    /** The room, or `null` when there is none by that id: erased, or never there. */
+    readonly room: PlaceRoom | null;
+    /** A room the agent is a member of now that is not this one, open or archived; `null`: none. */
+    readonly elsewhere: string | null;
+    /** How many agents the room holds already, less this one and the one whose place it takes. */
+    readonly others: number;
+    /** True when it takes the place of a Main agent: a harness's attach, in its Main room. */
+    readonly replacesLead: boolean;
+}
+/** Why this agent may not be put in this room, or nothing when it may. */
+export declare function refuseAgentInto(placement: AgentPlacement): PlaceRefusal | undefined;
+/** Why an agent left a room, as `agent.released` says it. */
+type LeftBecause = "archived" | "deleted" | "moved" | "agent_archived" | "removed" | "agent_deleted";
+/**
+ * What a run is told when its agent leaves the room it was working in, by why it left (agents
+ * review, findings 10 and 12): the `reason` on the `run.cancel` that stops it. Leaving a room
+ * stops the work, whatever the reason.
+ */
+export declare const STOPPED_BECAUSE: Readonly<Record<LeftBecause, string>>;
+/**
+ * The refusals an `error` frame names in `refusal`, for a client that offers a way on (ADR 0087):
+ * Move for an agent that is elsewhere, Unarchive for a room that is archived, and words for the
+ * other two. The server's socket and the conformance fake's both read this list.
+ */
+export declare const ONE_ROOM_REFUSALS: ReadonlySet<string>;
+export {};
+//# sourceMappingURL=agent-place.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-place.d.ts","sourceRoot":"","sources":["../../src/agent-place.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EACT,eAAe,GACf,WAAW,GACX,aAAa,GACb,iBAAiB,GACjB,eAAe,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC5F,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IAChC,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,SAAS,EAAE,cAAc,GAAG,YAAY,GAAG,SAAS,CAuBnF;AAED,6DAA6D;AAC7D,KAAK,WAAW,GACZ,UAAU,GACV,SAAS,GACT,OAAO,GACP,gBAAgB,GAChB,SAAS,GACT,eAAe,CAAC;AAEpB;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAOjE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAMhD,CAAC"}

package/dist/src/agent-place.js

@@ -0,0 +1,80 @@
+/**
+ * Where an agent may be (ADR 0087, rules 1 and 7), in one place (agents review, findings 5 to 8).
+ *
+ * An agent is in one room at a time. Nine paths put an agent in a room: a person's add, a move, an
+ * unarchive, a room opened or claimed by key, a harness's attach, a fork's copy, a hand-off's
+ * home, an agent's first words, and the answer to a room asked of several. Each used to read where
+ * the agent was and then write, with its own version of the rule or none. Two at once, or a path
+ * that did not ask, left an agent in two rooms.
+ *
+ * The rule is this function. The store asks it inside the append's transaction, of every event
+ * that puts an agent in a room, whichever path wrote it: that is what makes it hold. The door asks
+ * it first, with the same facts, so a person is told why before anything is written. It lives
+ * with the protocol so that the conformance fake asks the same function, and cannot differ.
+ *
+ * What it says:
+ *
+ * - the room is there, and open: an archived room takes no agent until it is unarchived;
+ * - a Main room takes people and its Main agent, and no other agent;
+ * - the Main agent's place in its Main room is not taken by another;
+ * - a deleted agent is in no room again (ADR 0095);
+ * - the agent is in no other room, open or archived. An archived room's agents are released as it
+ *   is archived, so one still in such a room is one whose release has not been written yet, and it
+ *   is not put anywhere else until it has.
+ *
+ * What it leaves to the door, because Chips itself may do it: a Main agent put in a room that is
+ * not a Main room yet (its harness opens the room, then names it its home), and an agent archived
+ * in its harness (an unarchive brings back whoever the archive released).
+ */
+/** Why this agent may not be put in this room, or nothing when it may. */
+export function refuseAgentInto(placement) {
+    const { agent, room, elsewhere } = placement;
+    if (agent.deleted === true) {
+        return { kind: "agent_deleted", message: "that agent was deleted" };
+    }
+    if (room === null)
+        return { kind: "unknown_space", message: "no such space in this workspace" };
+    if (room.home && (!agent.lead || placement.others > 0)) {
+        return { kind: "lead_room", message: "a Main space takes people, and no other agent" };
+    }
+    if (room.home && placement.replacesLead) {
+        return { kind: "lead_room", message: "the Main agent stays in its Main space" };
+    }
+    if (room.state === "closed") {
+        return { kind: "room_closed", message: "that space is archived: unarchive it first" };
+    }
+    if (elsewhere !== null) {
+        return {
+            kind: "agent_elsewhere",
+            message: "that agent is in another space: move it, or pick another",
+            space_id: elsewhere,
+        };
+    }
+    return undefined;
+}
+/**
+ * What a run is told when its agent leaves the room it was working in, by why it left (agents
+ * review, findings 10 and 12): the `reason` on the `run.cancel` that stops it. Leaving a room
+ * stops the work, whatever the reason.
+ */
+export const STOPPED_BECAUSE = {
+    archived: "The space was archived.",
+    deleted: "The space was deleted.",
+    moved: "The agent was moved to another space.",
+    agent_archived: "The agent was archived.",
+    removed: "The agent was taken out of the space.",
+    agent_deleted: "The agent was deleted.",
+};
+/**
+ * The refusals an `error` frame names in `refusal`, for a client that offers a way on (ADR 0087):
+ * Move for an agent that is elsewhere, Unarchive for a room that is archived, and words for the
+ * other two. The server's socket and the conformance fake's both read this list.
+ */
+export const ONE_ROOM_REFUSALS = new Set([
+    "agent_elsewhere",
+    "lead_room",
+    "agent_archived",
+    "room_closed",
+    "agent_deleted",
+]);
+//# sourceMappingURL=agent-place.js.map

package/dist/src/agent-place.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-place.js","sourceRoot":"","sources":["../../src/agent-place.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAoCH,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAAC,SAAyB;IACvD,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;IAC7C,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACtE,CAAC;IACD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC;IAChG,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,+CAA+C,EAAE,CAAC;IACzF,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC;QACxC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,wCAAwC,EAAE,CAAC;IAClF,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,4CAA4C,EAAE,CAAC;IACxF,CAAC;IACD,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,OAAO;YACL,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,0DAA0D;YACnE,QAAQ,EAAE,SAAS;SACpB,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAWD;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAA0C;IACpE,QAAQ,EAAE,yBAAyB;IACnC,OAAO,EAAE,wBAAwB;IACjC,KAAK,EAAE,uCAAuC;IAC9C,cAAc,EAAE,yBAAyB;IACzC,OAAO,EAAE,uCAAuC;IAChD,aAAa,EAAE,wBAAwB;CACxC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC;IAC5D,iBAAiB;IACjB,WAAW;IACX,gBAAgB;IAChB,aAAa;IACb,eAAe;CAChB,CAAC,CAAC"}