@cydm/happy-elves 0.1.0-beta.47 → 0.1.0-beta.49

package/apps/cli/dist/commands/orchestrator.d.ts

@@ -0,0 +1,2 @@
+import type { CommandInput } from "./command.js";
+export declare function handleOrchestrator({ domain, action, positional, flags }: CommandInput): Promise<boolean>;

package/apps/cli/dist/commands/orchestrator.js

@@ -0,0 +1,411 @@
+import { CliError, ControllerClient, DEFAULT_COMMAND_TIMEOUT_MS, collectExactTurnEvents, compactText, conciseEvents, deterministicRelayRequestId, deterministicTurnId, deriveOrchestration, normalizeOrchestratorStatus, normalizeOrchestratorTag, normalizeOrchestratorTags, ok, parseDurationMs, parsePermissionMode, promptSha256, readConfig, readOrchestratorMetadata, readPromptTextFile, rebuildTurnOutput, requirePositional, requireString, summarizeTurns, withOrchestratorRequest, withOrchestratorTags, } from "./lib/index.js";
+const defaultTurnHistoryLimit = 1000;
+const defaultMessageLimit = 50;
+class OrchestratorError extends CliError {
+    options;
+    constructor(message, code, options = {}) {
+        super(message, code);
+        this.options = options;
+        Object.assign(this, options);
+    }
+}
+function parsePositiveIntFlag(flags, name) {
+    const value = flags[name];
+    if (value === undefined || value === false)
+        return undefined;
+    if (value === true)
+        throw new CliError(`Missing --${name} value`, "MISSING_ARGUMENT");
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new CliError(`Invalid --${name}: ${value}`, "INVALID_ARGUMENT");
+    }
+    return parsed;
+}
+function optionalString(flags, name) {
+    const value = flags[name];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function parseTagsFlag(flags) {
+    const tags = requireString(flags, "tags")
+        .split(",")
+        .map((tag) => tag.trim())
+        .filter(Boolean);
+    return normalizeOrchestratorTags(tags);
+}
+function machineForSession(machines, session) {
+    return machines.find((machine) => machine.id === session.machineId);
+}
+function compactTurnRef(turn, includeOutput) {
+    if (!turn)
+        return undefined;
+    const output = turn.output || turn.terminalText || undefined;
+    return {
+        turnId: turn.turnId,
+        ...(turn.checkpointId ? { checkpointId: turn.checkpointId } : {}),
+        ...(turn.runtimeTurnId ? { runtimeTurnId: turn.runtimeTurnId } : {}),
+        status: turn.status,
+        ...(turn.prompt ? { promptPreview: compactText(turn.prompt, 180) } : {}),
+        ...(output ? { outputPreview: compactText(output, 360) } : {}),
+        ...(includeOutput && output ? { finalOutput: output } : {}),
+        ...(turn.startedAt !== undefined ? { startedAt: turn.startedAt } : {}),
+        ...(turn.completedAt !== undefined ? { completedAt: turn.completedAt } : {}),
+        updatedAt: turn.updatedAt,
+    };
+}
+async function threadSummary(client, session, machines, options = {}) {
+    const metadata = await client.decodeSessionMetadata(session);
+    const orchestrator = readOrchestratorMetadata(metadata);
+    const events = options.events ?? [];
+    const turns = events.length > 0 ? summarizeTurns(events) : [];
+    const latestTurn = turns[0];
+    const orchestration = options.historyFailure
+        ? {
+            state: "blocked",
+            rawStatus: session.status,
+            needsUser: false,
+            blocked: true,
+            completed: false,
+            reason: `history unavailable: ${options.historyFailure.code}`,
+        }
+        : deriveOrchestration(session, events);
+    const status = normalizeOrchestratorStatus(session, orchestration, latestTurn);
+    const machine = machineForSession(machines, session);
+    return {
+        threadId: session.id,
+        sessionId: session.id,
+        name: metadata.name ?? session.name,
+        tags: orchestrator.tags ?? [],
+        status,
+        rawStatus: session.status,
+        agent: metadata.agent ?? session.agent,
+        cwd: metadata.cwd ?? session.cwd,
+        updatedAt: session.updatedAt,
+        machine: {
+            machineId: session.machineId,
+            name: machine?.name,
+            online: machine?.online === true,
+        },
+        orchestration,
+        ...(options.historyFailure ? {
+            historyStatus: "unavailable",
+            historyError: options.historyFailure,
+        } : {}),
+        ...(options.includeLatestTurn ? { latestTurn: compactTurnRef(latestTurn, options.includeOutput === true) } : {}),
+    };
+}
+async function readThreadContext(client, threadId) {
+    const snapshot = await client.snapshot();
+    const session = snapshot.sessions.find((item) => item.id === threadId);
+    if (!session) {
+        throw new OrchestratorError(`Thread not found: ${threadId}`, "THREAD_NOT_FOUND", { sessionId: threadId, retryable: false });
+    }
+    return { machines: snapshot.machines, session };
+}
+function requestRecordForExistingTurn(turn, hash, createdAt) {
+    if (!turn)
+        return undefined;
+    return {
+        turnId: turn.turnId,
+        promptSha256: hash,
+        createdAt: turn.startedAt ?? turn.updatedAt ?? createdAt,
+    };
+}
+function errorCode(error) {
+    const candidate = error;
+    return typeof candidate?.code === "string" ? candidate.code : undefined;
+}
+function retryableError(error) {
+    const candidate = error;
+    return typeof candidate?.retryable === "boolean" ? candidate.retryable : true;
+}
+function threadHistoryFailure(error) {
+    return {
+        code: errorCode(error) ?? "HISTORY_UNAVAILABLE",
+        message: compactText(error instanceof Error ? error.message : String(error), 240),
+        retryable: retryableError(error),
+    };
+}
+async function readExactTurn(client, threadId, turnId) {
+    const events = await collectExactTurnEvents(client, threadId, turnId, defaultTurnHistoryLimit);
+    return summarizeTurns(events).find((turn) => turn.turnId === turnId);
+}
+async function eventsForThreadSummary(client, session) {
+    if (session.status !== "running" && session.status !== "new")
+        return [];
+    return await client.history(session.id, defaultTurnHistoryLimit);
+}
+async function safeEventsForThreadSummary(client, session) {
+    try {
+        return { events: await eventsForThreadSummary(client, session) };
+    }
+    catch (error) {
+        return { events: [], historyFailure: threadHistoryFailure(error) };
+    }
+}
+async function persistRequestRecordBestEffort(client, threadId, requestId, record) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const { session } = await readThreadContext(client, threadId);
+        const metadata = await client.decodeSessionMetadata(session);
+        const existing = readOrchestratorMetadata(metadata).requests?.[requestId];
+        if (existing) {
+            if (existing.turnId === record.turnId && existing.promptSha256 === record.promptSha256)
+                return;
+            return;
+        }
+        try {
+            await client.updateSessionMetadata(session.id, withOrchestratorRequest(metadata, requestId, record), { expectedUpdatedAt: session.updatedAt });
+            return;
+        }
+        catch (error) {
+            if (errorCode(error) !== "SESSION_METADATA_CONFLICT")
+                return;
+        }
+    }
+}
+function terminalStatusForTurn(turn) {
+    if (turn.status === "completed")
+        return "completed";
+    if (turn.status === "failed")
+        return "failed";
+    if (turn.status === "cancelled")
+        return "cancelled";
+    return "inProgress";
+}
+function requestConflict(threadId, requestId, turnId) {
+    return new OrchestratorError(`Request id already exists with different prompt content: ${requestId}`, "REQUEST_ID_CONFLICT", { retryable: false, sessionId: threadId, turnId });
+}
+function threadBusy(threadId, active, latestCompleted) {
+    return new OrchestratorError(`Thread already has a running turn: ${active.turnId}`, "THREAD_BUSY", {
+        retryable: true,
+        sessionId: threadId,
+        turnId: active.turnId,
+        activeTurnId: active.turnId,
+        latestCompletedTurnId: latestCompleted?.turnId,
+        rawStatus: "running",
+    });
+}
+async function waitForTurn(client, threadId, turnId, timeoutMs) {
+    const startedAt = Date.now();
+    while (true) {
+        const turn = await readExactTurn(client, threadId, turnId);
+        if (turn && turn.status !== "running")
+            return turn;
+        if (Date.now() - startedAt >= timeoutMs) {
+            throw new OrchestratorError(`Turn ${turnId} is still running or has not reached relay history yet.`, "TURN_WAIT_TIMEOUT", { retryable: true, sessionId: threadId, turnId, rawStatus: turn?.status ?? "missing" });
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+}
+function eventsForMessages(events, turns, mode, limit) {
+    if (!mode)
+        return undefined;
+    if (mode !== "latest" && mode !== "all")
+        throw new CliError(`Invalid --messages: ${mode}`, "INVALID_ARGUMENT");
+    const selected = mode === "latest" && turns[0]
+        ? events.filter((event) => event.turnId === turns[0]?.turnId)
+        : events;
+    return conciseEvents(selected).slice(-limit);
+}
+export async function handleOrchestrator({ domain, action, positional, flags }) {
+    if (domain !== "orchestrator")
+        return false;
+    const config = await readConfig(flags);
+    const client = new ControllerClient(config);
+    if (action === "list-threads") {
+        const snapshot = await client.snapshot();
+        const query = optionalString(flags, "query")?.toLowerCase();
+        const tag = optionalString(flags, "tag");
+        const normalizedTag = tag ? normalizeOrchestratorTag(tag) : undefined;
+        const machineId = optionalString(flags, "machine");
+        const limit = parsePositiveIntFlag(flags, "limit");
+        const candidates = [];
+        for (const session of snapshot.sessions) {
+            if (machineId && session.machineId !== machineId)
+                continue;
+            const metadata = await client.decodeSessionMetadata(session);
+            const orchestrator = readOrchestratorMetadata(metadata);
+            const tags = orchestrator.tags ?? [];
+            if (normalizedTag && !tags.includes(normalizedTag))
+                continue;
+            const searchable = [
+                session.id,
+                session.machineId,
+                metadata.name ?? session.name,
+                metadata.cwd ?? session.cwd,
+                metadata.agent ?? session.agent,
+                ...tags,
+            ].join("\n").toLowerCase();
+            if (query && !searchable.includes(query))
+                continue;
+            candidates.push(session);
+        }
+        const selected = limit === undefined ? candidates : candidates.slice(0, limit);
+        const threads = [];
+        for (const session of selected) {
+            const { events, historyFailure } = await safeEventsForThreadSummary(client, session);
+            threads.push(await threadSummary(client, session, snapshot.machines, { events, historyFailure }));
+        }
+        ok("orchestrator.listThreads", {
+            threads,
+            page: {
+                totalCount: candidates.length,
+                returned: threads.length,
+                hasMore: threads.length < candidates.length,
+                ...(limit !== undefined ? { limit } : {}),
+            },
+        });
+        return true;
+    }
+    if (action === "read-thread") {
+        const threadId = requirePositional(positional[0], "threadId");
+        const { session, machines } = await readThreadContext(client, threadId);
+        const limit = parsePositiveIntFlag(flags, "limit") ?? defaultMessageLimit;
+        const events = await client.history(threadId, defaultTurnHistoryLimit);
+        const turns = summarizeTurns(events);
+        const includeOutput = flags["include-output"] === true;
+        ok("orchestrator.readThread", {
+            thread: await threadSummary(client, session, machines, { events, includeLatestTurn: true, includeOutput }),
+            ...(eventsForMessages(events, turns, optionalString(flags, "messages"), limit) ? {
+                messages: eventsForMessages(events, turns, optionalString(flags, "messages"), limit),
+            } : {}),
+        }, { sessionId: threadId, turnId: turns[0]?.turnId });
+        return true;
+    }
+    if (action === "send-message") {
+        const threadId = requirePositional(positional[0], "threadId");
+        const text = typeof flags.text === "string"
+            ? flags.text
+            : typeof flags["text-file"] === "string"
+                ? await readPromptTextFile(flags["text-file"])
+                : "";
+        if (!text.trim())
+            throw new CliError("Missing --text or --text-file", "MISSING_ARGUMENT");
+        const requestId = requireString(flags, "request-id");
+        const turnId = deterministicTurnId(threadId, requestId);
+        const relayRequestId = deterministicRelayRequestId(threadId, requestId);
+        const hash = promptSha256(text);
+        const self = await client.tokenSelf();
+        if (!self.full) {
+            throw new OrchestratorError("orchestrator send-message requires a full controller token.", "SCOPED_TOKEN_FORBIDDEN", { retryable: false, sessionId: threadId, turnId });
+        }
+        await readThreadContext(client, threadId);
+        const events = await client.history(threadId, defaultTurnHistoryLimit);
+        const turns = summarizeTurns(events);
+        const existingTurn = await readExactTurn(client, threadId, turnId);
+        if (existingTurn?.prompt && promptSha256(existingTurn.prompt) !== hash)
+            throw requestConflict(threadId, requestId, turnId);
+        const active = turns.find((turn) => turn.status === "running");
+        const latestCompleted = turns.find((turn) => turn.status === "completed");
+        if (active && active.turnId !== turnId)
+            throw threadBusy(threadId, active, latestCompleted);
+        if (existingTurn && existingTurn.status !== "running") {
+            await persistRequestRecordBestEffort(client, threadId, requestId, requestRecordForExistingTurn(existingTurn, hash, Date.now()) ?? {
+                turnId,
+                promptSha256: hash,
+                createdAt: Date.now(),
+            });
+            ok("orchestrator.sendMessage", {
+                threadId,
+                sessionId: threadId,
+                turnId,
+                requestId,
+                status: terminalStatusForTurn(existingTurn),
+                rawStatus: existingTurn.status,
+                finalOutput: existingTurn.output || existingTurn.terminalText || undefined,
+            }, { requestId, sessionId: threadId, turnId });
+            return true;
+        }
+        if (existingTurn?.status === "running") {
+            ok("orchestrator.sendMessage", {
+                threadId,
+                sessionId: threadId,
+                turnId,
+                requestId,
+                status: "inProgress",
+                rawStatus: existingTurn?.status ?? "running",
+            }, { requestId, sessionId: threadId, turnId });
+            return true;
+        }
+        const record = { turnId, promptSha256: hash, createdAt: Date.now() };
+        const permissionMode = parsePermissionMode(flags["permission-mode"] ?? flags.permission);
+        const runtimeTimeoutMs = parseDurationMs(flags["runtime-timeout"], DEFAULT_COMMAND_TIMEOUT_MS);
+        try {
+            await client.run(threadId, text, {
+                wait: false,
+                permissionMode,
+                requestId: relayRequestId,
+                turnId,
+                promptHash: hash,
+                ackTimeoutMs: 15_000,
+                runtimeTimeoutMs,
+            });
+        }
+        catch (error) {
+            const enriched = error;
+            if (enriched.code === "REQUEST_ID_CONFLICT")
+                throw requestConflict(threadId, requestId, turnId);
+            if (enriched.code === "SESSION_BUSY") {
+                throw new OrchestratorError(enriched.message, "THREAD_BUSY", {
+                    retryable: true,
+                    sessionId: threadId,
+                    turnId,
+                    activeTurnId: enriched.activeTurnId,
+                    latestCompletedTurnId: enriched.latestCompletedTurnId,
+                    rawStatus: "running",
+                });
+            }
+            throw error;
+        }
+        await persistRequestRecordBestEffort(client, threadId, requestId, record);
+        ok("orchestrator.sendMessage", {
+            threadId,
+            sessionId: threadId,
+            turnId,
+            requestId,
+            status: "inProgress",
+            rawStatus: "running",
+        }, { requestId, sessionId: threadId, turnId });
+        return true;
+    }
+    if (action === "wait-thread") {
+        const threadId = requirePositional(positional[0], "threadId");
+        const turnId = requireString(flags, "turn");
+        await readThreadContext(client, threadId);
+        const turn = await waitForTurn(client, threadId, turnId, parseDurationMs(flags.timeout, DEFAULT_COMMAND_TIMEOUT_MS));
+        const output = await rebuildTurnOutput(client, threadId, turnId);
+        ok("orchestrator.waitThread", {
+            threadId,
+            sessionId: threadId,
+            turnId,
+            status: terminalStatusForTurn(turn),
+            rawStatus: turn.status,
+            finalOutput: output.output || undefined,
+            artifactPaths: {
+                output: output.outputPath,
+                latest: output.latestPath,
+                metadata: output.metadataPath,
+            },
+        }, { sessionId: threadId, turnId });
+        return true;
+    }
+    if (action === "set-thread-tags") {
+        const threadId = requirePositional(positional[0], "threadId");
+        const tags = parseTagsFlag(flags);
+        const { session, machines } = await readThreadContext(client, threadId);
+        const metadata = await client.decodeSessionMetadata(session);
+        let updated;
+        try {
+            updated = await client.updateSessionMetadata(threadId, withOrchestratorTags(metadata, tags), { expectedUpdatedAt: session.updatedAt });
+        }
+        catch (error) {
+            if (errorCode(error) !== "SESSION_METADATA_CONFLICT")
+                throw error;
+            throw new OrchestratorError("Session metadata changed while setting thread tags; retry with the latest session.", "SESSION_METADATA_CONFLICT", { retryable: true, sessionId: threadId });
+        }
+        ok("orchestrator.setThreadTags", {
+            thread: await threadSummary(client, updated, machines),
+        }, { sessionId: threadId });
+        return true;
+    }
+    return false;
+}

package/apps/cli/dist/commands/relay.js

@@ -1,4 +1,4 @@
-import { CliError, ok, relayHealth, requireRelayUrl, wantsJson } from "./lib/index.js";
+import { CliError, ok, redactedRelayUrl, relayHealth, requireRelayUrl, wantsJson } from "./lib/index.js";
 export async function handleRelay({ domain, action, flags }) {
     if (domain === "relay" && action === "serve") {
         const host = typeof flags.host === "string" ? flags.host : "0.0.0.0";
@@ -40,10 +40,10 @@ export async function handleRelay({ domain, action, flags }) {
             };
         }
         if (wantsJson(flags)) {
-            ok("relay.status", { relayUrl, health });
+            ok("relay.status", { relayUrl: redactedRelayUrl(relayUrl), health });
         }
         else {
-            console.log(`Relay ${relayUrl}: ${health.ok ? "ok" : `HTTP ${health.status}`}`);
+            console.log(`Relay ${redactedRelayUrl(relayUrl)}: ${health.ok ? "ok" : `HTTP ${health.status}`}`);
         }
         return true;
     }
@@ -64,11 +64,11 @@ export async function handleRelay({ domain, action, flags }) {
         }
         const allOk = checks.every((check) => check.ok);
         if (wantsJson(flags)) {
-            ok("relay.doctor", { ok: allOk, relayUrl, checks });
+            ok("relay.doctor", { ok: allOk, relayUrl: redactedRelayUrl(relayUrl), checks });
         }
         else {
             console.log(`Relay doctor: ${allOk ? "ok" : "issues found"}`);
-            console.log(`relay: ${relayUrl}`);
+            console.log(`relay: ${redactedRelayUrl(relayUrl)}`);
             for (const check of checks) {
                 console.log(`${check.ok ? "ok" : "fail"} ${check.name}: ${check.message}`);
             }

package/apps/cli/dist/commands/remote.js

@@ -1,5 +1,5 @@
 import os from "node:os";
-import { ControllerClient, configPath, ok, parseControllerJoinUrl, parseDurationMs, randomId, readConfig, relayHealth, requirePositional, requireRelayUrl, requireString, showMachine, wantsJson, wantsVerbose, writeConfig } from "./lib/index.js";
+import { ControllerClient, configPath, ok, parseControllerJoinUrl, parseDurationMs, randomId, readConfig, redactedRelayUrl, relayHealth, requirePositional, requireRelayUrl, requireString, showMachine, wantsJson, wantsVerbose, writeConfig } from "./lib/index.js";
 export async function handleRemote({ domain, action, positional, flags }) {
     if (domain === "remote" && action === "devices") {
         const config = await readConfig(flags);
@@ -49,7 +49,7 @@ export async function handleRemote({ domain, action, positional, flags }) {
             client.listDevices(),
         ]);
         const data = {
-            relayUrl: config.relayUrl,
+            relayUrl: redactedRelayUrl(config.relayUrl),
             relay: health,
             devices: {
                 count: devices.devices.length,

package/apps/cli/dist/commands/skill.d.ts

@@ -0,0 +1,2 @@
+import type { CommandInput } from "./command.js";
+export declare function handleSkill({ domain, action, flags }: CommandInput): Promise<boolean>;

package/apps/cli/dist/commands/skill.js

@@ -0,0 +1,214 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { ControllerClient, ORCHESTRATOR_CONTRACT_VERSION, ok, readConfig, redactedRelayUrl, requireString, } from "./lib/index.js";
+import { CliError } from "../errors.js";
+const defaultSkillName = "happy-elves-orchestrator";
+function optionalString(flags, name) {
+    const value = flags[name];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function skillName(flags) {
+    const name = optionalString(flags, "name") ?? defaultSkillName;
+    if (!/^[a-z0-9._-]+$/u.test(name))
+        throw new CliError(`Invalid skill name: ${name}`, "INVALID_ARGUMENT");
+    return name;
+}
+function installableSkillText(input) {
+    const name = input.skillName ?? defaultSkillName;
+    return `---
+name: ${name}
+description: Codex-like orchestration for Happy Elves loaded sessions using a CLI-first API.
+---
+
+# Happy Elves Orchestrator
+
+CLI version: ${input.cliVersion}
+Orchestrator contract version: ${input.contractVersion}
+
+## When To Use
+Use this skill when the user asks you to coordinate Happy Elves sessions, workers, reviewers, remote agents, or existing loaded sessions.
+
+## Main Workflow
+Always prefer the orchestrator API:
+
+\`\`\`bash
+happy-elves orchestrator list-threads --json
+happy-elves orchestrator read-thread <threadId> --json
+happy-elves orchestrator send-message <threadId> --text "<prompt>" --request-id <stable-id> --json
+happy-elves orchestrator wait-thread <threadId> --turn <turnId> --json
+\`\`\`
+
+Important rules:
+- \`threadId\` is the same value as Happy Elves \`sessionId\`.
+- Use stable request ids such as \`orch_round_3_worker_fix\`.
+- Reusing the same request id with the same prompt returns the same turn.
+- Reusing the same request id with different prompt text returns \`REQUEST_ID_CONFLICT\`.
+- If \`send-message\` returns \`THREAD_BUSY\`, wait/read the active turn instead of sending another prompt.
+- For waiting, use the exact \`turnId\` returned by \`send-message\`; do not follow "latest" in multi-actor workflows.
+- After installing or updating this skill, open a fresh Codex thread or reload skills before relying on the new instructions.
+
+## Discovery
+Use tags when the user has designated roles:
+
+\`\`\`bash
+happy-elves orchestrator list-threads --tag worker --json
+happy-elves orchestrator set-thread-tags <threadId> --tags worker,architecture-docs --json
+\`\`\`
+
+\`list-threads\` returns loaded sessions, including offline or closed sessions already known to the controller. \`--all\` is an explicit alias for this default loaded-session scope.
+
+If a running thread cannot load recent history, \`list-threads\` returns that thread with \`historyStatus: "unavailable"\` and \`historyError\`; do not treat it as healthy \`inProgress\`. Use \`read-thread <threadId>\` for a fail-fast exact-thread check.
+
+If tags are absent, use \`--query\` to find likely sessions, then ask only if multiple plausible targets remain.
+
+## Reading
+\`read-thread\` is intentionally compact by default. Ask for larger payloads only when needed:
+
+\`\`\`bash
+happy-elves orchestrator read-thread <threadId> --messages latest --json
+happy-elves orchestrator read-thread <threadId> --messages all --limit 100 --json
+happy-elves orchestrator read-thread <threadId> --include-output --json
+\`\`\`
+
+## Debug Fallback
+Use lower-level commands only for debugging, history import, repair, rewind, or fork:
+
+\`\`\`bash
+happy-elves machine list --json
+happy-elves session list --machine <machineId> --json
+happy-elves session status <sessionId> --verbose --json
+happy-elves turn result <sessionId> <turnId> --json
+\`\`\`
+
+## Safety
+Do not send prompts to real worker/reviewer sessions unless the user has clearly identified the target. For dogfood or probes, create or use a temporary session instead.
+`;
+}
+async function cliVersion() {
+    for (const candidate of [
+        path.resolve(import.meta.dirname, "..", "..", "..", "..", "package.json"),
+        path.resolve(import.meta.dirname, "..", "..", "..", "package.json"),
+        path.resolve(import.meta.dirname, "..", "..", "package.json"),
+    ]) {
+        try {
+            const parsed = JSON.parse(await fs.readFile(candidate, "utf8"));
+            if (typeof parsed.version === "string" && parsed.version.trim())
+                return parsed.version.trim();
+        }
+        catch {
+            // Try the next source or packaged layout.
+        }
+    }
+    return "0.1.0";
+}
+async function skillDoctor(flags) {
+    const checks = [];
+    const warnings = [];
+    checks.push({
+        name: "cli-executable",
+        status: "ok",
+        detail: process.argv[1] ? pathToFileURL(process.argv[1]).toString() : process.execPath,
+    });
+    checks.push({
+        name: "orchestrator-contract",
+        status: "ok",
+        detail: String(ORCHESTRATOR_CONTRACT_VERSION),
+    });
+    const installRoot = optionalString(flags, "to");
+    if (installRoot) {
+        const installed = path.join(installRoot, skillName(flags), "SKILL.md");
+        try {
+            const source = await fs.readFile(installed, "utf8");
+            const okVersion = source.includes(`Orchestrator contract version: ${ORCHESTRATOR_CONTRACT_VERSION}`);
+            checks.push({
+                name: "installed-skill",
+                status: okVersion ? "ok" : "warning",
+                detail: installed,
+            });
+            if (!okVersion)
+                warnings.push("Installed skill contract version differs from this CLI.");
+        }
+        catch (error) {
+            checks.push({
+                name: "installed-skill",
+                status: "warning",
+                detail: error instanceof Error ? error.message : String(error),
+            });
+            warnings.push("Skill is not installed at the provided --to directory.");
+        }
+    }
+    else {
+        checks.push({ name: "installed-skill", status: "warning", detail: "Pass --to <skills-dir> to check installation." });
+    }
+    try {
+        const config = await readConfig(flags);
+        const client = new ControllerClient(config);
+        const machines = await client.listMachines();
+        const online = machines.filter((machine) => machine.online).length;
+        checks.push({ name: "relay", status: "ok", detail: redactedRelayUrl(config.relayUrl) });
+        checks.push({
+            name: "online-machine",
+            status: online > 0 ? "ok" : "warning",
+            detail: `${online}/${machines.length} online`,
+        });
+        if (online === 0)
+            warnings.push("No online Happy Elves machines are currently visible.");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        checks.push({ name: "relay", status: "warning", detail: message });
+        warnings.push("Controller config or relay is not currently reachable.");
+    }
+    return { checks, warnings };
+}
+export async function handleSkill({ domain, action, flags }) {
+    if (domain !== "skill")
+        return false;
+    if (action === "print") {
+        console.log(installableSkillText({
+            cliVersion: await cliVersion(),
+            contractVersion: ORCHESTRATOR_CONTRACT_VERSION,
+            skillName: skillName(flags),
+        }));
+        return true;
+    }
+    if (action === "install") {
+        const root = requireString(flags, "to");
+        const name = skillName(flags);
+        const dir = path.join(root, name);
+        const file = path.join(dir, "SKILL.md");
+        await fs.mkdir(dir, { recursive: true });
+        if (flags.force !== true) {
+            try {
+                await fs.access(file);
+                throw new CliError(`Skill already exists at ${file}. Re-run with --force to overwrite.`, "SKILL_EXISTS");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        await fs.writeFile(file, installableSkillText({
+            cliVersion: await cliVersion(),
+            contractVersion: ORCHESTRATOR_CONTRACT_VERSION,
+            skillName: name,
+        }));
+        ok("skill.install", {
+            skill: name,
+            path: file,
+            contractVersion: ORCHESTRATOR_CONTRACT_VERSION,
+        });
+        return true;
+    }
+    if (action === "doctor") {
+        const result = await skillDoctor(flags);
+        ok("skill.doctor", {
+            contractVersion: ORCHESTRATOR_CONTRACT_VERSION,
+            checks: result.checks,
+            warnings: result.warnings,
+        });
+        return true;
+    }
+    return false;
+}