npm - agent-tempo - Versions diffs - 1.0.1 → 1.2.0 - Mend

agent-tempo 1.0.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/CLAUDE.md +8 -2
package/dashboard/dist/assets/index-D6Xyje_n.js +62 -0
package/dashboard/dist/assets/index-D6Xyje_n.js.map +1 -0
package/dashboard/dist/index.html +1 -1
package/dashboard/package.json +1 -1
package/dist/activities/claude-stop.d.ts +21 -0
package/dist/activities/claude-stop.js +94 -0
package/dist/cli/commands.d.ts +39 -0
package/dist/cli/commands.js +83 -2
package/dist/cli/legacy-migration.js +8 -2
package/dist/cli/sa-preflight.d.ts +27 -3
package/dist/cli/sa-preflight.js +169 -9
package/dist/cli/startup.js +34 -8
package/dist/client/core.js +9 -0
package/dist/client/interface.d.ts +21 -0
package/dist/daemon.js +1 -0
package/dist/http/catalog.js +17 -3
package/dist/http/event-types.d.ts +41 -0
package/dist/http/orphans.d.ts +76 -0
package/dist/http/orphans.js +93 -0
package/dist/http/server.js +13 -0
package/dist/reconcile/orphans.d.ts +37 -27
package/dist/reconcile/orphans.js +93 -6
package/dist/tui/index.js +1 -0
package/dist/utils/bg-preflight.d.ts +25 -0
package/dist/utils/bg-preflight.js +154 -0
package/package.json +5 -4
package/dashboard/dist/assets/index-_5jV0Znu.js +0 -62
package/dashboard/dist/assets/index-_5jV0Znu.js.map +0 -1

package/dashboard/dist/index.html CHANGED Viewed

@@ -12,7 +12,7 @@
       rel="stylesheet"
       href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400;500;600;700&family=Instrument+Serif:ital@0;1&family=JetBrains+Mono:wght@400;500&display=swap"
     />
-    <script type="module" crossorigin src="/dashboard/assets/index-_5jV0Znu.js"></script>
+    <script type="module" crossorigin src="/dashboard/assets/index-D6Xyje_n.js"></script>
     <link rel="stylesheet" crossorigin href="/dashboard/assets/index-CB78ToNE.css">
   </head>
   <body>

package/dashboard/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "agent-tempo-dashboard",
   "private": true,
-  "version": "1.0.1",
+  "version": "1.2.0",
   "type": "module",
   "description": "Web dashboard for agent-tempo. Bundled into the npm package; served by the daemon at /dashboard/*.",
   "scripts": {

package/dist/activities/claude-stop.d.ts ADDED Viewed

@@ -0,0 +1,21 @@
+export interface ClaudeStopInput {
+    /** Supervisor's 8-char short id from `SessionMetadata.bgShortId`. */
+    shortId: string;
+    /** Custom claude binary path (defaults to `'claude'` on PATH). */
+    claudeBin?: string;
+}
+export interface ClaudeStopResult {
+    success: boolean;
+    /** One of `'stopped'` | `'already-gone'` | `'error'`. */
+    outcome: 'stopped' | 'already-gone' | 'error';
+    /** Populated on `outcome === 'error'` — the raw stderr/stdout snippet for diagnostics. */
+    detail?: string;
+    /** Exit code from `claude stop`. Undefined on spawn-side failure. */
+    exitCode?: number;
+}
+/**
+ * Invoke `claude stop <shortId>` synchronously. Never throws — returns a
+ * structured `ClaudeStopResult` the workflow can act on. Routes through
+ * `resolveClaudePath` so the `claudeBin` config option is honoured.
+ */
+export declare function claudeStop(input: ClaudeStopInput): Promise<ClaudeStopResult>;

package/dist/activities/claude-stop.js ADDED Viewed

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeStop = claudeStop;
+/**
+ * #596 / ADR 0016 — `claude stop <shortId>` per-host activity.
+ *
+ * `claude --bg` hands the session to Anthropic's per-user Claude Code
+ * supervisor. We don't own the PID anymore (the supervisor does), so the
+ * existing `hard-terminate` PID-scan helper would always return
+ * `strategy: 'none'` and leak the supervisor job. Instead, ask the
+ * supervisor to stop the job via its documented CLI verb.
+ *
+ * **Routing**: registered on the per-host activity queue
+ * (`agent-tempo-{hostname}`) so the `claude` CLI runs on the same machine
+ * the supervisor lives on. The workflow proxy in `src/workflows/session.ts`
+ * picks the right host via `AgentTempoHostname` exactly the same way
+ * `hardTerminateAttachment` already does.
+ *
+ * **Idempotency**: `claude stop` exits 1 with `No job matching '<id>'` when
+ * the job is already gone. We classify that as success — destroy must be
+ * idempotent and a re-run of an already-stopped session is a normal flow.
+ * Any other non-zero exit (network/socket failure, supervisor itself wedged,
+ * unexpected CLI shape) is reported as `success: false` so the workflow's
+ * destroy path can fall back to the existing `hardTerminateAttachment`
+ * PID-scan as defense in depth.
+ *
+ * **Timing**: 15-second timeout. The supervisor responds in <100ms on a
+ * healthy host, but Windows process-spawn overhead and antivirus scanners
+ * can stretch the worst case. 15s leaves slack without holding up destroy.
+ */
+const child_process_1 = require("child_process");
+const activity_1 = require("@temporalio/activity");
+const spawn_1 = require("../spawn");
+const log = (...args) => console.error('[agent-tempo:claude-stop]', ...args);
+/**
+ * Validate the supervisor short id before shelling out. Anthropic uses
+ * lowercase hex from the full UUID's first 8 chars; reject anything else
+ * to avoid passing user-influenced strings into argv.
+ */
+function isValidShortId(s) {
+    return typeof s === 'string' && /^[0-9a-f]{8}$/.test(s);
+}
+/**
+ * Invoke `claude stop <shortId>` synchronously. Never throws — returns a
+ * structured `ClaudeStopResult` the workflow can act on. Routes through
+ * `resolveClaudePath` so the `claudeBin` config option is honoured.
+ */
+async function claudeStop(input) {
+    const { shortId, claudeBin } = input;
+    if (!isValidShortId(shortId)) {
+        throw activity_1.ApplicationFailure.nonRetryable(`claudeStop: invalid shortId "${shortId}" (must be 8 lowercase hex chars). ` +
+            `This indicates corrupt SessionMetadata.bgShortId — check the recruit path.`);
+    }
+    const bin = (0, spawn_1.resolveClaudePath)(claudeBin);
+    let result;
+    try {
+        result = (0, child_process_1.spawnSync)(bin, ['stop', shortId], {
+            encoding: 'utf8',
+            timeout: 15_000,
+            shell: process.platform === 'win32',
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        log(`claude stop ${shortId} failed to launch: ${detail}`);
+        return { success: false, outcome: 'error', detail };
+    }
+    if (result.error) {
+        log(`claude stop ${shortId} spawn error: ${result.error.message}`);
+        return { success: false, outcome: 'error', detail: result.error.message };
+    }
+    const exitCode = result.status ?? -1;
+    const stderr = (result.stderr || '').toString();
+    const stdout = (result.stdout || '').toString();
+    const combined = `${stderr}\n${stdout}`.trim();
+    if (exitCode === 0) {
+        log(`claude stop ${shortId} → stopped`);
+        return { success: true, outcome: 'stopped', exitCode };
+    }
+    // Anthropic's "already gone" signal — exit 1 with `No job matching '<id>'`
+    // somewhere in the combined output. Match case-insensitively to absorb
+    // small phrasing drift across CLI versions.
+    if (/no job matching/i.test(combined)) {
+        log(`claude stop ${shortId} → already-gone (exit ${exitCode}, idempotent success)`);
+        return { success: true, outcome: 'already-gone', exitCode };
+    }
+    log(`claude stop ${shortId} → error (exit ${exitCode}): ${combined || '(no output)'}`);
+    return {
+        success: false,
+        outcome: 'error',
+        exitCode,
+        detail: combined || `exit ${exitCode} with no output`,
+    };
+}

package/dist/cli/commands.d.ts CHANGED Viewed

@@ -132,6 +132,45 @@ export type StopTemporalResult = {
  * profile collateral damage.
  */
 export declare function stopTemporalServer(opts: StopTemporalServerOpts): StopTemporalResult;
+/**
+ * Minimal child handle {@link startTemporalForDestroy} needs — `ChildProcess`
+ * satisfies it. Kept narrow so unit tests can inject a fake without spawning.
+ *
+ * @internal
+ */
+export interface SpawnedTemporalChild {
+    kill(): void;
+    unref(): void;
+}
+/**
+ * Dependency seam for {@link startTemporalForDestroy} — production callers
+ * pass nothing and get the real spawn + reachability probe. Tests inject
+ * stubs plus a tiny `pollDelayMs` so the readiness loop runs instantly.
+ *
+ * @internal
+ */
+export interface StartTemporalForDestroyDeps {
+    /** Readiness probe — defaults to {@link isTemporalReachable} for `config`. */
+    isReachable?: () => Promise<boolean>;
+    /** Spawn hook — defaults to a detached `temporal server start-dev`. */
+    spawn?: () => SpawnedTemporalChild;
+    /** Readiness poll attempts. Default 20. */
+    attempts?: number;
+    /** Delay between readiness polls, ms. Default 500 (→ 20×500ms = 10s). */
+    pollDelayMs?: number;
+}
+/**
+ * Start a temporary Temporal dev server just long enough for `down --destroy`
+ * to terminate workflows when Temporal happened to be down. Polls for
+ * readiness; on timeout it kills the child it spawned so `down` never leaves
+ * a stray Temporal process booting in the background. Exported for unit
+ * tests — production callers pass only `config`.
+ *
+ * @internal
+ */
+export declare function startTemporalForDestroy(config: Config, deps?: StartTemporalForDestroyDeps): Promise<{
+    started: boolean;
+}>;
 export declare function down(opts: DownOpts): Promise<void>;
 interface AgentTypesCommandOpts {
     subcommand?: string;

package/dist/cli/commands.js CHANGED Viewed

@@ -40,6 +40,7 @@ exports.up = up;
 exports.formatScheduleRecurrence = formatScheduleRecurrence;
 exports.lineupScheduleToEntry = lineupScheduleToEntry;
 exports.stopTemporalServer = stopTemporalServer;
+exports.startTemporalForDestroy = startTemporalForDestroy;
 exports.down = down;
 exports.agentTypesCommand = agentTypesCommand;
 exports.broadcast = broadcast;
@@ -1547,6 +1548,44 @@ function stopTemporalServer(opts) {
         return { action: 'failed', error: err };
     }
 }
+/**
+ * Start a temporary Temporal dev server just long enough for `down --destroy`
+ * to terminate workflows when Temporal happened to be down. Polls for
+ * readiness; on timeout it kills the child it spawned so `down` never leaves
+ * a stray Temporal process booting in the background. Exported for unit
+ * tests — production callers pass only `config`.
+ *
+ * @internal
+ */
+async function startTemporalForDestroy(config, deps = {}) {
+    const attempts = deps.attempts ?? 20;
+    const pollDelayMs = deps.pollDelayMs ?? 500;
+    const isReachable = deps.isReachable ?? (() => isTemporalReachable(config));
+    const spawn = deps.spawn ?? (() => {
+        (0, fs_1.mkdirSync)(config_1.AGENT_TEMPO_HOME, { recursive: true });
+        const port = config.temporalAddress.split(':')[1] || '7233';
+        return (0, child_process_1.spawn)('temporal', [
+            'server', 'start-dev',
+            '--port', port,
+            '--db-filename', DEFAULT_DB_PATH,
+        ], { detached: true, stdio: 'ignore' });
+    });
+    const child = spawn();
+    child.unref();
+    for (let i = 0; i < attempts; i++) {
+        await new Promise(r => setTimeout(r, pollDelayMs));
+        if (await isReachable())
+            return { started: true };
+    }
+    // Timed out. The detached child may still be booting and would come up
+    // orphaned moments after we give up — kill the process we spawned so
+    // `down` doesn't leave a stray Temporal server behind.
+    try {
+        child.kill();
+    }
+    catch { /* already exited */ }
+    return { started: false };
+}
 async function down(opts) {
     const config = (0, config_1.getConfig)(opts);
     out.heading('agent-tempo teardown');
@@ -1555,7 +1594,35 @@ async function down(opts) {
         : `  Stopping daemon + Temporal. Workflows stay parked for the next ${out.dim('agent-tempo up')}.`);
     // Step 1 (destroy mode only): enumerate + terminate workflows across every
     // ensemble, after a typed confirmation showing the user what's at stake.
-    const temporalUp = await isTemporalReachable(config);
+    let temporalUp = await isTemporalReachable(config);
+    // `--destroy` can only terminate workflows while Temporal is reachable.
+    // Workflow state lives durably on disk in ~/.agent-tempo/, so if Temporal
+    // happens to be down when the user runs `down --destroy`, skipping the
+    // destroy step here silently leaves every workflow to be resurrected the
+    // next time anything starts the daemon (an `up`, a `status`, or the TUI).
+    // To make `--destroy` actually mean it, start Temporal temporarily just
+    // long enough to run the terminations — Step 4 below stops it again.
+    let startedTemporalForDestroy = false;
+    if (opts.destroy && !temporalUp) {
+        if (!temporalCliExists()) {
+            out.warn('temporal CLI not found — cannot destroy workflows; they will persist on disk.');
+        }
+        else {
+            out.log(`  ${out.dim('...')} Temporal is down — starting it temporarily to destroy workflows...`);
+            const { started } = await startTemporalForDestroy(config);
+            if (started) {
+                temporalUp = true;
+                startedTemporalForDestroy = true;
+                out.success('Temporal started for cleanup');
+            }
+            else {
+                out.warn('Could not start Temporal within 10s — workflows may survive teardown. ' +
+                    'Re-run `agent-tempo down --destroy` once Temporal is up. ' +
+                    'A stray Temporal process may have been left starting — check with ' +
+                    '`agent-tempo status` and stop it manually if one is still running.');
+            }
+        }
+    }
     if (opts.destroy && temporalUp) {
         try {
             const connection = await (0, connection_1.createTemporalConnection)(config);
@@ -1625,6 +1692,15 @@ async function down(opts) {
                         const confirmed = await typedConfirmPrompt(`  This terminates every workflow (${totalTargets}) and cannot be undone.`, 'destroy');
                         if (!confirmed) {
                             out.log('Aborted.');
+                            // We may have started Temporal solely to run this destroy.
+                            // Aborting at the confirmation prompt must not leave that
+                            // server orphaned — stop it before the hard exit. We own it
+                            // outright, so force past the cross-profile guard.
+                            if (startedTemporalForDestroy) {
+                                if (stopTemporalServer({ killSharedTemporal: true }).action === 'killed') {
+                                    out.log(`  ${out.dim('Temporal server stopped')}`);
+                                }
+                            }
                             process.exit(0);
                         }
                     }
@@ -1676,7 +1752,12 @@ async function down(opts) {
     // skips the kill when the OPPOSITE profile is likely active;
     // `--kill-shared-temporal` is the explicit opt-in to override.
     if (temporalUp) {
-        const result = stopTemporalServer({ killSharedTemporal: opts.killSharedTemporal });
+        // When we started Temporal ourselves just for the destroy step, always
+        // stop it again — the cross-profile guard is about not killing a server
+        // the *other* profile owns, but this one we own outright.
+        const result = stopTemporalServer({
+            killSharedTemporal: opts.killSharedTemporal || startedTemporalForDestroy,
+        });
         switch (result.action) {
             case 'killed':
                 out.success('Temporal server stopped');

package/dist/cli/legacy-migration.js CHANGED Viewed

@@ -55,10 +55,16 @@ exports.formatMigrationResult = formatMigrationResult;
  *   5. **Partial-copy resume.** Per-file SHA-256 in the marker — re-running
  *      a partially-completed run finishes only the missing/changed files.
  *   6. **Files copied.** Allowlist — `config.json`, `.bootstrap-cache.json`,
- *      any `*.yaml` user-stashed lineup files, plus subdirs `lineups/`,
+ *      any `*.yaml` user-stashed lineup files, plus subdirs `ensembles/`,
  *      `state/`, `coat-check/` (forward-compat — fine if absent). The
  *      volatile runtime trio (`daemon.pid`, `daemon.port`, `daemon.log`)
  *      is intentionally skipped — let the daemon recreate them.
+ *      (Historical note: the original brief named the lineup subdir
+ *      `lineups/`, but the actual on-disk name has always been
+ *      `ensembles/` — see `src/ensemble/{saver,loader}.ts`. The original
+ *      implementation copied the brief's typo verbatim, which silently
+ *      stranded user lineups across the v0.x → v1.x migration. Fixed by
+ *      pointing the allowlist at the real directory name.)
  *   7. **Volatile-state guard.** If `daemon.pid` is present in the legacy
  *      home (likely-running daemon), refuses unless `force: true`.
  *
@@ -80,7 +86,7 @@ const VOLATILE_FILES = new Set(['daemon.pid', 'daemon.port', 'daemon.log']);
 /** Allowlisted top-level files. `*.yaml` is matched as a glob. */
 const ALLOWLIST_FILES = new Set(['config.json', '.bootstrap-cache.json']);
 /** Allowlisted top-level subdirs (recursive copy). Forward-compat — fine if absent. */
-const ALLOWLIST_SUBDIRS = ['lineups', 'state', 'coat-check'];
+const ALLOWLIST_SUBDIRS = ['ensembles', 'state', 'coat-check'];
 function legacyHomeFor(profile, home) {
     return path.join(home, profile === 'dev' ? LEGACY_DEV_HOME_DIR_NAME : LEGACY_PROD_HOME_DIR_NAME);
 }

package/dist/cli/sa-preflight.d.ts CHANGED Viewed

@@ -6,10 +6,13 @@ export declare const REQUIRED_SEARCH_ATTRIBUTES: ReadonlyArray<{
 export interface SearchAttributePreflightOpts {
     temporalAddress: string;
     temporalNamespace: string;
+    /** API key for Temporal Cloud — triggers SDK-based probe when set. */
+    temporalApiKey?: string;
     /**
      * Optional test seam — given a namespace, return the set of search
      * attribute names that ARE currently registered. Defaults to
-     * {@link defaultProbeRegisteredAttributes} which shells out to
+     * {@link sdkProbeRegisteredAttributes} when `temporalApiKey` is set,
+     * otherwise {@link defaultProbeRegisteredAttributes} which shells out to
      * `temporal operator search-attribute list`.
      */
     probe?: (opts: {
@@ -35,15 +38,36 @@ export declare function defaultProbeRegisteredAttributes(opts: {
     temporalAddress: string;
     temporalNamespace: string;
 }): Promise<Set<string>>;
+/** Returns true if the address looks like a Temporal Cloud endpoint. */
+export declare function isTemporalCloud(address: string): boolean;
+/**
+ * SDK-based probe — uses the Temporal Client SDK to verify search attribute
+ * existence by issuing a visibility query. Works with Temporal Cloud API keys
+ * where the `temporal operator` CLI commands are unauthorized.
+ *
+ * Strategy: for each required attribute, issue `listWorkflowExecutions` with
+ * a query referencing that attribute. If the attribute is registered the query
+ * returns (possibly empty) results. If not registered, Temporal responds with
+ * INVALID_ARGUMENT containing "is not a valid search attribute".
+ */
+export declare function sdkProbeRegisteredAttributes(opts: {
+    temporalAddress: string;
+    temporalNamespace: string;
+    temporalApiKey?: string;
+}): Promise<Set<string>>;
 /**
  * Format the missing-SA error message. Paste-friendly: operators copy the
- * `temporal operator search-attribute create` block verbatim.
+ * registration commands verbatim. Cloud-aware: shows `tcld` commands for
+ * Temporal Cloud namespaces.
  */
-export declare function formatPreflightError(missing: ReadonlyArray<typeof REQUIRED_SEARCH_ATTRIBUTES[number]>, namespace: string, probeError?: string): string;
+export declare function formatPreflightError(missing: ReadonlyArray<typeof REQUIRED_SEARCH_ATTRIBUTES[number]>, namespace: string, probeError?: string, cloud?: boolean): string;
 /**
  * Verify all {@link REQUIRED_SEARCH_ATTRIBUTES} are registered on the
  * given namespace. Returns a structured result — callers decide whether
  * to log+continue (boot bootstrap step) or exit non-zero (daemon start).
+ *
+ * When `temporalApiKey` is set (or address is a Cloud endpoint), uses the
+ * SDK-based probe instead of shelling out to `temporal operator`.
  */
 export declare function verifySearchAttributes(opts: SearchAttributePreflightOpts): Promise<SearchAttributePreflightResult>;
 /**

package/dist/cli/sa-preflight.js CHANGED Viewed

@@ -1,7 +1,42 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REQUIRED_SEARCH_ATTRIBUTES = void 0;
 exports.defaultProbeRegisteredAttributes = defaultProbeRegisteredAttributes;
+exports.isTemporalCloud = isTemporalCloud;
+exports.sdkProbeRegisteredAttributes = sdkProbeRegisteredAttributes;
 exports.formatPreflightError = formatPreflightError;
 exports.verifySearchAttributes = verifySearchAttributes;
 exports.classifyRegistrationOutput = classifyRegistrationOutput;
@@ -29,6 +64,16 @@ exports.assertSearchAttributesOrExit = assertSearchAttributesOrExit;
  *   - `src/daemon.ts` boot path calls {@link verifySearchAttributes}
  *     directly to fail fast on `agent-tempo daemon start` before the worker
  *     tries to register workflows.
+ *
+ * Cloud support:
+ *   Temporal Cloud's operator gRPC service is not accessible with namespace
+ *   API keys, causing `temporal operator search-attribute list/create` to
+ *   fail with "Request unauthorized". When a Cloud namespace is detected
+ *   (address contains `.tmprl.cloud` or an API key is configured), the
+ *   preflight uses an SDK-based probe: issue a visibility query referencing
+ *   each required attribute — a registered attribute returns an empty result
+ *   set; an unregistered one throws INVALID_ARGUMENT. Registration
+ *   instructions surface `tcld` commands instead of `temporal operator`.
  */
 const child_process_1 = require("child_process");
 /** Single source of truth — must match `SEARCH_ATTRIBUTES` in `src/cli/startup.ts`. */
@@ -73,22 +118,123 @@ async function defaultProbeRegisteredAttributes(opts) {
     }
     return names;
 }
+/** Returns true if the address looks like a Temporal Cloud endpoint. */
+function isTemporalCloud(address) {
+    return address.includes('.tmprl.cloud');
+}
+/**
+ * Substrings Temporal servers use to signal "this search attribute is not
+ * registered". The exact wording varies across server versions and storage
+ * backends (e.g. 'is not a valid search attribute', 'is not defined',
+ * 'no mapping defined for the field'), so we match a set rather than a
+ * single phrase — a wording change must not cause the probe to misclassify
+ * an unregistered SA as an unexpected error and re-throw.
+ */
+const UNREGISTERED_SA_MARKERS = [
+    'is not a valid search attribute',
+    'is not defined',
+    'no mapping defined for the field',
+    'unknown or unindexed search attribute',
+];
+/** gRPC status code for INVALID_ARGUMENT. */
+const GRPC_INVALID_ARGUMENT = 3;
+/**
+ * Classify a visibility-query error as "search attribute not registered".
+ *
+ * A registered-but-empty attribute returns results; an unregistered one
+ * fails. Temporal reports the failure as gRPC INVALID_ARGUMENT — we key on
+ * that status code first (wording-independent) and fall back to known
+ * message substrings for transports/versions that don't surface a code.
+ */
+function isUnregisteredAttributeError(err) {
+    const msg = (err?.message || '').toLowerCase();
+    if (UNREGISTERED_SA_MARKERS.some((m) => msg.includes(m)))
+        return true;
+    // gRPC ServiceError exposes a numeric `code`; INVALID_ARGUMENT means the
+    // query referenced an attribute the namespace doesn't know about.
+    if (err?.code === GRPC_INVALID_ARGUMENT)
+        return true;
+    return false;
+}
+/**
+ * SDK-based probe — uses the Temporal Client SDK to verify search attribute
+ * existence by issuing a visibility query. Works with Temporal Cloud API keys
+ * where the `temporal operator` CLI commands are unauthorized.
+ *
+ * Strategy: for each required attribute, issue `listWorkflowExecutions` with
+ * a query referencing that attribute. If the attribute is registered the query
+ * returns (possibly empty) results. If not registered, Temporal responds with
+ * INVALID_ARGUMENT containing "is not a valid search attribute".
+ */
+async function sdkProbeRegisteredAttributes(opts) {
+    const { Connection } = await Promise.resolve().then(() => __importStar(require('@temporalio/client')));
+    const tls = opts.temporalApiKey ? true : undefined;
+    const conn = await Connection.connect({
+        address: opts.temporalAddress,
+        tls: tls,
+        apiKey: opts.temporalApiKey,
+    });
+    const registered = new Set();
+    try {
+        for (const attr of exports.REQUIRED_SEARCH_ATTRIBUTES) {
+            // The probe value only has to be syntactically valid for the
+            // attribute's type so the visibility query parses. We support
+            // Keyword (quoted string literal) and Bool (`true`) here — the only
+            // two types in REQUIRED_SEARCH_ATTRIBUTES. A new SA type would need
+            // its own literal form added below.
+            const testValue = attr.type === 'Bool' ? 'true' : '"__probe__"';
+            try {
+                await conn.workflowService.listWorkflowExecutions({
+                    namespace: opts.temporalNamespace,
+                    query: `${attr.name} = ${testValue}`,
+                    pageSize: 1,
+                });
+                registered.add(attr.name);
+            }
+            catch (err) {
+                if (isUnregisteredAttributeError(err)) {
+                    // Attribute not registered — don't add to set
+                }
+                else {
+                    // Unexpected error — re-throw
+                    throw err;
+                }
+            }
+        }
+    }
+    finally {
+        await conn.close();
+    }
+    return registered;
+}
 /**
  * Format the missing-SA error message. Paste-friendly: operators copy the
- * `temporal operator search-attribute create` block verbatim.
+ * registration commands verbatim. Cloud-aware: shows `tcld` commands for
+ * Temporal Cloud namespaces.
  */
-function formatPreflightError(missing, namespace, probeError) {
+function formatPreflightError(missing, namespace, probeError, cloud) {
     const lines = [];
     lines.push(`Required search attributes not registered on namespace '${namespace}'.`);
     if (probeError) {
         lines.push(`(Could not probe namespace state: ${probeError})`);
     }
     lines.push('');
-    lines.push('Run these commands once per Temporal namespace, then restart the daemon:');
-    lines.push('');
-    for (const attr of missing) {
-        lines.push(`  temporal operator search-attribute create ` +
-            `--name ${attr.name} --type ${attr.type} --namespace ${namespace}`);
+    if (cloud) {
+        lines.push('Register via tcld (Temporal Cloud CLI) or the Cloud UI, then restart the daemon:');
+        lines.push('');
+        const saFlags = missing.map((attr) => `--sa "${attr.name}=${attr.type}"`).join(' \\\n    ');
+        lines.push(`  tcld namespace search-attributes add --namespace ${namespace} \\\n    ${saFlags}`);
+        lines.push('');
+        lines.push('Or add them manually in the Temporal Cloud UI:');
+        lines.push(`  https://cloud.temporal.io → Namespaces → ${namespace} → Search Attributes`);
+    }
+    else {
+        lines.push('Run these commands once per Temporal namespace, then restart the daemon:');
+        lines.push('');
+        for (const attr of missing) {
+            lines.push(`  temporal operator search-attribute create ` +
+                `--name ${attr.name} --type ${attr.type} --namespace ${namespace}`);
+        }
     }
     lines.push('');
     lines.push('(See docs/ops/v1.0-migration.md for the full upgrade walkthrough.)');
@@ -98,9 +244,23 @@ function formatPreflightError(missing, namespace, probeError) {
  * Verify all {@link REQUIRED_SEARCH_ATTRIBUTES} are registered on the
  * given namespace. Returns a structured result — callers decide whether
  * to log+continue (boot bootstrap step) or exit non-zero (daemon start).
+ *
+ * When `temporalApiKey` is set (or address is a Cloud endpoint), uses the
+ * SDK-based probe instead of shelling out to `temporal operator`.
  */
 async function verifySearchAttributes(opts) {
-    const probe = opts.probe ?? defaultProbeRegisteredAttributes;
+    const cloud = isTemporalCloud(opts.temporalAddress) || !!opts.temporalApiKey;
+    const defaultProbe = cloud
+        ? () => sdkProbeRegisteredAttributes({
+            temporalAddress: opts.temporalAddress,
+            temporalNamespace: opts.temporalNamespace,
+            temporalApiKey: opts.temporalApiKey,
+        })
+        : () => defaultProbeRegisteredAttributes({
+            temporalAddress: opts.temporalAddress,
+            temporalNamespace: opts.temporalNamespace,
+        });
+    const probe = opts.probe ?? defaultProbe;
     let registered;
     let probeError;
     try {
@@ -121,7 +281,7 @@ async function verifySearchAttributes(opts) {
         ok: false,
         missing,
         probeError,
-        message: formatPreflightError(missing, opts.temporalNamespace, probeError),
+        message: formatPreflightError(missing, opts.temporalNamespace, probeError, cloud),
     };
 }
 /**

package/dist/cli/startup.js CHANGED Viewed

@@ -376,14 +376,40 @@ async function stepSearchAttrs(cache, config, now) {
     if (isCacheFresh(cache.steps.searchAttrs, TTL_24H, now)) {
         return { status: 'skipped', durationMs: 0 };
     }
-    const { result: outcome, durationMs } = await timed(() => {
-        // Per-attr classification via `registerSearchAttribute` (#605) —
-        // distinguishes `already-exists` (idempotent expected case) from real
-        // failures. Pre-#605 every non-zero exit was swallowed as "already
-        // registered", masking the SQLite dev-server's 10-Keyword-per-namespace
-        // cap and other genuine errors until a downstream workflow start failed
-        // with the confusing `INVALID_ARGUMENT: search attribute ... is not
-        // defined`.
+    const cloud = (0, sa_preflight_1.isTemporalCloud)(config.temporalAddress) || !!config.temporalApiKey;
+    const { result: outcome, durationMs } = await timed(async () => {
+        if (cloud) {
+            // For Temporal Cloud, use SDK probe to verify SAs are present.
+            // Registration must be done via tcld or the Cloud UI — we cannot
+            // use `temporal operator search-attribute create`.
+            try {
+                const registered = await (0, sa_preflight_1.sdkProbeRegisteredAttributes)({
+                    temporalAddress: config.temporalAddress,
+                    temporalNamespace: config.temporalNamespace,
+                    temporalApiKey: config.temporalApiKey,
+                });
+                const missing = sa_preflight_1.REQUIRED_SEARCH_ATTRIBUTES.filter((a) => !registered.has(a.name));
+                if (missing.length > 0) {
+                    const saFlags = missing.map((a) => `--sa "${a.name}=${a.type}"`).join(' ');
+                    return {
+                        status: 'failed',
+                        durationMs: 0,
+                        detail: `${missing.length} search attribute(s) not registered on Temporal Cloud.\n` +
+                            `  Register via: tcld namespace search-attributes add --namespace ${config.temporalNamespace} ${saFlags}\n` +
+                            `  Or add them in the Cloud UI: https://cloud.temporal.io`,
+                    };
+                }
+                return { status: 'ok', durationMs: 0 };
+            }
+            catch (err) {
+                return {
+                    status: 'failed',
+                    durationMs: 0,
+                    detail: `SDK probe failed: ${err?.message || err}`,
+                };
+            }
+        }
+        // Self-hosted path: per-attr classification via `registerSearchAttribute` (#605)
         const failures = [];
         for (const attr of sa_preflight_1.REQUIRED_SEARCH_ATTRIBUTES) {
             const r = (0, sa_preflight_1.registerSearchAttribute)(attr, config.temporalAddress, config.temporalNamespace);