@songsid/agend 2.1.6-beta.1 → 2.1.6-beta.2

package/dist/apply-job.d.ts

@@ -0,0 +1,114 @@
+/** How long a finished job stays answerable, and how long a key is honoured. */
+export declare const APPLY_JOB_RETENTION_MS: number;
+/**
+ * Wall clock, not a step count: the user is looking at a spinner, and the thing
+ * they need to be told is that it has been N seconds, not which internal phase
+ * it is in. Generous — a reconcile that restarts several agents on a loaded
+ * machine is slow but fine.
+ */
+export declare const APPLY_JOB_DEADLINE_MS = 120000;
+/** Outcome of asking the fleet to restart itself for a Settings change. */
+export type SelfRestartResult = {
+    ok: true;
+    jobId: string;
+    reused?: boolean;
+} | {
+    ok: false;
+    status: 409 | 429 | 503;
+    error: string;
+    retryAfterSeconds?: number;
+};
+/** The row for the fleet process itself, as opposed to one of its agents. */
+export declare const APPLY_FLEET_TARGET = "fleet";
+export type ApplyTargetKind = "hot" | "restart";
+/**
+ * `restart-required` is a terminal state, not a stalled one: the change is saved
+ * and valid, and a running fleet process cannot adopt it. Reporting it as done
+ * would tell the user AgEnD is on the new configuration when it is not.
+ */
+export type ApplyTargetStatus = "pending" | "running" | "done" | "failed" | "restart-required";
+export type ApplyJobStatus = "running" | "done" | "failed";
+export interface ApplyTarget {
+    /** Instance name, or `fleet` for the process-level row. */
+    target: string;
+    kind: ApplyTargetKind;
+    status: ApplyTargetStatus;
+    error?: string;
+    /**
+     * Who finished the row, when it was not this job's own work:
+     * `fleet-restart` — a process restart applied it;
+     * `no-change`     — the plan expected work the reconcile found unnecessary.
+     */
+    settled_by?: "fleet-restart" | "no-change";
+}
+export interface ApplyJob {
+    id: string;
+    /** The client's idempotency key. */
+    key: string;
+    status: ApplyJobStatus;
+    startedAt: number;
+    finishedAt?: number;
+    targets: ApplyTarget[];
+    /** Deadline for "still working" messaging; it never cancels the work. */
+    deadlineMs: number;
+    /** The process that created the job, so a restart is detectable. */
+    pid: number;
+    error?: string;
+    /**
+     * The idempotency key of the self-restart this job's fleet row was consumed
+     * by. Stored on the job rather than in memory because the process it belongs
+     * to is about to be replaced — a retry after the restart has to find it.
+     */
+    restart_key?: string;
+}
+/** Everything a caller needs to render, computed rather than stored so it stays
+ * true while the job is being read long after the last write. */
+export interface ApplyJobView extends ApplyJob {
+    elapsed_ms: number;
+    /** Past the deadline and still working — say so instead of spinning silently. */
+    overdue: boolean;
+    /** Human sentence for the overdue case; empty otherwise. */
+    message: string;
+}
+export declare function viewOf(job: ApplyJob, now?: number): ApplyJobView;
+/**
+ * The jobs file. Small, rewritten whole on every transition — a settings apply
+ * happens at human speed, so the simplest durable thing is the right one.
+ */
+/** Just enough of a logger for the one thing this module has to report. */
+export interface ApplyJobLogger {
+    warn(data: unknown, message: string): void;
+}
+export declare class ApplyJobStore {
+    private readonly dataDir;
+    private readonly now;
+    private readonly logger?;
+    private jobs;
+    constructor(dataDir: string, now?: () => number, logger?: ApplyJobLogger | undefined);
+    private path;
+    private read;
+    private write;
+    private prune;
+    /**
+     * A job created in an earlier process cannot still be running in this one.
+     *
+     * The restart is what applied the config: every agent came up from the saved
+     * file. So rows left pending or running are done — recorded as settled by the
+     * restart rather than by the job, because "who finished this" is exactly what
+     * the user is trying to find out.
+     */
+    settleAfterRestart(): ApplyJob[];
+    get(id: string): ApplyJob | null;
+    /** The job whose fleet row a given self-restart key already consumed. */
+    findByRestartKey(key: string): ApplyJob | null;
+    /** The live job for a key, if the client is retrying rather than re-applying. */
+    findByKey(key: string): ApplyJob | null;
+    create(key: string, targets: Array<Pick<ApplyTarget, "target" | "kind">>, deadlineMs?: number): ApplyJob;
+    /** Mutate one job and persist. Every transition hits the disk, because the
+     * transition we care most about is the last one before the process dies. */
+    update(id: string, mutate: (job: ApplyJob) => void): ApplyJob | null;
+    setTargetStatus(id: string, target: string, status: ApplyTargetStatus, error?: string): void;
+    finish(id: string, error?: string): void;
+    /** Test/introspection seam. */
+    all(): ApplyJob[];
+}

package/dist/apply-job.js

@@ -0,0 +1,214 @@
+/**
+ * A Settings "Apply" that the user can watch, and that survives the restart it
+ * asks for.
+ *
+ * The old path was `POST /api/settings/reload` → SIGHUP → nothing. The page said
+ * "changes applied" the moment the signal was sent, while the reconcile was
+ * still stopping and starting agents behind it, and a change that restarts AgEnD
+ * itself killed the only place the answer lived.
+ *
+ * Two properties carry the whole design:
+ *
+ * 1. **The job is on disk, not in the process.** A fleet-impact change takes the
+ *    fleet process down with it. An in-memory job dies there, `GET` starts
+ *    answering 404, and the page shows "restarting…" forever (#722/#748 are the
+ *    same shape). The replacement process reads the marker, settles whatever was
+ *    still in flight, and can answer for a job it never started.
+ * 2. **The client owns the idempotency key.** A server-minted job id cannot stop
+ *    a duplicate: on a phone the POST leaves, the answer never arrives, and the
+ *    retry is a second request the server has no way to recognise. A key the
+ *    client generates before the first attempt makes the retry identifiable, so
+ *    it returns the original job instead of applying everything twice.
+ */
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+const FILE = "settings-apply-jobs.json";
+/** How long a finished job stays answerable, and how long a key is honoured. */
+export const APPLY_JOB_RETENTION_MS = 30 * 60_000;
+/**
+ * Wall clock, not a step count: the user is looking at a spinner, and the thing
+ * they need to be told is that it has been N seconds, not which internal phase
+ * it is in. Generous — a reconcile that restarts several agents on a loaded
+ * machine is slow but fine.
+ */
+export const APPLY_JOB_DEADLINE_MS = 120_000;
+/** At most this many jobs are kept, newest first. */
+const MAX_JOBS = 20;
+/** The row for the fleet process itself, as opposed to one of its agents. */
+export const APPLY_FLEET_TARGET = "fleet";
+function isTerminal(status) {
+    return status === "done" || status === "failed";
+}
+export function viewOf(job, now = Date.now()) {
+    const elapsed = Math.max(0, (job.finishedAt ?? now) - job.startedAt);
+    const overdue = !isTerminal(job.status) && elapsed > job.deadlineMs;
+    return {
+        ...job,
+        elapsed_ms: elapsed,
+        overdue,
+        message: overdue ? `Still restarting (${Math.round(elapsed / 1000)}s)` : "",
+    };
+}
+export class ApplyJobStore {
+    dataDir;
+    now;
+    logger;
+    jobs = [];
+    constructor(dataDir, now = Date.now, logger) {
+        this.dataDir = dataDir;
+        this.now = now;
+        this.logger = logger;
+        this.jobs = this.read();
+    }
+    path() {
+        return join(this.dataDir, FILE);
+    }
+    read() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.path(), "utf-8"));
+            if (!Array.isArray(parsed.jobs))
+                return [];
+            return parsed.jobs.filter(job => typeof job?.id === "string"
+                && typeof job?.key === "string"
+                && typeof job?.startedAt === "number"
+                && Array.isArray(job?.targets));
+        }
+        catch {
+            // Missing or corrupt: an unreadable history must not stop the user from
+            // applying settings.
+            return [];
+        }
+    }
+    write() {
+        const path = this.path();
+        const temp = `${path}.${process.pid}.${this.now()}.tmp`;
+        try {
+            writeFileSync(temp, JSON.stringify({ jobs: this.jobs }), { mode: 0o600 });
+            renameSync(temp, path);
+        }
+        catch (err) {
+            try {
+                unlinkSync(temp);
+            }
+            catch { /* never created */ }
+            // A full or read-only data dir means this job will not survive a restart.
+            // Swallowing that silently is how the symptom becomes "progress just
+            // vanished" with nothing to look at.
+            this.logger?.warn({ err, path }, "Settings apply job could not be persisted");
+        }
+    }
+    prune() {
+        const cutoff = this.now() - APPLY_JOB_RETENTION_MS;
+        this.jobs = this.jobs
+            .filter(job => (job.finishedAt ?? job.startedAt) >= cutoff)
+            .slice(0, MAX_JOBS);
+    }
+    /**
+     * A job created in an earlier process cannot still be running in this one.
+     *
+     * The restart is what applied the config: every agent came up from the saved
+     * file. So rows left pending or running are done — recorded as settled by the
+     * restart rather than by the job, because "who finished this" is exactly what
+     * the user is trying to find out.
+     */
+    settleAfterRestart() {
+        const settled = [];
+        for (const job of this.jobs) {
+            if (isTerminal(job.status))
+                continue;
+            // Only a job from another process. The health server accepts requests a
+            // little before startup finishes, so an apply started seconds ago in THIS
+            // process would otherwise be declared finished by a restart that already
+            // happened. (A recycled pid would leave such a job running until its
+            // deadline reports it — the harmless direction.)
+            if (job.pid === process.pid)
+                continue;
+            for (const row of job.targets) {
+                if (row.status === "done" || row.status === "failed")
+                    continue;
+                row.status = "done";
+                row.settled_by = "fleet-restart";
+            }
+            job.status = "done";
+            job.finishedAt = this.now();
+            settled.push(job);
+        }
+        if (settled.length)
+            this.write();
+        return settled;
+    }
+    get(id) {
+        return this.jobs.find(job => job.id === id) ?? null;
+    }
+    /** The job whose fleet row a given self-restart key already consumed. */
+    findByRestartKey(key) {
+        return this.jobs.find(job => job.restart_key === key) ?? null;
+    }
+    /** The live job for a key, if the client is retrying rather than re-applying. */
+    findByKey(key) {
+        const cutoff = this.now() - APPLY_JOB_RETENTION_MS;
+        return this.jobs.find(job => job.key === key && (job.finishedAt ?? job.startedAt) >= cutoff) ?? null;
+    }
+    create(key, targets, deadlineMs = APPLY_JOB_DEADLINE_MS) {
+        const job = {
+            id: randomUUID(),
+            key,
+            status: "running",
+            startedAt: this.now(),
+            targets: targets.map(row => ({ ...row, status: "pending" })),
+            deadlineMs,
+            pid: process.pid,
+        };
+        this.jobs.unshift(job);
+        this.prune();
+        this.write();
+        return job;
+    }
+    /** Mutate one job and persist. Every transition hits the disk, because the
+     * transition we care most about is the last one before the process dies. */
+    update(id, mutate) {
+        const job = this.get(id);
+        if (!job)
+            return null;
+        mutate(job);
+        this.write();
+        return job;
+    }
+    setTargetStatus(id, target, status, error) {
+        this.update(id, job => {
+            const row = job.targets.find(item => item.target === target);
+            if (!row)
+                return;
+            row.status = status;
+            if (error)
+                row.error = error;
+        });
+    }
+    finish(id, error) {
+        this.update(id, job => {
+            for (const row of job.targets) {
+                if (row.status !== "pending" && row.status !== "running")
+                    continue;
+                if (error) {
+                    row.status = "failed";
+                    row.error = error;
+                    continue;
+                }
+                // The plan forecast work the reconcile then found unnecessary. Saying
+                // plain "done" would read as "this agent was restarted".
+                row.status = "done";
+                row.settled_by = "no-change";
+            }
+            job.status = error ? "failed" : job.targets.some(row => row.status === "failed") ? "failed" : "done";
+            job.finishedAt = this.now();
+            if (error)
+                job.error = error;
+        });
+    }
+    /** Test/introspection seam. */
+    all() {
+        return this.jobs;
+    }
+}
+//# sourceMappingURL=apply-job.js.map

package/dist/apply-job.js.map

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

package/dist/backend/credential-profile.d.ts

@@ -0,0 +1,114 @@
+export interface CredentialHomeSpec {
+    /** The variable that moves the credential home, prepended at launch. */
+    env: string;
+    /** The shared home this backend uses when the variable is unset. */
+    sharedRoot(): string;
+    /**
+     * Where under the root the backend's own files live. `XDG_DATA_HOME` points
+     * at a directory of many programs' data, so kiro's store is one level down;
+     * a backend whose variable points straight at its own home leaves this "".
+     */
+    storeSubdir: string;
+    /**
+     * Entries that must be real files in the profile. Everything the login is
+     * made of, plus anything the store cannot be separated from.
+     */
+    isolate: readonly string[];
+    /**
+     * Entries linked back to the shared home when they exist there. Only
+     * content-addressed runtimes and caches belong here — things that are
+     * expensive to duplicate and carry no identity.
+     */
+    share: readonly string[];
+    /**
+     * Whether this store holds a login, given its store directory.
+     *
+     * A profile nobody has logged into is not an empty session — the CLI stops at
+     * an interactive sign-in prompt and waits there, so an agent pointed at one
+     * never starts. A backend that cannot answer this omits it, and the switch is
+     * allowed rather than blocked on a check that does not exist.
+     */
+    hasLogin?: (storeHome: string) => boolean;
+    /** The subcommand that logs a store in, for telling the user what to run. */
+    loginSubcommand: string;
+}
+/** Backends that can hold more than one login. Codex and Claude come later. */
+export declare const CREDENTIAL_HOMES: Readonly<Record<string, CredentialHomeSpec>>;
+export declare function credentialHomeSpec(backendName: string): CredentialHomeSpec | null;
+/**
+ * The profile a backend was asked for, or null for "behave exactly as before".
+ *
+ * Null is the whole backward-compatibility story: no profile means no variable
+ * is prepended and no directory is created, so an instance that does not opt in
+ * cannot be affected by this feature at all.
+ */
+export declare function resolveCredentialProfile(backendOptions: Record<string, unknown> | undefined): string | null;
+/**
+ * Where a profile lives: under the fleet's data directory, not an instance's.
+ *
+ * A subscription is shared by however many agents the user points at it, so the
+ * directory belongs to the fleet. Putting it under an instance would make
+ * "these three agents use the work account" impossible to express.
+ */
+export declare function credentialProfileHome(dataDir: string, backendName: string, profile: string): string;
+/**
+ * Create the profile home and link the shareable parts back.
+ *
+ * Idempotent: it only ever adds links that are missing, and never replaces
+ * anything that already exists in the profile — a real directory there is
+ * someone's data, and this is not the code that decides to delete it.
+ */
+export declare function prepareCredentialProfileHome(spec: CredentialHomeSpec, profileHome: string): void;
+/**
+ * The profiles a fleet is configured to use for one backend, in a stable order.
+ *
+ * Read from the configuration rather than from the directories on disk: the
+ * config is what the fleet will actually launch, a directory can linger after a
+ * profile is removed, and a profile configured but never started has no
+ * directory yet. Instances sharing a profile name collapse into one entry,
+ * because they share one login and one quota.
+ */
+export declare function listConfiguredProfiles(config: {
+    instances?: Record<string, {
+        backend?: string;
+        backend_options?: Record<string, Record<string, unknown>>;
+    }>;
+    defaults?: {
+        backend?: string;
+        backend_options?: Record<string, Record<string, unknown>>;
+    };
+} | null, backendName: string): string[];
+/**
+ * The directory the backend's own files sit in, for one profile.
+ *
+ * One level below the profile home whenever the relocating variable points at a
+ * directory of many programs' data — `XDG_DATA_HOME/kiro-cli`, not
+ * `XDG_DATA_HOME`. Everything that reads a profile's store (the usage panel,
+ * the transcript reader, the login check) must agree on this path, so it is
+ * computed here rather than reassembled at each call site.
+ */
+export declare function credentialProfileStoreHome(dataDir: string, backendName: string, profile: string): string;
+/**
+ * Whether a profile can be started, and what to run if it cannot.
+ *
+ * `unknown` is not a failure: a backend with no login probe, or a profile on a
+ * backend that has no credential home at all, is simply not something this can
+ * speak about, and a caller must not treat silence as a refusal.
+ */
+export type CredentialProfileLogin = {
+    readonly state: "logged-in";
+} | {
+    readonly state: "signed-out";
+    readonly loginCommand: string;
+} | {
+    readonly state: "unknown";
+};
+export declare function credentialProfileLogin(dataDir: string, backendName: string, profile: string): CredentialProfileLogin;
+/** The profile one instance runs under, or null for the shared login. */
+export declare function instanceCredentialProfile(instance: {
+    backend_options?: Record<string, Record<string, unknown>>;
+} | undefined, defaults: {
+    backend_options?: Record<string, Record<string, unknown>>;
+} | undefined, backendName: string): string | null;
+/** Entries that are real (not links) in a prepared profile — for tests and doctor. */
+export declare function profilePrivateEntries(spec: CredentialHomeSpec, profileHome: string): string[];