stageflow 0.36.0 → 0.40.0

package/dist/agents/scheduleSource.js

@@ -0,0 +1,100 @@
+import { Cron } from "croner";
+export const DEFAULT_AGENT_SCHEDULE_TICK_INTERVAL_MS = 30_000;
+export function agentScheduleTickIntervalMsFromEnv(env = process.env) {
+    const raw = env.STAGEFLOW_AGENT_SCHEDULE_TICK_INTERVAL_MS;
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_AGENT_SCHEDULE_TICK_INTERVAL_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_AGENT_SCHEDULE_TICK_INTERVAL_MS;
+    return parsed;
+}
+function computeNextRunAt(schedule, from) {
+    const job = new Cron(schedule.cron, schedule.timezone !== undefined ? { timezone: schedule.timezone } : {});
+    return job.nextRun(from);
+}
+export class AgentScheduleSource {
+    service;
+    projectRoot;
+    intervalMs;
+    now;
+    logError;
+    interval;
+    inFlight = false;
+    constructor(options) {
+        this.service = options.service;
+        this.projectRoot = options.projectRoot;
+        this.intervalMs = options.intervalMs ?? DEFAULT_AGENT_SCHEDULE_TICK_INTERVAL_MS;
+        this.now = options.now ?? (() => new Date());
+        this.logError =
+            options.logError ??
+                ((message) => {
+                    console.error(message);
+                });
+    }
+    async start(onFire) {
+        if (this.intervalMs <= 0)
+            return;
+        this.interval = setInterval(() => {
+            if (this.inFlight)
+                return;
+            this.inFlight = true;
+            void this.tick(onFire)
+                .catch((err) => {
+                this.logError(`agent schedule tick failed: ${err instanceof Error ? err.message : String(err)}`);
+            })
+                .finally(() => {
+                this.inFlight = false;
+            });
+        }, this.intervalMs).unref();
+    }
+    async stop() {
+        if (this.interval !== undefined)
+            clearInterval(this.interval);
+        this.interval = undefined;
+    }
+    /**
+     * Fire every enabled agent whose stored next run is due, then store the
+     * following occurrence. A host that was down past a due time fires once,
+     * not once per missed occurrence.
+     */
+    async tick(onFire) {
+        const now = this.now();
+        for (const candidate of await this.service.scheduledAgents(this.projectRoot)) {
+            let following;
+            try {
+                following = computeNextRunAt(candidate.schedule, now);
+            }
+            catch (err) {
+                this.logError(`invalid schedule for agent "${candidate.agentId}": ${err instanceof Error ? err.message : String(err)}`);
+                continue;
+            }
+            const stored = this.service.schedules.nextRun(this.projectRoot, candidate.agentId);
+            if (stored === undefined) {
+                if (following)
+                    this.service.schedules.setNextRun(this.projectRoot, candidate.agentId, following.toISOString());
+                continue;
+            }
+            if (Date.parse(stored) > now.getTime()) {
+                // A schedule edited to fire sooner must not wait out the old next run.
+                if (following && following.getTime() < Date.parse(stored)) {
+                    this.service.schedules.setNextRun(this.projectRoot, candidate.agentId, following.toISOString());
+                }
+                continue;
+            }
+            try {
+                await onFire({
+                    agentId: candidate.agentId,
+                    message: candidate.schedule.message ?? "Scheduled check-in.",
+                });
+            }
+            catch (err) {
+                this.logError(`scheduled turn failed for agent "${candidate.agentId}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                if (following)
+                    this.service.schedules.setNextRun(this.projectRoot, candidate.agentId, following.toISOString());
+            }
+        }
+    }
+}

package/dist/agents/service.d.ts

@@ -0,0 +1,298 @@
+import { type AgentDefinition, type AgentIssue } from "../config/loadAgent.js";
+import { type AgentInboundMessage } from "./communications/port.js";
+import { ApprovalBroker } from "./approvalBroker.js";
+import { type DeliveryLedger, type ScheduleLedger } from "./ledgers.js";
+import { type FinishInput } from "./turnLifecycle.js";
+import { type DiffLine } from "./lineDiff.js";
+import { AgentStore, type AgentApproval, type AgentEvalScore, type AgentMessage, type AgentRevision, type AgentRevisionMeta, type AgentSession, type AgentSessionListItem, type AgentDelivery, type AgentSpan, type AgentTurn, type ApprovalActor, type RevisionSource, type SessionQuery, type SessionStats, type SessionStatus } from "./store.js";
+/** Lookups outside the agents directory, used only to produce non-blocking warnings. */
+export type AgentEnvironment = {
+    /** Server names in the project's `.mcp.json`, or undefined when there is no usable catalog. */
+    mcpServerNames(projectRoot: string): Promise<string[] | undefined>;
+    skillNames(projectRoot: string): Promise<string[] | undefined>;
+    connectionIds(): Promise<string[] | undefined>;
+    /** What a connection talks to (inbox, Photon project), so two connections on one inbox count as one channel. */
+    connectionIdentity?(connectionId: string): Promise<string | undefined>;
+    /** What the model catalog says about an id, or undefined when it cannot be checked. */
+    modelInfo?(id: string): Promise<{
+        known: boolean;
+        nativeTools: boolean;
+    } | undefined>;
+};
+export type AgentSummary = {
+    id: string;
+    name: string;
+    description: string | null;
+    enabled: boolean;
+    revision: number;
+    /** Problems with the file on disk; a non-empty list on a revision-0 agent means it never loaded. */
+    issues: AgentIssue[];
+    model: AgentDefinition["model"] | null;
+    tools: {
+        builtin: string[];
+        builtinTools: string[];
+        mcpServers: string[];
+        skills: string[];
+        browser: boolean;
+    };
+    askFirst: string[];
+    /** Connection the agent answers on, if any. */
+    channelConnection: string | null;
+    /** Cron expression when the agent starts sessions on a schedule. */
+    scheduleCron: string | null;
+    subAgents: string[];
+    capture: AgentDefinition["observability"]["capture"] | null;
+    /** Path of the public chat page (`/chat/<slug>`) while web chat is switched on and has a link. */
+    webChatUrl: string | null;
+    stats: SessionStats;
+    pendingApprovals: number;
+    updatedAt: string;
+};
+export type AgentDetail = {
+    agent: AgentSummary;
+    definition: AgentDefinition | null;
+    yaml: string | null;
+    warnings: AgentIssue[];
+};
+export type ValidationResult = {
+    definition: AgentDefinition | null;
+    issues: AgentIssue[];
+    warnings: AgentIssue[];
+    yaml: string | null;
+};
+export type AgentSessionDetail = {
+    session: AgentSession;
+    messages: AgentMessage[];
+    turns: AgentTurn[];
+    /** Every recorded span, ordered by turn then start time. Empty when capture is off. */
+    spans: AgentSpan[];
+    approvals: AgentApproval[];
+    pendingApproval: AgentApproval | null;
+    evalScores: AgentEvalScore[];
+    /** Channel replies and how they went, one per turn that had to reach someone. */
+    deliveries: AgentDelivery[];
+};
+export type ActiveTurn = {
+    session: AgentSession;
+    definition: AgentDefinition;
+    turn: AgentTurn;
+    history: AgentMessage[];
+    userMessage: AgentMessage;
+};
+export type ChangeActor = {
+    source: RevisionSource;
+    author?: string | null;
+};
+export declare class AgentService {
+    private readonly store;
+    private readonly environment;
+    private readonly now;
+    private readonly tails;
+    /** Wakes a turn paused at an ask-first tool when its approval is decided. */
+    readonly approvalBroker: ApprovalBroker;
+    /** Owns every legal change of a turn, its session and its approval. */
+    private readonly lifecycle;
+    /** Reply delivery bookkeeping, for ReplyDelivery. */
+    readonly deliveries: DeliveryLedger;
+    /** Next-run bookkeeping, for the scheduler. */
+    readonly schedules: ScheduleLedger;
+    constructor(options: {
+        store: AgentStore;
+        environment?: AgentEnvironment;
+        now?: () => Date; /** How long a file must be unchanged before its stamp is trusted (default 2 s). */
+        treeTrustMs?: number;
+    });
+    /** The service clock, so waits and expiries agree with stored timestamps. */
+    clockMs(): number;
+    private iso;
+    /** Serialize file-and-database work per project so a save and a sync never interleave. */
+    private exclusive;
+    private dir;
+    private file;
+    /**
+     * What the agents directory looked like at the last full sync, per project: names, sizes and modification times.
+     * While it is unchanged (and old enough to trust), a sync is one readdir and one stat per file, with no reads or
+     * hashing. Cleared by our own writes and archives.
+     */
+    private readonly syncedTree;
+    /** A file touched this recently may be edited again within the clock's resolution, so its stamp is not trusted yet. */
+    private readonly treeTrustMs;
+    private treeStamp;
+    /**
+     * Bring the database in line with `agents/*.agent.yaml`. Only files whose
+     * content hash changed are parsed. An unchanged tree costs a readdir and a
+     * stat per file, and writes nothing; a changed or freshly touched one is
+     * read and hashed in full.
+     */
+    private sync;
+    private fullSync;
+    private applyFile;
+    /** Write the canonical YAML and record the revision in one step. */
+    private writeRevision;
+    private readonly changeListeners;
+    /** Called after an agent is saved, enabled, disabled, restored or archived, so listeners on channels can follow. */
+    onChange(listener: () => void): void;
+    private notifyChanged;
+    private currentRevision;
+    private summarize;
+    private pendingByAgent;
+    list(projectRoot: string): Promise<AgentSummary[]>;
+    get(projectRoot: string, agentId: string): Promise<AgentDetail>;
+    /** The definition a session is pinned to. */
+    definitionAt(projectRoot: string, agentId: string, revision: number): Promise<AgentDefinition>;
+    private warningsFor;
+    /**
+     * Web chat defaults and links: a new agent starts with web chat on, an enabled block without a link
+     * gets one, and `slug: ""` asks for a new link (rotate). Previews never mint links.
+     */
+    private prepareWebChat;
+    /** The enabled agent a public link points at, or null. */
+    findWebChatAgent(projectRoot: string, slug: string): Promise<{
+        agentId: string;
+        definition: AgentDefinition;
+    } | null>;
+    /** Fills a missing id from the agent's name so callers never have to choose one. */
+    private withGeneratedId;
+    /** One connection answers for one agent: another agent already on this connection is an error. */
+    private channelConflicts;
+    validate(projectRoot: string, rawInput: unknown): Promise<ValidationResult>;
+    private parseOrThrow;
+    create(projectRoot: string, rawInput: unknown, actor: ChangeActor): Promise<AgentDetail>;
+    save(projectRoot: string, agentId: string, input: {
+        baseRevision: number;
+        definition: unknown;
+        summary?: string | null;
+    }, actor: ChangeActor): Promise<AgentDetail>;
+    setEnabled(projectRoot: string, agentId: string, enabled: boolean, actor: ChangeActor): Promise<AgentDetail>;
+    private readonly archiveListeners;
+    /** Called after an agent is archived with the ids of its sessions, so a runtime can let go of what it holds for them. */
+    onArchived(listener: (agentId: string, sessionIds: string[]) => void): void;
+    /** Remove the file; history stays readable (R5). */
+    archive(projectRoot: string, agentId: string): Promise<void>;
+    listRevisions(projectRoot: string, agentId: string): Promise<AgentRevisionMeta[]>;
+    getRevision(projectRoot: string, agentId: string, revision: number): Promise<AgentRevision>;
+    diffRevisions(projectRoot: string, agentId: string, from: number, to: number): Promise<DiffLine[]>;
+    /** Re-save an old revision as the newest one. Enabled state stays as it is now. */
+    restore(projectRoot: string, agentId: string, input: {
+        revision: number;
+        baseRevision: number;
+    }, actor: ChangeActor): Promise<AgentDetail>;
+    openSession(projectRoot: string, agentId: string, input: {
+        source: string;
+        sourceRef?: string | null;
+        threadKey?: string | null;
+        title?: string | null;
+    }): Promise<AgentSession>;
+    /** Id of the session's pending approval, if a turn is waiting on a person. */
+    pendingApprovalFor(_projectRoot: string, sessionId: string): string | null;
+    listSessionsForRef(projectRoot: string, agentId: string, source: string, sourceRef: string, limit: number): AgentSession[];
+    private sessionInProject;
+    getSession(projectRoot: string, sessionId: string): Promise<AgentSessionDetail>;
+    listSessions(projectRoot: string, agentId: string, query: SessionQuery): Promise<{
+        sessions: AgentSessionListItem[];
+        nextCursor: string | null;
+        stats: SessionStats;
+    }>;
+    /** Sessions of every agent in the project (or of one, when `agentId` is given), newest first, with matching stats. */
+    listAllSessions(projectRoot: string, query: SessionQuery, agentId?: string): Promise<{
+        sessions: AgentSessionListItem[];
+        nextCursor: string | null;
+        stats: SessionStats;
+    }>;
+    listSpans(projectRoot: string, sessionId: string): AgentSpan[];
+    /** OTLP/JSON for every turn of a session (what "Export session traces" downloads). */
+    exportSessionOtlp(projectRoot: string, sessionId: string): Record<string, unknown>;
+    /** OTLP/JSON for one finished turn, for live export to a collector. */
+    exportTurnOtlp(projectRoot: string, turnId: string): Record<string, unknown>;
+    /**
+     * Start a turn on a session's pinned revision: records the user message and
+     * marks the session running. The live agent state (enabled, not archived)
+     * gates new turns; the pinned revision supplies the configuration.
+     */
+    beginTurn(projectRoot: string, sessionId: string, input: {
+        text: string;
+        author?: string | null;
+        resumeTurnId?: string;
+    }): Promise<ActiveTurn>;
+    /** Session limits (`limits` in the pinned revision) are checked before each new turn. */
+    private assertWithinLimits;
+    /**
+     * A turn is about to pause for a person. Returns "waiting" once it is parked, or the approval's outcome when it was
+     * already decided in between (nothing to wait for), or "inactive" when the turn is no longer running.
+     */
+    waitOnApproval(projectRoot: string, turnId: string, approvalId: string): Promise<"waiting" | "approved" | "denied" | "expired" | "inactive">;
+    /** The wait is over (decided, expired): the turn runs again. */
+    resumeTurn(projectRoot: string, turnId: string): Promise<void>;
+    /** A stopped turn leaves its ask-first approval behind; close it so it cannot be approved later. */
+    closeApproval(projectRoot: string, approvalId: string): Promise<void>;
+    /**
+     * End a turn. Guarded: a turn that is already over is left as it is (the session detail is returned unchanged), so a
+     * late failure handler cannot rewrite a finished outcome.
+     */
+    completeTurn(projectRoot: string, turnId: string, input: {
+        status: FinishInput["status"];
+        assistantText?: string;
+        errorCode?: string | null;
+        usage?: {
+            inputTokens?: number;
+            outputTokens?: number;
+        };
+        costUsd?: number | null;
+        evalScores?: Array<{
+            metric: string;
+            score: number;
+        }>;
+        sessionStatus?: SessionStatus;
+    }): Promise<AgentSessionDetail>;
+    recordSpan(projectRoot: string, span: AgentSpan): void;
+    /** Called at host start: turns that were running when the host stopped can't resume. */
+    private interrupted;
+    recoverInterruptedTurns(): number;
+    /**
+     * Turns a restart cut off on an always-on agent, on a channel where a reply goes back to the sender's own handle
+     * (iMessage). Each is retried once; the person's message is not asked again.
+     */
+    resumableTurns(projectRoot: string): Promise<Array<{
+        agentId: string;
+        sessionId: string;
+        turnId: string;
+        text: string;
+        from: string;
+        connectionId: string;
+        provider: string;
+        threadId: string;
+    }>>;
+    /** Sends a restart cut off may or may not have arrived; they wait for a person. */
+    settleInterruptedDeliveries(): string[];
+    /** A reply that did not get through makes its turn a failure; one that finally does puts it right. */
+    setReplyDelivered(turnId: string, delivered: boolean): void;
+    latestUndelivered(projectRoot: string, agentId: string): AgentDelivery | undefined;
+    private expireApprovals;
+    requestApproval(projectRoot: string, sessionId: string, input: {
+        tool: string;
+        payload: Record<string, unknown>;
+        turnId?: string | null;
+    }): Promise<AgentApproval>;
+    decideApproval(projectRoot: string, sessionId: string, decision: "approve" | "deny", actor: ApprovalActor): Promise<AgentApproval>;
+    pendingApprovals(projectRoot: string): Promise<Array<AgentApproval & {
+        agentId: string;
+    }>>;
+    receive(projectRoot: string, message: AgentInboundMessage): Promise<{
+        agentId: string;
+        sessionId: string;
+        duplicate: boolean;
+    }>;
+    /**
+     * At-most-once outbound send keyed by operation. A send whose outcome is
+     * unknown (crash between submit and record) is never retried automatically.
+     */
+    sendOutbound(projectRoot: string, sessionId: string, operationKey: string, submit: () => Promise<void>): Promise<{
+        state: "submitted";
+        resent: boolean;
+    }>;
+    scheduledAgents(projectRoot: string): Promise<Array<{
+        agentId: string;
+        schedule: NonNullable<AgentDefinition["schedule"]>;
+    }>>;
+}
+export declare function hashApprovalPayload(payload: Record<string, unknown>): string;