@cloudhal/mcp-server 0.0.0-stage → 0.1.0

package/dist/src/schedules.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Schedules for agents and the REST API (RFC-0008 §10–§14): the deployment's schedule store, its
+ * ticker and core-ts's `ReleaseService` (pinning, scheduling, "Publish now"), "own" for releases, who may
+ * approve one, the views and the calendar, release requests and their carry-out, automation runs
+ * (the open run of an automation key, taint and budgets) and the scheduler's run-time re-check of
+ * approvals (`createReleaseApprovalCheck`). Shared by the MCP schedule tools (`schedule-tools.ts`)
+ * and `@cloudhal/api`'s schedule routes.
+ */
+import { type AgentMode, type Approval, type ApprovalCause, type ApprovalStore, checkAutoRelease, type OwnershipResolver, type Principal, type ReleaseItemRisk, type Role } from "@cloudhal/agent-runtime";
+import type { Actor, Automation, AutomationJob, NodeRef, Release, ReleaseApproval, ReleaseNodeKind, ReleaseWhen, ScheduleRun, Site } from "@cloudhal/core-contracts";
+import { type SiteGraphStore } from "@cloudhal/core-ts";
+import { type ReleasePurger, ReleaseService, type SchedulerControl } from "@cloudhal/core-ts/releases";
+import { type ApprovalVerdict, type RunTaintState, type StoredReleaseItem } from "@cloudhal/schedules";
+import type { ReleaseRecord, SqlScheduleStore } from "@cloudhal/schedules/sql";
+/** What a deployment provides for schedules (RFC-0008 §16). */
+export interface SchedulesDeps {
+    readonly store: SqlScheduleStore;
+    /** `false` when the deployment turned schedules off. Default true. */
+    readonly available?: boolean | undefined;
+    /** `CLOUDHAL_AUTOMATIONS=off` → false: automations stop, releases and gates go on (§11.6). */
+    readonly automationsEnabled?: boolean | undefined;
+    /**
+     * The deployment's ticker (`ApiDeps.scheduler`): its mode for `/api/instance` and
+     * `/api/scheduler`, and `poke` when something becomes due sooner (a release scheduled, approved or
+     * moved, a window opened; §8.3).
+     */
+    readonly scheduler?: SchedulerControl | undefined;
+    /** "Publish now" purges the live site's cache like a tick does (absent: nothing is cached). */
+    readonly purge?: ReleasePurger | undefined;
+    /** New versions one call may pin (§6.1 step 4; Workers Free: 20, the default). */
+    readonly maxNewBodies?: number | undefined;
+}
+/** True when the deployment serves schedules. */
+export declare const schedulesAvailable: (deps: SchedulesDeps | undefined) => deps is SchedulesDeps;
+/** core-ts's `ReleaseService` over this graph, with the deployment's ticker and purge. */
+export declare function releaseService(deps: SchedulesDeps, graph: SiteGraphStore, now?: () => Date): ReleaseService;
+/** Tells the ticker something is due at `at` (never throws, never awaited by callers' answers). */
+export declare function poke(deps: SchedulesDeps, at: string | undefined): void;
+/** The person approving on a local server without people (stdio, `bypass`, a confirmed elicitation). */
+export declare const LOCAL_PERSON: Readonly<{
+    id: "user_localdev01";
+    name: "Local developer";
+}>;
+/** Metadata keys on releases (Release.metadata, strings only). */
+export declare const RELEASE_META: {
+    /** The agent's note on a proposal (≤ 500, plain). */
+    readonly note: "cloudhal.note";
+    /** A gate-only reduction (set_embargo on a live node): re-checked without the mode rule. */
+    readonly reduce: "cloudhal.reduce";
+    /**
+     * The mode the agent worked in when it scheduled a gate-only reduction with its key's (`auto`)
+     * approval (`plan` … `auto`): such a release is not an `auto`-mode publish, so Studio labels it
+     * by this mode ("Hidden by an agent in EDITS mode"), not as "Automatic".
+     */
+    readonly mode: "cloudhal.mode";
+    /** The tool or route that made the release. */
+    readonly source: "cloudhal.source";
+};
+/** A node of the working copy by kind and id (undefined when it is gone). */
+export declare function workingNode(graph: SiteGraphStore, kind: string, id: string): Promise<{
+    id: string;
+    siteId?: string;
+    rev: number;
+} | undefined>;
+/** The live snapshot's node refs (empty when nothing is live yet). */
+export declare function liveRefs(graph: SiteGraphStore, site: Site): Promise<NodeRef[]>;
+/** A node version's body: the working copy when it is that version, else the snapshot blob. */
+export declare function nodeVersion<T = unknown>(graph: SiteGraphStore, ref: Pick<NodeRef, "id" | "kind" | "rev" | "hash">): Promise<T | undefined>;
+/**
+ * The `rl1:` a one-node request is bound to before any release exists (`schedule_unpublish`,
+ * `lift_embargo`): the node's working and live versions, so any change voids the request.
+ */
+export declare function nodeBinding(graph: SiteGraphStore, site: Site, nodeId: string): Promise<string>;
+/** The items as the low-risk check sees them (§10.3). */
+export declare function releaseRisk(items: readonly Pick<StoredReleaseItem, "item" | "deps">[], corrects?: ReadonlySet<string>): ReleaseItemRisk[];
+/** RFC-0019 §2.4: the release's articles whose target adds a correction to the live version. */
+export declare function releaseCorrections(graph: SiteGraphStore, items: readonly Pick<StoredReleaseItem, "item">[]): Promise<Set<string>>;
+/** A release removes content or carries an expiry: canceling it keeps content up (§12 `cancel_schedule`). */
+export declare function removesContent(graph: SiteGraphStore, record: Pick<ReleaseRecord, "items">): Promise<boolean>;
+/**
+ * Whether every item is `person`'s own (RFC-0005 §4, `ownOnlyChangeSet`'s rule): entries whose
+ * author is the person or one of their agents, plus new assets those entries use. Undefined when
+ * own-only, else why not.
+ */
+export declare function notOwnRelease(graph: SiteGraphStore, ownership: OwnershipResolver, person: string | undefined, items: readonly Pick<StoredReleaseItem, "item" | "deps">[]): Promise<string | undefined>;
+/**
+ * May this principal approve these items now (§10.4, §10.6)? `releases:publish`, or
+ * `releases:publish:own` with own-only items. Without a membership source a person may.
+ */
+export declare function approvalProblem(graph: SiteGraphStore, ownership: OwnershipResolver, principal: Pick<Principal, "scopes" | "person" | "actor">, items: readonly Pick<StoredReleaseItem, "item" | "deps">[]): Promise<string | undefined>;
+/** A person's approval as the contract stores it (a staff person, never an agent). */
+export declare function personApproval(principal: Pick<Principal, "actor" | "person">, at: string, extra?: {
+    executeAt?: string;
+    approvalId?: string;
+}): ReleaseApproval;
+/** When a scheduled release becomes due (`on-approval`: now). */
+export declare function executeAtOf(when: ReleaseWhen | undefined, now: string): string | undefined;
+export interface AutoVerdict {
+    ok: boolean;
+    /** Why not, in words (the agent reads it). */
+    reason?: string;
+    windowEnds: string;
+    check: ReturnType<typeof checkAutoRelease>;
+}
+/**
+ * The `auto` path of a release (§10.3, §10.7): the key's effective mode is `auto` (never inside a
+ * tainted run — such calls never get here), the items are low risk, the key holds
+ * `releases:publish` (own-only items with `:own`), and the release runs before the window ends.
+ */
+export declare function autoReleaseVerdict(graph: SiteGraphStore, ownership: OwnershipResolver, principal: Principal, items: readonly Pick<StoredReleaseItem, "item" | "deps">[], executeAt: string, now: Date): Promise<AutoVerdict>;
+/** How long an agent's release request may wait (§10.5): until the release's time, ≤ 30 days. */
+export declare function requestExpiry(when: ReleaseWhen | undefined, now: Date, agent: boolean): {
+    expiresAt?: string;
+    problem?: string;
+};
+/** The `input` of a release request: what the carry-out reads back (and Studio shows). */
+export interface ReleaseRequestInput {
+    siteId: string;
+    releaseId: string;
+    when: ReleaseWhen | null;
+    [key: string]: unknown;
+}
+/**
+ * Moves a release to `awaiting_approval` and files one request bound to its `rl1:` hash and
+ * `when` (§10.4): `args_hash` covers `approvalArgs(releaseId, when)`, the request expires at the
+ * release's time. A release already awaiting approval keeps waiting under the new request (the old
+ * one is closed). Returns the request.
+ */
+export declare function requestRelease(input: {
+    deps: SchedulesDeps;
+    approvals: ApprovalStore;
+    record: ReleaseRecord;
+    when: ReleaseWhen;
+    tool: string;
+    actor: Actor;
+    prompt: string;
+    cause: ApprovalCause;
+    mode?: AgentMode | undefined;
+    runId?: string | undefined;
+    now: Date;
+    extra?: Record<string, unknown>;
+}): Promise<{
+    release: Release;
+    request: Approval;
+}>;
+/** A release request that cannot be filed (too far ahead for an agent). */
+export declare class ScheduleRequestError extends Error {
+    readonly name = "ScheduleRequestError";
+}
+/** Whether a request's `when` is the release's current one (§10.4: the time is in `args_hash`). */
+export declare function sameWhen(a: ReleaseWhen | null | undefined, b: ReleaseWhen | undefined): boolean;
+export type ApprovalState = "none" | "pending" | "approved" | "auto" | "denied" | "expired";
+export declare function approvalState(r: Release): ApprovalState;
+export interface ReleaseItemView {
+    nodeId: string;
+    nodeKind: ReleaseNodeKind;
+    kind: "set" | "remove";
+    title: string | null;
+    path: string | null;
+    pinnedRev: number | null;
+    liveRev: number | null;
+    /** Added because a target uses it (§6.1 step 2). */
+    closure: boolean;
+    /** Other non-terminal releases with this node (D15). */
+    overlaps: string[];
+}
+export interface ReleaseView extends Release {
+    executeAt: string | null;
+    approvalState: ApprovalState;
+    view: {
+        items: ReleaseItemView[];
+        closureAdded: string[];
+        /** Nodes held by this release (locked against edits, §6.2). */
+        lockedNodes: string[];
+        request?: {
+            id: string;
+            status: Approval["status"];
+            actor: Actor;
+            expiresAt: string;
+            createdAt: string;
+        };
+    };
+}
+/** A release with its items' titles and paths, overlaps, locks and the request (§12 `get_release`). */
+export declare function releaseView(deps: SchedulesDeps, graph: SiteGraphStore, record: ReleaseRecord, approvals?: ApprovalStore): Promise<ReleaseView>;
+export interface CalendarItem {
+    /** `rel_…`, `gate:<nodeId>:from|until` or `occ:<automationId>:<at>`. */
+    id: string;
+    kind: "release" | "gate" | "automation";
+    at: string;
+    title: string;
+    target: {
+        nodeIds?: string[];
+        nodeId?: string;
+        automationId?: string;
+        releaseId?: string;
+    };
+    origin: "person" | "agent";
+    approval: ApprovalState;
+    state: string;
+    overlaps?: string[];
+}
+export interface CalendarQuery {
+    from: string;
+    to: string;
+    types?: readonly ("release" | "gate" | "automation")[];
+    states?: readonly string[];
+    origin?: "person" | "agent";
+    approval?: ApprovalState;
+    q?: string;
+    collection?: string;
+    /** Items to skip (the cursor). */
+    offset?: number;
+    limit?: number;
+}
+/** At most 62 days per calendar query (§12). */
+export declare const CALENDAR_MAX_DAYS = 62;
+export declare const CALENDAR_MAX_ITEMS = 200;
+/**
+ * Calendar items (§4.5, §12): releases, gates and automation occurrences between `from` and `to`,
+ * a view built from state (nothing stored). Sorted by time, then id.
+ */
+export declare function calendarItems(deps: SchedulesDeps, graph: SiteGraphStore, siteId: string, query: CalendarQuery): Promise<{
+    items: CalendarItem[];
+    nextCursor?: string;
+}>;
+/** Anomaly counters kept on the run's `counts` (§11.4 item 6). */
+export declare const RUN_COUNTS: {
+    readonly reduce: "reduce-calls";
+    readonly refusals: "refusals";
+};
+/** An automation key's open run, as one call sees it. */
+export interface RunContext {
+    run: ScheduleRun;
+    automation: Automation & {
+        job: Extract<AutomationJob, {
+            kind: "agent-task";
+        }>;
+    };
+    state: RunTaintState;
+}
+export declare function taintStateOf(run: ScheduleRun): RunTaintState;
+/**
+ * The principal an automation key works as inside its run (§11.2, §11.4): the mode is the key's,
+ * capped by the automation's `modeCap` (never `bypass`); an automation that reads untrusted text
+ * loses its write scopes on every call.
+ */
+export declare function runPrincipal(principal: Principal, automation: RunContext["automation"]): Principal;
+export type RunResolution = {
+    kind: "none";
+} | {
+    kind: "run";
+    run: RunContext;
+    principal: Principal;
+} | {
+    kind: "outside";
+    message: string;
+    automation?: Automation;
+};
+/**
+ * Resolves an automation key's call (§11.2): its automation (active, its own key, schedules and
+ * automations on) and its open run. `none` for other principals.
+ */
+export declare function resolveRun(deps: SchedulesDeps | undefined, principal: Principal, now: Date): Promise<RunResolution>;
+/** Who is who now, for the re-check at run time. */
+export interface ReleaseRightsSource {
+    /** A staff person's current role by actor id (`user_…`); undefined when they left. */
+    role(personId: string): Promise<Role | undefined>;
+    /** An agent key's state now; undefined when it was revoked or its creator left. */
+    key?(keyId: string): Promise<{
+        mode: AgentMode;
+        creatorRole: Role;
+    } | undefined>;
+}
+/**
+ * `checkApproval` for `runDue` / `createScheduler` (§10.6), after `baseApprovalVerdict`:
+ * - a person's approval holds while the approver is still a member who could approve it now
+ *   (`releases:publish`, or `:own` with own-only items), else `approval_lost`;
+ * - an `auto` approval holds while the key exists, its creator is a member and its effective mode
+ *   (for an automation's key: capped by the automation's current `modeCap`) is still `auto`
+ *   (`creator_removed`, `auto_window_ended`); a gate-only reduction
+ *   (`cloudhal.reduce`) skips the mode rule — any mode that may edit may hide;
+ * - without a rights source (no membership: local, tests) every approval holds.
+ */
+export declare function createReleaseApprovalCheck(input: {
+    graph: SiteGraphStore;
+    store: SqlScheduleStore;
+    ownership: OwnershipResolver;
+    rights?: ReleaseRightsSource | undefined;
+}): (release: Release, now: Date) => Promise<ApprovalVerdict>;
+/** Releases whose state a person may still change (not running, not finished). */
+export declare function editable(r: Release): boolean;