akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/tasks/backends/launchd.js

@@ -0,0 +1,187 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * launchd backend for `akm tasks` (macOS default).
+ *
+ * Each task is written as a per-user LaunchAgent plist at
+ * `~/Library/LaunchAgents/com.akm.task.<id>.plist` and registered via
+ * `launchctl bootstrap gui/<uid> <plist>`. Disabling uses
+ * `launchctl disable gui/<uid>/<label>` and re-enabling uses `enable`.
+ *
+ * Platform notes:
+ *   • The `bootstrap` / `bootout` / `enable` / `disable` subcommands require
+ *     macOS 10.10 (Yosemite) or newer. On older systems the equivalents
+ *     are `launchctl load -w` / `unload -w`. We only target modern macOS.
+ *   • `gui/<uid>` is the per-user GUI launchd domain — agents in this
+ *     domain only run while the user is logged in (no background runs at
+ *     the loginwindow). Tasks that need to run when the user is logged
+ *     out should be installed as system Daemons, which is out of scope.
+ *
+ * Tests inject a fake exec + filesystem so the backend can be unit-tested
+ * without touching the host launchctl.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ConfigError } from "../../core/errors";
+import { getTaskLogDir } from "../../core/paths";
+import { resolveAkmInvocation } from "../resolveAkmBin";
+import { parseSchedule, translateToLaunchd } from "../schedule";
+import { escapeXml, spawnCommand } from "./exec-utils";
+import launchdTemplate from "./launchd-template.xml" with { type: "text" };
+export const LAUNCHD_LABEL_PREFIX = "com.akm.task.";
+export function LAUNCHD_BACKEND(options = {}) {
+    const exec = options.exec ?? defaultLaunchdExec();
+    const fsLike = options.fs ?? defaultLaunchdFs();
+    const agentsDir = options.agentsDir ?? defaultAgentsDir();
+    const logDir = options.logDir ?? getTaskLogDir();
+    const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
+    const plistPath = (id) => path.join(agentsDir, `${LAUNCHD_LABEL_PREFIX}${id}.plist`);
+    const label = (id) => `${LAUNCHD_LABEL_PREFIX}${id}`;
+    const target = (id) => `gui/${exec.uid()}/${label(id)}`;
+    return {
+        name: "launchd",
+        install(task) {
+            // Capture PATH at install time so launchd (which strips the environment
+            // aggressively) can find the same binaries the user sees interactively.
+            let pathEnv;
+            if (options.envPath === false) {
+                pathEnv = undefined;
+            }
+            else if (typeof options.envPath === "string") {
+                pathEnv = options.envPath;
+            }
+            else {
+                pathEnv = process.env.PATH ?? "";
+            }
+            const xml = buildPlistXml(task, akmArgv, logDir, pathEnv);
+            fsLike.ensureDir(agentsDir);
+            // launchd refuses to start a job when StandardOutPath/StandardErrorPath
+            // points at a non-existent directory; create it before bootstrap.
+            fsLike.ensureDir(logDir);
+            fsLike.writeFile(plistPath(task.id), xml);
+            const bootout = exec.run(["launchctl", "bootout", target(task.id)]);
+            // bootout returning non-zero is fine — agent might not be loaded.
+            void bootout;
+            const bootstrap = exec.run(["launchctl", "bootstrap", `gui/${exec.uid()}`, plistPath(task.id)]);
+            if (bootstrap.status !== 0) {
+                throw new ConfigError(`launchctl bootstrap failed (exit ${bootstrap.status}): ${bootstrap.stderr || bootstrap.stdout || "no output"}.`, "INVALID_CONFIG_FILE", "Ensure `launchctl` is available; on macOS it is part of the base system.");
+            }
+            if (!task.enabled) {
+                const disable = exec.run(["launchctl", "disable", target(task.id)]);
+                if (disable.status !== 0) {
+                    throw new ConfigError(`launchctl disable failed: ${disable.stderr || disable.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+                }
+            }
+        },
+        uninstall(id) {
+            // Bootout first (may fail if agent never loaded — that's fine).
+            exec.run(["launchctl", "bootout", target(id)]);
+            const file = plistPath(id);
+            if (fsLike.exists(file))
+                fsLike.removeFile(file);
+        },
+        setEnabled(id, enabled) {
+            const verb = enabled ? "enable" : "disable";
+            const r = exec.run(["launchctl", verb, target(id)]);
+            if (r.status !== 0) {
+                throw new ConfigError(`launchctl ${verb} failed: ${r.stderr || r.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+            }
+        },
+        list() {
+            if (!fsLike.exists(agentsDir))
+                return [];
+            const ids = [];
+            for (const file of fsLike.list(agentsDir)) {
+                if (file.startsWith(LAUNCHD_LABEL_PREFIX) && file.endsWith(".plist")) {
+                    ids.push(file.slice(LAUNCHD_LABEL_PREFIX.length, -".plist".length));
+                }
+            }
+            return ids.map((id) => ({ id }));
+        },
+    };
+}
+// ── XML builder (exported for tests) ────────────────────────────────────────
+export function buildPlistXml(task, akmArgv, logDir, pathEnv) {
+    const spec = parseSchedule(task.schedule, "launchd");
+    const trigger = translateToLaunchd(spec);
+    const argv = [...akmArgv, "tasks", "run", task.id];
+    const programArgs = argv.map((a) => `      <string>${escapeXml(a)}</string>`).join("\n");
+    const logPath = path.join(logDir, `${task.id}.log`);
+    const triggerXml = renderLaunchdTrigger(trigger);
+    const envVarsXml = pathEnv !== undefined
+        ? `  <key>EnvironmentVariables</key>\n  <dict>\n    <key>PATH</key>\n    <string>${escapeXml(pathEnv)}</string>\n  </dict>\n`
+        : "";
+    return launchdTemplate
+        .replace("{{LABEL}}", LAUNCHD_LABEL_PREFIX + escapeXml(task.id))
+        .replace("{{PROGRAM_ARGS}}", programArgs)
+        .replaceAll("{{LOG_PATH}}", escapeXml(logPath))
+        .replace("{{ENV_VARS}}", envVarsXml)
+        .replace("{{TRIGGER_XML}}", triggerXml);
+}
+function renderLaunchdTrigger(trigger) {
+    if (trigger.intervalSeconds !== undefined) {
+        return `  <key>StartInterval</key>
+  <integer>${trigger.intervalSeconds}</integer>`;
+    }
+    const cal = trigger.calendar ?? {};
+    const lines = ["  <key>StartCalendarInterval</key>", "  <dict>"];
+    if (cal.Minute !== undefined)
+        lines.push(`    <key>Minute</key><integer>${cal.Minute}</integer>`);
+    if (cal.Hour !== undefined)
+        lines.push(`    <key>Hour</key><integer>${cal.Hour}</integer>`);
+    if (cal.Day !== undefined)
+        lines.push(`    <key>Day</key><integer>${cal.Day}</integer>`);
+    if (cal.Month !== undefined)
+        lines.push(`    <key>Month</key><integer>${cal.Month}</integer>`);
+    if (cal.Weekday !== undefined)
+        lines.push(`    <key>Weekday</key><integer>${cal.Weekday}</integer>`);
+    lines.push("  </dict>");
+    return lines.join("\n");
+}
+function defaultAgentsDir() {
+    // launchd's per-user LaunchAgents live under the user's home directory.
+    // If we can't determine HOME, refuse rather than silently producing a
+    // relative path that would write somewhere unexpected.
+    const home = os.homedir();
+    if (!home) {
+        throw new ConfigError("Cannot determine user home directory; launchd backend requires HOME to locate ~/Library/LaunchAgents.", "INVALID_CONFIG_FILE", "Set $HOME (POSIX) or the equivalent before running `akm tasks` on macOS.");
+    }
+    return path.join(home, "Library", "LaunchAgents");
+}
+function defaultLaunchdExec() {
+    return {
+        run(args) {
+            return spawnCommand(args);
+        },
+        uid() {
+            const fn = process.getuid;
+            return typeof fn === "function" ? fn.call(process) : 0;
+        },
+    };
+}
+function defaultLaunchdFs() {
+    return {
+        writeFile(file, content) {
+            fs.writeFileSync(file, content, { encoding: "utf8" });
+        },
+        removeFile(file) {
+            fs.rmSync(file, { force: true });
+        },
+        ensureDir(dir) {
+            fs.mkdirSync(dir, { recursive: true });
+        },
+        list(dir) {
+            try {
+                return fs.readdirSync(dir);
+            }
+            catch {
+                return [];
+            }
+        },
+        exists(file) {
+            return fs.existsSync(file);
+        },
+    };
+}

package/dist/tasks/backends/schtasks-template.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>akm scheduled task: {{TASK_ID}}</Description>
+    <URI>{{FOLDER}}{{TASK_ID}}</URI>
+  </RegistrationInfo>
+  <Triggers>
+{{TRIGGER_XML}}
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <Enabled>{{ENABLED}}</Enabled>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>{{COMMAND}}</Command>
+      <Arguments>{{ARGS}}</Arguments>
+    </Exec>
+  </Actions>
+  <!-- Log target (informational only; schtasks doesn't redirect): {{LOG_PATH}} -->
+</Task>

package/dist/tasks/backends/schtasks.js

@@ -0,0 +1,215 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * schtasks.exe backend for `akm tasks` (Windows default).
+ *
+ * Each task is registered under the `\akm\` Task Scheduler folder so the
+ * backend never touches user-managed tasks. The full task definition is
+ * sent through `schtasks /Create /TN \akm\<id> /XML <path>` so we can
+ * express triggers/principals/actions without quoting hell.
+ *
+ * Platform notes:
+ *   • `LogonType=InteractiveToken` means the task runs in the context of
+ *     the registering user only when they are logged in — there is no
+ *     stored password and the task will not fire at the lock screen.
+ *   • `<Principal>` deliberately omits `<UserId>`; per the Task Scheduler
+ *     2.0 schema (`principalType.UserId` minOccurs=0) this is valid and
+ *     defaults to the registering user.
+ *   • `<DisallowStartIfOnBatteries>false</…>` and `<StopIfGoingOnBatteries>
+ *     false</…>` allow the task to run on battery — utility tasks would
+ *     otherwise be silently skipped on laptops.
+ *   • `MultipleInstancesPolicy=IgnoreNew` makes overlapping triggers safe:
+ *     while a task is still running, a new fire is dropped rather than
+ *     queued or run in parallel.
+ *   • `/Query /FO CSV /NH` (without `/V`) outputs three columns:
+ *     `TaskName,Next Run Time,Status` — so the regex anchors on the task
+ *     name as the leading quoted field. Adding `/V` would shift HostName
+ *     into column 0; we deliberately don't.
+ *
+ * Tests inject a fake exec + filesystem.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ConfigError } from "../../core/errors";
+import { getTaskLogDir } from "../../core/paths";
+import { resolveAkmInvocation } from "../resolveAkmBin";
+import { parseSchedule, translateToSchtasks } from "../schedule";
+import { escapeXml, spawnCommand } from "./exec-utils";
+import schtasksTemplate from "./schtasks-template.xml" with { type: "text" };
+export const DEFAULT_FOLDER_PREFIX = "\\akm\\";
+export function SCHTASKS_BACKEND(options = {}) {
+    const exec = options.exec ?? defaultSchtasksExec();
+    const fsLike = options.fs ?? defaultSchtasksFs();
+    const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
+    const logDir = options.logDir ?? getTaskLogDir();
+    const folder = options.folderPrefix ?? DEFAULT_FOLDER_PREFIX;
+    const taskName = (id) => `${folder}${id}`;
+    return {
+        name: "schtasks",
+        install(task) {
+            fsLike.ensureDir(logDir);
+            const xml = buildSchtasksXml(task, akmArgv, logDir, { folderPrefix: folder });
+            const tmpFile = path.join(fsLike.tmpdir(), `akm-task-${task.id}-${Date.now()}.xml`);
+            fsLike.writeFile(tmpFile, xml);
+            try {
+                // /F forces overwrite if a task with the same name exists.
+                const r = exec.run(["schtasks", "/Create", "/TN", taskName(task.id), "/XML", tmpFile, "/F"]);
+                if (r.status !== 0) {
+                    throw new ConfigError(`schtasks /Create failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+                }
+                if (!task.enabled) {
+                    const dis = exec.run(["schtasks", "/Change", "/TN", taskName(task.id), "/DISABLE"]);
+                    if (dis.status !== 0) {
+                        throw new ConfigError(`schtasks /Change /DISABLE failed: ${dis.stderr || dis.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+                    }
+                }
+            }
+            finally {
+                fsLike.removeFile(tmpFile);
+            }
+        },
+        uninstall(id) {
+            const r = exec.run(["schtasks", "/Delete", "/TN", taskName(id), "/F"]);
+            if (r.status !== 0 && !/cannot find/i.test(r.stderr ?? "")) {
+                throw new ConfigError(`schtasks /Delete failed: ${r.stderr || r.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+            }
+        },
+        setEnabled(id, enabled) {
+            const flag = enabled ? "/ENABLE" : "/DISABLE";
+            const r = exec.run(["schtasks", "/Change", "/TN", taskName(id), flag]);
+            if (r.status !== 0) {
+                throw new ConfigError(`schtasks /Change ${flag} failed: ${r.stderr || r.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
+            }
+        },
+        list() {
+            const r = exec.run(["schtasks", "/Query", "/FO", "CSV", "/NH"]);
+            if (r.status !== 0)
+                return [];
+            const ids = [];
+            for (const line of (r.stdout ?? "").split(/\r?\n/)) {
+                const m = line.match(/^"([^"]+)",/);
+                if (!m)
+                    continue;
+                const name = m[1];
+                if (name.startsWith(folder)) {
+                    ids.push(name.slice(folder.length));
+                }
+            }
+            return ids.map((id) => ({ id }));
+        },
+    };
+}
+export function buildSchtasksXml(task, akmArgv, logDir, options = {}) {
+    const folder = options.folderPrefix ?? DEFAULT_FOLDER_PREFIX;
+    const now = options.now ? options.now() : new Date();
+    const startBoundary = formatStartBoundary(now);
+    const spec = parseSchedule(task.schedule, "schtasks");
+    const trigger = translateToSchtasks(spec);
+    const command = akmArgv[0];
+    const args = [...akmArgv.slice(1), "tasks", "run", task.id].map((a) => quoteArg(a)).join(" ");
+    const triggerXml = renderSchtasksTrigger(trigger, startBoundary);
+    const logPath = path.join(logDir, `${task.id}.log`);
+    return schtasksTemplate
+        .replaceAll("{{TASK_ID}}", escapeXml(task.id))
+        .replaceAll("{{FOLDER}}", escapeXml(folder))
+        .replace("{{TRIGGER_XML}}", triggerXml)
+        .replace("{{ENABLED}}", task.enabled ? "true" : "false")
+        .replace("{{COMMAND}}", escapeXml(command))
+        .replace("{{ARGS}}", escapeXml(args))
+        .replace("{{LOG_PATH}}", escapeXml(logPath));
+}
+function renderSchtasksTrigger(trigger, startBoundary) {
+    switch (trigger.kind) {
+        case "minute":
+            return `    <TimeTrigger>
+      <Repetition>
+        <Interval>PT${trigger.everyMinutes}M</Interval>
+      </Repetition>
+      <StartBoundary>${startBoundary}</StartBoundary>
+      <Enabled>true</Enabled>
+    </TimeTrigger>`;
+        case "hour":
+            return `    <TimeTrigger>
+      <Repetition>
+        <Interval>PT${trigger.everyHours}H</Interval>
+      </Repetition>
+      <StartBoundary>${startBoundary}</StartBoundary>
+      <Enabled>true</Enabled>
+    </TimeTrigger>`;
+        case "daily":
+            return `    <CalendarTrigger>
+      <StartBoundary>${pad(startBoundary, trigger.atHour, trigger.atMinute)}</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByDay><DaysInterval>1</DaysInterval></ScheduleByDay>
+    </CalendarTrigger>`;
+        case "weekly": {
+            const dayMap = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+            const days = trigger.daysOfWeek.map((d) => `        <${dayMap[d]} />`).join("\n");
+            return `    <CalendarTrigger>
+      <StartBoundary>${pad(startBoundary, trigger.atHour, trigger.atMinute)}</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByWeek>
+        <DaysOfWeek>
+${days}
+        </DaysOfWeek>
+        <WeeksInterval>1</WeeksInterval>
+      </ScheduleByWeek>
+    </CalendarTrigger>`;
+        }
+    }
+}
+function pad(base, hour, minute) {
+    // Rewrite the time component of an ISO-8601 boundary while preserving
+    // the date so daily/weekly triggers fire at the configured wall-clock
+    // time rather than the install instant.
+    const hh = String(hour).padStart(2, "0");
+    const mm = String(minute).padStart(2, "0");
+    return base.replace(/T\d\d:\d\d:\d\d$/, `T${hh}:${mm}:00`);
+}
+function formatStartBoundary(d) {
+    // Local-time ISO-8601 (no zone suffix) — Task Scheduler interprets a
+    // bare boundary in the registering user's timezone, which matches what
+    // a user typing "0 9 * * *" intuitively means ("9am local").
+    const yyyy = d.getFullYear();
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    const dd = String(d.getDate()).padStart(2, "0");
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mi = String(d.getMinutes()).padStart(2, "0");
+    const ss = String(d.getSeconds()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd}T${hh}:${mi}:${ss}`;
+}
+function quoteArg(s) {
+    if (/^[A-Za-z0-9_\-./@:%=+,\\]+$/.test(s))
+        return s;
+    return `"${s.replace(/"/g, '\\"')}"`;
+}
+function defaultSchtasksExec() {
+    return {
+        run(args) {
+            return spawnCommand(args);
+        },
+    };
+}
+function defaultSchtasksFs() {
+    return {
+        writeFile(file, content) {
+            fs.writeFileSync(file, content, { encoding: "utf8" });
+        },
+        removeFile(file) {
+            try {
+                fs.rmSync(file, { force: true });
+            }
+            catch {
+                /* ignore */
+            }
+        },
+        ensureDir(dir) {
+            fs.mkdirSync(dir, { recursive: true });
+        },
+        tmpdir() {
+            return os.tmpdir();
+        },
+    };
+}

package/dist/tasks/parser.js

@@ -0,0 +1,211 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Parse a task YAML file into a {@link TaskDocument}.
+ *
+ * The on-disk shape is a pure YAML file at `<stash>/tasks/<id>.yml`:
+ *
+ * ```yaml
+ * schedule: "0 9 * * *"
+ * # one of:
+ * workflow: workflow:daily-backup
+ * params:
+ *   region: us-east-1
+ * # ...or:
+ * prompt: agent:my-agent            # asset ref
+ * # ...or:
+ * prompt: ./prompts/my-prompt.md    # relative file path
+ * # ...or:
+ * prompt: |                         # inline multi-line prompt (block scalar)
+ *   Do the thing.
+ *   And the other thing.
+ * # ...or:
+ * command: akm improve --auto-accept=90 --limit 25
+ * enabled: true                     # default true
+ * name: Daily backup
+ * description: …
+ * when_to_use: …
+ * tags: [scheduled, backup]
+ * ```
+ *
+ * Validation lives in {@link validateTaskDocument}. The parser only enforces
+ * shape; cron syntax, target reachability, and profile availability are
+ * checked separately so callers can choose how strictly to surface errors.
+ */
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { UsageError } from "../core/errors";
+import { TASK_SCHEMA_VERSION } from "./schema";
+export function parseTaskDocument(input) {
+    const { yaml, filePath, id } = input;
+    let data;
+    try {
+        const parsed = parseYaml(yaml);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new UsageError(`Task "${id}" YAML must be a mapping (key: value pairs). File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        data = parsed;
+    }
+    catch (err) {
+        if (err instanceof UsageError)
+            throw err;
+        throw new UsageError(`Task "${id}" has invalid YAML: ${err instanceof Error ? err.message : String(err)}. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    }
+    const schedule = readString(data.schedule, "schedule", filePath);
+    if (!schedule) {
+        throw new UsageError(`Task "${id}" is missing a schedule (YAML key "schedule"). File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    const enabled = data.enabled === undefined ? true : data.enabled === true;
+    const name = readString(data.name, "name", filePath);
+    const description = readString(data.description, "description", filePath);
+    const when_to_use = readString(data.when_to_use, "when_to_use", filePath);
+    const tags = readStringArray(data.tags);
+    const hasWorkflow = "workflow" in data && data.workflow !== "" && data.workflow != null;
+    const hasPrompt = "prompt" in data && data.prompt !== "" && data.prompt != null;
+    const hasCommand = "command" in data && data.command !== "" && data.command != null;
+    const targetCount = [hasWorkflow, hasPrompt, hasCommand].filter(Boolean).length;
+    if (targetCount > 1) {
+        throw new UsageError(`Task "${id}" sets more than one of \`workflow\`, \`prompt\`, \`command\`; pick exactly one. File: ${filePath}`, "INVALID_FLAG_VALUE");
+    }
+    if (targetCount === 0) {
+        throw new UsageError(`Task "${id}" must set one of \`workflow\`, \`prompt\`, or \`command\`. File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    let target;
+    if (hasWorkflow) {
+        const ref = readString(data.workflow, "workflow", filePath);
+        if (!ref) {
+            throw new UsageError(`Task "${id}" has empty \`workflow\`. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        target = {
+            kind: "workflow",
+            ref,
+            params: readParams(data.params, filePath),
+        };
+    }
+    else if (hasCommand) {
+        const cmd = readCommand(data.command, filePath, id);
+        target = { kind: "command", cmd };
+    }
+    else {
+        const promptRaw = readString(data.prompt, "prompt", filePath);
+        if (!promptRaw) {
+            throw new UsageError(`Task "${id}" has empty \`prompt\`. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        const profile = readString(data.profile, "profile", filePath);
+        target = {
+            kind: "prompt",
+            source: resolvePromptSource(promptRaw, filePath, id),
+            profile: profile && profile.length > 0 ? profile : undefined,
+        };
+    }
+    // null / 0 / negative → disabled (no timeout). Positive number → override.
+    // Omitted → undefined (inherits config.agent.timeoutMs).
+    let timeoutMs;
+    if ("timeoutMs" in data) {
+        const raw = data.timeoutMs;
+        if (raw === null || raw === "null" || raw === 0 || (typeof raw === "number" && raw < 0)) {
+            timeoutMs = null;
+        }
+        else if (typeof raw === "number" && raw > 0) {
+            timeoutMs = raw;
+        }
+        // non-numeric / unrecognised → leave as undefined (inherit)
+    }
+    return {
+        schemaVersion: TASK_SCHEMA_VERSION,
+        id,
+        schedule,
+        enabled,
+        target,
+        name: name && name.length > 0 ? name : undefined,
+        description: description && description.length > 0 ? description : undefined,
+        when_to_use: when_to_use && when_to_use.length > 0 ? when_to_use : undefined,
+        tags: tags && tags.length > 0 ? tags : undefined,
+        source: { path: filePath },
+        timeoutMs,
+    };
+}
+/**
+ * Resolve a `prompt:` value into a {@link TaskPromptSource} variant.
+ *
+ *   • "<type>:<name>" (asset ref)              → asset
+ *   • "./foo.md", "../foo.md", "/abs"          → file
+ *   • "C:\\abs" (Windows absolute)             → file
+ *   • anything else (incl. block scalars)      → inline text
+ */
+function resolvePromptSource(raw, filePath, id) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("./") || trimmed.startsWith("../") || path.isAbsolute(trimmed)) {
+        return { kind: "file", path: trimmed };
+    }
+    if (/^[A-Za-z]:[\\/]/.test(trimmed)) {
+        return { kind: "file", path: trimmed };
+    }
+    if (/^[a-z][a-z0-9_-]*:[^\s]/i.test(trimmed)) {
+        return { kind: "asset", ref: trimmed };
+    }
+    if (!trimmed) {
+        throw new UsageError(`Task "${id}" has empty \`prompt\`. File: ${filePath}`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    return { kind: "inline", text: trimmed };
+}
+function readString(value, key, filePath) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string")
+        return value.trim();
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    throw new UsageError(`Key "${key}" must be a string. File: ${filePath}`, "INVALID_FLAG_VALUE");
+}
+function readStringArray(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string") {
+        return value
+            .split(/[\s,]+/)
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === "string" && v.trim().length > 0);
+    }
+    return undefined;
+}
+function readCommand(value, filePath, id) {
+    if (Array.isArray(value)) {
+        const parts = value.filter((v) => typeof v === "string" && v.trim().length > 0);
+        if (parts.length === 0) {
+            throw new UsageError(`Task "${id}" has empty \`command\` array. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        return parts;
+    }
+    if (typeof value === "string") {
+        const parts = value.trim().split(/\s+/).filter(Boolean);
+        if (parts.length === 0) {
+            throw new UsageError(`Task "${id}" has empty \`command\`. File: ${filePath}`, "INVALID_FLAG_VALUE");
+        }
+        return parts;
+    }
+    throw new UsageError(`Key "command" must be a string or array of strings. File: ${filePath}`, "INVALID_FLAG_VALUE");
+}
+function readParams(value, filePath) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim()) {
+        try {
+            const parsed = JSON.parse(value);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    throw new UsageError(`Key "params" must be a mapping or a JSON object. File: ${filePath}`, "INVALID_FLAG_VALUE");
+}