@chipschat/protocol 0.0.0-stage → 1.0.0

package/dist/src/room-note.d.ts

@@ -0,0 +1,213 @@
+/**
+ * What an agent is told of the room with each turn (ADR 0092): who is in it, how to reach each of
+ * them with an @, and what an @ does.
+ *
+ * Chips knows the room and its rules; a harness knew only what it had heard. So Chips words the
+ * note, once, here, and sends it on `message.new` as `room`: the members, each with the handle
+ * that reaches them, and the note itself for each who takes the turn. The server that sends it,
+ * the conformance fake that plays the server and the SDK that hands it over read the same words.
+ * It no longer says when Chips holds the agents (ADR 0187): the referee's warning says that, when
+ * it matters, in the workspace's own numbers.
+ *
+ * Each agent is listed with the harness it runs on (ADR 0101): "ASCII Art (Jacobian agent,
+ * @ASCIIArt)". A brief that said "Jacobian is the lead" left two agents asking "@Jacobian" in a room
+ * where Jacobian's agent was called ASCII Art.
+ *
+ * A room may have a lead (ADR 0104): the agent that hands out the work, and that Chips hands what
+ * was nobody's turn once the room goes still. The note says who it is, which of the others have a
+ * turn going and how long each has been without one, and, to the one taking the turn, what is
+ * news to it: that it has just joined, who joined since it last spoke, or, to the lead, that this
+ * message is its because it was nobody's. People in a team see all that for themselves; an agent
+ * exists only in its turns, so Chips says it at the top of each. And when older lines of what was
+ * said since its last turn were left out of the turn, it says that too (ADR 0105).
+ *
+ * In a room with other agents, every taker is told it may answer `NO_REPLY` when a message asks
+ * nothing of it now, and the lead that a step handed from one agent to another needs no word from
+ * it (ADR 0109). ASCII Art's OpenClaw agents, named for a step that was theirs later, said "Ready
+ * for J2's updated HTML", and J1, copied on each hand-off, said it again to the next agent.
+ */
+import { z } from "zod";
+import { type JobSpend } from "./spend.js";
+export declare const roomMember: z.ZodObject<{
+    participant_id: z.ZodString;
+    kind: z.ZodEnum<{
+        person: "person";
+        harness: "harness";
+        agent: "agent";
+    }>;
+    name: z.ZodString;
+    harness: z.ZodOptional<z.ZodString>;
+    handle: z.ZodOptional<z.ZodString>;
+    lead: z.ZodOptional<z.ZodLiteral<true>>;
+    time_zone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RoomMember = z.infer<typeof roomMember>;
+export declare const roomWork: z.ZodObject<{
+    participant_id: z.ZodString;
+    minutes: z.ZodInt;
+    step: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RoomWork = z.infer<typeof roomWork>;
+export declare const roomIdle: z.ZodObject<{
+    participant_id: z.ZodString;
+    minutes: z.ZodInt;
+}, z.core.$strip>;
+export type RoomIdle = z.infer<typeof roomIdle>;
+export declare const roomNote: z.ZodObject<{
+    members: z.ZodArray<z.ZodObject<{
+        participant_id: z.ZodString;
+        kind: z.ZodEnum<{
+            person: "person";
+            harness: "harness";
+            agent: "agent";
+        }>;
+        name: z.ZodString;
+        harness: z.ZodOptional<z.ZodString>;
+        handle: z.ZodOptional<z.ZodString>;
+        lead: z.ZodOptional<z.ZodLiteral<true>>;
+        time_zone: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    notes: z.ZodRecord<z.ZodString, z.ZodString>;
+    rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    working: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        participant_id: z.ZodString;
+        minutes: z.ZodInt;
+        step: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    idle: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        participant_id: z.ZodString;
+        minutes: z.ZodInt;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type RoomNote = z.infer<typeof roomNote>;
+/** A member as the server and the fake know them. */
+export interface NoteMember {
+    readonly id: string;
+    readonly kind: "person" | "agent";
+    readonly name: string;
+    /**
+     * For an agent, its harness's name; for a harness waiting under the first name its room holds
+     * for its agent, its own (ADR 0150).
+     */
+    readonly harness?: string | undefined;
+    /** The room's lead (ADR 0104). */
+    readonly lead?: boolean | undefined;
+    /** For a person, the IANA zone of their newest phone (ADR 0157). */
+    readonly timeZone?: string | undefined;
+}
+/** Who has a turn going in the room, and how long the others have been without one (ADR 0104). */
+export interface RoomNow {
+    readonly working: readonly RoomWork[];
+    readonly idle: readonly RoomIdle[];
+}
+/**
+ * What is news to one who takes the turn (ADR 0104), with who did it by name: that it joined the
+ * room and has not spoken there since; who joined since it last spoke there; to the lead, that
+ * the message is its because it was nobody's turn, who said it, and which person to tell; or that
+ * the message is the taker's though nobody @-mentioned it.
+ */
+export interface TakerNews {
+    readonly joined?: {
+        readonly minutes: number;
+        readonly by?: string | undefined;
+        /** Whether the room has files, which the turn lists at their current versions. */
+        readonly files: boolean;
+    };
+    readonly newcomers?: readonly {
+        readonly id: string;
+        readonly by?: string | undefined;
+    }[];
+    readonly nobodys?: {
+        readonly saidBy: string;
+        readonly tell?: string | undefined;
+    };
+    /** That the message is the taker's though it has no @ for it, and who sent it (`yoursWithoutAt`). */
+    readonly yours?: {
+        readonly saidBy: string;
+    };
+    /** That the message went to every agent here, and who sent it (`toEveryAgent`, ADR 0249). */
+    readonly toAll?: {
+        readonly saidBy: string;
+    };
+    /**
+     * How many lines of what was said since its last turn come with this one, when older ones were
+     * left out to fit its harness's budget (ADR 0105).
+     */
+    readonly cut?: {
+        readonly shown: number;
+    };
+}
+/**
+ * The handle that reaches a member among these, with its @: the whole name without spaces, else
+ * the first word, whichever is a handle a text can hold and names them (ADR 0091). Its own case,
+ * so `@OpenClaw2` rather than `@openclaw2`.
+ */
+export declare function noteHandle(member: NoteMember, members: readonly NoteMember[]): string | undefined;
+/**
+ * The members as the note lists them, each with its handle: people first, then agents, each by
+ * name, numbers in order ("OpenClaw 2" before "OpenClaw 10"). Not the order they joined, which two
+ * Chipses can break a tie in differently; this reads the same from both.
+ */
+export declare function roomMembers(members: readonly NoteMember[]): RoomMember[];
+/**
+ * The note for one who takes the turn:
+ *
+ * > In this room: Arjun (person, @Arjun), ASCII Art (Jacobian agent, @ASCIIArt), and you,
+ * > OpenClaw 2 (OpenClaw agent, @OpenClaw2). ASCII Art leads here: it hands out the work, and what
+ * > is nobody's turn goes to it. Working now: O1, 2 minutes in (last step: Editing
+ * > ascii-alphabet.html). Not working: ASCII Art for 3 minutes. This job has spent $1.20 of the
+ * > $3.00 this room allows a job; at $3.00 Chips holds the agents until a person acts. Everyone
+ * > here reads what you write; only those you @-mention act on it. To hand work to an agent or ask
+ * > it something, @-mention it. If a message asks nothing of you now, as when it names a step that
+ * > is yours later, answer NO_REPLY and nothing else: the room shows nothing, and nobody needs to
+ * > hear that you are ready or waiting.
+ *
+ * What is news to the taker comes first (ADR 0104): the lead's "Nobody has this turn", "You joined
+ * this room", "New since your last turn". What the job has spent comes after who is working, when
+ * Chips said (ADR 0117), in a room with other agents or none. The note ends with its rules
+ * (`roomRules`, ADR 0250), the same from turn to turn: with no other agent in the room, only
+ * "Everyone here reads what you write."
+ *
+ * Given the instant the turn is sent (`at`), each person's time there follows the room's line
+ * (ADR 0157): "Arjun's time now: 9:12 am, Tuesday 13 October 2026 (2026-10-13T09:12-07:00,
+ * America/Los_Angeles)." An agent asked for something at 10am, or in 50 minutes, has the date,
+ * the clock and the offset to write it with.
+ */
+export declare function renderRoomNote(members: readonly RoomMember[], youId: string, now?: RoomNow, news?: TakerNews, spend?: JobSpend, at?: string): string;
+/**
+ * How the space works, the words a taker's note ends with (ADR 0250): that everyone here reads what
+ * it writes, and beside other agents, what an @ does and when to answer NO_REPLY. They stay the same
+ * from turn to turn while the space's agents do. Said with every turn, they were a quarter of what a
+ * turn in a busy room carried, and in a session that keeps its turns they piled up, so `message.new`
+ * carries them apart too (`room.rules`) for a harness to say once a session.
+ */
+export declare function roomRules(members: readonly RoomMember[], youId: string): string;
+/**
+ * A taker's note without the rules it ends with (ADR 0250), for a turn whose session already holds
+ * them: the whole note from a Chips that sent no rules, and nothing for a taker with no note.
+ */
+export declare function noteWithoutRules(room: Pick<RoomNote, "notes" | "rules"> | undefined, taker: string): string | undefined;
+export declare const MONTHS: readonly ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+/**
+ * Whether a message is for this taker though it does not @ it (ADR 0081): its sender chose it in
+ * the composer, answered its words, or wrote on to it. Not one for every agent, nor one that
+ * @-mentions it. Its note says so beside other agents, where it otherwise reads that only those
+ * @-mentioned act, and an agent that was not the lead took a person's choice as nobody's turn
+ * (ADR 0104 addendum, 15 October 2026).
+ */
+export declare function yoursWithoutAt(payload: Readonly<Record<string, unknown>>, taker: string): boolean;
+/**
+ * Whether a message went to every agent in the room (ADR 0081's All). Its note says so beside other
+ * agents (ADR 0249), where it otherwise reads that only those @-mentioned act: in a room of four
+ * agents on 30 October 2026 the lead passed a person's question for all of them on with an @ to the
+ * three who already had it, one of them had asked the others the same, and each answered twice.
+ */
+export declare function toEveryAgent(payload: Readonly<Record<string, unknown>>): boolean;
+/**
+ * The room as `message.new` carries it: the members, and a note for each who takes the turn; with
+ * who has a turn going when Chips said (ADR 0104), what is news to each taker, what the job has
+ * spent (ADR 0117), and each person's time at the instant it is sent (`at`, ADR 0157); and the
+ * rules each note ends with (ADR 0250).
+ */
+export declare function roomNoteFor(members: readonly NoteMember[], takers: readonly string[], now?: RoomNow, news?: Readonly<Record<string, TakerNews>>, spend?: JobSpend, at?: string): RoomNote;
+//# sourceMappingURL=room-note.d.ts.map

package/dist/src/room-note.d.ts.map

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