@chipschat/protocol 0.0.0-stage → 1.0.1

package/dist/src/join.js

@@ -0,0 +1,190 @@
+/**
+ * Join requests (ADR 0122): something asks to join Chips, and a person allows it. A harness asks
+ * for a key and the room it starts in; a device asks to be paired. No token is copied by hand.
+ *
+ * Two ways in, one request:
+ *
+ * - **The requester starts.** It sends `POST /v1/join` with no credential and is answered with a
+ *   secret, which only it holds, and a short code, which it shows. An owner or admin compares the
+ *   code, says which of what it asks for it may have, and allows it or not. The requester polls
+ *   `POST /v1/join/:id/redeem` with the secret and is handed its credential once.
+ * - **A person starts.** An owner or admin makes a link, choosing first what the harness may do.
+ *   The link is `<address>/j/<secret>`, good once, for fifteen minutes; whoever holds it redeems
+ *   it at `POST /v1/join/redeem`, already allowed.
+ *
+ * The code is for comparing, not a secret: the 128-bit secret is the credential. Every rule a
+ * client draws from — how long each lasts, how many may wait — is named here once, so the server,
+ * the apps and the SDK cannot disagree.
+ */
+import { z } from "zod";
+import { HARNESS_CAPABILITIES } from "./capabilities.js";
+import { pairingCode } from "./pairing.js";
+import { id, isoTimestamp, workspaceRole } from "./primitives.js";
+/** How long a request a requester started waits for a person: ten minutes. */
+export const JOIN_CODE_SECONDS = 600;
+/** How long a link a person made waits for its harness: fifteen minutes. */
+export const JOIN_LINK_SECONDS = 900;
+/** Requests waiting for a person at once, on one server. The sixth is refused. */
+export const JOIN_WAITING_MAX = 5;
+/** Requests one address may start in a minute. */
+export const JOIN_ASKS_PER_MINUTE = 10;
+/**
+ * How often a requester asks whether it was allowed, in seconds: twenty a minute, under the thirty
+ * a relay lets through a tunnel without a credential.
+ */
+export const JOIN_POLL_SECONDS = 3;
+export const joinKind = z
+    .enum(["harness", "device", "invite", "pairing"])
+    .describe("A harness asking for a key; a device asking to be paired; a person joining by an invite, or a device pairing by a code, that waits for whoever handed it out (ADR 0232).");
+/** The kinds a link makes, which wait for the one person who handed it out (ADR 0232). */
+export const LINK_KINDS = ["invite", "pairing"];
+/** Whether a request is a link's, asked of one person: an invite's, or a pairing code's. */
+export function isLinkKind(kind) {
+    return LINK_KINDS.includes(kind);
+}
+/**
+ * The code a link's request shows (ADR 0232): six digits made from the joining device's key, the
+ * same on the device and on the Allow sheet, for a person to compare.
+ */
+export const keyCode = z.string().regex(/^[0-9]{6}$/, "six digits");
+/** Six digits as people read them: two groups of three. */
+export function keyCodeShown(code) {
+    return keyCode.safeParse(code).success ? `${code.slice(0, 3)} ${code.slice(3)}` : code;
+}
+/** A code a request shows: a requester's to compare or type, or a link's six digits. */
+const requestCode = z.union([pairingCode, keyCode]);
+export const joinState = z
+    .enum(["waiting", "allowed", "denied", "expired", "redeemed"])
+    .describe("`waiting` for a person; `allowed`, and not yet collected; `denied` by a person, or withdrawn; `expired` before it was collected; `redeemed`, which spends it.");
+export const joinStartedBy = z
+    .enum(["requester", "person"])
+    .describe("Who started it: the requester, with a code to compare, or a person, with a link that is allowed already.");
+/** What a person may grant a harness: every capability a harness may take (ADR 0046). */
+export const GRANTABLE = Object.values(HARNESS_CAPABILITIES);
+const capabilities = z
+    .array(z.string().min(1).max(120))
+    .max(64)
+    .describe("Capability names, as `HARNESS_CAPABILITIES` spells them.");
+const words = (most) => z.string().min(1).max(most);
+/** A request as an owner's or admin's client sees it: never the secret. */
+export const joinRequestView = z
+    .object({
+    request_id: id("join"),
+    kind: joinKind,
+    state: joinState,
+    started_by: joinStartedBy,
+    code: requestCode
+        .optional()
+        .describe("The code the requester shows, to compare. A harness's link has none; an invite's or a pairing code's is six digits from the joining device's key (ADR 0232)."),
+    name: words(120)
+        .optional()
+        .describe("What it calls itself. A link's is known once it is redeemed."),
+    software: words(120).optional().describe("Its software and version, as it says."),
+    machine: words(120).optional().describe("The machine it runs on, as it says."),
+    from_addr: words(120).optional().describe("The address it asked from, as Chips saw it."),
+    wants: capabilities.describe("What a harness asked to do. Nothing, for a device."),
+    capabilities: capabilities.describe("What a person allowed it, which may be less than it asked for. Empty until allowed."),
+    url: z
+        .url({ protocol: /^https?$/ })
+        .describe("Where Chips tells the requester to find it: the link's address, or the server's."),
+    decided_by: id("person").optional().describe("Who allowed it, refused it or made the link."),
+    decided_at: isoTimestamp.optional(),
+    created_at: isoTimestamp,
+    expires_at: isoTimestamp.describe("When it stops being good, unless it was redeemed."),
+    harness_id: id("harness").optional().describe("The harness it made, once redeemed."),
+    space_id: id("space")
+        .optional()
+        .describe("The harness's direct room, once redeemed; for an invite, the room it brings the person into."),
+    device_id: id("device").optional().describe("The device it paired, once redeemed."),
+    pair_as: id("person")
+        .optional()
+        .describe("Whom a device is paired as, when the owner who allowed it chose somebody already here (ADR 0206), or the person a pairing code was made for. Absent: the person who allowed it."),
+    role: workspaceRole.optional().describe("For an invite: the role the person joins with."),
+})
+    .describe("A join request, as an owner or admin sees it (ADR 0122).");
+/** `POST /v1/join`: what a requester sends. */
+export const joinAsk = z
+    .object({
+    kind: joinKind.default("harness"),
+    name: words(120).describe("What it calls itself: the harness's or the device's name."),
+    software: words(120).optional(),
+    machine: words(120).optional(),
+    wants: capabilities.optional().describe("For a harness: what it asks to be allowed."),
+    public_key: z
+        .string()
+        .regex(/^[A-Za-z0-9+/]{40,64}={0,2}$/)
+        .optional()
+        .describe("For a device: the public half of its Ed25519 key, SPKI DER, base64."),
+})
+    .describe("A request to join.");
+/** The answer to `POST /v1/join`. */
+export const joinAsked = z.object({
+    request_id: id("join"),
+    secret: z.string().min(16).max(200).describe("The requester's alone: it polls with it."),
+    code: requestCode,
+    expires_in: z.int().positive().describe("Seconds until it expires."),
+    interval: z.int().positive().describe("Seconds between polls."),
+});
+/**
+ * What `POST /v1/invites/redeem` and `POST /v1/pair` answer, `202`, for a link that asks (ADR
+ * 0232): a request that waits for the person who handed the link out, polled as a device's is.
+ */
+export const linkWaiting = joinAsked
+    .extend({ state: z.literal("waiting"), code: keyCode })
+    .describe("A link's request, waiting for the person who handed it out (ADR 0232).");
+/** What a harness is handed once, when its request is redeemed. */
+export const joinedHarness = z.object({
+    kind: z.literal("harness"),
+    url: z.url({ protocol: /^https?$/ }),
+    harness_id: id("harness"),
+    token: z.string().min(16).max(400).describe("Shown once. Chips keeps its digest."),
+    space_id: id("space").optional().describe("The room it speaks in first, with the person."),
+    capabilities,
+});
+/** What a device is handed once, when its request is redeemed. */
+export const joinedDevice = z.object({
+    kind: z.literal("device"),
+    url: z.url({ protocol: /^https?$/ }),
+    device_id: id("device"),
+    participant_id: id("person"),
+    workspace_id: id("workspace"),
+    display_name: words(120),
+    workspace_name: words(120).optional(),
+    server_key: z
+        .string()
+        .min(1)
+        .max(128)
+        .optional()
+        .describe("The server's tunnel key, base64url (ADR 0191): what the device pins, so from here on it reaches the server through the tunnel door on this network and through the relay, and never a plain address again."),
+    role: workspaceRole.optional().describe("For an invite: the role the person joined with."),
+    space_id: id("space").optional().describe("For an invite: the room it put the person in."),
+});
+/** A poll's answer while the request still waits for a person: ask again in `interval`. */
+export const joinPending = z.object({
+    state: z.literal("waiting"),
+    interval: z.int().positive(),
+});
+/** The secret a link carries: URL-safe, at least 128 bits. */
+const SECRET = /^[A-Za-z0-9_-]{22,120}$/;
+/** A link a person hands a harness: the server's address, then `/j/`, then the secret. */
+export function joinLink(base, secret) {
+    return `${base.replace(/\/$/, "")}/j/${secret}`;
+}
+/** A link taken apart: where Chips is, and the secret. Nothing when it is not a join link. */
+export function parseJoinLink(link) {
+    let parsed;
+    try {
+        parsed = new URL(link.trim());
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return undefined;
+    const match = /^(.*)\/j\/([^/]+)\/?$/.exec(parsed.pathname);
+    const secret = match?.[2];
+    if (match === null || secret === undefined || !SECRET.test(secret))
+        return undefined;
+    return { url: `${parsed.origin}${match[1] ?? ""}`, secret };
+}
+//# sourceMappingURL=join.js.map

package/dist/src/join.js.map

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

package/dist/src/limits.d.ts

@@ -0,0 +1,50 @@
+/**
+ * How big an attachment may be (ADR 0047).
+ *
+ * Two numbers decide it. The server has a ceiling, `CHIPS_MAX_ATTACHMENT_BYTES`, which nothing
+ * gets past; under it the workspace may cap photos, videos and files separately, by an event an
+ * owner or an admin sends (`attachment.limits_set`). The arithmetic is here, in the package both
+ * the server and the clients already share, so the phone refuses a file with the sentence the
+ * server would have used, before a byte of it has left the phone.
+ */
+/** The three caps a workspace sets. Audio and everything else that is not a picture is a file. */
+export type CapKind = "image" | "video" | "file";
+export declare const CAP_KINDS: readonly CapKind[];
+/** A cap in bytes for each kind, or `null` for the server's own ceiling. */
+export interface AttachmentCaps {
+    readonly image: number | null;
+    readonly video: number | null;
+    readonly file: number | null;
+}
+export declare const NO_CAPS: AttachmentCaps;
+/**
+ * The longest voice note (ADR 0054): a phone stops recording at it, and the server writes down
+ * what was said in sound no longer than it. Longer sound is kept, with its length and no words.
+ */
+export declare const LONGEST_VOICE_NOTE_MS: number;
+/** The kind a cap is named for, from the kind a MIME type sorts into. */
+export declare function capKind(kind: "image" | "video" | "audio" | "file"): CapKind;
+/** The words each kind goes by on a screen and in a sentence. */
+export declare const CAP_WORDS: Readonly<Record<CapKind, {
+    readonly one: string;
+    readonly many: string;
+}>>;
+/** `50 MB`, `1.5 MB`, `512 KB` — whole megabytes without a decimal, since a cap is usually one. */
+export declare function formatLimit(bytes: number, decimals?: number): string;
+/** The cap that applies to a kind here: the workspace's when it set one under the ceiling, else the ceiling. */
+export declare function attachmentCap(caps: AttachmentCaps, kind: "image" | "video" | "audio" | "file", ceiling: number): number;
+/**
+ * Why a file of this size may not be sent, or nothing when it may. One sentence, the same on
+ * the server and on every client, naming whose limit it is: the workspace's cap, or the server's
+ * ceiling when the workspace set none.
+ */
+export declare function sizeRefusal(caps: AttachmentCaps, kind: "image" | "video" | "audio" | "file", bytes: number, ceiling: number): string | undefined;
+/** A cap above the ceiling is refused when it is set, so no cap in the log is ever a dead letter. */
+export declare function capsOverCeiling(caps: AttachmentCaps, ceiling: number): string | undefined;
+/**
+ * The kind a file's name suggests, for a courtesy before the bytes are seen: a slot refused by
+ * the name's kind saves the upload, and the bytes are judged again by what they turn out to be.
+ * An SVG is a file, as the server serves it.
+ */
+export declare function kindFromName(filename: string): "image" | "video" | "audio" | "file";
+//# sourceMappingURL=limits.d.ts.map

package/dist/src/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,kGAAkG;AAClG,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjD,eAAO,MAAM,SAAS,EAAE,SAAS,OAAO,EAA+B,CAAC;AAExE,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,eAAO,MAAM,OAAO,EAAE,cAAyD,CAAC;AAEhF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAAgB,CAAC;AAEnD,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAE3E;AAED,iEAAiE;AACjE,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAK9F,CAAC;AAKJ,mGAAmG;AACnG,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAK/D;AAED,gHAAgH;AAChH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,EAC1C,OAAO,EAAE,MAAM,GACd,MAAM,CAGR;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,EAC1C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CAapB;AAED,qGAAqG;AACrG,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQzF;AAkBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAOnF"}

package/dist/src/limits.js

@@ -0,0 +1,106 @@
+/**
+ * How big an attachment may be (ADR 0047).
+ *
+ * Two numbers decide it. The server has a ceiling, `CHIPS_MAX_ATTACHMENT_BYTES`, which nothing
+ * gets past; under it the workspace may cap photos, videos and files separately, by an event an
+ * owner or an admin sends (`attachment.limits_set`). The arithmetic is here, in the package both
+ * the server and the clients already share, so the phone refuses a file with the sentence the
+ * server would have used, before a byte of it has left the phone.
+ */
+export const CAP_KINDS = ["image", "video", "file"];
+export const NO_CAPS = { image: null, video: null, file: null };
+/**
+ * The longest voice note (ADR 0054): a phone stops recording at it, and the server writes down
+ * what was said in sound no longer than it. Longer sound is kept, with its length and no words.
+ */
+export const LONGEST_VOICE_NOTE_MS = 5 * 60 * 1000;
+/** The kind a cap is named for, from the kind a MIME type sorts into. */
+export function capKind(kind) {
+    return kind === "image" || kind === "video" ? kind : "file";
+}
+/** The words each kind goes by on a screen and in a sentence. */
+export const CAP_WORDS = {
+    image: { one: "photo", many: "photos" },
+    video: { one: "video", many: "videos" },
+    file: { one: "file", many: "files" },
+};
+const KB = 1024;
+const MB = KB * KB;
+/** `50 MB`, `1.5 MB`, `512 KB` — whole megabytes without a decimal, since a cap is usually one. */
+export function formatLimit(bytes, decimals = 1) {
+    if (bytes < MB)
+        return `${Math.round(bytes / KB)} KB`;
+    const mb = bytes / MB;
+    // "1.0 MB" beside a cap of "1 MB" reads as a bug; a decimal that is all zeros goes.
+    return `${mb.toFixed(decimals).replace(/\.0+$/, "")} MB`;
+}
+/** The cap that applies to a kind here: the workspace's when it set one under the ceiling, else the ceiling. */
+export function attachmentCap(caps, kind, ceiling) {
+    const own = caps[capKind(kind)];
+    return own === null ? ceiling : Math.min(own, ceiling);
+}
+/**
+ * Why a file of this size may not be sent, or nothing when it may. One sentence, the same on
+ * the server and on every client, naming whose limit it is: the workspace's cap, or the server's
+ * ceiling when the workspace set none.
+ */
+export function sizeRefusal(caps, kind, bytes, ceiling) {
+    const cap = attachmentCap(caps, kind, ceiling);
+    if (bytes <= cap)
+        return undefined;
+    const words = CAP_WORDS[capKind(kind)];
+    const capWords = formatLimit(cap);
+    // A size that rounds to the cap's own words is said more finely: "capped at 1 MB, and this
+    // one is 1 MB" reads as a bug.
+    const size = formatLimit(bytes) === capWords ? formatLimit(bytes, 2) : formatLimit(bytes);
+    const own = caps[capKind(kind)];
+    if (own !== null && own <= ceiling) {
+        return `${capitalise(words.many)} here are capped at ${capWords}, and this one is ${size}.`;
+    }
+    return `This server takes ${words.many} up to ${capWords}, and this one is ${size}.`;
+}
+/** A cap above the ceiling is refused when it is set, so no cap in the log is ever a dead letter. */
+export function capsOverCeiling(caps, ceiling) {
+    for (const kind of CAP_KINDS) {
+        const cap = caps[kind];
+        if (cap !== null && cap > ceiling) {
+            return `A cap of ${formatLimit(cap)} on ${CAP_WORDS[kind].many} is more than this server takes (${formatLimit(ceiling)}).`;
+        }
+    }
+    return undefined;
+}
+const IMAGE = new Set([
+    "jpg",
+    "jpeg",
+    "png",
+    "gif",
+    "webp",
+    "heic",
+    "heif",
+    "avif",
+    "bmp",
+    "tif",
+    "tiff",
+]);
+const VIDEO = new Set(["mp4", "m4v", "mov", "webm", "mkv", "avi", "3gp"]);
+const AUDIO = new Set(["mp3", "m4a", "aac", "wav", "ogg", "oga", "flac", "caf", "opus"]);
+/**
+ * The kind a file's name suggests, for a courtesy before the bytes are seen: a slot refused by
+ * the name's kind saves the upload, and the bytes are judged again by what they turn out to be.
+ * An SVG is a file, as the server serves it.
+ */
+export function kindFromName(filename) {
+    const dot = filename.lastIndexOf(".");
+    const extension = dot === -1 ? "" : filename.slice(dot + 1).toLowerCase();
+    if (IMAGE.has(extension))
+        return "image";
+    if (VIDEO.has(extension))
+        return "video";
+    if (AUDIO.has(extension))
+        return "audio";
+    return "file";
+}
+function capitalise(word) {
+    return word.charAt(0).toUpperCase() + word.slice(1);
+}
+//# sourceMappingURL=limits.js.map

package/dist/src/limits.js.map

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

package/dist/src/matters.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether an action matters (ADR 0008, ADR 0036 Gate 5, ADR 0195): it leaves the workspace,
+ * spends money, cannot be undone, or carries one of the hot risk classes. What Chips stops for
+ * at "Ask when it matters", what a lead is never handed, and since ADR 0195 what always waits
+ * for a person: a harness may not settle such an ask itself, a person answers it once (no This
+ * session, no Always), and a rule a person's answer made never allows one.
+ *
+ * Chips goes by what the harness says about the action; it never sees the tool call. Here, so
+ * the server, the conformance kit's fake and the apps read the same sentence.
+ */
+/** The classes that make an action matter: leaving the workspace, money, credentials, destruction. */
+export declare const HOT_RISK: ReadonlySet<string>;
+/** The flags an ask carries about its action, as the harness declared them. */
+export interface ActionFlags {
+    readonly external?: boolean | undefined;
+    readonly irreversible?: boolean | undefined;
+    readonly money_usd?: number | undefined;
+    readonly risk?: readonly string[] | undefined;
+}
+/** Whether the action is one that always waits for a person. */
+export declare function actionMatters(action: ActionFlags): boolean;
+//# sourceMappingURL=matters.d.ts.map

package/dist/src/matters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matters.d.ts","sourceRoot":"","sources":["../../src/matters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,sGAAsG;AACtG,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,MAAM,CAMvC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/C;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAO1D"}

package/dist/src/matters.js

@@ -0,0 +1,26 @@
+/**
+ * Whether an action matters (ADR 0008, ADR 0036 Gate 5, ADR 0195): it leaves the workspace,
+ * spends money, cannot be undone, or carries one of the hot risk classes. What Chips stops for
+ * at "Ask when it matters", what a lead is never handed, and since ADR 0195 what always waits
+ * for a person: a harness may not settle such an ask itself, a person answers it once (no This
+ * session, no Always), and a rule a person's answer made never allows one.
+ *
+ * Chips goes by what the harness says about the action; it never sees the tool call. Here, so
+ * the server, the conformance kit's fake and the apps read the same sentence.
+ */
+/** The classes that make an action matter: leaving the workspace, money, credentials, destruction. */
+export const HOT_RISK = new Set([
+    "external",
+    "external_communication",
+    "destructive",
+    "financial",
+    "credential",
+]);
+/** Whether the action is one that always waits for a person. */
+export function actionMatters(action) {
+    return (action.external === true ||
+        action.irreversible === true ||
+        (action.money_usd ?? 0) > 0 ||
+        (action.risk ?? []).some((risk) => HOT_RISK.has(risk)));
+}
+//# sourceMappingURL=matters.js.map

package/dist/src/matters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matters.js","sourceRoot":"","sources":["../../src/matters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,sGAAsG;AACtG,MAAM,CAAC,MAAM,QAAQ,GAAwB,IAAI,GAAG,CAAC;IACnD,UAAU;IACV,wBAAwB;IACxB,aAAa;IACb,WAAW;IACX,YAAY;CACb,CAAC,CAAC;AAUH,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,MAAmB;IAC/C,OAAO,CACL,MAAM,CAAC,QAAQ,KAAK,IAAI;QACxB,MAAM,CAAC,YAAY,KAAK,IAAI;QAC5B,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC;QAC3B,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CACvD,CAAC;AACJ,CAAC"}

package/dist/src/mentions.d.ts

@@ -0,0 +1,63 @@
+/**
+ * What an `@handle` is, on the wire.
+ *
+ * A message mentions a participant by name — `@Ledger`, `@arjun` — and Chips resolves the
+ * handle to a participant id against the members of the space (M3.3), so a harness can tell a
+ * message addressed to it from one addressed to the room, and a client can draw the chip. The
+ * server that resolves and the clients that render have to agree on what a handle is, so the
+ * rule lives here, with the schemas, and nowhere else.
+ *
+ * A handle is `@` followed by two to sixty of letters, digits, `_`, `-` and `.`, not ending in
+ * a dot or an underscore — so `@Ledger.` at the end of a sentence names Ledger, and so does
+ * `_@Ledger_` in italics — at the start of the text, after a space, or after what opens Markdown's
+ * emphasis, a parenthesis or a quotation: `**@Ledger:**`, `(@Ledger)`, `"@Ledger"`. The apps draw
+ * a mention inside emphasis as one, so the server has to hear it there too (AW-20: a lead's
+ * `**@OpenClaw3:**` drew a mention and reached nobody). After a letter or a digit it is not one,
+ * so an email address names nobody.
+ *
+ * A participant answers to two handles, both case-insensitive: their display name
+ * with its spaces removed, and its first word; `Scout · mini` is `@scout`. The whole name comes
+ * first (ADR 0091): a first word names a participant only where nobody else among them has it,
+ * as a first word or a whole name, so beside "OpenClaw 2", `@OpenClaw` is OpenClaw's.
+ *
+ * `@all` names every agent in the space (ADR 0081), so no participant answers to it.
+ */
+/** Whether a word, without its `@`, is one a text can mention: `OpenClaw2`, not `J` or `Scout·mini`. */
+export declare function isHandle(word: string): boolean;
+/** A fresh, non-global pattern that captures the handle after the `@` in group 1. */
+export declare function mentionPattern(): RegExp;
+/** The handles a text mentions, lowercased, in order, each once. */
+export declare function handlesIn(text: string): string[];
+/** The handle that names every harness in the space rather than one participant. */
+export declare const EVERYONE_HANDLE = "all";
+/** Whether a text says `@all`. */
+export declare function mentionsEveryone(text: string): boolean;
+/**
+ * The handles a participant answers to: the whole name without spaces, and its first word.
+ * Never `all`, which names everyone.
+ */
+export declare function handlesOf(displayName: string): string[];
+export interface Mentionable {
+    readonly id: string;
+    readonly displayName: string;
+    /**
+     * Other names it answers to, after every participant's own: an agent answers to its harness's
+     * name where it is the harness's one agent in the room (ADR 0087's addendum), so `@Jacobian`
+     * still names Jacobian's agent there, whatever the agent is called.
+     */
+    readonly also?: readonly string[] | undefined;
+}
+/**
+ * Who each handle names among these participants (ADR 0091): every whole name first, the first
+ * given winning where two are one (Chips numbers an agent whose name clashes, so only names from
+ * before that can be); then each first word that one participant has and nobody has as a whole
+ * name; then the names a participant is only `also` known by, where nobody answers to them yet. A
+ * first word two participants share names nobody, and no `also` takes it.
+ */
+export declare function handleMap(participants: readonly Mentionable[]): Map<string, string>;
+/**
+ * The participants a text mentions, as ids, in the order the text names them and each once. A
+ * handle nobody answers to is not a mention: it stays plain text on screen.
+ */
+export declare function resolveMentions(text: string, participants: readonly Mentionable[]): string[];
+//# sourceMappingURL=mentions.d.ts.map

package/dist/src/mentions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mentions.d.ts","sourceRoot":"","sources":["../../src/mentions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAUH,wGAAwG;AACxG,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED,qFAAqF;AACrF,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQhD;AAED,oFAAoF;AACpF,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC,kCAAkC;AAClC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAOvD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/C;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAgBnF;AA0BD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,EAAE,CAQ5F"}

package/dist/src/mentions.js

@@ -0,0 +1,129 @@
+/**
+ * What an `@handle` is, on the wire.
+ *
+ * A message mentions a participant by name — `@Ledger`, `@arjun` — and Chips resolves the
+ * handle to a participant id against the members of the space (M3.3), so a harness can tell a
+ * message addressed to it from one addressed to the room, and a client can draw the chip. The
+ * server that resolves and the clients that render have to agree on what a handle is, so the
+ * rule lives here, with the schemas, and nowhere else.
+ *
+ * A handle is `@` followed by two to sixty of letters, digits, `_`, `-` and `.`, not ending in
+ * a dot or an underscore — so `@Ledger.` at the end of a sentence names Ledger, and so does
+ * `_@Ledger_` in italics — at the start of the text, after a space, or after what opens Markdown's
+ * emphasis, a parenthesis or a quotation: `**@Ledger:**`, `(@Ledger)`, `"@Ledger"`. The apps draw
+ * a mention inside emphasis as one, so the server has to hear it there too (AW-20: a lead's
+ * `**@OpenClaw3:**` drew a mention and reached nobody). After a letter or a digit it is not one,
+ * so an email address names nobody.
+ *
+ * A participant answers to two handles, both case-insensitive: their display name
+ * with its spaces removed, and its first word; `Scout · mini` is `@scout`. The whole name comes
+ * first (ADR 0091): a first word names a participant only where nobody else among them has it,
+ * as a first word or a whole name, so beside "OpenClaw 2", `@OpenClaw` is OpenClaw's.
+ *
+ * `@all` names every agent in the space (ADR 0081), so no participant answers to it.
+ */
+const HANDLE = "[a-z0-9_-][a-z0-9_.-]{0,58}[a-z0-9-]";
+/**
+ * Where a handle may begin: the start of the text, after a space or one of `*("'“‘`, or after an
+ * underscore that is not a word's, as italics open: `_@Ledger_`, not `first_@example.com`.
+ */
+const BEFORE = `(?:^|(?<=[\\s*("'\u201C\u2018])|(?<=(?:^|[^a-z0-9])_))`;
+/** Whether a word, without its `@`, is one a text can mention: `OpenClaw2`, not `J` or `Scout·mini`. */
+export function isHandle(word) {
+    return new RegExp(`^${HANDLE}$`, "i").test(word);
+}
+/** A fresh, non-global pattern that captures the handle after the `@` in group 1. */
+export function mentionPattern() {
+    return new RegExp(`${BEFORE}@(${HANDLE})`, "i");
+}
+/** The handles a text mentions, lowercased, in order, each once. */
+export function handlesIn(text) {
+    const found = [];
+    const pattern = new RegExp(`${BEFORE}@(${HANDLE})`, "gi");
+    for (const match of text.matchAll(pattern)) {
+        const handle = match[1].toLowerCase();
+        if (!found.includes(handle))
+            found.push(handle);
+    }
+    return found;
+}
+/** The handle that names every harness in the space rather than one participant. */
+export const EVERYONE_HANDLE = "all";
+/** Whether a text says `@all`. */
+export function mentionsEveryone(text) {
+    return handlesIn(text).includes(EVERYONE_HANDLE);
+}
+/**
+ * The handles a participant answers to: the whole name without spaces, and its first word.
+ * Never `all`, which names everyone.
+ */
+export function handlesOf(displayName) {
+    const trimmed = displayName.trim().toLowerCase();
+    if (trimmed === "")
+        return [];
+    const whole = trimmed.replace(/\s+/g, "");
+    const first = trimmed.split(/\s+/)[0];
+    const handles = whole === first ? [whole] : [whole, first];
+    return handles.filter((handle) => handle !== EVERYONE_HANDLE);
+}
+/**
+ * Who each handle names among these participants (ADR 0091): every whole name first, the first
+ * given winning where two are one (Chips numbers an agent whose name clashes, so only names from
+ * before that can be); then each first word that one participant has and nobody has as a whole
+ * name; then the names a participant is only `also` known by, where nobody answers to them yet. A
+ * first word two participants share names nobody, and no `also` takes it.
+ */
+export function handleMap(participants) {
+    const byHandle = new Map();
+    for (const participant of participants) {
+        const whole = handlesOf(participant.displayName)[0];
+        if (whole !== undefined && !byHandle.has(whole))
+            byHandle.set(whole, participant.id);
+    }
+    const shared = giveFirstWords(byHandle, participants);
+    const also = participants.flatMap((participant) => (participant.also ?? []).flatMap((name) => handlesOf(name).map((handle) => [handle, participant.id])));
+    for (const [handle, id] of also) {
+        if (!byHandle.has(handle) && !shared.has(handle))
+            byHandle.set(handle, id);
+    }
+    return byHandle;
+}
+/**
+ * Each first word one participant has and nobody has as a whole name, given to its participant;
+ * the first words two share, which name nobody, returned.
+ */
+function giveFirstWords(byHandle, participants) {
+    const firsts = new Map();
+    for (const participant of participants) {
+        const handles = handlesOf(participant.displayName);
+        const first = handles[1] ?? handles[0];
+        if (first === undefined)
+            continue;
+        firsts.set(first, (firsts.get(first) ?? new Set()).add(participant.id));
+    }
+    const shared = new Set();
+    for (const [first, ids] of firsts) {
+        if (byHandle.has(first))
+            continue;
+        if (ids.size === 1)
+            byHandle.set(first, [...ids][0]);
+        else
+            shared.add(first);
+    }
+    return shared;
+}
+/**
+ * The participants a text mentions, as ids, in the order the text names them and each once. A
+ * handle nobody answers to is not a mention: it stays plain text on screen.
+ */
+export function resolveMentions(text, participants) {
+    const byHandle = handleMap(participants);
+    const ids = [];
+    for (const handle of handlesIn(text)) {
+        const id = byHandle.get(handle);
+        if (id !== undefined && !ids.includes(id))
+            ids.push(id);
+    }
+    return ids;
+}
+//# sourceMappingURL=mentions.js.map

package/dist/src/mentions.js.map

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