@plainconceptsplatform/loop-task 2.6.0

package/dist/core/command/command-runner.js

@@ -0,0 +1,300 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execa } from "execa";
+import { formatDuration } from "../../duration.js";
+import { t } from "../../shared/i18n/index.js";
+import { MAX_CONTEXT_STDOUT_BYTES, MAX_SPAN_OUTPUT_BYTES } from "../../shared/config/constants.js";
+import { StdoutCaptureTransform } from "./stdout-capture-transform.js";
+import { killProcessTree } from "./process-tree.js";
+import { getAgentIntegrations } from "../../daemon/telemetry/agent-integrations/index.js";
+import { getDataDir } from "../../shared/config/paths.js";
+function quoteArg(arg) {
+    if (arg.length === 0)
+        return "''";
+    if (/^[A-Za-z0-9_\-=:./,@]+$/.test(arg))
+        return arg;
+    const cleaned = arg.replace(/[\n\r]/g, " ");
+    return "'" + cleaned.replace(/'/g, "'\\''") + "'";
+}
+function formatCommandLine(command, commandArgs) {
+    return [command, ...commandArgs.map(quoteArg)].join(" ").trim();
+}
+export function extractExitCode(error) {
+    return error && typeof error === "object" && "exitCode" in error
+        ? error.exitCode
+        : 1;
+}
+export function childEnv() {
+    if (process.env.LOOP_TASK_DEFAULTED_NODE_ENV !== "1") {
+        return process.env;
+    }
+    return {
+        ...process.env,
+        NODE_ENV: undefined,
+        LOOP_TASK_DEFAULTED_NODE_ENV: undefined,
+    };
+}
+function loadEnvFile() {
+    try {
+        const envPath = path.join(getDataDir(), "env");
+        const content = fs.readFileSync(envPath, "utf-8");
+        const env = {};
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const eq = trimmed.indexOf("=");
+            if (eq < 0)
+                continue;
+            const key = trimmed.slice(0, eq).trim();
+            const value = trimmed.slice(eq + 1).trim().replace(/^['"]|['"]$/g, "");
+            if (key)
+                env[key] = value;
+        }
+        return env;
+    }
+    catch {
+        return {};
+    }
+}
+const activePids = new Set();
+export function getActivePids() {
+    return activePids;
+}
+export function killAllActiveProcesses() {
+    for (const pid of activePids) {
+        killProcessTree(pid, "SIGTERM").catch(() => { });
+    }
+}
+export async function executeCommand(command, commandArgs, cwd, logStream, signal, runNumber, captureStdout = false, isChain = false, telemetryCtx) {
+    const startedAt = new Date();
+    if (!isChain) {
+        const header = t("loop.runHeader", { timestamp: startedAt.toLocaleString(), runNumber: runNumber ?? 0 });
+        logStream.write(header);
+    }
+    logStream.write(t("loop.commandLine", { command: formatCommandLine(command, commandArgs) }));
+    if (cwd) {
+        logStream.write(t("loop.cwdLine", { cwd }));
+    }
+    if (cwd && !fs.existsSync(cwd)) {
+        const endedAt = new Date();
+        logStream.write(t("loop.cwdMissingLog", { cwd }));
+        logStream.write(t("loop.exitMarker", { code: 1, duration: formatDuration(0) }));
+        return { exitCode: 1, duration: 0, startedAt, endedAt };
+    }
+    const shellCommand = formatCommandLine(command, commandArgs);
+    const needShell = /(\$\(|`|&&|\|\||;|>|<|\|)/.test(shellCommand);
+    // Per-task telemetry override: skip telemetry for this command entirely
+    const taskTelemetryDisabled = telemetryCtx?.telemetryConfig?.enabled === false;
+    // Telemetry: create command span and prepare child env
+    const commandSpan = (telemetryCtx && !taskTelemetryDisabled)
+        ? telemetryCtx.telemetry.startCommand({
+            command,
+            commandLine: formatCommandLine(command, commandArgs),
+            argumentCount: commandArgs.length,
+            cwd,
+            runId: telemetryCtx.runId,
+            loopId: telemetryCtx.loopId,
+            taskId: telemetryCtx.taskId,
+            taskName: telemetryCtx.taskName,
+        }, telemetryCtx.taskSpan ?? telemetryCtx.loopSpan)
+        : undefined;
+    let telemetryEnv = {};
+    let detectedIntegrationId;
+    if (telemetryCtx && telemetryCtx.telemetry.getStatus().enabled && !taskTelemetryDisabled) {
+        const traceCtx = (telemetryCtx.taskSpan ?? telemetryCtx.loopSpan)?.getTraceContext() ?? {};
+        const integrationOverride = telemetryCtx.telemetryConfig?.integration;
+        const prepared = telemetryCtx.telemetry.prepareChildProcess({ command, args: commandArgs, cwd }, {
+            runId: telemetryCtx.runId,
+            loopId: telemetryCtx.loopId,
+            loopName: telemetryCtx.loopName,
+            taskId: telemetryCtx.taskId,
+            taskName: telemetryCtx.taskName,
+            projectId: telemetryCtx.projectId,
+            projectName: telemetryCtx.projectName,
+            traceParent: traceCtx.traceParent,
+            traceState: traceCtx.traceState,
+        }, integrationOverride);
+        telemetryEnv = prepared.env;
+        detectedIntegrationId = prepared.integrationId;
+        if (detectedIntegrationId && commandSpan) {
+            commandSpan.setAttribute("loop_task.agent.integration", detectedIntegrationId);
+        }
+    }
+    const baseEnv = childEnv();
+    const fileEnv = loadEnvFile();
+    const mergedEnv = {
+        ...baseEnv,
+        ...fileEnv,
+        ...telemetryEnv,
+    };
+    const detachedOpt = process.platform !== "win32" ? { detached: true } : {};
+    const child = needShell
+        ? execa(shellCommand, {
+            stdout: "pipe",
+            stderr: "pipe",
+            stdin: "ignore",
+            buffer: false,
+            cwd: cwd || undefined,
+            cancelSignal: signal,
+            shell: true,
+            env: mergedEnv,
+            killSignal: "SIGTERM",
+            ...detachedOpt,
+        })
+        : execa(command, commandArgs, {
+            stdout: "pipe",
+            stderr: "pipe",
+            stdin: "ignore",
+            buffer: false,
+            cwd: cwd || undefined,
+            cancelSignal: signal,
+            env: mergedEnv,
+            killSignal: "SIGTERM",
+            ...detachedOpt,
+        });
+    if (child.pid) {
+        activePids.add(child.pid);
+    }
+    const stdoutCapture = (captureStdout || !!detectedIntegrationId)
+        ? new StdoutCaptureTransform(MAX_CONTEXT_STDOUT_BYTES)
+        : null;
+    const stderrCapture = (captureStdout || !!detectedIntegrationId)
+        ? new StdoutCaptureTransform(MAX_CONTEXT_STDOUT_BYTES)
+        : null;
+    if (stdoutCapture) {
+        child.stdout.pipe(stdoutCapture).pipe(logStream, { end: false });
+    }
+    else {
+        child.stdout.pipe(logStream, { end: false });
+    }
+    if (stderrCapture) {
+        child.stderr.pipe(stderrCapture).pipe(logStream, { end: false });
+    }
+    else {
+        child.stderr.pipe(logStream, { end: false });
+    }
+    try {
+        const result = await child;
+        const endedAt = new Date();
+        const duration = endedAt.getTime() - startedAt.getTime();
+        if (child.pid)
+            activePids.delete(child.pid);
+        if (stdoutCapture?.isTruncated()) {
+            logStream.write(t("context.truncationWarning"));
+        }
+        logStream.write(t("loop.exitMarker", { code: String(result.exitCode), duration: formatDuration(duration) }));
+        if (commandSpan) {
+            commandSpan.setAttribute("process.exit.code", result.exitCode ?? 0);
+            if (telemetryCtx?.telemetry.getStatus().captureCommandOutput && stdoutCapture) {
+                commandSpan.setAttribute("loop_task.command.stdout", truncateForSpan(stdoutCapture.getCaptured(), MAX_SPAN_OUTPUT_BYTES));
+            }
+        }
+        // Attempt to parse agent usage from output
+        if (detectedIntegrationId && stdoutCapture) {
+            tryParseAgentUsage(telemetryCtx.telemetry, detectedIntegrationId, { exitCode: result.exitCode ?? 0, stdout: stdoutCapture.getCaptured(), duration }, commandSpan);
+        }
+        if (commandSpan) {
+            commandSpan.ok();
+        }
+        return {
+            exitCode: result.exitCode ?? 0,
+            duration,
+            startedAt,
+            endedAt,
+            ...(captureStdout && stdoutCapture ? { stdout: stdoutCapture.getCaptured() } : {}),
+            ...(captureStdout && stderrCapture ? { stderr: stderrCapture.getCaptured() } : {}),
+        };
+    }
+    catch (error) {
+        const endedAt = new Date();
+        const duration = endedAt.getTime() - startedAt.getTime();
+        const exitCode = extractExitCode(error);
+        if (child.pid) {
+            activePids.delete(child.pid);
+            if (signal?.aborted) {
+                await killProcessTree(child.pid);
+            }
+        }
+        if (stdoutCapture?.isTruncated()) {
+            logStream.write(t("context.truncationWarning"));
+        }
+        logStream.write(t("loop.exitMarker", { code: exitCode, duration: formatDuration(duration) }));
+        if (commandSpan) {
+            commandSpan.setAttribute("process.exit.code", exitCode);
+            if (telemetryCtx?.telemetry.getStatus().captureCommandOutput && stdoutCapture) {
+                commandSpan.setAttribute("loop_task.command.stdout", truncateForSpan(stdoutCapture.getCaptured(), MAX_SPAN_OUTPUT_BYTES));
+            }
+            commandSpan.end(signal?.aborted ? "cancelled" : "error");
+        }
+        // Attempt to parse agent usage from output even on failure
+        if (detectedIntegrationId && stdoutCapture) {
+            tryParseAgentUsage(telemetryCtx.telemetry, detectedIntegrationId, { exitCode, stdout: stdoutCapture.getCaptured(), duration }, commandSpan);
+        }
+        return {
+            exitCode,
+            duration,
+            startedAt,
+            endedAt,
+            ...(captureStdout && stdoutCapture ? { stdout: stdoutCapture.getCaptured() } : {}),
+            ...(captureStdout && stderrCapture ? { stderr: stderrCapture.getCaptured() } : {}),
+        };
+    }
+}
+export async function executeCommandForeground(command, commandArgs, logger, cwd = "") {
+    const startedAt = new Date();
+    logger.debug(t("loop.executing", { command: `${command} ${commandArgs.join(" ")}` }));
+    if (cwd && !fs.existsSync(cwd)) {
+        logger.error(t("loop.cwdMissing", { cwd }));
+        const endedAt = new Date();
+        return { exitCode: 1, duration: 0, startedAt, endedAt };
+    }
+    try {
+        const result = await execa(command, commandArgs, {
+            stdout: "inherit",
+            stderr: "inherit",
+            stdin: "inherit",
+            cwd: cwd || undefined,
+            shell: true,
+            env: childEnv(),
+        });
+        const endedAt = new Date();
+        return {
+            exitCode: result.exitCode ?? 0,
+            duration: endedAt.getTime() - startedAt.getTime(),
+            startedAt,
+            endedAt,
+        };
+    }
+    catch (error) {
+        const endedAt = new Date();
+        return {
+            exitCode: extractExitCode(error),
+            duration: endedAt.getTime() - startedAt.getTime(),
+            startedAt,
+            endedAt,
+        };
+    }
+}
+function tryParseAgentUsage(telemetry, integrationId, result, span) {
+    try {
+        const integrations = getAgentIntegrations();
+        const match = integrations.find((i) => i.id === integrationId);
+        if (!match?.parseUsage)
+            return;
+        const usage = match.parseUsage(result);
+        if (usage) {
+            usage.integration = integrationId;
+            telemetry.recordAgentUsage(usage, span);
+        }
+    }
+    catch {
+        // Telemetry must never fail execution
+    }
+}
+function truncateForSpan(text, maxBytes) {
+    const buf = Buffer.from(text, "utf-8");
+    if (buf.length <= maxBytes)
+        return text;
+    return buf.subarray(0, maxBytes).toString("utf-8") + `\n... [truncated, ${buf.length} bytes total]`;
+}

package/dist/core/command/process-tree.js

@@ -0,0 +1,73 @@
+export function getDetachedSpawnOptions(base) {
+    if (process.platform === "win32") {
+        return { ...base, windowsHide: true };
+    }
+    return {
+        ...base,
+        detached: true,
+    };
+}
+const SIGKILL_TIMEOUT_MS = 5000;
+export async function killProcessTree(pid, signal = "SIGTERM") {
+    if (process.platform === "win32") {
+        try {
+            const { execa: execaSync } = await import("execa");
+            await execaSync("taskkill", ["/T", "/F", "/PID", String(pid)]);
+        }
+        catch {
+            try {
+                process.kill(pid, signal);
+            }
+            catch { /* already dead */ }
+        }
+        return;
+    }
+    const tryKill = (sig) => {
+        try {
+            process.kill(-pid, sig);
+            return true;
+        }
+        catch {
+            try {
+                process.kill(pid, sig);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+    };
+    const isAlive = () => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const killed = tryKill(signal);
+    if (!killed || !isAlive())
+        return;
+    if (signal !== "SIGKILL") {
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                if (isAlive()) {
+                    tryKill("SIGKILL");
+                }
+                resolve();
+            }, SIGKILL_TIMEOUT_MS);
+            const check = setInterval(() => {
+                if (!isAlive()) {
+                    clearTimeout(timer);
+                    clearInterval(check);
+                    resolve();
+                }
+            }, 200);
+            setTimeout(() => {
+                clearInterval(check);
+                resolve();
+            }, SIGKILL_TIMEOUT_MS + 1000);
+        });
+    }
+}

package/dist/core/command/resolve-cwd.js

@@ -0,0 +1,8 @@
+import path from "node:path";
+export function resolveEffectiveCwd(loopCwd, projectDirectory) {
+    if (!loopCwd)
+        return projectDirectory || process.cwd();
+    if (path.isAbsolute(loopCwd))
+        return loopCwd;
+    return path.join(projectDirectory || process.cwd(), loopCwd);
+}

package/dist/core/command/stdout-capture-transform.js

@@ -0,0 +1,73 @@
+import { Transform } from "node:stream";
+import { MAX_CONTEXT_STDOUT_BYTES } from "../../shared/config/constants.js";
+const KV_LINE_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+export class StdoutCaptureTransform extends Transform {
+    constructor(maxBytes = MAX_CONTEXT_STDOUT_BYTES) {
+        super({ decodeStrings: true });
+        this.captured = [];
+        this.totalBytes = 0;
+        this.truncated = false;
+        this.partialLine = "";
+        this.kvPairs = {};
+        this.maxBytes = maxBytes;
+    }
+    _transform(chunk, _encoding, callback) {
+        this.push(chunk);
+        if (this.truncated) {
+            callback();
+            return;
+        }
+        const chunkBytes = chunk.byteLength;
+        const remaining = this.maxBytes - this.totalBytes;
+        if (remaining <= 0) {
+            this.truncated = true;
+            callback();
+            return;
+        }
+        if (chunkBytes <= remaining) {
+            this.captured.push(Buffer.from(chunk));
+            this.totalBytes += chunkBytes;
+        }
+        else {
+            const slice = Buffer.from(chunk).subarray(0, remaining);
+            this.captured.push(slice);
+            this.totalBytes += slice.byteLength;
+            this.truncated = true;
+        }
+        this.extractKvFromChunk(chunk);
+        callback();
+    }
+    extractKvFromChunk(chunk) {
+        const text = chunk.toString("utf-8");
+        const combined = this.partialLine + text;
+        const lines = combined.split("\n");
+        this.partialLine = lines.pop() ?? "";
+        for (const line of lines) {
+            const match = line.trim().match(KV_LINE_RE);
+            if (match) {
+                this.kvPairs[match[1]] = match[2];
+            }
+        }
+    }
+    _flush(callback) {
+        if (this.partialLine) {
+            const match = this.partialLine.trim().match(KV_LINE_RE);
+            if (match) {
+                this.kvPairs[match[1]] = match[2];
+            }
+            this.partialLine = "";
+        }
+        callback();
+    }
+    getCaptured() {
+        if (this.captured.length === 0)
+            return "";
+        return Buffer.concat(this.captured, this.totalBytes).toString("utf-8");
+    }
+    getKvPairs() {
+        return { ...this.kvPairs };
+    }
+    isTruncated() {
+        return this.truncated;
+    }
+}

package/dist/core/context/context-parser.js

@@ -0,0 +1,65 @@
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function parseStdout(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    let whole;
+    try {
+        whole = JSON.parse(trimmed);
+    }
+    catch {
+        whole = undefined;
+    }
+    if (whole !== undefined) {
+        if (isObject(whole)) {
+            return whole;
+        }
+        if (typeof whole === "string" || typeof whole === "number" || typeof whole === "boolean" || whole === null) {
+            return { output: String(whole) };
+        }
+        if (Array.isArray(whole)) {
+            return { output: trimmed };
+        }
+    }
+    const lines = trimmed.split("\n");
+    const parsedLines = [];
+    let jsonlSuccess = true;
+    for (const line of lines) {
+        const l = line.trim();
+        if (l.length === 0)
+            continue;
+        try {
+            parsedLines.push(JSON.parse(l));
+        }
+        catch {
+            jsonlSuccess = false;
+            break;
+        }
+    }
+    if (jsonlSuccess && parsedLines.length > 0) {
+        const result = {};
+        for (const pl of parsedLines) {
+            if (isObject(pl)) {
+                Object.assign(result, pl);
+            }
+            else {
+                result.output = String(pl);
+            }
+        }
+        return result;
+    }
+    return { output: trimmed };
+}
+export function mergeCommandOutput(context, stdout, stderr) {
+    const parsed = parseStdout(stdout);
+    if (parsed !== null) {
+        Object.assign(context, parsed);
+    }
+    const output = [stdout, stderr].filter(Boolean).join("\n").trim();
+    if (output.length > 0) {
+        context.output = output;
+    }
+}

package/dist/core/context/log-context.js

@@ -0,0 +1,3 @@
+export function formatContextLog(context) {
+    return `${JSON.stringify(context)}\n`;
+}

package/dist/core/context/template.js

@@ -0,0 +1,20 @@
+function shellEscape(value) {
+    if (value.length === 0)
+        return '""';
+    // If the value is purely safe characters, pass it through unmodified
+    if (/^[A-Za-z0-9_\-=:./,@]+$/.test(value))
+        return value;
+    // Escape characters that are dangerous inside double quotes, then wrap
+    // the whole value in single quotes  the strongest shell quoting.
+    // Single quotes preserve everything literally (newlines, backticks,
+    // $, ", \, parens) except single quotes themselves.
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+export function interpolate(input, context) {
+    return input.replace(/{{(\w+)}}/g, (_, key) => {
+        const raw = context[key];
+        if (raw === undefined || raw === null)
+            return "";
+        return shellEscape(String(raw));
+    });
+}

package/dist/core/context/validate-context.js

@@ -0,0 +1,19 @@
+export function validateContext(value) {
+    if (value === undefined || value === null) {
+        return { valid: true, context: {} };
+    }
+    if (typeof value !== "object" || Array.isArray(value) || value === null) {
+        return { valid: false, error: "Context must be a JSON object" };
+    }
+    const obj = value;
+    for (const key of Object.keys(obj)) {
+        const v = obj[key];
+        if (Array.isArray(v)) {
+            return { valid: false, error: `Context key "${key}" has an array  only string values are allowed` };
+        }
+        if (typeof v === "object" && v !== null) {
+            return { valid: false, error: `Context key "${key}" has a nested object  only string values are allowed` };
+        }
+    }
+    return { valid: true, context: obj };
+}

package/dist/core/foreground/index.js

@@ -0,0 +1,81 @@
+import { formatDuration } from "../../duration.js";
+import { t } from "../../shared/i18n/index.js";
+import { sleep } from "../../shared/sleep.js";
+import { executeCommandForeground } from "../command/command-runner.js";
+export async function runLoop(options, logger, signal) {
+    const state = {
+        running: false,
+        runCount: 0,
+        shuttingDown: false,
+    };
+    const onSignal = () => {
+        state.shuttingDown = true;
+        logger.info(t("loop.shuttingDown"));
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    const command = options.command;
+    const commandArgs = options.commandArgs;
+    const cwd = options.cwd;
+    try {
+        let isFirstRun = true;
+        while (!state.shuttingDown) {
+            if (options.maxRuns !== null &&
+                state.runCount >= options.maxRuns) {
+                logger.info(t("loop.completed", { runs: state.runCount }));
+                break;
+            }
+            if (isFirstRun && !options.immediate) {
+                logger.info(t("loop.waitingFirst", { duration: formatDuration(options.interval) }));
+                try {
+                    await sleep(options.interval, signal);
+                }
+                catch {
+                    break;
+                }
+                if (state.shuttingDown)
+                    break;
+            }
+            isFirstRun = false;
+            state.running = true;
+            state.runCount++;
+            logger.info(t("loop.runSeparator", {
+                run: state.runCount,
+                maxRuns: options.maxRuns !== null ? `/${options.maxRuns}` : "",
+            }));
+            const result = await executeCommandForeground(command, commandArgs, logger, cwd);
+            state.running = false;
+            if (result.exitCode !== 0) {
+                logger.error(t("loop.commandFailed", { code: result.exitCode }));
+            }
+            if (options.verbose) {
+                logger.debug(t("loop.debugStartedAt", { timestamp: result.startedAt.toISOString() }));
+                logger.debug(t("loop.debugEndedAt", { timestamp: result.endedAt.toISOString() }));
+                logger.debug(t("loop.debugExitCode", { code: result.exitCode }));
+                logger.debug(t("loop.debugDuration", { duration: formatDuration(result.duration) }));
+            }
+            if (state.shuttingDown)
+                break;
+            if (options.maxRuns !== null &&
+                state.runCount >= options.maxRuns) {
+                logger.info(t("loop.completed", { runs: state.runCount }));
+                break;
+            }
+            const nextRun = new Date(Date.now() + options.interval);
+            logger.info(t("loop.nextRun", {
+                duration: formatDuration(options.interval),
+                time: nextRun.toLocaleTimeString(),
+            }));
+            try {
+                await sleep(options.interval, signal);
+            }
+            catch {
+                break;
+            }
+        }
+    }
+    finally {
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+    }
+}