harnery 0.34.0 → 0.35.0

package/src/lib/browser/standalone-html.ts

@@ -0,0 +1,312 @@
+// Self-contained HTML snapshots for `harn browse` trio mode.
+//
+// `page.content()` serializes the DOM but not the resources it points at, and
+// framework pages reference those with root-absolute paths (`/_next/static/…`).
+// Written to a file and reopened from anywhere else — the files origin, another
+// host, `file://` — every one of those paths resolves against the wrong root and
+// 404s, so the snapshot renders as unstyled black-on-white text with broken
+// images. That is what an operator sees when they preview an artifact's `.html`.
+//
+// This rewrite makes the saved document stand on its own:
+//   - stylesheets are fetched and inlined as <style>
+//   - fonts, images, and icons are inlined as data: URIs under a byte budget
+//   - anything left over (too large, cross-origin, unreachable) is rewritten to
+//     an absolute URL on the captured origin rather than left root-relative
+//   - <script> and preload/prefetch hints are dropped: none of them can work in
+//     a snapshot, and a dead script tag only invites a hydration attempt
+//
+// The live page is untouched — everything happens on a clone of the document.
+
+/** Byte budget for one inlined sub-resource. Larger ones stay as absolute URLs. */
+export const DEFAULT_MAX_RESOURCE_BYTES = 512 * 1024;
+
+/** Byte budget for all inlined sub-resources in one snapshot. */
+export const DEFAULT_MAX_TOTAL_RESOURCE_BYTES = 8 * 1024 * 1024;
+
+export interface StandaloneHtmlRequest {
+  maxResourceBytes: number;
+  maxTotalResourceBytes: number;
+}
+
+export interface StandaloneHtmlResult {
+  html: string;
+  /** Source URL the snapshot was taken from. */
+  source: string;
+  /** Stylesheets inlined as <style>. */
+  stylesheetsInlined: number;
+  /** Stylesheets left as absolute <link> (unreachable or cross-origin). */
+  stylesheetsLinked: number;
+  /** Sub-resources (fonts, images, icons) inlined as data: URIs. */
+  resourcesInlined: number;
+  /** Sub-resources left as absolute URLs (over budget or unreachable). */
+  resourcesLinked: number;
+  /** Bytes of sub-resource payload inlined. */
+  inlinedBytes: number;
+}
+
+export function buildStandaloneHtmlScript(): (
+  args: StandaloneHtmlRequest,
+) => Promise<StandaloneHtmlResult> {
+  return async ({ maxResourceBytes, maxTotalResourceBytes }) => {
+    const SKIP = /^(?:data:|blob:|javascript:|mailto:|tel:|sms:|about:|#)/i;
+    const base = document.baseURI;
+
+    let inlinedBytes = 0;
+    let resourcesInlined = 0;
+    let resourcesLinked = 0;
+    let stylesheetsInlined = 0;
+    let stylesheetsLinked = 0;
+
+    const absolute = (url: string, from: string): string | null => {
+      try {
+        return new URL(url, from).href;
+      } catch {
+        return null;
+      }
+    };
+
+    const dataUriCache = new Map<string, string | null>();
+
+    /** Fetch a resource as a data: URI, or null when it is unreachable or over budget. */
+    const toDataUri = async (url: string): Promise<string | null> => {
+      const cached = dataUriCache.get(url);
+      if (cached !== undefined) return cached;
+      let result: string | null = null;
+      try {
+        const res = await fetch(url, { credentials: "include" });
+        if (res.ok) {
+          const buf = await res.arrayBuffer();
+          const fits =
+            buf.byteLength <= maxResourceBytes &&
+            inlinedBytes + buf.byteLength <= maxTotalResourceBytes;
+          if (fits) {
+            const bytes = new Uint8Array(buf);
+            let binary = "";
+            const chunk = 0x8000;
+            for (let i = 0; i < bytes.length; i += chunk) {
+              binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+            }
+            const type = (res.headers.get("content-type") ?? "").split(";")[0]?.trim();
+            result = `data:${type || "application/octet-stream"};base64,${btoa(binary)}`;
+            inlinedBytes += buf.byteLength;
+          }
+        }
+      } catch {
+        result = null;
+      }
+      dataUriCache.set(url, result);
+      return result;
+    };
+
+    /** Resolve one reference: data: URI when it fits, absolute URL otherwise. */
+    const resolveRef = async (
+      raw: string,
+      from: string,
+      inline: boolean,
+    ): Promise<string | null> => {
+      const trimmed = raw.trim();
+      if (!trimmed || SKIP.test(trimmed)) return null;
+      const url = absolute(trimmed, from);
+      if (!url) return null;
+      if (!inline) return url;
+      const dataUri = await toDataUri(url);
+      if (dataUri) {
+        resourcesInlined += 1;
+        return dataUri;
+      }
+      resourcesLinked += 1;
+      return url;
+    };
+
+    /** Rewrite url() and @import references inside a stylesheet against its own URL. */
+    const rewriteCss = async (css: string, from: string): Promise<string> => {
+      const urlRef = /url\(\s*(['"]?)([^'")]*)\1\s*\)/g;
+      const importRef = /@import\s+(['"])([^'"]+)\1/g;
+
+      const replacements = new Map<string, string>();
+      const collect = async (pattern: RegExp, inline: boolean) => {
+        pattern.lastIndex = 0;
+        const seen: string[] = [];
+        for (let m = pattern.exec(css); m; m = pattern.exec(css)) {
+          const raw = m[2];
+          if (raw !== undefined && !replacements.has(raw)) seen.push(raw);
+        }
+        for (const raw of seen) {
+          const resolved = await resolveRef(raw, from, inline);
+          if (resolved) replacements.set(raw, resolved);
+        }
+      };
+      await collect(urlRef, true);
+      await collect(importRef, false);
+
+      return css
+        .replace(urlRef, (full, _q, raw: string) => {
+          const next = replacements.get(raw);
+          return next ? `url("${next}")` : full;
+        })
+        .replace(importRef, (full, _q, raw: string) => {
+          const next = replacements.get(raw);
+          return next ? `@import "${next}"` : full;
+        });
+    };
+
+    const doc = document.cloneNode(true) as Document;
+
+    // Nothing executable survives a snapshot; leaving these in only produces
+    // console noise and a doomed hydration pass on reopen.
+    for (const node of Array.from(doc.querySelectorAll("script, base"))) node.remove();
+    const deadHints = 'link[rel~="preload"],link[rel~="modulepreload"],link[rel~="prefetch"]';
+    for (const node of Array.from(doc.querySelectorAll(deadHints))) node.remove();
+
+    // Stylesheets: fetch → inline. Falls back to the CSSOM (which covers rules a
+    // same-origin sheet already parsed) and finally to an absolute <link>.
+    for (const link of Array.from(doc.querySelectorAll('link[rel~="stylesheet"]'))) {
+      const href = link.getAttribute("href");
+      const url = href ? absolute(href, base) : null;
+      if (!url) {
+        link.remove();
+        continue;
+      }
+      let css: string | null = null;
+      try {
+        const res = await fetch(url, { credentials: "include" });
+        if (res.ok) css = await res.text();
+      } catch {
+        css = null;
+      }
+      if (css === null) {
+        for (const sheet of Array.from(document.styleSheets)) {
+          if (sheet.href !== url) continue;
+          try {
+            css = Array.from(sheet.cssRules)
+              .map((rule) => rule.cssText)
+              .join("\n");
+          } catch {
+            css = null;
+          }
+          break;
+        }
+      }
+      if (css === null) {
+        link.setAttribute("href", url);
+        stylesheetsLinked += 1;
+        continue;
+      }
+      const style = doc.createElement("style");
+      style.setAttribute("data-harnery-inlined-from", url);
+      const media = link.getAttribute("media");
+      if (media) style.setAttribute("media", media);
+      style.textContent = await rewriteCss(css, url);
+      link.replaceWith(style);
+      stylesheetsInlined += 1;
+    }
+
+    // Inline <style> blocks carry their own relative refs (framework @font-face
+    // rules in particular), so they need the same treatment.
+    for (const style of Array.from(doc.querySelectorAll("style"))) {
+      if (style.hasAttribute("data-harnery-inlined-from")) continue;
+      const css = style.textContent;
+      if (css) style.textContent = await rewriteCss(css, base);
+    }
+
+    // Stylesheets adopted via CSSOM never appear in the DOM and would be lost.
+    const adopted = (document as Document & { adoptedStyleSheets?: CSSStyleSheet[] })
+      .adoptedStyleSheets;
+    if (adopted?.length) {
+      const parts: string[] = [];
+      for (const sheet of adopted) {
+        try {
+          parts.push(
+            Array.from(sheet.cssRules)
+              .map((rule) => rule.cssText)
+              .join("\n"),
+          );
+        } catch {
+          // Constructed sheet with unreadable rules; nothing to recover.
+        }
+      }
+      if (parts.length) {
+        const style = doc.createElement("style");
+        style.setAttribute("data-harnery-adopted", "");
+        style.textContent = await rewriteCss(parts.join("\n"), base);
+        doc.head?.appendChild(style);
+      }
+    }
+
+    // Element references. Media and icons are worth inlining; navigation targets
+    // only need to stop pointing at the wrong root.
+    const inlineAttrs: Array<[string, string]> = [
+      ["img", "src"],
+      ["source", "src"],
+      ["video", "src"],
+      ["video", "poster"],
+      ["audio", "src"],
+      ["track", "src"],
+      ["input", "src"],
+      ["object", "data"],
+      ['link[rel~="icon"]', "href"],
+      ['link[rel~="apple-touch-icon"]', "href"],
+      ["image", "href"],
+      ["use", "href"],
+    ];
+    const absoluteAttrs: Array<[string, string]> = [
+      ["a", "href"],
+      ["area", "href"],
+      ["form", "action"],
+      ["iframe", "src"],
+      ["embed", "src"],
+      ["link", "href"],
+    ];
+
+    const applyAttrs = async (specs: Array<[string, string]>, inline: boolean) => {
+      for (const [selector, attr] of specs) {
+        for (const el of Array.from(doc.querySelectorAll(selector))) {
+          const raw = el.getAttribute(attr);
+          if (!raw) continue;
+          const next = await resolveRef(raw, base, inline);
+          if (next) el.setAttribute(attr, next);
+        }
+      }
+    };
+    await applyAttrs(inlineAttrs, true);
+    await applyAttrs(absoluteAttrs, false);
+
+    // srcset is a comma-separated list of `url descriptor` pairs.
+    for (const el of Array.from(doc.querySelectorAll("img[srcset], source[srcset]"))) {
+      const raw = el.getAttribute("srcset");
+      if (!raw) continue;
+      const rewritten: string[] = [];
+      for (const candidate of raw.split(",")) {
+        const parts = candidate.trim().split(/\s+/);
+        const url = parts.shift();
+        if (!url) continue;
+        const next = (await resolveRef(url, base, true)) ?? url;
+        rewritten.push([next, ...parts].join(" "));
+      }
+      if (rewritten.length) el.setAttribute("srcset", rewritten.join(", "));
+    }
+
+    // Inline style attributes can carry background-image url().
+    for (const el of Array.from(doc.querySelectorAll("[style]"))) {
+      const raw = el.getAttribute("style");
+      if (!raw?.includes("url(")) continue;
+      el.setAttribute("style", await rewriteCss(raw, base));
+    }
+
+    const provenance = doc.createElement("meta");
+    provenance.setAttribute("name", "harnery:snapshot-source");
+    provenance.setAttribute("content", location.href);
+    doc.head?.prepend(provenance);
+
+    const doctype = document.doctype ? `<!DOCTYPE ${document.doctype.name}>` : "<!DOCTYPE html>";
+    return {
+      html: `${doctype}\n${doc.documentElement.outerHTML}\n`,
+      source: location.href,
+      stylesheetsInlined,
+      stylesheetsLinked,
+      resourcesInlined,
+      resourcesLinked,
+      inlinedBytes,
+    };
+  };
+}

package/src/lib/instructions/apply.ts

@@ -99,6 +99,7 @@ function blockSkills(projectRoot: string, adapter: string): BlockSkills {
     decide: supported && !exclude.has("harn-decide"),
     council: supported && !exclude.has("harn-council"),
     end: supported && !exclude.has("harn-end"),
+    team: supported && !exclude.has("harn-team"),
   };
 }
 

package/src/lib/instructions/templates.ts

@@ -34,6 +34,8 @@ export interface BlockSkills {
   council: boolean;
   /** the `harn-end` skill file is present */
   end: boolean;
+  /** the `harn-team` skill file is present */
+  team: boolean;
 }
 
 /**
@@ -50,7 +52,7 @@ export interface BlockSkills {
  */
 export function renderInstructionsBlock(
   binName: string,
-  skills: BlockSkills = { decide: true, council: true, end: true },
+  skills: BlockSkills = { decide: true, council: true, end: true, team: true },
 ): string {
   const b = binName;
 
@@ -58,6 +60,7 @@ export function renderInstructionsBlock(
     skills.decide && "`harn-decide`",
     skills.council && "`harn-council`",
     skills.end && "`harn-end`",
+    skills.team && "`harn-team`",
   ].filter(Boolean) as string[];
   const deeper =
     named.length > 0
@@ -72,6 +75,9 @@ export function renderInstructionsBlock(
   const endPointer = skills.end
     ? "When the whole session is genuinely finished, use the `harn-end` skill as the final workflow."
     : `When the whole session is genuinely finished, run \`${b} agents status --end-turn --end-session\` as the final tool action.`;
+  const teamPointer = skills.team
+    ? "The `harn-team` skill owns the tier choice, the governor artifacts, and the drive loop."
+    : `See \`${b} governor --help\` for the tier choice and the drive loop.`;
   // Render the journal categories from the canonical enum so this prose can
   // never drift from what `journal add` actually accepts (the "note, plan…" list
   // silently lagged the tool by two categories before this).
@@ -115,6 +121,7 @@ first when one pass will do, the second when the objective must outlive the
 attempt, and the third when a human would otherwise have to babysit the loop. A
 run that needs authorization parks durably instead of failing, so check
 \`${b} approval list\` when one appears to be waiting rather than stuck.
+${teamPointer}
 
 **Durable role handoff.** When you are replacing a prior session in the same
 named role, run \`${b} agents identity assume <name>\` before declaring your task.
@@ -123,9 +130,10 @@ live process still holds the name; never hand-edit Harnery's history, heartbeat,
 or derived identity cache.
 
 **Declare intent on shell commands.** Every command you run is captured to the
-coordination ledger. Lead a shell command with a \`# intent: <why>\` comment (or set
-the tool's description) so the recorded event carries a reason instead of
-\`(no intent)\`.
+coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
+\`# intent: <why>\` comment (or set the tool's description) so the recorded event
+carries a reason instead of \`(no intent)\`; the [tool-intent
+guide](https://harnery.com/guides/tool-intent/) owns the details.
 
 **Journal.** \`${b} journal add <category> "<text>"\` (category = ${journalCats})
 leaves breadcrumbs that survive context compaction;
@@ -370,6 +378,131 @@ explicitly identifies it. Use the web control or \`${b} agents end --instance-id
 durably queues the end for its current turn.`;
 }
 
+function teamBody(b: string): string {
+  return `Harnery gives you three ways to put more than one agent on a job. They differ
+by how long the objective outlives a single execution, and picking the wrong one
+is the usual reason a team spins. This skill owns that choice, the files a
+governed team needs, and the drive loop.
+
+## Step 0: do not build a second team
+
+Run this before anything else, every time:
+
+\`\`\`bash
+${b} governor list
+\`\`\`
+
+If a goal already covers the objective, **you are done building** — drive the
+existing one (Step 3). A second team pointed at the same tree fights the first:
+both hold the same files and their frozen missions contradict each other. It is
+the most expensive mistake available here, and it looks like progress while you
+make it. Listings are tolerant: an unreadable record prints a warning row with
+its id, which is evidence the goal *exists* — inspect it before creating a
+replacement. Treat stale or suffixed experiment goals as shared runtime state;
+archiving them is an operator call, not yours.
+
+## Step 1: pick the tier
+
+Match the tier to how long the objective must survive, not to how big it feels.
+
+| Surface | Use when | Dies when |
+|---|---|---|
+| \`${b} run <script>\` | One bounded pass: deterministic JS stages fan out to headless subagents. | The pass ends. Nothing remembers it. |
+| \`${b} work create <title> <workflow>\` | The objective must outlive the attempt: retries, failures, review rounds. | You accept or cancel it. |
+| \`${b} governor create\` | A graph of interdependent work with distinct roles, where a human would otherwise babysit the loop. | You accept the root or it exhausts its bounds. |
+
+When unsure, start with \`${b} run\`: it is the only tier you can throw away for
+free, and iterating a script there before freezing it is how you avoid
+invalidating a durable work item later. And check the sizing first: a single
+agent often matches a team on a task that does not truly decompose — reliability
+is multiplicative across steps, and the metric that decides is cost per
+completed task, not agent count.
+
+## Step 2: build the governor team
+
+Four artifacts, kept in a managed workspace
+(\`${b} artifacts create <slug> --purpose "<why>"\`), then frozen:
+
+**team.json** maps specialist id to profile: \`instructions\` (the role's whole
+charter) plus optional \`adapter\`, \`effort\`, \`maxAttempts\`. Two role rules
+carry most of the value: **split producing evidence from judging it** (a
+verifier that runs gates, a separate reviewer that accepts or refuses — no agent
+grades its own homework), and **add a standing scope-auditor** that reports at
+each milestone whether the finish line moved, since no one else is positioned to
+notice a rising bar. Write each role's hard boundaries explicitly, in the
+negative: name every act that is somebody else's. Write every brief as a
+four-part contract — objective, output (the named artifact that proves it),
+tools, boundaries — and pass references, not pasted content. \`timeoutMs\` and
+\`maxTurns\` are workflow-script options, never specialist-profile keys; the
+create command rejects unsupported keys with the offending key and the allowed
+set.
+
+**mission.json** carries \`objective\`, \`acceptance\` (criteria), and
+\`max_milestones\`. Write acceptance so **refusing is a representable outcome**
+("X exists, or the blocker is stated with its citation") — a criterion an agent
+cannot satisfy by correctly refusing gets reissued forever. Every criterion
+names the artifact that satisfies it (a path, a passing command, a review
+record); a criterion satisfiable by prose will eventually be satisfied exactly
+that way.
+
+**replanning.json** freezes the planner policy: \`planner_specialist\`,
+\`auto_apply\`, \`max_replans\`, \`max_work_items_per_plan\`,
+\`max_total_work_items\`, a \`templates\` catalog, and \`review\` with
+\`reviewer_specialists\` and \`max_revision_rounds\`. Keep \`auto_apply: false\`
+and proof auto-acceptance off for anything that can touch public state.
+
+**Workflow templates** are the plain-JS scripts the planner may choose from;
+route product decisions to a decision-brief template, never an implement one.
+Authoring traps (frozen script hashes, the five-minute \`timeoutMs\` default,
+schema caps, child sandboxes) live in the
+[workflow-authoring guide](https://harnery.com/guides/workflow-authoring/).
+
+\`\`\`bash
+${b} governor create --id <goal-id> --title "<title>" \\
+  --team <ws>/team.json --mission <ws>/mission.json \\
+  --replanning <ws>/replanning.json --max-parallel-work 2 --json
+\`\`\`
+
+## Step 3: drive it
+
+\`${b} governor show <goal-id> --json\` — the \`projection\` object is the whole
+dashboard: read \`state\`, \`reason\`, and \`next_action\`, then do exactly that
+action. Useful fields: \`ready_work\` / \`retryable_work\` / \`attention_work\`,
+\`decision_blocked_work\` (parked on a docket entry, not broken),
+\`replans_used\` / \`replans_remaining\`, and the milestone counters.
+
+\`\`\`bash
+${b} governor tick <goal-id>   # at most one scheduling cycle
+${b} governor run <goal-id>    # cycles until success, attention, or budget
+${b} approval list             # a run needing authorization parks, not fails
+\`\`\`
+
+Rules that prevent stranded work:
+
+- **Never drive a governed item with \`${b} work retry\` or \`${b} work run\`.**
+  Only the governor supplies the frozen specialist map; a bare retry starts a
+  run with no team, dies at the first specialist stage, and still burns the
+  attempt. \`${b} work retry\` is for standalone work only.
+- **A blocked item cannot be accepted.** When its objective was met out of band,
+  the door back is \`${b} work reopen\` plus a fresh governor cycle, not accept.
+- **Read the spin signals before retrying.** Zero milestones with climbing
+  \`replans_used\` and repeated reviewer rejections means the mission prose or
+  acceptance criteria are wrong, not the agents. Replans are capped; diagnose
+  first.
+- **A frozen mission cannot be edited** — deliberately. Pass corrections as
+  retry context on individual items, or create a new goal and cancel the old
+  one. Do not keep re-planning against prose you know is stale.
+- **"ended without terminal evidence"** means the child died before writing its
+  proof, not that the work failed. Check whether the outcome landed before
+  redoing it.
+
+## Reporting back
+
+Tell the operator which tier you chose and why, the goal id, the roles, and the
+single next action. If you declined to build a team because one already existed,
+say that first; it is the most useful sentence in the reply.`;
+}
+
 export const SKILLS: SkillTemplate[] = [
   {
     id: "harn-decide",
@@ -407,4 +540,16 @@ export const SKILLS: SkillTemplate[] = [
         body: endBody(binName),
       }),
   },
+  {
+    id: "harn-team",
+    relPath: "harn-team/SKILL.md",
+    render: (binName) =>
+      buildOwnedSkill({
+        name: "harn-team",
+        description:
+          "Stand up and drive a multi-agent team on an objective: pick between a bounded run, durable work, and a governed role team; build the governor artifacts; drive off projection.next_action. Use when asked to put a team of agents on a job, orchestrate agents, or check on a goal already running. Refuses to build a second team when one already covers the objective.",
+        binName,
+        body: teamBody(binName),
+      }),
+  },
 ];