@litterthanlit/hypher-cli 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litterthanlit/hypher-cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Hypher bridge for coding agents: hooks, a local outbox, and a truth check against the working tree. Pilot, not yet recorded.",
   "type": "module",
   "bin": {

package/src/env.mjs

@@ -7,7 +7,7 @@ import os from "node:os";
 import path from "node:path";
 
 // Keep equal to package.json; a test checks it.
-export const CLI_VERSION = "0.1.7";
+export const CLI_VERSION = "0.1.8";
 export const DEFAULT_API_BASE = "https://www.hypher.app";
 export const INTEGRATIONS_URL = "https://hypher.app/app/settings/integrations";
 export const API_KEYS_URL = "https://hypher.app/app/settings/api-keys";

package/src/session.mjs

@@ -17,13 +17,18 @@ import {
   renderNoHandoffNote,
   renderUnlinkedLine,
 } from "../vendor/handoffNote.mjs";
-import { buildSealProposal } from "../vendor/handoffSeal.mjs";
-import { parseHandoffProposal } from "../vendor/structuredHandoff.mjs";
+import { buildSealProposal, CLI_UPDATE_COMMAND, readOnlyHandoffMessage } from "../vendor/handoffSeal.mjs";
+import { parseHandoffProposalLenient } from "../vendor/structuredHandoff.mjs";
 
 // The MCP tool first: in an agent's shell `hypher` may be off PATH or inside Codex's sandbox.
 export const ACK_HINT = "call the `acknowledge` tool of the `hypher` MCP server, or run `hypher ack`";
 const NOT_CONNECTED_LINE = "Hypher is not connected on this computer; starting without it. Run `hypher init` in a terminal.";
 
+/** Said at the top of the note when the handoff is newer than this copy of Hypher can save over. */
+export function readOnlyNotice(version) {
+  return `Hypher: this handoff is read-only here. It is format version ${version}, newer than this copy of Hypher can save over, so a save would be refused and nothing would be sent. Use the note as it is. To save again, run \`${CLI_UPDATE_COMMAND}\` in a terminal.`;
+}
+
 /** The agent running this command, from its environment. */
 export function detectAgent(env, fallback) {
   if (env.HYPHER_AGENT) return String(env.HYPHER_AGENT).slice(0, 40);
@@ -104,8 +109,9 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
     return { status: "rejected", note: `Hypher: ${prepared?.error ?? "could not load the handoff"}. Run \`hypher doctor\`.`, snapshot };
   }
 
-  const parsed = parseHandoffProposal(prepared.proposal, { allowPlaceholders: true });
-  if (!parsed.ok) return { status: "rejected", note: "Hypher returned a handoff this CLI cannot read. Update with `hypher init`.", snapshot };
+  // Read leniently: a field, a longer list, or a newer version written by a newer Hypher is not a reason to refuse the note.
+  const parsed = parseHandoffProposalLenient(prepared.proposal);
+  if (!parsed.ok) return { status: "rejected", note: `Hypher returned a handoff this CLI cannot read. Update with \`${CLI_UPDATE_COMMAND}\`.`, snapshot };
   const proposal = parsed.value;
   const verdict = truthCheck(snapshot.root, proposal.repo);
   const savedAt = typeof prepared.savedAt === "number" ? prepared.savedAt : undefined;
@@ -121,6 +127,7 @@ export async function resumeHere({ env, cwd, destination, sessionId, now = Date.
     currentTree: verdict?.current?.tree ?? snapshot.tree,
     checkpoint: shownCheckpoint,
     acknowledge: ACK_HINT,
+    notice: parsed.readOnly ? readOnlyNotice(proposal.schemaVersion) : null,
   });
   updateWorktreeState(env, snapshot.root, (state) => withBranchState({
     ...state,
@@ -174,7 +181,9 @@ export async function sealHere({ env, cwd, seal, agent, now = Date.now() }) {
   if (!state || state.projectId !== link.projectId || typeof state.baseRevision !== "number") {
     return { ok: false, code: "no-base", message: "Run `hypher resume` first, so this save is based on the handoff you read." };
   }
-  const prior = state.proposal ? parseHandoffProposal(state.proposal, { allowPlaceholders: true }) : null;
+  const prior = state.proposal ? parseHandoffProposalLenient(state.proposal) : null;
+  // A newer format than this copy can write: refused before anything is built or sent.
+  if (prior?.ok && prior.readOnly) return { ok: false, code: "read-only", message: readOnlyHandoffMessage(prior.value.schemaVersion) };
   const iso = new Date(now).toISOString().slice(0, 16).replace("T", " ");
   // Checks are bound to the working-tree hash at this save. Without one, the handoff still
   // saves; the checks are left out and the agent is told.

package/vendor/handoffNote.mjs

@@ -135,6 +135,7 @@ function sections(input, max, listLimit) {
         header,
         NOTE_FIRST_REPLY,
         NOTE_PREAMBLE,
+        ...(input.notice ? [noteText(input.notice, 500)] : []),
         input.verdict ? describeVerdict(input.verdict)
             : "Tree: not checked here. Compare the repository, branch, commit, and uncommitted files yourself before continuing.",
         `Constraints: ${joinItems(limit(proposal.constraints), "none recorded.", max)}${more(proposal.constraints)}`,

package/vendor/handoffSeal.mjs

@@ -6,8 +6,17 @@
  * adds a source for this session, and maps short decision references ("D2",
  * or a unique part of the text) to the exact prior text for `supersedes`.
  */
-import { HANDOFF_PROPOSAL_SCHEMA_VERSION, parseHandoffProposal, } from "./structuredHandoff.mjs";
+import { HANDOFF_PROPOSAL_SCHEMA_VERSION, knownFieldsV1, parseHandoffProposal, reattachUnknownFields, } from "./structuredHandoff.mjs";
 export const MAX_HANDOFF_ITEMS = 8;
+/**
+ * What an installed copy runs to update itself. `hypher init` from an installed copy finds itself
+ * already at its own path and keeps the same version; the `@latest` fetch is what updates.
+ */
+export const CLI_UPDATE_COMMAND = "npx @litterthanlit/hypher-cli@latest init";
+/** Why a save on top of a newer-format handoff is refused. One line; nothing was sent. */
+export function readOnlyHandoffMessage(version) {
+    return `This handoff is format version ${version}, newer than this copy of Hypher can save over, so nothing was sent. Update with \`${CLI_UPDATE_COMMAND}\` in a terminal, then save again.`;
+}
 function clean(value) {
     return typeof value === "string" ? value.trim() : "";
 }
@@ -103,11 +112,23 @@ function tooMany(field, count, hint) {
     return `A handoff keeps at most ${MAX_HANDOFF_ITEMS} ${field}; this one would have ${count}. ${hint}`;
 }
 /**
+ * Carry rule: a save sends what it knows plus what it was handed, unchanged. Fields of the prior
+ * handoff that this code does not know are re-attached as they were: the top-level ones always,
+ * and those on a decision, source, or evidence item for as long as that item is carried forward.
+ * They leave with the item when it is replaced or dropped, because its owner was removed on
+ * purpose. Nothing this code did not read is invented or edited, and `repo` is replaced. The
+ * known fields are built only from the seal input and checked by the strict parser; the carried
+ * ones are not checked here, and the server refuses by name what it does not accept. A prior
+ * newer than version 1 is read-only: the save is refused.
+ *
  * @param prior the proposal this session resumed from (null for the first handoff)
  * @param sessionRef a unique label for this session, used as its source
  */
 export function buildSealProposal(input) {
     const { prior, seal } = input;
+    if (prior && prior.schemaVersion !== HANDOFF_PROPOSAL_SCHEMA_VERSION) {
+        return { ok: false, error: readOnlyHandoffMessage(prior.schemaVersion) };
+    }
     const nextAction = clean(seal.nextAction);
     if (!nextAction)
         return { ok: false, error: "The next action is required: nextAction (in a shell, --next \"…\")." };
@@ -200,8 +221,12 @@ export function buildSealProposal(input) {
             return { ok: false, error: tooMany(field, proposal[field].length, "Keep the ones the next agent needs.") };
         }
     }
-    const parsed = parseHandoffProposal(proposal);
+    // The strict parser sees only the fields this code knows; the carried ones go back afterwards.
+    const sendable = knownFieldsV1(proposal);
+    if (!sendable)
+        return { ok: false, error: readOnlyHandoffMessage(proposal.schemaVersion) };
+    const parsed = parseHandoffProposal(sendable);
     if (!parsed.ok)
         return parsed;
-    return { ok: true, proposal: parsed.value };
+    return { ok: true, proposal: reattachUnknownFields(parsed.value, { ...prior, ...proposal }) };
 }

package/vendor/structuredHandoff.mjs

@@ -409,6 +409,248 @@ export function parseHandoffProposal(value, options = {}) {
     }
     return { ok: true, value: proposal };
 }
+const DECISION_KEYS = new Set(["decision", "reason", "status", "sourceRefs", "supersedes"]);
+const SOURCE_KEYS = new Set(["ref", "label", "kind", "sourceId"]);
+const REPO_KEYS = new Set(["repository", "branch", "commit", "dirty", "worktreePath", "dirtyFingerprint"]);
+/** Required text, trimmed, with no length cap. */
+function readText(value, field) {
+    return shortText(value, field, Number.POSITIVE_INFINITY);
+}
+function readTextList(value, field) {
+    if (!Array.isArray(value))
+        return { ok: false, error: `${field} must be an array` };
+    const items = [];
+    for (const item of value) {
+        const parsed = readText(item, field);
+        if (!parsed.ok)
+            return parsed;
+        items.push(parsed.value);
+    }
+    return { ok: true, value: items };
+}
+/** The own fields of `value` that are not in `known`, in their original order. */
+function unknownFieldsOf(value, known) {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !known.has(key)));
+}
+function knownFieldsOnly(value, known) {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => known.has(key)));
+}
+function readRepo(value) {
+    if (!isObject(value))
+        return { ok: false, error: "repo must be an object" };
+    const branch = readText(value.branch, "repo.branch");
+    if (!branch.ok)
+        return branch;
+    const commit = readText(value.commit, "repo.commit");
+    if (!commit.ok)
+        return commit;
+    if (typeof value.dirty !== "boolean")
+        return { ok: false, error: "repo.dirty must be a boolean" };
+    const result = { branch: branch.value, commit: commit.value, dirty: value.dirty };
+    for (const field of ["repository", "worktreePath", "dirtyFingerprint"]) {
+        if (value[field] === undefined)
+            continue;
+        const parsed = readText(value[field], `repo.${field}`);
+        if (!parsed.ok)
+            return parsed;
+        result[field] = parsed.value;
+    }
+    return { ok: true, value: result };
+}
+function readEvidence(value) {
+    if (!Array.isArray(value))
+        return { ok: false, error: "evidence must be an array" };
+    const items = [];
+    for (const item of value) {
+        if (!isObject(item))
+            return { ok: false, error: "evidence must be objects" };
+        const command = readText(item.command, "evidence.command");
+        if (!command.ok)
+            return command;
+        if (typeof item.exitCode !== "number" || !Number.isFinite(item.exitCode)) {
+            return { ok: false, error: "evidence.exitCode must be a number" };
+        }
+        const tree = readText(item.tree, "evidence.tree");
+        if (!tree.ok)
+            return tree;
+        if (item.capturedBy !== "agent" && item.capturedBy !== "hook") {
+            return { ok: false, error: "evidence.capturedBy must be agent or hook" };
+        }
+        if (typeof item.capturedAt !== "number" || !Number.isFinite(item.capturedAt)) {
+            return { ok: false, error: "evidence.capturedAt must be a number" };
+        }
+        items.push({
+            command: command.value,
+            exitCode: item.exitCode,
+            tree: tree.value,
+            capturedBy: item.capturedBy,
+            capturedAt: item.capturedAt,
+            ...unknownFieldsOf(item, EVIDENCE_KEYS),
+        });
+    }
+    return { ok: true, value: items };
+}
+/**
+ * Read a handoff leniently: the reader of a stored handoff, which must not refuse a note because
+ * a newer Hypher wrote a field, a longer list, or a longer line than this code would. For any
+ * input `parseHandoffProposal` accepts, the known fields come out equal. A `schemaVersion` above 1
+ * parses but is flagged `readOnly`: the meaning may have changed, so a writer must not save over
+ * it. A missing, non-integer, or below-1 `schemaVersion` is an error.
+ */
+export function parseHandoffProposalLenient(value) {
+    if (!isObject(value))
+        return { ok: false, error: "proposal must be an object" };
+    const schemaVersion = value.schemaVersion;
+    if (typeof schemaVersion !== "number" || !Number.isInteger(schemaVersion) || schemaVersion < 1) {
+        return { ok: false, error: "proposal.schemaVersion must be a whole number, 1 or higher" };
+    }
+    const goal = readText(value.goal, "goal");
+    if (!goal.ok)
+        return goal;
+    const constraints = readTextList(value.constraints, "constraints");
+    if (!constraints.ok)
+        return constraints;
+    const completed = readTextList(value.completed, "completed");
+    if (!completed.ok)
+        return completed;
+    const unverified = readTextList(value.unverified, "unverified");
+    if (!unverified.ok)
+        return unverified;
+    const blockers = readTextList(value.blockers, "blockers");
+    if (!blockers.ok)
+        return blockers;
+    const nextAction = readText(value.nextAction, "nextAction");
+    if (!nextAction.ok)
+        return nextAction;
+    if (!Array.isArray(value.decisions))
+        return { ok: false, error: "decisions must be an array" };
+    const decisions = [];
+    for (const item of value.decisions) {
+        if (!isObject(item))
+            return { ok: false, error: "decisions must be objects" };
+        const decision = readText(item.decision, "decisions.decision");
+        if (!decision.ok)
+            return decision;
+        const reason = readText(item.reason, "decisions.reason");
+        if (!reason.ok)
+            return reason;
+        const entry = { decision: decision.value, reason: reason.value };
+        if (item.status !== undefined) {
+            if (item.status !== "reported" && item.status !== "approved")
+                return { ok: false, error: "decisions.status is invalid" };
+            entry.status = item.status;
+        }
+        if (item.sourceRefs !== undefined) {
+            const sourceRefs = readTextList(item.sourceRefs, "decisions.sourceRefs");
+            if (!sourceRefs.ok)
+                return sourceRefs;
+            entry.sourceRefs = sourceRefs.value;
+        }
+        if (item.supersedes !== undefined) {
+            const supersedes = readText(item.supersedes, "decisions.supersedes");
+            if (!supersedes.ok)
+                return supersedes;
+            entry.supersedes = supersedes.value;
+        }
+        decisions.push({ ...entry, ...unknownFieldsOf(item, DECISION_KEYS) });
+    }
+    if (!Array.isArray(value.sources))
+        return { ok: false, error: "sources must be an array" };
+    const sources = [];
+    for (const item of value.sources) {
+        if (!isObject(item))
+            return { ok: false, error: "sources must be objects" };
+        const ref = readText(item.ref, "sources.ref");
+        if (!ref.ok)
+            return ref;
+        const source = { ref: ref.value };
+        if (item.label !== undefined) {
+            const label = readText(item.label, "sources.label");
+            if (!label.ok)
+                return label;
+            source.label = label.value;
+        }
+        if (item.kind !== undefined) {
+            if (item.kind !== "agent_report" && item.kind !== "capture" && item.kind !== "agent_event") {
+                return { ok: false, error: "sources.kind is invalid" };
+            }
+            source.kind = item.kind;
+        }
+        if (item.sourceId !== undefined) {
+            const sourceId = readText(item.sourceId, "sources.sourceId");
+            if (!sourceId.ok)
+                return sourceId;
+            source.sourceId = sourceId.value;
+        }
+        sources.push({ ...source, ...unknownFieldsOf(item, SOURCE_KEYS) });
+    }
+    const repo = readRepo(value.repo);
+    if (!repo.ok)
+        return repo;
+    let evidence;
+    if (value.evidence !== undefined) {
+        const read = readEvidence(value.evidence);
+        if (!read.ok)
+            return read;
+        evidence = read.value;
+    }
+    const proposal = {
+        schemaVersion,
+        goal: goal.value,
+        constraints: constraints.value,
+        decisions,
+        completed: completed.value,
+        unverified: unverified.value,
+        blockers: blockers.value,
+        nextAction: nextAction.value,
+        sources,
+        repo: repo.value,
+        ...(evidence !== undefined ? { evidence } : {}),
+        ...unknownFieldsOf(value, PROPOSAL_KEYS),
+    };
+    return { ok: true, value: proposal, readOnly: schemaVersion > HANDOFF_PROPOSAL_SCHEMA_VERSION };
+}
+/**
+ * A read handoff as version 1 with only the fields this code knows: unknown fields are dropped at
+ * the top level and on each decision, source, and evidence item. Null above version 1, whose known
+ * fields may no longer mean what they meant. What a writer sends to be checked by the strict parser.
+ */
+export function knownFieldsV1(read) {
+    if (read.schemaVersion !== HANDOFF_PROPOSAL_SCHEMA_VERSION)
+        return null;
+    return {
+        schemaVersion: HANDOFF_PROPOSAL_SCHEMA_VERSION,
+        goal: read.goal,
+        constraints: read.constraints,
+        decisions: read.decisions.map((item) => knownFieldsOnly(item, DECISION_KEYS)),
+        completed: read.completed,
+        unverified: read.unverified,
+        blockers: read.blockers,
+        nextAction: read.nextAction,
+        sources: read.sources.map((item) => knownFieldsOnly(item, SOURCE_KEYS)),
+        repo: knownFieldsOnly(read.repo, REPO_KEYS),
+        ...(read.evidence ? { evidence: read.evidence.map((item) => knownFieldsOnly(item, EVIDENCE_KEYS)) } : {}),
+    };
+}
+/**
+ * Put back, unchanged, the unknown fields `carrier` held: the top-level ones, and those of each
+ * decision, source, and evidence item. `known` must be what a parse of `knownFieldsV1(carrier)`
+ * returns, or any list built from it, with the same items in the same order: the fields go back
+ * by position. Nothing is invented or edited.
+ */
+export function reattachUnknownFields(known, carrier) {
+    const back = (items, from, keys) => items.map((item, index) => {
+        const owner = from?.[index];
+        return isObject(owner) ? { ...item, ...unknownFieldsOf(owner, keys) } : item;
+    });
+    return {
+        ...known,
+        ...unknownFieldsOf(carrier, PROPOSAL_KEYS),
+        decisions: back(known.decisions, carrier.decisions, DECISION_KEYS),
+        sources: back(known.sources, carrier.sources, SOURCE_KEYS),
+        ...(known.evidence ? { evidence: back(known.evidence, carrier.evidence, EVIDENCE_KEYS) } : {}),
+    };
+}
 export function renderHandoffPacket(proposal) {
     const lines = [
         `Goal: ${proposal.goal}`,
@@ -613,6 +855,30 @@ export function planHandoffDelivery(input) {
         receipt,
     };
 }
+export function headFromRow(projectId, row) {
+    if (!row || typeof row.revision !== "number")
+        return { kind: "none" };
+    const unreadable = (error) => ({ kind: "unreadable", revision: row.revision, error });
+    if (!row.proposal || !row.idempotencyKey || !row.sourceAgent)
+        return unreadable("the stored row is incomplete");
+    const parsed = parseHandoffProposalLenient(row.proposal);
+    if (!parsed.ok)
+        return unreadable(parsed.error);
+    const proposal = knownFieldsV1(parsed.value);
+    if (!proposal)
+        return unreadable(`it is format version ${parsed.value.schemaVersion}, newer than this server reads`);
+    return {
+        kind: "head",
+        head: {
+            projectId,
+            revision: row.revision,
+            idempotencyKey: row.idempotencyKey,
+            proposal,
+            source: row.sourceAgent,
+            savedAt: row.generatedAt,
+        },
+    };
+}
 export function readHandoffCommand(value) {
     if (!isObject(value))
         return { ok: true, command: null };