agent-tempo 1.0.1

package/dist/activities/resolve.d.ts

@@ -0,0 +1,64 @@
+import { Client, WorkflowHandle } from '@temporalio/client';
+import { AttachmentPhase } from '../types';
+/**
+ * Resolve a session by player name.
+ * Lists all running session workflows and queries each for metadata.
+ * This avoids depending on custom search attributes which are eventually
+ * consistent and may be missing or stale.
+ *
+ * Shared by activity files (outbox, schedule-fire) and the tools layer.
+ *
+ * **Deadline (#336/#529):** the visibility iterator is bounded by
+ * `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On timeout,
+ * throws `VisibilityIteratorTimeoutError` rather than returning `null`
+ * — silent `null` on a partially-scanned set would be indistinguishable
+ * from "definitely not found," producing false "Player not found" errors
+ * upstream. Every existing caller wraps this in a try/catch (outbox
+ * activities, MCP tools' `defineTool` helper, CLI dev-verbs); the throw
+ * propagates as a retryable / user-visible "lookup timed out" rather
+ * than the misleading "player not found."
+ */
+export declare function resolveSession(client: Client, ensemble: string, playerName: string): Promise<WorkflowHandle | null>;
+/** Info returned for each session by scanEnsembleSessions. */
+export interface EnsembleSessionInfo {
+    workflowId: string;
+    playerId: string;
+    part: string;
+    hostname: string;
+    workDir: string;
+    gitRoot?: string;
+    gitBranch?: string;
+    isConductor: boolean;
+    agentType: string;
+    playerType?: string;
+    /**
+     * Attachment phase read from the `AgentTempoAttachmentState` search attribute.
+     * May be undefined for older workflows that predate the attachment lifecycle,
+     * or transiently while search attributes propagate.
+     */
+    phase?: AttachmentPhase;
+    /**
+     * #399 W1+W2 — monotonic message-activity counter from the session's
+     * `getActivityState` query (introduced in W2). Undefined when the
+     * session predates W2 or the query failed.
+     */
+    activityCount?: number;
+    /**
+     * #399 W1+W2 — ISO timestamp of the last activity-counter bump on the
+     * session. Undefined when the session predates W2 or the query failed.
+     */
+    lastActivityAt?: string;
+}
+/**
+ * Scan all running session workflows in an ensemble.
+ * Returns metadata + part for each session. Shared by the ensemble MCP tool
+ * and the Maestro refresh activity.
+ *
+ * **Deadline (#336/#529):** the iterator is bounded by
+ * `VISIBILITY_DEADLINES_MS.scanEnsembleSessions` (default 15s). On
+ * timeout, returns the partial result accumulated so far and emits a
+ * warn log. This site is **partial-tolerant by design** — the caller
+ * (maestro refresh, ensemble MCP tool) treats the result as a
+ * best-effort snapshot that the next tick / re-invocation will fill in.
+ */
+export declare function scanEnsembleSessions(client: Client, ensemble: string, log?: (...args: unknown[]) => void): Promise<EnsembleSessionInfo[]>;

package/dist/activities/resolve.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSession = resolveSession;
+exports.scanEnsembleSessions = scanEnsembleSessions;
+const search_attributes_1 = require("../utils/search-attributes");
+const signals_1 = require("../workflows/signals");
+const query_timeout_1 = require("../utils/query-timeout");
+const visibility_deadline_1 = require("../utils/visibility-deadline");
+/** Shared query for listing running session workflows. */
+const SESSION_LIST_QUERY = `WorkflowType = "agentSessionWorkflow" AND ExecutionStatus = "Running"`;
+/**
+ * Resolve a session by player name.
+ * Lists all running session workflows and queries each for metadata.
+ * This avoids depending on custom search attributes which are eventually
+ * consistent and may be missing or stale.
+ *
+ * Shared by activity files (outbox, schedule-fire) and the tools layer.
+ *
+ * **Deadline (#336/#529):** the visibility iterator is bounded by
+ * `VISIBILITY_DEADLINES_MS.resolveSession` (default 10s). On timeout,
+ * throws `VisibilityIteratorTimeoutError` rather than returning `null`
+ * — silent `null` on a partially-scanned set would be indistinguishable
+ * from "definitely not found," producing false "Player not found" errors
+ * upstream. Every existing caller wraps this in a try/catch (outbox
+ * activities, MCP tools' `defineTool` helper, CLI dev-verbs); the throw
+ * propagates as a retryable / user-visible "lookup timed out" rather
+ * than the misleading "player not found."
+ */
+async function resolveSession(client, ensemble, playerName) {
+    for await (const wf of (0, visibility_deadline_1.iterateWithDeadline)(client.workflow.list({ query: SESSION_LIST_QUERY }), visibility_deadline_1.VISIBILITY_DEADLINES_MS.resolveSession, 'resolveSession')) {
+        try {
+            const handle = client.workflow.getHandle(wf.workflowId);
+            // Issue #433 — bound the per-session metadata query so a wedged
+            // session worker can't hang the entire `resolveSession` lookup.
+            // The catch already treats failure as "skip this candidate".
+            const metadata = await (0, query_timeout_1.queryHandleWithTimeout)(handle, 'getMetadata');
+            if (metadata.ensemble === ensemble && metadata.playerId === playerName) {
+                return handle;
+            }
+        }
+        catch (err) {
+            // Re-throw deadline timeouts — callers that wrap us in try/catch
+            // already treat unknown throws as a soft "lookup failed" path,
+            // and the typed error name makes the failure mode legible in
+            // outbox logs / user-facing tool errors.
+            if ((0, visibility_deadline_1.isVisibilityTimeout)(err))
+                throw err;
+            // Workflow may have just completed, or worker is wedged (#433) — skip
+        }
+    }
+    return null;
+}
+/**
+ * Scan all running session workflows in an ensemble.
+ * Returns metadata + part for each session. Shared by the ensemble MCP tool
+ * and the Maestro refresh activity.
+ *
+ * **Deadline (#336/#529):** the iterator is bounded by
+ * `VISIBILITY_DEADLINES_MS.scanEnsembleSessions` (default 15s). On
+ * timeout, returns the partial result accumulated so far and emits a
+ * warn log. This site is **partial-tolerant by design** — the caller
+ * (maestro refresh, ensemble MCP tool) treats the result as a
+ * best-effort snapshot that the next tick / re-invocation will fill in.
+ */
+async function scanEnsembleSessions(client, ensemble, log = () => { }) {
+    const sessions = [];
+    try {
+        for await (const workflow of (0, visibility_deadline_1.iterateWithDeadline)(client.workflow.list({ query: SESSION_LIST_QUERY }), visibility_deadline_1.VISIBILITY_DEADLINES_MS.scanEnsembleSessions, 'scanEnsembleSessions')) {
+            try {
+                const handle = client.workflow.getHandle(workflow.workflowId);
+                // Issue #433 — bound the metadata + part queries so a single wedged
+                // session worker can't hang the entire ensemble scan. Outer
+                // try/catch treats any failure as "skip this row", so timeouts
+                // produce a partial-but-progressing scan instead of a stalled one.
+                const metadata = await (0, query_timeout_1.queryHandleWithTimeout)(handle, 'getMetadata');
+                if (metadata.ensemble !== ensemble)
+                    continue;
+                const part = await (0, query_timeout_1.queryHandleWithTimeout)(handle, 'getPart');
+                // Attachment phase lives in the `AgentTempoAttachmentState` search
+                // attribute (written by the workflow on every phase transition).
+                const phase = (0, search_attributes_1.getAttachmentPhase)(workflow);
+                // #399 W1+W2 — best-effort fetch of the session's monotonic
+                // activity counter. Wrapped in its own try/catch so a session
+                // predating W2 (no `getActivityState` query handler) doesn't
+                // disqualify the whole row. #433 — also timeout-bounded so a
+                // wedged W2 query handler doesn't stall the scan.
+                let activityCount;
+                let lastActivityAt;
+                try {
+                    const activity = await (0, query_timeout_1.queryHandleWithTimeout)(handle, signals_1.getActivityStateQuery);
+                    activityCount = activity.activityCount;
+                    lastActivityAt = activity.lastActivityAt;
+                }
+                catch {
+                    // Session predates W2 or the query is otherwise unavailable —
+                    // leave both fields undefined so the maestro contributes zero
+                    // to the tempo bucket for this player this cycle.
+                }
+                sessions.push({
+                    workflowId: workflow.workflowId,
+                    playerId: metadata.playerId,
+                    part,
+                    hostname: metadata.hostname,
+                    workDir: metadata.workDir,
+                    gitRoot: metadata.gitRoot,
+                    gitBranch: metadata.gitBranch,
+                    isConductor: metadata.isConductor,
+                    agentType: metadata.agentType || 'claude',
+                    playerType: metadata.playerType,
+                    phase,
+                    activityCount,
+                    lastActivityAt,
+                });
+            }
+            catch {
+                // Workflow may have just completed — skip it
+            }
+        }
+    }
+    catch (err) {
+        if ((0, visibility_deadline_1.isVisibilityTimeout)(err)) {
+            log(`scanEnsembleSessions: ${err.message} — returning partial (${sessions.length} sessions)`);
+        }
+        else {
+            throw err;
+        }
+    }
+    return sessions;
+}

package/dist/activities/schedule-fire.d.ts

@@ -0,0 +1,36 @@
+import { Client } from '@temporalio/client';
+export interface FireScheduleInput {
+    ensemble: string;
+    scheduleName: string;
+    message: string;
+    target: string;
+    createdBy: string;
+}
+export interface FireScheduleResult {
+    success: boolean;
+    error?: string;
+    /**
+     * #336/#529 — when `target === 'all'`, true if the visibility iterator
+     * hit its deadline before enumerating every running session. The
+     * caller (schedule workflow / TUI surface) renders a "partial
+     * delivery — scan timed out" notice rather than implying every
+     * player received the message.
+     */
+    timedOut?: boolean;
+    /** #336/#529 — entries actually scanned before deadline or completion. */
+    scanned?: number;
+}
+export interface ComputeNextCronInput {
+    cronExpression: string;
+    timezone?: string;
+}
+/** Activity interface — used by proxyActivities in the scheduler workflow. */
+export interface ScheduleActivities {
+    fireSchedule(input: FireScheduleInput): Promise<FireScheduleResult>;
+    computeNextCronFire(input: ComputeNextCronInput): Promise<string | null>;
+}
+/**
+ * Create the schedule-fire activity bound to a Temporal client.
+ * The returned object is registered with the worker as activities.
+ */
+export declare function createScheduleActivities(client: Client): ScheduleActivities;

package/dist/activities/schedule-fire.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createScheduleActivities = createScheduleActivities;
+const croner_1 = require("croner");
+const config_1 = require("../config");
+const resolve_1 = require("./resolve");
+const visibility_deadline_1 = require("../utils/visibility-deadline");
+/**
+ * Create the schedule-fire activity bound to a Temporal client.
+ * The returned object is registered with the worker as activities.
+ */
+function createScheduleActivities(client) {
+    return {
+        async computeNextCronFire(input) {
+            const job = new croner_1.Cron(input.cronExpression, { timezone: input.timezone || 'UTC' });
+            const next = job.nextRun();
+            return next ? next.toISOString() : null;
+        },
+        async fireSchedule(input) {
+            const { ensemble, scheduleName, message, target, createdBy } = input;
+            try {
+                const text = `[scheduled: ${scheduleName}] ${message}`;
+                // Handle target "all" — deliver to every active player except the conductor
+                if (target === 'all') {
+                    const query = `WorkflowType = "agentSessionWorkflow" AND ExecutionStatus = "Running"`;
+                    const failures = [];
+                    let delivered = 0;
+                    let scanned = 0;
+                    let timedOut = false;
+                    // #336/#529 — bound the visibility iterator. `target='all'` is
+                    // a structured-outcome site: a partial scan would silently
+                    // violate the "deliver to every player" semantic, so we carry
+                    // `timedOut` into the result.
+                    try {
+                        for await (const wf of (0, visibility_deadline_1.iterateWithDeadline)(client.workflow.list({ query }), visibility_deadline_1.VISIBILITY_DEADLINES_MS.fireScheduleAll, 'fireScheduleAll')) {
+                            scanned++;
+                            try {
+                                const handle = client.workflow.getHandle(wf.workflowId);
+                                const metadata = await handle.query('getMetadata');
+                                if (metadata.ensemble !== ensemble)
+                                    continue;
+                                if (metadata.isConductor)
+                                    continue; // skip conductor
+                                await handle.signal('receiveMessage', {
+                                    from: createdBy,
+                                    text,
+                                    isScheduled: true,
+                                    scheduleName,
+                                    responseRequested: false,
+                                });
+                                delivered++;
+                            }
+                            catch (err) {
+                                const msg = err instanceof Error ? err.message : String(err);
+                                failures.push(`${wf.workflowId}: ${msg}`);
+                            }
+                        }
+                    }
+                    catch (err) {
+                        if ((0, visibility_deadline_1.isVisibilityTimeout)(err)) {
+                            timedOut = true;
+                            // Mark the partial-delivery failure mode so the caller's
+                            // notification surface can describe it accurately.
+                            failures.push(`scan deadline (${err.deadlineMs}ms) exceeded after ${err.partialCount} entries`);
+                        }
+                        else {
+                            throw err;
+                        }
+                    }
+                    if (delivered === 0 && failures.length === 0) {
+                        await notifyFailure(client, ensemble, createdBy, scheduleName, target, 'No active players found in the ensemble.');
+                        return { success: false, error: 'No active players found', scanned, timedOut };
+                    }
+                    return {
+                        success: !timedOut && failures.length === 0,
+                        error: failures.length > 0
+                            ? (timedOut
+                                ? `Delivered to ${delivered} players, scan timed out before completion: ${failures.join('; ')}`
+                                : `Delivered to ${delivered} players, ${failures.length} failed: ${failures.join('; ')}`)
+                            : undefined,
+                        scanned,
+                        ...(timedOut ? { timedOut: true } : {}),
+                    };
+                }
+                // Resolve single target player by querying running session workflows
+                const handle = await (0, resolve_1.resolveSession)(client, ensemble, target);
+                if (!handle) {
+                    // Notify the creator (or conductor as fallback) about the failure
+                    await notifyFailure(client, ensemble, createdBy, scheduleName, target, `Player "${target}" not found — session may have been terminated.`);
+                    return { success: false, error: `No active session found for "${target}"` };
+                }
+                // Send cue signal with from set to the original creator's name
+                await handle.signal('receiveMessage', {
+                    from: createdBy,
+                    text,
+                    isScheduled: true,
+                    scheduleName,
+                    responseRequested: false,
+                });
+                return { success: true };
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                return { success: false, error: errorMsg };
+            }
+        },
+    };
+}
+/**
+ * Notify the schedule creator (or conductor as fallback) that delivery failed.
+ * This lets the creator's AI session decide whether to re-recruit the target.
+ */
+async function notifyFailure(client, ensemble, createdBy, scheduleName, target, reason) {
+    const failureText = `[scheduled: ${scheduleName}] Delivery to "${target}" failed — ${reason}`;
+    // Try the creator first
+    const creatorHandle = await (0, resolve_1.resolveSession)(client, ensemble, createdBy);
+    if (creatorHandle) {
+        try {
+            await creatorHandle.signal('receiveMessage', {
+                from: 'scheduler',
+                text: failureText,
+                isScheduled: true,
+                scheduleName,
+                responseRequested: false,
+            });
+            return;
+        }
+        catch {
+            // creator signal failed, fall through to conductor
+        }
+    }
+    // Fallback: notify the conductor
+    try {
+        const conductorId = (0, config_1.conductorWorkflowId)(ensemble);
+        const conductorHandle = client.workflow.getHandle(conductorId);
+        await conductorHandle.signal('receiveMessage', {
+            from: 'scheduler',
+            text: failureText,
+            isScheduled: true,
+            responseRequested: false,
+            scheduleName,
+        });
+    }
+    catch {
+        // Nobody available to notify — logged by the workflow
+    }
+}