@halofy/agent-connect 0.13.1 → 0.14.0

package/README.md

@@ -1,6 +1,6 @@
 # Halofy agent lifecycle installer
 
-Status: source for `@halofy/agent-connect@0.13.1`; publication and deployment
+Status: source for `@halofy/agent-connect@0.14.0`; 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.
@@ -24,6 +24,31 @@ 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.
 
+## AI budget delivery and controlled submissions (0.14.0 source)
+
+Installation, session-start and explicit sync refresh the installation's own
+structured budget state through signed `/v1/agent-runtime/budget/check`.
+Claude `UserPromptSubmit` checks again before each submitted turn, even with
+capture paused, and returns a mechanical blocking decision when a turn-limited
+budget is exhausted or usage cannot be verified. Cached balances never grant
+work. The check has a three-second network deadline; failures cannot silently
+disable a previously enforced budget. An older kernel without this endpoint is
+explicitly monitoring only until upgraded.
+
+This requires trusted execution of the installed hook. It limits new submitted
+turns based on observed API-equivalent estimates; it cannot stop every internal
+model call or subagent, bound subscription invoices, or control a user who
+removes the hook. Kimi, Codex, Cursor, Gemini, Cline, VS Code and Hermes remain
+monitoring through this package until their blocking boundaries are separately
+verified. The account/team budget applies across all captured models; no model
+choice is inferred from an agent label. See the
+[Claude hook decision contract](https://code.claude.com/docs/en/hooks#userpromptsubmit-decision-control).
+
+The local `budget-<installation-id>.json` file is diagnostic configuration,
+not financial authority. `sync` and installer results report budget status
+separately from instruction/skill delivery. Publication, server deployment and
+real-host enforcement still require release verification.
+
 ## Headless host limits and explicit refresh
 
 Codex `exec` lifecycle hooks are not verified. A local Codex CLI 0.154.0
@@ -311,6 +336,19 @@ updated disposable installation. Existing local runtimes do not auto-upgrade.
 
 ## Organization instructions (0.10.0)
 
+Version 0.13.2 includes an MCP policy validator extension.
+It accepts one final generated `Required MCP access policy` document in the
+connection's exact namespace, alongside ordinary authored instructions. That
+document may exceed 16 KiB; the complete instruction bundle still cannot exceed
+64 KiB. Ordinary documents keep their 16 KiB limit and unique, ordered ancestor
+scopes. Content hashes, bundle digest, UTF-8 and managed-marker checks still apply.
+Existing installed `0.13.1` runtimes without this extension reject same-scope
+authored/generated pairs and generated policies above 16 KiB. They need an
+upgraded runtime. The exact 0.13.2 publication and artifact verification are
+recorded in [release evidence](../../../docs/operations/workspace-onboarding-rollout.md).
+Publication does not upgrade existing installations. Invalid bundles leave
+existing local files untouched.
+
 This source adds Govern instruction delivery alongside the existing skill,
 policy, knowledge and delivery-receipt paths. Activation requires the reviewed
 0.10.0 npm publication, matching server deployment and a fresh confirmed

package/bin/halofy-agent.mjs

@@ -10,6 +10,7 @@ import { HERMES_HOOK_EVENTS, runHermesLifecycleHook } from "../src/hermes-hook.m
 import { LifecycleRuntime } from "../src/runtime.mjs";
 import { inspectCaptureHealth, setCapturePaused } from "../src/health.mjs";
 import { refreshManagedConfiguration } from "../src/delivery-sync.mjs";
+import { budgetBlockReason } from "../src/budgets.mjs";
 import { RUNTIME_VERSION } from "../src/version.mjs";
 import { join, resolve } from "node:path";
 import { realpath } from "node:fs/promises";
@@ -134,9 +135,10 @@ if (!["mcp", "hermes-mcp", "diagnostics", "hook", "hermes-hook", "pause", "resum
     }
   } catch (error) {
     if (hookEvent === "PreToolUse") process.stdout.write(`${JSON.stringify(skillInvocationDenial())}\n`);
+    if (hookEvent === "UserPromptSubmit") process.stdout.write(`${JSON.stringify({ decision: "block", reason: budgetBlockReason("usage_unavailable") })}\n`);
     process.stderr.write(`${command === "diagnostics" ? "Halofy diagnostics unavailable" :
       error?.message || "Halofy MCP proxy unavailable"}\n`);
-    process.exitCode = hookEvent === "PreToolUse" ? 0 : 1;
+    process.exitCode = ["PreToolUse", "UserPromptSubmit"].includes(hookEvent) ? 0 : 1;
   }
 }
 

package/package.json

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

package/src/budgets.mjs

@@ -0,0 +1,112 @@
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { readPrivateJson, withContextLock } from "./context-sync.mjs";
+import { safeDirectory, writePrivateFile } from "./storage.mjs";
+
+const MODES = new Set(["monitoring", "turn_limited"]);
+const REASONS = new Set(["ok", "budget_exhausted", "usage_unavailable"]);
+const BASES = new Set(["catalog_estimate", "unavailable", "not_observed"]);
+const amount = (value) => value === null || (typeof value === "number" && Number.isFinite(value) && value >= 0);
+
+/** No cached balance grants work. The stored response is diagnostic state only. */
+export function validateBudgetConfiguration(value) {
+  if (!value || value.schemaVersion !== 1 || typeof value.version !== "string" || value.version.length > 256
+    || !MODES.has(value.mode) || !MODES.has(value.capability) || !REASONS.has(value.reason)
+    || !BASES.has(value.usageBasis) || typeof value.configured !== "boolean" || typeof value.allowed !== "boolean"
+    || typeof value.warning !== "boolean" || value.warningPercent !== 80
+    || ![value.periodStart, value.periodEnd, value.asOf].every((date) => typeof date === "string" && Number.isFinite(Date.parse(date)))
+    || Date.parse(value.periodStart) >= Date.parse(value.periodEnd)
+    || !Array.isArray(value.policies) || value.policies.length > 2
+    || !Array.isArray(value.balances) || value.balances.length > 4
+    || value.balances.some((balance) => !balance || !["team", "account", "agent", "shared"].includes(balance.scope)
+      || !amount(balance.limitUsd) || !amount(balance.spentUsd) || !amount(balance.reservedUsd)
+      || balance.reservedUsd === null || !amount(balance.availableUsd))
+    || (value.mode === "turn_limited" && value.allowed && value.reason !== "ok")) {
+    throw new Error("invalid_budget_configuration");
+  }
+  return value;
+}
+
+export function budgetBlockReason(reason) {
+  return reason === "budget_exhausted"
+    ? "Your Halofy AI budget has been reached. Ask your manager to increase the budget before starting another turn."
+    : "Halofy could not verify your current AI budget. Retry when the workspace is available; this turn has not started.";
+}
+
+async function readBudgetState(path) {
+  const saved = await readPrivateJson(path);
+  if (saved === null) {
+    // readPrivateJson uses null for an absent file. A present JSON null is
+    // damaged evidence, not an installation that has never seen enforcement.
+    try { await lstat(path); }
+    catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+    throw new Error("invalid_budget_state");
+  }
+  if (!saved || !MODES.has(saved.capability) || typeof saved.checkedAt !== "string"
+    || !Number.isFinite(Date.parse(saved.checkedAt))) throw new Error("invalid_budget_state");
+  validateBudgetConfiguration(saved.configuration);
+  return saved;
+}
+
+function assertFreshBudget(configuration) {
+  const now = Date.now();
+  if (Date.parse(configuration.asOf) < now - 120_000 || Date.parse(configuration.asOf) > now + 30_000
+    || Date.parse(configuration.periodStart) > now || Date.parse(configuration.periodEnd) <= now) {
+    throw new Error("stale_budget_configuration");
+  }
+}
+
+export async function refreshBudgetConfiguration({ connection, transport, root, stderr = process.stderr }) {
+  const capable = connection.clientKind === "claude-code";
+  const unavailable = (legacy = false) => {
+    const denied = capable && !legacy;
+    stderr.write(`[halofy] AI budget ${legacy ? "monitoring: server upgrade required" : "unavailable"}; ${denied ? "new turn blocked" : "monitoring only"}\n`);
+    return { status: legacy ? "unsupported" : "unavailable", capability: capable && !legacy ? "turn_limited" : "monitoring",
+      denied, reason: "usage_unavailable" };
+  };
+  try {
+    if (typeof connection.installationId !== "string" || !/^[A-Za-z0-9_-]{1,160}$/.test(connection.installationId)) throw new Error("invalid_installation");
+    await safeDirectory(root, true);
+    const path = join(root, `budget-${connection.installationId}.json`);
+    const lockRoot = join(root, `budget-${connection.installationId}`);
+    await safeDirectory(lockRoot, true);
+    // Hooks may run in separate processes. Do not hold the state lock while
+    // waiting for HTTP, but decide against the latest state after it settles.
+    let response, failure;
+    try {
+      if (typeof transport?.budgetCheck !== "function") throw new Error("budget_transport_unavailable");
+      response = await transport.budgetCheck();
+    } catch (error) { failure = error; }
+    return await withContextLock(lockRoot, async () => {
+      const previous = await readBudgetState(path);
+      if (failure) {
+        // Legacy fallback is allowed only after checking the current record
+        // under the same lock used by all successful observation writers.
+        return unavailable(failure?.status === 404 && previous?.configuration.mode !== "turn_limited");
+      }
+      const configuration = validateBudgetConfiguration(response);
+      assertFreshBudget(configuration);
+      if (previous) {
+        const observedAt = Date.parse(configuration.asOf);
+        const previousAt = Date.parse(previous.configuration.asOf);
+        if (observedAt < previousAt || (observedAt === previousAt && previous.configuration.mode === "turn_limited"
+          && (configuration.mode !== "turn_limited" || ((!previous.configuration.allowed
+            || previous.configuration.capability !== "turn_limited") && configuration.allowed)))) {
+          throw new Error("outdated_budget_configuration");
+        }
+      }
+      const capability = capable && configuration.capability === "turn_limited" ? "turn_limited" : "monitoring";
+      // Persist a valid requirement even if this host cannot meet its advertised
+      // capability. A later 404 must not erase this first enforced observation.
+      await writePrivateFile(path, JSON.stringify({ configuration, capability, checkedAt: new Date().toISOString() }));
+      assertFreshBudget(configuration);
+      if (capable && configuration.mode === "turn_limited" && capability !== "turn_limited") return unavailable();
+      const denied = capability === "turn_limited" && configuration.mode === "turn_limited" && !configuration.allowed;
+      return { status: "ready", capability, denied, reason: configuration.reason, configuration };
+    }, { timeoutMs: 1_000 });
+  } catch {
+    // Unsafe, malformed, stale or unavailable evidence never enables Claude.
+    // Unsupported host hook protocols remain explicitly monitoring.
+    return unavailable();
+  }
+}

package/src/claude-hook.mjs

@@ -6,6 +6,7 @@ import { LifecycleRuntime } from "./runtime.mjs";
 import { normalizeClaudeHookEvent, RECALL_INJECTION_ENABLED, rankedRecallBlocks } from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
 import { syncManagedDelivery } from "./delivery-sync.mjs";
+import { budgetBlockReason, refreshBudgetConfiguration } from "./budgets.mjs";
 
 /** Shared delivery refresh remains independent of capture/heartbeat brownouts. */
 export async function syncSkillsAtSessionStart(runtime, connection, root, stderr, syncOptions = {}) {
@@ -19,6 +20,7 @@ export async function syncConfigurationAtSessionStart(runtime, connection, root,
   await Promise.allSettled([
     Promise.resolve().then(() => runtime.syncInstructions?.()),
     syncSkillsAtSessionStart(runtime, connection, root, stderr, syncOptions),
+    refreshBudgetConfiguration({ connection, transport: runtime.transport, root, stderr }),
   ]);
 }
 
@@ -98,6 +100,7 @@ export async function runClaudeLifecycleHook(connection, eventName, {
   env,
   runtimeFactory = (activeConnection, options) => new LifecycleRuntime(activeConnection, options),
 } = {}) {
+  let budgetVerified = false;
   try {
     const hookInput = input ?? await readHookInput();
     if (eventName === "PreToolUse") {
@@ -105,10 +108,20 @@ export async function runClaudeLifecycleHook(connection, eventName, {
       if (decision) stdout.write(JSON.stringify(decision));
       return { handled: true, denied: Boolean(decision) };
     }
-    const session = hostSession(hookInput);
-    if (!session) return { handled: true };
     const capture = await captureStateSnapshot(root, connection.installationId);
     const runtime = runtimeFactory(connection, { root, captureGeneration: capture.generation });
+    // This is a host decision, not an instruction asking the model to stop.
+    // Check before session/capture gates, including when capture is paused.
+    if (eventName === "UserPromptSubmit") {
+      const budget = await refreshBudgetConfiguration({ connection, transport: runtime.transport, root, stderr });
+      if (budget.denied) {
+        stdout.write(JSON.stringify({ decision: "block", reason: budgetBlockReason(budget.reason) }));
+        return { handled: true, denied: true, budget };
+      }
+      budgetVerified = true;
+    }
+    const session = hostSession(hookInput);
+    if (!session) return { handled: true };
     if (capture.paused) {
       if (eventName === "SessionStart") {
         // Capture pause does not suspend instruction or reference delivery.
@@ -203,6 +216,7 @@ export async function runClaudeLifecycleHook(connection, eventName, {
     return { handled: true };
   } catch (error) {
     if (eventName === "PreToolUse") stdout.write(JSON.stringify(skillInvocationDenial()));
+    if (eventName === "UserPromptSubmit" && !budgetVerified) stdout.write(JSON.stringify({ decision: "block", reason: budgetBlockReason("usage_unavailable") }));
     const code = error && typeof error === "object" && typeof error.code === "string"
       ? error.code : "runtime_unavailable";
     stderr.write(`[halofy] lifecycle hook degraded: ${code}\n`);

package/src/context-sync.mjs

@@ -44,14 +44,18 @@ async function saveManifest(stateRoot, value) {
   await rename(temporary, join(stateRoot, "manifest.json"));
 }
 
-export async function withContextLock(stateRoot, action) {
+export async function withContextLock(stateRoot, action, { timeoutMs = 120_000 } = {}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw fail("invalid_lock_timeout");
   const lockPath = join(stateRoot, "refresh.lock");
   const candidate = join(stateRoot, `lock-${process.pid}-${randomBytes(12).toString("hex")}.tmp`);
   await privateFile(candidate, JSON.stringify({ pid: process.pid }));
   const started = Date.now();
   let acquired = false;
+  let firstAttempt = true;
   try {
     while (!acquired) {
+      if (!firstAttempt && Date.now() - started >= timeoutMs) throw fail("context_sync_busy");
+      firstAttempt = false;
       try { await link(candidate, lockPath); acquired = true; }
       catch (error) {
         if (error?.code !== "EEXIST") throw error;
@@ -61,7 +65,10 @@ export async function withContextLock(stateRoot, action) {
         let owner;
         try { owner = await readPrivateJson(lockPath); }
         catch (readError) { if (readError?.code === "ENOENT") continue; throw readError; }
-        if (owner === null) continue;
+        if (owner === null) {
+          if (await state(lockPath)) throw fail("unsafe_lock");
+          continue;
+        }
         if (!Number.isSafeInteger(owner?.pid) || owner.pid <= 0) throw fail("unsafe_lock");
         let dead = false;
         try { process.kill(owner.pid, 0); } catch (probe) { if (probe?.code === "ESRCH") dead = true; }
@@ -75,7 +82,7 @@ export async function withContextLock(stateRoot, action) {
             if (latest?.ino === entry.ino && latest?.dev === entry.dev) await rm(lockPath);
           } catch (recoveryError) {
             if (recoveryError?.code !== "EEXIST" && recoveryError?.code !== "ENOENT") throw recoveryError;
-            if (Date.now() - started > 120_000) throw fail("context_sync_busy");
+            if (Date.now() - started >= timeoutMs) throw fail("context_sync_busy");
             await new Promise((done) => setTimeout(done, 25));
           } finally {
             if (recovering) await rm(recovery, { recursive: true });
@@ -83,7 +90,7 @@ export async function withContextLock(stateRoot, action) {
           continue;
         }
         // Never steal a live writer's lock because a network page was slow.
-        if (Date.now() - started > 120_000) throw fail("context_sync_busy");
+        if (Date.now() - started >= timeoutMs) throw fail("context_sync_busy");
         await new Promise((done) => setTimeout(done, 25));
       }
     }

package/src/delivery-sync.mjs

@@ -5,20 +5,22 @@ import { safeDirectory, readPrivateJson, withContextLock, readManagedContextTupl
 import { syncManagedSkills, readManagedSkillTuples, describeSkillSync } from "./skills-sync.mjs";
 import { retirePredecessorContent } from "./predecessor-sync.mjs";
 import { writePrivateFile } from "./storage.mjs";
+import { refreshBudgetConfiguration } from "./budgets.mjs";
 
 export const DELIVERY_NOTICE = "Halofy managed policies, skills, or knowledge references changed during this conversation. Start a new session to load the current references; previously loaded content may be outdated. File delivery does not confirm policy compliance.";
 
 /** Explicit file refresh for hosts/modes without observed lifecycle hooks.
  * Never fabricate a host session or enqueue/capture conversation events. */
 export async function refreshManagedConfiguration(runtime, connection, root, { stderr = process.stderr, ...options } = {}) {
-  const [instructions, delivery] = await Promise.allSettled([
+  const [instructions, delivery, budgets] = await Promise.allSettled([
     Promise.resolve().then(() => runtime.syncInstructions()),
     syncManagedDelivery({ ...options, connection, transport: runtime.transport, root, stderr, phase: "start" }),
+    refreshBudgetConfiguration({ connection, transport: runtime.transport, root, stderr }),
   ]);
   const instructionStatus = instructions.status === "fulfilled" ? instructions.value?.status ?? "unavailable" : "unavailable";
   const deliveryOutcome = delivery.status === "fulfilled" ? delivery.value.outcome : "failed";
   const acknowledged = delivery.status === "fulfilled" && delivery.value.acknowledged === true;
-  return { instructionStatus, deliveryOutcome, acknowledged,
+  return { instructionStatus, deliveryOutcome, acknowledged, budgets: budgets.status === "fulfilled" ? budgets.value : { status: "unavailable" },
     ready: ["installed", "pending_restart"].includes(instructionStatus) && deliveryOutcome === "synced" && acknowledged };
 }
 const SHA = /^[a-f0-9]{64}$/;

package/src/host-hook.mjs

@@ -11,6 +11,7 @@ import { defaultRuntimeDirectory } from "./storage.mjs";
 import { readHookInput, syncConfigurationAtSessionStart } from "./claude-hook.mjs";
 import { syncManagedDelivery } from "./delivery-sync.mjs";
 import { transcriptDriverFor } from "./transcript-drivers/index.mjs";
+import { refreshBudgetConfiguration } from "./budgets.mjs";
 
 const USER_EVENTS = new Set(["UserPromptSubmit", "beforeSubmitPrompt", "BeforeAgent", "pre_llm_call"]);
 const ASSISTANT_EVENTS = new Set(["afterAgentResponse", "AfterAgent", "post_llm_call", "transform_llm_output"]);
@@ -157,6 +158,9 @@ export async function runHostLifecycleHook(connection, eventName, {
     if (!session) return { handled: true, unavailable: "missing_host_session" };
     const capture = await captureStateSnapshot(root, connection.installationId);
     const runtime = runtimeFactory(connection, { root, captureGeneration: capture.generation });
+    // Other host hook protocols remain monitoring until their blocking boundary
+    // has its own conformance test. Budget delivery never upgrades that claim.
+    if (USER_EVENTS.has(eventName)) await refreshBudgetConfiguration({ connection, transport: runtime.transport, root, stderr });
     if (capture.paused) {
       if (START_EVENTS.has(eventName)) {
         // Capture pause does not suspend instruction or reference delivery.

package/src/install.mjs

@@ -14,6 +14,7 @@ import { syncManagedSkills } from "./skills-sync.mjs";
 import { syncManagedDelivery } from "./delivery-sync.mjs";
 import { retirePredecessorContent } from "./predecessor-sync.mjs";
 import { syncManagedContext } from "./context-sync.mjs";
+import { refreshBudgetConfiguration } from "./budgets.mjs";
 
 export const CLAUDE_CAPABILITIES = CLIENT_REGISTRY["claude-code"].capabilities;
 
@@ -239,10 +240,13 @@ export async function installLocalConnection({
   const instructions = instructionProfile
     ? await syncAgentInstructions(connection, { root, fetchImpl, timeoutMs: INSTALL_INSTRUCTION_SYNC_TIMEOUT_MS })
     : undefined;
+  const budgets = await refreshBudgetConfiguration({ connection, root,
+    transport: new SignedRuntimeTransport(connection, { fetchImpl, timeoutMs: 3_000 }) });
   return {
     installationId,
     previousInstallationId: connection.previousInstallationId ?? null,
     ...(instructions ? { instructions } : {}),
+    budgets,
     heartbeat,
     reused: false,
     proofStorage: connection.proofStorage,

package/src/installer-cli.mjs

@@ -207,6 +207,7 @@ export function disclosureText({ serverUrl, projectRoot, clientKind, clientVersi
     "Organization instructions: supported adapters manage an additive global rule file or marked section across projects in the selected local agent profile. Existing personal instructions are preserved. Updates sync at installation and supported session starts; restart the host to load changes.",
     "Other OS accounts, containers, remote/cloud hosts and unsupported agents are not covered. Instruction precedence remains controlled by the host.",
     "Disconnecting stops future capture but does not erase retained data.",
+    "AI budgets: fresh signed limits are delivered with configuration. Trusted Claude prompt-submit hooks can block new turns when an enforced budget is exhausted or unavailable, including while capture is paused. Other packaged hosts are monitoring only. Internal model calls, subagents and subscription billing are not a hard monetary ceiling.",
     `Disclosure: ${DISCLOSURE_VERSION}`,
   ].join("\n");
 }
@@ -264,6 +265,7 @@ export function allDisclosureText({ serverUrl, projectRoot, organization = null,
     "Organization instructions: supported adapters manage an additive global rule file or marked section across projects in the selected local agent profile. Existing personal instructions are preserved. Updates sync at installation and supported session starts; restart the host to load changes.",
     "Other OS accounts, containers, remote/cloud hosts and unsupported agents are not covered. Instruction precedence remains controlled by the host.",
     "Disconnecting stops future capture but does not erase retained data.",
+    "AI budgets: trusted Claude prompt-submit hooks can block new turns on exhausted or unavailable enforced budgets independently of capture pause. Other packaged hosts are monitoring only; internal calls and subscription billing are outside a hard monetary ceiling.",
     `Disclosure: ${DISCLOSURE_VERSION}`,
   );
   return lines.join("\n");
@@ -403,6 +405,7 @@ async function runAllInstaller(input, {
           : null,
         proofStorage: installed.proofStorage,
         instructions: installed.instructions,
+        budgets: installed.budgets,
         syncCommand: { command: process.execPath, args: [bundle.runtimePath, "sync", "--connection", installed.installationId], environment: { HALOFY_AGENT_HOME: root } },
         skillGuard: configured.skillGuard,
         configuredPaths: configured.configuredPaths || [configured.mcpPath, configured.settingsPath],
@@ -516,6 +519,7 @@ export async function runInstaller(argv, {
     publishedPackage: true,
     projectConfigured: true,
     instructions: installed.instructions,
+    budgets: installed.budgets,
     syncCommand: { command: process.execPath, args: [bundle.runtimePath, "sync", "--connection", installed.installationId], environment: { HALOFY_AGENT_HOME: root } },
     skillGuard: configured.skillGuard,
     configuredPaths: configured.configuredPaths || [configured.mcpPath, configured.settingsPath],

package/src/instructions.mjs

@@ -12,6 +12,7 @@ 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 MCP_POLICY_ID = /^mcp-policy-[a-f0-9]{64}$/;
 const MARKER = "<!-- HALOFY-INSTRUCTIONS:";
 const fail = (code) => { throw Object.assign(new Error(code), { instructionCode: code }); };
 const plain = (value) => value && typeof value === "object" && !Array.isArray(value);
@@ -34,16 +35,21 @@ export function validateInstructionBundle(bundle, expectedNamespace) {
       bundle.namespace !== expectedNamespace || !HEX.test(bundle.digest) || !Array.isArray(bundle.documents) ||
       Buffer.byteLength(JSON.stringify(bundle)) > 64 * 1024) fail("invalid_bundle");
   let previous = null;
-  const documents = bundle.documents.map((doc) => {
+  const documents = bundle.documents.map((doc, index) => {
+    // This reserved identifier is a wire discriminator, not an authenticity
+    // proof. Authority still comes from the authorized server response.
+    const generatedPolicy = plain(doc) && typeof doc.id === "string" && MCP_POLICY_ID.test(doc.id);
     if (!plain(doc) || typeof doc.id !== "string" || !/^[A-Za-z0-9_-]{1,160}$/.test(doc.id) || !scope(doc.namespace) ||
         !(doc.namespace === "" || doc.namespace === expectedNamespace || expectedNamespace.startsWith(`${doc.namespace}/`)) ||
-        (previous !== null && !(doc.namespace !== previous && (previous === "" || doc.namespace.startsWith(`${previous}/`)))) ||
+        (doc.id.startsWith("mcp-policy-") && !generatedPolicy) ||
+        (generatedPolicy && (index !== bundle.documents.length - 1 || doc.namespace !== expectedNamespace || doc.title !== "Required MCP access policy")) ||
+        (!generatedPolicy && previous !== null && !(doc.namespace !== previous && (previous === "" || doc.namespace.startsWith(`${previous}/`)))) ||
         !Number.isSafeInteger(doc.version) || doc.version < 1 || typeof doc.title !== "string" || !doc.title.trim() || doc.title.length > 160 || doc.title.includes(MARKER) ||
         /[\u0000-\u001f\u007f]/.test(doc.title) || typeof doc.content !== "string" || !doc.content.trim() ||
         Buffer.from(doc.title, "utf8").toString("utf8") !== doc.title || Buffer.from(doc.content, "utf8").toString("utf8") !== doc.content ||
-        doc.content.includes("\0") || doc.content.includes(MARKER) || Buffer.byteLength(doc.content) > 16 * 1024 ||
+        doc.content.includes("\0") || doc.content.includes(MARKER) || Buffer.byteLength(doc.content) > (generatedPolicy ? 64 : 16) * 1024 ||
         !HEX.test(doc.sha256) || sha(doc.content) !== doc.sha256) fail("invalid_bundle");
-    previous = doc.namespace;
+    if (!generatedPolicy) previous = doc.namespace;
     return { id: doc.id, namespace: doc.namespace, version: doc.version, title: doc.title, content: doc.content, sha256: doc.sha256 };
   });
   if (sha(JSON.stringify(documents)) !== bundle.digest) fail("invalid_bundle");

package/src/transport.mjs

@@ -22,7 +22,7 @@ export class SignedRuntimeTransport {
     this.signal = signal;
   }
 
-  async request(path, { method = "POST", body, headers = {}, raw = false, maxResponseBytes } = {}) {
+  async request(path, { method = "POST", body, headers = {}, raw = false, maxResponseBytes, timeoutMs = this.timeoutMs } = {}) {
     const bodyBytes = body === undefined
       ? Buffer.alloc(0)
       : Buffer.from(typeof body === "string" || Buffer.isBuffer(body) ? body : JSON.stringify(body));
@@ -34,7 +34,7 @@ export class SignedRuntimeTransport {
       bodyBytes,
     });
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
       const response = await this.fetch(`${this.connection.serverUrl}${path}`, {
         method,
@@ -97,6 +97,9 @@ export class SignedRuntimeTransport {
   deliveryReceipt(receipt) {
     return this.request("/v1/agent-runtime/delivery/receipt", { body: receipt, maxResponseBytes: 16 * 1024 });
   }
+  budgetCheck() {
+    return this.request("/v1/agent-runtime/budget/check", { body: {}, maxResponseBytes: 32 * 1024, timeoutMs: Math.min(this.timeoutMs, 3_000) });
+  }
   contextPage(cursor) {
     return this.request("/v1/agent-runtime/context", {
       body: cursor === undefined ? {} : { cursor }, maxResponseBytes: 8 * 1024 * 1024,

package/src/version.mjs

@@ -1,4 +1,4 @@
 export const PACKAGE_NAME = "@halofy/agent-connect";
-export const INSTALLER_VERSION = "0.13.1";
-export const RUNTIME_VERSION = "0.13.1";
-export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-17.1";
+export const INSTALLER_VERSION = "0.14.0";
+export const RUNTIME_VERSION = "0.14.0";
+export const DISCLOSURE_VERSION = "halofy-agent-lifecycle-2026-09-25.1";