@halofy/agent-connect 0.11.0 → 0.12.1

package/README.md

@@ -1,7 +1,9 @@
 # Halofy agent lifecycle installer
 
-Status: published installer (`@halofy/agent-connect@0.10.0`). The deployment
-workflow pins the verified tarball; host loading requires separate verification.
+Status: source for `@halofy/agent-connect@0.12.1`; publication and deployment
+require separate verification. The production console supplies the command for
+the verified published package pinned by the deployment workflow. Host loading
+requires separate verification.
 
 This package contains the host-neutral client pieces for installation-bound
 agent connections:
@@ -22,10 +24,32 @@ conversations and serves the agent-invoked MCP memory tools, but does not push
 recalled memory into host sessions on session start or prompt submit. The
 bounded recall block formats stay in place and tested for when it returns.
 
-There is one setup path for every packaged client:
+## Browser sign-in
+
+Users assigned to a team can run the installer without a manually copied badge.
+Use the production console’s verified command. After 0.12.1 is published and
+verified, the command for this source version is:
 
 ```bash
-npx --yes @halofy/agent-connect@0.10.0 install <client-kind> \
+npx @halofy/agent-connect@0.12.1 install claude-code --server https://app.halofy.ai
+```
+
+`login <client-kind> --server <origin>` is an alias for the same installation
+flow. The installer opens the existing Halofy sign-in page, displays a public
+verification code, and waits for the user to confirm their authorized team and
+device. Google sign-in is available through the existing console authentication.
+A per-installation Ed25519 key is saved privately before enrollment; the approval
+claim is bound to that same key. Device secrets and claims are never printed or
+put in browser URLs. Retry a failed/expired sign-in with the same command; the
+pending key survives retries. Installation still requires the terminal's
+explicit CONNECT disclosure before changing host configuration.
+
+Browser sign-in requires the matching server enrollment endpoints. The example
+above does not establish that 0.12.1 is published or enabled in production. The
+manual claim path remains supported; after publication, its 0.12.1 form is:
+
+```bash
+npx --yes @halofy/agent-connect@0.12.1 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```
@@ -199,6 +223,16 @@ memory recall. There is no resident instruction daemon; an offline device or a
 host session without an installed startup hook does not fetch updates. Claude's
 existing hook installation is project-scoped even though its rule file is global.
 
+Version 0.12.1 gives instruction GET and its best-effort status receipt one shared
+8-second deadline at startup or direct refresh, and 15 seconds during interactive
+installation. A failed GET preserves current instructions; a receipt timeout does
+not undo a completed local update or prove server acknowledgement. Other request
+and host-hook limits are unchanged; this is not a deadline guarantee for the
+whole startup sequence. Startup runs instruction sync alongside skill/reference
+delivery, including while capture is paused, so slow reference downloads or
+receipts do not hold up the instruction fetch. Replay and heartbeat still follow
+both refreshes.
+
 | Host | Local target | Boundaries |
 |---|---|---|
 | Codex | `CODEX_HOME` or `~/.codex`, active nonempty `AGENTS.override.md` else `AGENTS.md` | Marked section; changing the active target reports a conflict |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halofy/agent-connect",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "description": "Halofy lifecycle installer and runtime for supported agents; runtime requests are signed with a per-installation Ed25519 key",
   "bin": {

package/src/claude-hook.mjs

@@ -12,6 +12,15 @@ export async function syncSkillsAtSessionStart(runtime, connection, root, stderr
   return result.skills;
 }
 
+/** Disjoint owned files and locks let instructions refresh without waiting for
+ * skill/reference downloads or their receipt. Both settle before capture work. */
+export async function syncConfigurationAtSessionStart(runtime, connection, root, stderr, syncOptions = {}) {
+  await Promise.allSettled([
+    Promise.resolve().then(() => runtime.syncInstructions?.()),
+    syncSkillsAtSessionStart(runtime, connection, root, stderr, syncOptions),
+  ]);
+}
+
 function id(value) {
   return createHash("sha256").update(String(value)).digest("hex");
 }
@@ -96,9 +105,8 @@ export async function runClaudeLifecycleHook(connection, eventName, {
     const runtime = runtimeFactory(connection, { root, captureGeneration: capture.generation });
     if (capture.paused) {
       if (eventName === "SessionStart") {
-        await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
-        // Capture pause does not suspend governed instruction delivery.
-        await runtime.syncInstructions?.().catch(() => {});
+        // Capture pause does not suspend instruction or reference delivery.
+        await syncConfigurationAtSessionStart(runtime, connection, root, stderr, { home, env });
         await runtime.heartbeat(connection.capabilities || {});
       } else if (eventName === "UserPromptSubmit") {
         const delivery = await syncManagedDelivery({ connection, transport: runtime.transport, root, home, env, stderr, phase: "turn" });
@@ -110,9 +118,7 @@ export async function runClaudeLifecycleHook(connection, eventName, {
 
     if (eventName === "SessionStart") {
       // Refresh/withdraw local context even when replay or heartbeat fails.
-      await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
-      // Instructions have their own brownout boundary, independent of recall.
-      await runtime.syncInstructions?.().catch(() => {});
+      await syncConfigurationAtSessionStart(runtime, connection, root, stderr, { home, env });
       await runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
       if (RECALL_INJECTION_ENABLED) {

package/src/enrollment.mjs

@@ -0,0 +1,83 @@
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { generateInstallationKeyPair } from "./crypto.mjs";
+import { normalizeLifecycleServerUrl } from "./install.mjs";
+import { readJson, writePrivateFile, defaultRuntimeDirectory } from "./storage.mjs";
+import { CLIENT_KINDS } from "./client-registry.mjs";
+
+export async function prepareInstallationKey(root, clientKind) {
+  const path = join(root, `pending-${clientKind}.json`);
+  const previous = await readJson(path);
+  if (previous) {
+    if (!previous.publicJwk || !previous.privateJwk || !previous.installationIdCandidate) {
+      throw new Error("pending installation key is invalid; repair local runtime storage before retrying");
+    }
+    return previous;
+  }
+  const key = { ...generateInstallationKeyPair(), installationIdCandidate: `local_${randomUUID()}` };
+  await writePrivateFile(path, `${JSON.stringify(key)}\n`);
+  return key;
+}
+
+export function openVerificationBrowser(uri) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
+  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", uri] : [uri];
+  const child = spawn(command, args, { shell: false, detached: true, stdio: "ignore" });
+  child.on("error", () => {}); // Printed URL remains usable when there is no desktop browser.
+  child.unref();
+}
+
+/** Device secrets stay in memory. Only the public human code reaches browser/terminal. */
+export async function enrollWithBrowser({ serverUrl, clientKind, root = defaultRuntimeDirectory(),
+  fetchImpl = globalThis.fetch, output = process.stdout, openBrowser = openVerificationBrowser,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now }) {
+  if (!CLIENT_KINDS.includes(clientKind)) throw new Error("unsupported enrollment client");
+  const server = normalizeLifecycleServerUrl(serverUrl);
+  const base = new URL(server);
+  if (!["https:", "http:"].includes(base.protocol) || base.username || base.password || base.search || base.hash || base.pathname !== "/") {
+    throw new Error("sign-in requires a server origin without credentials, path or query");
+  }
+  const key = await prepareInstallationKey(root, clientKind);
+  async function request(path, body) {
+    let response;
+    try {
+      response = await fetchImpl(`${server}/v1/agent-enrollment/${path}`, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
+        redirect: "error", signal: AbortSignal.timeout(15_000),
+      });
+    } catch { throw new Error("sign-in connection unavailable; retry sign-in"); }
+    if (!response.ok) {
+      throw new Error(response.status === 429 ? "sign-in rate limit reached; try again later" :
+        response.status === 410 ? "sign-in expired; retry sign-in" : "sign-in denied or unavailable; retry sign-in");
+    }
+    try { return await response.json(); } catch { throw new Error("invalid sign-in response"); }
+  }
+  const start = await request("start", { clientKind, publicKeyJwk: key.publicJwk });
+  let uri;
+  try { uri = new URL(start.verificationUri); } catch { throw new Error("invalid sign-in response"); }
+  if (typeof start.deviceCode !== "string" || !/^[A-Za-z0-9_-]{32,128}$/.test(start.deviceCode) ||
+      typeof start.userCode !== "string" || !/^[A-Za-z0-9-]{4,32}$/.test(start.userCode) ||
+      uri.origin !== base.origin || uri.username || uri.password || uri.pathname !== "/console/connect" ||
+      uri.hash || uri.search !== `?code=${start.userCode}` ||
+      !Number.isFinite(start.expiresIn) || start.expiresIn <= 0 || start.expiresIn > 1800 ||
+      !Number.isFinite(start.interval) || start.interval < 1 || start.interval > 60) {
+    throw new Error("invalid sign-in response");
+  }
+  const deadline = now() + start.expiresIn * 1000;
+  output.write(`Sign in and confirm this device: ${uri.href}\nCode: ${start.userCode}\n`);
+  try { await openBrowser(uri.href); } catch { /* URL is available for manual opening. */ }
+  while (now() < deadline) {
+    await sleep(start.interval * 1000);
+    if (now() >= deadline) break;
+    const token = await request("token", { deviceCode: start.deviceCode });
+    if (token.status === "pending") continue;
+    if (token.status === "expired") throw new Error("sign-in expired; retry sign-in");
+    if (token.status === "denied") throw new Error("sign-in denied; retry sign-in");
+    if (token.status !== "approved" || token.clientKind !== clientKind ||
+        typeof token.claim !== "string" || !/^hsc_[A-Za-z0-9_-]{43}$/.test(token.claim) ||
+        typeof token.organization !== "string" || !token.organization.trim()) throw new Error("invalid sign-in response");
+    return { claim: token.claim, organization: token.organization.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().slice(0, 100) };
+  }
+  throw new Error("sign-in expired; retry sign-in");
+}

package/src/host-hook.mjs

@@ -9,7 +9,7 @@ import {
   rankedRecallBlocks,
 } from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
-import { readHookInput, syncSkillsAtSessionStart } from "./claude-hook.mjs";
+import { readHookInput, syncConfigurationAtSessionStart } from "./claude-hook.mjs";
 import { syncManagedDelivery } from "./delivery-sync.mjs";
 import { transcriptDriverFor } from "./transcript-drivers/index.mjs";
 
@@ -161,9 +161,8 @@ export async function runHostLifecycleHook(connection, eventName, {
     const runtime = runtimeFactory(connection, { root, captureGeneration: capture.generation });
     if (capture.paused) {
       if (START_EVENTS.has(eventName)) {
-        await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
-        // Capture pause does not suspend governed instruction delivery.
-        await runtime.syncInstructions?.().catch(() => {});
+        // Capture pause does not suspend instruction or reference delivery.
+        await syncConfigurationAtSessionStart(runtime, connection, root, stderr, { home, env });
         await runtime.heartbeat(connection.capabilities || {});
       } else if (USER_EVENTS.has(eventName)) {
         const delivery = await syncManagedDelivery({ connection, transport: runtime.transport, root, home, env, stderr, phase: "turn" });
@@ -175,9 +174,7 @@ export async function runHostLifecycleHook(connection, eventName, {
 
     if (START_EVENTS.has(eventName)) {
       // Refresh/withdraw local context even when replay or heartbeat fails.
-      await syncSkillsAtSessionStart(runtime, connection, root, stderr, { home, env });
-      // Instructions have their own brownout boundary, independent of recall.
-      await runtime.syncInstructions?.().catch(() => {});
+      await syncConfigurationAtSessionStart(runtime, connection, root, stderr, { home, env });
       await runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
       if (RECALL_INJECTION_ENABLED) {

package/src/install.mjs

@@ -4,7 +4,7 @@ import { chmod, cp, rename, rm, unlink } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { generateInstallationKeyPair } from "./crypto.mjs";
 import { ConnectionStore, defaultRuntimeDirectory, ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
-import { syncAgentInstructions } from "./instructions.mjs";
+import { INSTALL_INSTRUCTION_SYNC_TIMEOUT_MS, syncAgentInstructions } from "./instructions.mjs";
 import { SignedRuntimeTransport } from "./transport.mjs";
 import { inspectCaptureHealth } from "./health.mjs";
 import { INSTALLER_VERSION, RUNTIME_VERSION } from "./version.mjs";
@@ -232,7 +232,7 @@ export async function installLocalConnection({
     }
   }
   const instructions = instructionProfile
-    ? await syncAgentInstructions(connection, { root, transport: new SignedRuntimeTransport(connection, { fetchImpl, timeoutMs: 2_000 }) })
+    ? await syncAgentInstructions(connection, { root, fetchImpl, timeoutMs: INSTALL_INSTRUCTION_SYNC_TIMEOUT_MS })
     : undefined;
   return {
     installationId,

package/src/installer-cli.mjs

@@ -1,3 +1,4 @@
+import { enrollWithBrowser } from "./enrollment.mjs";
 import { recordHealthTargets } from "./health.mjs";
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
@@ -78,9 +79,9 @@ export function parseInstallerArgs(argv) {
   }
   const serverUrl = values.get("--server");
   const claim = values.get("--claim");
-  if (command !== "install" || !CLIENT_KINDS.includes(clientKind) || !serverUrl || !claim ||
-      !/^hsc_[A-Za-z0-9_-]{43}$/.test(claim)) {
-    throw new Error("Usage: agent-connect install <supported-client> --server <https-url> --claim <one-use-claim>");
+  if (!["install", "login"].includes(command) || !CLIENT_KINDS.includes(clientKind) || !serverUrl ||
+      (claim !== undefined && !/^hsc_[A-Za-z0-9_-]{43}$/.test(claim))) {
+    throw new Error("Usage: agent-connect install|login <supported-client> --server <https-url> [--claim <one-use-claim>]");
   }
   return {
     mode: "single",
@@ -426,6 +427,9 @@ export async function runInstaller(argv, {
   sourceRoot,
   claudeConfigPath,
   skillsHome,
+  openBrowser,
+  enrollmentSleep,
+  enrollmentNow,
 } = {}) {
   const input = parseInstallerArgs(argv);
   if (input.mode === "all") {
@@ -435,7 +439,13 @@ export async function runInstaller(argv, {
     });
   }
   const clientVersion = input.clientKind === "claude-code" ? await detectClaude() : await detectHost(input.clientKind);
-  const claimDisclosure = await fetchClaimDisclosure({
+  const enrollment = !input.claim ? await enrollWithBrowser({
+    serverUrl: input.serverUrl, clientKind: input.clientKind, root, fetchImpl, output,
+    ...(openBrowser ? { openBrowser } : {}), ...(enrollmentSleep ? { sleep: enrollmentSleep } : {}),
+    ...(enrollmentNow ? { now: enrollmentNow } : {}),
+  }) : null;
+  if (enrollment) input.claim = enrollment.claim;
+  const claimDisclosure = enrollment || await fetchClaimDisclosure({
     serverUrl: input.serverUrl,
     claim: input.claim,
     fetchImpl,

package/src/instructions.mjs

@@ -7,6 +7,9 @@ import { isActiveInstallation } from "./active.mjs";
 import { ConnectionStore, readJson } from "./storage.mjs";
 import { SignedRuntimeTransport } from "./transport.mjs";
 
+export const INSTRUCTION_SYNC_TIMEOUT_MS = 8_000;
+export const INSTALL_INSTRUCTION_SYNC_TIMEOUT_MS = 15_000;
+
 const sha = (value) => createHash("sha256").update(value).digest("hex");
 const HEX = /^[a-f0-9]{64}$/;
 const MARKER = "<!-- HALOFY-INSTRUCTIONS:";
@@ -247,20 +250,32 @@ async function retirePredecessorInstructions(connection, root) {
   }
 }
 
-/** Separate best-effort operation: a failed GET never means remove instructions. */
-export async function syncAgentInstructions(connection, { root, transport = new SignedRuntimeTransport(connection, { timeoutMs: 2_000 }) } = {}) {
+/** Separate best-effort operation: a failed GET never means remove instructions.
+ * GET and receipt share one deadline so a slow receipt cannot double startup delay.
+ * An explicitly injected transport retains its own cancellation policy. */
+export async function syncAgentInstructions(connection, {
+  root, transport, fetchImpl = globalThis.fetch, timeoutMs = INSTRUCTION_SYNC_TIMEOUT_MS,
+} = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const activeTransport = transport ?? new SignedRuntimeTransport(connection, {
+    fetchImpl, timeoutMs, signal: controller.signal,
+  });
   let receipt = { digest: sha("[]"), status: "unavailable", reason: "fetch_unavailable" };
   try {
-    if (!(await isActiveInstallation(connection, root))) return { ...receipt, status: "unsupported", reason: "inactive_installation" };
-    await retirePredecessorInstructions(connection, root);
-    const bundle = await transport.instructions();
-    receipt.digest = typeof bundle?.digest === "string" && HEX.test(bundle.digest) ? bundle.digest : receipt.digest;
-    receipt = await applyInstructionBundle(connection, bundle, { root, canActivate: () => isActiveInstallation(connection, root) });
-  } catch (error) {
-    const reason = error.instructionCode;
-    const unsupported = ["custom_context_unsupported", "reinstall_required", "inactive_installation"].includes(reason);
-    receipt = { ...receipt, status: unsupported ? "unsupported" : reason && reason !== "invalid_bundle" ? "conflict" : "unavailable", reason: reason || "fetch_unavailable" };
-  }
-  try { await transport.instructionStatus(receipt); } catch { /* A receipt failure cannot disable capture/MCP. */ }
-  return receipt;
+    try {
+      if (!(await isActiveInstallation(connection, root))) return { ...receipt, status: "unsupported", reason: "inactive_installation" };
+      await retirePredecessorInstructions(connection, root);
+      const bundle = await activeTransport.instructions();
+      if (!transport) controller.signal.throwIfAborted();
+      receipt.digest = typeof bundle?.digest === "string" && HEX.test(bundle.digest) ? bundle.digest : receipt.digest;
+      receipt = await applyInstructionBundle(connection, bundle, { root, canActivate: () => isActiveInstallation(connection, root) });
+    } catch (error) {
+      const reason = error.instructionCode;
+      const unsupported = ["custom_context_unsupported", "reinstall_required", "inactive_installation"].includes(reason);
+      receipt = { ...receipt, status: unsupported ? "unsupported" : reason && reason !== "invalid_bundle" ? "conflict" : "unavailable", reason: reason || "fetch_unavailable" };
+    }
+    try { await activeTransport.instructionStatus(receipt); } catch { /* A receipt failure cannot disable capture/MCP. */ }
+    return receipt;
+  } finally { clearTimeout(timer); }
 }

package/src/runtime.mjs

@@ -16,7 +16,7 @@ export class LifecycleRuntime {
   constructor(connection, {
     root,
     transport = new SignedRuntimeTransport(connection),
-    instructionTransport = new SignedRuntimeTransport(connection, { timeoutMs: 2_000 }),
+    instructionTransport,
     maxBatchEvents = 100,
     maxBatchBytes = 1024 * 1024,
     commitThreshold = 20,

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.11.0";
-export const RUNTIME_VERSION = "0.11.0";
+export const INSTALLER_VERSION = "0.12.1";
+export const RUNTIME_VERSION = "0.12.1";
 export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-10.1";