@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/design/fixtures/DESIGN.golden.md

@@ -1,238 +0,0 @@
----
-name: "Northwind"
-version: "bv_01HQZ"
-generatedAt: "2026-09-08T12:00:00.000Z"
-source: "cohort · branding.getFoundation"
-colors:
-  ink: "#0d0d0d"
-  paper: "#ffffff"
-  primary-moss: "#2d5be3"
-  muted: "#6b7280"
-  accent-amber: "#c9851f"
-  line: "#e7e5e4"
-  primary: "#2d5be3"
-  accent: "#c9851f"
-  success: "#177245"
-  warning: "#c9851f"
-  danger: "#a11d1d"
-  neutral-100: "#f5f5f4"
-  neutral-500: "#78716c"
-  neutral-900: "#1c1917"
-colorsDark:
-  ink: "#f5f5f4"
-  paper: "#0b0b0c"
-  primary-moss: "#7ea0ff"
-  line: "#26262a"
-  primary: "#7ea0ff"
-typography:
-  display: "Outfit"
-  body: "Inter"
-  mono: "JetBrains Mono"
-  heading: "Outfit"
-  scale:
-    display: { size: "76px", weight: 600, leading: 1.05, tracking: -0.02 }
-    heading: { size: "38px", weight: 600, leading: 1.15, tracking: -0.01 }
-    body: { size: "14px", weight: 400, leading: 1.5 }
-    small: { size: "11.5px", weight: 500 }
-    caption: { size: "11px", weight: 500, leading: 1.4, tracking: 0.04 }
-rounded:
-  chip: "8px"
-  field: "9px"
-  card: "13px"
-  modal: "14px"
-  pill: "999px"
-spacing:
-  xs: "4px"
-  sm: "8px"
-  md: "12px"
-  lg: "16px"
-  xl: "22px"
-shadow:
-  sm: "0 1px 2px rgba(13,13,13,0.06)"
-  md: "0 18px 50px rgba(13,13,13,0.13)"
-border:
-  hairline: "1px solid #e7e5e4"
-  strong: "1px solid #d6d3d1"
-components:
-  button:
-    background: "{colors.primary}"
-    foreground: "{colors.paper}"
-    radius: "{rounded.pill}"
-    padding: "{spacing.sm} {spacing.lg}"
-    font: "{typography.body}"
-  card:
-    background: "{colors.paper}"
-    foreground: "{colors.ink}"
-    border: "{border.hairline}"
-    radius: "{rounded.card}"
-    padding: "{spacing.xl}"
-    shadow: "{shadow.md}"
-  input:
-    background: "{colors.paper}"
-    border: "{border.hairline}"
-    radius: "{rounded.field}"
-    padding: "{spacing.sm} {spacing.md}"
-    font: "{typography.body}"
-  surface:
-    background: "{colors.paper}"
-    foreground: "{colors.ink}"
-    muted: "{colors.muted}"
-    radius: "{rounded.modal}"
----
-
-# Northwind — design system
-
-The frontmatter above is the token contract: it is generated from the workspace's
-saved brand foundation and is the source of truth for colour, type, radius and
-spacing. Read it before you pick a value. Component entries are written as
-`{group.key}` refs, so changing a token changes every component that names it.
-
-This file is GENERATED — edits here are overwritten on the next sync. To change
-the foundation itself, propose the change (`design_propose_change`); a human
-reviews and applies it, and the next sync brings it back down.
-
-## Palette
-
-- `{colors.ink}` — #0d0d0d (dark #f5f5f4)
-- `{colors.paper}` — #ffffff (dark #0b0b0c)
-- `{colors.primary-moss}` — #2d5be3 (dark #7ea0ff)
-- `{colors.muted}` — #6b7280
-- `{colors.accent-amber}` — #c9851f
-- `{colors.line}` — #e7e5e4 (dark #26262a)
-- `{colors.primary}` — #2d5be3 (dark #7ea0ff)
-- `{colors.accent}` — #c9851f
-- `{colors.success}` — #177245
-- `{colors.warning}` — #c9851f
-- `{colors.danger}` — #a11d1d
-- `{colors.neutral-100}` — #f5f5f4
-- `{colors.neutral-500}` — #78716c
-- `{colors.neutral-900}` — #1c1917
-
-## Typography
-
-- **display:** Outfit
-- **body:** Inter
-- **mono:** JetBrains Mono
-- **heading:** Outfit
-
-- `{typography.scale.display}` — 76px · weight 600 · leading 1.05 · tracking -0.02
-- `{typography.scale.heading}` — 38px · weight 600 · leading 1.15 · tracking -0.01
-- `{typography.scale.body}` — 14px · weight 400 · leading 1.5
-- `{typography.scale.small}` — 11.5px · weight 500
-- `{typography.scale.caption}` — 11px · weight 500 · leading 1.4 · tracking 0.04
-
-### Type rules
-
-One geometric face for structure, one humanist face for reading.
-
-- Display only above 32px.
-- Never set body copy below 13px.
-
-### Colour rules
-
-- One primary per view.
-- Semantic colour is for state, never decoration.
-
-## Visual language
-
-### Imagery
-
-- **Uses imagery:** yes
-- **Medium:** photography
-- **Secondary media:** diagram
-- **Grade:** natural
-- **Grain:** fine
-- **Crop:** wide
-- **Aspect ratios:** 16/9, 1/1
-- **Subjects:** hands at work, quiet rooms
-- **Mood:** calm, considered
-- **Composition:** off-centre, generous negative space
-- **Duotone:** shadow #12213f · highlight #f3ede1
-
-### Imagery (brand system)
-
-- **Medium:** documentary photography
-- **Style:** unstaged
-- **Treatment:** warm highlights, cool shadows
-- **Mood:** assured
-- **Subjects:** workshops, field crews
-- **Avoid:** stock handshakes, isolated laptops
-
-### Iconography
-
-- **Style:** line
-- **Weight:** 1.5px
-- **Corner:** rounded
-- **Grid:** 24
-
-### Motion
-
-- **Character:** settled
-- **Easing:** cubic-bezier(0.2, 0, 0, 1)
-- **Duration (ms):** 220
-- **Principles:** Move once, arrive., Never animate what a person is reading.
-
-### Texture
-
-- **Surfaces:** paper, frosted glass
-- **Background:** flat
-- **Notes:** No gradients behind text.
-
-### Guardrails
-
-Do:
-
-- Let type carry the page.
-- Use one accent per view.
-
-Do not:
-
-- No stock handshakes.
-- No drop shadows on text.
-
-### Generation seeds
-
-- **Prompt seed:** quiet rooms, natural light, fine grain
-- **Seed locked:** yes
-- **Negative seed:** neon, lens flare
-- **References:** moodboard/2026-03
-- **Source:** generated
-- **Schema version:** 2
-
-## Layout principles
-
-- Left-align everything that reads.
-- One idea per band.
-
-## Marks
-
-- `brandIcon` — set
-- `wordmark` — set
-
-Fetch the bytes with `design_export_kit`; never inline them here.
-
-## Additional tokens
-
-Keys the renderer does not model yet, carried through verbatim so nothing is
-lost between an hq that added a token and an SDK that has not learned it.
-
-```json
-{
-  "elevationCurve": {
-    "0": "none",
-    "1": "0 1px 2px rgba(0,0,0,0.05)"
-  },
-  "examples": {
-    "hero": "A crew at first light.",
-    "cta": "Start the walkthrough"
-  },
-  "gridUnit": 4
-}
-```
-
-## Provenance
-
-- **Version:** V2.7
-- **Version id:** bv_01HQZ
-- **Synced:** 2026-09-08T12:00:00.000Z
-- **Source:** cohort · branding.getFoundation

package/lib/design/fixtures/PRODUCT.golden.md

@@ -1,67 +0,0 @@
----
-name: "Northwind"
-version: "bv_01HQZ"
-generatedAt: "2026-09-08T12:00:00.000Z"
-source: "cohort · branding.getFoundation"
----
-
-# Northwind — product voice
-
-Generated from the workspace's saved brand foundation. It says how this
-product sounds; `DESIGN.md` beside it says how it looks. Read both before
-writing anything a customer sees. Edits here are overwritten on the next
-sync — propose foundation changes with `design_propose_change`.
-
-## Positioning
-
-The operating system for companies that run on agents as well as people.
-
-## Taglines
-
-- Work that runs itself.
-- One company, many hands.
-
-## Voice
-
-Concise, specific, accountable. Write like a capable peer — no hype, no emoji, no hedging.
-
-## Tone
-
-- Plain
-- Exact
-- Unhurried
-- Direct
-
-## Lexicon
-
-Say:
-
-- decide
-- ship
-- owe
-
-Avoid:
-
-- leverage
-- synergy
-- unlock
-
-## In practice
-
-Two invoices need a decision today. Both are under £5,000.
-
-## Motifs
-
-- A single hairline rule.
-- Numbers set in the mono face.
-
-## Iconography
-
-Line icons on a 24px grid, 1.5px stroke.
-
-## Provenance
-
-- **Version:** V2.7
-- **Version id:** bv_01HQZ
-- **Synced:** 2026-09-08T12:00:00.000Z
-- **Source:** cohort · branding.getFoundation

package/lib/design/fixtures/foundation.json

@@ -1,133 +0,0 @@
-{
-  "v": 2,
-  "colors": [
-    { "name": "Ink", "value": "#0d0d0d", "dark": "#f5f5f4" },
-    { "name": "Paper", "value": "#ffffff", "dark": "#0b0b0c" },
-    { "name": "Primary · Moss", "value": "#2d5be3", "dark": "#7ea0ff" },
-    { "name": "Muted", "value": "#6b7280" },
-    { "name": "Accent · Amber", "value": "#c9851f" },
-    { "name": "Line", "value": "#e7e5e4", "dark": "#26262a" }
-  ],
-  "fonts": { "display": "Outfit", "body": "Inter", "mono": "JetBrains Mono" },
-  "type": [
-    { "role": "Display", "size": 76, "weight": 600 },
-    { "role": "Heading", "size": 38, "weight": 600 },
-    { "role": "Body", "size": 14, "weight": 400 },
-    { "role": "Small", "size": 11.5, "weight": 500 }
-  ],
-  "space": [
-    { "name": "xs", "value": 4 },
-    { "name": "sm", "value": 8 },
-    { "name": "md", "value": 12 },
-    { "name": "lg", "value": 16 },
-    { "name": "xl", "value": 22 }
-  ],
-  "radii": [
-    { "name": "chip", "value": 8 },
-    { "name": "field", "value": 9 },
-    { "name": "card", "value": 13 },
-    { "name": "modal", "value": 14 },
-    { "name": "pill", "value": 999 }
-  ],
-  "shadow": [
-    { "name": "sm", "value": "0 1px 2px rgba(13,13,13,0.06)" },
-    { "name": "md", "value": "0 18px 50px rgba(13,13,13,0.13)" }
-  ],
-  "border": [
-    { "name": "hairline", "value": "1px solid #e7e5e4" },
-    { "name": "strong", "value": "1px solid #d6d3d1" }
-  ],
-  "voice": "Concise, specific, accountable. Write like a capable peer — no hype, no emoji, no hedging.",
-  "positioning": "The operating system for companies that run on agents as well as people.",
-  "taglines": ["Work that runs itself.", "One company, many hands."],
-  "toneTraits": ["Plain", "Exact", "Unhurried"],
-  "logos": {
-    "brandIcon": "https://assets.example.test/icon.png",
-    "wordmark": "https://assets.example.test/wordmark.svg",
-    "favicon": null
-  },
-  "examples": { "hero": "A crew at first light.", "cta": "Start the walkthrough" },
-  "visualLanguage": {
-    "v": 2,
-    "source": "generated",
-    "imagery": {
-      "needsImagery": true,
-      "medium": "photography",
-      "secondaryMedia": ["diagram"],
-      "colorGrade": "natural",
-      "grain": "fine",
-      "crop": "wide",
-      "aspectRatios": ["16/9", "1/1"],
-      "subjects": ["hands at work", "quiet rooms"],
-      "mood": ["calm", "considered"],
-      "composition": "off-centre, generous negative space",
-      "duotone": { "shadow": "#12213f", "highlight": "#f3ede1" }
-    },
-    "iconography": { "style": "line", "weight": "1.5px", "corner": "rounded", "grid": 24 },
-    "motion": {
-      "character": "settled",
-      "easing": "cubic-bezier(0.2, 0, 0, 1)",
-      "durationMs": 220,
-      "principles": ["Move once, arrive.", "Never animate what a person is reading."]
-    },
-    "texture": { "surfaces": ["paper", "frosted glass"], "background": "flat", "notes": "No gradients behind text." },
-    "guardrails": {
-      "dos": ["Let type carry the page.", "Use one accent per view."],
-      "donts": ["No stock handshakes.", "No drop shadows on text."]
-    },
-    "promptSeed": "quiet rooms, natural light, fine grain",
-    "seedLocked": true,
-    "negativeSeed": "neon, lens flare",
-    "references": ["moodboard/2026-03"]
-  },
-  "system": {
-    "typography": {
-      "families": {
-        "display": { "family": "Outfit", "category": "sans", "weights": [500, 600] },
-        "heading": { "family": "Outfit", "category": "sans", "weights": [600] },
-        "body": { "family": "Inter", "category": "sans", "weights": [400, 500] },
-        "mono": { "family": "JetBrains Mono", "category": "mono", "weights": [400] }
-      },
-      "scale": [
-        { "role": "Display", "size": 76, "weight": 600, "leading": 1.05, "tracking": -0.02 },
-        { "role": "Heading", "size": 38, "weight": 600, "leading": 1.15, "tracking": -0.01 },
-        { "role": "Body", "size": 14, "weight": 400, "leading": 1.5 },
-        { "role": "Caption", "size": 11, "weight": 500, "leading": 1.4, "tracking": 0.04 }
-      ],
-      "pairingRationale": "One geometric face for structure, one humanist face for reading.",
-      "usageRules": ["Display only above 32px.", "Never set body copy below 13px."]
-    },
-    "color": {
-      "roles": {
-        "primary": { "name": "Signal Blue", "value": "#2d5be3", "dark": "#7ea0ff" },
-        "accent": { "name": "Amber", "value": "#c9851f" }
-      },
-      "neutralRamp": [
-        { "step": 100, "value": "#f5f5f4" },
-        { "step": 500, "value": "#78716c" },
-        { "step": 900, "value": "#1c1917" }
-      ],
-      "semantic": { "success": "#177245", "warning": "#c9851f", "danger": "#a11d1d" },
-      "usageRules": ["One primary per view.", "Semantic colour is for state, never decoration."]
-    },
-    "imagery": {
-      "medium": "documentary photography",
-      "style": "unstaged",
-      "treatment": "warm highlights, cool shadows",
-      "mood": "assured",
-      "subjects": ["workshops", "field crews"],
-      "donts": ["stock handshakes", "isolated laptops"]
-    },
-    "motifs": ["A single hairline rule.", "Numbers set in the mono face."],
-    "iconography": "Line icons on a 24px grid, 1.5px stroke.",
-    "layoutPrinciples": ["Left-align everything that reads.", "One idea per band."],
-    "voice": {
-      "voice": "Concise, specific, accountable.",
-      "toneTraits": ["Plain", "Direct"],
-      "lexicon": { "use": ["decide", "ship", "owe"], "avoid": ["leverage", "synergy", "unlock"] },
-      "exampleCopy": "Two invoices need a decision today. Both are under £5,000."
-    }
-  },
-  "elevationCurve": { "0": "none", "1": "0 1px 2px rgba(0,0,0,0.05)" },
-  "gridUnit": 4
-}

package/lib/design/refresh-gate.test.mjs

@@ -1,144 +0,0 @@
-/**
- * refresh-gate.test.mjs — WHEN a seat re-syncs its brand foundation
- * (WP-M7 mechanic 4). The gate is pure, so every case here is a table row.
- *
- * The two rules worth stating in prose because they are the ones a reader
- * would get wrong:
- *
- *   · An UNKNOWN current version is not a change. The daemon asks the gate
- *     twice per tick — before the read (version unknown) and after it — and if
- *     "unknown" counted as a new version, the pre-read call would say yes on
- *     every tick and the interval would mean nothing.
- *   · A `lastAt` in the FUTURE refreshes. A clock that jumped backwards (or a
- *     state file copied from another box) must not be able to freeze DESIGN.md
- *     on disk until the wall clock catches up.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  isUnversionedFoundation,
-  shouldRefreshDesign,
-  foundationVersion,
-  foundationVersionLabel,
-  DESIGN_REFRESH_INTERVAL_MS,
-  DESIGN_STATE_REL,
-  DESIGN_FILES,
-} from "./refresh-gate.mjs";
-
-const NOW = Date.parse("2026-09-08T12:00:00Z");
-
-test("the interval is 15 minutes and the paths are the ones the CLI and daemon write", () => {
-  assert.equal(DESIGN_REFRESH_INTERVAL_MS, 15 * 60_000);
-  assert.equal(DESIGN_STATE_REL, "state/design/foundation.json");
-  assert.deepEqual(DESIGN_FILES, ["DESIGN.md", "PRODUCT.md"]);
-});
-
-test("never synced → refresh", () => {
-  assert.deepEqual(shouldRefreshDesign({ now: NOW }), { refresh: true, reason: "never" });
-  assert.deepEqual(shouldRefreshDesign({ lastAt: null, now: NOW }), { refresh: true, reason: "never" });
-  assert.deepEqual(shouldRefreshDesign({ lastAt: "not a date", now: NOW }), { refresh: true, reason: "never" });
-});
-
-test("inside the interval with an unchanged version → no refresh", () => {
-  assert.deepEqual(
-    shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW - 60_000, now: NOW }),
-    { refresh: false, reason: "fresh" },
-  );
-});
-
-test("a changed version refreshes immediately, however recent the last sync", () => {
-  assert.deepEqual(
-    shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_2", lastAt: NOW - 1_000, now: NOW }),
-    { refresh: true, reason: "version-changed" },
-  );
-  // First-ever version on a seat that had synced an unversioned org.
-  assert.deepEqual(
-    shouldRefreshDesign({ lastVersion: null, currentVersion: "bv_1", lastAt: NOW - 1_000, now: NOW }),
-    { refresh: true, reason: "version-changed" },
-  );
-});
-
-test("an UNKNOWN current version is not a change — the pre-read call must not always say yes", () => {
-  for (const currentVersion of [null, undefined, "", 7, {}]) {
-    assert.deepEqual(
-      shouldRefreshDesign({ lastVersion: "bv_1", currentVersion, lastAt: NOW - 60_000, now: NOW }),
-      { refresh: false, reason: "fresh" },
-      `currentVersion=${JSON.stringify(currentVersion)}`,
-    );
-  }
-});
-
-test("the interval fires at the boundary and after it, not before", () => {
-  const at = (dt) => shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW - dt, now: NOW });
-  assert.equal(at(DESIGN_REFRESH_INTERVAL_MS - 1).refresh, false);
-  assert.deepEqual(at(DESIGN_REFRESH_INTERVAL_MS), { refresh: true, reason: "interval" });
-  assert.deepEqual(at(DESIGN_REFRESH_INTERVAL_MS * 10), { refresh: true, reason: "interval" });
-});
-
-test("a lastAt in the future refreshes rather than freezing the seat", () => {
-  assert.deepEqual(
-    shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW + 86_400_000, now: NOW }),
-    { refresh: true, reason: "clock-skew" },
-  );
-});
-
-test("lastAt is accepted as an ISO string or epoch ms", () => {
-  const iso = shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: "2026-09-08T11:59:00Z", now: NOW });
-  const ms = shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW - 60_000, now: NOW });
-  assert.deepEqual(iso, ms);
-});
-
-test("a bad or absent intervalMs falls back to the 15-minute default", () => {
-  for (const intervalMs of [undefined, null, 0, -5, NaN, "soon"]) {
-    const r = shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW - 14 * 60_000, now: NOW, intervalMs });
-    assert.equal(r.refresh, false, `intervalMs=${String(intervalMs)}`);
-  }
-  assert.equal(
-    shouldRefreshDesign({ lastVersion: "bv_1", currentVersion: "bv_1", lastAt: NOW - 60_000, now: NOW, intervalMs: 30_000 }).reason,
-    "interval",
-    "an explicit shorter interval is honoured",
-  );
-});
-
-test("foundationVersion prefers headVersionId, then version.id, then a stable 'unversioned'", () => {
-  assert.equal(foundationVersion({ headVersionId: "bv_1", version: { id: "bv_0" }, foundation: {} }), "bv_1");
-  assert.equal(foundationVersion({ headVersionId: null, version: { id: "bv_0" }, foundation: {} }), "bv_0");
-  assert.equal(foundationVersion({ headVersionId: null, version: null, foundation: {} }), "unversioned");
-  assert.equal(foundationVersion({}), null, "a frame with no foundation has no version identity");
-  assert.equal(foundationVersion(null), null);
-  assert.equal(foundationVersion("nope"), null);
-});
-
-test("'unversioned' is STABLE, so an org that never saved a foundation does not re-render every poll", () => {
-  const frame = { headVersionId: null, version: null, foundation: { colors: [] } };
-  const v = foundationVersion(frame);
-  assert.equal(shouldRefreshDesign({ lastVersion: v, currentVersion: foundationVersion(frame), lastAt: NOW - 60_000, now: NOW }).refresh, false);
-});
-
-test("foundationVersionLabel reads the label, falls back to V2.<seq>, and never invents", () => {
-  assert.equal(foundationVersionLabel({ version: { label: "Palette refresh", seq: 7 } }), "Palette refresh");
-  assert.equal(foundationVersionLabel({ version: { seq: 7 } }), "V2.7");
-  assert.equal(foundationVersionLabel({ version: { label: "   " } }), "");
-  assert.equal(foundationVersionLabel({ version: null }), "");
-  assert.equal(foundationVersionLabel(null), "");
-});
-
-test("isUnversionedFoundation catches the frame hq ACTUALLY sends for a workspace with no brand", () => {
-  // hq's `loadSavedFoundation` falls back to `dsDefaults()`, so the foundation
-  // is never null. `unversioned` is the only truthful signal, and an older hq
-  // that omits it is judged by having no version identity at all.
-  const stock = { foundation: { colors: [] }, version: null, headVersionId: null, unversioned: true };
-  assert.equal(isUnversionedFoundation(stock), true);
-  assert.equal(isUnversionedFoundation({ ...stock, unversioned: undefined }), true, "older hq: no version identity of any kind");
-
-  const saved = { foundation: { colors: [] }, version: { id: "bv_1", seq: 3 }, headVersionId: "bv_1", unversioned: false };
-  assert.equal(isUnversionedFoundation(saved), false);
-  // hq is trusted when it states the field, even where retention pruned the
-  // snapshot row and only the etag survives.
-  assert.equal(isUnversionedFoundation({ foundation: {}, version: null, headVersionId: "bv_9", unversioned: false }), false);
-
-  assert.equal(isUnversionedFoundation(null), false, "an absent frame is a read failure, not an unversioned workspace");
-  assert.equal(isUnversionedFoundation({}), false);
-});