@rk0429/agentic-relay 22.3.0 → 22.4.0

package/dist/bin/relay.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { AgentManagementService } from "../application/agent-management-service.js";
 import { ChatDaemonService, } from "../application/chat/chat-daemon-service.js";
 import { ChatInboundHandler } from "../application/chat/chat-inbound-handler.js";
 import { ChatOutboundHandler } from "../application/chat/chat-outbound-handler.js";
@@ -306,6 +307,33 @@ async function main() {
         }
         return;
     }
+    if (command.kind === "agent-list" ||
+        command.kind === "agent-show" ||
+        command.kind === "agent-stop" ||
+        command.kind === "agent-log") {
+        const agentService = new AgentManagementService({ store });
+        const exitCode = await handleAgentCommand(command, {
+            service: agentService,
+            stdout: process.stdout,
+            stderr: process.stderr,
+            now: () => new Date(),
+            fileExists: async (filePath) => {
+                try {
+                    await access(filePath);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            readTextFile: (filePath) => readFile(filePath, "utf8"),
+            readFileStream: createFollowReader(),
+        });
+        if (exitCode !== undefined) {
+            process.exitCode = exitCode;
+        }
+        return;
+    }
     if (command.kind === "chat-setup" ||
         command.kind === "chat-start" ||
         command.kind === "chat-stop" ||
@@ -351,6 +379,7 @@ async function main() {
         const server = createRelayMcpServer({
             service,
             taskService,
+            agentManagementService: new AgentManagementService({ store }),
             store,
             routineStatusQueryService: buildRoutineStatusQueryService({
                 store,
@@ -633,6 +662,72 @@ export async function handleRoutineCommand(command, dependencies) {
         }
     }
 }
+export async function handleAgentCommand(command, dependencies) {
+    switch (command.kind) {
+        case "agent-list": {
+            const agents = await dependencies.service.listActiveAgents({
+                includeStale: command.includeStale,
+            });
+            if (command.format === "json") {
+                dependencies.stdout.write(`${JSON.stringify(agents, null, 2)}\n`);
+                return 0;
+            }
+            dependencies.stdout.write(renderAgentTable(agents));
+            return 0;
+        }
+        case "agent-show": {
+            const detail = await dependencies.service.getAgentDetail({
+                relaySessionId: command.relaySessionId,
+            });
+            if (!detail) {
+                writeLine(dependencies.stderr, `No session found for relay session id: ${command.relaySessionId}`);
+                return 1;
+            }
+            dependencies.stdout.write(renderAgentDetail(detail));
+            return 0;
+        }
+        case "agent-stop": {
+            const result = await dependencies.service.stopAgent({
+                relaySessionId: command.relaySessionId,
+                actorId: dependencies.actorId ?? "local-cli-operator",
+                gracePeriodMs: command.gracePeriodMs,
+            });
+            if (command.format === "json") {
+                dependencies.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return 0;
+            }
+            writeLine(dependencies.stdout, renderStopAgentResult(result));
+            return 0;
+        }
+        case "agent-log": {
+            const logPath = dependencies.service.readSessionLogPath({
+                relaySessionId: command.relaySessionId,
+                now: dependencies.now(),
+            });
+            const exists = await dependencies.fileExists(logPath);
+            if (!exists) {
+                writeLine(dependencies.stderr, `No log file found for today at ${logPath}.`);
+                return 1;
+            }
+            const raw = await dependencies.readTextFile(logPath);
+            for (const line of filterAgentLogLines(raw, command.relaySessionId)) {
+                writeLine(dependencies.stdout, line);
+            }
+            if (!command.follow) {
+                return 0;
+            }
+            if (!dependencies.readFileStream) {
+                throw new ValidationError("Agent log follow is unavailable in this environment.");
+            }
+            await dependencies.readFileStream(logPath, {
+                follow: true,
+                sessionId: command.relaySessionId,
+                onLine: (line) => writeLine(dependencies.stdout, line),
+            });
+            return undefined;
+        }
+    }
+}
 async function suppressLoopStateWarnings(fn) {
     const origWarn = console.warn;
     console.warn = (...args) => {
@@ -655,6 +750,9 @@ export function renderHelpText(topic, scriptName = path.basename(fileURLToPath(i
         if (isRoutineHelpTopic(topic)) {
             return renderRoutineHelp(topic, scriptName);
         }
+        if (isAgentHelpTopic(topic)) {
+            return renderAgentHelp(topic, scriptName);
+        }
         if (isChatHelpTopic(topic)) {
             return renderChatHelp(topic, scriptName);
         }
@@ -669,6 +767,10 @@ export function renderHelpText(topic, scriptName = path.basename(fileURLToPath(i
         `       ${scriptName} routine cleanup [--config <dir>] [--dry-run]`,
         `       ${scriptName} routine list [--config <dir>] [--format <table|tsv|json>]`,
         `       ${scriptName} routine status [name] [--config <dir>] [--format <table|tsv|json>] [--limit <n>] [--run-id <uuid>]`,
+        `       ${scriptName} agent list [--include-stale] [--format <table|json>]`,
+        `       ${scriptName} agent show <session-id>`,
+        `       ${scriptName} agent stop <session-id> [--grace-ms <n>] [--json]`,
+        `       ${scriptName} agent log <session-id> [--follow]`,
         `       ${scriptName} chat setup (--slack | --discord) [--tokens-only]`,
         `       ${scriptName} chat start [--foreground]`,
         `       ${scriptName} chat stop`,
@@ -687,6 +789,10 @@ export function renderHelpText(topic, scriptName = path.basename(fileURLToPath(i
         `  ${commandName} routine cleanup [options]  Remove stale routine metadata`,
         `  ${commandName} routine list   [options]  List known routines`,
         `  ${commandName} routine status [options]  Show routine status details`,
+        `  ${commandName} agent list    [options]  List active agent processes`,
+        `  ${commandName} agent show    [options]  Show one agent session`,
+        `  ${commandName} agent stop    [options]  Stop one running agent`,
+        `  ${commandName} agent log     [options]  Show session logs for one agent`,
         `  ${commandName} chat setup   [options]  Configure Slack or Discord integration`,
         `  ${commandName} chat start   [options]  Start the chat daemon`,
         `  ${commandName} chat stop               Stop the chat daemon`,
@@ -746,9 +852,71 @@ function renderCoreSubcommandHelp(topic, scriptName) {
 function isRoutineHelpTopic(topic) {
     return topic.startsWith("routine");
 }
+function isAgentHelpTopic(topic) {
+    return topic.startsWith("agent");
+}
 function isChatHelpTopic(topic) {
     return topic.startsWith("chat");
 }
+function renderAgentHelp(topic, scriptName) {
+    if (topic === "agent") {
+        return renderAgentAggregateHelp(scriptName);
+    }
+    const commandName = path.parse(scriptName).name;
+    const allSubcommandsReference = `See '${commandName} agent --help' for all subcommands.`;
+    switch (topic) {
+        case "agent-list":
+            return [
+                `Usage: ${scriptName} agent list [options]`,
+                "",
+                "List active agent processes.",
+                "",
+                "Options:",
+                "  --include-stale       Include stale agent sessions",
+                "  --format <fmt>        Output format (table, json)",
+                "  --json                Alias for --format json",
+                "  -h, --help            Show this help",
+                "",
+                allSubcommandsReference,
+            ].join("\n");
+        case "agent-show":
+            return [
+                `Usage: ${scriptName} agent show <session-id>`,
+                "",
+                "Show one agent session and its related task.",
+                "",
+                "Options:",
+                "  -h, --help            Show this help",
+                "",
+                allSubcommandsReference,
+            ].join("\n");
+        case "agent-stop":
+            return [
+                `Usage: ${scriptName} agent stop <session-id> [options]`,
+                "",
+                "Stop one running agent process.",
+                "",
+                "Options:",
+                "  --grace-ms <n>        SIGTERM grace period before SIGKILL (0-600000)",
+                "  --json                Output StopAgentResult as JSON",
+                "  -h, --help            Show this help",
+                "",
+                allSubcommandsReference,
+            ].join("\n");
+        case "agent-log":
+            return [
+                `Usage: ${scriptName} agent log <session-id> [options]`,
+                "",
+                "Show session logs for one agent.",
+                "",
+                "Options:",
+                "  --follow              Follow appended log lines",
+                "  -h, --help            Show this help",
+                "",
+                allSubcommandsReference,
+            ].join("\n");
+    }
+}
 function renderChatHelp(topic, scriptName) {
     if (topic === "chat") {
         return [
@@ -952,9 +1120,199 @@ function renderRoutineAggregateHelp(scriptName) {
         "  -h, --help            Show this help",
     ].join("\n");
 }
+function renderAgentAggregateHelp(scriptName) {
+    return [
+        `Usage: ${scriptName} agent list [options]`,
+        `       ${scriptName} agent show <session-id>`,
+        `       ${scriptName} agent stop <session-id> [options]`,
+        `       ${scriptName} agent log <session-id> [options]`,
+        "",
+        "Agent commands:",
+        "  list              List active agent processes",
+        "  show              Show one agent session",
+        "  stop              Stop one running agent",
+        "  log               Show session logs for one agent",
+        "",
+        "Options:",
+        "  --include-stale       Include stale agent sessions",
+        "  --format <fmt>        Output format for `agent list` (table, json)",
+        "  --json                Alias for JSON output (`agent list`, `agent stop`)",
+        "  --grace-ms <n>        SIGTERM grace period before SIGKILL (0-600000)",
+        "  --follow              Follow appended log lines",
+        "  -h, --help            Show this help",
+    ].join("\n");
+}
 function printHelp(topic) {
     console.error(renderHelpText(topic));
 }
+function renderAgentTable(agents) {
+    if (agents.length === 0) {
+        return "No active agents.\n";
+    }
+    const headers = ["agent_id", "session_id", "role", "backend", "running_for", "status"];
+    const rows = agents.map((agent) => [
+        agent.agent_id,
+        agent.relay_session_id.slice(0, 8),
+        agent.role ?? "-",
+        agent.backend ?? "-",
+        formatRunningFor(agent.running_for_seconds),
+        agent.status,
+    ]);
+    const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column].length)));
+    const lines = [
+        headers.map((header, column) => header.padEnd(widths[column])).join("  "),
+        ...rows.map((row) => row.map((cell, column) => cell.padEnd(widths[column])).join("  ")),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+function formatRunningFor(totalSeconds) {
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    return [hours, minutes, seconds]
+        .map((value) => String(value).padStart(2, "0"))
+        .join(":");
+}
+function renderAgentDetail(detail) {
+    const metadataOrder = [
+        "relaySessionId",
+        "agentId",
+        "role",
+        "parentRelaySessionId",
+        "continuationKind",
+        "backend",
+        "backendSessionId",
+        "ownerPid",
+        "ownerStartedAt",
+        "backendChildPid",
+        "backendChildObservedAt",
+        "status",
+        "phase",
+        "taskType",
+        "cwd",
+        "createdAt",
+        "updatedAt",
+        "lastHeartbeatAt",
+        "lastProgressAt",
+        "handoffFrom",
+    ];
+    const lines = metadataOrder
+        .flatMap((key) => {
+        const value = detail.metadata[key];
+        return value === undefined ? [] : [`${key}: ${formatAgentValue(value)}`];
+    });
+    if (detail.task) {
+        lines.push("", "Task:");
+        lines.push(`  title: ${detail.task.title}`);
+        lines.push(`  status: ${detail.task.status}`);
+    }
+    if (detail.metadata.stopRequestedAt && detail.metadata.stopRequestedBy) {
+        lines.push("", "Stop history:");
+        lines.push(`  requested_at: ${detail.metadata.stopRequestedAt}`);
+        lines.push(`  requested_by: ${detail.metadata.stopRequestedBy}`);
+        if (detail.metadata.stopReason) {
+            lines.push(`  reason: ${detail.metadata.stopReason}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function formatAgentValue(value) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+function renderStopAgentResult(result) {
+    switch (result.kind) {
+        case "stopped":
+            return `Stopped agent (pid ${result.pid}) after ${result.durationMs}ms.`;
+        case "killed":
+            return `Force-killed agent (pid ${result.pid}) after SIGTERM grace.`;
+        case "no_child":
+            return "No child process recorded — nothing to stop.";
+        case "already_exited":
+            return `Child process (pid ${result.pid}) has already exited.`;
+    }
+}
+function filterAgentLogLines(raw, relaySessionId) {
+    return raw
+        .split(/\r?\n/u)
+        .filter((line) => line.length > 0)
+        .filter((line) => matchesAgentLogLine(line, relaySessionId));
+}
+function matchesAgentLogLine(line, relaySessionId) {
+    try {
+        const parsed = JSON.parse(line);
+        return parsed.session_id === relaySessionId;
+    }
+    catch {
+        return false;
+    }
+}
+function createFollowReader() {
+    return async (filePath, options) => {
+        let cursor = 0;
+        let buffer = "";
+        try {
+            cursor = (await readFile(filePath, "utf8")).length;
+        }
+        catch {
+            cursor = 0;
+        }
+        const flushAppended = async () => {
+            const content = await readFile(filePath, "utf8");
+            if (content.length < cursor) {
+                cursor = 0;
+                buffer = "";
+            }
+            if (content.length === cursor) {
+                return;
+            }
+            buffer += content.slice(cursor);
+            cursor = content.length;
+            const segments = buffer.split(/\r?\n/u);
+            buffer = segments.pop() ?? "";
+            for (const line of segments) {
+                if (matchesAgentLogLine(line, options.sessionId)) {
+                    options.onLine(line);
+                }
+            }
+        };
+        if (!options.follow) {
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearInterval(timer);
+                process.off("SIGINT", onSigint);
+                options.signal?.removeEventListener("abort", onAbort);
+                resolve();
+            };
+            const fail = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearInterval(timer);
+                process.off("SIGINT", onSigint);
+                options.signal?.removeEventListener("abort", onAbort);
+                reject(error);
+            };
+            const onAbort = () => cleanup();
+            const onSigint = () => cleanup();
+            const timer = setInterval(() => {
+                void flushAppended().catch(fail);
+            }, 1000);
+            process.once("SIGINT", onSigint);
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    };
+}
 function createRoutineCatalogLoader(allowCommandRun) {
     return async (yamlPath, repo, vars) => {
         const loaded = await loadRoutine(yamlPath, repo, vars);