@geminixiang/mikan 1.0.0-beta.76 → 1.0.0-beta.77

package/dist/office/index.js

@@ -1,9 +1,3 @@
-/**
- * The Conversation office module: canonical identity, the Workspace/Office
- * layout values, the durable registry journal, and the boot-time legacy
- * migration. Everything outside `src/office/` imports from this module;
- * exported types live in `types.ts` per module convention.
- */
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
@@ -12,20 +6,17 @@ import { parseGithubConversationId } from "../adapters/github/ids.js";
 import { legacyConversationCredentialKey } from "../sandbox/identity.js";
 import { migrateConversationVaultKeys } from "../vault/index.js";
 import { atomicWritePrivateFile, isRecord, readTextFileIfExists } from "../file-guards.js";
-// ── Office identity (address & keys) ──────────────────────────────────────────
 const OFFICE_KEY_VERSION = "v1";
 const OFFICE_KEY_DOMAIN = "office-address-v1";
 const OFFICE_KEY_DIGEST_LENGTH = 16;
 const READABLE_ID_LENGTH = 32;
 const PLATFORM_NAMES = new Set(["slack", "discord", "telegram", "github"]);
 const OFFICE_KEY_PATTERN = /^v1-(slack|discord|telegram|github)-[a-z0-9]+(?:-[a-z0-9]+)*-[a-f0-9]{16}$/;
-/** Construct the canonical identity used by future office consumers. */
 export function createOfficeAddress(platform, conversationId) {
     assertPlatformName(platform);
     assertConversationId(conversationId);
     return Object.freeze({ platform, conversationId });
 }
-/** Validate an untrusted runtime value as a canonical office address. */
 export function validateOfficeAddress(value) {
     if (!isRecord(value))
         throw new Error("Office address must be an object");
@@ -37,22 +28,18 @@ export function validateOfficeAddress(value) {
     }
     return createOfficeAddress(assertPlatformName(value.platform), value.conversationId);
 }
-/** Return true only for a supported platform name. */
 function isPlatformName(value) {
     return typeof value === "string" && PLATFORM_NAMES.has(value);
 }
-/** Validate a platform name and return it for typed callers. */
 export function assertPlatformName(value) {
     if (!isPlatformName(value))
         throw new Error(`Unsupported platform: ${JSON.stringify(value)}`);
     return value;
 }
-/** Path separators and the C0/C1 control ranges are never allowed in an id. */
 function isUnsafeConversationIdChar(character) {
     const code = character.codePointAt(0) ?? 0;
     return character === "/" || character === "\\" || code <= 0x1f || (code >= 0x7f && code <= 0x9f);
 }
-/** Validate a raw platform conversation identifier before it enters storage. */
 export function assertConversationId(value) {
     if (value.length === 0 || value === "." || value === "..") {
         throw new Error("Conversation id must be non-empty and not a path marker");
@@ -62,7 +49,6 @@ export function assertConversationId(value) {
     }
     return value;
 }
-/** Derive a readable diagnostic key whose digest remains the identity authority. */
 export function officeKey(address) {
     const normalized = validateOfficeAddress(address);
     const readable = readableConversationId(normalized.conversationId);
@@ -72,31 +58,18 @@ export function officeKey(address) {
         .slice(0, OFFICE_KEY_DIGEST_LENGTH);
     return `${OFFICE_KEY_VERSION}-${normalized.platform}-${readable}-${digest}`;
 }
-/**
- * Resolve the persistent workspace directory for an office.
- * Module-internal: registry/migration record target paths with it. Callers
- * outside `src/office/` use the `Office` value's `dir` field instead.
- */
 export function officeDir(workspaceRoot, address) {
     return join(workspaceRoot, officeKey(address));
 }
-/**
- * Resolve the host-only state directory for an office.
- *
- * Settings and migration callers that only hold a `stateDir` string use this
- * when no materialized `Office` value is available.
- */
 export function officeStateDir(stateDir, address) {
     return join(stateDir, "conversations", officeKey(address));
 }
-/** Compare canonical office identities without relying on their readable key. */
 export function sameOffice(left, right) {
     const leftAddress = validateOfficeAddress(left);
     const rightAddress = validateOfficeAddress(right);
     return (leftAddress.platform === rightAddress.platform &&
         leftAddress.conversationId === rightAddress.conversationId);
 }
-/** Validate a persisted or externally supplied office key. */
 export function assertOfficeKey(value) {
     if (!OFFICE_KEY_PATTERN.test(value)) {
         throw new Error(`Invalid office key: ${JSON.stringify(value)}`);
@@ -115,36 +88,12 @@ function readableConversationId(conversationId) {
         .replace(/-+$/g, "");
     return readable || "conversation";
 }
-// ── Workspace/Office layout ───────────────────────────────────────────────────
-/**
- * Workspace-root entries that are shared infrastructure, never office dirs.
- * The single definition behind boot-time directory setup, the workspace
- * projection, and the migration's legacy-dir scan. `events` stays reserved
- * for the legacy scheduling bus that `mikan office migrate-events` drains.
- */
 export const RESERVED_WORKSPACE_NAMES = Object.freeze(new Set(["skills", "events", "agents", "MEMORY.md"]));
-/**
- * Construct the Workspace value for a deployment. One construction site per
- * process (main.ts for the daemon; CLI subcommands and tests build their
- * own). The value owns the registry instance and the recorded-office cache
- * that office materialization uses on hot paths, so there is no process-wide
- * registry state.
- */
-/**
- * An office's session files live in `<office dir>/sessions` — the one home of
- * that rule. String-based for surfaces that hold a conversation dir rather
- * than an `Office` value (mirrors `officeStateDir`); `Office.sessionsDir` is
- * derived from it. Pointer/thread-file semantics live in `sessions/store`.
- */
 export function officeSessionsDir(dir) {
     return join(dir, "sessions");
 }
 export function createWorkspace(options) {
-    // Paths are joined as given (no resolve) so values match what callers
-    // passing the same root/stateDir strings computed before this module.
     const { root, stateDir } = options;
-    // Lazy: CLI surfaces construct a Workspace for path math without paying
-    // for (or being allowed to create) the registry journal.
     let registry;
     const recorded = new Set();
     const offices = new Map();
@@ -174,9 +123,6 @@ export function createWorkspace(options) {
                 stateDir: join(stateDir, "conversations", key),
                 workspace,
                 ensure() {
-                    // Record-first ordering: a crash can leave a record without a
-                    // directory (harmless; recreated on the next message) but never an
-                    // anonymous office directory the registry cannot enumerate.
                     if (!recorded.has(key)) {
                         registry ??= new OfficeRegistry(stateDir);
                         registry.recordOffice(normalized);
@@ -192,7 +138,6 @@ export function createWorkspace(options) {
     });
     return workspace;
 }
-/** mkdir-if-missing with the same fail-closed type guard as projection roots. */
 function ensureRegularOfficeDirectory(dir) {
     let stats;
     try {
@@ -208,7 +153,6 @@ function ensureRegularOfficeDirectory(dir) {
         throw new Error(`Office directory must be a regular non-symlink directory: ${dir}`);
     }
 }
-// ── Office registry journal ───────────────────────────────────────────────────
 const REGISTRY_VERSION = 1;
 const REGISTRY_FILENAME = "office-registry.json";
 const MIGRATION_STATUSES = new Set([
@@ -233,7 +177,6 @@ export class OfficeRegistry {
         this.lockTimeoutMs = options.lockTimeoutMs ?? REGISTRY_LOCK_TIMEOUT_MS;
         this.state = this.readState();
     }
-    /** Reload the atomic registry file after another host process changed it. */
     reload() {
         this.state = this.readState();
         return this.state;
@@ -255,11 +198,6 @@ export class OfficeRegistry {
             return this.state;
         });
     }
-    /**
-     * Record that an office exists. Idempotent: re-recording a known office is
-     * a lock-free cache hit for callers that materialize directories per
-     * message, so this sits safely on hot write paths.
-     */
     recordOffice(address) {
         const normalized = validateOfficeAddress(address);
         const existing = this.findOffice(normalized);
@@ -284,11 +222,6 @@ export class OfficeRegistry {
     findOffice(address) {
         return this.state.offices.find((record) => record.platform === address.platform && record.conversationId === address.conversationId);
     }
-    /**
-     * Validate and record a legacy directory. With exactly one enabled platform,
-     * ownership is safe to infer. With zero or multiple platforms, the record
-     * remains explicit `needs-owner` unless the caller supplies an owner.
-     */
     prepareLegacyMigration(options) {
         const rawConversationId = assertConversationId(options.rawConversationId);
         const sourceDir = resolve(options.sourceDir);
@@ -437,11 +370,6 @@ export class OfficeRegistry {
         this.writeState(this.registryPath, `${JSON.stringify(candidate, null, 2)}\n`);
         this.state = candidate;
     }
-    /**
-     * Acquire the domain lease, reload while holding it, then perform one
-     * read-modify-write. A future move transaction can retain the same lease
-     * across its filesystem operation instead of splitting the transition.
-     */
     withExclusiveLease(operation) {
         const release = acquireRegistryLease(this.lockPath, this.lockTimeoutMs);
         try {
@@ -524,7 +452,6 @@ function parseState(value, path) {
     if (new Set(enabledPlatforms).size !== enabledPlatforms.length) {
         throw new Error(`Duplicate enabled platform in ${path}`);
     }
-    // Files written before office records existed simply have no offices yet.
     const offices = (Array.isArray(value.offices) ? value.offices : []).map((entry) => parseOfficeRecord(entry, path));
     if (new Set(offices.map((record) => officeKey(record))).size !== offices.length) {
         throw new Error(`Duplicate office record in ${path}`);
@@ -556,7 +483,6 @@ function hasMigrationStrings(value) {
         typeof value.status === "string" &&
         typeof value.updatedAt === "string");
 }
-/** Validate the fields every stored migration record must carry. */
 function parseMigrationFields(value, path) {
     if (!hasMigrationStrings(value)) {
         throw new Error(`Invalid office migration fields in ${path}`);
@@ -577,10 +503,6 @@ function parseMigrationFields(value, path) {
         updatedAt: value.updatedAt,
     };
 }
-/**
- * Ownership rules by status: `needs-owner` must carry neither owner nor
- * target, `failed` may carry either, every other status must carry both.
- */
 function assertOwnershipMatchesStatus(status, ownerPlatform, targetDir, path) {
     const owned = ownerPlatform !== undefined;
     const targeted = targetDir !== undefined;
@@ -673,7 +595,6 @@ function assertRegularDirectory(path, label) {
         throw new Error(`${label} must be a regular directory: ${path}`);
     }
 }
-/** `lstat` that reports a missing path as undefined; other errors still throw. */
 function lstatIfExists(path) {
     try {
         return lstatSync(path);
@@ -703,7 +624,6 @@ function assertPathAbsent(path, label) {
 function pathExists(path) {
     return lstatIfExists(path) !== undefined;
 }
-/** Create the lock directory and stamp it with our token, unwinding on failure. */
 function claimRegistryLock(lockPath, token) {
     mkdirSync(lockPath, { mode: 0o700 });
     try {
@@ -727,10 +647,6 @@ function acquireRegistryLease(lockPath, timeoutMs) {
         }
     }
 }
-/**
- * Handle one failed lock attempt: rethrow anything but a held lock, clear a
- * stale lock so the next attempt wins, else wait until the deadline passes.
- */
 function awaitFreeRegistryLock(lockPath, deadline, error) {
     if (!isErrno(error, "EEXIST"))
         throw error;
@@ -772,9 +688,7 @@ function registryLockIsStale(lockPath) {
             }
         }
     }
-    catch {
-        // The owner file may not have been written before its process died.
-    }
+    catch { }
     try {
         const oldEnough = Date.now() - statSync(lockPath).mtimeMs >= REGISTRY_LOCK_STALE_MS;
         return ownerKnown ? !ownerAlive : oldEnough;
@@ -786,21 +700,9 @@ function registryLockIsStale(lockPath) {
 function sleepSync(milliseconds) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
 }
-// ── raw-id lookups (cold paths: CLI, Admin enumeration) ──────────────────────
-/** Current office inventory, read fresh from disk for cross-process freshness. */
 export function listRegisteredOffices(stateDir) {
     return new OfficeRegistry(stateDir).getOffices();
 }
-/**
- * Enabled platforms whose id format could have produced this raw
- * conversation id. Auto-claiming uses this as verification, not guessing:
- * every format below is one mikan itself writes (GitHub ids are mikan-derived
- * slugs; Slack/Telegram/Discord ids are the platforms' own grammars), and a
- * directory is only claimed when exactly one enabled platform's format
- * matches. Bare digits stay ambiguous while both Telegram and Discord are
- * enabled (negative ids are Telegram-only); anything matching no enabled
- * format fails closed to needs-owner.
- */
 function platformsMatchingConversationIdFormat(rawConversationId, enabledPlatforms) {
     return enabledPlatforms.filter((platform) => {
         switch (platform) {
@@ -827,18 +729,6 @@ function isGithubConversationId(rawConversationId) {
 function isErrno(error, code) {
     return error instanceof Error && "code" in error && error.code === code;
 }
-// ── Boot-time legacy migration ────────────────────────────────────────────────
-/**
- * Move every legacy raw-id office directory under the workspace root to the
- * canonical office-key layout, journaling each move through the office
- * registry so an interrupted run resumes instead of losing offices.
- *
- * The engine never guesses: with several enabled platforms an unowned raw
- * directory stays in place and is reported for `mikan office claim`. Callers
- * must treat a non-empty `unowned`/`failed` as fatal for daemon boot — after
- * the layout flip, an unmigrated legacy directory is invisible to the
- * runtime, which would silently present the conversation as empty.
- */
 export function migrateLegacyOffices(options) {
     const registry = new OfficeRegistry(options.stateDir);
     for (const platform of options.enabledPlatforms)
@@ -855,8 +745,6 @@ export function migrateLegacyOffices(options) {
     };
     recoverInterruptedMoves(registry, summary);
     claimAndMoveLegacyDirs(registry, options.workspaceRoot, summary);
-    // Credential vaults are keyed by office too; the registry inventory (which
-    // the directory moves above just extended) drives the same rename.
     const vaults = migrateConversationVaultKeys({
         stateDir: options.stateDir,
         offices: registry.getOffices(),
@@ -875,7 +763,6 @@ export function migrateLegacyOffices(options) {
     }
     return summary;
 }
-/** Complete or fail every move the journal says was interrupted mid-rename. */
 function recoverInterruptedMoves(registry, summary) {
     for (const record of registry.getState().migrations) {
         if (record.status !== "moving")
@@ -891,7 +778,6 @@ function recoverInterruptedMoves(registry, summary) {
         log.logInfo(`[office] Recovered interrupted migration: ${record.rawConversationId}`);
     }
 }
-/** Complete one interrupted rename; returns the failure reason when it cannot. */
 function finishInterruptedMove(record) {
     const targetDir = record.targetDir;
     if (!targetDir)
@@ -907,12 +793,6 @@ function finishInterruptedMove(record) {
         renameSync(record.sourceDir, targetDir);
     return undefined;
 }
-/**
- * A legacy directory is claimable unless it already failed (reported via
- * summary.failed). One that reappears after a committed move is a different
- * (or resurrected) office the runtime can no longer see, so refusing to boot
- * beats silently ignoring its data.
- */
 function isClaimableLegacyDir(registry, workspaceRoot, rawConversationId) {
     const existing = registry.getMigration(rawConversationId);
     if (existing?.status === "committed") {
@@ -920,7 +800,6 @@ function isClaimableLegacyDir(registry, workspaceRoot, rawConversationId) {
     }
     return existing?.status !== "failed";
 }
-/** Scan the workspace root and move every claimable legacy office directory. */
 function claimAndMoveLegacyDirs(registry, workspaceRoot, summary) {
     for (const rawConversationId of listLegacyOfficeDirs(workspaceRoot)) {
         if (!isClaimableLegacyDir(registry, workspaceRoot, rawConversationId))
@@ -931,7 +810,7 @@ function claimAndMoveLegacyDirs(registry, workspaceRoot, summary) {
             workspaceRoot,
         });
         if (record.status === "needs-owner")
-            continue; // reported via summary.unowned
+            continue;
         const moving = registry.markMoving(rawConversationId);
         const targetDir = moving.targetDir;
         if (!targetDir)
@@ -943,12 +822,6 @@ function claimAndMoveLegacyDirs(registry, workspaceRoot, summary) {
         log.logInfo(`[office] Migrated office directory: ${rawConversationId} -> ${targetDir}`);
     }
 }
-/**
- * Move each registered office's host state tree from
- * `conversations/<rawId>` to
- * `conversations/<officeKey>` in one rename. Conflicts are reported for
- * manual merge, never clobbered.
- */
 function migrateConversationStateDirs(registry, stateDir, summary) {
     for (const office of registry.getOffices()) {
         const legacyDir = join(stateDir, "conversations", office.conversationId);
@@ -964,7 +837,6 @@ function migrateConversationStateDirs(registry, stateDir, summary) {
         log.logInfo(`[office] Migrated host state dir to office key: ${office.conversationId}`);
     }
 }
-/** A migrated office is an existing office; keep the directory enumerable. */
 function recordMigratedOffice(registry, record) {
     if (!record.ownerPlatform)
         return;
@@ -973,19 +845,6 @@ function recordMigratedOffice(registry, record) {
         conversationId: record.rawConversationId,
     });
 }
-/**
- * Legacy office candidates: regular directories that are not reserved
- * infrastructure, not hidden, and not already office-key named. A symlink in
- * office position is refused outright — following it could move data from
- * outside the workspace root.
- *
- * A candidate must also look like a conversation office: every office that
- * ever saw a message has a `log.jsonl`, and every office that ran the agent
- * has `sessions/`. Trusted workspace roots legitimately accumulate other
- * directories — repos the agent cloned, build output — which are not offices
- * and must be neither renamed nor reported as unowned; they stay where they
- * are (an operator can still claim one explicitly via `mikan office claim`).
- */
 function listLegacyOfficeDirs(workspaceRoot) {
     return readdirSync(workspaceRoot, { withFileTypes: true })
         .filter((entry) => isLegacyOfficeDir(workspaceRoot, entry))
@@ -1012,7 +871,6 @@ function isLegacyOfficeDir(workspaceRoot, entry) {
 function looksLikeConversationOffice(dir) {
     return existsSync(join(dir, "log.jsonl")) || existsSync(join(dir, "sessions"));
 }
-/** Operator-facing boot failure for offices the engine may not move itself. */
 export function formatUnmigratedOfficesError(summary) {
     const lines = ["Conversation office migration cannot complete:"];
     if (summary.unowned.length > 0) {
@@ -1030,20 +888,11 @@ export function formatUnmigratedOfficesError(summary) {
     ]));
     return lines.join("\n");
 }
-/** One blank-separated "these need manual work" block, empty when nothing does. */
 function conflictSection(ids, explanation) {
     if (ids.length === 0)
         return [];
     return ["", ...explanation, ...ids.map((id) => `  - ${id}`)];
 }
-/**
- * Bind-spec translator for the container layout migration: rewrites every
- * host path the office migration renamed — workspace dirs, per-conversation
- * state trees, conversation vaults — and the guest workspace segment, using
- * the registry's office inventory as the raw-id ↔ office mapping. Specs that
- * reference none of the renamed paths come back unchanged, which is also how
- * an already-migrated container is recognized.
- */
 function replacePrefix(path, pairs) {
     for (const [oldPrefix, newPrefix] of pairs) {
         if (path === oldPrefix)