@rubytech/create-sitedesk-code 0.1.521 → 0.1.523

package/payload/platform/plugins/scheduling/mcp/dist/lib/routine-run.d.ts

@@ -0,0 +1,175 @@
+import type { Driver } from "neo4j-driver";
+/** Which dispatch loop opened the record. */
+export type RunKind = "recurring" | "one-time";
+/** The `chooseDispatchMode` result the record was opened for. */
+export type RunMode = "agent" | "action" | "none";
+/**
+ * What the dispatcher can honestly say at close time.
+ *
+ * `accepted` means the POST returned 200 or the MCP tool returned without
+ * error — nothing about the work is known. `handleInbound` is fire-and-forget
+ * and `ensureChannelSession` returns rather than throwing on a spawn failure
+ * (ui/server/routes/channel/schedule-inject.ts), so `finished` can never be
+ * established here. It is reached only by `promoteRoutineRuns` on the reconcile
+ * tick, from evidence in the transcript.
+ */
+export type RunOutcome = "accepted" | "failed" | "no-destination";
+/** Records are kept for 30 days. A quarter-hourly routine settles at ~2,900 per account. */
+export declare const RETENTION_DAYS = 30;
+/**
+ * How long an `open` record may live before it counts as an orphan. This is
+ * `DISPATCH_TIMEOUT_MS` from check-due-events, the hard ceiling on the dispatch
+ * leg, so a genuinely in-flight run can never be miscounted.
+ */
+export declare const ORPHAN_AFTER_MS = 600000;
+/** Neo4j integers arrive as `{low, high}` objects; normalise to a JS number. */
+export declare function toNumber(v: unknown): number | null;
+export interface OpenRunInput {
+    eventId: string;
+    accountId: string;
+    kind: RunKind;
+    mode: RunMode;
+    /** `<channel>:<destination>` for an agent turn, `<plugin>.<tool>` for an action, `-` for none. */
+    target: string;
+    /**
+     * The instant the run was due. On the recurring path this is byte-identical
+     * to the `lastTriggered` the same tick writes, which is what the
+     * `fires-without-records` audit reconciles against.
+     */
+    scheduledFor: string;
+}
+/**
+ * Open the record BEFORE the dispatch, so a run that dies mid-flight still has a
+ * record and a line. Returns the runId, or null when the write failed.
+ */
+export declare function openRoutineRun(driver: Driver, input: OpenRunInput): Promise<string | null>;
+/**
+ * The transport result, emitted separately from the work result so the two can
+ * never be conflated. Log-only: the httpStatus lands on the node at close.
+ */
+export declare function logRunDispatch(runId: string | null, target: string, httpStatus: number | null): void;
+export interface CloseRunInput {
+    outcome: RunOutcome;
+    /** The verbatim `accepted` / `error:<n>` / `error:<msg>` string, kept unparsed. */
+    dispatchResult?: string | null;
+    httpStatus?: number | null;
+    error?: string | null;
+}
+/**
+ * Close the record. `ranMs` is computed in Cypher from the stored `startedAt`
+ * so it is measured against the record's own clock rather than assumed from a
+ * value the caller carried. `startedAt` is an ISO string, so it is parsed with
+ * `datetime()` before the subtraction — a bare string compare against a
+ * temporal would silently yield null.
+ */
+export declare function closeRoutineRun(driver: Driver, runId: string | null, input: CloseRunInput): Promise<void>;
+export interface RunSessionInput {
+    /** The `adminSessionIdFor` hash this firing lands in. */
+    sessionKey: string | null;
+    /** JSONL byte size at inject time — where in the shared transcript this run starts. */
+    transcriptOffset: number | null;
+    /**
+     * False when the offset could not be resolved. Because `adminSessionIdFor`
+     * hashes `${accountId}:admin:${subject}`, every run for one destination shares
+     * one transcript; `bounded=false` surfaces that collision rather than hiding
+     * it, and makes the record unpromotable by design.
+     */
+    bounded: boolean;
+}
+export declare function recordRunSession(driver: Driver, runId: string | null, input: RunSessionInput): Promise<void>;
+/**
+ * Read a transcript from `from` BYTES to the end. Null when unreadable.
+ *
+ * The offset is a byte count — `schedule-inject` records `statSync().size`. It is
+ * therefore read with a positional `readSync`, not by decoding the file and
+ * slicing the string: `String.prototype.slice` indexes UTF-16 code units, so one
+ * multi-byte character anywhere before the boundary (an emoji, an accented name,
+ * a curly quote — all routine in a transcript) would shift the cut and silently
+ * drop the head of this run's output, leaving a finished run recorded as merely
+ * started. Reading positionally also means only the tail is loaded, not the whole
+ * transcript, on every record on every 120-second tick.
+ */
+export declare function readTranscriptTail(path: string, from: number, to?: number | null): string | null;
+/**
+ * Decide a run's status from the slice of transcript that belongs to it.
+ *
+ * Pure, so the rule is testable without a filesystem or a graph.
+ *
+ * The window alone is not enough to attribute output. `adminSessionIdFor` puts
+ * every run for one destination in ONE transcript together with the operator's
+ * own messages, so "an assistant row appeared after this run's offset" is true
+ * whenever the operator simply had a conversation — which would report a routine
+ * that has been dead for a week as having produced output on every fire. The
+ * dispatcher prefixes each injected turn with a schedule marker naming the
+ * routine (`… event <first 8 of eventId> …`, composeScheduleMarker on both the
+ * WhatsApp and Telegram notification paths), so the run's own inbound is
+ * identifiable inside the window:
+ *
+ *   - no marker              → nothing of this run's landed. Do not promote.
+ *   - marker, no assistant   → started: the inbound journalled, no answer yet.
+ *   - marker then assistant  → finished: this run produced that output.
+ *
+ * The assistant row must come AFTER the marker, or a reply to the operator's
+ * earlier message would be credited to this run.
+ */
+export declare function classifyRunEvidence(window: string, eventId: string): "none" | "started" | "finished";
+/**
+ * Promote `accepted` and `started` records from evidence in the transcript.
+ *
+ * This is the honest half of the outcome vocabulary. The dispatcher can only
+ * ever say `accepted` — `handleInbound` is fire-and-forget and a spawn failure
+ * returns rather than throwing — so `started` and `finished` are established
+ * here, from evidence inside the slice of transcript that belongs to the run:
+ * bounded below by its own recorded offset and above by the next run's on the
+ * same transcript, and identified within that window by the run's own schedule
+ * marker (see `classifyRunEvidence`).
+ *
+ * A `bounded=false` record is never selected: without a lower boundary there is
+ * no way to attribute appended bytes to THIS run rather than to the operator's
+ * own traffic in the same shared transcript. Leaving it `accepted` is the
+ * correct reading, not a gap.
+ *
+ * Never throws (honours the sweep contract).
+ */
+export declare function promoteRoutineRuns(driver: Driver, accountId: string, deps?: {
+    readTail?: (path: string, from: number, to: number | null) => string | null;
+    projectDirFor?: (sessionKey: string) => string | null;
+}): Promise<{
+    started: number;
+    finished: number;
+}>;
+/**
+ * The retention control. Unbounded record growth is the same defect as the
+ * uncapped notes string this task removes, so the sweep ships with the record
+ * rather than after it. Never throws.
+ */
+export declare function sweepRoutineRuns(driver: Driver, accountId: string, nowMs: number, retentionDays?: number): Promise<number>;
+/**
+ * Records opened and never closed. A run dying between open and close emits
+ * nothing on its own; this is the only control that finds it. Emitted every
+ * tick including zero, because a check that is silent when healthy cannot be
+ * distinguished from a check that stopped running.
+ */
+export declare function auditRunOrphans(driver: Driver, accountId: string, nowMs: number): Promise<void>;
+/**
+ * Reconciles the OLD scalar against the NEW record: a routine whose
+ * `lastTriggered` moved past the previous audit with no `:RoutineRun` at that
+ * instant fired through a path that writes no record. Load-bearing — without it
+ * a missed dispatch path would be assumed absent rather than detected.
+ *
+ * Defined against `lastTriggered`, which only the RECURRING path writes (the
+ * one-time path sets `eventStatus` and `updatedAt` alone). It therefore covers
+ * the recurring path only, by construction. The one-time path is covered by its
+ * own test and by the census.
+ *
+ * Returns the new watermark: the newest `lastTriggered` seen, or the previous
+ * watermark when nothing fired. Never throws.
+ */
+export declare function auditFiresWithoutRecords(driver: Driver, accountId: string, watermark: string | null): Promise<string>;
+/**
+ * The retention control's own signal. A rising `total` with a fixed `oldest` is
+ * the unbounded-growth signature — the shape the notes blob had for years with
+ * nothing watching it. Emitted every tick including zero.
+ */
+export declare function auditRunCensus(driver: Driver, accountId: string): Promise<void>;
+//# sourceMappingURL=routine-run.d.ts.map

package/payload/platform/plugins/scheduling/mcp/dist/lib/routine-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routine-run.d.ts","sourceRoot":"","sources":["../../src/lib/routine-run.ts"],"names":[],"mappings":"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"}