@revenexx/studio-integrations 0.6.0 → 1.0.0

package/dist/runtime/pages/integrations/workflows/index.vue

@@ -3,11 +3,16 @@ import { AddCircle as Plus } from "#solar-icons";
 import { Button } from "@revenexx/studio";
 import WorkflowsTable from "../../../components/Integrations/WorkflowsTable.vue";
 import WorkflowCreateDialog from "../../../components/Integrations/WorkflowCreateDialog.vue";
-useHead({ title: "Workflows \xB7 Revenexx Cockpit" });
+const t = useIntegrationsT();
+useHead({ title: () => t("integration.workflows.list.head.title") });
 const { workflows, loading, error, load } = useIntegrationsWorkflows();
 onMounted(() => {
   void load();
 });
+const { buildTick } = useIntegrationsRealtime();
+watch(buildTick, () => {
+  void load(true);
+});
 const loadFailed = computed(() => !!error && !!error.value && !workflows.value.length);
 const createOpen = ref(false);
 </script>
@@ -15,12 +20,12 @@ const createOpen = ref(false);
 <template>
   <IntegrationsLayout>
     <PageHeader
-      title="Workflows"
+      :title="t('integration.workflows.list.header.title')"
     >
       <template #actions>
         <Button class="h-7 text-sm" @click="createOpen = true">
           <Plus :size="14" />
-          New workflow
+          {{ t("integration.workflows.list.action.new") }}
         </Button>
       </template>
     </PageHeader>
@@ -29,12 +34,12 @@ const createOpen = ref(false);
       <StateCard
         v-if="loadFailed"
         variant="error"
-        title="Could not load workflows"
+        :title="t('integration.workflows.list.error.title')"
         :description="error ?? void 0"
       >
         <template #actions>
           <Button variant="outline" class="h-8 text-sm" @click="load(true)">
-            Try again
+            {{ t("integration.common.action.retry") }}
           </Button>
         </template>
       </StateCard>

package/dist/runtime/plugins/locale.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Apply the language a host configured statically (`studioIntegrations.locale`,
+ * or `NUXT_PUBLIC_STUDIO_INTEGRATIONS_LOCALE`) before anything renders.
+ *
+ * It runs ahead of the host's own plugins — module plugins are registered
+ * first — so a host that switches the language at runtime is applying its
+ * choice after this one, never being overwritten by it.
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/plugins/locale.js

@@ -0,0 +1,6 @@
+import { setStudioLocale } from "../utils/localize.js";
+import { defineNuxtPlugin, useRuntimeConfig } from "#app";
+export default defineNuxtPlugin(() => {
+  const configured = useRuntimeConfig().public.studioIntegrations?.locale;
+  if (configured) setStudioLocale(configured);
+});

package/dist/runtime/plugins/realtime.client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Starts realtime once per tab, client-only.
+ *
+ * TWO THINGS HAPPEN HERE AND NEITHER HAPPENS ANYWHERE ELSE.
+ *
+ * `usePlatformTalkback()` is what BUILDS the Talkback client: it imports the
+ * package, mints a connection token and opens the socket on its first call, then
+ * registers the client in studio-shared's registry. The channel composables only
+ * READ that registry — so without this call `useTalkbackTopic()` would find no
+ * client, subscribe to nothing and report a null channel, with no error anywhere.
+ * A plugin rather than a call inside the composable because building the client has
+ * side effects (a dynamic import, a WebSocket, a token mint) and a composable a
+ * component may reach during render is the wrong place for those.
+ *
+ * `useIntegrationsRealtime()` then takes the subscriptions. Warming it here rather
+ * than leaving it to the first surface that asks means an event arriving before the
+ * runs page is opened still moves the signals, and it puts the detached scope's
+ * creation at a defined point in the app's life instead of inside whichever
+ * component rendered first.
+ *
+ * BOTH ARE IDEMPOTENT AND BOTH ARE FREE WHEN REALTIME IS OFF. An empty
+ * `talkbackHost` makes `usePlatformTalkback()` return without building anything —
+ * neither `@revenexx/talkback-js` nor `centrifuge` is imported — and this plugin
+ * costs two function calls.
+ *
+ * The bare names resolve per application, so a host that overrides
+ * `usePlatformTalkback` (the standalone `studio-ui` does, because its API dev token
+ * is not one the Talkback facade will accept) gets its own client here, and a host
+ * that does not gets studio-shared's default.
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/plugins/realtime.client.js

@@ -0,0 +1,4 @@
+export default defineNuxtPlugin(() => {
+  usePlatformTalkback();
+  useIntegrationsRealtime();
+});

package/dist/runtime/types/integrations.d.ts

@@ -318,7 +318,24 @@ export interface NodeManifest {
         title?: LocalizedString;
         category?: string;
     }>;
-    input: NodeManifestInput;
+    /**
+     * The named ports a node accepts data on, keyed by port name — the mirror of
+     * `outputs`.
+     *
+     * **A node that accepts nothing arrives as `[]`, not `{}`**, which is why the
+     * empty array is in the type: the service encodes an empty PHP array as a JSON
+     * array, so the empty case is a different JSON *type* from the populated one. It
+     * is `never[]` rather than `NodeManifestInput[]` because a *populated* array is
+     * not a shape the service produces and not one anything here would read — only
+     * `[]` is real. Read the key through `inputPortsForManifest`, which handles both
+     * forms once.
+     *
+     * **Optional here, required there.** Every published manifest carries it — the
+     * service's schema lists it among the required keys — but the studio also builds
+     * manifest objects in tests and has to tolerate one that predates a field or
+     * omits it, so the type does not claim more than the studio can rely on.
+     */
+    inputs?: Record<string, NodeManifestInput> | never[];
     /** Empty marks a terminal node (PO-201): the run ends there, so the canvas
      *  draws no output handle and no edge may leave it. */
     outputs: NodeManifestOutput[];
@@ -328,6 +345,13 @@ export interface NodeManifest {
         name: string;
         label: string | null;
     };
+    /**
+     * Whether this version's code was built and can therefore be executed
+     * (editor-side enrichment from `GET /nodes`; not manifest data). Absent means
+     * an API that does not report it — treated as executable, so an older host
+     * does not make every node disappear.
+     */
+    __hasBundle?: boolean;
 }
 export interface SecretRecord {
     key: string;

package/dist/runtime/utils/cockpitSources.d.ts

@@ -40,9 +40,18 @@
  * That is measured, not read off the regex: unimport's own `injectImports`, run
  * over this file, injects all five — and over the same file with the declarations
  * rewritten as `declare function`, injects nothing. Repeat it that way if the
- * spelling ever has to change. Nothing stands guard over it automatically, because
- * a test would mean this repository taking a dependency on a build tool it does
- * not otherwise use, to assert that tool's behaviour rather than its own.
+ * spelling ever has to change.
+ *
+ * **Since PO-271 something does stand guard over it, incidentally rather than by
+ * design.** The end-to-end suite runs against a host that auto-imports the same five
+ * names (`playground/app/composables/cockpitFakes.ts`), so the injection has to work
+ * *there* for `specs/credential-managed-source.md` AC-2 to pass at all: rewrite these
+ * as `declare function`, and unimport skips the injection in the playground exactly
+ * as it would in the cockpit, all five names are undefined, the panel disables
+ * itself, and AC-2 goes red. AC-1 would stay green, which is why this is worth
+ * writing down — the half of the spec that is about a host *without* the sources
+ * cannot see the difference. There is still no test asserting the build tool's
+ * behaviour directly, and there deliberately is not one.
  */
 /**
  * The shapes this module uses.
@@ -148,6 +157,16 @@ export interface CockpitMailCredential {
  * says nothing about why. `null` is what the caller turns into "the managed
  * sources are unavailable here", with the manual fields left in place.
  *
+ * **This is not a test for being inside a cockpit, and PO-223 learned that the hard
+ * way.** The dashboard read `!== null` as "am I in a cockpit" for its four shortcuts
+ * into host-owned surfaces, and the standalone dev studio answered yes: it provides
+ * all five names as inert stand-ins on purpose
+ * (`integrations/studio-ui/app/composables/consoleStubs.ts`) so that the managed
+ * credential panels render their empty states rather than nothing. What this answers
+ * is whether the five names are in scope — exactly what the managed sources need to
+ * know, and nothing beyond it. A caller asking anything else has to ask its own
+ * question; that dashboard now asks the router.
+ *
  * Must be called from a component's setup, like the composables it calls.
  */
 export declare function cockpitSources(): CockpitSources | null;

package/dist/runtime/utils/credentialState.d.ts

@@ -16,13 +16,41 @@ export interface CredentialStateInfo {
     label: string;
     /** Badge/pill classes for this state. */
     toneClass: string;
-    /** Failure detail, when the state is `failed`. */
+    /**
+     * What the last test said, whether it passed or failed. A credential type that
+     * reached something can name it — which host, which environment, which plan —
+     * and that is exactly what an operator cannot see anywhere else once a node
+     * stops asking them to configure it.
+     */
     message?: string | null;
     /** When the underlying result was recorded (ISO). */
     at?: string | null;
 }
 type TestableCredential = Pick<Credential, 'status' | 'last_test_ok' | 'last_test_at' | 'last_test_message'>;
+/** Every state a credential can be in, in the order a reader is offered them. */
+export declare const CREDENTIAL_STATES: readonly ["connected", "failed", "needs_reauth", "untested"];
+/**
+ * What a state is called for the reader, keyed rather than derived from a
+ * credential.
+ *
+ * `credentialState()` below answers "what state is this credential in, and what
+ * is it called"; this answers the second half on its own, for the list's filter,
+ * which offers all four states whether or not a credential is in them. They read
+ * the same map, so the badge on a row and the option that finds it cannot come to
+ * disagree — they did, briefly, as two copies of the same four `t()` calls.
+ */
+export declare function credentialStateLabel(key: CredentialConnState): string;
+/**
+ * The `label` is read at call time rather than held in a map beside `TONE`: a
+ * map built once would keep the language it was built in, and this function is
+ * called from inside the table's `computed()` on every render anyway.
+ */
 export declare function credentialState(c: TestableCredential): CredentialStateInfo;
-/** "just now" / "3m ago" / "2h ago" / "5d ago" / a date. Empty for no timestamp. */
+/**
+ * "just now" / "3m ago" / "2h ago" / "5d ago" / a date. Empty for no timestamp.
+ *
+ * Reuses the studio's common time words (`integration.common.time.*`) rather
+ * than minting its own — the same rule as the dashboard's `formatRelative`.
+ */
 export declare function relativeTime(iso?: string | null): string;
 export {};

package/dist/runtime/utils/credentialState.js

@@ -1,3 +1,16 @@
+import { useIntegrationsT } from "../composables/useIntegrationsT.js";
+export const CREDENTIAL_STATES = ["connected", "failed", "needs_reauth", "untested"];
+const MESSAGE_KEY = {
+  connected: "integration.credentials.state.connected",
+  failed: "integration.credentials.state.failed",
+  // Not derivable from the key: the state is called `needs_reauth` on the wire and
+  // "Needs reconnect" to a reader, which is the reason this map exists at all.
+  needs_reauth: "integration.credentials.state.needsReconnect",
+  untested: "integration.credentials.state.untested"
+};
+export function credentialStateLabel(key) {
+  return useIntegrationsT()(MESSAGE_KEY[key]);
+}
 const TONE = {
   connected: "bg-emerald-500/10 border-emerald-500/20 text-emerald-700",
   failed: "bg-rose-500/10 border-rose-500/20 text-rose-700",
@@ -5,25 +18,27 @@ const TONE = {
   untested: "bg-slate-500/10 border-slate-500/20 text-slate-600"
 };
 export function credentialState(c) {
+  const t = useIntegrationsT();
   if (c.status === "needs_reauth") {
-    return { key: "needs_reauth", label: "Needs reconnect", toneClass: TONE.needs_reauth, at: c.last_test_at };
+    return { key: "needs_reauth", label: t(MESSAGE_KEY.needs_reauth), toneClass: TONE.needs_reauth, at: c.last_test_at };
   }
   if (c.last_test_ok === true) {
-    return { key: "connected", label: "Connected", toneClass: TONE.connected, at: c.last_test_at };
+    return { key: "connected", label: t(MESSAGE_KEY.connected), toneClass: TONE.connected, message: c.last_test_message, at: c.last_test_at };
   }
   if (c.last_test_ok === false) {
-    return { key: "failed", label: "Failed", toneClass: TONE.failed, message: c.last_test_message, at: c.last_test_at };
+    return { key: "failed", label: t(MESSAGE_KEY.failed), toneClass: TONE.failed, message: c.last_test_message, at: c.last_test_at };
   }
-  return { key: "untested", label: "Not Connected", toneClass: TONE.untested };
+  return { key: "untested", label: t(MESSAGE_KEY.untested), toneClass: TONE.untested };
 }
 export function relativeTime(iso) {
   if (!iso) return "";
-  const t = new Date(iso).getTime();
-  if (Number.isNaN(t)) return "";
-  const ms = Date.now() - t;
-  if (ms < 6e4) return "just now";
-  if (ms < 36e5) return `${Math.floor(ms / 6e4)}m ago`;
-  if (ms < 864e5) return `${Math.floor(ms / 36e5)}h ago`;
-  if (ms < 30 * 864e5) return `${Math.floor(ms / 864e5)}d ago`;
+  const at = new Date(iso).getTime();
+  if (Number.isNaN(at)) return "";
+  const t = useIntegrationsT();
+  const ms = Date.now() - at;
+  if (ms < 6e4) return t("integration.common.time.justNow");
+  if (ms < 36e5) return t("integration.common.time.minutesAgo", Math.floor(ms / 6e4));
+  if (ms < 864e5) return t("integration.common.time.hoursAgo", Math.floor(ms / 36e5));
+  if (ms < 30 * 864e5) return t("integration.common.time.daysAgo", Math.floor(ms / 864e5));
   return new Date(iso).toLocaleDateString();
 }

package/dist/runtime/utils/localize.d.ts

@@ -1,12 +1,59 @@
+/**
+ * Tell the studio which language to render in. **This is the host's job**, and
+ * it is the whole contract: the module is published, so it must not go looking
+ * for the cockpit's storage keys or import the cockpit's i18n. A host with a
+ * language switcher calls this whenever the choice changes; a host with a fixed
+ * language sets `studioIntegrations.locale` in its Nuxt config instead and
+ * never calls this at all.
+ *
+ * A BCP-47 tag (`de`, `en`, `de-CH`). Empty or absent means English.
+ */
+export declare function setStudioLocale(locale: string | null | undefined): void;
+/** The language the studio is currently rendering in. Reactive when read in an effect. */
+export declare function studioLocale(): string;
+/**
+ * The key a read answers from — which is the key a *deletion* has to remove, since
+ * what the user is clearing is the text in front of them.
+ *
+ * All four steps, in the order `resolveLocalized` reads them: the exact tag, the same
+ * language in another region, English, and the map's own first entry. `''` when the
+ * map holds no string at all.
+ */
+export declare function languageKeyRead(map: unknown, locale?: string): string;
+/**
+ * The key an edit is written to.
+ *
+ * The first two steps of {@link languageKeyRead} and deliberately not its last two:
+ * falling back to English or to the first entry answers "what can I show you", and
+ * writing there would put the author's text into a language they are not reading —
+ * the silent loss this exists to prevent (PO-259). A language the map does not hold
+ * yet is written under its base subtag, never the tag the host set, so that reading
+ * it back finds it: a `de-CH` studio reading a `de` text through the region step
+ * would otherwise write a new `de-CH` key and leave every plain-`de` reader on the
+ * old wording.
+ *
+ * **That guarantee is about the keys this function invents.** The first two steps
+ * return a key the map already holds, verbatim — so a map carrying `DE-ch` is written
+ * back into `DE-ch`, which the API's `^[a-z]{2,3}(-[A-Z]{2})?$` rejects. Not a case
+ * that can arise: such a map could not have been saved in the first place, and the
+ * only writer of these keys is this function. Returning an existing key as it stands
+ * is what makes the write land where the read came from, which is worth more here than
+ * normalising a shape nothing can produce — but it is why the sentence above says
+ * *invents* rather than *writes*.
+ *
+ * Deleting is the other question and has the other answer — see
+ * {@link languageKeyRead}.
+ */
+export declare function languageKeyToWrite(map: unknown, locale?: string): string;
 /**
  * Resolve a multilingual value from the Integrations API. The API returns
  * names and descriptions either as a plain string or as an already-parsed
  * object `{de:"…", en:"…"}` (the HTTP client does JSON decoding automatically).
  * JSON-encoded strings like `'{"de":"…","en":"…"}'` are also handled.
  *
- * Priority: 1) "en", 2) first key found. English is the cockpit default —
- * there is no working language switcher yet; browser-locale preference
- * returns together with the switcher.
+ * The language is the studio's ({@link setStudioLocale}) unless the caller
+ * names one. English is the fallback, and the map's own first entry the
+ * fallback after that.
  *
  * **This is the studio's only resolver, and that is the point.** The same three
  * lines used to sit in seventeen components under six names (`labelText`, `loc`,
@@ -22,7 +69,7 @@
  * `descriptionText`), so no grep for the rule's shape found them. Both resolve
  * text a person typed and went to `resolveDisplayName` below, not here.
  */
-export declare function resolveLocalized(value: unknown): string;
+export declare function resolveLocalized(value: unknown, locale?: string): string;
 /**
  * The same resolution, for a value that may be **text a person wrote** — a
  * node's own name, a group frame's label.
@@ -37,4 +84,4 @@ export declare function resolveLocalized(value: unknown): string;
  * resolved. Use this wherever the value can be something a person typed; use
  * `resolveLocalized` for anything that can only have come from a manifest.
  */
-export declare function resolveDisplayName(value: string | Record<string, string> | undefined | null): string;
+export declare function resolveDisplayName(value: string | Record<string, string> | undefined | null, locale?: string): string;

package/dist/runtime/utils/localize.js

@@ -1,11 +1,49 @@
-export function resolveLocalized(value) {
+import { shallowRef } from "vue";
+const uiLocale = shallowRef("en");
+export function setStudioLocale(locale) {
+  const next = typeof locale === "string" ? locale.trim() : "";
+  uiLocale.value = next || "en";
+}
+export function studioLocale() {
+  return uiLocale.value;
+}
+function baseLanguage(locale) {
+  const base = locale.toLowerCase().split(/[-_]/)[0] ?? "";
+  return /^[a-z]{2,3}$/.test(base) ? base : "en";
+}
+export function languageKeyRead(map, locale = studioLocale()) {
+  const obj = map && typeof map === "object" ? map : {};
+  const keys = Object.keys(obj);
+  if (!keys.length) return "";
+  const wanted = locale.toLowerCase();
+  const base = baseLanguage(locale);
+  const candidates = [
+    keys.find((k) => k.toLowerCase() === wanted),
+    keys.find((k) => baseLanguage(k) === base),
+    keys.find((k) => baseLanguage(k) === "en"),
+    keys[0]
+  ];
+  for (const key of candidates) {
+    if (key === void 0) continue;
+    if (typeof obj[key] === "string") return key;
+  }
+  return "";
+}
+export function languageKeyToWrite(map, locale = studioLocale()) {
+  const keys = map && typeof map === "object" ? Object.keys(map) : [];
+  const wanted = locale.toLowerCase();
+  const base = baseLanguage(locale);
+  return keys.find((k) => k.toLowerCase() === wanted) ?? keys.find((k) => baseLanguage(k) === base) ?? base;
+}
+function pickLanguage(map, locale) {
+  const key = languageKeyRead(map, locale);
+  const picked = key ? map[key] : void 0;
+  return typeof picked === "string" ? picked : "";
+}
+export function resolveLocalized(value, locale = uiLocale.value) {
   if (value === null || value === void 0) return "";
   if (typeof value === "object" && !Array.isArray(value)) {
-    const map = value;
-    const keys = Object.keys(map);
-    if (!keys.length) return "";
-    const picked = map["en"] ?? map[keys[0]];
-    return typeof picked === "string" ? picked : "";
+    return pickLanguage(value, locale);
   }
   if (typeof value !== "string") return String(value);
   const trimmed = value.trim();
@@ -13,12 +51,12 @@ export function resolveLocalized(value) {
   try {
     const parsed = JSON.parse(trimmed);
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return trimmed;
-    return resolveLocalized(parsed);
+    return resolveLocalized(parsed, locale);
   } catch {
     return trimmed;
   }
 }
-export function resolveDisplayName(value) {
+export function resolveDisplayName(value, locale = uiLocale.value) {
   if (typeof value === "string") return value;
-  return resolveLocalized(value);
+  return resolveLocalized(value, locale);
 }

package/dist/runtime/utils/pollBudget.d.ts

@@ -0,0 +1,72 @@
+/**
+ * How often a poll is still allowed to fetch once realtime is carrying the same
+ * updates.
+ *
+ * Every run surface polls: the runs list every three seconds, the detail panel
+ * every three and its timeline every ten, the replay canvas every four. That is the
+ * only thing that made a `running → completed` transition appear at all, and it is
+ * expensive — `runs.vue`'s pass fans out one request per workflow and then
+ * reconciles up to five active runs, so the list can cost dozens of requests every
+ * three seconds while anything is in flight.
+ *
+ * Talkback replaces the *latency* argument for polling, not the safety argument. So
+ * the intervals stay exactly where they are and this decides, per tick, whether the
+ * tick may spend a request: at the ordinary cadence while nothing is being reported,
+ * and at a slow safety cadence once something is.
+ *
+ * COUNTING TICKS, NOT READING A CLOCK, and that is deliberate twice over. The tick
+ * is the only thing that has actually happened — a wall-clock reading would make
+ * this disagree with a `setInterval` the browser throttled in a background tab. And
+ * `specs/runs.md` AC-8's test installs Playwright's fake clock and fast-forwards
+ * it; a `Date.now()` in here would read the fake time, which is the kind of
+ * coupling that makes a test pass for the wrong reason.
+ *
+ * WHAT `delivering` HAS TO MEAN, and this is the argument the parameter's name is
+ * carrying. Being subscribed is no evidence: a channel resolves from the local
+ * subscription, so a tenant whose event catalogue never publishes these topics holds
+ * open channels that stay silent for the life of the tab — and thinning on that state
+ * would make such a tenant ten times slower than before any of this existed, with
+ * nothing anywhere saying so. `useIntegrationsRealtime` therefore counts deliveries,
+ * and this is only ever thinned once something has really arrived.
+ *
+ * WHY A SLOW POLL RATHER THAN NONE. What is still unavailable is whether delivery is
+ * CONTINUING: a socket that dies quietly after one event keeps reading as delivering,
+ * because the per-channel confirmation that would settle it is not passed through the
+ * packages between Centrifugo and here. A budget that stopped fetching entirely would
+ * then show a stale list for as long as the tab stayed open, with nothing anywhere
+ * saying so. Backing off from three seconds to thirty gives up latency we now get
+ * from events and keeps the property that mattered: the view converges without the
+ * operator doing anything.
+ *
+ * The caller keeps its own tick-shedding (`!loading.value`) in front of this, so a
+ * tick that finds a load still out neither fetches nor spends budget — see
+ * `loadGate.ts` for why that flag is trustworthy.
+ */
+export interface PollBudgetOptions {
+    /** The caller's own interval, i.e. how much time one `due()` call stands for. */
+    intervalMs: number;
+    /** The gap between fetches while reports are arriving. */
+    liveIntervalMs: number;
+}
+export interface PollBudget {
+    /**
+     * Whether this tick may fetch. Advances the budget, so call it once per tick and
+     * last in the condition — `hasActive && !loading && budget.due(delivering)`.
+     */
+    due: (delivering: boolean) => boolean;
+    /**
+     * Counts a fetch this budget did not authorise: a report's refetch, a manual
+     * refresh, a row action, an opening surface's first read. Without it the next due
+     * tick would send a second request for a state that was just read.
+     *
+     * CALL IT IN THE LOADER, not at each call site, wherever the surface has a loader
+     * of its own to put it in — `[id].vue`'s `loadRuns`, `RunDetailPanel`'s
+     * `loadSummary` and `loadTimelineEvents`, `runs.vue`'s `reload`. A contract that
+     * asks every future caller to remember is one that ends up wider than the wiring,
+     * which is how this note came to be written.
+     */
+    spend: () => void;
+}
+/** The safety cadence every run surface backs off to while reports are arriving. */
+export declare const SAFETY_POLL_MS = 30000;
+export declare function createPollBudget(options: PollBudgetOptions): PollBudget;

package/dist/runtime/utils/pollBudget.js

@@ -0,0 +1,17 @@
+export const SAFETY_POLL_MS = 3e4;
+export function createPollBudget(options) {
+  let elapsed = 0;
+  return {
+    due(delivering) {
+      elapsed += options.intervalMs;
+      if (!delivering || elapsed >= options.liveIntervalMs) {
+        elapsed = 0;
+        return true;
+      }
+      return false;
+    },
+    spend() {
+      elapsed = 0;
+    }
+  };
+}

package/dist/runtime/utils/schedule.d.ts

@@ -1,28 +1,3 @@
-/**
- * A schedule, in both directions: the structured rhythm the studio lets a user
- * pick, the five-field cron expression the platform runs on, and the sentence
- * that says it in words.
- *
- * The studio no longer asks anyone to write cron. It asks for a rhythm — every
- * few minutes, daily at a time, on these weekdays — and `toCron` turns that into
- * the expression the API stores. `parseCron` is the way back, so a schedule that
- * arrives from anywhere (a template, the MCP tools, a hand-written expression from
- * before this existed) opens in the same controls if it can, and stays an
- * expression if it cannot.
- *
- * **The sentence is total over what the picker can build.** `describeRecurrence`
- * always answers; the refusal to guess lives in `parseCron`, which returns `null`
- * for everything outside the shapes below — several stepped fields, minute and
- * hour lists, `L`/`#` syntax, month restrictions, seconds precision. That is what
- * lets the studio show the sentence instead of the expression: for anything it
- * authored there is always a sentence, and where there is none the expression is
- * shown, because nothing else would be true.
- *
- * **Nothing here converts a time.** The platform evaluates the expression in the
- * trigger's own timezone (`CronExpression->isDue($now->setTimezone($tz))`), so the
- * numbers in it are wall-clock time in that zone. The zone is therefore half of
- * the schedule and the caller's to show — it is not a formatting detail.
- */
 /** A rhythm the picker can build, and `describeRecurrence` can always say. */
 export type Recurrence = 
 /** `interval` minutes apart, all day, every day. `1` means every minute. */