@huynle/hub 0.8.7 → 0.9.1

package/packages/protocol/src/artifacts.ts

@@ -39,6 +39,28 @@ export const ISOLATED_KINDS: readonly ArtifactKind[] = ["html", "app"]
 
 export type ArtifactVisibility = "private" | "workspace"
 
+/**
+ * Where an artifact came from when the hub made it for the console (absent: a normal artifact). "preview": an HTML
+ * preview of a code block in a session message (session media §3); hidden from the default library, archived and
+ * purged by preview retention, and turned into a normal artifact by Keep (which clears it).
+ */
+export const ARTIFACT_ORIGINS = ["preview"] as const
+export type ArtifactOrigin = (typeof ARTIFACT_ORIGINS)[number]
+
+/**
+ * A preview's source in one message of a session: the n-th (0-based) ```html block (`block`), or a local HTML page the
+ * message names (`path`, as written; session media §3 4b). Exactly one of the two. Provenance only; grants nothing.
+ */
+export interface ArtifactProvenance {
+  readonly sessionID: string
+  readonly messageID: string
+  readonly block?: number
+  readonly path?: string
+}
+
+/** Longest page path a preview's provenance carries (PREVIEW_BUNDLE_LIMITS.pathMax). */
+const PROVENANCE_PATH_MAX = 4096
+
 export interface Artifact extends Revisioned {
   readonly v: 1
   readonly id: string
@@ -54,6 +76,10 @@ export interface Artifact extends Revisioned {
   readonly latestRevisionID: string
   readonly tags?: readonly string[]
   readonly metadata?: Readonly<Record<string, string>>
+  /** Absent: a normal artifact. */
+  readonly origin?: ArtifactOrigin
+  /** With origin "preview": the code block or page it previews. */
+  readonly provenance?: ArtifactProvenance
   readonly createdAt: number
   readonly updatedAt: number
 }
@@ -129,9 +155,26 @@ export function artifactInputProblem(v: unknown): string | undefined {
   if (v.visibility !== undefined && v.visibility !== "private" && v.visibility !== "workspace") return "visibility must be private or workspace"
   if (v.visibility === "workspace" && !isContractID("workspace", v.workspaceID)) return "workspace visibility needs a workspaceID"
   if (v.workspaceID !== undefined && !isContractID("workspace", v.workspaceID)) return "workspaceID must be a workspace ID"
+  if (v.origin !== undefined && !ARTIFACT_ORIGINS.includes(v.origin as ArtifactOrigin)) return `origin must be one of ${ARTIFACT_ORIGINS.join(", ")}`
+  if (v.provenance !== undefined) {
+    const problem = provenanceProblem(v.provenance)
+    if (problem) return problem
+  }
   return tagsProblem(v.tags) ?? metadataProblem(v.metadata)
 }
 
+const PROVENANCE_ID = /^[A-Za-z0-9_.:-]{1,200}$/
+/** Session and message IDs are the harness's (opaque, bounded); `block` a 0-based index, or `path` a page path. */
+export function provenanceProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "provenance must be {sessionID, messageID, block} or {sessionID, messageID, path}"
+  if (typeof v.sessionID !== "string" || !PROVENANCE_ID.test(v.sessionID)) return "provenance.sessionID must be a session ID"
+  if (typeof v.messageID !== "string" || !PROVENANCE_ID.test(v.messageID)) return "provenance.messageID must be a message ID"
+  if ((v.block === undefined) === (v.path === undefined)) return "provenance needs exactly one of block and path"
+  if (v.block !== undefined && (typeof v.block !== "number" || !Number.isSafeInteger(v.block) || v.block < 0 || v.block > 9999)) return "provenance.block must be a whole number 0–9999"
+  if (v.path !== undefined && (typeof v.path !== "string" || v.path.length < 1 || v.path.length > PROVENANCE_PATH_MAX || /[\u0000\r\n]/.test(v.path))) return `provenance.path must be 1–${PROVENANCE_PATH_MAX} characters on one line`
+  return undefined
+}
+
 export function blobRefProblem(v: unknown): string | undefined {
   if (!isObj(v)) return "blob must be an object"
   if (!isBlobHash(v.hash)) return "hash must be sha256:<64 hex>"

package/packages/protocol/src/credentials.ts

@@ -0,0 +1,38 @@
+// Literal credentials in free text (tokens, keys, private keys): found, or replaced with "[redacted: <kind>]". Voice
+// recordings scrub every text field with it; spoken and pushed failure reasons and voice-front wakes do too.
+
+/** Distinctive credential formats; prose about secrets ("set API_KEY=…") is not matched. */
+export const CREDENTIALS: readonly (readonly [string, RegExp])[] = [
+  ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ["hub app token", /\bhat_[0-9a-f]{16}_[A-Za-z0-9_-]{43,}/],
+  ["github token", /\bgh[pousr]_[A-Za-z0-9]{36,}/],
+  ["github token", /\bgithub_pat_[A-Za-z0-9_]{22,}/],
+  ["api key", /\bsk-[A-Za-z0-9_-]{20,}/],
+  ["api key", /\bAIza[0-9A-Za-z_-]{35}/],
+  ["aws access key", /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/],
+  ["slack token", /\bxox[abposr]-[A-Za-z0-9-]{10,}/],
+  ["jwt", /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/],
+  ["bearer token", /\b[Bb]earer\s+[A-Za-z0-9._~+/=-]{20,}/],
+]
+
+/** The kind of literal credential in a text, or undefined. */
+export function credentialFinding(text: string): string | undefined {
+  for (const [kind, pattern] of CREDENTIALS) if (pattern.test(text)) return kind
+  return undefined
+}
+
+/**
+ * (REC-01) Replaces every literal credential in a text with `[redacted: <kind>]` (the CREDENTIALS table, applied
+ * globally) and lists the kinds removed, each once, in table order. Voice recordings scrub every text field with it.
+ */
+export function redactCredentials(text: string): { text: string; kinds: string[] } {
+  const kinds: string[] = []
+  let out = text
+  for (const [kind, pattern] of CREDENTIALS) {
+    const global = new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`)
+    const next = out.replace(global, `[redacted: ${kind}]`)
+    if (next !== out && !kinds.includes(kind)) kinds.push(kind)
+    out = next
+  }
+  return { text: out, kinds }
+}

package/packages/protocol/src/index.ts

@@ -18,8 +18,11 @@
 
 import { featureList, HUB_URL_MAX_CHARS, ID, isByeFrame as isBye, isHubURL, isObj, isResFrame as isRes, isWelcomeFrame, MAX_FRAME, MAX_RETRY_AFTER_MS, nonEmpty, num, parseFrame as parse, str, token, UNSAFE_CHARS } from "./wire.ts"
 import type { NodeMessage, NodeServerMessage } from "./node.ts"
+import { isWindowsAbsolutePath } from "./launch.ts"
 import { PROFILE_APPLY_FEATURE, profileApplyRequestProblem, type ProfileApplyRequest, type ProfileApplyResult } from "./profiles.ts"
 import { SESSION_CONTEXT_FEATURE, sessionContextProblem, type SessionContextRequest, type SessionContextResult } from "./concierge.ts"
+import { isMediaOffset, parseMediaRef, type TimelineMediaResult } from "./media.ts"
+import { isPreviewBundleRequest, PREVIEW_BUNDLE_FEATURE, type PreviewBundleRequest, type PreviewBundleResult } from "./preview-bundle.ts"
 
 export * from "./harness-events.ts"
 export * from "./launch.ts"
@@ -32,6 +35,9 @@ export * from "./concierge.ts"
 export * from "./profiles.ts"
 export * from "./artifacts.ts"
 export * from "./embedded-media.ts"
+export * from "./media.ts"
+export * from "./media-allowlist.ts"
+export * from "./preview-bundle.ts"
 export * from "./teams.ts"
 export * from "./graph.ts"
 export * from "./voice-recording.ts"
@@ -96,7 +102,9 @@ export interface AvailableModel {
  * mode (`order: "desc"` or `before`): the newest rows (before `before`) in chronological order, `older` for the
  * page before them. Both cursors are opaque. Items are the spoke's rows (src/spoke/timeline.ts TimelineItem); newer
  * spokes add optional `pos` (ordering position), `callID`, `childSessionID`, `title`, `ordinal` and, on error rows,
- * `declined` (a denied permission stopped the turn).
+ * `declined` (a denied permission stopped the turn). Spokes with "timelineMedia" (media.ts) add `ref`, `bytes`,
+ * `width`, `height` to user rows' `files`, and `media` (the same shape, ≤ MEDIA_LIMITS.perRow) to tool rows (their
+ * image file items, refs `t<part>.<item>`) and assistant text rows (local image paths, refs `p:…`).
  */
 export interface TimelinePage {
   readonly items: readonly unknown[]
@@ -172,6 +180,11 @@ export interface SessionInfo {
    */
   readonly agent?: string
   readonly contextRevision?: number
+  /**
+   * (feature "voiceFront") Set on a hidden voice-front session: the ID of the main session it fronts. The hub routes
+   * that session's conversation through it and never lists it. Older hubs ignore it.
+   */
+  readonly voiceFrontOf?: string
   /**
    * (FX-07) The session is locked as a Concierge session on this spoke (sent from the first sessions frame after a
    * restart, before `agent` or `contextRevision` are known). The hub treats it as a Concierge session.
@@ -449,8 +462,12 @@ export const IMPLIED_OPENCODE_FEATURES = [
  * reaches its own server).
  * "dismissError": it forgets a session's last run failure when the user dismisses it (dismissError op), so a
  * reconnect does not seed it again.
+ * "timelineMedia": it serves timeline images by ref in chunks (timelineMedia op, media.ts), and its timeline rows
+ * carry media refs (user files' `ref`, tool and assistant rows' `media`).
+ * "previewBundle": it answers previewBundle (preview-bundle.ts): a local HTML page an assistant message names and the
+ * files it refers to, under the media path policy, paged under the frame limit.
  */
-const OPTIONAL_SPOKE_FEATURES = [...IMPLIED_OPENCODE_FEATURES, "autoName", "sessionTokens", "deliver", "hubPrompt", "permissionMessage", "actTokens", "launch", "fork", "revert", "dismissError"] as const
+const OPTIONAL_SPOKE_FEATURES = [...IMPLIED_OPENCODE_FEATURES, "autoName", "sessionTokens", "deliver", "hubPrompt", "permissionMessage", "actTokens", "launch", "fork", "revert", "dismissError", "timelineMedia", PREVIEW_BUNDLE_FEATURE, "voiceFront"] as const
 
 /**
  * The core ops. An OpenCode spoke serves them all without announcing them; a spoke of another harness announces
@@ -641,8 +658,16 @@ export type ServerRequest =
   | { readonly op: "summary"; readonly sessionID: string }
   /** One changed file's patch in the session's directory. */
   | { readonly op: "diff"; readonly sessionID: string; readonly file: string }
-  /** Switch the session to the voice orchestrator agent (on) or back to its previous agent (off). */
-  | { readonly op: "conversation"; readonly sessionID: string; readonly on: boolean }
+  /**
+   * Switch the session to the voice orchestrator agent (on) or back to its previous agent (off). `front` (feature
+   * "voiceFront", sent only to spokes that list it): leave the session's agent and model untouched and put a hidden
+   * voice-front session in front of it instead (docs/plans/2026-11-06-voice-front-p1-contract.md).
+   */
+  /**
+   * `front` (feature "voiceFront"): put a hidden voice front in front of the session. `frontID`: the front the hub
+   * knows for it (a resend to a restarted spoke): re-linked if it still exists, instead of creating another.
+   */
+  | { readonly op: "conversation"; readonly sessionID: string; readonly on: boolean; readonly front?: boolean; readonly frontID?: string }
   | { readonly op: "models"; readonly sessionID: string }
   | { readonly op: "modelPrefs"; readonly sessionID: string }
   | { readonly op: "setModelPrefs"; readonly sessionID: string; readonly voice?: ModelSelection | null; readonly worker?: ModelSelection | null }
@@ -650,6 +675,16 @@ export type ServerRequest =
   | { readonly op: "timelinePart"; readonly sessionID: string; readonly messageID: string; readonly partID: string }
   /** One image attached to a user message (its position in the message's files). */
   | { readonly op: "timelineFile"; readonly sessionID: string; readonly messageID: string; readonly index: number }
+  /**
+   * (S4 M2, feature "timelineMedia") One image of a timeline row, by its ref (media.ts): a user attachment, a tool
+   * content item or an image path in an assistant message. `offset`: the chunk to answer (default 0).
+   */
+  | { readonly op: "timelineMedia"; readonly sessionID: string; readonly messageID: string; readonly ref: string; readonly offset?: number }
+  /**
+   * (Session media §3 4b, feature "previewBundle") A local HTML page named in an assistant message's text and the
+   * files it refers to: the manifest first, then chunks of the files not inlined (preview-bundle.ts).
+   */
+  | PreviewBundleRequest
   /** Enable or disable voice for one session (adds/removes it from the machine config's session list). */
   | { readonly op: "expose"; readonly sessionID: string; readonly on: boolean }
   /**
@@ -708,6 +743,11 @@ export type ServerRequest =
   | { readonly op: "revertRestore"; readonly sessionID: string }
   /** Make a staged revert permanent: the hidden messages are removed (feature "revert"). */
   | { readonly op: "revertCommit"; readonly sessionID: string }
+  /**
+   * (feature "voiceFront") Delete a voice-front session no conversation uses (the hub found it stale). The spoke
+   * deletes only a session on the voice-front agent that it has not linked; anything else is left alone.
+   */
+  | { readonly op: "removeFront"; readonly sessionID: string }
   /** Forget the session's last run failure: the user dismissed it (feature "dismissError"). */
   | { readonly op: "dismissError"; readonly sessionID: string }
 
@@ -723,6 +763,8 @@ export function featureForOp(op: ServerRequest["op"]): SpokeFeature {
     case "revertRestore":
     case "revertCommit":
       return "revert"
+    case "removeFront":
+      return "voiceFront"
     default:
       return op
   }
@@ -824,7 +866,8 @@ export interface ResultFor {
   stop: { readonly stopped: readonly string[] }
   summary: SessionSummary
   diff: { readonly patch?: FilePatch }
-  conversation: { readonly agent: string }
+  /** `front`: the voice-front session now in front of this one (on with `front`; absent when the spoke fell back). */
+  conversation: { readonly agent: string; readonly front?: { readonly sessionID: string } }
   models: { readonly models: readonly AvailableModel[] }
   modelPrefs: { readonly prefs: SessionModelPrefs; readonly defaults: SessionModelPrefs }
   setModelPrefs: { readonly prefs: SessionModelPrefs; readonly defaults: SessionModelPrefs }
@@ -832,6 +875,8 @@ export interface ResultFor {
   timelinePart: { readonly detail: unknown }
   /** No `file` when the message has no image at that index; `tooLarge` when its bytes would not fit in a frame. */
   timelineFile: { readonly file?: PromptImage; readonly tooLarge?: boolean }
+  timelineMedia: TimelineMediaResult
+  previewBundle: PreviewBundleResult
   expose: { readonly exposed: boolean }
   create: { readonly sessionID: string; readonly openedIn?: "herdr" }
   /** `applied`: sessions whose token the spoke stored; `skipped`: the others, with the reason. */
@@ -850,6 +895,7 @@ export interface ResultFor {
   revertCommit: Record<string, never>
   /** `dismissed`: the spoke had a failure of the session to forget. */
   dismissError: { readonly dismissed: boolean }
+  removeFront: { readonly removed: boolean }
 }
 
 // ---------- both directions ----------
@@ -1182,17 +1228,23 @@ function isServerRequest(v: unknown): v is ServerRequest {
       return nonEmpty(v.sessionID) && promptBody(v)
     case "timelineFile":
       return nonEmpty(v.sessionID) && nonEmpty(v.messageID) && v.messageID.length <= 300 && Number.isInteger(v.index) && Number(v.index) >= 0 && Number(v.index) < 1000
+    case "timelineMedia":
+      return nonEmpty(v.sessionID) && nonEmpty(v.messageID) && v.messageID.length <= 300 && str(v.ref) && parseMediaRef(v.ref) !== undefined && (v.offset === undefined || isMediaOffset(v.offset))
+    case "previewBundle":
+      return isPreviewBundleRequest(v)
     case "diff":
       return nonEmpty(v.sessionID) && nonEmpty(v.file) && v.file.length <= 4096
     case "rename":
       return nonEmpty(v.sessionID) && str(v.title) && v.title.length <= 1000
     case "conversation":
+      return nonEmpty(v.sessionID) && typeof v.on === "boolean" && (v.frontID === undefined || (nonEmpty(v.frontID) && v.frontID.length <= 300))
     case "expose":
       return nonEmpty(v.sessionID) && typeof v.on === "boolean"
     case "create":
       return (
         nonEmpty(v.directory) &&
-        v.directory.startsWith("/") &&
+        // POSIX as before; a Windows machine's directory in canonical form (C:/…, Phase 3).
+        (v.directory.startsWith("/") || isWindowsAbsolutePath(v.directory)) &&
         v.directory.length <= 4096 &&
         (v.title === undefined || (str(v.title) && v.title.length <= 200)) &&
         (v.herdrWorkspace === undefined || (nonEmpty(v.herdrWorkspace) && v.herdrWorkspace.length <= 100)) &&
@@ -1218,6 +1270,7 @@ function isServerRequest(v: unknown): v is ServerRequest {
     case "revertRestore":
     case "revertCommit":
     case "dismissError":
+    case "removeFront":
       return nonEmpty(v.sessionID)
     default:
       return false

package/packages/protocol/src/launch.ts

@@ -9,8 +9,8 @@ import { isObj, UNSAFE_CHARS } from "./wire.ts"
 export const LAUNCH_STATES = ["queued", "placing", "provisioning", "running", "ended"] as const
 export type LaunchState = (typeof LAUNCH_STATES)[number]
 
-/** How an ended launch ended. */
-export const LAUNCH_OUTCOMES = ["idle", "needs_user", "failed", "timeout", "stopped", "lost"] as const
+/** How an ended launch ended. expired (H3): its notAfter passed while it was still queued or placing (never started). */
+export const LAUNCH_OUTCOMES = ["idle", "needs_user", "failed", "timeout", "stopped", "lost", "expired"] as const
 export type LaunchOutcome = (typeof LAUNCH_OUTCOMES)[number]
 
 /** `worktree`: `<repo>/.worktrees/<branch>` (reused when present); `checkout`: the repo itself; `clone`: a fresh clone at `repo`. */
@@ -89,6 +89,11 @@ export interface LaunchSpec {
   readonly end?: LaunchEnd
   /** (HWA-15) Pin and apply this profile version to the session before its prompt (spokes that announce profileApply). */
   readonly agentProfile?: LaunchAgentProfile
+  /**
+   * (H3) Epoch ms: a launch still queued or placing then is never started; it ends with outcome expired. At most 30
+   * days ahead; already passed at submit: 422 expired, nothing stored. No effect once it is provisioning.
+   */
+  readonly notAfter?: number
 }
 
 /** What a node collected from a launch's workspace. */
@@ -144,17 +149,52 @@ export const LABELS_MAX = 32
 export const LABEL_VALUE_MAX = 256
 const LABEL_KEY = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,62}$/
 
-/** An absolute path of at most PATH_MAX characters without `.`/`..` segments, empty segments or unsafe characters. */
+/**
+ * An absolute path of at most PATH_MAX characters without `.`/`..` segments, empty segments or unsafe characters:
+ * POSIX `/a/b` (a trailing slash allowed, as before), or a canonical Windows path `C:/a/b` (upper-case drive, `/`
+ * separators, the root `C:/`; no backslash). UNC (`//server`, `\\server`) and device paths (`//?/`, `\\?\`) are never
+ * absolute here. The Windows form is the bootstrap contracts' rule (packages/cli/src/bootstrap/contracts/validate.ts
+ * isAbsolutePath); native forms are canonicalized at the node's edge (canonicalNativePath).
+ */
 export function isAbsolutePath(v: unknown): v is string {
-  if (typeof v !== "string" || !v.startsWith("/") || v.length > PATH_MAX || UNSAFE_CHARS.test(v)) return false
-  if (v === "/") return true
-  return v
+  if (typeof v !== "string" || v.length > PATH_MAX || UNSAFE_CHARS.test(v)) return false
+  if (WINDOWS_ROOT.test(v)) return !v.includes("\\") && normalSegments(v.slice(2))
+  if (!v.startsWith("/")) return false
+  return normalSegments(v)
+}
+
+/** `rest` (starting with "/") is "/" or "/"-separated segments, none empty, "." or ".." (one trailing "/" allowed). */
+function normalSegments(rest: string): boolean {
+  if (!rest.startsWith("/")) return false
+  if (rest === "/") return true
+  return rest
     .slice(1)
     .replace(/\/$/, "")
     .split("/")
     .every((part) => part !== "" && part !== "." && part !== "..")
 }
 
+const WINDOWS_ROOT = /^[A-Z]:(?=\/)/
+
+/** Whether `v` is a canonical Windows absolute path (`C:/…`). */
+export const isWindowsAbsolutePath = (v: unknown): v is string => typeof v === "string" && WINDOWS_ROOT.test(v) && isAbsolutePath(v)
+
+/**
+ * The canonical form of a path a host reported in its own form (node.json, realpath, git output), or undefined when
+ * it has none: Windows drive paths get an upper-case drive and `/` separators (a `\\?\` or `\??\` final-path
+ * prefix is dropped); repeated and trailing slashes are dropped. UNC, device and relative paths have no canonical
+ * form. Mirrors packages/cli/src/bootstrap/discovery/util.ts normalizeAbs.
+ */
+export function canonicalNativePath(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined
+  let p = value.replace(/^(\\\\\?\\|\\\?\?\\)(?=[A-Za-z]:\\)/, "")
+  if (/^[A-Za-z]:[\\/]/.test(p)) p = p[0]!.toUpperCase() + p.slice(1).replace(/\\/g, "/")
+  else if (!p.startsWith("/") || p.startsWith("//")) return undefined
+  p = p.replace(/\/{2,}/g, "/")
+  if (p.endsWith("/") && p !== "/" && !/^[A-Z]:\/$/.test(p)) p = p.slice(0, -1)
+  return isAbsolutePath(p) ? p : undefined
+}
+
 /** A branch name `git check-ref-format --branch` accepts, from a conservative character set, never starting with `-`. */
 export function isRefName(v: unknown): v is string {
   if (typeof v !== "string" || v.length === 0 || v.length > REF_MAX) return false