@mesh-tech/mesh-cli 0.1.1 → 0.12.0

package/dist/src/commands/temporal.js

@@ -0,0 +1,781 @@
+/**
+ * mesh temporal — inspect Temporal workflows for the current app/stack.
+ *
+ * Commands:
+ *   mesh temporal describe <workflowId> [runId]   Show workflow status and metadata
+ *   mesh temporal history <workflowId> [runId]    Show workflow event history
+ *
+ * Connection info is resolved from the app's Pulumi stack output (same as mesh dev).
+ * Uses the raw gRPC API so we can render events without a codec proxy; when
+ * `--show-payloads` is set we resolve the app's `TEMPORAL_ENCODING_KEY` from
+ * its Kubernetes secret and decrypt inline via the shared codec helper.
+ */
+import { spawnSync } from "node:child_process";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { logError, logInfo, logSuccess, logWarn } from "../utils/log.js";
+import { classifyHistoryEvents, extractSnapshotMessages, reconstructTranscript, renderTranscriptMarkdown, } from "../utils/recover-conversation.js";
+import { findAppRoot, findStackConfigs, getCurrentStack, pulumiStackOutput, readStackConfig, } from "../utils/pulumi.js";
+import { resolveAwsCredentials } from "../utils/aws-auth.js";
+import { resolveTemporalAuth, acquireTemporalBearer } from "../utils/temporal-auth.js";
+import { buildDecrypterForNamespace, buildRawDecrypterForNamespace, } from "../utils/temporal-codec.js";
+/**
+ * Resolve Temporal address and namespace from the current app's stack output.
+ * Falls back to env vars if stack output isn't available.
+ */
+async function resolveConnection(options) {
+    // Explicit overrides take precedence
+    if (options.address && options.namespace) {
+        return { address: options.address, namespace: options.namespace };
+    }
+    // Try from environment (set by mesh dev)
+    if (!options.address && process.env.TEMPORAL_ADDRESS) {
+        const address = process.env.TEMPORAL_ADDRESS;
+        const namespace = options.namespace ?? process.env.TEMPORAL_NAMESPACE;
+        if (namespace)
+            return { address, namespace };
+    }
+    // Resolve from Pulumi stack output
+    const appRoot = findAppRoot(process.cwd());
+    if (!appRoot) {
+        throw new Error("Not in a Mesh app directory (no Pulumi.yaml found).\n" +
+            "Run from an app directory, or provide --address and --namespace.");
+    }
+    const stack = options.stack ?? getCurrentStack(appRoot);
+    if (!stack) {
+        const stacks = findStackConfigs(appRoot);
+        throw new Error(`No Pulumi stack selected.\n` +
+            (stacks.length > 0
+                ? `Available: ${stacks.join(", ")}\nUse: mesh temporal --stack <name> ...`
+                : "No stack configs found in this directory."));
+    }
+    const sa = stack ? ["--stack", stack] : [];
+    // Resolve AWS credentials the same way mesh dev does
+    const deployerRole = readStackConfig(appRoot, stack, "mesh:deployerRole");
+    const awsCreds = deployerRole
+        ? (await resolveAwsCredentials(deployerRole, appRoot, stack))?.env
+        : undefined;
+    // Pulumi's `app` output from env.register() is a struct containing a
+    // secret-tainted `dev` field (secret because service env vars include values
+    // like TEMPORAL_ENCODING_KEY). pulumiStackOutput transparently retries with
+    // --show-secrets when it sees a `"[secret]"` placeholder, so we can reach
+    // the non-sensitive tunnel/namespace fields nested inside.
+    let devOutput;
+    let appOutput;
+    try {
+        const result = pulumiStackOutput(appRoot, "app", sa, awsCreds);
+        appOutput = JSON.parse(result);
+        devOutput = appOutput.dev ?? appOutput;
+    }
+    catch {
+        // Legacy stacks that exported `dev` directly (pre-env.register() format).
+        try {
+            const result = pulumiStackOutput(appRoot, "dev", sa, awsCreds);
+            devOutput = JSON.parse(result);
+            appOutput = devOutput;
+        }
+        catch {
+            throw new Error(`Could not read stack output for '${stack}'.\n` +
+                "Ensure you've run: mesh deploy up\n" +
+                "Or provide --address and --namespace explicitly.");
+        }
+    }
+    const tunnel = devOutput?.tunnels?.temporal;
+    // namespace lives at the app output level, not inside dev
+    const namespace = options.namespace ?? appOutput?.namespace ?? devOutput?.namespace;
+    if (!tunnel) {
+        throw new Error("No temporal tunnel found in stack output.");
+    }
+    if (!namespace) {
+        throw new Error("No temporal namespace found in stack output.");
+    }
+    // Auth context for minting a Bearer, mirroring resolveTemporalAuthVars in dev.ts:
+    // tenant/env/name come from the PLATFORM block (platformName is the platform's
+    // name, not the app tenant — it keys the Zitadel issuer lookup).
+    const platform = (devOutput?.platform ?? appOutput?.platform);
+    const auth = platform
+        ? {
+            tenant: platform.tenant ?? "mesh",
+            env: platform.env ?? "dev",
+            platformName: platform.name ?? platform.tenant ?? "mesh",
+        }
+        : undefined;
+    return {
+        address: options.address ?? `${tunnel.host}:${tunnel.port}`,
+        namespace,
+        auth,
+    };
+}
+/**
+ * Mint a Zitadel Bearer for the connection, or return undefined to connect
+ * unauthenticated (correct for local/non-enforcing Temporal). Prefers ambient
+ * env creds (e.g. exported by `mesh dev`); otherwise resolves the app's M2M
+ * credentials from SSM via the auth context.
+ */
+async function resolveBearerToken(auth) {
+    try {
+        const haveEnvCreds = !!process.env.TEMPORAL_AUTH_CLIENT_ID && !!process.env.ZITADEL_ISSUER;
+        const vars = !haveEnvCreds && auth
+            ? await resolveTemporalAuth(auth.tenant, auth.env, auth.platformName)
+            : {};
+        return await acquireTemporalBearer(vars);
+    }
+    catch (err) {
+        logWarn(`Temporal auth unavailable (${err instanceof Error ? err.message : String(err)}); ` +
+            `connecting unauthenticated`);
+        return undefined;
+    }
+}
+// ── Event type names ─────────────────────────────────────────────────────────
+// Temporal event type enum → human-readable name
+const EVENT_TYPE_NAMES = {
+    1: "WorkflowExecutionStarted",
+    2: "WorkflowExecutionCompleted",
+    3: "WorkflowExecutionFailed",
+    4: "WorkflowExecutionTimedOut",
+    5: "WorkflowTaskScheduled",
+    6: "WorkflowTaskStarted",
+    7: "WorkflowTaskCompleted",
+    8: "WorkflowTaskTimedOut",
+    9: "WorkflowTaskFailed",
+    10: "ActivityTaskScheduled",
+    11: "ActivityTaskStarted",
+    12: "ActivityTaskCompleted",
+    13: "ActivityTaskFailed",
+    14: "ActivityTaskTimedOut",
+    15: "ActivityTaskCancelRequested",
+    16: "ActivityTaskCanceled",
+    17: "TimerStarted",
+    18: "TimerFired",
+    19: "TimerCanceled",
+    20: "WorkflowExecutionCancelRequested",
+    21: "WorkflowExecutionCanceled",
+    24: "WorkflowExecutionSignaled", // not 22/23 which were removed
+    25: "WorkflowExecutionTerminated",
+    26: "WorkflowExecutionSignaled",
+    29: "WorkflowPropertiesModified",
+    40: "ChildWorkflowExecutionStarted",
+    41: "ChildWorkflowExecutionCompleted",
+    42: "ChildWorkflowExecutionFailed",
+    43: "ChildWorkflowExecutionCanceled",
+    44: "ChildWorkflowExecutionTimedOut",
+    45: "ChildWorkflowExecutionTerminated",
+    46: "WorkflowPropertiesModified",
+    48: "NexusOperationScheduled",
+    49: "NexusOperationStarted",
+    50: "NexusOperationCompleted",
+    51: "NexusOperationFailed",
+    52: "NexusOperationCanceled",
+    53: "NexusOperationTimedOut",
+};
+// Workflow status enum → name
+const STATUS_NAMES = {
+    0: "UNSPECIFIED",
+    1: "RUNNING",
+    2: "COMPLETED",
+    3: "FAILED",
+    4: "CANCELED",
+    5: "TERMINATED",
+    6: "CONTINUED_AS_NEW",
+    7: "TIMED_OUT",
+};
+// ── Commands ─────────────────────────────────────────────────────────────────
+async function describeWorkflow(workflowId, runId, options) {
+    const conn = await connect(options);
+    try {
+        const desc = await conn.connection.workflowService.describeWorkflowExecution({
+            namespace: conn.namespace,
+            execution: { workflowId, runId },
+        });
+        const info = desc.workflowExecutionInfo;
+        if (!info) {
+            logError("No workflow execution info returned.");
+            return;
+        }
+        console.log(`Workflow:   ${workflowId}`);
+        console.log(`Run ID:     ${info.execution?.runId ?? runId ?? "?"}`);
+        console.log(`Type:       ${info.type?.name ?? "?"}`);
+        console.log(`Status:     ${STATUS_NAMES[info.status ?? 0] ?? info.status}`);
+        console.log(`Task Queue: ${info.taskQueue ?? "?"}`);
+        console.log(`Namespace:  ${conn.namespace}`);
+        // Pending activities
+        const pending = desc.pendingActivities ?? [];
+        if (pending.length > 0) {
+            console.log(`\nPending Activities (${pending.length}):`);
+            for (const pa of pending) {
+                console.log(`  - ${pa.activityType?.name ?? "?"} (attempt ${pa.attempt}, state: ${pa.state})`);
+            }
+        }
+        // Pending nexus operations
+        const pendingNexus = desc.pendingNexusOperations ?? [];
+        if (pendingNexus.length > 0) {
+            console.log(`\nPending Nexus Operations (${pendingNexus.length}):`);
+            for (const pn of pendingNexus) {
+                console.log(`  - ${pn.operation ?? "?"} → ${pn.endpoint ?? "?"} (state: ${pn.state})`);
+            }
+        }
+    }
+    finally {
+        conn.connection.close();
+    }
+}
+/**
+ * Page through a workflow's execution history, yielding each event in order.
+ * Shared by `history` (existing-history phase) and `recover-conversation` so the
+ * pagination logic lives in one place. Follow-mode long-polling is separate
+ * (it uses `waitNewEvent` + terminal detection) and stays in `showHistory`.
+ */
+async function* iterHistoryEvents(workflowService, namespace, workflowId, runId, maximumPageSize = 100) {
+    let nextPageToken;
+    do {
+        const resp = await workflowService.getWorkflowExecutionHistory({
+            namespace,
+            execution: { workflowId, runId },
+            maximumPageSize,
+            nextPageToken,
+        });
+        for (const event of resp.history?.events ?? []) {
+            yield event;
+        }
+        nextPageToken = resp.nextPageToken?.length ? resp.nextPageToken : undefined;
+    } while (nextPageToken);
+}
+async function showHistory(workflowId, runId, options) {
+    const conn = await connect(options);
+    const maxEvents = options.follow ? Infinity : parseInt(options.limit ?? "200", 10);
+    // Compact mode skips WorkflowTask* events (scheduling noise)
+    const skipTypes = new Set([5, 6, 7, 8, 9]); // WorkflowTask*
+    // Resolve the per-app encoding key lazily — only when the caller asks for
+    // payload bodies. Failure to resolve is non-fatal: we print the history
+    // without payloads and the warning from buildDecrypterForNamespace tells
+    // the user why.
+    const decrypter = options.showPayloads
+        ? await buildDecrypterForNamespace(conn.namespace)
+        : undefined;
+    try {
+        let totalShown = 0;
+        let lastEventId = 0;
+        console.log(`History for ${workflowId} (namespace: ${conn.namespace})${options.follow ? " [following]" : ""}\n`);
+        // Fetch existing history first
+        for await (const event of iterHistoryEvents(conn.connection.workflowService, conn.namespace, workflowId, runId)) {
+            lastEventId = Number(event.eventId);
+            const eventType = event.eventType ?? 0;
+            if (options.compact !== false && skipTypes.has(eventType))
+                continue;
+            await printEvent(event, decrypter);
+            totalShown++;
+            if (totalShown >= maxEvents)
+                break;
+        }
+        if (!options.follow) {
+            console.log(`\n${totalShown} events shown.`);
+            return;
+        }
+        // Follow mode: long-poll for new events until workflow completes
+        const terminalTypes = new Set([2, 3, 4, 21, 27, 28]); // Completed, Failed, TimedOut, Canceled, Terminated, ContinuedAsNew
+        let done = false;
+        while (!done) {
+            try {
+                const resp = await conn.connection.workflowService.getWorkflowExecutionHistory({
+                    namespace: conn.namespace,
+                    execution: { workflowId, runId },
+                    maximumPageSize: 100,
+                    waitNewEvent: true,
+                    // Start after the last event we've seen
+                    ...(lastEventId > 0 ? { skipArchival: true } : {}),
+                });
+                for (const event of resp.history?.events ?? []) {
+                    const eid = Number(event.eventId);
+                    if (eid <= lastEventId)
+                        continue; // already shown
+                    lastEventId = eid;
+                    const eventType = event.eventType ?? 0;
+                    if (options.compact !== false && skipTypes.has(eventType))
+                        continue;
+                    await printEvent(event, decrypter);
+                    totalShown++;
+                    // Check if workflow reached a terminal state
+                    if (terminalTypes.has(eventType)) {
+                        done = true;
+                    }
+                }
+            }
+            catch (err) {
+                // Connection reset or workflow completed between polls
+                if (err?.code === 5 /* NOT_FOUND */ || err?.message?.includes("not found")) {
+                    console.log("\nWorkflow completed or not found.");
+                    done = true;
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        console.log(`\n${totalShown} events shown (workflow ended).`);
+    }
+    finally {
+        conn.connection.close();
+    }
+}
+async function printEvent(event, decrypter) {
+    const eventType = event.eventType ?? 0;
+    const typeName = EVENT_TYPE_NAMES[eventType] ?? `Unknown(${eventType})`;
+    const id = String(event.eventId).padStart(4);
+    const detail = extractEventDetail(event);
+    const detailStr = detail ? ` — ${detail}` : "";
+    console.log(`${id}  ${typeName}${detailStr}`);
+    if (!decrypter)
+        return;
+    // Print any named payload groups attached to this event — activity input/
+    // output, signal input, workflow start args, etc. — decrypted and pretty-
+    // printed under the header line with a 6-space indent so they align under
+    // the event ID column.
+    for (const group of extractEventPayloads(event)) {
+        const rendered = await renderPayloads(group.payloads, decrypter);
+        if (rendered === null)
+            continue;
+        console.log(`      ${group.label}:`);
+        for (const line of rendered.split("\n")) {
+            console.log(`        ${line}`);
+        }
+    }
+}
+/**
+ * Pick out the payload-bearing fields on a history event. Returns an empty
+ * array for events that carry no interesting data (workflow task lifecycle,
+ * timers, property modifications, etc.).
+ */
+function extractEventPayloads(event) {
+    const groups = [];
+    const pushIfAny = (label, payloads) => {
+        if (payloads && payloads.length > 0)
+            groups.push({ label, payloads });
+    };
+    if (event.workflowExecutionStartedEventAttributes) {
+        pushIfAny("input", event.workflowExecutionStartedEventAttributes.input?.payloads);
+    }
+    if (event.workflowExecutionCompletedEventAttributes) {
+        pushIfAny("result", event.workflowExecutionCompletedEventAttributes.result?.payloads);
+    }
+    if (event.workflowExecutionFailedEventAttributes) {
+        const failure = event.workflowExecutionFailedEventAttributes.failure;
+        if (failure?.message)
+            groups.push({ label: "failure", payloads: [{ __failure: failure }] });
+    }
+    if (event.workflowExecutionSignaledEventAttributes) {
+        pushIfAny("signal input", event.workflowExecutionSignaledEventAttributes.input?.payloads);
+    }
+    if (event.activityTaskScheduledEventAttributes) {
+        pushIfAny("input", event.activityTaskScheduledEventAttributes.input?.payloads);
+    }
+    if (event.activityTaskCompletedEventAttributes) {
+        pushIfAny("result", event.activityTaskCompletedEventAttributes.result?.payloads);
+    }
+    if (event.activityTaskFailedEventAttributes) {
+        const failure = event.activityTaskFailedEventAttributes.failure;
+        if (failure?.message)
+            groups.push({ label: "failure", payloads: [{ __failure: failure }] });
+    }
+    if (event.nexusOperationScheduledEventAttributes) {
+        const input = event.nexusOperationScheduledEventAttributes.input;
+        if (input)
+            pushIfAny("input", [input]);
+    }
+    if (event.nexusOperationCompletedEventAttributes) {
+        const result = event.nexusOperationCompletedEventAttributes.result;
+        if (result)
+            pushIfAny("result", [result]);
+    }
+    if (event.nexusOperationFailedEventAttributes) {
+        const failure = event.nexusOperationFailedEventAttributes.failure;
+        if (failure?.message)
+            groups.push({ label: "failure", payloads: [{ __failure: failure }] });
+    }
+    return groups;
+}
+/**
+ * Render one or more payloads into a multi-line string, or return `null`
+ * when nothing rendered (e.g. all payloads were non-encrypted and empty).
+ *
+ * Failures (`{ __failure: ... }`) are rendered specially since they're a
+ * structured error, not an encrypted payload.
+ */
+async function renderPayloads(payloads, decrypter) {
+    const parts = [];
+    for (const payload of payloads) {
+        if (payload && typeof payload === "object" && "__failure" in payload) {
+            const failure = payload.__failure;
+            parts.push(renderFailure(failure));
+            continue;
+        }
+        const decoded = await decrypter(payload);
+        if (decoded === null) {
+            parts.push("[non-encrypted payload]");
+        }
+        else {
+            parts.push(decoded);
+        }
+    }
+    return parts.length > 0 ? parts.join("\n---\n") : null;
+}
+function renderFailure(failure) {
+    const lines = [failure.message ?? "(no message)"];
+    if (failure.stackTrace)
+        lines.push(failure.stackTrace);
+    return lines.join("\n");
+}
+/** Extract a human-readable detail string from event attributes. */
+function extractEventDetail(event) {
+    // Activity scheduled
+    if (event.activityTaskScheduledEventAttributes) {
+        const a = event.activityTaskScheduledEventAttributes;
+        return `activity: ${a.activityType?.name ?? "?"}, queue: ${a.taskQueue?.name ?? "?"}`;
+    }
+    // Activity completed
+    if (event.activityTaskCompletedEventAttributes) {
+        return `scheduledId: ${event.activityTaskCompletedEventAttributes.scheduledEventId}`;
+    }
+    // Activity failed
+    if (event.activityTaskFailedEventAttributes) {
+        const a = event.activityTaskFailedEventAttributes;
+        const msg = a.failure?.message ?? "";
+        return `scheduledId: ${a.scheduledEventId}${msg ? `, error: ${msg.slice(0, 120)}` : ""}`;
+    }
+    // Activity timed out
+    if (event.activityTaskTimedOutEventAttributes) {
+        return `scheduledId: ${event.activityTaskTimedOutEventAttributes.scheduledEventId}`;
+    }
+    // Nexus scheduled
+    if (event.nexusOperationScheduledEventAttributes) {
+        const a = event.nexusOperationScheduledEventAttributes;
+        return `endpoint: ${a.endpoint ?? "?"}, operation: ${a.operation ?? "?"}, service: ${a.service ?? "?"}`;
+    }
+    // Nexus completed/failed/timed out
+    if (event.nexusOperationCompletedEventAttributes) {
+        return `scheduledId: ${event.nexusOperationCompletedEventAttributes.scheduledEventId}`;
+    }
+    if (event.nexusOperationFailedEventAttributes) {
+        const a = event.nexusOperationFailedEventAttributes;
+        return `scheduledId: ${a.scheduledEventId}, error: ${a.failure?.message?.slice(0, 120) ?? "?"}`;
+    }
+    if (event.nexusOperationTimedOutEventAttributes) {
+        return `scheduledId: ${event.nexusOperationTimedOutEventAttributes.scheduledEventId}`;
+    }
+    // Signal
+    if (event.workflowExecutionSignaledEventAttributes) {
+        return `signal: ${event.workflowExecutionSignaledEventAttributes.signalName ?? "?"}`;
+    }
+    // Workflow started
+    if (event.workflowExecutionStartedEventAttributes) {
+        const a = event.workflowExecutionStartedEventAttributes;
+        return `type: ${a.workflowType?.name ?? "?"}, queue: ${a.taskQueue?.name ?? "?"}`;
+    }
+    // Workflow completed/failed
+    if (event.workflowExecutionCompletedEventAttributes)
+        return null;
+    if (event.workflowExecutionFailedEventAttributes) {
+        return `error: ${event.workflowExecutionFailedEventAttributes.failure?.message?.slice(0, 120) ?? "?"}`;
+    }
+    // Timer
+    if (event.timerStartedEventAttributes) {
+        const dur = event.timerStartedEventAttributes.startToFireTimeout;
+        return `timerId: ${event.timerStartedEventAttributes.timerId}, duration: ${dur?.seconds ?? "?"}s`;
+    }
+    if (event.timerFiredEventAttributes) {
+        return `timerId: ${event.timerFiredEventAttributes.timerId}`;
+    }
+    return null;
+}
+/**
+ * Reconstruct an agent conversation's transcript from its durable Temporal
+ * history — for when the worker can no longer replay it (code drift) but the
+ * history is intact. Fetches the full history (same client/decrypt path as
+ * `history`), classifies the `submit_user_message` signals (human turns) and
+ * `callLLM` activity completions (assistant turns), decrypts their payloads,
+ * and renders an ordered transcript.
+ */
+async function recoverConversation(workflowId, runId, options) {
+    const conn = await connect(options);
+    // The history is encrypted — without the key there's nothing to reconstruct,
+    // so (unlike `history`) a missing key is fatal here.
+    const decrypter = await buildDecrypterForNamespace(conn.namespace);
+    if (!decrypter) {
+        conn.connection.close();
+        throw new Error("Cannot decrypt conversation payloads: no encoding key available.\n" +
+            "Set TEMPORAL_ENCODING_KEY (e.g. from a `mesh dev` worker env) or configure " +
+            "kubectl namespace read access, then retry.");
+    }
+    try {
+        // Decode one payload group (signal input / activity result) into a plain
+        // object. The decrypter yields pretty-printed JSON; parse it back. Any
+        // failure returns undefined so the pure reconstructor emits a placeholder.
+        const decodePayload = async (payloads) => {
+            const first = payloads?.[0];
+            if (first === undefined)
+                return undefined;
+            const decoded = await decrypter(first);
+            if (decoded === null)
+                return undefined;
+            try {
+                return JSON.parse(decoded);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        // Collect the full history in order, then classify it (which activity
+        // completions were `callLLM`, which signals were `submit_user_message`)
+        // via the shared pure helper.
+        const rawEvents = [];
+        for await (const event of iterHistoryEvents(conn.connection.workflowService, conn.namespace, workflowId, runId)) {
+            rawEvents.push(event);
+        }
+        // --snapshot: emit the store-ready conversation blob with STRUCTURED
+        // ModelMessage[] (tool-call parts intact) for a full-fidelity backfill,
+        // rather than the flattened text turns. artifacts/focus are left empty —
+        // the artifact index isn't reconstructable from history here, and the store
+        // defaults them.
+        if (options.snapshot) {
+            const messages = await extractSnapshotMessages(rawEvents, decodePayload);
+            const blob = {
+                conversationId: workflowId,
+                messages,
+                artifacts: [],
+                focus: null,
+            };
+            const output = JSON.stringify(blob, null, 2) + "\n";
+            if (options.out) {
+                writeFileSync(options.out, output);
+                logSuccess(`Wrote snapshot (${messages.length} messages) to ${options.out}`);
+            }
+            else {
+                process.stdout.write(output);
+            }
+            return;
+        }
+        const events = await classifyHistoryEvents(rawEvents, decodePayload);
+        const turns = reconstructTranscript(events);
+        const output = options.json
+            ? JSON.stringify({
+                turns: turns.map((t) => ({
+                    role: t.role,
+                    text: t.text,
+                    ...(t.toolCalls ? { toolCalls: t.toolCalls } : {}),
+                })),
+            }, null, 2) + "\n"
+            : renderTranscriptMarkdown(turns);
+        if (options.out) {
+            writeFileSync(options.out, output);
+            logSuccess(`Wrote ${turns.length} turns to ${options.out}`);
+        }
+        else {
+            process.stdout.write(output);
+        }
+    }
+    finally {
+        conn.connection.close();
+    }
+}
+/**
+ * Capture a workflow's FULL durable Temporal history to a replay fixture JSON
+ * file — for LOCAL replay debugging of a specific production break. This is the
+ * real-history counterpart of the CI gate's synthetic golden fixtures: the
+ * output is the same proto3-JSON `{ events }` shape `@mesh-tech/agent-sdk`'s
+ * `historyToFixture` produces, so it runs through `replayFixture` locally. It
+ * is never committed to the replay fixtures dir — those are synthetic goldens;
+ * this file holds real decrypted production data (see warning below).
+ *
+ * Payloads are DECRYPTED (via the same codec `history --show-payloads` uses) so
+ * the fixture replays under agent-sdk's plaintext converter. Because that means
+ * the file contains real customer/conversation data, the default output path is
+ * `~/.mesh/replay-histories/` — outside any git repo — and a loud warning is
+ * printed. An explicit `--out` inside a git repo is checked with
+ * `git check-ignore`; a non-ignored path gets a loud warning (but is not
+ * blocked). Like `recover-conversation`, a missing encoding key is fatal — an
+ * encrypted fixture can't be replayed.
+ */
+async function captureHistory(workflowId, runId, options) {
+    const conn = await connect(options);
+    // A fixture whose payloads stay encrypted can't be replayed (the replayer
+    // uses a codec-free converter), so — like recover-conversation — treat a
+    // missing key as fatal rather than emitting a useless file.
+    const decrypter = await buildRawDecrypterForNamespace(conn.namespace);
+    if (!decrypter) {
+        conn.connection.close();
+        throw new Error("Cannot decrypt history payloads: no encoding key available.\n" +
+            "A replay fixture needs decrypted payloads. Set TEMPORAL_ENCODING_KEY " +
+            "(e.g. from a `mesh dev` worker env) or configure kubectl namespace read " +
+            "access, then retry.");
+    }
+    try {
+        const events = [];
+        for await (const event of iterHistoryEvents(conn.connection.workflowService, conn.namespace, workflowId, runId)) {
+            events.push(event);
+        }
+        if (events.length === 0) {
+            throw new Error(`No history events found for workflow '${workflowId}'` +
+                (runId ? ` (run ${runId})` : "") +
+                `. Check the workflow id and namespace (${conn.namespace}).`);
+        }
+        // Lazy import — pulls in @temporalio/common only when actually capturing,
+        // so the CLI still loads without the Temporal SDK installed.
+        const { serializeHistoryToFixture } = await import("../utils/capture-history.js");
+        const { fixture, eventCount, decryptedPayloads } = await serializeHistoryToFixture(events, decrypter);
+        const outPath = options.out ??
+            join(homedir(), ".mesh", "replay-histories", `${sanitizeFileId(workflowId)}.json`);
+        mkdirSync(dirname(outPath), { recursive: true });
+        if (options.out)
+            warnIfNotGitIgnored(options.out);
+        writeFileSync(outPath, JSON.stringify(fixture, null, 2) + "\n");
+        logSuccess(`Wrote replay history (${eventCount} events, ${decryptedPayloads} payloads decrypted) to ${outPath}`);
+        logWarn("⚠  This file contains DECRYPTED payloads — real customer/conversation " +
+            "data.\n" +
+            "   For LOCAL replay debugging ONLY. Do NOT commit it. (CI golden " +
+            "fixtures are synthetic; this is the debugging counterpart.)");
+    }
+    finally {
+        conn.connection.close();
+    }
+}
+/** Make a workflow id safe to use as a filename (slashes, spaces, etc.). */
+function sanitizeFileId(id) {
+    return id.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+/**
+ * A replay fixture holds real DECRYPTED production data, so when the user
+ * points `--out` at a path inside a git repo we check whether that path is
+ * git-ignored (`git check-ignore`) and print a LOUD warning when it is not —
+ * we warn, we don't block. Best-effort: silent when git is unavailable or the
+ * path is outside any repo (exit code 128), since there is nothing to commit
+ * it into.
+ */
+function warnIfNotGitIgnored(outPath) {
+    const abs = resolve(outPath);
+    try {
+        // Exit 0 = ignored, 1 = in a repo but NOT ignored, 128 = not a repo.
+        const res = spawnSync("git", ["-C", dirname(abs), "check-ignore", "-q", abs], {
+            stdio: "ignore",
+        });
+        if (res.status !== 1)
+            return;
+    }
+    catch {
+        return; // git missing/unusable — can't check, stay quiet
+    }
+    logWarn("⚠⚠⚠  OUTPUT PATH IS INSIDE A GIT REPO AND IS *NOT* GITIGNORED  ⚠⚠⚠\n" +
+        `   ${abs}\n` +
+        "   This fixture contains DECRYPTED production payloads. Add it to " +
+        ".gitignore or move it outside the repo — do NOT commit it.");
+}
+async function terminateWorkflow(workflowId, runId, options) {
+    const conn = await connect(options);
+    try {
+        await conn.connection.workflowService.terminateWorkflowExecution({
+            namespace: conn.namespace,
+            workflowExecution: { workflowId, runId },
+            reason: options.reason ?? "terminated via mesh temporal",
+            identity: "mesh-cli",
+        });
+        logSuccess(`Terminated ${workflowId}${runId ? ` (run ${runId})` : ""} in namespace ${conn.namespace}`);
+    }
+    finally {
+        conn.connection.close();
+    }
+}
+async function connect(options) {
+    const info = await resolveConnection(options);
+    logInfo(`Connecting to ${info.address} (namespace: ${info.namespace})`);
+    // Dynamic import — @temporalio/client is only available in workspaces
+    // that have it installed. The mesh-cli uses it from the monorepo.
+    const { Connection } = await import("@temporalio/client");
+    // Attach a Zitadel Bearer when the server enforces auth. Without it the
+    // MeshAuthorizer denies calls with "Request unauthorized" (e.g. terminate).
+    const token = await resolveBearerToken(info.auth);
+    const metadata = token ? { authorization: `Bearer ${token}` } : undefined;
+    const connection = await Connection.connect({ address: info.address, metadata });
+    return { connection, namespace: info.namespace };
+}
+// ── Registration ─────────────────────────────────────────────────────────────
+export function registerTemporalCommands(program) {
+    const temporal = program
+        .command("temporal")
+        .description("Inspect Temporal workflows for the current app/stack");
+    const sharedOpts = (cmd) => cmd
+        .option("--stack <stack>", "Pulumi stack name (auto-detected from current directory)")
+        .option("--address <addr>", "Temporal server address (default: from stack output)")
+        .option("--namespace <ns>", "Temporal namespace (default: from stack output)");
+    sharedOpts(temporal
+        .command("describe <workflowId> [runId]")
+        .description("Show workflow status and metadata")).action(async (workflowId, runId, opts) => {
+        try {
+            await describeWorkflow(workflowId, runId, opts);
+        }
+        catch (err) {
+            logError(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    });
+    sharedOpts(temporal
+        .command("terminate <workflowId> [runId]")
+        .description("Terminate a running workflow (e.g. a wedged/looping conversation)"))
+        .option("--reason <reason>", "Termination reason (recorded in workflow history)")
+        .action(async (workflowId, runId, opts) => {
+        try {
+            await terminateWorkflow(workflowId, runId, opts);
+        }
+        catch (err) {
+            logError(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    });
+    sharedOpts(temporal
+        .command("history <workflowId> [runId]")
+        .description("Show workflow event history")
+        .option("-n, --limit <n>", "Maximum events to show (default: 200)")
+        .option("-f, --follow", "Tail the history, waiting for new events until the workflow completes")
+        .option("--no-compact", "Show all events including WorkflowTask scheduling noise")
+        .option("-p, --show-payloads", "Decrypt and print activity inputs/outputs (reads TEMPORAL_ENCODING_KEY from the app's K8s secret via kubectl)")).action(async (workflowId, runId, opts) => {
+        try {
+            await showHistory(workflowId, runId, opts);
+        }
+        catch (err) {
+            logError(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    });
+    sharedOpts(temporal
+        .command("recover-conversation <workflowId> [runId]")
+        .description("Reconstruct an agent conversation transcript from durable Temporal history " +
+        "(for when the worker can no longer replay it). Requires the encoding key — " +
+        "reads TEMPORAL_ENCODING_KEY (or the app's K8s secret).")
+        .option("--out <path>", "Write the transcript to a file instead of stdout")
+        .option("--json", "Emit a structured { turns: [...] } JSON array instead of markdown")
+        .option("--snapshot", "Emit a store-ready conversation blob { conversationId, messages, artifacts, focus } " +
+        "with STRUCTURED ModelMessage[] (tool-call parts intact) for a full-fidelity backfill")).action(async (workflowId, runId, opts) => {
+        try {
+            await recoverConversation(workflowId, runId, opts);
+        }
+        catch (err) {
+            logError(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    });
+    sharedOpts(temporal
+        .command("capture-history <workflowId> [runId]")
+        .description("Capture a workflow's full history to a replay fixture JSON (proto3-JSON, " +
+        "DECRYPTED payloads) for LOCAL replay debugging. Requires the encoding key. " +
+        "Defaults to ~/.mesh/replay-histories/<workflowId>.json (outside any repo) — " +
+        "do NOT commit the output.")
+        .option("--out <path>", "Output path (default: ~/.mesh/replay-histories/<workflowId>.json; a non-gitignored " +
+        "path inside a git repo triggers a loud warning)")).action(async (workflowId, runId, opts) => {
+        try {
+            await captureHistory(workflowId, runId, opts);
+        }
+        catch (err) {
+            logError(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=temporal.js.map