@toddzheng024/dscode-bundle 0.7.23 → 0.7.24

package/plugins/triggers/config.mjs

@@ -0,0 +1,245 @@
+// Trigger definitions: the configuration half of the trigger mechanism
+// (docs/triggers-design.md). A definition says what produces an event, which
+// folder the fresh session binds to, what it is asked to do, and the limits that
+// keep an unattended run bounded. Nothing here starts a run: the ingress, the
+// runner and the source installers are separate work, and `/triggers` reads this
+// layer only.
+//
+// One bad file never hides the rest: discovery returns the definitions it could
+// read plus a per-file problem list, so a listing always shows what is usable.
+
+import { readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+/** Source kinds this version accepts; each has its own required fields. */
+export const SOURCE_KINDS = Object.freeze(['interval', 'calendar', 'watch', 'poll', 'external']);
+
+/** The only overlap policy: a trigger whose run is still going is skipped. */
+export const OVERLAP = 'skip';
+
+/** The only notification policy for now: append to the run log. */
+export const NOTIFY = 'log';
+
+/** Defaults a definition may omit. */
+export const DEFAULTS = Object.freeze({
+  enabled: true,
+  preset: 'dscode',
+  permission: 'workspace-write',
+  maxGoalRounds: 20,
+  timeoutSeconds: 1800,
+  maxRunsPerDay: 24,
+  minIntervalSeconds: 60,
+});
+
+/** Permission presets an unattended run may use; `ask` can never complete. */
+const UNATTENDED_PERMISSIONS = Object.freeze(['auto', 'workspace-write', 'read-only', 'danger-full-access']);
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/u;
+
+class TriggerConfigError extends Error {}
+
+const fail = message => { throw new TriggerConfigError(message); };
+
+const isPlainObject = value => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+function positiveNumber(value, label) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) fail(`${label} must be a positive number`);
+  return value;
+}
+
+function positiveInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value <= 0) fail(`${label} must be a positive whole number`);
+  return value;
+}
+
+function nonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') fail(`${label} must be a non-empty string`);
+  return value.trim();
+}
+
+/** Reject a key this version does not read, so a typo cannot fall back silently. */
+function knownKeys(raw, allowed, label) {
+  const unknown = Object.keys(raw).filter(key => !allowed.includes(key));
+  if (unknown.length > 0) fail(`${label} has no such field: ${unknown.join(', ')} (accepted: ${allowed.join(', ')})`);
+}
+
+/** Validate and normalize one source block. */
+function normalizeSource(raw) {
+  if (!isPlainObject(raw)) fail('source must be an object');
+  const kind = nonEmptyString(raw.kind, 'source.kind');
+  if (!SOURCE_KINDS.includes(kind)) fail(`source.kind must be one of: ${SOURCE_KINDS.join(', ')}`);
+  const fields = kind === 'interval' ? ['kind', 'seconds']
+    : kind === 'calendar' ? ['kind', 'cron']
+      : kind === 'watch' ? ['kind', 'paths']
+        : kind === 'poll' ? ['kind', 'everySeconds', 'check']
+          : ['kind'];
+  knownKeys(raw, fields, `source (${kind})`);
+  if (kind === 'interval') return { kind, seconds: positiveInteger(raw.seconds, 'source.seconds') };
+  if (kind === 'calendar') {
+    const cron = nonEmptyString(raw.cron, 'source.cron');
+    // Five fields is the only shape the installer can translate to launchd.
+    if (cron.split(/\s+/u).length !== 5) fail('source.cron must have five fields (minute hour day month weekday)');
+    return { kind, cron };
+  }
+  if (kind === 'watch') {
+    if (!Array.isArray(raw.paths) || raw.paths.length === 0) fail('source.paths must be a non-empty list of paths');
+    return { kind, paths: raw.paths.map((path, index) => nonEmptyString(path, `source.paths[${index}]`)) };
+  }
+  if (kind === 'poll') {
+    return { kind, everySeconds: positiveInteger(raw.everySeconds, 'source.everySeconds'), check: nonEmptyString(raw.check, 'source.check') };
+  }
+  return { kind };
+}
+
+/**
+ * Validate one raw definition into the normalized shape.
+ * @param raw - the parsed YAML/JSON body.
+ * @param meta - where it came from: `{ origin, path }`.
+ * @returns the normalized definition.
+ * @throws {TriggerConfigError} with a user-facing message.
+ */
+export function normalizeTrigger(raw, { origin, path } = {}) {
+  if (!isPlainObject(raw)) fail('a trigger definition must be a mapping');
+  knownKeys(raw, ['id', 'enabled', 'source', 'workspace', 'prompt', 'preset', 'permission', 'model', 'effort', 'goal', 'limits', 'overlap', 'notify'], 'the definition');
+  const id = nonEmptyString(raw.id, 'id');
+  if (!ID_PATTERN.test(id)) fail('id must start with a letter or digit and use only a-z, 0-9, dot, underscore or dash');
+  const workspace = nonEmptyString(raw.workspace, 'workspace');
+  if (!isAbsolute(workspace)) fail('workspace must be an absolute path: a triggered session binds to it and cannot change folders');
+  const prompt = nonEmptyString(raw.prompt, 'prompt');
+  const enabled = raw.enabled === undefined ? DEFAULTS.enabled : raw.enabled;
+  if (typeof enabled !== 'boolean') fail('enabled must be true or false');
+
+  const permission = raw.permission === undefined ? DEFAULTS.permission : nonEmptyString(raw.permission, 'permission');
+  if (!UNATTENDED_PERMISSIONS.includes(permission)) {
+    fail(`permission must be one of: ${UNATTENDED_PERMISSIONS.join(', ')} — an unattended run cannot ask for approval`);
+  }
+
+  const goal = raw.goal;
+  if (!isPlainObject(goal)) fail('goal must be an object with the objective to finish');
+  knownKeys(goal, ['objective', 'maxRounds'], 'goal');
+  const objective = nonEmptyString(goal.objective, 'goal.objective');
+  const maxRounds = goal.maxRounds === undefined ? DEFAULTS.maxGoalRounds : positiveInteger(goal.maxRounds, 'goal.maxRounds');
+
+  const limits = raw.limits === undefined ? {} : raw.limits;
+  if (!isPlainObject(limits)) fail('limits must be an object');
+  knownKeys(limits, ['timeoutSeconds', 'maxRunsPerDay', 'minIntervalSeconds', 'maxCostUsd'], 'limits');
+  const timeoutSeconds = limits.timeoutSeconds === undefined ? DEFAULTS.timeoutSeconds : positiveInteger(limits.timeoutSeconds, 'limits.timeoutSeconds');
+  const maxRunsPerDay = limits.maxRunsPerDay === undefined ? DEFAULTS.maxRunsPerDay : positiveInteger(limits.maxRunsPerDay, 'limits.maxRunsPerDay');
+  const minIntervalSeconds = limits.minIntervalSeconds === undefined ? DEFAULTS.minIntervalSeconds : positiveInteger(limits.minIntervalSeconds, 'limits.minIntervalSeconds');
+  const maxCostUsd = limits.maxCostUsd === undefined ? undefined : positiveNumber(limits.maxCostUsd, 'limits.maxCostUsd');
+
+  if (raw.overlap !== undefined && raw.overlap !== OVERLAP) fail(`overlap must be "${OVERLAP}"`);
+  if (raw.notify !== undefined && raw.notify !== NOTIFY) fail(`notify must be "${NOTIFY}"`);
+
+  const source = normalizeSource(raw.source);
+  return {
+    id, enabled, source, workspace, prompt,
+    preset: raw.preset === undefined ? DEFAULTS.preset : nonEmptyString(raw.preset, 'preset'),
+    permission,
+    ...(raw.model === undefined ? {} : { model: nonEmptyString(raw.model, 'model') }),
+    ...(raw.effort === undefined ? {} : { effort: nonEmptyString(raw.effort, 'effort') }),
+    goal: { objective, maxRounds },
+    limits: { timeoutSeconds, maxRunsPerDay, minIntervalSeconds, ...(maxCostUsd === undefined ? {} : { maxCostUsd }) },
+    overlap: OVERLAP,
+    notify: NOTIFY,
+    origin: origin ?? 'user',
+    path: path ?? '',
+  };
+}
+
+/** Parse one file body: JSON or YAML by extension, YAML as the general form. */
+function parseBody(text, path) {
+  if (/\.json$/iu.test(path)) {
+    try { return JSON.parse(text); } catch (error) { fail(`not valid JSON: ${error.message}`); }
+  }
+  try { return parseYaml(text); } catch (error) { fail(`not valid YAML: ${error.message}`); }
+}
+
+/** Read one directory of definitions, returning definitions and problems. */
+function readDirectory(directory, origin) {
+  const definitions = [];
+  const problems = [];
+  let entries;
+  try {
+    entries = readdirSync(directory);
+  } catch (error) {
+    // Absent is normal (most machines and projects have no triggers); anything
+    // else must be reported, or a permission problem reads as "none defined".
+    if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') {
+      problems.push({ path: directory, message: `cannot read the trigger directory: ${error?.code ?? error?.message ?? error}` });
+    }
+    return { definitions, problems };
+  }
+  for (const entry of entries.sort()) {
+    if (!/\.(ya?ml|json)$/iu.test(entry)) continue;
+    const path = join(directory, entry);
+    try {
+      const normalized = normalizeTrigger(parseBody(readFileSync(path, 'utf8'), path), { origin, path });
+      if (normalized.id !== entry.replace(/\.(ya?ml|json)$/iu, '')) {
+        fail(`id "${normalized.id}" must match the file name ("${entry}")`);
+      }
+      definitions.push(normalized);
+    } catch (error) {
+      problems.push({ path, message: error instanceof TriggerConfigError ? error.message : String(error?.message ?? error) });
+    }
+  }
+  return { definitions, problems };
+}
+
+/**
+ * Discover trigger definitions. User-level files live under `<state>/triggers/`;
+ * project files under `<workspace>/.dsh/triggers/` and win on an id collision, so
+ * a repository can pin its own definition and have it reviewed in a pull request.
+ * @param options - `{ home, workspace }`; either may be absent.
+ * @returns `{ definitions, problems }`, definitions sorted by id.
+ */
+export function loadTriggerDefinitions({ home, workspace } = {}) {
+  const user = home === undefined ? { definitions: [], problems: [] } : readDirectory(join(home, 'triggers'), 'user');
+  const project = workspace === undefined ? { definitions: [], problems: [] } : readDirectory(join(resolve(workspace), '.dsh', 'triggers'), 'project');
+  const byId = new Map();
+  for (const definition of user.definitions) byId.set(definition.id, definition);
+  for (const definition of project.definitions) byId.set(definition.id, { ...definition, overrides: byId.has(definition.id) });
+  return {
+    definitions: [...byId.values()].sort((left, right) => left.id.localeCompare(right.id)),
+    problems: [...user.problems, ...project.problems],
+  };
+}
+
+/** The newest run in one line; `formatRun` in log.mjs owns the vocabulary. */
+function formatLastRun(record) {
+  const when = new Date(record.startedAt).toISOString().replace('T', ' ').slice(0, 19);
+  const reason = record.reason === null || record.reason === undefined ? '' : ` (${record.reason})`;
+  return `${when} ${record.outcome}${reason} · exit ${record.exitCode}`;
+}
+
+/** One line, bounded: a listing row must never be forged out of a value. */
+const inline = (text, limit = 96) => {
+  const folded = String(text).replace(/\s+/gu, ' ').trim();
+  return folded.length > limit ? `${folded.slice(0, limit - 1)}…` : folded;
+};
+
+/**
+ * One definition as the text `/triggers` prints.
+ * @param definition - a normalized definition.
+ * @param options - `{ lastRun }`: the newest run record, when the log has one.
+ * @returns the aligned block.
+ */
+export function formatTrigger(definition, { lastRun } = {}) {
+  const source = definition.source.kind === 'interval' ? `every ${definition.source.seconds}s`
+    : definition.source.kind === 'calendar' ? `cron ${definition.source.cron}`
+      : definition.source.kind === 'watch' ? `watch ${definition.source.paths.join(', ')}`
+        : definition.source.kind === 'poll' ? `poll ${definition.source.everySeconds}s: ${definition.source.check}`
+          : 'external (emit only)';
+  return [
+    `${definition.enabled ? 'on ' : 'off'} ${definition.id}${definition.overrides ? ' (project overrides user)' : ''}`,
+    `    source:    ${source}`,
+    `    workspace: ${definition.workspace}`,
+    `    goal:      ${inline(definition.goal.objective)} (max ${definition.goal.maxRounds} rounds)`,
+    `    prompt:    ${inline(definition.prompt)}`,
+    `    limits:    ${definition.limits.timeoutSeconds}s, ${definition.limits.maxRunsPerDay}/day${definition.limits.maxCostUsd === undefined ? '' : `, $${definition.limits.maxCostUsd}`}`,
+    `    run as:    ${definition.preset}/${definition.permission}${definition.model === undefined ? '' : ` · ${definition.model}`}`,
+    `    file:      ${definition.path === '' ? '(unknown)' : definition.path}`,
+    ...(lastRun === undefined ? [] : [`    last:      ${formatLastRun(lastRun)}`]),
+  ].join('\n');
+}

package/plugins/triggers/host.mjs

@@ -0,0 +1,138 @@
+// Host-side half of one trigger run: the clean session an event starts. Unlike
+// `dscode exec`, which runs exactly one turn, this one keeps going while the
+// goal is active — the round driver supplies the continuation — and stops on the
+// goal's own end, a cap, the timeout, or a needed approval.
+//
+// It owns the agent, the goal and the transcript; the parent process owns the
+// lock, the limits and the run record. The two swap files: `DSCODE_TRIGGER_OPTIONS`
+// in, `<options>.result.json` out.
+import { randomUUID } from 'node:crypto';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { decideStop } from './run.mjs';
+import { readRunSpec, writeRunResult } from './options.mjs';
+import { writeRunTail } from './log.mjs';
+import { sessionSpend } from '../session-metrics/view.mjs';
+import { triggerOverlay } from './overlay.mjs';
+
+export { triggerOverlay };
+
+export const name = 'dscode-trigger-host';
+export const inject = ['agents', 'agentPresets', 'agentDefaultModel', 'permissionPresets', 'llm', 'goals', 'appExit'];
+
+export function apply(ctx) {
+  void run(ctx).catch(error => { process.stderr.write(`dscode trigger run: ${error.message}\n`); ctx.get('appExit')(1); });
+}
+
+function splitRoute(value) {
+  const at = value.indexOf('/');
+  if (at <= 0 || at === value.length - 1) throw new Error(`model expects provider/model, got ${value}`);
+  return [value.slice(0, at), value.slice(at + 1)];
+}
+
+async function run(ctx) {
+  await ctx.get('loader').await();
+  const optionsPath = process.env.DSCODE_TRIGGER_OPTIONS;
+  if (!optionsPath) throw new Error('DSCODE_TRIGGER_OPTIONS is missing');
+  const spec = readRunSpec(optionsPath);
+  const resultPath = `${optionsPath}.result.json`;
+
+  const selection = ctx.agentDefaultModel.currentSelection();
+  const [provider, model] = spec.model ? splitRoute(spec.model) : [selection.provider, selection.model];
+  const effort = spec.effort ?? selection.reasoningEffort;
+  const agentOptions = { provider, model, ...(effort ? { reasoningEffort: effort } : {}) };
+  const setup = async agentCtx => { await ctx.agentPresets.mount(agentCtx, spec.preset ?? 'dscode'); };
+
+  const handle = await ctx.agents.create({
+    sessionId: randomUUID(),
+    meta: { cwd: spec.workspace, agentPreset: spec.preset ?? 'dscode' },
+    agentOptions,
+    setup,
+  });
+  const agent = handle.agent;
+  const session = agent.session;
+  if (spec.permission) {
+    ctx.permissionPresets.resolve(spec.permission);
+    ctx.permissionPresets.set(session, spec.permission);
+  }
+
+  // The goal is created through the SERVICE, not the `create_goal` tool: the tool
+  // requires a direct human turn, and an unattended run has none. The service is
+  // the same path the human-facing /goal command uses.
+  ctx.goals.create(agent, { objective: spec.goal.objective, maxGoalRounds: spec.goal.maxRounds });
+
+  let finished = false;
+  let approvalsRejected = false;
+  let lastText = '';
+  const limiter = spec.limits ?? {};
+
+  const finish = (result, tail) => {
+    if (finished) return;
+    finished = true;
+    if (tail !== undefined && tail.trim() !== '') {
+      try { writeRunTail(process.env.DSH_HOME ?? '.', spec.triggerId, spec.runId, tail); } catch { /* the record still explains the run */ }
+    }
+    try {
+      writeRunResult(resultPath, { ...result, sessionId: session.id });
+    } catch (error) {
+      process.stderr.write(`dscode trigger run: could not write the result file: ${error.message}\n`);
+    }
+    ctx.get('appExit')(result.exitCode);
+  };
+
+  /** Read durable goal state plus recorded spend, and stop if the run is over. */
+  const evaluate = () => {
+    if (finished) return;
+    let goal;
+    try { goal = ctx.goals.get(agent); } catch { goal = undefined; }
+    let costUsd;
+    try { costUsd = sessionSpend(session.id).cost; } catch { costUsd = undefined; }
+    const decision = decideStop({ goal, costUsd, limits: limiter, approvalsRejected });
+    if (!decision.stop) return;
+    finish({
+      outcome: decision.outcome,
+      reason: decision.reason ?? null,
+      exitCode: decision.exitCode,
+      cost: Number.isFinite(costUsd) ? costUsd : null,
+      rounds: Number.isFinite(goal?.roundsStarted) ? goal.roundsStarted : null,
+    }, lastText);
+  };
+
+  ctx.on('session/event', (subject, event) => {
+    if (subject.id !== session.id) return;
+    if (event.type === 'assistant/message') {
+      const text = (event.data.message?.content ?? []).filter(block => block.type === 'text').map(block => block.text).join('');
+      if (text !== '') lastText = text;
+      return;
+    }
+    // The goal round driver continues after a turn; only the goal's own state
+    // (or a cap) ends the run, so this is a check, not a completion signal.
+    if (event.type === 'turn/end') evaluate();
+  });
+  ctx.on('session/disposed', source => {
+    if (source.id !== session.id) return;
+    finish({ outcome: 'failed', reason: 'model_error', exitCode: 1, cost: null, rounds: null }, lastText);
+  });
+  // No human is present: an approval request is refused, and the run is marked
+  // as having needed one so the operator sees it in the record.
+  ctx.on('approval/request', (request, next) => {
+    if (request.agent?.id !== agent.id) return next();
+    approvalsRejected = true;
+    process.stderr.write(`approval needed for ${request.toolName}: rejected (a triggered run has no human to ask)\n`);
+    return 'rejected';
+  });
+
+  if (Number.isFinite(limiter.timeoutSeconds) && limiter.timeoutSeconds > 0) {
+    setTimeout(() => {
+      const goal = (() => { try { return ctx.goals.get(agent); } catch { return undefined; } })();
+      finish({
+        outcome: 'timedout',
+        reason: approvalsRejected ? 'approval_required' : 'timeout',
+        exitCode: 124,
+        cost: (() => { try { return sessionSpend(session.id).cost; } catch { return null; } })(),
+        rounds: Number.isFinite(goal?.roundsStarted) ? goal.roundsStarted : null,
+      }, lastText);
+    }, limiter.timeoutSeconds * 1000).unref();
+  }
+
+  agent.followup(createUserMessage({ content: [{ type: 'text', text: spec.prompt }], source: { kind: 'user' } }));
+}

package/plugins/triggers/index.mjs

@@ -0,0 +1,57 @@
+// The read-only half of the trigger mechanism: `/triggers` lists the definitions
+// this machine and this project carry, and `/triggers show <id>` prints one.
+// Nothing here starts a run — the ingress, the runner and the source installers
+// are separate work (docs/triggers-design.md).
+import { loadTriggerDefinitions, formatTrigger } from './config.mjs';
+import { formatRun, readRuns } from './log.mjs';
+import { formatEvent, listEvents } from './spool.mjs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const name = 'dscode-triggers';
+export const inject = ['commands'];
+
+/** The state directory the launcher hands the child, as the other plugins read it. */
+const stateHome = () => process.env.DSH_HOME ?? process.env.DSCODE_HOME ?? join(homedir(), '.local/share/dscode-hub');
+
+export function apply(ctx) {
+  ctx.commands.register({
+    name: 'triggers',
+    description: 'List trigger definitions, or show one by id',
+    handler({ agent, rawInput }) {
+      const [action, id, extra] = rawInput.trim().split(/\s+/u);
+      const workspace = agent?.session?.header?.cwd;
+      const { definitions, problems } = loadTriggerDefinitions({ home: stateHome(), workspace });
+      const problemsText = problems.length === 0 ? [] : ['', 'Unreadable definitions:', ...problems.map(problem => `  ${problem.path}: ${problem.message}`)];
+      const lastRun = id => readRuns(stateHome(), { triggerId: id, limit: 1 })[0];
+      if (action === 'events') {
+        if (id === undefined || id === '' || extra !== undefined) return { kind: 'error', text: 'Usage: /triggers events <id>' };
+        const pending = listEvents(stateHome(), id);
+        return pending.length === 0
+          ? { kind: 'success', text: `No pending events for ${id}.` }
+          : { kind: 'success', text: pending.map(formatEvent).join('\n') };
+      }
+      if (action === 'runs') {
+        if (id === undefined || id === '' || extra !== undefined) return { kind: 'error', text: 'Usage: /triggers runs <id>' };
+        const runs = readRuns(stateHome(), { triggerId: id, limit: 20 });
+        return runs.length === 0
+          ? { kind: 'success', text: `No runs recorded for ${id}.` }
+          : { kind: 'success', text: runs.map(formatRun).join('\n') };
+      }
+      if (action !== undefined && action !== '' && action !== 'list' && action !== 'show') {
+        return { kind: 'error', text: `Unknown action "${action}". Usage: /triggers [list|show <id>|events <id>|runs <id>]` };
+      }
+      if (action === 'show') {
+        if (id === undefined || id === '') return { kind: 'error', text: `Usage: /triggers show <id>\nKnown ids: ${definitions.map(definition => definition.id).join(', ') || '(none)'}` };
+        const found = definitions.find(definition => definition.id === id);
+        if (found === undefined) return { kind: 'error', text: `No trigger "${id}" in ${stateHome()}/triggers or ${workspace ?? '(no workspace)'}/.dsh/triggers` };
+        if (extra !== undefined) return { kind: 'error', text: `Usage: /triggers show <id>` };
+        return { kind: 'success', text: formatTrigger(found, { lastRun: lastRun(found.id) }) };
+      }
+      if (definitions.length === 0 && problems.length === 0) {
+        return { kind: 'success', text: `No triggers defined.\nAdd one as ${stateHome()}/triggers/<id>.yml, or per project as <workspace>/.dsh/triggers/<id>.yml.\nThe definition format is in docs/triggers-design.md; running them is not implemented yet.` };
+      }
+      return { kind: 'success', text: [...definitions.map(definition => formatTrigger(definition, { lastRun: lastRun(definition.id) })), ...problemsText].join('\n') };
+    },
+  });
+}

package/plugins/triggers/launchd.mjs

@@ -0,0 +1,101 @@
+// Installing a trigger into the system scheduler. launchd owns the clock
+// (docs/triggers-design.md), so this module turns one definition into a
+// LaunchAgent plist and, for anything launchd cannot express, into the crontab
+// line a person can paste. Nothing here runs a session or decides anything about
+// a run: it is text generation plus two launchctl calls.
+//
+// Only shapes launchd can express are accepted on purpose. A cron expression it
+// cannot map (ranges, steps, lists) fails the install with a message rather than
+// silently scheduling something else.
+
+import { join } from 'node:path';
+
+/** Label prefix for a DSCODE trigger agent; one label per trigger id. */
+export const AGENT_LABEL_PREFIX = 'ai.dscode.trigger.';
+
+/** Where an installed agent's plist and its launchd output live. */
+export const agentPath = (home, id) => join(home, 'triggers', 'agents', `${id}.plist`);
+export const agentStdoutPath = (home, id) => join(home, 'triggers', 'agents', `${id}.log`);
+export const agentLabel = id => `${AGENT_LABEL_PREFIX}${id}`;
+
+const CRON_FIELDS = ['Minute', 'Hour', 'Day', 'Month', 'Weekday'];
+
+/**
+ * Map a five-field cron expression onto launchd's StartCalendarInterval keys.
+ * Only `*` and plain numbers are accepted: launchd has no syntax for ranges,
+ * steps or lists, so those are refused instead of approximated.
+ * @param cron - `minute hour day month weekday`.
+ * @returns the keys an integer-valued StartCalendarInterval may carry.
+ * @throws {Error} with a user-facing message for anything launchd cannot express.
+ */
+export function cronToCalendarInterval(cron) {
+  const fields = String(cron).trim().split(/\s+/u);
+  if (fields.length !== 5) throw new Error('the cron expression needs five fields (minute hour day month weekday)');
+  const interval = {};
+  fields.forEach((field, index) => {
+    if (field === '*') return;
+    if (!/^\d{1,2}$/u.test(field)) {
+      throw new Error(`launchd cannot schedule "${field}" in the ${CRON_FIELDS[index]} field: use intervals for a cadence, or plain numbers here`);
+    }
+    interval[CRON_FIELDS[index]] = Number(field);
+  });
+  if (Object.keys(interval).length === 0) throw new Error('a cron expression of five "*" fields would fire every minute; use an interval instead');
+  return interval;
+}
+
+/** Escape the five XML characters a plist value may contain. */
+const xml = value => String(value).replace(/[<>&"']/gu, char => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' }[char]));
+
+/**
+ * Build the LaunchAgent plist for one definition.
+ * @param definition - a normalized definition.
+ * @param options - `{ home, dscodePath, project }`; `dscodePath` must be absolute.
+ * @returns the plist XML.
+ * @throws {Error} when the source has no schedule to install.
+ */
+export function launchAgent(definition, { home, dscodePath, project }) {
+  const args = [dscodePath, 'trigger', 'run', definition.id, '--project', project];
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    `  <key>Label</key><string>${xml(agentLabel(definition.id))}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    ...args.map(argument => `    <string>${xml(argument)}</string>`),
+    '  </array>',
+    `  <key>WorkingDirectory</key><string>${xml(definition.workspace)}</string>`,
+    '  <key>ProcessType</key><string>Background</string>',
+    `  <key>StandardOutPath</key><string>${xml(agentStdoutPath(home, definition.id))}</string>`,
+    `  <key>StandardErrorPath</key><string>${xml(agentStdoutPath(home, definition.id))}</string>`,
+  ];
+  const { kind } = definition.source;
+  if (kind === 'interval') lines.push(`  <key>StartInterval</key><integer>${definition.source.seconds}</integer>`);
+  else if (kind === 'poll') lines.push(`  <key>StartInterval</key><integer>${definition.source.everySeconds}</integer>`);
+  else if (kind === 'calendar') {
+    const interval = cronToCalendarInterval(definition.source.cron);
+    lines.push('  <key>StartCalendarInterval</key>', '  <dict>', ...Object.entries(interval).map(([key, value]) => `    <key>${key}</key><integer>${value}</integer>`), '  </dict>');
+  } else if (kind === 'watch') {
+    lines.push('  <key>WatchPaths</key>', '  <array>', ...definition.source.paths.map(path => `    <string>${xml(path)}</string>`), '  </array>');
+  } else {
+    throw new Error(`a "${kind}" source has nothing to schedule: producers post into its spool with "dscode trigger emit ${definition.id}"`);
+  }
+  lines.push('</dict>', '</plist>', '');
+  return lines.join('\n');
+}
+
+/**
+ * The crontab line for the same schedule, for a machine without launchd.
+ * @returns the line, or a comment explaining why there is none.
+ */
+export function crontabLine(definition, { dscodePath, project }) {
+  const command = `${dscodePath} trigger run ${definition.id} --project ${project}`;
+  if (definition.source.kind === 'calendar') return `${definition.source.cron} ${command}`;
+  const seconds = definition.source.kind === 'interval' ? definition.source.seconds
+    : definition.source.kind === 'poll' ? definition.source.everySeconds : undefined;
+  if (seconds === undefined) return `# ${definition.id}: a "${definition.source.kind}" source has no crontab form; producers post events instead`;
+  if (seconds % 60 !== 0) return `# ${definition.id}: ${seconds}s is not a whole number of minutes; cron runs at minute resolution`;
+  const minutes = seconds / 60;
+  return minutes < 60 ? `*/${minutes} * * * * ${command}` : `0 */${Math.round(minutes / 60)} * * * ${command}`;
+}

package/plugins/triggers/log.mjs

@@ -0,0 +1,104 @@
+// The run log: the durable record every trigger run appends, and the pipe a
+// failure notifier will read later (docs/triggers-design.md). One JSONL file for
+// outcomes plus a per-run text tail for the transcript end. A record must carry
+// enough to explain a run without the terminal: what fired, which session, how
+// it ended, and why.
+
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** Outcomes a run record may carry. */
+export const OUTCOMES = Object.freeze(['completed', 'skipped', 'failed', 'timedout', 'blocked', 'overrun']);
+
+/** Stable skip/failure reasons; `null` on a clean completion. */
+export const REASONS = Object.freeze([
+  'model_error', 'approval_required', 'goal_blocked', 'goal_paused', 'round_cap', 'cost_cap', 'timeout', 'interrupted',
+  'already_running', 'no_match', 'duplicate', 'disabled', 'over_daily_limit', 'too_soon', 'workspace_missing',
+]);
+
+const isPlainObject = value => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+class RunLogError extends Error {}
+
+const fail = message => { throw new RunLogError(message); };
+
+/** The append-only outcome log for one state directory. */
+export const runsPath = home => join(home, 'triggers', 'runs.jsonl');
+
+/** The text tail of one run (the agent's own last words), beside the outcome log. */
+export const runTailPath = (home, triggerId, runId) => join(home, 'triggers', 'logs', triggerId, `${runId}.log`);
+
+/**
+ * Append one run record.
+ * @param home - the state directory.
+ * @param record - the record; see the design record for the field set.
+ * @returns the record that was written.
+ * @throws {RunLogError} when a required field is missing or a value is outside the vocabulary.
+ */
+export function appendRun(home, record) {
+  if (!isPlainObject(record)) fail('a run record must be an object');
+  for (const field of ['triggerId', 'runId', 'startedAt', 'outcome', 'exitCode']) {
+    if (record[field] === undefined) fail(`a run record needs ${field}`);
+  }
+  if (typeof record.triggerId !== 'string' || record.triggerId === '') fail('triggerId must be a non-empty string');
+  if (typeof record.runId !== 'string' || record.runId === '') fail('runId must be a non-empty string');
+  if (!Number.isFinite(record.startedAt)) fail('startedAt must be a number (epoch milliseconds)');
+  if (!Number.isSafeInteger(record.exitCode)) fail('exitCode must be a whole number');
+  if (!OUTCOMES.includes(record.outcome)) fail(`outcome must be one of: ${OUTCOMES.join(', ')}`);
+  if (record.reason !== null && record.reason !== undefined && !REASONS.includes(record.reason)) {
+    fail(`reason must be null or one of: ${REASONS.join(', ')}`);
+  }
+  const path = runsPath(home);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  appendFileSync(path, JSON.stringify({ endedAt: null, sessionId: null, cost: null, rounds: null, ...record, reason: record.reason ?? null }) + '\n', { mode: 0o600 });
+  return record;
+}
+
+/**
+ * Read recent run records, newest first. A torn or unreadable line is skipped
+ * rather than failing the listing: the log is append-only and a half-written
+ * line is what a crash mid-append leaves behind.
+ * @param home - the state directory.
+ * @param options - `{ triggerId, limit }`.
+ * @returns run records, newest first.
+ */
+export function readRuns(home, { triggerId, limit = 20 } = {}) {
+  let raw;
+  try {
+    raw = readFileSync(runsPath(home), 'utf8');
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (triggerId !== undefined && record.triggerId !== triggerId) continue;
+    records.push(record);
+  }
+  records.reverse();
+  return limit === 0 ? records : records.slice(0, limit);
+}
+
+/** Write (replacing) one run's text tail. */
+export function writeRunTail(home, triggerId, runId, text) {
+  const path = runTailPath(home, triggerId, runId);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, text, { mode: 0o600 });
+  return path;
+}
+
+/** One record as the single listing line `/triggers` shows. */
+export function formatRun(record) {
+  if (record === undefined) return 'never ran';
+  const when = new Date(record.startedAt).toISOString().replace('T', ' ').slice(0, 19);
+  const reason = record.reason === null || record.reason === undefined ? '' : ` (${record.reason})`;
+  const cost = Number.isFinite(record.cost) ? ` $${record.cost.toFixed(2)}` : '';
+  const rounds = Number.isFinite(record.rounds) ? ` ${record.rounds}r` : '';
+  return `${when} ${record.outcome}${reason} exit ${record.exitCode}${cost}${rounds}`;
+}