@huynle/hub 0.7.4 → 0.8.1

package/packages/spoke-sdk/src/profile-apply.ts

@@ -0,0 +1,245 @@
+// Profile application for harness adapters (HWA-15; contract packages/protocol/src/profiles.ts). Shared by the
+// OpenCode (HWA-16), Claude Code (HWA-17) and Codex/preset (HWA-18) adapters; checked by the conformance suite.
+//
+// Precedence (the documented rule): a profile ADDS a session-scoped layer and never replaces local configuration.
+//   - Local instructions (project AGENTS.md/CLAUDE.md, the user's own harness config) load unchanged. Profile
+//     instructions come after them, framed by profileInstructionsBlock, which says local instructions take
+//     precedence where they conflict.
+//   - A local skill or command with the same name wins: the profile's is skipped with a note (status partial).
+//   - Parts the adapter cannot apply are skipped with a note (partial); nothing applicable is `unsupported`.
+//   - An adapter whose harness reads the profile only at session start answers `restart_required`.
+//   - Adapters write session-scoped state only, never global harness configuration.
+// Secrets: profiles carry `{{secret:NAME}}` references only (central never resolves them). The adapter resolves
+// them on the spoke's machine when a command is rendered at invocation (renderProfileCommand; default source
+// envSecrets: HUB_SECRET_<NAME> in the spoke's environment). Resolved values are never written to disk, sent to
+// the hub, or put in notes; an adapter that cannot render at invocation skips commands that reference secrets.
+import { createHash } from "node:crypto"
+import {
+  canonicalProfileJSON,
+  PROFILE_APPLY_LIMITS,
+  type ProfileApplyRequest,
+  type ProfileApplyResult,
+  type ProfileApplyStatus,
+  type ProfileCommand,
+  type ProfileSkill,
+  profileTemplateParts,
+  type ProfileVersionContent,
+} from "../../protocol/src/index.ts"
+
+/** sha256 hex of the canonical JSON of a version's content: what the hub sends as `digest`. */
+export function profileDigest(content: ProfileVersionContent): string {
+  return createHash("sha256").update(canonicalProfileJSON(content)).digest("hex")
+}
+
+/** What a harness adapter can apply to a running session. */
+export interface ProfileCapabilities {
+  readonly instructions: boolean
+  readonly skills: boolean
+  readonly commands: boolean
+  /** It can switch the session's model. */
+  readonly model: boolean
+  /** Applied parts take effect in the running session; false: only after the session restarts. */
+  readonly live: boolean
+  /** It renders commands when they are invoked (so secret references resolve then, on this machine). */
+  readonly renderAtInvocation: boolean
+}
+
+/** Names the session already has locally (they win over the profile's). */
+export interface ProfileLocalNames {
+  readonly skills?: Iterable<string>
+  readonly commands?: Iterable<string>
+}
+
+export interface ProfilePlan {
+  readonly status: ProfileApplyStatus
+  /** The framed instructions block to add after local instructions (absent: none to apply). */
+  readonly instructions?: string
+  readonly skills: readonly ProfileSkill[]
+  readonly commands: readonly ProfileCommand[]
+  readonly model?: string
+  readonly notes: readonly string[]
+}
+
+/** A note within the protocol's bounds: plain text of at most noteChars characters. */
+export function profileNote(text: string): string {
+  const clean = text.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ")
+  return clean.length <= PROFILE_APPLY_LIMITS.noteChars ? clean : `${clean.slice(0, PROFILE_APPLY_LIMITS.noteChars - 1)}…`
+}
+
+/** At most PROFILE_APPLY_LIMITS.notes notes (the last one says how many were left out). */
+export function boundedNotes(notes: readonly string[]): string[] {
+  const max = PROFILE_APPLY_LIMITS.notes
+  const clean = notes.map(profileNote)
+  return clean.length <= max ? clean : [...clean.slice(0, max - 1), `… ${clean.length - max + 1} more notes`]
+}
+
+/** The profile instructions as adapters add them: after local instructions, which take precedence. */
+export function profileInstructionsBlock(req: Pick<ProfileApplyRequest, "profileID" | "version" | "content">): string {
+  return [
+    `<!-- hub profile ${req.profileID} v${req.version} (session-scoped) -->`,
+    `Hub agent profile ${req.profileID} version ${req.version}, applied to this session only. Where it conflicts with local project or user instructions, the local instructions take precedence.`,
+    "",
+    req.content.instructions ?? "",
+  ].join("\n")
+}
+
+/** Secret names a template references. */
+export function templateSecrets(template: string): string[] {
+  const parts = profileTemplateParts(template)
+  if (typeof parts === "string") return []
+  return [...new Set(parts.flatMap((p) => ("secret" in p ? [p.secret] : [])))]
+}
+
+/** What to apply of a profile version, by the precedence rule above. */
+export function planProfileApplication(req: ProfileApplyRequest, options: { readonly capabilities: ProfileCapabilities; readonly local?: ProfileLocalNames }): ProfilePlan {
+  const { capabilities: can } = options
+  const { content } = req
+  const localSkills = new Set(options.local?.skills ?? [])
+  const localCommands = new Set(options.local?.commands ?? [])
+  const notes: string[] = []
+  let offered = 0
+  let usable = 0
+
+  let instructions: string | undefined
+  if (content.instructions !== undefined && content.instructions.trim() !== "") {
+    offered++
+    if (can.instructions) {
+      instructions = profileInstructionsBlock(req)
+      usable++
+    } else notes.push("instructions not supported by this harness adapter")
+  }
+
+  const skills: ProfileSkill[] = []
+  if (content.skills.length) {
+    offered++
+    if (!can.skills) notes.push("skills not supported by this harness adapter")
+    else
+      for (const skill of content.skills) {
+        if (localSkills.has(skill.name)) notes.push(`skill ${skill.name} skipped: a local skill of that name takes precedence`)
+        else skills.push(skill)
+      }
+    if (skills.length) usable++
+  }
+
+  const commands: ProfileCommand[] = []
+  if (content.commands.length) {
+    offered++
+    if (!can.commands) notes.push("commands not supported by this harness adapter")
+    else
+      for (const command of content.commands) {
+        const secrets = templateSecrets(command.template)
+        if (localCommands.has(command.name)) notes.push(`command ${command.name} skipped: a local command of that name takes precedence`)
+        else if (secrets.length && !can.renderAtInvocation) notes.push(`command ${command.name} skipped: it needs secrets (${secrets.join(", ")}) and this adapter cannot render at invocation`)
+        else commands.push(command)
+      }
+    if (commands.length) usable++
+  }
+
+  let model: string | undefined
+  if (content.model !== undefined) {
+    offered++
+    if (can.model) {
+      model = content.model
+      usable++
+    } else notes.push("model ignored: this harness adapter cannot change the model")
+  }
+
+  const status: ProfileApplyStatus = offered > 0 && usable === 0 ? "unsupported" : !can.live ? "restart_required" : notes.length ? "partial" : "applied"
+  return { status, ...(instructions !== undefined ? { instructions } : {}), skills, commands, ...(model !== undefined ? { model } : {}), notes: boundedNotes(notes) }
+}
+
+/** What an adapter's apply may report; its status (if any) and notes replace or extend the plan's. */
+export interface ProfileApplyOutcome {
+  readonly status?: ProfileApplyStatus
+  readonly notes?: readonly string[]
+}
+
+export interface ProfileApplyHandlerOptions {
+  readonly capabilities: ProfileCapabilities
+  /** The session's local skill and command names (they win over the profile's). */
+  readonly local?: (sessionID: string) => ProfileLocalNames | undefined
+  /** Writes the plan to the session's own (session-scoped) state. Throwing answers `rejected` with the reason. */
+  readonly apply: (plan: ProfilePlan, req: ProfileApplyRequest) => Promise<ProfileApplyOutcome | void>
+  /** Sessions whose last applied digest is remembered (default 1000). */
+  readonly remembered?: number
+}
+
+/** The answer to a profileApply request, echoing what it was asked to apply. */
+export function profileApplyResult(req: ProfileApplyRequest, status: ProfileApplyStatus, notes: readonly string[] = []): ProfileApplyResult {
+  const bounded = boundedNotes(notes)
+  return { sessionID: req.sessionID, profileID: req.profileID, version: req.version, digest: req.digest, status, ...(bounded.length ? { notes: bounded } : {}) }
+}
+
+/**
+ * The `profileApply` op handler for HarnessSpoke (`handlers: { profileApply: handler.handle }`, which announces the
+ * feature): checks the digest, plans by precedence, calls the adapter, and answers a valid result. A repeated
+ * request for the digest a session already applied (applied or partial) answers the same result without
+ * re-applying; restart_required, rejected and unsupported are tried again.
+ */
+export class ProfileApplyHandler {
+  private readonly options: ProfileApplyHandlerOptions
+  private readonly done = new Map<string, ProfileApplyResult>()
+
+  constructor(options: ProfileApplyHandlerOptions) {
+    this.options = options
+  }
+
+  readonly handle = async (req: ProfileApplyRequest): Promise<ProfileApplyResult> => {
+    if (profileDigest(req.content) !== req.digest) return profileApplyResult(req, "rejected", ["digest does not match the content; nothing applied"])
+    const previous = this.done.get(req.sessionID)
+    if (previous && previous.profileID === req.profileID && previous.version === req.version && previous.digest === req.digest) return previous
+    const plan = planProfileApplication(req, { capabilities: this.options.capabilities, ...(this.options.local ? { local: this.options.local(req.sessionID) ?? {} } : {}) })
+    if (plan.status === "unsupported") return profileApplyResult(req, "unsupported", plan.notes)
+    let outcome: ProfileApplyOutcome | void
+    try {
+      outcome = await this.options.apply(plan, req)
+    } catch (cause) {
+      return profileApplyResult(req, "rejected", [`adapter failed: ${cause instanceof Error ? cause.message : String(cause)}`])
+    }
+    const result = profileApplyResult(req, outcome?.status ?? plan.status, [...plan.notes, ...(outcome?.notes ?? [])])
+    this.done.delete(req.sessionID)
+    if (result.status === "applied" || result.status === "partial") {
+      this.done.set(req.sessionID, result)
+      while (this.done.size > (this.options.remembered ?? 1000)) this.done.delete(this.done.keys().next().value!)
+    }
+    return result
+  }
+
+  /** Forgets a session (it ended, or its applied state was lost). */
+  forget(sessionID: string): void {
+    this.done.delete(sessionID)
+  }
+}
+
+/** A command's secret references are not available on this machine (names only, never values). */
+export class ProfileSecretMissingError extends Error {
+  constructor(readonly missing: readonly string[]) {
+    super(`missing secret(s) ${missing.join(", ")} on this machine`)
+    this.name = "ProfileSecretMissingError"
+  }
+}
+
+/** Secrets from the spoke's environment: `{{secret:NAME}}` reads `<prefix>NAME` (default HUB_SECRET_NAME). */
+export function envSecrets(env: Readonly<Record<string, string | undefined>> = process.env, prefix = "HUB_SECRET_"): (name: string) => string | undefined {
+  return (name) => {
+    const value = env[`${prefix}${name}`]
+    return value === undefined || value === "" ? undefined : value
+  }
+}
+
+/**
+ * Renders a command at invocation on the spoke: each `{{param}}` once, literally (a value is never parsed again),
+ * each `{{secret:NAME}}` from `secret`. Exactly the template's parameters must be given.
+ */
+export function renderProfileCommand(template: string, params: Readonly<Record<string, string>>, secret: (name: string) => string | undefined): string {
+  const parts = profileTemplateParts(template)
+  if (typeof parts === "string") throw new Error(`template: ${parts}`)
+  const wanted = [...new Set(parts.flatMap((p) => ("param" in p ? [p.param] : [])))]
+  const missing = wanted.filter((name) => !Object.hasOwn(params, name))
+  if (missing.length) throw new Error(`missing parameter(s) ${missing.join(", ")}`)
+  const unknown = Object.keys(params).filter((name) => !wanted.includes(name))
+  if (unknown.length) throw new Error(`unknown parameter(s) ${unknown.map((n) => (/^[a-z][a-z0-9_]{0,39}$/.test(n) ? n : "?")).join(", ")}`)
+  const absent = [...new Set(parts.flatMap((p) => ("secret" in p && secret(p.secret) === undefined ? [p.secret] : [])))]
+  if (absent.length) throw new ProfileSecretMissingError(absent)
+  return parts.map((p) => ("text" in p ? p.text : "param" in p ? params[p.param]! : secret(p.secret)!)).join("")
+}

package/src/central/actions.ts

@@ -73,6 +73,13 @@ export interface PromptInput {
   readonly images?: readonly PromptImage[]
   /** True for the user's own prompts; agent prompts never reset the hop chain (decision wvqeuis0 §8). */
   readonly resetHops: boolean
+  /**
+   * (CON-09a) false: the user did not write this text (a Concierge proposal run as the user), so it is never the
+   * source of the session's first-prompt intent. (CON-10) "first": it is the session's first prompt by construction
+   * (a launch's prompt, even when the launch already gave the session its name as title). Absent: it is the first
+   * prompt only when the session has no real title yet.
+   */
+  readonly intent?: false | "first"
 }
 
 /** Typed input steered into the running tree. */

package/src/central/agent/acting-routes.ts

@@ -14,6 +14,7 @@ import { DELIVER_ID_MAX, DELIVERY_MODES, type DeliveryMode, type FormAnswer, for
 import type { Acting } from "./acting"
 import { AgentError } from "./errors"
 import type { AgentRoute } from "./routes"
+import { AGENT_JSON_BODY_MAX, boundedText } from "./body"
 
 // A literal: routes.ts imports this module (AGENT_PREFIX is not initialised yet when it loads).
 const PREFIX = "/api/agent/sessions/:addr"
@@ -27,7 +28,7 @@ const invalid = (message: string) => new AgentError("invalid", message)
 type Body = Record<string, unknown>
 
 async function bodyOf(request: Request, optional = false): Promise<Body> {
-  const raw = await request.text()
+  const raw = await boundedText(request, AGENT_JSON_BODY_MAX)
   if (!raw.trim() && optional) return {}
   const value: unknown = JSON.parse(raw)
   if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalid("Body must be a JSON object")

package/src/central/agent/acting-switch.ts

@@ -6,6 +6,7 @@
 //   (agent/acting.ts) calls ensureActing() first and again before the spoke request; it answers 423 paused.
 //   Reading and messaging keep working (messaging has its own switch, AgentData.messagingPaused).
 // - hubNever(): hub.json `agents.never` (already validated by config.ts), checked before every grant.
+import { boundedJson } from "./body"
 import type { Store } from "../store"
 import type { AgentActor } from "./actor"
 import type { AgentAudit } from "./audit"
@@ -82,7 +83,7 @@ export function actingSwitchRoutes(acting: ActingSwitch): AgentRoute[] {
       path: `${AGENT_PREFIX}/acting`,
       allow: {},
       async handle({ request, user, actor }) {
-        const body: unknown = await request.json()
+        const body: unknown = await boundedJson(request)
         const enabled = typeof body === "object" && body !== null && !Array.isArray(body) ? (body as Record<string, unknown>).enabled : undefined
         if (typeof enabled !== "boolean") throw new AgentError("invalid", "enabled must be true or false")
         await acting.setUserActing(user.id, actor, enabled)