@stigmer/server 3.14.0-dev.20260910084630

package/src/temporal/schedule/config.ts

@@ -0,0 +1,186 @@
+/**
+ * Schedule-clock configuration — ports
+ * pkg/domain/schedule/temporal/config.go.
+ *
+ * Environment variables deliberately share the STIGMER_SCHEDULES_* names
+ * with the cloud edition, so test harnesses and runbooks use one
+ * vocabulary. There is deliberately NO interval-floor knob: the floor is a
+ * platform guardrail for a shared metered system, enforced by cloud's
+ * pre-persist probe; OSS is one user on their own machine and has no probe
+ * (DD-015 D-A) — a present-but-ignored knob would be a lie.
+ *
+ * Config lives with the clock, not the domain (sub-project decision 1,
+ * owner-ratified): every reader is clock-side — the agentexecution
+ * precedent of a domain-local config was driven by a domain-step consumer
+ * (oss#397) that schedule does not have.
+ */
+
+export class ScheduleTemporalConfig {
+  constructor(
+    /**
+     * Task queue for the tick workflow and its activities. Dedicated (not
+     * the agent-execution queue) so a spanning tick can never starve agent
+     * executions. Default: schedule_stigmer.
+     */
+    readonly stigmerQueue: string,
+    /**
+     * Baked into every artifact's policy: how far back Temporal fires
+     * missed ticks after downtime (the laptop that slept through 9am).
+     * Default: 60.
+     */
+    readonly catchupWindowMinutes: number,
+    /**
+     * The artifact's baked workflow run timeout — a backstop, not policy
+     * (the tracking budget is the policy). Default: 24.
+     */
+    readonly tickRunTimeoutHours: number,
+    /** The auto-pause threshold (DD-008 D7). Default: 5. */
+    readonly maxConsecutiveFailures: number,
+    /**
+     * One fire's tracking budget — under overlap SKIP, literally the
+     * maximum time one hung run may silence a schedule. Clamped at fire
+     * time (resolvedRunTrackingTimeoutMinutes). Default: 60.
+     */
+    readonly runTrackingTimeoutMinutes: number,
+    /**
+     * Gates the periodic convergence pass (the reconnect-triggered pass
+     * always runs — it is correctness, not hygiene, on an ephemeral dev
+     * server). Default: true.
+     */
+    readonly reconciliationEnabled: boolean,
+    /** The periodic pass cadence. Default: 5. */
+    readonly reconciliationIntervalMinutes: number,
+    /**
+     * Bounds each scheduled run's tool rounds (0 disables the bound). An
+     * unattended runaway burns the user's own API budget with nobody
+     * watching — worse than an interactive one. Default: 20 (the cloud
+     * profile's value).
+     */
+    readonly executionProfileMaxToolRounds: number,
+    /**
+     * Bounds each scheduled run's spend, enforced by the shared runner
+     * (0 disables). Default: 1.00.
+     */
+    readonly executionProfileMaxCostUsd: number,
+    /**
+     * Bounds the fire ledger (DD-017 D-7): rows recorded earlier than this
+     * are pruned by the reconciliation pass. Default: 90 (a quarter of
+     * monthly reminder cycles — run history is a product surface, not
+     * delivery plumbing).
+     */
+    readonly runHistoryRetentionDays: number,
+  ) {}
+
+  /**
+   * Clamps the tracking budget to at least 1 minute and at least one hour
+   * inside the baked artifact run timeout — the cloud edition's exact
+   * clamp, so a misconfigured budget cannot outlive the tick that carries
+   * it (Go ResolvedRunTrackingTimeoutMinutes).
+   */
+  resolvedRunTrackingTimeoutMinutes(): number {
+    let ceiling = (this.tickRunTimeoutHours - 1) * 60;
+    if (ceiling < 1) {
+      ceiling = 1;
+    }
+    let resolved = this.runTrackingTimeoutMinutes;
+    if (resolved > ceiling) {
+      resolved = ceiling;
+    }
+    if (resolved < 1) {
+      resolved = 1;
+    }
+    return resolved;
+  }
+
+  /**
+   * Floors the pause threshold at 1 — a zero/negative threshold would
+   * pause on configuration, not on failure (Go
+   * ResolvedMaxConsecutiveFailures).
+   */
+  resolvedMaxConsecutiveFailures(): number {
+    return this.maxConsecutiveFailures < 1 ? 1 : this.maxConsecutiveFailures;
+  }
+
+  /**
+   * Floors the fire-ledger retention at 1 day — zero/negative would prune
+   * history as it lands (Go ResolvedRunHistoryRetentionDays).
+   */
+  resolvedRunHistoryRetentionDays(): number {
+    return this.runHistoryRetentionDays < 1 ? 1 : this.runHistoryRetentionDays;
+  }
+
+  /**
+   * Floors the periodic-pass cadence at 1 minute. Go has no clamp here and
+   * time.NewTicker(0) PANICS the process; a zero interval through
+   * setInterval would instead hot-loop full-table reconciliation passes
+   * silently — the worse failure mode. The floor follows this file's
+   * sibling clamps and is a disclosed divergence (crash → clamp) on a
+   * misconfiguration no healthy deployment carries.
+   */
+  resolvedReconciliationIntervalMinutes(): number {
+    return this.reconciliationIntervalMinutes < 1
+      ? 1
+      : this.reconciliationIntervalMinutes;
+  }
+}
+
+/** Loads configuration from environment variables (Go LoadConfig). */
+export function newScheduleConfigFromEnv(): ScheduleTemporalConfig {
+  return new ScheduleTemporalConfig(
+    getEnv("TEMPORAL_SCHEDULE_STIGMER_TASK_QUEUE", "schedule_stigmer"),
+    getEnvInt("STIGMER_SCHEDULES_CATCHUP_WINDOW_MINUTES", 60),
+    getEnvInt("STIGMER_SCHEDULES_TICK_RUN_TIMEOUT_HOURS", 24),
+    getEnvInt("STIGMER_SCHEDULES_MAX_CONSECUTIVE_FAILURES", 5),
+    getEnvInt("STIGMER_SCHEDULES_RUN_TRACKING_TIMEOUT_MINUTES", 60),
+    getEnvBool("STIGMER_SCHEDULES_RECONCILIATION_ENABLED", true),
+    getEnvInt("STIGMER_SCHEDULES_RECONCILIATION_INTERVAL_MINUTES", 5),
+    getEnvInt("STIGMER_SCHEDULES_EXECUTION_PROFILE_MAX_TOOL_ROUNDS", 20),
+    getEnvFloat("STIGMER_SCHEDULES_EXECUTION_PROFILE_MAX_COST_USD", 1.0),
+    getEnvInt("STIGMER_SCHEDULES_RUN_HISTORY_RETENTION_DAYS", 90),
+  );
+}
+
+function getEnv(key: string, defaultValue: string): string {
+  const value = process.env[key];
+  return value !== undefined && value !== "" ? value : defaultValue;
+}
+
+/**
+ * Go strconv.Atoi parity: only a plain (optionally signed) integer parses;
+ * anything else silently keeps the default, exactly Go's getEnvInt.
+ */
+function getEnvInt(key: string, defaultValue: number): number {
+  const value = process.env[key];
+  if (value === undefined || value === "" || !/^[+-]?\d+$/.test(value)) {
+    return defaultValue;
+  }
+  return Number.parseInt(value, 10);
+}
+
+/**
+ * Go strconv.ParseBool parity: exactly 1/t/T/TRUE/true/True and the 0/f
+ * family parse; anything else keeps the default.
+ */
+function getEnvBool(key: string, defaultValue: boolean): boolean {
+  const value = process.env[key];
+  if (value === undefined || value === "") {
+    return defaultValue;
+  }
+  if (["1", "t", "T", "TRUE", "true", "True"].includes(value)) {
+    return true;
+  }
+  if (["0", "f", "F", "FALSE", "false", "False"].includes(value)) {
+    return false;
+  }
+  return defaultValue;
+}
+
+/** Go strconv.ParseFloat parity: a finite float parses, else the default. */
+function getEnvFloat(key: string, defaultValue: number): number {
+  const value = process.env[key];
+  if (value === undefined || value === "") {
+    return defaultValue;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : defaultValue;
+}

package/src/temporal/schedule/model-pinning.ts

@@ -0,0 +1,47 @@
+/**
+ * The unattended model-pinning rule — ports
+ * pkg/domain/schedule/temporal/modelpinning.go (stigmer/stigmer#362).
+ *
+ * A schedule whose fires would run the CURSOR harness must pin a model: an
+ * empty model there selects Auto, whose price variant follows the provider
+ * ACCOUNT's out-of-band default speed setting — nobody at a 3 AM fire is
+ * watching a rate change. The native harness is exempt on purpose: an
+ * empty model resolves to the platform's own registry-priced default at an
+ * explicitly requested tier — deterministic, nothing to pin.
+ *
+ * Only an EXPLICIT cursor harness trips the rule in this edition: an unset
+ * harness resolves to the OSS platform default (native), so there is no
+ * cursor path to guard. The cloud edition additionally judges its
+ * configured default harness (cursor there) — same contract, each
+ * edition's own default-harness truth (the DD-015 divergence posture).
+ *
+ * Evaluated at write time (the controller's model-pinning validator
+ * delegates here) AND as the run starter's launch backstop, so rows
+ * written before the rule existed refuse at fire time instead of running
+ * mispriced. Pure module (no node built-ins): the domain validator imports
+ * it across the domain→clock boundary, exactly Go's controller →
+ * scheduletemporal edge.
+ */
+import type { ScheduleSpec } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/spec_pb";
+import { Harness } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+
+/**
+ * Returns the refusal copy, or "" when the fire is allowed (Go
+ * ScheduleModelPinningRefusal — the copy is cross-edition byte contract).
+ */
+export function scheduleModelPinningRefusal(
+  spec: ScheduleSpec | undefined,
+): string {
+  const agent = spec?.target.case === "agent" ? spec.target.value : undefined;
+  if (agent?.harness !== Harness.CURSOR) {
+    return "";
+  }
+  if ((agent.runConfig?.modelName ?? "").trim() !== "") {
+    return "";
+  }
+  return (
+    "spec.agent.run_config.model_name must name a pinned model when the run would use " +
+    "the Cursor harness — with no pinned model Cursor runs Auto, whose price variant " +
+    "follows the provider account's out-of-band default speed setting (stigmer/stigmer#362)"
+  );
+}

package/src/temporal/schedule/names.ts

@@ -0,0 +1,168 @@
+/**
+ * Schedule-clock Temporal wire identifiers and the tick's outcome
+ * vocabulary — ports the constants of pkg/domain/schedule/temporal
+ * (artifact.go, tick_activities.go).
+ *
+ * Every value here is a byte-pinned cross-repo wire constant: the cloud
+ * Java ScheduleArtifact, the integration harness's ScheduleInspector, and
+ * both server editions address artifacts, workflows, and activities by
+ * these exact strings — changing one on any side strands every existing
+ * artifact. The outcome vocabulary rides Temporal's JSON data converter
+ * into recorded histories, so the STRING VALUES and the RunStart /
+ * FailureRecorded FIELD NAMES are replay contract too.
+ *
+ * Imported by BOTH the workflow bundle and host code — no node built-ins,
+ * no framework imports (the workflow-bundle import discipline).
+ */
+
+/**
+ * The tick workflow's registered type and the artifact-id prefix's stem
+ * (Go TickWorkflowType). The artifact's baked action starts this exact
+ * type name — a rename would fail every fire with "workflow type not
+ * found".
+ */
+export const TICK_WORKFLOW_TYPE = "schedule/tick";
+
+/**
+ * Prefixes each Schedule resource's Temporal Schedule artifact id:
+ * schedule/tick/{scheduleResourceId} (Go TickIDPrefix).
+ */
+export const TICK_ID_PREFIX = `${TICK_WORKFLOW_TYPE}/`;
+
+/**
+ * The cloud write-path's throwaway fire-time probes (Go probeIDPrefix).
+ * OSS never creates probes (no pre-persist probe — DD-015 D-A), but the
+ * reconciler skips the prefix defensively so a shared/dev namespace never
+ * gets its probes treated as tick orphans.
+ */
+export const PROBE_ID_PREFIX = "schedule/probe/";
+
+/** The Temporal Schedule artifact id for a Schedule resource id. */
+export function artifactId(scheduleResourceId: string): string {
+  return TICK_ID_PREFIX + scheduleResourceId;
+}
+
+/** Inverts artifactId. */
+export function resourceIdOf(artifactIdValue: string): string {
+  return artifactIdValue.startsWith(TICK_ID_PREFIX)
+    ? artifactIdValue.slice(TICK_ID_PREFIX.length)
+    : artifactIdValue;
+}
+
+// ─── Activity names ─────────────────────────────────────────────────────
+// Slash-namespaced like the platform's other Go-owned system activities,
+// registered by the schedule worker under these exact names.
+
+export const RECORD_TICK_ACTIVITY_NAME = "stigmer/schedule/record-tick";
+export const START_SCHEDULED_RUN_ACTIVITY_NAME = "stigmer/schedule/start-run";
+export const POLL_EXECUTION_PHASE_ACTIVITY_NAME =
+  "stigmer/schedule/poll-phase";
+export const RECORD_SUCCESSFUL_RUN_ACTIVITY_NAME =
+  "stigmer/schedule/record-success";
+export const RECORD_FAILED_RUN_ACTIVITY_NAME =
+  "stigmer/schedule/record-failure";
+
+// ─── The tick's outcome vocabulary ──────────────────────────────────────
+// String-typed so the JSON data converter serializes them stably across
+// releases; the VALUES mirror the cloud edition's enums name-for-name
+// (one runbook, two editions) — Go tick_activities.go.
+
+/** recordTick's verdict on whether this fire proceeds (Go TickOutcome). */
+export type TickOutcome =
+  | "FIRED"
+  | "SKIPPED_DELETED"
+  | "SKIPPED_DISABLED"
+  | "SKIPPED_AUTO_PAUSED";
+
+export const TICK_FIRED = "FIRED" satisfies TickOutcome;
+export const TICK_SKIPPED_DELETED = "SKIPPED_DELETED" satisfies TickOutcome;
+export const TICK_SKIPPED_DISABLED = "SKIPPED_DISABLED" satisfies TickOutcome;
+export const TICK_SKIPPED_AUTO_PAUSED = "SKIPPED_AUTO_PAUSED" satisfies TickOutcome;
+
+/** startScheduledRun's verdict on the run start (Go RunOutcome). */
+export type RunOutcome =
+  | "STARTED"
+  | "ALREADY_STARTED"
+  | "SKIPPED"
+  | "TARGET_MISSING"
+  | "REFUSED";
+
+export const RUN_STARTED = "STARTED" satisfies RunOutcome;
+export const RUN_ALREADY_STARTED = "ALREADY_STARTED" satisfies RunOutcome;
+export const RUN_SKIPPED = "SKIPPED" satisfies RunOutcome;
+export const RUN_TARGET_MISSING = "TARGET_MISSING" satisfies RunOutcome;
+export const RUN_REFUSED = "REFUSED" satisfies RunOutcome;
+
+/** The tracked execution's observed phase class (Go RunPhase). */
+export type RunPhase =
+  | "RUNNING"
+  | "COMPLETED"
+  | "FAILED"
+  | "CANCELLED"
+  | "TERMINATED"
+  | "GONE";
+
+export const PHASE_RUNNING = "RUNNING" satisfies RunPhase;
+export const PHASE_COMPLETED = "COMPLETED" satisfies RunPhase;
+export const PHASE_FAILED = "FAILED" satisfies RunPhase;
+export const PHASE_CANCELLED = "CANCELLED" satisfies RunPhase;
+export const PHASE_TERMINATED = "TERMINATED" satisfies RunPhase;
+export const PHASE_GONE = "GONE" satisfies RunPhase;
+
+/** Which path fed the streak, for the log line (Go FailureKind). */
+export type FailureKind = "START_FAILED" | "RUN_FAILED" | "RUN_TIMED_OUT";
+
+export const FAILURE_START_FAILED = "START_FAILED" satisfies FailureKind;
+export const FAILURE_RUN_FAILED = "RUN_FAILED" satisfies FailureKind;
+export const FAILURE_RUN_TIMED_OUT = "RUN_TIMED_OUT" satisfies FailureKind;
+
+/**
+ * startScheduledRun's full answer (Go RunStart). The tracking budget rides
+ * the activity RESULT so workflow timing derives from recorded history — a
+ * config flip can never confuse an in-flight replay. Field names are the
+ * recorded-history JSON contract (Go's json tags), never rename.
+ */
+export interface RunStart {
+  outcome: RunOutcome;
+  /** Set exactly when outcome ∈ {STARTED, ALREADY_STARTED}. */
+  executionId: string;
+  /** This fire's tracking budget, already clamped. */
+  trackingTimeoutMinutes: number;
+  /**
+   * The deterministic start-failure copy when outcome ∈ {TARGET_MISSING,
+   * REFUSED}.
+   */
+  failureReason: string;
+}
+
+/** recordFailedRun's post-image summary (Go FailureRecorded). */
+export interface FailureRecorded {
+  consecutiveFailures: number;
+  paused: boolean;
+}
+
+/**
+ * The activity surface the tick workflow proxies, keyed by the pinned
+ * slash names (the TS SDK registers and invokes activities by object key).
+ */
+export interface ScheduleTickActivities {
+  [RECORD_TICK_ACTIVITY_NAME]: (
+    scheduleResourceId: string,
+    nominalFireTimeRfc3339: string,
+  ) => Promise<TickOutcome>;
+  [START_SCHEDULED_RUN_ACTIVITY_NAME]: (
+    scheduleResourceId: string,
+    nominalFireTimeRfc3339: string,
+  ) => Promise<RunStart>;
+  [POLL_EXECUTION_PHASE_ACTIVITY_NAME]: (
+    executionId: string,
+  ) => Promise<RunPhase>;
+  [RECORD_SUCCESSFUL_RUN_ACTIVITY_NAME]: (
+    scheduleResourceId: string,
+  ) => Promise<void>;
+  [RECORD_FAILED_RUN_ACTIVITY_NAME]: (
+    scheduleResourceId: string,
+    reason: string,
+    kind: FailureKind,
+  ) => Promise<FailureRecorded>;
+}