@songsid/agend 2.3.0-beta.1 → 2.3.0-beta.11

package/dist/memory-hogs.js

@@ -0,0 +1,124 @@
+/**
+ * #2015: which processes hold the most memory in the fleet's service, and whose they are. When host memory pressure
+ * rises, General is told the top few — the fleet, tmux, or an instance's CLI or a command it ran — so a person can stop
+ * a runaway before the kernel's OOM killer picks a victim (2026-10-17: one agent's 19 GB script).
+ *
+ * The processes are the fleet cgroup's (cgroup v2 `cgroup.procs`: everything the service runs), else the fleet's
+ * descendants. Each one's owner is found by walking its parents to a tmux pane's shell: the pane's window name is the
+ * instance. Every read is a small /proc file, read one at a time, never more than one at once in memory.
+ */
+import { readFile, readdir } from "node:fs/promises";
+/** At most this many processes are looked at (a bound on the work, not a cut of the answer on a normal host). */
+export const MEMORY_HOGS_SCAN_MAX = 4096;
+async function readText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Name, VmRSS (bytes) and parent pid of one process, or null (gone, a kernel thread, unreadable). */
+async function statusOf(procRoot, pid) {
+    const s = await readText(`${procRoot}/${pid}/status`);
+    if (!s)
+        return null;
+    const name = /^Name:\s*(.*)$/m.exec(s)?.[1]?.trim() ?? "?";
+    const rss = /^VmRSS:\s+(\d+) kB$/m.exec(s)?.[1];
+    const ppid = /^PPid:\s+(\d+)$/m.exec(s)?.[1];
+    if (!rss || !ppid)
+        return null;
+    return { name, rss: Number.parseInt(rss, 10) * 1024, ppid: Number.parseInt(ppid, 10) };
+}
+/** Every descendant of `roots` (the roots included), breadth first, from one pass over every process's parent. */
+async function descendants(procRoot, roots) {
+    let entries = [];
+    try {
+        entries = await readdir(procRoot);
+    }
+    catch {
+        return roots;
+    }
+    const children = new Map();
+    for (const e of entries.slice(0, 65536)) {
+        if (!/^\d+$/.test(e))
+            continue;
+        const st = await statusOf(procRoot, Number(e));
+        if (!st)
+            continue;
+        const list = children.get(st.ppid) ?? [];
+        list.push(Number(e));
+        children.set(st.ppid, list);
+    }
+    const out = [];
+    const queue = [...roots];
+    const seen = new Set();
+    while (queue.length && out.length < MEMORY_HOGS_SCAN_MAX) {
+        const pid = queue.shift();
+        if (seen.has(pid))
+            continue;
+        seen.add(pid);
+        out.push(pid);
+        queue.push(...(children.get(pid) ?? []));
+    }
+    return out;
+}
+/**
+ * The pids the service runs: its cgroup's, else the fleet process and its descendants. The tmux server holding the
+ * instances can outlive a fleet restart in another cgroup (a fleet started again from another terminal moves to a new
+ * scope; tmux stays): when it is not among the cgroup's processes, its descendants (every pane's CLI and what it ran)
+ * are added (#2036 review).
+ */
+async function servicePids(deps, procRoot) {
+    // The cgroup v2 path (the "0::" line), as process-memory.ts reads it.
+    const line = (await readText(`${procRoot}/${deps.fleetPid}/cgroup`))?.split("\n").find(l => l.startsWith("0::"));
+    const cg = line ? line.slice(3).trim() : null;
+    const cgRoot = deps.cgroupRoot ?? "/sys/fs/cgroup";
+    if (cg && cg !== "/") {
+        const procs = await readText(`${cgRoot}${cg}/cgroup.procs`);
+        if (procs) {
+            const pids = procs.split("\n").map(l => Number.parseInt(l, 10)).filter(n => Number.isSafeInteger(n) && n > 0).slice(0, MEMORY_HOGS_SCAN_MAX);
+            if (!deps.tmuxServerPid || pids.includes(deps.tmuxServerPid))
+                return pids;
+            const outside = (await descendants(procRoot, [deps.tmuxServerPid])).filter(p => !pids.includes(p));
+            return [...pids, ...outside].slice(0, MEMORY_HOGS_SCAN_MAX);
+        }
+    }
+    // No cgroup v2 view: the fleet's and tmux's descendants.
+    return descendants(procRoot, [deps.fleetPid, ...(deps.tmuxServerPid ? [deps.tmuxServerPid] : [])]);
+}
+/** The `limit` processes with the most RSS in the fleet's service, largest first, each with its owner. */
+export async function topMemoryHogs(deps, limit = 3) {
+    const procRoot = deps.procRoot ?? "/proc";
+    const pids = await servicePids(deps, procRoot);
+    const info = new Map();
+    for (const pid of pids) {
+        const st = await statusOf(procRoot, pid);
+        if (st)
+            info.set(pid, st);
+    }
+    const paneOf = new Map(deps.panes.map(p => [p.pid, p.window]));
+    const ownerOf = async (pid) => {
+        let at = pid;
+        for (let hops = 0; hops < 64 && at > 1; hops++) {
+            const pane = paneOf.get(at);
+            if (pane !== undefined)
+                return deps.isInstance(pane) ? { owner: "instance", instance: pane } : { owner: "other" };
+            if (at === deps.tmuxServerPid)
+                return { owner: "tmux" };
+            if (at === deps.fleetPid)
+                return { owner: "fleet" };
+            const parent = info.get(at)?.ppid ?? (await statusOf(procRoot, at))?.ppid;
+            if (!parent)
+                break;
+            at = parent;
+        }
+        return { owner: "other" };
+    };
+    const top = [...info.entries()].sort((a, b) => b[1].rss - a[1].rss).slice(0, Math.max(0, limit));
+    const out = [];
+    for (const [pid, st] of top)
+        out.push({ pid, name: st.name, rssBytes: st.rss, ...(await ownerOf(pid)) });
+    return out;
+}
+//# sourceMappingURL=memory-hogs.js.map

package/dist/memory-hogs.js.map

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

package/dist/outbound-handlers.d.ts

@@ -109,6 +109,16 @@ export interface OutboundContext {
     getInstanceExecutionState?(name: string): "idle" | "working" | "stuck" | "paused" | null;
     /** Subscription provider IDs used by running or paused fleet/Classic instances. */
     getActiveUsageProviderIds?(): ReadonlySet<string>;
+    /** #2056: Settings → Web appearance for the user (web-settings-tools.ts). */
+    webSettings?: import("./web-settings-tools.js").WebSettingsTools;
+    /** #2001: the cache report as last worked out (CacheService.published) — never a transcript read. */
+    cacheReportPublished?(window: string): Promise<import("./cache-service.js").CacheReport>;
+    /** #2122: the usage report; `only`: just that instance (an ordinary caller's own row). */
+    usageReport?(params: {
+        range: import("./usage-report.js").UsageRange;
+        group: import("./usage-report.js").UsageGroup;
+        only?: string;
+    }): Promise<import("./usage-report.js").UsageReport>;
     /** Effective process state used to annotate cross-instance delivery results. */
     getInstanceStatus?(name: string): "running" | "paused" | "stopped" | "crashed";
     /** #1808: whether `backend` takes this model name (the rule /backend applies too); `choices`: what it offers. */

package/dist/outbound-handlers.js

@@ -15,7 +15,7 @@ import { CHAT_PROFILE_LOGIN_BACKENDS, credentialProfileLogin, credentialSwitchCa
 import { kiroEngineCandidates, kiroEngineStatus } from "./kiro-engine-status.js";
 import { noPlaceMarkers, placeRef, renderPlaceRefs, stripPlaceRefs, webRoute } from "./topic-link.js";
 import { formatCrossInstanceInboundMessage, MAX_ASSEMBLED_CROSS_INSTANCE_MESSAGE_BYTES, } from "./cross-instance-envelope.js";
-import { BroadcastArgs, CreateInstanceArgs, CreateTeamArgs, DelegateTaskArgs, DeleteInstanceArgs, DeleteTeamArgs, DeployTemplateArgs, DescribeInstanceArgs, ListDeploymentsArgs, ListInstancesArgs, ListTeamsArgs, ReplaceInstanceArgs, ReportResultArgs, DeliveryStatusArgs, RequestInformationArgs, RestartInstanceArgs, SendToInstanceArgs, PauseInstanceArgs, WakeInstanceArgs, StopInstanceArgs, GetInstanceLogsArgs, GetEffortArgs, ClosePollArgs, KiroEngineStatusArgs, GetUsageArgs, ListModelsArgs, GetFleetConfigArgs, UpdateInstanceConfigArgs, UpdateFleetDefaultsArgs, StartInstanceArgs, TeardownDeploymentArgs, UpdateTeamArgs, validateArgs, } from "./outbound-schemas.js";
+import { BroadcastArgs, CreateInstanceArgs, CreateTeamArgs, DelegateTaskArgs, DeleteInstanceArgs, DeleteTeamArgs, DeployTemplateArgs, DescribeInstanceArgs, ListDeploymentsArgs, ListInstancesArgs, ListTeamsArgs, ReplaceInstanceArgs, ReportResultArgs, DeliveryStatusArgs, RequestInformationArgs, RestartInstanceArgs, SendToInstanceArgs, PauseInstanceArgs, WakeInstanceArgs, StopInstanceArgs, GetInstanceLogsArgs, GetEffortArgs, ClosePollArgs, KiroEngineStatusArgs, GetUsageArgs, GetCacheReportArgs, GetUsageReportArgs, GetWebSettingsArgs, SetWebSettingsArgs, ListModelsArgs, GetFleetConfigArgs, UpdateInstanceConfigArgs, UpdateFleetDefaultsArgs, StartInstanceArgs, TeardownDeploymentArgs, UpdateTeamArgs, validateArgs, } from "./outbound-schemas.js";
 const HOME_DIR = homedir();
 function formatByteSize(bytes) {
     if (bytes < 1024)
@@ -522,7 +522,8 @@ const listInstances = (ctx, rawArgs, respond, meta) => {
     }
     if (filterName) {
         const lowerName = filterName.toLowerCase();
-        allInstances = allInstances.filter(i => i.name.toLowerCase().includes(lowerName));
+        allInstances = allInstances.filter(i => i.name.toLowerCase().includes(lowerName) ||
+            (i.display_name?.toLowerCase().includes(lowerName) ?? false));
     }
     if (filterBackend) {
         allInstances = allInstances.filter(i => i.backend === filterBackend);
@@ -552,6 +553,7 @@ const listInstances = (ctx, rawArgs, respond, meta) => {
     const compactInstances = allInstances.map(i => ({
         name: i.name,
         status: i.status,
+        ...(i.display_name ? { display_name: i.display_name } : {}),
         backend: i.backend,
         model: i.model,
         kind: i.kind,
@@ -603,6 +605,7 @@ const describeInstance = (ctx, rawArgs, respond) => {
             name: targetName,
             type: "instance",
             kind: "fleet-topic",
+            display_name: config.display_name ?? null,
             description: config.description ?? null,
             tags: config.tags ?? [],
             working_directory: config.working_directory,
@@ -871,6 +874,119 @@ const getUsage = async (ctx, rawArgs, respond) => {
         respond(null, `Usage fetch failed: ${err.message}`);
     }
 };
+/**
+ * #2056: Settings → Web appearance for the user — get_web_settings / set_web_settings, through the page's own stores and
+ * checks (web-settings-tools.ts). Who may call them is the tool profile (General, coordinator, full), at every sink.
+ */
+const getWebSettings = async (ctx, rawArgs, respond) => {
+    const v = validateArgs(GetWebSettingsArgs, rawArgs, "get_web_settings");
+    if (!v.ok) {
+        respond(null, v.error);
+        return;
+    }
+    if (!ctx.webSettings) {
+        respond(null, "get_web_settings is unavailable on this fleet");
+        return;
+    }
+    const r = ctx.webSettings.read(v.data.person);
+    if (r.ok)
+        respond(r);
+    else
+        respond(null, `get_web_settings: ${r.error}${r.detail ? ` — ${r.detail}` : ""}`);
+};
+const setWebSettings = async (ctx, rawArgs, respond) => {
+    const v = validateArgs(SetWebSettingsArgs, rawArgs, "set_web_settings");
+    if (!v.ok) {
+        respond(null, v.error);
+        return;
+    }
+    if (!ctx.webSettings) {
+        respond(null, "set_web_settings is unavailable on this fleet");
+        return;
+    }
+    try {
+        respond(ctx.webSettings.change(v.data.person, v.data.change));
+    }
+    catch (err) {
+        respond(null, `set_web_settings failed: ${err.message}`);
+    }
+};
+/**
+ * #2001: the prompt-cache report for an agent. From the last scan (cacheReportPublished: in-memory ledgers, reused
+ * for a minute) — no transcript read and no process on the fleet loop. Who sees what: cacheReportScope.
+ */
+const getCacheReport = async (ctx, rawArgs, respond, meta) => {
+    const v = validateArgs(GetCacheReportArgs, rawArgs, "get_cache_report");
+    if (!v.ok) {
+        respond(null, v.error);
+        return;
+    }
+    const caller = meta?.instanceName;
+    if (!caller) {
+        respond(null, "get_cache_report: the calling instance is unknown");
+        return;
+    }
+    if (!ctx.cacheReportPublished) {
+        respond(null, "get_cache_report is unavailable on this fleet");
+        return;
+    }
+    const { resolveToolSet, cacheReportScope } = await import("./tool-permissions.js");
+    const { cacheReportForTool } = await import("./cache-report-tool.js");
+    const scope = cacheReportScope(resolveToolSet(ctx.fleetConfig?.instances[caller], caller));
+    try {
+        const out = cacheReportForTool(await ctx.cacheReportPublished(v.data.window ?? "7d"), { scope, caller, instance: v.data.instance, top: v.data.top });
+        if ("error" in out && typeof out.error === "string")
+            respond(null, out.error);
+        else
+            respond(out);
+    }
+    catch (err) {
+        respond(null, `get_cache_report failed: ${err.message}`);
+    }
+};
+/**
+ * #2122: the usage report for an agent — the dashboard's Fleet → Usage, from the last scan (no transcript read). Who
+ * sees what: cacheReportScope (its own row, or the fleet). Every amount carries `basis`: the API-equivalent at list
+ * price, not money spent.
+ */
+const getUsageReport = async (ctx, rawArgs, respond, meta) => {
+    const v = validateArgs(GetUsageReportArgs, rawArgs, "get_usage_report");
+    if (!v.ok) {
+        respond(null, v.error);
+        return;
+    }
+    const caller = meta?.instanceName;
+    if (!caller) {
+        respond(null, "get_usage_report: the calling instance is unknown");
+        return;
+    }
+    if (!ctx.usageReport) {
+        respond(null, "get_usage_report is unavailable on this fleet");
+        return;
+    }
+    const { resolveToolSet, cacheReportScope } = await import("./tool-permissions.js");
+    const { usageRange, usageGroup } = await import("./usage-report.js");
+    const scope = cacheReportScope(resolveToolSet(ctx.fleetConfig?.instances[caller], caller));
+    if (scope === "own" && v.data.instance !== undefined && v.data.instance !== caller) {
+        respond(null, "get_usage_report: an instance reads only its own row");
+        return;
+    }
+    const only = scope === "own" ? caller : v.data.instance;
+    try {
+        const r = await ctx.usageReport({ range: usageRange(v.data.range, v.data.from, v.data.to), group: scope === "own" ? "instance" : usageGroup(v.data.group), ...(only ? { only } : {}) });
+        const top = v.data.top ?? 10;
+        respond({
+            basis: r.basis, range: r.range, zone: r.zone, granularity: r.granularity, group: r.group,
+            rows: r.rows.slice(0, top).map(row => ({ ...row, basis: r.basis })),
+            more: Math.max(0, r.rows.length - top),
+            totals: { ...r.totals, basis: r.basis },
+            notMeasured: r.notMeasured, shared: r.shared, scanning: r.scanning,
+        });
+    }
+    catch (err) {
+        respond(null, `get_usage_report failed: ${err.message}`);
+    }
+};
 /**
  * Enumerate a backend's models. Read-only and best-effort by design: the
  * catalog is an aid for picking a name, and AgEnD passes model strings through
@@ -1993,6 +2109,10 @@ export const outboundHandlers = new Map([
     ["close_poll", closePoll],
     ["kiro_engine_status", kiroEngineStatusHandler],
     ["get_usage", getUsage],
+    ["get_cache_report", getCacheReport],
+    ["get_usage_report", getUsageReport],
+    ["get_web_settings", getWebSettings],
+    ["set_web_settings", setWebSettings],
     ["list_models", listModels],
     ["get_instance_logs", getInstanceLogs],
     ["get_fleet_config", getFleetConfig],