@huynle/hub 0.7.4 → 0.8.1

package/packages/claude-code/src/launcher.ts

@@ -3,7 +3,8 @@
 // --input-format stream-json --output-format stream-json --verbose [--model m] [--agent a]`, so its hooks reach the
 // daemon like any `hub claude` run (HUB_CLAUDE_LAUNCH, HUB_CLAUDE_SOCKET), a turn is a user message written to its
 // stdin, the turn's end is the result line on its stdout, and an interrupt is a control request (Esc has no hook,
-// a control request works). Turns are answered in order (Claude Code runs queued user messages one after another).
+// a control request works). A profile's model (HWA-17) is the control request set_model, confirmed by Claude Code's
+// control response. Turns are answered in order (Claude Code runs queued user messages one after another).
 // When claude exits its open turns fail and onExit reports it; stopAll closes stdin (claude ends after the running
 // turn) and kills what lingers.
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"
@@ -44,7 +45,8 @@ interface Turn {
 interface Proc {
   readonly child: ChildProcessWithoutNullStreams
   readonly turns: Turn[]
-  readonly controls: Map<string, () => void>
+  /** Open control requests: called with Claude Code's response, or nothing when it exited. */
+  readonly controls: Map<string, (response?: Record<string, any>) => void>
   readonly exited: Promise<void>
   stderr: string
 }
@@ -224,14 +226,32 @@ export class ClaudeLauncher {
     const proc = this.#procs.get(sessionID)
     if (!proc) return false
     for (const turn of proc.turns) turn.interrupted = true
-    const id = `hub_int_${++this.#controlID}`
-    const answered = new Promise<void>((resolve) => proc.controls.set(id, resolve))
-    proc.child.stdin.write(`${JSON.stringify({ type: "control_request", request_id: id, request: { subtype: "interrupt" } })}\n`)
-    await Promise.race([answered, sleep(CONTROL_WAIT_MS)])
-    proc.controls.delete(id)
+    await this.#control(proc, { subtype: "interrupt" }, CONTROL_WAIT_MS)
     return true
   }
 
+  /**
+   * Changes the session's model (control request set_model, a Claude Code model ID or alias); resolves when Claude
+   * Code confirms, rejects with its error, when it does not answer in `waitMs`, or for a session it did not start.
+   */
+  async setModel(sessionID: string, model: string, waitMs = CONTROL_WAIT_MS): Promise<void> {
+    const proc = this.#procs.get(sessionID)
+    if (!proc) throw new Error(`Session ${sessionID} was not started by the hub here (only hub-launched Claude Code sessions change model from the hub)`)
+    const response = await this.#control(proc, { subtype: "set_model", model }, waitMs)
+    if (!response) throw new Error("Claude Code did not confirm the model change")
+    if (response.subtype !== "success") throw new Error(typeof response.error === "string" && response.error ? response.error.slice(0, 200) : "Claude Code refused the model change")
+  }
+
+  /** Sends a control request; resolves with Claude Code's response, or undefined (no answer in time, or it exited). */
+  async #control(proc: Proc, request: Record<string, unknown>, waitMs: number): Promise<Record<string, any> | undefined> {
+    const id = `hub_ctl_${++this.#controlID}`
+    const answered = new Promise<Record<string, any> | undefined>((resolve) => proc.controls.set(id, resolve))
+    proc.child.stdin.write(`${JSON.stringify({ type: "control_request", request_id: id, request })}\n`)
+    const response = await Promise.race([answered, sleep(waitMs).then(() => undefined)])
+    proc.controls.delete(id)
+    return response
+  }
+
   /** Ends every process: stdin closed, then SIGTERM and SIGKILL for what lingers. */
   async stopAll(): Promise<void> {
     const procs = [...this.#procs.values()]
@@ -258,8 +278,8 @@ export class ClaudeLauncher {
       const turn = proc.turns.shift()
       turn?.resolve(turnResult(line, turn.interrupted))
     } else if (line.type === "control_response") {
-      const id = record(line.response).request_id
-      if (typeof id === "string") proc.controls.get(id)?.()
+      const response = record(line.response)
+      if (typeof response.request_id === "string") proc.controls.get(response.request_id)?.(response)
     }
   }
 }

package/packages/claude-code/src/paths.ts

@@ -1,18 +1,18 @@
 // Where the Claude Code spoke keeps its files: <hub state dir>/claude-code (the hub state dir is $HUB_STATE_DIR, else
-// ~/.local/state/hub), a private (0700) directory holding the daemon's socket (daemon.sock, 0600), its log and the
+// $XDG_STATE_HOME/hub or ~/.local/state/hub), a private (0700) directory holding the daemon's socket (daemon.sock, 0600), its log and the
 // plugin directories the wrapper loads with --plugin-dir. $HUB_CLAUDE_SOCKET names another socket (tests, or a
 // short path when the state dir is too deep for a Unix socket path).
 import { chmodSync, lstatSync, mkdirSync } from "node:fs"
 import { homedir } from "node:os"
 import path from "node:path"
 import { hubEnv, type Env } from "../../../src/env.ts"
-import { APP_DIR, stateBase } from "../../../src/migrate.ts"
+import { resolveHubStateDir } from "../../../src/migrate.ts"
 
 /** Longest Unix socket path (macOS sun_path is 104 bytes with the terminating NUL). */
 export const SOCKET_PATH_MAX = 103
 
 export function claudeStateDir(env: Env = process.env, home: string = homedir()): string {
-  return path.join(hubEnv(env).HUB_STATE_DIR || path.join(stateBase(home), APP_DIR), "claude-code")
+  return path.join(resolveHubStateDir(env, home).dir, "claude-code")
 }
 
 export function socketPath(env: Env = process.env, home: string = homedir()): string {

package/packages/claude-code/src/profile.ts

@@ -0,0 +1,173 @@
+// Profile application for Claude Code sessions (HWA-17; contract packages/protocol/src/profiles.ts, SDK
+// spoke-sdk/src/profile-apply.ts). Only the native mechanisms this spoke already uses, nothing written to the
+// user's Claude Code settings, no plugin installed, no permission changed, no session restarted:
+//
+//                      instructions                      model                          skills / commands
+//   hub-launched       hook context, next prompt         set_model control request      skipped (note)
+//   terminal           hook context, next prompt         ignored (note: the user's)     skipped (note)
+//
+// - Instructions: kept in the daemon's memory for the session only and handed to Claude Code as hook
+//   additionalContext at the session's next UserPromptSubmit (and again at SessionStart after a compaction, which
+//   drops earlier context). They come after the local CLAUDE.md files, framed by profileInstructionsBlock (local
+//   instructions take precedence). A newer version replaces them; one without instructions says the earlier ones
+//   no longer apply.
+// - Model: a hub-launched session runs headless under the daemon (launcher.ts), which changes its model with the
+//   stream-json control request set_model and waits for Claude Code's answer (anthropic models only). A terminal
+//   session's model belongs to the user at the terminal (/model): ignored with a note.
+// - Skills and commands: Claude Code loads them only from plugin and settings directories when a session starts;
+//   adding them would mean installing a plugin, writing settings or restarting the session, none of which the hub
+//   does on its own. Skipped with a note (partial beside other parts; alone the answer is unsupported). So no
+//   command is ever rendered here and `{{secret:NAME}}` references are never resolved.
+// - Unknown and subagent sessions are rejected (a subagent shares its parent's context). Applies to one session run
+//   one at a time, in arrival order. A repeat of the applied digest answers the same without re-applying (SDK).
+import type { ProfileApplyRequest, ProfileApplyResult } from "../../protocol/src/index.ts"
+import { profileApplyResult, ProfileApplyHandler, type ProfileApplyOutcome, type ProfileCapabilities, type ProfilePlan } from "../../spoke-sdk/src/index.ts"
+import { launchModel } from "./launcher.ts"
+
+/** How the daemon runs a session: started by the hub (headless under the daemon) or by a user in a terminal. */
+export type ClaudeSessionKind = "launched" | "terminal"
+
+/** What profile application needs of the daemon. */
+export interface ClaudeProfilePort {
+  /** The kind of a root session the daemon reports; undefined for unknown and subagent sessions. */
+  kind(sessionID: string): ClaudeSessionKind | undefined
+  /** Changes a hub-launched session's model (a Claude Code model ID); throws with Claude Code's reason. */
+  setModel(sessionID: string, model: string): Promise<void>
+}
+
+export interface ClaudeProfilesOptions {
+  /** Sessions whose profile state is kept (default 1000; the oldest are forgotten first). */
+  readonly sessionsMax?: number
+}
+
+const BASE: Omit<ProfileCapabilities, "model"> = { instructions: true, skills: false, commands: false, live: true, renderAtInvocation: false }
+
+/** What Claude Code sessions take, by kind. */
+export const CLAUDE_PROFILE_CAPABILITIES: Readonly<Record<ClaudeSessionKind, ProfileCapabilities>> = {
+  launched: { ...BASE, model: true },
+  terminal: { ...BASE, model: false },
+}
+
+const SESSIONS_MAX = 1000
+const SKILLS_NOTE = "Claude Code loads skills and commands only from plugin or settings directories at session start; the hub installs no plugin, writes no settings and restarts no session"
+const NEXT_PROMPT_NOTE = "instructions reach the model with the session's next prompt (hook context)"
+const TERMINAL_MODEL_NOTE = "model ignored: a terminal session's model is the user's to change (/model)"
+
+/** The Claude Code model ID of a profile model "provider/model"; throws unless Claude Code can run it. */
+export function profileModelID(model: string): string {
+  const at = model.indexOf("/")
+  if (at <= 0 || at === model.length - 1) throw new Error(`model ${JSON.stringify(model)} is not provider/model`)
+  return launchModel({ providerID: model.slice(0, at), modelID: model.slice(at + 1) })!
+}
+
+interface Staged {
+  readonly profileID: string
+  readonly version: number
+  /** The effective profile's framed instructions (re-sent after a compaction). */
+  readonly instructions?: string
+  /** What the next prompt carries (the instructions, or a notice that earlier ones no longer apply). */
+  pending?: string
+  /** Some profile text reached the model already. */
+  delivered: boolean
+}
+
+const header = (req: Pick<ProfileApplyRequest, "profileID" | "version">) => `<!-- hub profile ${req.profileID} v${req.version} (session-scoped) -->`
+
+export class ClaudeProfiles {
+  readonly #port: ClaudeProfilePort
+  readonly #max: number
+  readonly #staged = new Map<string, Staged>()
+  readonly #queues = new Map<string, Promise<unknown>>()
+  readonly #handlers: Readonly<Record<ClaudeSessionKind, ProfileApplyHandler>>
+
+  constructor(port: ClaudeProfilePort, options: ClaudeProfilesOptions = {}) {
+    this.#port = port
+    this.#max = options.sessionsMax ?? SESSIONS_MAX
+    const handler = (kind: ClaudeSessionKind) =>
+      new ProfileApplyHandler({ capabilities: CLAUDE_PROFILE_CAPABILITIES[kind], apply: (plan, req) => this.#apply(kind, plan, req), remembered: this.#max })
+    this.#handlers = { launched: handler("launched"), terminal: handler("terminal") }
+  }
+
+  /** The `profileApply` op handler (HarnessSpoke handlers: announces the feature). */
+  readonly handle = (req: ProfileApplyRequest): Promise<ProfileApplyResult> => {
+    const previous = this.#queues.get(req.sessionID) ?? Promise.resolve()
+    const run = previous.then(() => this.#handle(req))
+    const tail = run.catch(() => undefined)
+    this.#queues.set(req.sessionID, tail)
+    void tail.then(() => {
+      if (this.#queues.get(req.sessionID) === tail) this.#queues.delete(req.sessionID)
+    })
+    return run
+  }
+
+  /**
+   * The profile context a hook hands the model now, if any: at UserPromptSubmit what is pending (once); at
+   * SessionStart after a compaction (source "compact") the effective instructions again.
+   */
+  context(sessionID: string, event: "UserPromptSubmit" | "SessionStart", source?: string): string | undefined {
+    const s = this.#staged.get(sessionID)
+    if (!s) return undefined
+    let text: string | undefined
+    if (event === "UserPromptSubmit") text = s.pending
+    else if (event === "SessionStart" && source === "compact") text = s.instructions
+    if (text === undefined) return undefined
+    s.pending = undefined
+    s.delivered = true
+    return text
+  }
+
+  /** The session ended: its profile state goes with it. */
+  ended(sessionID: string): void {
+    this.#staged.delete(sessionID)
+    this.#handlers.launched.forget(sessionID)
+    this.#handlers.terminal.forget(sessionID)
+  }
+
+  async #handle(req: ProfileApplyRequest): Promise<ProfileApplyResult> {
+    const kind = this.#port.kind(req.sessionID)
+    if (!kind) return profileApplyResult(req, "rejected", [`${req.sessionID} is not a Claude Code session this spoke reports (a subagent session follows its parent's context)`])
+    return this.#handlers[kind].handle(req)
+  }
+
+  async #apply(kind: ClaudeSessionKind, plan: ProfilePlan, req: ProfileApplyRequest): Promise<ProfileApplyOutcome> {
+    const notes: string[] = []
+    let modelFailed = false
+    if (req.content.skills.length || req.content.commands.length) notes.push(SKILLS_NOTE)
+    if (kind === "terminal" && req.content.model !== undefined) notes.push(TERMINAL_MODEL_NOTE)
+    if (plan.model !== undefined) {
+      let id: string | undefined
+      try {
+        id = profileModelID(plan.model)
+      } catch (cause) {
+        modelFailed = true
+        notes.push(`model ignored: ${message(cause)}`)
+      }
+      if (id !== undefined) {
+        try {
+          await this.#port.setModel(req.sessionID, id)
+        } catch (cause) {
+          modelFailed = true
+          notes.push(`model not changed: ${message(cause)}`)
+        }
+      }
+    }
+    if (modelFailed && plan.instructions === undefined) return { status: "rejected", notes }
+    this.#stage(req, plan.instructions)
+    if (plan.instructions !== undefined) notes.push(NEXT_PROMPT_NOTE)
+    return { ...(modelFailed ? { status: "partial" as const } : {}), notes }
+  }
+
+  /** Keeps the version's instructions for the session's next prompt (replacing an earlier version's). */
+  #stage(req: ProfileApplyRequest, instructions: string | undefined): void {
+    const before = this.#staged.get(req.sessionID)
+    const delivered = before?.delivered === true
+    let pending: string | undefined
+    if (instructions !== undefined) pending = delivered ? instructions.replace(header(req), `${header(req)}\nThis replaces earlier hub profile instructions in this session.`) : instructions
+    else if (delivered) pending = `${header(req)}\nHub agent profile ${req.profileID} version ${req.version} now applies to this session without instructions: earlier hub profile instructions in this session no longer apply.`
+    this.#staged.delete(req.sessionID)
+    this.#staged.set(req.sessionID, { profileID: req.profileID, version: req.version, ...(instructions !== undefined ? { instructions } : {}), ...(pending !== undefined ? { pending } : {}), delivered })
+    while (this.#staged.size > this.#max) this.#staged.delete(this.#staged.keys().next().value!)
+  }
+}
+
+const message = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))

package/packages/claude-code/src/sessions.ts

@@ -28,6 +28,9 @@
 // Hub-launched sessions (launched(): the daemon runs their claude headless, launcher.ts) are reported at create,
 // before any hook; a prompt the hub writes to one (hubPrompt) is delivered with origin "hub", and the turn's result
 // line ends a turn the hooks left running (turnEnded: an interrupt fires no Stop hook).
+//
+// Profiles (HWA-17, profile.ts): a session's pending profile instructions ride on its next UserPromptSubmit context
+// (before hub messages), and again on SessionStart after a compaction; a session's end forgets its profile.
 import { existsSync } from "node:fs"
 import path from "node:path"
 import { randomBytes } from "node:crypto"
@@ -65,6 +68,12 @@ export interface HookReply {
   readonly env?: Record<string, string>
 }
 
+/** The session-scoped profile state (ClaudeProfiles). */
+export interface ProfileContextPort {
+  context(sessionID: string, event: "UserPromptSubmit" | "SessionStart", source?: string): string | undefined
+  ended(sessionID: string): void
+}
+
 export interface SessionsOptions {
   readonly spoke: SpokePort
   /** How long SessionStart waits for the hub's session token (default 3 s). */
@@ -76,6 +85,8 @@ export interface SessionsOptions {
   /** Context for the hub addresses in a user's prompt (design §2.4); undefined when there is none. */
   readonly references?: (prompt: string, sessionID: string) => Promise<string | undefined>
   readonly now?: () => number
+  /** Profile instructions for the hooks to carry (HWA-17). */
+  readonly profiles?: ProfileContextPort
 }
 
 const DEFAULT_TOKEN_WAIT_MS = 3000
@@ -143,6 +154,7 @@ export class ClaudeSessions {
   readonly #projectOf: (cwd: string) => string | undefined
   readonly #references?: SessionsOptions["references"]
   readonly #now: () => number
+  readonly #profiles?: ProfileContextPort
   /** By native session ID. */
   readonly #sessions = new Map<string, Session>()
   /** Hub session ID (root or child) → native root session ID. */
@@ -157,6 +169,7 @@ export class ClaudeSessions {
     this.#projectOf = options.projectOf ?? gitRoot
     this.#references = options.references
     this.#now = options.now ?? Date.now
+    this.#profiles = options.profiles
   }
 
   /** Handles one hook input; never throws for a valid input. */
@@ -175,7 +188,7 @@ export class ClaudeSessions {
     if (ctx.rewake) return this.#rewake(s, ctx)
     switch (event) {
       case "SessionStart":
-        return this.#sessionStart(s, created)
+        return this.#sessionStart(s, created, input.source)
       case "UserPromptSubmit":
         return this.#prompt(s, input)
       case "PreToolUse":
@@ -330,15 +343,17 @@ export class ClaudeSessions {
     return { id, title, directory: cwd, updated: this.#now(), owned: true, ...(parentID ? { parentID } : {}), ...(project ? { project } : {}) }
   }
 
-  async #sessionStart(s: Session, _created: boolean): Promise<HookReply> {
+  async #sessionStart(s: Session, _created: boolean, source: string | undefined): Promise<HookReply> {
+    const profile = this.#profiles?.context(s.hubID, "SessionStart", source)
+    const output = profile ? { output: { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: profile } } } : {}
     const deadline = this.#now() + this.#tokenWaitMs
     let token = this.#spoke.sessionToken(s.hubID)
     while (!token && this.#now() < deadline) {
       await new Promise((resolve) => setTimeout(resolve, TOKEN_POLL_MS))
       token = this.#spoke.sessionToken(s.hubID)
     }
-    if (!token) return {}
-    return { env: { ...(token.url ? { HUB_URL: token.url } : {}), HUB_SESSION_TOKEN: token.token } }
+    if (!token) return output
+    return { env: { ...(token.url ? { HUB_URL: token.url } : {}), HUB_SESSION_TOKEN: token.token }, ...output }
   }
 
   async #prompt(s: Session, input: HookInput): Promise<HookReply> {
@@ -361,6 +376,8 @@ export class ClaudeSessions {
     if (fromUser) this.#emit({ type: "session.inbox.delivered", data: { sessionID: s.hubID, inboxID: `prompt_${turnID}`, origin: "user" } })
     this.#release(s)
     const parts: string[] = []
+    const profile = this.#profiles?.context(s.hubID, "UserPromptSubmit")
+    if (profile) parts.push(profile)
     if (fromUser && this.#references && prompt.includes("@")) {
       const note = await this.#references(prompt, s.hubID).catch(() => undefined)
       if (note) parts.push(note)
@@ -517,6 +534,7 @@ export class ClaudeSessions {
     this.#sessions.delete(native)
     if (s.launch && this.#launches.get(s.launch) === s.hubID) this.#launches.delete(s.launch)
     this.#spoke.endSession(s.hubID)
+    this.#profiles?.ended(s.hubID)
   }
 
   // ---------- permissions ----------