@hasna/mementos 0.17.3 → 0.17.5

package/dist/cli/index.js

@@ -7019,18 +7019,55 @@ var init_memories = __esm(() => {
   ]);
 });
 
+// src/lib/agent-name.ts
+function trimControlBytes(value) {
+  let name = value;
+  for (;; ) {
+    const next = name.trim().replace(CONTROL_BYTE_EDGES, "");
+    if (next === name)
+      return name;
+    name = next;
+  }
+}
+function isValidAgentName(name) {
+  return name.length > 0 && name.length <= AGENT_NAME_MAX_LENGTH && /^[A-Za-z0-9._-]+$/.test(name) && /[A-Za-z0-9_-]/.test(name);
+}
+function isUrlDotSegment(value) {
+  const segment = value.toLowerCase();
+  return segment === "." || segment === ".." || segment === "%2e" || segment === ".%2e" || segment === "%2e." || segment === "%2e%2e";
+}
+function agentPathSegment(name) {
+  if (isUrlDotSegment(name)) {
+    throw new Error(`Refusing to build an agent URL from ${JSON.stringify(name)}: the URL parser collapses a dot segment, ` + `so the request path would not be the one built here.`);
+  }
+  return encodeURIComponent(name);
+}
+function sanitizeAgentName(raw) {
+  if (typeof raw !== "string")
+    return null;
+  const name = trimControlBytes(raw);
+  if (CONTROL_BYTE.test(name))
+    return null;
+  return isValidAgentName(name) ? name : null;
+}
+var AGENT_NAME_MAX_LENGTH = 128, CONTROL_BYTE, CONTROL_BYTE_EDGES;
+var init_agent_name = __esm(() => {
+  CONTROL_BYTE = /[\u0000-\u001f\u007f]/;
+  CONTROL_BYTE_EDGES = /^[\u0000-\u001f\u007f]+|[\u0000-\u001f\u007f]+$/g;
+});
+
 // src/db/agents.ts
 import { homedir as homedir3 } from "os";
 import { join as join6 } from "path";
 import { existsSync as existsSync5, readFileSync as readFileSync2 } from "fs";
 function resolveWritingAgentName() {
-  const envName = process.env["MEMENTOS_AGENT"]?.trim();
+  const envName = sanitizeAgentName(process.env["MEMENTOS_AGENT"]);
   if (envName)
     return envName;
   try {
     const path = join6(homedir3(), ".hasna", "conversations", "agent-id");
     if (existsSync5(path)) {
-      const fileAgent = readFileSync2(path, "utf8").trim();
+      const fileAgent = sanitizeAgentName(readFileSync2(path, "utf8"));
       if (fileAgent)
         return fileAgent;
     }
@@ -7111,7 +7148,7 @@ function registerAgent(name, sessionId, description, role, projectId, db) {
 }
 function getAgent(idOrName, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/agents/${encodeURIComponent(idOrName)}`, undefined, { allow404: true });
+    const { status, data } = apiJson("GET", `/agents/${agentPathSegment(idOrName)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -7175,7 +7212,7 @@ function touchAgent(idOrName, db) {
     const agent2 = getAgent(idOrName);
     if (!agent2)
       return;
-    apiJson("PATCH", `/agents/${encodeURIComponent(agent2.id)}`, {});
+    apiJson("PATCH", `/agents/${agentPathSegment(agent2.id)}`, {});
     return;
   }
   const d = db || getDatabase();
@@ -7186,7 +7223,7 @@ function touchAgent(idOrName, db) {
 }
 function updateAgent(id, updates, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("PATCH", `/agents/${encodeURIComponent(id)}`, updates, { allow404: true });
+    const { status, data } = apiJson("PATCH", `/agents/${agentPathSegment(id)}`, updates, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -7232,6 +7269,7 @@ function updateAgent(id, updates, db) {
 var CONFLICT_WINDOW_MS, UNBOUNDED_AGENT_LIST_LIMIT;
 var init_agents = __esm(() => {
   init_types();
+  init_agent_name();
   init_database();
   init_api_mode();
   CONFLICT_WINDOW_MS = 30 * 60 * 1000;
@@ -13680,7 +13718,7 @@ import {
   ClientTransportConfigurationError as ClientTransportConfigurationError2
 } from "@hasna/contracts/client";
 function sdkProtocolError(operation, detail) {
-  return new MementosError(`mementos ${operation} returned a malformed 2xx response: ${detail}`, 502);
+  return new MementosError(`mementos ${operation} returned a malformed 2xx response: ${detail}`, 502, undefined, "MEMENTOS_RESPONSE_CONTRACT");
 }
 function sessionProtocolError(detail) {
   return sdkProtocolError("session jobs", detail);
@@ -14135,11 +14173,12 @@ class MementosClient {
       body: body !== undefined ? JSON.stringify(body) : undefined
     });
     if (!res.ok) {
-      let errBody = {};
+      let errBody;
       try {
         errBody = await res.json();
       } catch {}
-      throw new MementosError(errBody.error ?? `HTTP ${res.status}`, res.status, errBody.details);
+      const errorObject = errBody && typeof errBody === "object" && !Array.isArray(errBody) ? errBody : undefined;
+      throw new MementosError(typeof errorObject?.["error"] === "string" ? errorObject["error"] : `HTTP ${res.status}`, res.status, errorObject?.["details"]);
     }
     if (res.status === 204)
       return;
@@ -14341,10 +14380,10 @@ class MementosClient {
     return this.post("/api/agents", input);
   }
   getAgent(idOrName) {
-    return this.get(`/api/agents/${idOrName}`);
+    return this.get(`/api/agents/${agentPathSegment(idOrName)}`);
   }
   updateAgent(idOrName, updates) {
-    return this.patch(`/api/agents/${idOrName}`, updates);
+    return this.patch(`/api/agents/${agentPathSegment(idOrName)}`, updates);
   }
   listAgentsByProject(projectId) {
     return this.get(`/api/agents`, { project_id: projectId });
@@ -14887,14 +14926,17 @@ var MEMENTOS_MACHINE_REGISTRATION_CONTRACT = "mementos.machine-registration.v1",
 var init_sdk = __esm(() => {
   init_audit_contract();
   init_local_opt_in();
+  init_agent_name();
   init_decisions();
   MementosError = class MementosError extends Error {
     status;
     details;
-    constructor(message, status, details) {
+    code;
+    constructor(message, status, details, code) {
       super(message);
       this.status = status;
       this.details = details;
+      this.code = code;
       this.name = "MementosError";
     }
   };
@@ -14919,9 +14961,35 @@ __export(exports_claude_stop_hook, {
 });
 import { constants, openSync, closeSync, fstatSync, readSync } from "fs";
 import { isAbsolute } from "path";
+function failureCategory(error, phase) {
+  if (error instanceof HookFailure)
+    return { phase, reason: error.reason };
+  if (error instanceof MementosConfigError)
+    return { phase: "configuration", reason: "configuration_unavailable" };
+  if (error instanceof MementosError) {
+    return { phase: "response", reason: error.code === "MEMENTOS_RESPONSE_CONTRACT" ? "response_contract" : "http_error" };
+  }
+  if (error instanceof SyntaxError) {
+    return { phase: phase === "request" ? "response" : phase, reason: "invalid_json" };
+  }
+  if (phase === "input")
+    return { phase, reason: "input_unreadable" };
+  if (phase === "transcript") {
+    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+    const reason = code === "ENOENT" ? "file_not_found" : code === "EACCES" || code === "EPERM" ? "file_access_denied" : code === "ELOOP" ? "file_symlink_refused" : "file_read_failed";
+    return { phase, reason };
+  }
+  if (phase === "configuration")
+    return { phase, reason: "configuration_unavailable" };
+  if (error instanceof Error && error.name === "TimeoutError")
+    return { phase, reason: "timeout" };
+  if (error instanceof Error && error.name === "AbortError")
+    return { phase, reason: "aborted" };
+  return { phase, reason: phase === "response" ? "response_unreadable" : error instanceof TypeError ? "network_error" : "request_failed" };
+}
 function object2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
-    throw new Error("invalid input");
+    throw new HookFailure("invalid_shape", "invalid input");
   return value;
 }
 function textContent(value) {
@@ -14938,13 +15006,15 @@ function textContent(value) {
 function claudeTranscript(context) {
   const path = context["transcript_path"];
   if (typeof path !== "string" || !isAbsolute(path))
-    throw new Error("transcript path required");
+    throw new HookFailure("transcript_path_required", "transcript path required");
   const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
   let raw;
   try {
     const stat = fstatSync(fd);
-    if (!stat.isFile() || stat.size > MAX_TRANSCRIPT_BYTES)
-      throw new Error("invalid transcript file");
+    if (!stat.isFile())
+      throw new HookFailure("transcript_not_regular", "invalid transcript file");
+    if (stat.size > MAX_TRANSCRIPT_BYTES)
+      throw new HookFailure("transcript_too_large", "invalid transcript file");
     const buffer = Buffer.alloc(MAX_TRANSCRIPT_BYTES + 1);
     let read = 0;
     while (read < buffer.length) {
@@ -14954,7 +15024,7 @@ function claudeTranscript(context) {
       read += count;
     }
     if (read > MAX_TRANSCRIPT_BYTES)
-      throw new Error("transcript grew beyond bound");
+      throw new HookFailure("transcript_too_large", "transcript grew beyond bound");
     raw = buffer.subarray(0, read).toString("utf8");
   } finally {
     closeSync(fd);
@@ -14969,7 +15039,7 @@ function claudeTranscript(context) {
     if (row["type"] !== "user" && row["type"] !== "assistant")
       continue;
     if (row["sessionId"] !== undefined && row["sessionId"] !== context["session_id"])
-      throw new Error("transcript session mismatch");
+      throw new HookFailure("transcript_session_mismatch", "transcript session mismatch");
     const message = object2(row["message"]);
     const text = textContent(message["content"]);
     if (!text.trim())
@@ -14994,54 +15064,72 @@ async function runClaudeStopHook(options = {}) {
   const report = options.stderr ?? ((text) => {
     process.stderr.write(text);
   });
+  let phase = "input";
   try {
     const chunks = [];
     let bytes = 0;
     for await (const chunk of options.stdin ?? Bun.stdin.stream()) {
       bytes += chunk.byteLength;
       if (bytes > MAX_CONTEXT_BYTES)
-        throw new Error("context too large");
+        throw new HookFailure("context_too_large", "context too large");
       chunks.push(chunk);
     }
     const context = object2(JSON.parse(Buffer.concat(chunks).toString("utf8")));
     if (context["hook_event_name"] !== "Stop")
-      throw new Error("not a Stop event");
+      throw new HookFailure("invalid_event", "not a Stop event");
     if (context["stop_hook_active"] === true)
       return 0;
     const session = context["session_id"];
     if (typeof session !== "string" || !session.trim() || session.length > 256)
-      throw new Error("session required");
+      throw new HookFailure("invalid_session", "session required");
+    phase = "transcript";
     const transcript = claudeTranscript(context);
     if (!transcript.trim())
       return 0;
+    phase = "configuration";
     const client = options.client ?? new MementosClient({
-      fetch: (input, init) => fetch(input, { ...init, redirect: "error", signal: AbortSignal.timeout(5000) })
+      fetch: async (input, init) => {
+        const response = await fetch(input, { ...init, redirect: "error", signal: AbortSignal.timeout(5000) });
+        phase = "response";
+        return response;
+      }
     });
     const authority = new URL(client.apiUrl);
     if (authority.protocol !== "https:" || !authority.pathname.endsWith("/v1"))
-      throw new Error("hosted v1 authority required");
+      throw new HookFailure("hosted_authority_required", "hosted v1 authority required");
+    const agentId = sanitizeAgentName(process.env["MEMENTOS_AGENT"]);
+    phase = "request";
     await client.ingestSession({
       transcript,
       session_id: session,
       source: "claude-code",
-      ...process.env["MEMENTOS_AGENT"] ? { agent_id: process.env["MEMENTOS_AGENT"] } : {}
+      ...agentId ? { agent_id: agentId } : {}
     });
     report(`[mementos] Session queued for hosted memory extraction.
 `);
     return 0;
   } catch (error) {
-    const status = error instanceof MementosError && Number.isInteger(error.status) ? ` (HTTP ${error.status})` : "";
-    report(`[mementos] Hosted session ingest failed${status}; no local fallback or automatic retry.
+    const failure = failureCategory(error, phase);
+    const status = error instanceof MementosError && error.code !== "MEMENTOS_RESPONSE_CONTRACT" && Number.isInteger(error.status) && error.status >= 100 && error.status <= 599 ? ` (HTTP ${error.status})` : "";
+    report(`[mementos] Hosted session ingest failed${status} [phase=${failure.phase}; reason=${failure.reason}]; no local fallback or automatic retry.
 `);
     return 1;
   }
 }
-var MAX_CONTEXT_BYTES, MAX_TRANSCRIPT_BYTES;
+var MAX_CONTEXT_BYTES, MAX_TRANSCRIPT_BYTES, HookFailure;
 var init_claude_stop_hook = __esm(() => {
   init_sdk();
+  init_agent_name();
   init_redact();
   MAX_CONTEXT_BYTES = 64 * 1024;
   MAX_TRANSCRIPT_BYTES = 8 * 1024 * 1024;
+  HookFailure = class HookFailure extends Error {
+    reason;
+    constructor(reason, message) {
+      super(message);
+      this.reason = reason;
+    }
+  };
 });
 
 // src/db/session-jobs.ts
@@ -16109,7 +16197,8 @@ function planClaudeHook(home, command = claudeHookCommand()) {
   const changed = !before || JSON.stringify(settings) !== JSON.stringify(JSON.parse(next));
   return { settingsPath, resolvedSettingsPath, legacyPath, directory, directory_sha256: directory.sha256, before, next, changed, settings_sha256: before ? digest2(before) : "absent", legacy_hook_sha256: legacyHash, command };
 }
-function installClaudeHook(home, expected, command = claudeHookCommand()) {
+async function installClaudeHook(home, expected, command = claudeHookCommand(), options = {}) {
+  const { planClaudeStopHookUpdate, applyAgentIntegration } = await import("@hasna/skills");
   const plan = planClaudeHook(home, command);
   if (plan.directory.alias && !expected.directorySha256)
     throw new Error("MEMENTOS_HOOK_DIRECTORY_PREIMAGE_REQUIRED");
@@ -16117,8 +16206,18 @@ function installClaudeHook(home, expected, command = claudeHookCommand()) {
     throw new Error("MEMENTOS_HOOK_DIRECTORY_PREIMAGE_CHANGED");
   if (plan.settings_sha256 !== expected.settingsSha256 || (plan.legacy_hook_sha256 ?? undefined) !== expected.legacyHookSha256)
     throw new Error("MEMENTOS_HOOK_PREIMAGE_CHANGED");
-  if (!plan.changed)
+  const integrationOptions = {
+    home,
+    dataDir: options.skillsDataDir,
+    expectedSettingsSha256: plan.settings_sha256,
+    replacement: plan.changed ? plan.next : plan.before.toString("utf8")
+  };
+  const integrationPlan = planClaudeStopHookUpdate(integrationOptions);
+  if (!plan.changed) {
+    if (integrationPlan)
+      applyAgentIntegration(integrationPlan);
     return { changed: false, settings_sha256: plan.settings_sha256 };
+  }
   const directory = plan.directory.path;
   mkdirSync5(directory, { recursive: true, mode: 448 });
   const claimedDirectory = claudeDirectory(home);
@@ -16136,13 +16235,19 @@ function installClaudeHook(home, expected, command = claudeHookCommand()) {
       writeFileSync4(backup, plan.before, { flag: "wx", mode: 384 });
     if (backup && digest2(readRegular(backup)) !== plan.settings_sha256)
       throw new Error("MEMENTOS_HOOK_BACKUP_CONFLICT");
-    writeFileSync4(temporary, plan.next, { flag: "wx", mode: 384 });
     const current = planClaudeHook(home, command);
     if (current.directory_sha256 !== claimedDirectory.sha256)
       throw new Error("MEMENTOS_HOOK_DIRECTORY_PREIMAGE_CHANGED");
     if (current.settings_sha256 !== plan.settings_sha256 || current.legacy_hook_sha256 !== plan.legacy_hook_sha256)
       throw new Error("MEMENTOS_HOOK_PREIMAGE_CHANGED");
-    renameSync(temporary, plan.resolvedSettingsPath);
+    if (integrationPlan) {
+      applyAgentIntegration(integrationPlan);
+    } else {
+      if (planClaudeStopHookUpdate(integrationOptions))
+        throw new Error("MEMENTOS_HOOK_SKILLS_POLICY_CHANGED");
+      writeFileSync4(temporary, plan.next, { flag: "wx", mode: 384 });
+      renameSync(temporary, plan.resolvedSettingsPath);
+    }
     if (claudeDirectory(home).sha256 !== claimedDirectory.sha256 || digest2(readRegular(plan.resolvedSettingsPath)) !== digest2(plan.next))
       throw new Error("MEMENTOS_HOOK_READBACK_FAILED");
   } finally {
@@ -74685,7 +74790,7 @@ session_end = "bun ${script}"`);
       if (opts.apply) {
         if (!opts.expectSettingsSha256)
           throw new Error("Preview first; --apply requires --expect-settings-sha256");
-        outputJson(installClaudeHook2(homedir6(), { settingsSha256: opts.expectSettingsSha256, legacyHookSha256: opts.expectHookSha256, directorySha256: opts.expectDirectorySha256 }));
+        outputJson(await installClaudeHook2(homedir6(), { settingsSha256: opts.expectSettingsSha256, legacyHookSha256: opts.expectHookSha256, directorySha256: opts.expectDirectorySha256 }));
       } else {
         const plan = planClaudeHook2(homedir6());
         outputJson({ changed: plan.changed, settings_path: plan.settingsPath, resolved_settings_path: plan.resolvedSettingsPath, directory_sha256: plan.directory_sha256, directory_alias: plan.directory.alias, command: plan.command, settings_sha256: plan.settings_sha256, legacy_hook_sha256: plan.legacy_hook_sha256 });
@@ -76144,7 +76249,7 @@ function registerInitCommand(program2) {
     try {
       const { planClaudeHook: planClaudeHook2, installClaudeHook: installClaudeHook2 } = await Promise.resolve().then(() => (init_claude_hook_install(), exports_claude_hook_install));
       const plan = planClaudeHook2(home);
-      const result = installClaudeHook2(home, { settingsSha256: plan.settings_sha256, legacyHookSha256: plan.legacy_hook_sha256 ?? undefined, directorySha256: plan.directory_sha256 });
+      const result = await installClaudeHook2(home, { settingsSha256: plan.settings_sha256, legacyHookSha256: plan.legacy_hook_sha256 ?? undefined, directorySha256: plan.directory_sha256 });
       console.log(chalk41.green(result.changed ? "  \u2713 Hosted Stop hook installed" : "  \xB7 Hosted Stop hook already installed"));
     } catch {
       console.error(chalk41.red("  \u2717 Stop hook installation refused; run mementos session setup-hook --claude to inspect the preconditions"));

package/dist/db/agents.d.ts

@@ -16,6 +16,13 @@ export interface AgentListFilter {
  * Returns null when neither source yields a non-empty name. An unreadable or
  * missing identity file is treated as absent — a write must never fail merely
  * because the identity file was mid-write.
+ *
+ * BOTH sources are sanitized: control-byte padding is stripped (station07's
+ * file held `autumn-bea\0\0`, and the padded value reached
+ * `/agents/autumn-bea%00%00` as a hosted 400) and the remainder must be a
+ * usable agent name. A value that is not usable — an error string written by a
+ * failed claim, say — is treated as absent rather than used, so the caller's
+ * own refusal path owns the outcome.
  */
 export declare function resolveWritingAgentName(): string | null;
 export declare function registerAgent(name: string, sessionId?: string, description?: string, role?: string, projectId?: string, db?: Database): Agent;

package/dist/db/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/db/agents.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAQ/C,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAcvD;AAgBD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,CA0EP;AAED,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,EAChB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,GAAG,IAAI,CA6Bd;AA+CD,wBAAgB,UAAU,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAAC;AACnD,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAAC;AAsB5E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAahE;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAAC;AAC/E,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,EAAE,CAAC;AA0BX,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACtI,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,GAAG,IAAI,CAsDd"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/db/agents.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAS/C,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAcvD;AAgBD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,CA0EP;AAED,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,MAAM,EAChB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,GAAG,IAAI,CA6Bd;AA+CD,wBAAgB,UAAU,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAAC;AACnD,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAAC;AAsB5E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAahE;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,KAAK,EAAE,CAAC;AAC/E,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,EAAE,CAAC;AA0BX,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACtI,EAAE,CAAC,EAAE,QAAQ,GACZ,KAAK,GAAG,IAAI,CAsDd"}

package/dist/index.js

@@ -55476,6 +55476,18 @@ function getMemoryProjectLinkReceipt(memoryId, receiptId, identity = linkAuthori
 }
 // src/memory-project-link/index.ts
 init_schema();
+// src/lib/agent-name.ts
+function isUrlDotSegment(value) {
+  const segment = value.toLowerCase();
+  return segment === "." || segment === ".." || segment === "%2e" || segment === ".%2e" || segment === "%2e." || segment === "%2e%2e";
+}
+function agentPathSegment(name) {
+  if (isUrlDotSegment(name)) {
+    throw new Error(`Refusing to build an agent URL from ${JSON.stringify(name)}: the URL parser collapses a dot segment, ` + `so the request path would not be the one built here.`);
+  }
+  return encodeURIComponent(name);
+}
+
 // src/db/agents.ts
 init_database();
 init_api_mode();
@@ -55555,7 +55567,7 @@ function registerAgent(name, sessionId, description, role, projectId, db) {
 }
 function getAgent(idOrName, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/agents/${encodeURIComponent(idOrName)}`, undefined, { allow404: true });
+    const { status, data } = apiJson("GET", `/agents/${agentPathSegment(idOrName)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -55619,7 +55631,7 @@ function touchAgent(idOrName, db) {
     const agent2 = getAgent(idOrName);
     if (!agent2)
       return;
-    apiJson("PATCH", `/agents/${encodeURIComponent(agent2.id)}`, {});
+    apiJson("PATCH", `/agents/${agentPathSegment(agent2.id)}`, {});
     return;
   }
   const d = db || getDatabase();
@@ -55645,7 +55657,7 @@ function listAgentsByProject(projectId, filterOrDb = {}, db) {
 }
 function updateAgent(id, updates, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("PATCH", `/agents/${encodeURIComponent(id)}`, updates, { allow404: true });
+    const { status, data } = apiJson("PATCH", `/agents/${agentPathSegment(id)}`, updates, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;

package/dist/lib/agent-name.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Hygiene for agent identity VALUES, shared by every reader in this package.
+ *
+ * WHY THIS EXISTS. On 2026-09-18 the fleet's machine identity surface
+ * (`~/.hasna/conversations/agent-id`, written by `conversations agents
+ * register`) was found holding two corrupt values: station07's was
+ * `autumn-bea\0\0` (NUL padded) and station01's was an error string with a
+ * literal newline, written by a failed claim. `resolveWritingAgentName()` read
+ * both at face value, and the padded name was interpolated into
+ * `/agents/autumn-bea%00%00` — a 400 from the hosted API, on a path that only
+ * ever receives a name.
+ *
+ * The rules are deliberately the same three the conversations CLI applies:
+ * control-byte PADDING is stripped, the remainder is trimmed, and what is left
+ * must be ONE token of `[A-Za-z0-9._-]` (at most 128 characters). A value that
+ * fails is refused, never "repaired" into something nobody wrote: an error
+ * message that landed in a name field is not an identity.
+ *
+ * This module has NO imports on purpose — it is reached from the db layer, the
+ * CLI, the MCP tools and the SDK, and must not drag any of them into a bundle.
+ */
+/**
+ * Longest agent name this build will accept. Fleet names are short
+ * (`autumn-bear`, `chief-engineering-officer`); anything longer is a message
+ * that landed in a name field, not a name.
+ */
+export declare const AGENT_NAME_MAX_LENGTH = 128;
+/** Remove every control byte from a raw value. Pure. */
+export declare function stripControlBytes(value: string): string;
+/**
+ * Strip control-byte PADDING and surrounding whitespace from one raw value.
+ *
+ * This is the shape the fleet actually saw: station07's file held
+ * `autumn-bea\0\0`, and the padded value reached the hosted API as
+ * `/agents/autumn-bea%00%00`. The padding is never part of a name, so the
+ * readable bytes under it are kept.
+ *
+ * Only the EDGES are stripped. A control byte that survives in the middle is
+ * corruption that cannot be repaired by deleting it — joining `autumn\0bear`
+ * into `autumnbear` would mint a name nobody wrote — so the sanitizer below
+ * refuses such a value instead. Pure.
+ */
+export declare function trimControlBytes(value: string): string;
+/**
+ * Whether a value can be used as an agent name at all.
+ *
+ * A name is interpolated into URL paths and into attribution columns, so it
+ * must be one token — no spaces, no colons, no slashes — and contain at least
+ * one character that is not a dot. The last rule is what refuses `.` and `..`:
+ * a pure dot segment is collapsed by the URL parser, so `/api/agents/..`
+ * resolves to `/v1/` and the request silently changes shape (measured in review
+ * of hasna/apps#2619, todos A3-00715). `Error: already-claimed` fails the
+ * charset and is refused instead of being registered as an agent.
+ */
+export declare function isValidAgentName(name: string): boolean;
+/**
+ * The segments a URL parser collapses while resolving a path: `.` and `..`,
+ * plus their percent-encoded spellings (the WHATWG URL spec's "single-dot" and
+ * "double-dot path segment").
+ *
+ * `encodeURIComponent` does NOT touch a dot, so encoding alone cannot
+ * neutralize these: `/api/agents/..` is resolved by the fetch URL parser to
+ * `/v1/` and the request silently changes shape — measured in review of
+ * hasna/apps#2619 (todos A3-00715), where the SDK's `getAgent("..")` issued
+ * `GET /v1/`. This predicate is the rule for the URL BOUNDARY below, where a
+ * value can be an explicit argument rather than a validated name;
+ * {@link isValidAgentName} applies the name-side equivalent (at least one
+ * non-dot character). Pure.
+ */
+export declare function isUrlDotSegment(value: string): boolean;
+/**
+ * Encode one agent name for an `/agents/<name>` path segment, refusing a value
+ * the URL parser would collapse to a different path.
+ *
+ * This is the boundary rule for callers that take a name straight from argv, an
+ * MCP argument, a store row or an SDK call — places where
+ * {@link isValidAgentName} is not on the path. Everything else is
+ * percent-encoded; a dot segment is refused rather than encoded, because
+ * encoding cannot express it (see {@link isUrlDotSegment}).
+ *
+ * @throws {Error} when `name` is a URL dot segment.
+ */
+export declare function agentPathSegment(name: string): string;
+/**
+ * Read one raw value into a usable agent name, or `null` when nothing usable
+ * remains. Control-byte padding is stripped and the result is trimmed before
+ * validation, so `autumn-bea\0\0\n` reads back as `autumn-bea`; a value with
+ * interior corruption, or one that is not a single token, is refused.
+ *
+ * `null` is the only failure value: callers decide whether an unusable name is
+ * absent (the file fallback in `resolveWritingAgentName`) or a refusal. Pure.
+ */
+export declare function sanitizeAgentName(raw: string | null | undefined): string | null;
+//# sourceMappingURL=agent-name.d.ts.map

package/dist/lib/agent-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-name.d.ts","sourceRoot":"","sources":["../../src/lib/agent-name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAWzC,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOtD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAUtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAO/E"}

package/dist/lib/claude-hook-install.d.ts

@@ -21,7 +21,9 @@ export declare function installClaudeHook(home: string, expected: {
     settingsSha256: string;
     legacyHookSha256?: string;
     directorySha256?: string;
-}, command?: string): {
+}, command?: string, options?: {
+    skillsDataDir?: string;
+}): Promise<{
     changed: boolean;
     settings_sha256: string;
     backup?: undefined;
@@ -29,5 +31,5 @@ export declare function installClaudeHook(home: string, expected: {
     changed: boolean;
     settings_sha256: string;
     backup: string | null;
-};
+}>;
 //# sourceMappingURL=claude-hook-install.d.ts.map

package/dist/lib/claude-hook-install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-hook-install.d.ts","sourceRoot":"","sources":["../../src/lib/claude-hook-install.ts"],"names":[],"mappings":"AAYA,wBAAgB,iBAAiB,IAAI,MAAM,CAI1C;AAuBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAsB;;;;;;;;;;;;;;;;;EAmCzE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,SAAsB;;;;;;;;EA+BvK"}
+{"version":3,"file":"claude-hook-install.d.ts","sourceRoot":"","sources":["../../src/lib/claude-hook-install.ts"],"names":[],"mappings":"AAYA,wBAAgB,iBAAiB,IAAI,MAAM,CAI1C;AAuBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,SAAsB;;;;;;;;;;;;;;;;;EAmCzE;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,SAAsB,EAAE,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO;;;;;;;;GAiDvN"}

package/dist/lib/claude-stop-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-stop-hook.d.ts","sourceRoot":"","sources":["../../src/lib/claude-stop-hook.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAiB,MAAM,iBAAiB,CAAC;AAoBhE,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAuCzE;AAED,wBAAsB,iBAAiB,CAAC,OAAO,GAAE;IAC/C,KAAK,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,cAAc,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsCvB"}
+{"version":3,"file":"claude-stop-hook.d.ts","sourceRoot":"","sources":["../../src/lib/claude-stop-hook.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAsC,MAAM,iBAAiB,CAAC;AA0DrF,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAwCzE;AAED,wBAAsB,iBAAiB,CAAC,OAAO,GAAE;IAC/C,KAAK,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,cAAc,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmDvB"}

package/dist/lib/open-sessions-connector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"open-sessions-connector.d.ts","sourceRoot":"","sources":["../../src/lib/open-sessions-connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,2BAA2B;IAC1C,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAA8B;gBAEhC,MAAM,EAAE,2BAA2B;IAI/C;;OAEG;IACG,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACrD,OAAO,CAAC,YAAY,CAAC;IAwCxB;;OAEG;IACG,kBAAkB,CAAC,OAAO,GAAE;QAChC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAelB,sBAAsB;YAiBtB,oBAAoB;CAqBnC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,qBAAqB,CAWxD"}
+{"version":3,"file":"open-sessions-connector.d.ts","sourceRoot":"","sources":["../../src/lib/open-sessions-connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,2BAA2B;IAC1C,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAA8B;gBAEhC,MAAM,EAAE,2BAA2B;IAI/C;;OAEG;IACG,aAAa,CACjB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACrD,OAAO,CAAC,YAAY,CAAC;IAwCxB;;OAEG;IACG,kBAAkB,CAAC,OAAO,GAAE;QAChC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAelB,sBAAsB;YAiBtB,oBAAoB;CAqBnC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,qBAAqB,CAaxD"}

package/dist/mcp/index.js

@@ -61981,6 +61981,20 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/db/agents.ts
 init_types();
+
+// src/lib/agent-name.ts
+function isUrlDotSegment(value) {
+  const segment = value.toLowerCase();
+  return segment === "." || segment === ".." || segment === "%2e" || segment === ".%2e" || segment === "%2e." || segment === "%2e%2e";
+}
+function agentPathSegment(name) {
+  if (isUrlDotSegment(name)) {
+    throw new Error(`Refusing to build an agent URL from ${JSON.stringify(name)}: the URL parser collapses a dot segment, ` + `so the request path would not be the one built here.`);
+  }
+  return encodeURIComponent(name);
+}
+
+// src/db/agents.ts
 init_database();
 init_api_mode();
 var CONFLICT_WINDOW_MS = 30 * 60 * 1000;
@@ -62059,7 +62073,7 @@ function registerAgent(name, sessionId, description, role, projectId, db) {
 }
 function getAgent(idOrName, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("GET", `/agents/${encodeURIComponent(idOrName)}`, undefined, { allow404: true });
+    const { status, data } = apiJson("GET", `/agents/${agentPathSegment(idOrName)}`, undefined, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;
@@ -62123,7 +62137,7 @@ function touchAgent(idOrName, db) {
     const agent2 = getAgent(idOrName);
     if (!agent2)
       return;
-    apiJson("PATCH", `/agents/${encodeURIComponent(agent2.id)}`, {});
+    apiJson("PATCH", `/agents/${agentPathSegment(agent2.id)}`, {});
     return;
   }
   const d = db || getDatabase();
@@ -62149,7 +62163,7 @@ function listAgentsByProject(projectId, filterOrDb = {}, db) {
 }
 function updateAgent(id, updates, db) {
   if (!db && isApiMode()) {
-    const { status, data } = apiJson("PATCH", `/agents/${encodeURIComponent(id)}`, updates, { allow404: true });
+    const { status, data } = apiJson("PATCH", `/agents/${agentPathSegment(id)}`, updates, { allow404: true });
     if (status === 404 || !data)
       return null;
     return data;

package/dist/sdk/index.d.ts

@@ -581,7 +581,8 @@ export interface MementosClientConfig {
 export declare class MementosError extends Error {
     readonly status: number;
     readonly details?: unknown | undefined;
-    constructor(message: string, status: number, details?: unknown | undefined);
+    readonly code?: "MEMENTOS_RESPONSE_CONTRACT" | undefined;
+    constructor(message: string, status: number, details?: unknown | undefined, code?: "MEMENTOS_RESPONSE_CONTRACT" | undefined);
 }
 /**
  * Thrown when the SDK is asked to reach the memory store and NOTHING resolves: