@halofy/agent-connect 0.8.0 → 0.10.0

package/src/skills-sync.mjs

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
-import { mkdir, readFile, rename, stat } from "node:fs/promises";
+import { mkdir, readFile, rename, lstat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
-import { ensurePrivateDirectory, readJson, writePrivateFile } from "./storage.mjs";
+import { isActiveInstallation } from "./active.mjs";
+import { ensurePrivateDirectory, readJson, safeDirectory, writePrivateFile } from "./storage.mjs";
 
 /**
  * Badge-delivered skills (CONTRACTS-S16-SKILL-TRACKING D37–D39 on the signed
@@ -62,7 +63,7 @@ function safeKey(skillKey) {
 
 async function pathState(path) {
   try {
-    return await stat(path);
+    return await lstat(path);
   } catch (error) {
     if (error?.code === "ENOENT") return null;
     throw error;
@@ -80,6 +81,9 @@ async function readText(path) {
 
 /** Move a managed copy aside with its bytes intact; never `rm`. */
 async function quarantine(skillsRoot, quarantineRoot, skillKey, now) {
+  if (!safeKey(skillKey)) throw new Error("invalid managed skill key");
+  await safeDirectory(skillsRoot);
+  await safeDirectory(quarantineRoot, true);
   const from = join(skillsRoot, skillKey);
   if (!(await pathState(from))) return null;
   await ensurePrivateDirectory(quarantineRoot);
@@ -99,10 +103,15 @@ async function isManaged(skillsRoot, skillKey, manifestEntry) {
 }
 
 export async function loadSkillsManifest(root, installationId) {
+  if (typeof installationId !== "string" || !/^[A-Za-z0-9_-]{1,160}$/.test(installationId)) throw new Error("invalid installation");
+  await safeDirectory(root, true);
+  const manifestFile = await pathState(skillsManifestPath(root, installationId));
+  if (manifestFile && (!manifestFile.isFile() || manifestFile.isSymbolicLink())) throw new Error("unsafe skill manifest");
   const manifest = await readJson(skillsManifestPath(root, installationId), null);
-  if (!manifest || manifest.version !== 1 || !Array.isArray(manifest.installs)) {
-    return { version: 1, installationId, installs: [], lastCheckinAt: null };
-  }
+  if (!manifestFile) return { version: 1, installationId, installs: [], lastCheckinAt: null };
+  if (!manifest || manifest.version !== 1 || !Array.isArray(manifest.installs)) throw new Error("invalid skill manifest");
+  if (manifest.installationId !== installationId || manifest.installs.some((entry) =>
+    !safeKey(entry?.skillKey) || typeof entry.skillId !== "string" || !/^[a-f0-9]{64}$/.test(entry.sha))) throw new Error("invalid skill manifest");
   return manifest;
 }
 
@@ -126,6 +135,7 @@ export async function syncManagedSkills({
     supported: skillsRoot !== null,
     skillsRoot,
     checkedIn: false,
+    complete: false,
     installed: [],
     updated: [],
     quarantined: [],
@@ -134,30 +144,46 @@ export async function syncManagedSkills({
     errors: [],
   };
   if (!skillsRoot) return summary;
+  await safeDirectory(skillsRoot, true);
 
   const manifestPath = skillsManifestPath(root, connection.installationId);
   const quarantineRoot = join(root, "skills-quarantine", connection.installationId);
   const manifest = await loadSkillsManifest(root, connection.installationId);
-  const byId = new Map(manifest.installs.map((entry) => [entry.skillId, entry]));
   const current = now();
 
+  const active = () => isActiveInstallation(connection, root);
+  if (!(await active())) {
+    summary.errors.push({ stage: "checkin", code: "inactive_installation" });
+    return summary;
+  }
   let response;
   try {
     response = await transport.skillsCheckin(manifest.installs.map(({ skillId, sha }) => ({ skillId, sha })));
+    if (!response || !Array.isArray(response.skills) || !Array.isArray(response.items)
+      || response.skills.some((skill) => !safeKey(skill?.skillKey) || typeof skill.skillId !== "string"
+        || !/^[a-f0-9]{64}$/.test(skill.sha))
+      || new Set(response.skills.map((skill) => skill.skillId)).size !== response.skills.length
+      || new Set(response.skills.map((skill) => skill.skillKey)).size !== response.skills.length) {
+      throw Object.assign(new Error("invalid skill discovery"), { code: "invalid_skill_discovery" });
+    }
+    if (!(await active())) throw Object.assign(new Error("inactive installation"), { code: "inactive_installation" });
     summary.checkedIn = true;
   } catch (error) {
     summary.errors.push({ stage: "checkin", code: error?.code || "runtime_unavailable" });
+    if (error?.code === "inactive_installation") return summary;
     const last = manifest.lastCheckinAt ? Date.parse(manifest.lastCheckinAt) : NaN;
     if (Number.isFinite(last) && current.getTime() - last > STALE_AFTER_MS) {
+      const failedWithdrawals = [];
       for (const entry of manifest.installs) {
         try {
           const moved = await quarantine(skillsRoot, quarantineRoot, entry.skillKey, current);
           if (moved) summary.quarantined.push({ skillKey: entry.skillKey, reason: "stale_checkin", to: moved });
         } catch (fsError) {
+          failedWithdrawals.push(entry);
           summary.errors.push({ stage: "quarantine", skillKey: entry.skillKey, code: fsError?.code || "fs_error" });
         }
       }
-      manifest.installs = [];
+      manifest.installs = failedWithdrawals;
       await writePrivateFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
     }
     return summary;
@@ -172,6 +198,7 @@ export async function syncManagedSkills({
   //    lists that the badge no longer resolves.
   const verdicts = new Map((Array.isArray(response?.items) ? response.items : []).map((item) => [item.skillId, item]));
   const survivors = [];
+  const failedWithdrawals = [];
   for (const entry of manifest.installs) {
     const verdict = verdicts.get(entry.skillId);
     const status = verdict?.status;
@@ -183,6 +210,7 @@ export async function syncManagedSkills({
     } catch (error) {
       summary.errors.push({ stage: "quarantine", skillKey: entry.skillKey, code: error?.code || "fs_error" });
       survivors.push(entry);
+      failedWithdrawals.push(entry);
     }
   }
   manifest.installs = survivors;
@@ -196,11 +224,21 @@ export async function syncManagedSkills({
       entry.skillId = verdict.currentSkillId;
     }
   }
-  const next = [];
+  const next = [...failedWithdrawals];
   for (const skill of wanted.values()) {
     const entry = manifest.installs.find((candidate) => candidate.skillId === skill.skillId);
     const dir = join(skillsRoot, skill.skillKey);
     const file = join(dir, "SKILL.md");
+    if (!(await active())) {
+      summary.errors.push({ stage: "download", code: "inactive_installation" });
+      return summary;
+    }
+    const directoryEntry = await pathState(dir);
+    const fileEntry = await pathState(file);
+    if (directoryEntry?.isSymbolicLink() || fileEntry?.isSymbolicLink()) {
+      summary.conflicts.push({ skillKey: skill.skillKey, reason: "unsafe_path" });
+      continue;
+    }
     const onDisk = await readText(file);
     const intact = entry && typeof onDisk === "string" && digest(onDisk) === entry.fileSha256;
     if (entry && entry.sha === skill.sha && intact) {
@@ -216,7 +254,12 @@ export async function syncManagedSkills({
       const exported = await transport.skillDownload(skill.skillId);
       const content = typeof exported?.content === "string" ? exported.content : null;
       if (!content) throw Object.assign(new Error("skill export was empty"), { code: "empty_export" });
-      await mkdir(dir, { recursive: true });
+      if (!content.startsWith("---\n") || !content.split("\n---\n")[0].split("\n").includes(`content_sha256: ${skill.sha}`)) {
+        throw Object.assign(new Error("skill digest mismatch"), { code: "skill_digest_mismatch" });
+      }
+      if (!(await active())) throw Object.assign(new Error("inactive installation"), { code: "inactive_installation" });
+      await safeDirectory(dir, true);
+      if ((await pathState(file))?.isSymbolicLink()) throw new Error("unsafe skill file");
       await writePrivateFile(file, content);
       const record = {
         skillId: skill.skillId,
@@ -248,6 +291,12 @@ export async function syncManagedSkills({
       summary.errors.push({ stage: "ack", code: error?.code || "runtime_unavailable" });
     }
   }
+  summary.complete = summary.checkedIn && !summary.errors.length && !summary.conflicts.length
+    && manifest.installs.length === wanted.size && await active();
+  if (summary.complete) {
+    try { Object.defineProperty(summary, "tuples", { value: await readManagedSkillTuples({ connection, root, home, env }) }); }
+    catch { summary.complete = false; }
+  }
   return summary;
 }
 
@@ -264,3 +313,45 @@ export function describeSkillSync(summary) {
   if (!summary.checkedIn) parts.unshift("check-in unavailable");
   return `skills (${basename(dirname(summary.skillsRoot))}/${basename(summary.skillsRoot)}): ${parts.join(", ") || "nothing to do"}`;
 }
+
+/** Verify exported definition bytes, not just claimed frontmatter/manifest SHAs. */
+export async function readManagedSkillTuples({ connection, root, home = homedir(), env = process.env }) {
+  const skillsRoot = managedSkillsDirectory(connection.clientKind, { home, env });
+  if (skillsRoot) await safeDirectory(skillsRoot);
+  await safeDirectory(root);
+  const manifestEntry = await pathState(skillsManifestPath(root, connection.installationId));
+  if (!skillsRoot || !manifestEntry?.isFile() || manifestEntry.isSymbolicLink()) throw new Error("missing skill evidence");
+  const manifest = await loadSkillsManifest(root, connection.installationId);
+  if (manifest.installationId !== connection.installationId || !manifest.lastCheckinAt) throw new Error("incomplete skill evidence");
+  for (const entry of manifest.installs) {
+    if (!safeKey(entry.skillKey) || typeof entry.skillId !== "string" || !/^[a-f0-9]{64}$/.test(entry.sha)) throw new Error("invalid skill evidence");
+    const dir = join(skillsRoot, entry.skillKey), file = join(dir, "SKILL.md");
+    if ((await pathState(dir))?.isSymbolicLink() || (await pathState(file))?.isSymbolicLink()) throw new Error("unsafe skill evidence");
+    const content = await readText(file);
+    const separator = content?.indexOf("\n---\n\n");
+    // The export wrapper adds exactly one blank line and one terminal newline.
+    const definition = separator >= 0 && content.endsWith("\n") ? content.slice(separator + 6, -1) : null;
+    if (definition === null || digest(content) !== entry.fileSha256 || digest(definition) !== entry.sha) throw new Error("modified skill evidence");
+  }
+  return manifest.installs.map(({ skillId, skillKey, sha }) => [skillId, skillKey, sha]);
+}
+
+/** Retire a reconnect predecessor's managed discovery before activating its replacement.
+ * Move the owned directory intact, including employee edits, outside discovery;
+ * never delete or follow its contents. An unowned collision remains untouched. */
+export async function retireManagedSkills({ connection, root, home = homedir(), env = process.env, now = () => new Date() }) {
+  const skillsRoot = managedSkillsDirectory(connection.clientKind, { home, env });
+  if (!skillsRoot) return;
+  const manifest = await loadSkillsManifest(root, connection.installationId);
+  if (!manifest.installs.length) return;
+  await safeDirectory(skillsRoot);
+  for (const entry of manifest.installs) {
+    const dir = join(skillsRoot, entry.skillKey);
+    const disk = await pathState(dir);
+    if (!disk) continue;
+    if (disk.isSymbolicLink() || !disk.isDirectory()) throw new Error("unsafe predecessor skill");
+    await quarantine(skillsRoot, join(root, "skills-quarantine", connection.installationId), entry.skillKey, now());
+  }
+  manifest.installs = [];
+  await writePrivateFile(skillsManifestPath(root, connection.installationId), `${JSON.stringify(manifest, null, 2)}\n`);
+}

package/src/storage.mjs

@@ -1,6 +1,6 @@
 import { constants } from "node:fs";
-import { access, chmod, mkdir, open, readFile, rename, stat, unlink } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { access, chmod, mkdir, lstat, open, readFile, rename, stat, unlink } from "node:fs/promises";
+import { dirname, join, parse, resolve } from "node:path";
 import { homedir, platform } from "node:os";
 import { randomBytes } from "node:crypto";
 
@@ -132,3 +132,21 @@ export class ConnectionStore {
     }
   }
 }
+
+/** Refuse symlinks at every ancestor before touching managed runtime paths. */
+export async function safeDirectory(path, create = false) {
+  const absolute = resolve(path);
+  let current = parse(absolute).root;
+  for (const part of absolute.slice(current.length).split(/[\\/]/).filter(Boolean)) {
+    current = join(current, part);
+    let entry;
+    try { entry = await lstat(current); }
+    catch (error) { if (error?.code !== "ENOENT") throw error; }
+    if (!entry && create) {
+      try { await mkdir(current, { mode: 0o700 }); } catch (error) { if (error?.code !== "EEXIST") throw error; }
+      entry = await lstat(current);
+    }
+    if (!entry) throw Object.assign(new Error("directory_missing"), { code: "directory_missing" });
+    if (entry.isSymbolicLink() || !entry.isDirectory()) throw Object.assign(new Error("unsafe_directory"), { code: "unsafe_directory" });
+  }
+}

package/src/transport.mjs

@@ -90,6 +90,12 @@ export class SignedRuntimeTransport {
 
   /** Badge skill check-in beacon: exactly the installed {skillId, sha} pairs (D39). */
   skillsCheckin(items) { return this.request("/v1/agent-runtime/skills/checkin", { body: { items } }); }
+  deliveryCheck({ refresh = false } = {}) {
+    return this.request("/v1/agent-runtime/delivery/check", { body: refresh ? { refresh: true } : {}, maxResponseBytes: 16 * 1024 });
+  }
+  deliveryReceipt(receipt) {
+    return this.request("/v1/agent-runtime/delivery/receipt", { body: receipt, maxResponseBytes: 16 * 1024 });
+  }
   contextPage(cursor) {
     return this.request("/v1/agent-runtime/context", {
       body: cursor === undefined ? {} : { cursor }, maxResponseBytes: 8 * 1024 * 1024,
@@ -99,6 +105,8 @@ export class SignedRuntimeTransport {
   skillDownload(skillId) {
     return this.request(`/v1/agent-runtime/skills/${encodeURIComponent(skillId)}/download`, { method: "GET" });
   }
+  instructions() { return this.request("/v1/agent-runtime/instructions", { method: "GET", maxResponseBytes: 64 * 1024 }); }
+  instructionStatus(body) { return this.request("/v1/agent-runtime/instructions/status", { body, maxResponseBytes: 16 * 1024 }); }
 
   openSession(body) { return this.request("/v1/agent-sessions/open", { body }); }
   appendEvents(sessionId, events) { return this.request(`/v1/agent-sessions/${encodeURIComponent(sessionId)}/events`, { body: { events } }); }

package/src/version.mjs

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