@huynle/hub 0.7.3 → 0.8.0

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 ----------