@huynle/hub 0.8.7 → 0.9.0

package/packages/cli/src/cli.ts

@@ -14,7 +14,7 @@ import { readSpokeCredentials } from "../../node/src/config.ts"
 import { hostname } from "node:os"
 import { serveMcp } from "./mcp"
 import { intentLine, writeIntent } from "./intents"
-import { ASK_EXPIRES_DEFAULT_S, askOutcome, declinedText, durationArg, inboxText, mutedText, repliedText, sentText, textArg } from "./messaging"
+import { ASK_EXPIRES_DEFAULT_S, askOutcome, declinedText, durationArg, inboxText, mutedText, notAfterArg, repliedText, sentText, textArg } from "./messaging"
 import { watch } from "./watch"
 import { DECISION_FLAGS, decisionOptions, decisionsText, openedText, stateArg } from "./decisions"
 import { GRANT_FLAGS, GRANT_REQUEST_FLAGS, grantError, grantRequestArg, grantSpecArg, grantsText, grantText, requestedText, userOnly } from "./grants"
@@ -81,10 +81,13 @@ Identity
   hub role release <role[.project]> [--session <addr>]
 
 Messaging (text "-" reads it from stdin)
-  hub msg <addr> "text" [--all] [--no-wake] [--urgent]   tell: fire and forget
-  hub ask <addr> "text" [--wait [secs]] [--expires 2h] [--all] [--no-wake] [--urgent]
+  hub msg <addr> "text" [--all] [--no-wake] [--urgent] [--not-after <ms|ISO time>] [--key K]
+                                      tell: fire and forget; --not-after: never delivered after that time
+  hub ask <addr> "text" [--wait [secs]] [--expires 2h] [--not-after <ms|ISO time>] [--all] [--no-wake] [--urgent] [--key K]
                                       tracked until answered, declined or expired; --wait alone waits until
-                                      it expires; exit 0 answered, 1 declined or no answer yet, 8 expired
+                                      it expires; exit 0 answered, 1 declined or no answer yet, 8 expired;
+                                      --key (Idempotency-Key): a retry with the same key and text answers
+                                      the first send again and sends nothing (24 h, per credential)
   hub reply <msgID> "text" [--no-wake]   goes to the real sender
   hub decline <msgID> --why "reason"
   hub ask @me "question" [--option id=label[:safe]]... [--recommend id [--why "…"]] [--urgency low|normal|high]
@@ -119,9 +122,10 @@ Launching (users; agents and app tokens with sessions:launch under a grant with
          [--name <@name>] [--role R]... [--harness H] [--agent A] [--model provider/model]
          [--runtime host|openshell [--profile P]] [--machine M] [--node-label k=v]... [--prefer]
          [--label k=v]... [--prompt "text" | --prompt -] [--end idle|asked|never] [--timeout 4h]
-         [--cleanup keep|remove] [--key K]
+         [--cleanup keep|remove] [--key K] [--not-after <ms|ISO time>]
                                       start a session; the same --key again answers the same launch;
-                                      --label tags it for apps, --node-label picks nodes (--prefer: not required)
+                                      --label tags it for apps, --node-label picks nodes (--prefer: not required);
+                                      --not-after: still waiting for a machine then, it never starts (expired)
   hub launches list [--state S[,S]] [--label k=v]...   your launches (agents: the ones they started)
   hub launches show <launchID> · hub launches stop <launchID>   (stop: exit 8 when it already ended)
 
@@ -278,8 +282,17 @@ const whyOf = (flags: Parsed["flags"]) => {
   return why !== undefined ? { why } : {}
 }
 
-/** --no-wake and --urgent as SDK send options. */
-const sendFlags = (flags: Parsed["flags"]) => ({ ...(flags["no-wake"] === true ? { wake: false } : {}), ...(flags.urgent === true ? { urgent: true } : {}) })
+/** --no-wake, --urgent, --not-after and --key as SDK send options. */
+const sendFlags = (flags: Parsed["flags"]) => {
+  const notAfter = str(flags, "not-after")
+  const key = str(flags, "key")
+  return {
+    ...(flags["no-wake"] === true ? { wake: false } : {}),
+    ...(flags.urgent === true ? { urgent: true } : {}),
+    ...(notAfter === undefined ? {} : { notAfter: notAfterArg(notAfter, "--not-after") }),
+    ...(key !== undefined ? { idempotencyKey: key } : {}),
+  }
+}
 
 const nodeIo = (io: Io): NodeIo => ({
   env: io.env,
@@ -399,7 +412,7 @@ const COMMANDS: Record<string, Command> = {
   },
   msg: {
     args: ["<addr>", "<text>"],
-    flags: { all: "bool", "no-wake": "bool", urgent: "bool" },
+    flags: { all: "bool", "no-wake": "bool", urgent: "bool", "not-after": "string", key: "string" },
     async handle(context) {
       const { flags, args } = context.parsed
       const text = await textArg(args[1]!, context.io.stdin)
@@ -410,7 +423,7 @@ const COMMANDS: Record<string, Command> = {
   },
   ask: {
     args: ["<addr>", "<text>"],
-    flags: { all: "bool", "no-wake": "bool", urgent: "bool", expires: "string", wait: "optional", ...DECISION_FLAGS },
+    flags: { all: "bool", "no-wake": "bool", urgent: "bool", "not-after": "string", key: "string", expires: "string", wait: "optional", ...DECISION_FLAGS },
     async handle(context) {
       const { flags, args } = context.parsed
       const decision = decisionOptions(flags, args[0]!)

package/packages/cli/src/http.ts

@@ -33,6 +33,7 @@ const EXIT_OF: Record<string, number> = {
   offline: EXIT.unavailable,
   busy: EXIT.unavailable,
   gone: EXIT.gone,
+  expired: EXIT.gone,
   unauthorized: EXIT.unauthorized,
   token_expired: EXIT.unauthorized,
 }

package/packages/cli/src/launches.ts

@@ -5,6 +5,7 @@ import path from "node:path"
 import type { LaunchSpec, LaunchStep, LaunchView } from "../../sdk/src/index.ts"
 import { CLEANUP_POLICIES, LAUNCH_END_WHEN, RUNTIME_KINDS, WORKSPACE_MODES } from "../../protocol/src/launch.ts"
 import { str, UsageError, type FlagKind, type Parsed } from "./args"
+import { notAfterArg } from "./messaging"
 
 export const LAUNCH_FLAGS: Readonly<Record<string, FlagKind>> = {
   key: "string",
@@ -28,6 +29,7 @@ export const LAUNCH_FLAGS: Readonly<Record<string, FlagKind>> = {
   end: "string",
   timeout: "string",
   cleanup: "string",
+  "not-after": "string",
 }
 
 /** `a, b or c` */
@@ -93,10 +95,12 @@ export async function launchSpecArg(flags: Parsed["flags"], context: LaunchArgCo
   const runtime = kind === undefined ? undefined : { kind, ...(profile !== undefined ? { profile } : {}) }
   const placement = defined({ labels: nodeLabels, machine, mode: flags.prefer === true ? ("prefer" as const) : undefined })
   const end = defined({ when, timeout: str(flags, "timeout"), cleanup })
+  const notAfterText = str(flags, "not-after")
+  const notAfter = notAfterText === undefined ? undefined : notAfterArg(notAfterText, "--not-after")
   return {
     ...defined({ key: str(flags, "key"), name, roles, harness: str(flags, "harness"), agent: str(flags, "agent"), model: str(flags, "model") }),
     workspace,
-    ...defined({ runtime, placement, prompt, labels, end }),
+    ...defined({ runtime, placement, prompt, labels, end, notAfter }),
   }
 }
 

package/packages/cli/src/mcp.ts

@@ -18,7 +18,7 @@ import { intentLine, writeIntent } from "./intents"
 import type { Credentials } from "./credentials"
 import { logText, oneLine, sessionsText, showText, statusText, whoamiText, whoText } from "./format"
 import { CliError, withHub } from "./http"
-import { askOutcome, declinedText, deliveryText, durationArg, mutedText, repliedText, sentText } from "./messaging"
+import { askOutcome, declinedText, deliveryText, durationArg, mutedText, notAfterArg, repliedText, sentText } from "./messaging"
 import { DECISION_STATES, decisionsText, decisionText, openedText } from "./decisions"
 import { CLEANUP_POLICIES, LAUNCH_END_WHEN, RUNTIME_KINDS, WORKSPACE_MODES } from "../../protocol/src/launch.ts"
 import { launchedText, launchesText, launchText, stoppedLaunchText } from "./launches"
@@ -103,11 +103,27 @@ const optionalExpires = (args: Args): number | undefined => {
   }
   throw new ArgError(`"expires" must be seconds or a duration like 30s, 5m, 2h, 1d`)
 }
-/** The wake and urgent arguments as SDK send options. */
+/** notAfter (H2): epoch milliseconds, or an ISO 8601 date-time converted to them. */
+const optionalNotAfter = (args: Args): number | undefined => {
+  const value = args.notAfter
+  if (value === undefined || value === null) return undefined
+  if (typeof value === "number" && Number.isSafeInteger(value)) return value
+  if (typeof value === "string") {
+    try {
+      return notAfterArg(value, "\"notAfter\"")
+    } catch (cause) {
+      if (cause instanceof UsageError) throw new ArgError(cause.message)
+      throw cause
+    }
+  }
+  throw new ArgError(`"notAfter" must be epoch milliseconds or an ISO 8601 date-time like 2027-01-15T12:00:00Z`)
+}
+/** The wake, urgent and notAfter arguments as SDK send options. */
 const sendOptions = (args: Args) => {
   const wake = optionalBool(args, "wake")
   const urgent = optionalBool(args, "urgent")
-  return { ...(wake !== undefined ? { wake } : {}), ...(urgent !== undefined ? { urgent } : {}) }
+  const notAfter = optionalNotAfter(args)
+  return { ...(wake !== undefined ? { wake } : {}), ...(urgent !== undefined ? { urgent } : {}), ...(notAfter !== undefined ? { notAfter } : {}) }
 }
 
 /** The why argument as SDK act options. */
@@ -178,6 +194,7 @@ function launchSpec(args: Args): LaunchSpec {
       prompt: optional(args, "prompt"),
       labels: optionalLabels(args, "labels"),
       end: definedFields({ when: optionalEnum(args, "end", LAUNCH_END_WHEN), timeout: optional(args, "timeout"), cleanup: optionalEnum(args, "cleanup", CLEANUP_POLICIES) }),
+      notAfter: optionalNotAfter(args),
     }),
   }
 }
@@ -220,6 +237,7 @@ const STRING = { type: "string" } as const
 const SEND = {
   wake: { type: "boolean", description: "false: admit the message without starting a turn." },
   urgent: { type: "boolean", description: "Steer into the recipient's running turn." },
+  notAfter: { type: ["number", "string"], description: "Never deliver after this time: epoch milliseconds or an ISO 8601 date-time (at most 30 days ahead). Already passed: nothing is sent (expired)." },
   all: { type: "boolean", description: "Send to every session the address names (each holder of a role)." },
 } as const
 const TO = { type: "string", description: "The recipient: @name, @@role, @@role#team (a role of one of your teams), @name.project, ses_…, or @me (the user)." } as const
@@ -388,7 +406,7 @@ const webhookText = (w: { id: string; url: string; events: readonly string[]; la
 const webhookTools: readonly Tool[] = [
   {
     name: "webhook_create",
-    description: "Create a durable signed webhook for canonical compact events. The signing secret is returned only here. Needs events:subscribe plus every selected family's scope.",
+    description: "Create a durable signed webhook for canonical compact events (e.g. launch.*, session.*, message.changed, team.intake). The signing secret is returned only here. Needs events:subscribe plus every selected family's scope; events [\"team.intake\"] alone needs only teams:submit (an app gets only its own submissions).",
     properties: { url: STRING, events: { type: "array", items: STRING }, label: STRING }, required: ["url"], readOnly: false,
     run: async (hub, args, signal) => {
       const events = optionalStrings(args, "events")
@@ -809,13 +827,13 @@ const TOOLS: readonly Tool[] = [
   {
     name: "msg",
     description: "Tell a session something (fire and forget). Sent as this server's credential, not as an OpenCode session.",
-    properties: { to: TO, text: { ...STRING, description: "The message." }, ...SEND },
+    properties: { to: TO, text: { ...STRING, description: "The message." }, ...SEND, idempotencyKey: IDEMPOTENCY },
     required: ["to", "text"],
     readOnly: false,
     run: async (hub, args, signal) => {
       const to = need(args, "to")
       const text = need(args, "text")
-      const options = { ...sendOptions(args), signal }
+      const options = { ...sendOptions(args), ...idemOption(args), signal }
       if (optionalBool(args, "all")) return sentAllText(await hub.msg(to, text, { ...options, all: true }))
       return sentText(await hub.msg(to, text, options))
     },
@@ -829,6 +847,7 @@ const TOOLS: readonly Tool[] = [
       wait: { type: "number", minimum: 0, maximum: WAIT_POLL_MAX_S, description: `Seconds to wait for the answer (0–${WAIT_POLL_MAX_S}).` },
       expires: { type: ["number", "string"], description: "When the ask expires: seconds, or 30s, 5m, 2h, 1d (1 minute to 7 days; default 24 h)." },
       ...SEND,
+      idempotencyKey: IDEMPOTENCY,
     },
     required: ["to", "text"],
     readOnly: false,
@@ -837,7 +856,7 @@ const TOOLS: readonly Tool[] = [
       const text = need(args, "text")
       const wait = optionalWait(args)
       const expires = optionalExpires(args)
-      const options = { ...sendOptions(args), ...(expires !== undefined ? { expires } : {}), signal }
+      const options = { ...sendOptions(args), ...(expires !== undefined ? { expires } : {}), ...idemOption(args), signal }
       if (optionalBool(args, "all")) {
         if (wait !== undefined) throw new ArgError(`"wait" cannot be combined with "all"`)
         return sentAllText(await hub.ask(to, text, { ...options, all: true }))
@@ -999,7 +1018,7 @@ const TOOLS: readonly Tool[] = [
   {
     name: "launch",
     description:
-      "Start a new session on a node (a hub node with the repo under its workspace roots). The same key again answers the same launch. Needs an app token with scope sessions:launch and a grant with verb launch covering the repo.",
+      "Start a new session on a node (a hub node with the repo under its workspace roots). The same key again answers the same launch. With notAfter, a launch still waiting for a machine at that time is never started (it ends expired). Needs an app token with scope sessions:launch and a grant with verb launch covering the repo.",
     properties: {
       repo: { ...STRING, description: "Absolute path of the repository on the node (or where a clone goes)." },
       mode: { type: "string", enum: [...WORKSPACE_MODES], description: "worktree (default: <repo>/.worktrees/<branch>, needs branch), checkout, or clone (needs remote)." },
@@ -1022,6 +1041,7 @@ const TOOLS: readonly Tool[] = [
       end: { type: "string", enum: [...LAUNCH_END_WHEN], description: "When it ends: idle (default; idle with nothing open for 30 s), asked (with a question open: needs_user), never." },
       timeout: { ...STRING, description: "Longest run, e.g. 4h or 90m." },
       cleanup: { type: "string", enum: [...CLEANUP_POLICIES], description: "keep (default) or remove the workspace when it ends." },
+      notAfter: { type: ["number", "string"], description: "Do not start after this time: epoch milliseconds or an ISO 8601 date-time (at most 30 days ahead). Still waiting for a machine then, the launch ends expired; once placed it runs (timeout bounds it). Already passed: nothing is launched (expired)." },
     },
     required: ["repo"],
     readOnly: false,

package/packages/cli/src/messaging.ts

@@ -57,6 +57,20 @@ export function durationArg(value: string, flag: string): number {
   return Number(match[1]) * UNIT_S[match[2]!]!
 }
 
+/** An ISO 8601 date-time with at least hours and minutes; no zone means local time. */
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:?\d{2})?$/i
+
+/**
+ * A notAfter (H2) as epoch milliseconds, from epoch milliseconds (digits) or an ISO 8601 date-time like
+ * 2027-01-15T12:00:00Z; the hub checks the range (future, at most 30 days ahead). Throws UsageError(`what` …).
+ */
+export function notAfterArg(value: string, what: string): number {
+  const text = value.trim()
+  const ms = /^\d+$/.test(text) ? Number(text) : ISO_DATE_TIME.test(text) ? Date.parse(text) : Number.NaN
+  if (!Number.isSafeInteger(ms)) throw new UsageError(`${what} takes epoch milliseconds or an ISO 8601 date-time like 2027-01-15T12:00:00Z (got "${value}")`)
+  return ms
+}
+
 const iso = (ms: number) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z")
 
 /** What an ask came to, its text, and the exit code: answered 0, declined 1, open after a wait 1, expired 8. */

package/packages/cli/src/team-intake-mcp.ts

@@ -5,6 +5,8 @@
 // sessions submit under team policy and, in the team's entry role, report status.
 import { sanitizeText } from "../../sdk/src/envelope.ts"
 import { reportIntakeStatus, TEAM_INTAKE_STATUS_INPUTS, type TeamIntake, type TeamIntakeApi, type TeamIntakePriority, type TeamIntakeStatus, type TeamIntakeStatusInput } from "../../sdk/src/team-intake.ts"
+import { UsageError } from "./args"
+import { notAfterArg } from "./messaging"
 import { ToolArgError } from "./tool-args"
 
 type Args = Record<string, unknown>
@@ -60,6 +62,22 @@ function dueOf(args: Args): number | undefined {
   return ms
 }
 
+/** `notAfter` (H4) as epoch milliseconds or an ISO 8601 date-time; the hub checks the range. */
+function notAfterOf(args: Args): number | undefined {
+  const value = args.notAfter
+  if (value === undefined || value === null || value === "") return undefined
+  if (typeof value === "number" && Number.isSafeInteger(value)) return value
+  if (typeof value === "string") {
+    try {
+      return notAfterArg(value, `"notAfter"`)
+    } catch (cause) {
+      if (cause instanceof UsageError) throw new ToolArgError(cause.message)
+      throw cause
+    }
+  }
+  throw new ToolArgError(`"notAfter" must be epoch milliseconds or an ISO 8601 date-time like 2027-01-15T12:00:00Z`)
+}
+
 const line = (i: TeamIntake) =>
   `${i.id}  ${i.status}${i.progress ? `/${i.progress}` : ""}  ${i.priority}  r${i.revision}  ${sanitizeText(i.title).replace(/\s+/g, " ")}`
 
@@ -71,6 +89,7 @@ function intakeText(i: TeamIntake): string {
     `status: ${i.status}${i.progress ? ` (${i.progress})` : ""}  priority: ${i.priority}  from: ${from}`,
     ...(i.assignmentID ? [`assignment: ${i.assignmentID} in workspace ${i.workspaceID ?? "?"}${i.sessionID ? `, delivered to ${i.sessionID}` : ""}`] : []),
     ...(i.due !== undefined ? [`due: ${new Date(i.due).toISOString()}`] : []),
+    ...(i.notAfter !== undefined ? [`not after: ${new Date(i.notAfter).toISOString()}`] : []),
     ...(i.labels?.length ? [`labels: ${i.labels.join(", ")}`] : []),
     ...(i.criteria?.length ? ["done means:", ...i.criteria.map((c) => `- ${sanitizeText(c)}`)] : []),
     ...(i.ref ? [`ref: ${sanitizeText(i.ref)}`] : []),
@@ -83,7 +102,7 @@ export const teamIntakeTools: readonly TeamIntakeTool[] = [
   {
     name: "team_submit",
     description:
-      "Give work to a team: its entry role (e.g. the project manager) receives the task with the team's context and owns it as an assignment in the team's workspace; while the role is vacant it waits queued. Pass `key` to make retries idempotent. App tokens need scope teams:submit; sessions submit under the team's communication policy.",
+      "Give work to a team: its entry role (e.g. the project manager) receives the task with the team's context and owns it as an assignment in the team's workspace; while the role is vacant it waits queued (with `notAfter`, only until then: still queued at that time, it is cancelled with reason not_after instead of delivered late). Pass `key` to make retries idempotent. App tokens need scope teams:submit; sessions submit under the team's communication policy.",
     properties: {
       team: TEAM,
       title: { ...STRING, description: "One line, at most 120 characters." },
@@ -91,6 +110,10 @@ export const teamIntakeTools: readonly TeamIntakeTool[] = [
       priority: { type: "string", enum: PRIORITIES, description: "Default normal." },
       labels: { type: "array", items: STRING, description: "Slugs (lowercase letters, digits, dashes)." },
       due: { ...STRING, description: "When it is due: an ISO date/time." },
+      notAfter: {
+        type: ["number", "string"],
+        description: "Never deliver after this time: epoch milliseconds or an ISO 8601 date-time (at most 30 days ahead). Already passed: nothing is submitted (expired). Still queued then: cancelled (reason not_after).",
+      },
       criteria: { type: "array", items: STRING, description: "What done means (at most 8 lines)." },
       ref: { ...STRING, description: "An external reference, e.g. a Brain task ID." },
       key: { ...STRING, description: "Idempotency-Key: the same key and body return the original submission." },
@@ -103,12 +126,13 @@ export const teamIntakeTools: readonly TeamIntakeTool[] = [
       const labels = strings(args, "labels")
       const criteria = strings(args, "criteria")
       const due = dueOf(args)
+      const notAfter = notAfterOf(args)
       const brief = optional(args, "brief")
       const ref = optional(args, "ref")
       const key = optional(args, "key")
       const { intake, created } = await hub.teams.submit(
         need(args, "team"),
-        { title: need(args, "title"), ...(brief ? { brief } : {}), ...(priority ? { priority } : {}), ...(labels ? { labels } : {}), ...(due !== undefined ? { due } : {}), ...(criteria ? { criteria } : {}), ...(ref ? { ref } : {}) },
+        { title: need(args, "title"), ...(brief ? { brief } : {}), ...(priority ? { priority } : {}), ...(labels ? { labels } : {}), ...(due !== undefined ? { due } : {}), ...(notAfter !== undefined ? { notAfter } : {}), ...(criteria ? { criteria } : {}), ...(ref ? { ref } : {}) },
         { signal, ...(key ? { idempotencyKey: key } : {}) },
       )
       return `${created ? "Submitted" : "Already submitted (same key)"}: ${intake.id} is ${intake.status}${intake.status === "queued" ? " (waiting for the entry role)" : ""}\n${intakeText(intake)}`

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.8.7",
+  "version": "0.9.0",
   "private": true,
   "description": "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-node",
-  "version": "0.8.7",
+  "version": "0.9.0",
   "private": true,
   "description": "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-preset",
-  "version": "0.8.7",
+  "version": "0.9.0",
   "private": true,
   "description": "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-protocol",
-  "version": "0.8.7",
+  "version": "0.9.0",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",