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

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

@@ -6,9 +6,11 @@ import { handleConfig } from "./config.js";
 import { handleDaemon } from "./daemon.js";
 import { handleLoop } from "./loop.js";
 import { handleMachine } from "./machine.js";
+import { handleOrchestrator } from "./orchestrator.js";
 import { handleRelay } from "./relay.js";
 import { handleRemote } from "./remote.js";
 import { handleSession } from "./session.js";
+import { handleSkill } from "./skill.js";
 import { handleToken } from "./token.js";
 import { handleTurn } from "./turn.js";
 import { commandUsage, commandUsageText, handleCliError, parseCliFlags, skillText, startBootstrap, topLevelDoctor, topLevelStatus, usage, usageText } from "./lib/index.js";
@@ -22,7 +24,9 @@ const domainHandlers = [
     handleDaemon,
     handleRelay,
     handleMachine,
+    handleOrchestrator,
     handleSession,
+    handleSkill,
     handleTurn,
     handleCollect,
 ];
@@ -31,7 +35,7 @@ export async function main() {
     const [domain] = argv;
     if (!domain)
         usage();
-    if (domain === "--skill" || domain === "skill") {
+    if (domain === "--skill") {
         console.log(skillText());
         return;
     }

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

@@ -1,4 +1,4 @@
-import { configPath, ok, readConfig, redactedControllerConfig, requireRelayUrl, requireString, wantsJson, writeConfig } from "./lib/index.js";
+import { configPath, ok, readConfig, redactedControllerConfig, redactedRelayUrl, requireRelayUrl, requireString, wantsJson, writeConfig } from "./lib/index.js";
 export async function handleConfig({ domain, action, flags }) {
     if (domain === "config" && action === "init") {
         const config = {
@@ -7,7 +7,7 @@ export async function handleConfig({ domain, action, flags }) {
             accountSecret: requireString(flags, "secret"),
         };
         await writeConfig(config);
-        ok("config.init", { path: configPath, relayUrl: config.relayUrl });
+        ok("config.init", { path: configPath, relayUrl: redactedRelayUrl(config.relayUrl) });
         return true;
     }
     if (domain === "config" && action === "show") {

package/apps/cli/dist/commands/lib/args.js

@@ -23,6 +23,8 @@ const valueFlags = new Set([
     "permission-mode",
     "prompt",
     "prompt-file",
+    "query",
+    "request-id",
     "every",
     "reason",
     "relay",
@@ -35,11 +37,14 @@ const valueFlags = new Set([
     "format",
     "loops",
     "machines",
+    "messages",
     "sessions",
     "secret",
     "since",
     "stop-on",
     "tail",
+    "tag",
+    "tags",
     "text",
     "text-file",
     "timeout",
@@ -56,8 +61,10 @@ const valueFlags = new Set([
 const booleanFlags = new Set([
     "all",
     "detach",
+    "force",
     "help",
     "h",
+    "include-output",
     "include-archived",
     "json",
     "keep-source",

package/apps/cli/dist/commands/lib/config.d.ts

@@ -2,6 +2,7 @@ import type { CliConfig, DaemonConfig } from "./types.js";
 export declare function requireString(flags: Record<string, string | boolean>, key: string): string;
 export declare function requirePositional(value: string | undefined, name: string): string;
 export declare function normalizeRelayUrl(value: string): string;
+export declare function redactedRelayUrl(value: string): string;
 export declare function requireRelayUrl(flags: Record<string, string | boolean>, key?: string): string;
 export declare function readConfig(flags: Record<string, string | boolean>): Promise<CliConfig>;
 export declare function readDaemonConfig(): Promise<DaemonConfig>;

package/apps/cli/dist/commands/lib/config.js

@@ -17,6 +17,19 @@ export function requirePositional(value, name) {
 export function normalizeRelayUrl(value) {
     return value.replace(/\/+$/, "");
 }
+export function redactedRelayUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.username || url.password) {
+            url.username = "";
+            url.password = "";
+        }
+        return normalizeRelayUrl(url.toString());
+    }
+    catch {
+        return normalizeRelayUrl(value.replace(/\/\/[^/@]+@/u, "//"));
+    }
+}
 function assertStringField(candidate, field, label) {
     const value = candidate[field];
     if (typeof value !== "string" || value.length === 0) {
@@ -125,7 +138,7 @@ export async function writeDaemonConfig(config) {
 }
 export function redactedDaemonConfig(config) {
     return {
-        relayUrl: config.relayUrl,
+        relayUrl: redactedRelayUrl(config.relayUrl),
         accountId: config.accountId,
         machineId: config.machineId,
         machineName: config.machineName,
@@ -136,7 +149,7 @@ export function redactedDaemonConfig(config) {
 }
 export function redactedControllerConfig(config) {
     return {
-        relayUrl: config.relayUrl,
+        relayUrl: redactedRelayUrl(config.relayUrl),
         hasControllerToken: Boolean(config.controllerToken),
         hasAccountSecret: Boolean(config.accountSecret),
     };

package/apps/cli/dist/commands/lib/doctor.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { configDir, configPath } from "./paths.js";
-import { redactedControllerConfig, redactedDaemonConfig } from "./config.js";
+import { redactedControllerConfig, redactedDaemonConfig, redactedRelayUrl } from "./config.js";
 import { ok, wantsJson } from "./json.js";
 import { localDaemonStatus } from "./local-daemon.js";
 import { readExistingControllerConfig, readExistingDaemonConfig, relayHealth } from "./relay-http.js";
@@ -21,11 +21,11 @@ export async function topLevelDoctor(flags) {
             name: "relay",
             ok: health.ok,
             message: health.ok ? "reachable" : `HTTP ${health.status}`,
-            details: { relayUrl: relay.relayUrl, body: health.body },
+            details: { relayUrl: redactedRelayUrl(relay.relayUrl), body: health.body },
         });
     }
     catch (error) {
-        checks.push({ name: "relay", ok: false, message: error instanceof Error ? error.message : String(error), details: { relayUrl: relay.relayUrl } });
+        checks.push({ name: "relay", ok: false, message: error instanceof Error ? error.message : String(error), details: { relayUrl: redactedRelayUrl(relay.relayUrl) } });
     }
     const existingDaemon = await readExistingDaemonConfig().catch((error) => {
         checks.push({ name: "daemon-config", ok: false, message: error instanceof Error ? error.message : String(error) });

package/apps/cli/dist/commands/lib/exit.js

@@ -126,6 +126,7 @@ export function handleCliError(error) {
         activeTurnId: enriched.activeTurnId,
         latestCompletedTurnId: enriched.latestCompletedTurnId,
         commandAcked: enriched.commandAcked,
-    }, enriched.capability);
+        rawStatus: enriched.rawStatus,
+    }, enriched.capability, enriched.retryable);
     process.exit(1);
 }

package/apps/cli/dist/commands/lib/index.d.ts

@@ -13,6 +13,7 @@ export * from "./exit.js";
 export * from "./json.js";
 export * from "./local-daemon.js";
 export * from "./loop-store.js";
+export * from "./orchestrator.js";
 export * from "./paths.js";
 export * from "./relay-http.js";
 export * from "./scope.js";

package/apps/cli/dist/commands/lib/index.js

@@ -13,6 +13,7 @@ export * from "./exit.js";
 export * from "./json.js";
 export * from "./local-daemon.js";
 export * from "./loop-store.js";
+export * from "./orchestrator.js";
 export * from "./paths.js";
 export * from "./relay-http.js";
 export * from "./scope.js";

package/apps/cli/dist/commands/lib/json.d.ts

@@ -1,5 +1,5 @@
 import type { JsonEnvelope } from "../../../../../packages/shared/dist/index.js";
 export declare function ok<T>(type: string, data: T, meta?: JsonEnvelope["meta"]): void;
-export declare function writeError(code: string, message: string, meta?: JsonEnvelope["meta"], capability?: string): void;
+export declare function writeError(code: string, message: string, meta?: JsonEnvelope["meta"], capability?: string, retryable?: boolean): void;
 export declare function wantsJson(flags: Record<string, string | boolean>): boolean;
 export declare function wantsVerbose(flags: Record<string, string | boolean>): boolean;

package/apps/cli/dist/commands/lib/json.js

@@ -1,10 +1,10 @@
 export function ok(type, data, meta = {}) {
     console.log(JSON.stringify({ ok: true, type, data, meta }, null, 2));
 }
-export function writeError(code, message, meta = {}, capability) {
+export function writeError(code, message, meta = {}, capability, retryable) {
     console.error(JSON.stringify({
         ok: false,
-        error: { code, message, ...(capability ? { capability } : {}) },
+        error: { code, message, ...(capability ? { capability } : {}), ...(retryable !== undefined ? { retryable } : {}) },
         meta,
     }, null, 2));
 }

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

@@ -0,0 +1,30 @@
+import type { SessionSnapshot } from "../../../../../packages/shared/dist/index.js";
+import type { OrchestrationSummary } from "./types.js";
+import type { TurnSummary } from "./session-output.js";
+export declare const ORCHESTRATOR_CONTRACT_VERSION = 1;
+export type OrchestratorStatus = "idle" | "inProgress" | "completed" | "needsInput" | "blocked" | "failed" | "cancelled" | "offline" | "closed";
+export type OrchestratorRequestRecord = {
+    turnId: string;
+    promptSha256: string;
+    createdAt: number;
+};
+export type OrchestratorMetadata = {
+    tags?: string[];
+    requests?: Record<string, OrchestratorRequestRecord>;
+};
+export type MetadataWithOrchestrator = Record<string, unknown> & {
+    orchestrator?: Record<string, unknown> & {
+        tags?: string[];
+        requests?: Record<string, unknown>;
+    };
+};
+export declare function promptSha256(text: string): string;
+export declare function deterministicTurnId(threadId: string, requestId: string): string;
+export declare function deterministicRelayRequestId(threadId: string, requestId: string): string;
+export declare function normalizeOrchestratorStatus(session: Pick<SessionSnapshot, "status">, orchestration: OrchestrationSummary, latestTurn?: Pick<TurnSummary, "status">): OrchestratorStatus;
+export declare function normalizeOrchestratorTag(value: string): string;
+export declare function normalizeOrchestratorTags(values: readonly string[]): string[];
+export declare function readOrchestratorMetadata(metadata: Record<string, unknown>): OrchestratorMetadata;
+export declare function withOrchestratorTags(metadata: Record<string, unknown>, tags: string[]): MetadataWithOrchestrator;
+export declare function withOrchestratorRequest(metadata: Record<string, unknown>, requestId: string, request: OrchestratorRequestRecord): MetadataWithOrchestrator;
+export declare function withoutOrchestratorRequest(metadata: Record<string, unknown>, requestId: string): MetadataWithOrchestrator;

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

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { CliError } from "../../errors.js";
+export const ORCHESTRATOR_CONTRACT_VERSION = 1;
+export function promptSha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function deterministicTurnId(threadId, requestId) {
+    const digest = createHash("sha256").update(threadId).update("\0").update(requestId).digest("base64url");
+    return `turn_${digest.slice(0, 28)}`;
+}
+export function deterministicRelayRequestId(threadId, requestId) {
+    const digest = createHash("sha256").update("orchestrator").update("\0").update(threadId).update("\0").update(requestId).digest("base64url");
+    return `req_${digest.slice(0, 28)}`;
+}
+export function normalizeOrchestratorStatus(session, orchestration, latestTurn) {
+    if (session.status === "closed")
+        return "closed";
+    if (session.status === "offline")
+        return "offline";
+    if (orchestration.needsUser)
+        return "needsInput";
+    if (orchestration.blocked)
+        return "blocked";
+    if (latestTurn?.status === "running" || session.status === "running" || session.status === "new")
+        return "inProgress";
+    if (latestTurn?.status === "failed" || session.status === "failed")
+        return "failed";
+    if (latestTurn?.status === "cancelled" || session.status === "cancelled")
+        return "cancelled";
+    if (latestTurn?.status === "completed" || orchestration.completed || session.status === "completed")
+        return "completed";
+    return "idle";
+}
+export function normalizeOrchestratorTag(value) {
+    const tag = value.trim().toLowerCase();
+    if (!tag)
+        throw new CliError("Empty orchestrator tag is not allowed", "INVALID_ARGUMENT");
+    if (tag.length > 64)
+        throw new CliError(`Orchestrator tag is too long: ${tag}`, "INVALID_ARGUMENT");
+    if (!/^[a-z0-9._-]+$/u.test(tag)) {
+        throw new CliError(`Invalid orchestrator tag: ${value}`, "INVALID_ARGUMENT");
+    }
+    return tag;
+}
+export function normalizeOrchestratorTags(values) {
+    const tags = [...new Set(values.map(normalizeOrchestratorTag))];
+    if (tags.length > 20)
+        throw new CliError("A thread can have at most 20 orchestrator tags", "INVALID_ARGUMENT");
+    return tags;
+}
+export function readOrchestratorMetadata(metadata) {
+    const raw = metadata.orchestrator;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const record = raw;
+    const tags = Array.isArray(record.tags)
+        ? [...new Set(record.tags.flatMap((item) => {
+                if (typeof item !== "string")
+                    return [];
+                try {
+                    return [normalizeOrchestratorTag(item)];
+                }
+                catch {
+                    return [];
+                }
+            }))]
+        : undefined;
+    const requests = {};
+    if (record.requests && typeof record.requests === "object" && !Array.isArray(record.requests)) {
+        for (const [requestId, value] of Object.entries(record.requests)) {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                continue;
+            const candidate = value;
+            if (typeof candidate.turnId === "string" &&
+                typeof candidate.promptSha256 === "string" &&
+                typeof candidate.createdAt === "number") {
+                requests[requestId] = {
+                    turnId: candidate.turnId,
+                    promptSha256: candidate.promptSha256,
+                    createdAt: candidate.createdAt,
+                };
+            }
+        }
+    }
+    return {
+        ...(tags ? { tags } : {}),
+        ...(Object.keys(requests).length > 0 ? { requests } : {}),
+    };
+}
+function rawOrchestratorMetadata(metadata) {
+    return metadata.orchestrator && typeof metadata.orchestrator === "object" && !Array.isArray(metadata.orchestrator)
+        ? { ...metadata.orchestrator }
+        : {};
+}
+function rawOrchestratorRequests(rawOrchestrator) {
+    return rawOrchestrator.requests && typeof rawOrchestrator.requests === "object" && !Array.isArray(rawOrchestrator.requests)
+        ? { ...rawOrchestrator.requests }
+        : {};
+}
+export function withOrchestratorTags(metadata, tags) {
+    const rawOrchestrator = rawOrchestratorMetadata(metadata);
+    return {
+        ...metadata,
+        orchestrator: {
+            ...rawOrchestrator,
+            tags: normalizeOrchestratorTags(tags),
+        },
+    };
+}
+export function withOrchestratorRequest(metadata, requestId, request) {
+    const rawOrchestrator = rawOrchestratorMetadata(metadata);
+    const rawRequests = rawOrchestratorRequests(rawOrchestrator);
+    const existingRequest = rawRequests[requestId] && typeof rawRequests[requestId] === "object" && !Array.isArray(rawRequests[requestId])
+        ? { ...rawRequests[requestId] }
+        : {};
+    return {
+        ...metadata,
+        orchestrator: {
+            ...rawOrchestrator,
+            requests: {
+                ...rawRequests,
+                [requestId]: {
+                    ...existingRequest,
+                    ...request,
+                },
+            },
+        },
+    };
+}
+export function withoutOrchestratorRequest(metadata, requestId) {
+    const rawOrchestrator = rawOrchestratorMetadata(metadata);
+    const orchestrator = readOrchestratorMetadata(metadata);
+    const requests = rawOrchestratorRequests(rawOrchestrator);
+    delete requests[requestId];
+    const nextOrchestrator = {
+        ...rawOrchestrator,
+        ...(orchestrator.tags ? { tags: orchestrator.tags } : {}),
+        ...(Object.keys(requests).length > 0 ? { requests } : {}),
+    };
+    if (Object.keys(requests).length === 0)
+        delete nextOrchestrator.requests;
+    return {
+        ...metadata,
+        ...(Object.keys(nextOrchestrator).length > 0 ? { orchestrator: nextOrchestrator } : { orchestrator: undefined }),
+    };
+}

package/apps/cli/dist/commands/lib/relay-http.js

@@ -1,7 +1,14 @@
 import { CliError } from "../../errors.js";
-import { normalizeRelayUrl, readConfig, readDaemonConfig } from "./config.js";
+import { normalizeRelayUrl, readConfig, readDaemonConfig, redactedRelayUrl } from "./config.js";
 export async function relayHealth(relayUrl) {
-    const response = await fetch(`${normalizeRelayUrl(relayUrl)}/health`);
+    const normalizedRelayUrl = normalizeRelayUrl(relayUrl);
+    let response;
+    try {
+        response = await fetch(`${normalizedRelayUrl}/health`);
+    }
+    catch (error) {
+        throw cliErrorFromFetch(error, "RELAY_UNREACHABLE", `Could not reach ${redactedRelayUrl(normalizedRelayUrl)}`);
+    }
     const text = await response.text();
     let body = text;
     try {
@@ -90,8 +97,12 @@ export async function readExistingDaemonConfig() {
 export function cliErrorFromFetch(error, code, message) {
     if (error instanceof CliError)
         return error;
-    const suffix = error instanceof Error ? `: ${error.message}` : "";
-    return new CliError(`${message}${suffix}`, code);
+    const redactedMessage = redactUrlCredentialsInText(message);
+    const suffix = error instanceof Error ? `: ${redactUrlCredentialsInText(error.message)}` : "";
+    return new CliError(`${redactedMessage}${suffix}`, code);
+}
+function redactUrlCredentialsInText(value) {
+    return value.replace(/(https?:\/\/)([^/@\s]+)@/gu, "$1");
 }
 export function isAuthTokenInvalid(error) {
     if (!error || typeof error !== "object")

package/apps/cli/dist/commands/lib/session-output.d.ts

@@ -50,6 +50,7 @@ export declare function summarizeTurns(events: DecodedSessionEvent[]): TurnSumma
 export declare function structuredOutputForTurn(sessionId: string, turn: TurnSummary): StructuredCommandOutput;
 export declare function structuredOutputForStoredTurn(output: StoredTurnOutput): StructuredCommandOutput;
 export declare function structuredOutputForRunningTurn(sessionId: string, turnId: string): StructuredCommandOutput;
+export declare function collectExactTurnEvents(client: ControllerClient, sessionId: string, turnId: string, limit?: number): Promise<DecodedSessionEvent[]>;
 export declare function rebuildTurnOutput(client: ControllerClient, sessionId: string, turnId?: string): Promise<StoredTurnOutput>;
 export declare function conciseEvents(events: DecodedSessionEvent[]): Array<{
     id: number;

package/apps/cli/dist/commands/lib/session-output.js

@@ -280,7 +280,7 @@ function foldAliasedRuntimeEvents(events) {
             profile.output += payload.text;
         }
         else if (payload?.type === "done") {
-            const runtimeTurnId = payload.lastTurnId ?? payload.currentHead;
+            const runtimeTurnId = payload.lastTurnId;
             if (runtimeTurnId && runtimeTurnId !== event.turnId && !runtimeTurnId.startsWith("event:")) {
                 runtimeToRequest.set(runtimeTurnId, event.turnId);
             }
@@ -288,7 +288,6 @@ function foldAliasedRuntimeEvents(events) {
         profiles.set(event.turnId, profile);
     }
     const duplicateRuntimeTurns = new Set();
-    const duplicateRuntimeToRequest = new Map();
     for (const [runtimeTurnId, requestTurnId] of runtimeToRequest) {
         const request = profiles.get(requestTurnId);
         const runtime = profiles.get(runtimeTurnId);
@@ -298,12 +297,11 @@ function foldAliasedRuntimeEvents(events) {
             continue;
         if (isDuplicateRuntimeOutput(request.output, runtime.output)) {
             duplicateRuntimeTurns.add(runtimeTurnId);
-            duplicateRuntimeToRequest.set(runtimeTurnId, requestTurnId);
         }
     }
     return {
         events: duplicateRuntimeTurns.size === 0 ? events : events.filter((event) => !duplicateRuntimeTurns.has(event.turnId)),
-        runtimeToRequest: duplicateRuntimeToRequest,
+        runtimeToRequest,
     };
 }
 function isDuplicateRuntimeOutput(requestOutput, runtimeOutput) {
@@ -324,13 +322,47 @@ function turnInProgressError(sessionId, turn, latestCompleted) {
         latestCompletedTurnId: latestCompleted?.turnId,
     });
 }
+export async function collectExactTurnEvents(client, sessionId, turnId, limit = 1000) {
+    const events = [];
+    const seen = new Set();
+    let since;
+    for (let pageCount = 0; pageCount < 200; pageCount += 1) {
+        const page = await client.collectPage(sessionId, {
+            turnId,
+            limit,
+            ...(since === undefined ? {} : { since }),
+        });
+        for (const event of page.events) {
+            if (seen.has(event.id))
+                continue;
+            seen.add(event.id);
+            events.push(event);
+        }
+        const nextSince = page.newestCursor
+            ?? page.newestEventId
+            ?? (page.events.length > 0 ? Math.max(...page.events.map((event) => event.id)) : undefined);
+        if (page.events.length < limit || nextSince === undefined || nextSince === since)
+            break;
+        since = nextSince;
+    }
+    return events;
+}
 export async function rebuildTurnOutput(client, sessionId, turnId) {
-    const events = await client.history(sessionId, 1000);
-    const folded = foldAliasedRuntimeEvents(events);
-    const resolvedTurnId = turnId ? folded.runtimeToRequest.get(turnId) ?? turnId : undefined;
-    const turns = summarizeTurns(events);
-    const latestCompleted = turns.find((turn) => turn.status === "completed");
-    const summary = resolvedTurnId ? turns.find((turn) => turn.turnId === resolvedTurnId) : turns[0];
+    let events = await client.history(sessionId, 1000);
+    let folded = foldAliasedRuntimeEvents(events);
+    let resolvedTurnId = turnId ? folded.runtimeToRequest.get(turnId) ?? turnId : undefined;
+    let turns = summarizeTurns(events);
+    let latestCompleted = turns.find((turn) => turn.status === "completed");
+    let summary = resolvedTurnId ? turns.find((turn) => turn.turnId === resolvedTurnId) : turns[0];
+    const exactTurnId = turnId ? (resolvedTurnId ?? turnId) : summary?.status === "running" ? undefined : summary?.turnId;
+    if (exactTurnId) {
+        events = await collectExactTurnEvents(client, sessionId, exactTurnId, 1000);
+        folded = foldAliasedRuntimeEvents(events);
+        resolvedTurnId = turnId ? (folded.runtimeToRequest.get(turnId) ?? resolvedTurnId) : exactTurnId;
+        turns = summarizeTurns(events);
+        latestCompleted = turns.find((turn) => turn.status === "completed") ?? latestCompleted;
+        summary = resolvedTurnId ? turns.find((turn) => turn.turnId === resolvedTurnId) : turns[0];
+    }
     if (!summary) {
         throw new CliError(turnId ? `Turn ${turnId} was not found in the latest relay history.` : "No turn output found for session", turnId ? "TURN_NOT_FOUND" : "RESULT_NOT_FOUND");
     }

package/apps/cli/dist/commands/lib/status.js

@@ -1,5 +1,5 @@
 import { ControllerClient } from "../../../../../packages/client/dist/index.js";
-import { readConfig } from "./config.js";
+import { readConfig, redactedRelayUrl } from "./config.js";
 import { ok, wantsJson } from "./json.js";
 import { localDaemonStatus } from "./local-daemon.js";
 import { displayPath, lastAssistantOutput, readStoredTurnOutput } from "./session-output.js";
@@ -20,7 +20,7 @@ export async function topLevelStatus(flags) {
         ? lastAssistantOutput(await client.history(latestSession.id, 200).catch(() => []))
         : "";
     const data = {
-        relayUrl: config.relayUrl,
+        relayUrl: redactedRelayUrl(config.relayUrl),
         relay: {
             ok: Boolean(snapshot),
             ...(relayError ? { error: relayError } : {}),
@@ -46,7 +46,7 @@ export async function topLevelStatus(flags) {
         ok("status", data);
         return;
     }
-    console.log(`Relay: ${config.relayUrl}${relayError ? ` (unreachable: ${relayError})` : ""}`);
+    console.log(`Relay: ${data.relayUrl}${relayError ? ` (unreachable: ${relayError})` : ""}`);
     console.log(`Daemon: ${localStatus.running ? `running${localStatus.pid ? ` pid ${localStatus.pid}` : ""}` : "not running"}`);
     console.log(`Machines: ${data.machines.onlineCount}/${data.machines.count} online`);
     console.log(`Sessions: ${data.sessions.count} total, ${data.sessions.runningCount} running`);

package/apps/cli/dist/commands/lib/types.d.ts

@@ -30,6 +30,7 @@ export type SessionMetadata = {
     name?: string;
     requestedRuntimeName?: string;
     runtime?: unknown;
+    [key: string]: unknown;
 };
 export declare const idleSessionStatuses: SessionSnapshot["status"][];
 export type OrchestrationState = "pending" | "active" | "idle" | "completed" | "blocked" | "needs-user" | "closed";

package/apps/cli/dist/commands/lib/usage.js

@@ -43,6 +43,18 @@ Check local controller config, relay reachability, and daemon state.
   diagnose/exec are LAN/dev-only. exec requires the daemon to advertise devTools.
   --timeout-ms limits the remote process. --wait-timeout-ms limits how long this CLI waits for the result.
   file preview is read-only and limited to files inside --root.
+`,
+    orchestrator: `Usage:
+  happy-elves orchestrator list-threads [--query <q>] [--tag <tag>] [--machine <id>] [--limit n] [--all] --json
+  happy-elves orchestrator read-thread <threadId> [--messages latest|all] [--limit n] [--include-output] --json
+  happy-elves orchestrator send-message <threadId> (--text <prompt> | --text-file <path>) --request-id <id> [--permission-mode <mode>] [--runtime-timeout 1000s] --json
+  happy-elves orchestrator wait-thread <threadId> --turn <turnId> [--timeout 1000s] --json
+  happy-elves orchestrator set-thread-tags <threadId> --tags worker,reviewer --json
+
+Codex-like orchestration:
+  threadId is the existing sessionId. send-message is detached by default and
+  returns a deterministic turnId for the supplied request id. wait-thread waits
+  for that exact turn id instead of following the latest turn.
 `,
     session: `Usage:
   happy-elves session create --machine <machineId> [--agent codex] [--cwd <path>] [--name <name>] [--permission-mode <mode>] --json
@@ -92,6 +104,11 @@ Turn management:
   happy-elves token create [--name <name>] [--machines a,b] [--sessions a,b] [--loops a,b] --actions a,b [--expires-in 24h] --json
   happy-elves token list [--verbose] [--json]
   happy-elves token revoke <tokenId> --json
+`,
+    skill: `Usage:
+  happy-elves skill print [--name happy-elves-orchestrator]
+  happy-elves skill install --to <skills-dir> [--name happy-elves-orchestrator] [--force] --json
+  happy-elves skill doctor [--to <skills-dir>] [--name happy-elves-orchestrator] [--json]
 `,
     loop: `Usage:
   happy-elves loop create <sessionId> [--every 15m] (--prompt <text> | --prompt-file <path>) [--stop-on blocked] --json
@@ -158,6 +175,11 @@ Core commands:
   turn rewind <sessionId> <turn-or-checkpoint-id> --json
   turn fork <sessionId> <turn-or-checkpoint-id> --name <name> --json
 
+  orchestrator list-threads --json
+  orchestrator send-message <threadId> --text <prompt> --request-id <id> --json
+  orchestrator read-thread <threadId> --json
+  orchestrator wait-thread <threadId> --turn <turnId> --json
+
   remote status --json
   remote devices [--json]
   remote invite-controller [--device-name <name>] [--ttl 10m] --json
@@ -173,15 +195,15 @@ Usage:
   happy-elves --help
 
 Common flows:
-  Discover: machine list --json; session list --machine <machineId> --json
-  Continue: session history --machine <machineId> --json; session continue <runtimeSessionId> --machine <machineId> --json
-  Execute: turn run <sessionId> --text <prompt> --json; turn result <sessionId> <turnId> --json
+  Orchestrate: orchestrator list-threads --json; orchestrator send-message <threadId> --text <prompt> --request-id <id> --json; orchestrator wait-thread <threadId> --turn <turnId> --json
+  Debug: machine list --json; session list --machine <machineId> --json; turn result <sessionId> <turnId> --json
   Branch: turn rewind <sessionId> <turnId> --json; turn fork <sessionId> <turnId> --name <name> --json
 
 More:
   happy-elves --skill
   happy-elves <domain> --help
   start, status, doctor, collect, config, account, daemon, relay, token, loop.
+  orchestrator, skill.
 `;
 }
 export function skillText() {
@@ -199,17 +221,17 @@ Do not:
   returns a sessionId.
 
 Recommended agent workflow:
-  1. machine list --json
-  2. session list --machine <machineId> --limit 20 --json
-  3. session history --machine <machineId> --limit 20 --json
-  4. session continue <runtimeSessionId> --machine <machineId> --json
-  5. turn run <sessionId> --text <prompt> --json
-  6. turn wait <sessionId> <turnId> --json
-  7. turn result <sessionId> <turnId> --json
+  1. orchestrator list-threads --json
+  2. orchestrator read-thread <threadId> --json
+  3. orchestrator send-message <threadId> --text <prompt> --request-id <stable-id> --json
+  4. orchestrator read-thread <threadId> --json
+  5. orchestrator wait-thread <threadId> --turn <turnId> --json
 
 Concepts:
   Loaded session: a Happy Elves control-plane session that can be operated by
   this CLI.
+  Thread: an orchestrator-facing alias for a loaded session. threadId is the
+  same value as sessionId.
   Runtime history: read-only provider history discovered by session history.
   Turn: one execution within a loaded session.
   Relay: encrypted transport between controllers and daemons. Use relay
@@ -230,12 +252,20 @@ Session management:
 Output modes:
   Prefer --json when another agent or program will parse the result.
   Use human output for direct terminal inspection.
-  Default JSON is compact: list/status/turn answer with bounded projections,
-  not raw metadata or event streams.
-  Add --verbose to status, list, history, turn list, or collect when internal
-  details are needed for debugging.
-  turn run waits for completion by default with a 1000s timeout. Use --detach
-  only when you intentionally want background execution.
+  Orchestrator JSON is compact by default. read-thread returns only a short
+  latest-turn projection unless --messages latest|all or --include-output is
+  explicitly requested.
+  list-threads returns loaded sessions, including known offline/closed sessions;
+  --all is an explicit alias for that loaded-session scope. If a running
+  thread's history is unavailable, the item reports historyStatus/historyError
+  instead of pretending to be healthy inProgress.
+  send-message requires --request-id and is detached by default. Reusing the
+  same request id with the same prompt returns the same turn; reusing it with a
+  different prompt returns REQUEST_ID_CONFLICT.
+
+Debug commands:
+  machine/session/turn commands remain available for lower-level inspection,
+  runtime history import, rewind, fork, and result repair.
 
 Security notes:
   Account secrets stay on controllers and daemons.