@dynamicagents/plugins 0.11.0 → 0.12.0

package/dist/computer/host/sync.d.ts

@@ -0,0 +1,111 @@
+import type { Workspace } from "@cloudflare/computer";
+import type { Deadline } from "@dynamicagents/core/alarm";
+/**
+ * The host's half of syncing: moving what the container wrote into the object.
+ *
+ * ## Why the host has a half at all
+ *
+ * Every command is bracketed by a sync — a push before it runs, a pull after it
+ * exits — and the pull is what carries its writes back into this object's
+ * SQLite. That pull can fail while the command itself succeeds: a transport that
+ * dropped, a container replaced underneath it. The library reports that on the
+ * command's result and schedules nothing of its own afterwards. What it does
+ * keep is the cursor, so a later `pull()` resumes the same operation rather than
+ * starting one.
+ *
+ * That later `pull()` is this. Without it the workspace silently lags the
+ * container: the file tools read a tree missing the last command's work, and git
+ * — which runs on this side — would commit and push it that way.
+ */
+/**
+ * How long one drain spends moving blocks before it comes back.
+ *
+ * The alarm is shared. Every other reason a workspace wakes is queued behind
+ * whatever the alarm is doing, so a drain that ran to completion in one
+ * invocation would hold the object for as long as the pull takes. A minute
+ * finishes an ordinary pull outright and keeps a large one from starving the
+ * install watchdog.
+ */
+export declare const SYNC_DRAIN_BUDGET_MS = 60000;
+/** How soon a drain that is making progress comes back for the next block. */
+export declare const SYNC_DRAIN_RESUME_MS = 1000;
+/**
+ * The ceiling on the wait after a pull that failed.
+ *
+ * A failure is not a slow success: whatever broke — a container that stopped
+ * answering, a transport that will not open — is usually still broken a second
+ * later, and coming back at the resume interval would be an alarm and an error
+ * line every second for as long as the workspace stays up. Backing off turns
+ * that into a handful of attempts an hour, which is the rate a recoverable
+ * fault actually clears at.
+ *
+ * Bounded rather than abandoned, because the cursor is durable and the cost of
+ * one more attempt is one round trip: a container that comes back should be
+ * drained without anyone asking.
+ */
+export declare const SYNC_DRAIN_MAX_BACKOFF_MS: number;
+/** How long to wait before a retry, after this many consecutive failures. */
+export declare function syncRetryDelayMs(attempt: number): number;
+/**
+ * What one drain achieved.
+ *
+ * `incomplete` and `failed` are separated because they want opposite responses.
+ * `incomplete` is a healthy drain that ran out of budget with the cursor moved,
+ * and the right answer is to come straight back. `failed` is a pull that threw
+ * with nothing to show for it, and coming straight back would spin against
+ * whatever is broken — see {@link syncRetryDelayMs}.
+ *
+ * `unavailable` is not a failure either: it is the answer when there is no
+ * container to pull from, which also means there is nothing outstanding that
+ * could still be recovered. Kept distinct from `complete` so a caller deciding
+ * whether to act on the workspace — a git push, say — can tell "nothing to move"
+ * from "nothing reachable".
+ */
+export type DrainOutcome = "complete" | "incomplete" | "failed" | "unavailable";
+/**
+ * What a schedule waiting on a pull carries: how many times it has failed in a
+ * row. Both the drain's own deadline and the container-idle deferral that waits
+ * for one hold it, since both have to back off against the same fault.
+ */
+export interface SyncDrainIntent {
+    attempt: number;
+}
+export interface WorkspaceSyncDeps {
+    workspace: () => Workspace;
+    /** Whether a container is up. A drain must never start one — see {@link drain}. */
+    containerRunning: () => boolean;
+    /** Where the next block is scheduled. */
+    deadline: () => Deadline<SyncDrainIntent | undefined>;
+    tag: () => string;
+    id: () => string;
+}
+export declare class WorkspaceSync {
+    private readonly deps;
+    constructor(deps: WorkspaceSyncDeps);
+    /**
+     * Come back shortly and move what is still outstanding.
+     *
+     * A deadline rather than an immediate drain, because the caller is usually
+     * holding something that should not wait on a pull — an install's drain, or a
+     * request. `set` replaces whatever stood before, so arming twice is one
+     * schedule rather than two.
+     */
+    arm(attempt?: number): Promise<void>;
+    /**
+     * Move what the container has written into this object's storage.
+     *
+     * One block per `next()`, under a budget rather than to completion, because
+     * the iterator is disposable by design: the durable state is the cursor the
+     * block just committed, so stopping is a normal thing to do and a recreated
+     * iterable picks up where this one stopped.
+     *
+     * **Never starts a container.** Opening a backend handle would launch one, and
+     * a pull against a replacement finds an empty filesystem rather than the
+     * writes it was after — the library fences that to the runtime that ran the
+     * command, but launching a container to discover so is pure cost. A stopped
+     * container also means there is nothing left to pull: whatever it held that
+     * never arrived is gone, which is why a drain runs *before* an idle deadline
+     * stops one.
+     */
+    drain(budgetMs: number): Promise<DrainOutcome>;
+}

package/dist/computer/host/sync.js

@@ -0,0 +1,124 @@
+/**
+ * The host's half of syncing: moving what the container wrote into the object.
+ *
+ * ## Why the host has a half at all
+ *
+ * Every command is bracketed by a sync — a push before it runs, a pull after it
+ * exits — and the pull is what carries its writes back into this object's
+ * SQLite. That pull can fail while the command itself succeeds: a transport that
+ * dropped, a container replaced underneath it. The library reports that on the
+ * command's result and schedules nothing of its own afterwards. What it does
+ * keep is the cursor, so a later `pull()` resumes the same operation rather than
+ * starting one.
+ *
+ * That later `pull()` is this. Without it the workspace silently lags the
+ * container: the file tools read a tree missing the last command's work, and git
+ * — which runs on this side — would commit and push it that way.
+ */
+/**
+ * How long one drain spends moving blocks before it comes back.
+ *
+ * The alarm is shared. Every other reason a workspace wakes is queued behind
+ * whatever the alarm is doing, so a drain that ran to completion in one
+ * invocation would hold the object for as long as the pull takes. A minute
+ * finishes an ordinary pull outright and keeps a large one from starving the
+ * install watchdog.
+ */
+export const SYNC_DRAIN_BUDGET_MS = 60_000;
+/** How soon a drain that is making progress comes back for the next block. */
+export const SYNC_DRAIN_RESUME_MS = 1_000;
+/**
+ * The ceiling on the wait after a pull that failed.
+ *
+ * A failure is not a slow success: whatever broke — a container that stopped
+ * answering, a transport that will not open — is usually still broken a second
+ * later, and coming back at the resume interval would be an alarm and an error
+ * line every second for as long as the workspace stays up. Backing off turns
+ * that into a handful of attempts an hour, which is the rate a recoverable
+ * fault actually clears at.
+ *
+ * Bounded rather than abandoned, because the cursor is durable and the cost of
+ * one more attempt is one round trip: a container that comes back should be
+ * drained without anyone asking.
+ */
+export const SYNC_DRAIN_MAX_BACKOFF_MS = 5 * 60_000;
+/** How long to wait before a retry, after this many consecutive failures. */
+export function syncRetryDelayMs(attempt) {
+    return Math.min(SYNC_DRAIN_RESUME_MS * 2 ** Math.max(0, attempt), SYNC_DRAIN_MAX_BACKOFF_MS);
+}
+export class WorkspaceSync {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Come back shortly and move what is still outstanding.
+     *
+     * A deadline rather than an immediate drain, because the caller is usually
+     * holding something that should not wait on a pull — an install's drain, or a
+     * request. `set` replaces whatever stood before, so arming twice is one
+     * schedule rather than two.
+     */
+    async arm(attempt = 0) {
+        await this.deps
+            .deadline()
+            .set(new Date(Date.now() + syncRetryDelayMs(attempt)), { attempt });
+    }
+    /**
+     * Move what the container has written into this object's storage.
+     *
+     * One block per `next()`, under a budget rather than to completion, because
+     * the iterator is disposable by design: the durable state is the cursor the
+     * block just committed, so stopping is a normal thing to do and a recreated
+     * iterable picks up where this one stopped.
+     *
+     * **Never starts a container.** Opening a backend handle would launch one, and
+     * a pull against a replacement finds an empty filesystem rather than the
+     * writes it was after — the library fences that to the runtime that ran the
+     * command, but launching a container to discover so is pure cost. A stopped
+     * container also means there is nothing left to pull: whatever it held that
+     * never arrived is gone, which is why a drain runs *before* an idle deadline
+     * stops one.
+     */
+    async drain(budgetMs) {
+        if (!this.deps.containerRunning())
+            return "unavailable";
+        const stopAt = Date.now() + budgetMs;
+        let blocks = 0;
+        let entries = 0;
+        try {
+            for await (const progress of this.deps.workspace().pull()) {
+                blocks += 1;
+                entries += progress.entries;
+                if (progress.complete) {
+                    // Silent for the ordinary case — one empty block, which is what a
+                    // workspace with nothing outstanding returns on every check.
+                    if (blocks > 1 || entries > 0) {
+                        console.info(`[${this.deps.tag()}] pull drained`, {
+                            id: this.deps.id(),
+                            blocks,
+                            entries
+                        });
+                    }
+                    return "complete";
+                }
+                if (Date.now() >= stopAt)
+                    return "incomplete";
+            }
+            // The iterable ended without a block claiming completion, which is what a
+            // backend with nothing to sync returns. Nothing is outstanding either way.
+            return "complete";
+        }
+        catch (err) {
+            // Left outstanding rather than retried here: the cursor is durable, so the
+            // next drain resumes whatever this one committed before it threw.
+            console.error(`[${this.deps.tag()}] a pull could not be drained`, {
+                id: this.deps.id(),
+                blocks,
+                entries,
+                err: String(err)
+            });
+            return "failed";
+        }
+    }
+}

package/dist/computer/host/wake.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What a workspace object wakes for, as one map.
+ *
+ * Its own module because the object that registers these callbacks and the
+ * `JobLifecycle` in `./install-job.ts` that schedules some of them by name both type
+ * against it, and neither should own it. A name that exists in one and not the
+ * other is then a compile error rather than a schedule that is rejected at
+ * runtime.
+ */
+import type { SyncDrainIntent } from "./sync.js";
+export type WorkspaceWakeHandlers = {
+    installRun: () => Promise<void>;
+    installWatch: () => Promise<void>;
+    idleReclaim: () => Promise<void>;
+    /** Start a cold container before a command needs it — see `./workspace.ts`. */
+    containerWarm: () => Promise<void>;
+    containerIdle: (payload?: SyncDrainIntent) => Promise<void>;
+    syncRetry: (payload?: SyncDrainIntent) => Promise<void>;
+};

package/dist/computer/host/wake.js

@@ -0,0 +1,10 @@
+/**
+ * What a workspace object wakes for, as one map.
+ *
+ * Its own module because the object that registers these callbacks and the
+ * `JobLifecycle` in `./install-job.ts` that schedules some of them by name both type
+ * against it, and neither should own it. A name that exists in one and not the
+ * other is then a compile error rather than a schedule that is rejected at
+ * runtime.
+ */
+export {};