humanish 0.106.1 → 0.107.0

package/dist/actors/codex/protocol-compat.js

@@ -0,0 +1,357 @@
+// The per-launch protocol check: the generated app-server schema against the fields humanish reads
+// and sends (protocol-contract.ts). It checks only those fields. It does not guarantee the rest of
+// the protocol, and it does not attest how the release behaves.
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+const MAX_SCHEMA_FILE_BYTES = 16 * 1024 * 1024;
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+const list = (value) => (Array.isArray(value) ? value : []);
+/** A regular file of at most 16 MiB, checked before it is opened: no pipe, device or link. */
+async function readJson(file) {
+    const info = await lstat(file);
+    if (!info.isFile() || info.size > MAX_SCHEMA_FILE_BYTES)
+        throw new Error(`${file} is not a schema file`);
+    return record(JSON.parse(await readFile(file, "utf8")));
+}
+/** Each method of a ClientRequest or ServerNotification union, with its params definition. */
+function methodParams(union) {
+    const result = new Map();
+    for (const branch of list(union.oneOf)) {
+        const properties = record(record(branch).properties);
+        const method = list(record(properties.method).enum)[0];
+        const ref = record(properties.params).$ref;
+        if (typeof method === "string" && typeof ref === "string")
+            result.set(method, ref.split("/").pop());
+    }
+    return result;
+}
+/**
+ * Reads the files `codex app-server generate-json-schema --experimental` writes: the v2 and full
+ * bundles for definitions, and the ClientRequest and ServerNotification unions for params.
+ */
+export async function loadProtocolSchema(directory) {
+    const definitions = new Map();
+    for (const name of [
+        "codex_app_server_protocol.v2.schemas.json",
+        "codex_app_server_protocol.schemas.json",
+    ]) {
+        const bundle = await readJson(path.join(directory, name));
+        for (const [key, value] of Object.entries(record(bundle.definitions)))
+            if (!definitions.has(key))
+                definitions.set(key, value);
+    }
+    const requests = await readJson(path.join(directory, "ClientRequest.json"));
+    const notifications = await readJson(path.join(directory, "ServerNotification.json"));
+    return {
+        definitions,
+        requestParams: methodParams(requests),
+        notificationParams: methodParams(notifications),
+    };
+}
+/** Types both declarations allow; an integer is a number. */
+function sharedTypes(a, b) {
+    const left = Array.isArray(a) ? a : [a], right = Array.isArray(b) ? b : [b];
+    const shared = new Set();
+    for (const type of left)
+        if (right.includes(type))
+            shared.add(String(type));
+        else if (type === "integer" && right.includes("number"))
+            shared.add("integer");
+        else if (type === "number" && right.includes("integer"))
+            shared.add("integer");
+    return [...shared];
+}
+/**
+ * Two schemas a value must both satisfy, as one: types and fixed values intersect, required fields
+ * add up, and a property, items or additionalProperties both constrain becomes their `allOf`.
+ * False when nothing satisfies both.
+ */
+function intersect(a, b) {
+    if (a === false || b === false)
+        return false;
+    if (a === true)
+        return b;
+    if (b === true)
+        return a;
+    const out = { ...a };
+    for (const [key, value] of Object.entries(b)) {
+        if (!(key in out))
+            out[key] = value;
+        else if (key === "properties") {
+            const merged = { ...record(out.properties) };
+            for (const [name, schema] of Object.entries(record(value)))
+                merged[name] = name in merged ? { allOf: [merged[name], schema] } : schema;
+            out.properties = merged;
+        }
+        else if (key === "required")
+            out.required = [...new Set([...list(out.required), ...list(value)])];
+        else if (key === "type")
+            out.type = sharedTypes(out.type, value);
+        else if (key === "enum")
+            out.enum = list(out.enum).filter((item) => list(value).includes(item));
+        else if (key === "const") {
+            if (out.const !== value)
+                out.enum = [];
+        }
+        else if (key === "items" || key === "additionalProperties")
+            out[key] = { allOf: [out[key], value] };
+        else
+            out[key] = value;
+    }
+    if ("const" in out && "enum" in out) {
+        out.enum = list(out.enum).filter((item) => item === out.const);
+        delete out.const;
+    }
+    const empty = (key) => Array.isArray(out[key]) && list(out[key]).length === 0;
+    return empty("type") || empty("enum") ? false : out;
+}
+/**
+ * A field's schema as the alternatives it may take: `$ref`s followed, `allOf` intersected, and
+ * `anyOf` and `oneOf` expanded, so that each alternative is one plain schema. `false` (no value)
+ * is dropped; `true` (any value) stays.
+ */
+function alternatives(schema, node, seen = new Set()) {
+    if (typeof node === "boolean")
+        return node ? [true] : [];
+    if (typeof node.$ref === "string") {
+        // The full bundle nests v2 definitions (`#/definitions/v2/Name`); the v2 bundle has each by name.
+        const name = node.$ref.split("/").pop();
+        const target = schema.definitions.get(name);
+        if (target === undefined || seen.has(name))
+            return [];
+        return alternatives(schema, target, new Set([...seen, name]));
+    }
+    const own = { ...node };
+    delete own.anyOf;
+    delete own.oneOf;
+    delete own.allOf;
+    let result = [own];
+    for (const member of list(node.allOf)) {
+        const parts = alternatives(schema, member, seen);
+        result = result.flatMap((base) => parts.map((part) => intersect(base, part)));
+    }
+    const union = [...list(node.anyOf), ...list(node.oneOf)];
+    if (union.length > 0)
+        result = result.flatMap((base) => union.flatMap((branch) => alternatives(schema, branch, seen).map((part) => intersect(base, part))));
+    return result.filter((part) => part !== false);
+}
+function kindOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "integer" : "number";
+    return typeof value;
+}
+/** The fixed values an alternative allows, or undefined when it does not fix them. */
+const fixedValues = (node) => node.const !== undefined ? [node.const] : Array.isArray(node.enum) ? node.enum : undefined;
+/** The JSON types an alternative allows; `any` when it constrains none. */
+function typesOf(node) {
+    if (typeof node === "boolean")
+        return new Set(node ? ["any"] : []);
+    const declared = node.type;
+    if (typeof declared === "string")
+        return new Set([declared]);
+    if (Array.isArray(declared))
+        return new Set(declared);
+    const fixed = fixedValues(node);
+    if (fixed !== undefined)
+        return new Set(fixed.map(kindOf));
+    if (node.properties !== undefined)
+        return new Set(["object"]);
+    if (node.items !== undefined)
+        return new Set(["array"]);
+    return new Set(["any"]);
+}
+const accepts = (types, type) => types.has(type) || types.has("any") || (type === "integer" && types.has("number"));
+/** Whether an alternative allows a value humanish compares against or sends. */
+function allows(node, value) {
+    if (typeof node === "boolean")
+        return node;
+    if (!accepts(typesOf(node), kindOf(value)))
+        return false;
+    const fixed = fixedValues(node);
+    return fixed === undefined || fixed.includes(value);
+}
+function property(schema, node, name) {
+    if (typeof node !== "object")
+        return [];
+    const properties = record(node.properties);
+    if (Object.hasOwn(properties, name))
+        return alternatives(schema, properties[name]);
+    const extra = node.additionalProperties;
+    return extra === true || typeof extra === "object" ? alternatives(schema, extra) : [];
+}
+/** Whether a union branch's discriminator `field` is fixed to `value`. */
+function selects(schema, node, field, value) {
+    return property(schema, node, field).some((part) => typeof part === "object" && (fixedValues(part) ?? []).includes(value));
+}
+/**
+ * The alternatives at `path` under a definition, and each container on the way. A step is
+ * `name`, `name[]` (its array items) or `{field=value}` (the union branches with that value).
+ */
+function walk(schema, definition, fieldPath) {
+    const root = schema.definitions.get(definition);
+    let nodes = root === undefined ? [] : alternatives(schema, root);
+    const containers = [];
+    const done = [];
+    for (const segment of fieldPath === "" ? [] : fieldPath.split(".")) {
+        if (done.length > 0)
+            containers.push({ prefix: done.join("."), nodes, kind: "object" });
+        const branch = /^\{([A-Za-z_]+)=([A-Za-z0-9_/-]+)\}$/.exec(segment);
+        if (branch)
+            nodes = nodes.filter((node) => selects(schema, node, branch[1], branch[2]));
+        else {
+            const array = segment.endsWith("[]");
+            const name = array ? segment.slice(0, -2) : segment;
+            nodes = nodes.flatMap((node) => property(schema, node, name));
+            if (array) {
+                containers.push({ prefix: [...done, name].join("."), nodes, kind: "array" });
+                nodes = nodes.flatMap((node) => typeof node === "object" && node.items !== undefined
+                    ? alternatives(schema, node.items)
+                    : []);
+            }
+        }
+        done.push(segment);
+    }
+    return { nodes, containers };
+}
+/** A field's alternatives at `path` under a definition, or none when the field is gone. */
+export function resolveField(schema, definition, fieldPath) {
+    return walk(schema, definition, fieldPath).nodes;
+}
+const show = (value) => (value === null ? "null" : String(value));
+const typesIn = (nodes) => [
+    ...new Set(nodes.flatMap((node) => [...typesOf(node)])),
+];
+/** String values offered at a field, or undefined when an alternative allows any string. */
+function offeredStrings(nodes) {
+    const values = [];
+    for (const node of nodes.filter((entry) => accepts(typesOf(entry), "string"))) {
+        const fixed = typeof node === "object" ? fixedValues(node) : undefined;
+        if (fixed === undefined)
+            return undefined;
+        values.push(...fixed.filter((value) => typeof value === "string"));
+    }
+    return [...new Set(values)];
+}
+/**
+ * A read field: every type the release allows there, and in each container on the way, is one
+ * humanish handles; each compared value is still allowed; values beyond `known` are recorded.
+ * `listed` holds the paths with their own rule, whose types decide for that container.
+ */
+function checkRead(schema, owner, definition, rule, listed, found) {
+    const { nodes, containers } = walk(schema, definition, rule.path);
+    if (nodes.length === 0) {
+        if (!rule.optional)
+            found.incompatibilities.add(`${owner} ${rule.path} is no longer in the schema`);
+        return;
+    }
+    for (const container of containers.filter((entry) => !listed.has(entry.prefix))) {
+        const foreign = typesIn(container.nodes).filter((type) => type !== container.kind);
+        if (foreign.length > 0)
+            found.incompatibilities.add(`${owner} ${container.prefix} now allows ${foreign.join(", ")}; humanish reads ${container.kind}`);
+    }
+    if (rule.types !== undefined) {
+        const accepted = new Set(rule.types);
+        if (accepted.has("number"))
+            accepted.add("integer");
+        const foreign = typesIn(nodes).filter((type) => !accepted.has(type));
+        if (foreign.length > 0)
+            found.incompatibilities.add(`${owner} ${rule.path} now allows ${foreign.join(", ")}; humanish reads ${rule.types.join(" or ")}`);
+    }
+    const missing = (rule.expects ?? []).filter((value) => !nodes.some((node) => allows(node, value)));
+    if (missing.length > 0)
+        found.incompatibilities.add(`${owner} ${rule.path} no longer allows ${missing.map(show).join(", ")}`);
+    const offered = rule.known === undefined ? undefined : offeredStrings(nodes);
+    if (offered === undefined)
+        return;
+    const known = new Set([...rule.known, ...(rule.expects ?? [])]);
+    const added = offered.filter((value) => !known.has(value));
+    if (added.length > 0)
+        found.additions.add(`${owner} ${rule.path} now also allows ${added.join(", ")}`);
+}
+/** A sent field: some alternative still accepts each type and value humanish sends there. */
+function checkSent(schema, owner, definition, rule, found) {
+    const nodes = resolveField(schema, definition, rule.path);
+    const where = rule.path === "" ? owner : `${owner} ${rule.path}`;
+    if (nodes.length === 0) {
+        found.incompatibilities.add(`${where} is no longer accepted`);
+        return;
+    }
+    for (const type of rule.sends)
+        if (!nodes.some((node) => accepts(typesOf(node), type)))
+            found.incompatibilities.add(`${where} no longer accepts ${type}`);
+    for (const value of rule.expects ?? [])
+        if (!nodes.some((node) => allows(node, value)))
+            found.incompatibilities.add(`${where} no longer accepts ${show(value)}`);
+    const fields = rule.fields;
+    if (fields === undefined)
+        return;
+    const required = nodes.flatMap((node) => (typeof node === "object" ? list(node.required) : []));
+    const unsent = [...new Set(required)].filter((field) => typeof field === "string" && !fields.includes(field));
+    if (unsent.length > 0)
+        found.incompatibilities.add(`${where} now requires ${unsent.join(", ")}, which humanish does not send`);
+}
+function checkReads(schema, owner, definition, rules, found) {
+    const listed = new Set(rules.map((rule) => rule.path));
+    for (const rule of rules)
+        checkRead(schema, owner, definition, rule, listed, found);
+}
+/** Checks a generated schema against the contract; any incompatibility refuses the launch. */
+export function checkProtocol(schema, contract) {
+    const found = { incompatibilities: new Set(), additions: new Set() };
+    const present = (name, what) => {
+        if (schema.definitions.has(name))
+            return true;
+        found.incompatibilities.add(`${what} ${name} is no longer in the schema`);
+        return false;
+    };
+    for (const request of contract.requests) {
+        const params = schema.requestParams.get(request.method);
+        if (params === undefined) {
+            found.incompatibilities.add(`${request.method} is no longer a client request`);
+            continue;
+        }
+        for (const rule of request.params)
+            checkSent(schema, `${request.method} request`, params, rule, found);
+        const response = request.response;
+        if (response && present(response.definition, `${request.method}'s response`))
+            checkReads(schema, `${request.method} response`, response.definition, response.reads, found);
+    }
+    for (const message of contract.messages) {
+        if (present(message.definition, `${message.method}'s`))
+            checkReads(schema, message.method, message.definition, message.reads, found);
+        const reply = message.reply;
+        if (reply && present(reply.definition, `${message.method}'s reply`))
+            for (const rule of reply.sends)
+                checkSent(schema, `${message.method} reply`, reply.definition, rule, found);
+    }
+    // The carriers in every notification, including the consumed ones outside ServerNotification.
+    const notifications = new Map(schema.notificationParams);
+    for (const message of contract.messages)
+        if (message.reply === undefined && !notifications.has(message.method))
+            notifications.set(message.method, message.definition);
+    for (const [method, params] of notifications)
+        checkReads(schema, method, params, contract.itemCarriers, found);
+    return { incompatibilities: [...found.incompatibilities], additions: [...found.additions] };
+}
+const listed = (items) => items.length <= 5
+    ? items.join("; ")
+    : `${items.slice(0, 5).join("; ")}; and ${items.length - 5} more`;
+/** The refusal detail for an incompatible release. */
+export function protocolIncompatibilityMessage(cliVersion, incompatibilities) {
+    const release = `Codex CLI${cliVersion === undefined ? "" : ` ${cliVersion}`}`;
+    return incompatibilities.length === 0
+        ? `${release} changed the app-server protocol humanish uses.`
+        : `${release} changed the app-server protocol humanish uses: ${listed(incompatibilities)}.`;
+}
+/** The run warning for schema values beyond the baseline, or undefined when there were none. */
+export function protocolAdditionsWarning(cliVersion, additions) {
+    if (additions === undefined || additions.length === 0)
+        return undefined;
+    return `Codex CLI${cliVersion === undefined ? "" : ` ${cliVersion}`}'s app-server schema has values humanish has not seen: ${listed(additions)}. humanish recorded them and continued.`;
+}

package/dist/actors/codex/protocol-contract.d.ts

@@ -0,0 +1,61 @@
+export type ProtocolPrimitive = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+/** A value humanish compares against or sends. */
+export type ProtocolValue = string | boolean | null;
+/** One field humanish reads. */
+export interface ProtocolFieldRule {
+    /** Dot path under the definition. `name[]` is its array items; `{field=value}` selects a branch. */
+    readonly path: string;
+    /** The types humanish accepts; a release that allows another refuses. Omitted: presence only. */
+    readonly types?: readonly ProtocolPrimitive[];
+    readonly expects?: readonly ProtocolValue[];
+    readonly known?: readonly string[];
+    /** humanish handles the field's absence; when present, its types are still checked. */
+    readonly optional?: boolean;
+}
+/** One field humanish sends: the schema must still accept each type and value it sends there. */
+export interface ProtocolSentField {
+    readonly path: string;
+    readonly sends: readonly ProtocolPrimitive[];
+    readonly expects?: readonly ProtocolValue[];
+    /** For an object: every field humanish sends in it; a field the release newly requires refuses. */
+    readonly fields?: readonly string[];
+}
+interface ProtocolRequest {
+    readonly method: string;
+    readonly params: readonly ProtocolSentField[];
+    /** The response definition, named here because the schema does not link it to its method. */
+    readonly response?: {
+        readonly definition: string;
+        readonly reads: readonly ProtocolFieldRule[];
+    };
+}
+interface ProtocolMessage {
+    /** The notification method, or the server request humanish answers. */
+    readonly method: string;
+    readonly definition: string;
+    readonly reads: readonly ProtocolFieldRule[];
+    /** The answer humanish sends to a server request. */
+    readonly reply?: {
+        readonly definition: string;
+        readonly sends: readonly ProtocolSentField[];
+    };
+}
+export interface ProtocolContract {
+    readonly requests: readonly ProtocolRequest[];
+    readonly messages: readonly ProtocolMessage[];
+    /** Read in every server notification's params (restricted-notifications.ts, notificationItems). */
+    readonly itemCarriers: readonly ProtocolFieldRule[];
+}
+/** What a launch compares against that depends on the launch. */
+export interface ProtocolContractHost {
+    /** The reasoning effort the launch configures and expects back. */
+    readonly reasoningEffort: string;
+    readonly platform: NodeJS.Platform;
+}
+/**
+ * The contract for one launch. config/read's `config` is typed only for some keys; the keys
+ * humanish pins that the schema leaves open are checked at launch by admitsRestrictedCodexConfig,
+ * which compares exact values, so they are not listed here.
+ */
+export declare function protocolContract(host: ProtocolContractHost): ProtocolContract;
+export {};