@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.33

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/lease.mjs

@@ -0,0 +1,24 @@
+// A permanent inode and a kernel lock serialize CLI processes. The Host inherits
+// the descriptor so a killed parent cannot leave a still-running session unowned.
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+import { tryLockExclusive } from '@deepseek-ai/node-addon-system/flock';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+export async function acquireTriggerLease(home, id, { wait = false, delay = sleep } = {}) {
+  const directory = join(home, 'triggers', 'locks');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const fd = openSync(join(directory, `${id}.guard`), 'a', 0o600);
+  try {
+    for (;;) {
+      try { await tryLockExclusive(fd); break; }
+      catch (error) {
+        if (!['EAGAIN', 'EWOULDBLOCK'].includes(error.code)) throw error;
+        if (!wait) { closeSync(fd); return undefined; }
+        await delay(100);
+      }
+    }
+    let released = false;
+    return { fd, release() { if (!released) { released = true; closeSync(fd); } } };
+  } catch (error) { closeSync(fd); throw error; }
+}

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}`;
+}

package/plugins/triggers/management.mjs

@@ -0,0 +1,181 @@
+// Agent-facing management uses the same definitions, jobs and scheduler as the CLI.
+import { existsSync, lstatSync, mkdirSync, renameSync, rmSync, writeFileSync, linkSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { stringify } from 'yaml';
+import { loadTriggerDefinitions, normalizeTrigger } from './config.mjs';
+import { JobStore } from './jobs.mjs';
+import { normalizeEvent } from './spool.mjs';
+import { dueTime } from './schedule.mjs';
+import { acquireTriggerLease } from './lease.mjs';
+import { schedulerService } from './scheduler-service.mjs';
+
+const stable = value => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+  ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item);
+const required = (value, label) => { if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} is required`); return value; };
+const clean = definition => Object.fromEntries(Object.entries(definition).filter(([key]) => !['origin', 'path', 'overrides'].includes(key)));
+
+/** No shell, inherited input or unbounded launchctl wait. */
+function launchctl(args, { ignoreFailure = false } = {}) {
+  return new Promise((resolveRun, reject) => {
+    const child = spawn('/bin/launchctl', args, { stdio: 'ignore' });
+    const timer = setTimeout(() => child.kill('SIGKILL'), 10000);
+    child.once('error', error => { clearTimeout(timer); if (ignoreFailure) resolveRun(1); else reject(error); });
+    child.once('exit', code => { clearTimeout(timer); if (code === 0 || ignoreFailure) resolveRun(code ?? 1); else reject(new Error(`launchctl failed (${code})`)); });
+  });
+}
+
+export class TriggerManagement {
+  constructor({ home, dscodePath, platform = process.platform, now = Date.now, service = schedulerService, runLaunchctl = launchctl }) {
+    Object.assign(this, { home, dscodePath, platform, now, service, runLaunchctl });
+  }
+  workspace(agent) {
+    const cwd = agent?.session?.header?.cwd;
+    if (!cwd || !isAbsolute(cwd)) throw new Error('A session bound to a workspace is required');
+    return resolve(cwd);
+  }
+  definitions(project) { return loadTriggerDefinitions({ home: this.home, workspace: project }); }
+  definition(project, id) {
+    required(id, 'trigger_id');
+    const definition = this.definitions(project).definitions.find(item => item.id === id);
+    if (!definition) throw new Error(`No trigger "${id}"`);
+    if (resolve(definition.workspace) !== project) throw new Error('The trigger belongs to another workspace');
+    return definition;
+  }
+  runnable(definition) {
+    if (!['read-only', 'workspace-write'].includes(definition.permission) || definition.preset !== 'dscode') {
+      throw new Error('Agent-managed scheduling requires the dscode preset and read-only or workspace-write permission');
+    }
+  }
+  withStore(fn) {
+    const store = new JobStore(this.home);
+    try { return fn(store); } finally { store.close(); }
+  }
+  async status() {
+    const lease = await acquireTriggerLease(this.home, '_scheduler');
+    const running = !lease;
+    lease?.release();
+    return { running, ...(!running ? { next_step: 'Use trigger_scheduler(action="install") on macOS, or run dscode trigger scheduler start under a service manager.' } : {}) };
+  }
+  write(project, definition, existing) {
+    const directory = join(project, '.dsh', 'triggers');
+    // Do not turn a project-local tool into an arbitrary-file writer via symlinks.
+    for (const path of [join(project, '.dsh'), directory]) {
+      if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw new Error('Trigger configuration directories must not be symlinks');
+    }
+    mkdirSync(directory, { recursive: true });
+    const path = existing?.path ?? join(directory, `${definition.id}.yml`);
+    if (relative(directory, dirname(path)) !== '' || (existsSync(path) && lstatSync(path).isSymbolicLink())) throw new Error('Only regular project-local definitions can be changed');
+    const body = path.endsWith('.json') ? JSON.stringify(clean(definition), null, 2) + '\n' : stringify(clean(definition));
+    const temp = join(directory, `.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(temp, body, { flag: 'wx', mode: 0o600 });
+      if (existing) renameSync(temp, path);
+      else linkSync(temp, path); // Never overwrite a concurrently created definition.
+    } finally { rmSync(temp, { force: true }); }
+    return path;
+  }
+  async manage(args, agent) {
+    const project = this.workspace(agent);
+    const { action, trigger_id: id } = args;
+    if (action === 'list') {
+      const found = this.definitions(project);
+      return { definitions: found.definitions.filter(d => resolve(d.workspace) === project), problems: found.problems, schedules: this.withStore(s => s.schedules().filter(row => row.project === project)), sources: this.withStore(s => s.sources().filter(row => row.project === project)), scheduler: await this.status() };
+    }
+    if (action === 'get') return { definition: this.definition(project, id) };
+    if (!['create', 'update', 'enable', 'disable', 'register', 'unregister'].includes(action)) throw new Error('Unknown trigger action');
+    let definition;
+    if (action === 'create' || action === 'update') {
+      required(id, 'trigger_id');
+      const found = this.definitions(project);
+      const existing = found.definitions.find(d => d.id === id);
+      if (action === 'create' && existing) throw new Error('Trigger already exists; use update');
+      if (action === 'update' && (!existing || existing.origin !== 'project')) throw new Error('Only existing project-local definitions can be updated');
+      if (existing && resolve(existing.workspace) !== project) throw new Error('The trigger belongs to another workspace');
+      // A broken JSON/YAML file must be repaired explicitly, never shadowed by a new extension.
+      if (found.problems.some(p => ['yml', 'yaml', 'json'].some(ext => p.path === join(project, '.dsh', 'triggers', `${id}.${ext}`)))) throw new Error('Repair the unreadable definition before editing it');
+      const patch = args.definition;
+      if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('definition is required for create/update');
+      const allowed = ['prompt', 'source', 'goal', 'limits', 'session', 'enabled', 'permission', 'model', 'effort'];
+      if (Object.keys(patch).some(key => !allowed.includes(key))) throw new Error(`definition accepts only ${allowed.join(', ')}`);
+      const base = existing ? clean(existing) : {};
+      if (patch.session) delete base.overlap;
+      definition = normalizeTrigger({ ...base, ...patch, id, workspace: project, preset: 'dscode' }, { origin: 'project' });
+      if (!['external', 'calendar', 'interval', 'script'].includes(definition.source.kind)) throw new Error('Agent-managed sources must be external, calendar, interval or script');
+      this.runnable(definition);
+      definition.path = this.write(project, definition, existing);
+      // Creating/editing a recurring source also registers it; external has no cadence.
+      this.withStore(s => definition.source.kind === 'external' ? s.unregister(id, project, this.now()) : s.register(definition, project, this.now()));
+    } else {
+      definition = this.definition(project, id);
+      if (action === 'register') {
+        this.runnable(definition);
+        this.withStore(s => s.register(definition, project, this.now()));
+      } else if (action === 'unregister') this.withStore(s => s.unregister(id, project, this.now()));
+      else {
+        if (definition.origin !== 'project') throw new Error('Only project-local definitions can be enabled or disabled');
+        definition.enabled = action === 'enable';
+        if (definition.enabled) this.runnable(definition);
+        this.write(project, definition, definition);
+      }
+    }
+    return { definition, action, scheduler: await this.status() };
+  }
+  async source(args, agent) {
+    const project = this.workspace(agent);
+    const definition = this.definition(project, args.trigger_id);
+    if (definition.source.kind !== 'script') throw new Error('source management requires a script source');
+    const source = this.withStore(s => {
+      if (['status', 'logs'].includes(args.action)) return s.source(definition.id, project);
+      this.runnable(definition);
+      return s.controlSource(definition, project, args.action);
+    });
+    if (args.action === 'logs') return { log: source?.log ?? '' };
+    return { source: source ?? { status: 'unregistered' }, scheduler: await this.status() };
+  }
+  async emit(args, agent) {
+    const project = this.workspace(agent);
+    const definition = this.definition(project, args.trigger_id);
+    this.runnable(definition);
+    const job = this.withStore(s => s.acceptEvent({ definition, project, payload: args.event ?? {}, eventId: args.eventId, now: this.now() }));
+    return { job, scheduler: await this.status() };
+  }
+  async jobs(args, agent) {
+    const project = this.workspace(agent);
+    const now = this.now();
+    if (args.action === 'list') {
+      const limit = args.limit ?? 50;
+      if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error('limit must be 1..100');
+      return { jobs: this.withStore(s => s.list(args.trigger_id).filter(j => j.project === project && j.workspace === project).slice(0, limit)), scheduler: await this.status() };
+    }
+    if (args.action === 'cancel') {
+      required(args.job_id, 'job_id');
+      return this.withStore(s => {
+        const job = s.get(args.job_id);
+        if (!job || job.project !== project || job.workspace !== project) throw new Error('No job in this workspace');
+        if (job.state !== 'cancelled') s.cancel(job.id, now);
+        return { job: s.get(job.id) };
+      });
+    }
+    if (args.action !== 'schedule') throw new Error('Unknown job action');
+    const definition = this.definition(project, args.trigger_id);
+    this.runnable(definition);
+    const requestKey = required(args.idempotency_key, 'idempotency_key');
+    if (requestKey.length > 200) throw new Error('idempotency_key must be at most 200 characters');
+    const payload = args.event ?? {};
+    normalizeEvent(definition.id, payload, { eventId: 'validation', now });
+    // Lookup a retry before future-time validation: its original due time may have passed.
+    const request = stable({ triggerId: definition.id, after: args.after, at: args.at, payload });
+    const job = this.withStore(s => s.createOnce({ requestKey, request, triggerId: definition.id, project, workspace: project, payload, dueAt: () => dueTime(args, now), now }));
+    return { job, scheduler: await this.status() };
+  }
+  async scheduler(args) {
+    if (args.action === 'status') return this.status();
+    if (args.action !== 'install') throw new Error('Scheduler action must be status or install');
+    if (!this.dscodePath || !isAbsolute(this.dscodePath) || !existsSync(this.dscodePath)) throw new Error('Restart DSCODE to provide its launcher path, or install the scheduler through the CLI');
+    const messages = [];
+    await this.service('install', { home: this.home, dscodePath: this.dscodePath, platform: this.platform, launchctl: this.runLaunchctl, out: text => messages.push(text) });
+    return { messages, scheduler: await this.status() };
+  }
+}

package/plugins/triggers/options.mjs

@@ -0,0 +1,117 @@
+// The run spec and run result: the two files that cross the process boundary
+// between `dscode trigger run` (which owns the lock, the limits and the record)
+// and the Host it spawns (which owns the agent, the goal and the transcript).
+// Keeping them small and validated is what lets either half be tested alone.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const isPlainObject = value => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+class TriggerIoError extends Error {}
+
+const fail = message => { throw new TriggerIoError(message); };
+
+/** Write one JSON file atomically enough for a spawned child to read it once. */
+function writeJson(path, value) {
+  writeFileSync(path, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+  return path;
+}
+
+/** Read a JSON file that must exist and must be an object. */
+function readJson(path, label) {
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (error) {
+    fail(`${label} is unreadable: ${error?.code ?? error?.message ?? error}`);
+  }
+  try {
+    const value = JSON.parse(raw);
+    if (!isPlainObject(value)) fail(`${label} must be an object`);
+    return value;
+  } catch (error) {
+    fail(`${label} is not valid JSON: ${error?.message ?? error}`);
+  }
+}
+
+/**
+ * Render the prompt one run sends: the definition's template with the event's
+ * values substituted. A template that never mentions the event text gets it
+ * appended, so an event can never be silently dropped by a forgetting template.
+ * @param template - the definition's prompt.
+ * @param event - the event that fired the run, when there is one.
+ * @returns the prompt text.
+ */
+export function renderPrompt(template, event) {
+  const text = typeof template === 'string' ? template : '';
+  if (event === undefined || event === null) return text;
+  let rendered = text
+    .replace(/\{\{event\.text\}\}/gu, event.text ?? '')
+    .replace(/\{\{event\.title\}\}/gu, event.title ?? '')
+    .replace(/\{\{event\.source\}\}/gu, event.source ?? '')
+    .replace(/\{\{event\.eventId\}\}/gu, event.eventId ?? '')
+    .replace(/\{\{event\.fields\.([A-Za-z0-9_.-]+)\}\}/gu, (_whole, key) => {
+      const value = isPlainObject(event.fields) ? event.fields[key] : undefined;
+      return value === undefined ? '' : String(value);
+    });
+  if (!/\{\{event\./u.test(text) && String(event.text ?? '').trim() !== '') {
+    const title = event.title === undefined ? '' : `${event.title}: `;
+    const block = `Event (${event.source ?? 'unspecified'}): ${title}${event.text}`;
+    rendered = [rendered.trimEnd(), block].filter(part => part !== '').join('\n\n');
+  }
+  return rendered;
+}
+
+/**
+ * Write the spec the spawned Host reads.
+ * @param path - where to write it.
+ * @param spec - `{ triggerId, runId, workspace, prompt, preset, permission, model?, effort?, goal, limits }`.
+ * @returns the path.
+ */
+export function writeRunSpec(path, spec) {
+  if (!isPlainObject(spec)) fail('a run spec must be an object');
+  for (const field of ['triggerId', 'runId', 'workspace', 'prompt', 'goal']) {
+    if (spec[field] === undefined) fail(`a run spec needs ${field}`);
+  }
+  if (!isPlainObject(spec.goal) || typeof spec.goal.objective !== 'string' || spec.goal.objective.trim() === '') fail('a run spec needs goal.objective');
+  if (!Number.isSafeInteger(spec.goal.maxRounds) || spec.goal.maxRounds <= 0) fail('a run spec needs a positive goal.maxRounds');
+  validateSessionMode(spec);
+  return writeJson(path, spec);
+}
+
+/** Read a run spec written by {@link writeRunSpec}. */
+export function readRunSpec(path) {
+  const spec = readJson(path, 'the run spec');
+  for (const field of ['triggerId', 'runId', 'workspace', 'prompt', 'goal']) {
+    if (spec[field] === undefined) fail(`the run spec is missing ${field}`);
+  }
+  validateSessionMode(spec);
+  return spec;
+}
+
+/** Write the result the Host reports back, which the parent turns into a record. */
+export function writeRunResult(path, result) {
+  if (!isPlainObject(result)) fail('a run result must be an object');
+  if (typeof result.outcome !== 'string') fail('a run result needs an outcome');
+  if (!Number.isSafeInteger(result.exitCode)) fail('a run result needs an exitCode');
+  return writeJson(path, result);
+}
+
+/**
+ * Read the Host's result.
+ * @param path - the result file.
+ * @returns the result, or undefined when the child died before writing one.
+ */
+export function readRunResult(path) {
+  try {
+    return readJson(path, 'the run result');
+  } catch {
+    return undefined;
+  }
+}
+
+function validateSessionMode(spec) {
+  if (spec.session !== undefined && (!isPlainObject(spec.session) || !['new', 'persistent'].includes(spec.session.mode) || Object.keys(spec.session).some(key => key !== 'mode'))) {
+    fail('a run spec session must contain only mode: new or persistent');
+  }
+}

package/plugins/triggers/overlay.mjs

@@ -0,0 +1,7 @@
+// The composition overlay that turns a terminal profile into one triggered run:
+// the terminal rows are disabled and the trigger host is inserted instead. It is
+// a pure string builder on purpose — the published launcher ships this file to
+// compose the same overlay, and it must not pull the host's dependencies in.
+export function triggerOverlay(pluginPath) {
+  return `- id: tui-startup\n  disabled: true\n- id: tui-runner\n  disabled: true\n- id: dscode-session-cards\n  config:\n    enabled: false\n- insert:\n    - id: dscode-trigger-host\n      name: ${JSON.stringify(pluginPath)}\n`;
+}

package/plugins/triggers/poll.mjs

@@ -0,0 +1,65 @@
+// The poll predicate: with no resident listener, "watch an external thing" is a
+// scheduled cheap check that only starts a session when something changed. The
+// check is a shell command run in the definition's workspace; exit 0 means
+// "there is work", anything else means "nothing to do".
+//
+// A predicate that cannot run must not fire a run: a spawn failure or a timeout
+// is reported as not matched, never as a match.
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { sandboxCommand, signalGroup } from './source-sandbox.mjs';
+import { spawn as nodeSpawn } from 'node:child_process';
+
+/** Output cap for the check's own text, so a chatty check cannot flood a record. */
+export const MAX_CHECK_OUTPUT_CHARS = 2000;
+
+/**
+ * Run one poll predicate.
+ * @param check - the shell command from `source.check`.
+ * @param options - `{ cwd, timeoutMs, spawn }`; `spawn` is injectable for tests.
+ * @returns `{ matched, code, output }`: `matched` is true only on exit 0.
+ */
+export function evaluateCheck(check, { cwd, timeoutMs = 60000, spawn = nodeSpawn, home, permission = 'read-only' } = {}) {
+  return new Promise(resolveCheck => {
+    let child, scratch;
+    const cleanup = () => { if (child) signalGroup(child, 'SIGKILL'); if (scratch) rmSync(scratch, { recursive: true, force: true }); };
+    try {
+      scratch = mkdtempSync('/tmp/dscode-poll-');
+      const launch = sandboxCommand(['/bin/sh', '-c', check], { workspace: cwd, writable: [scratch], home, permission });
+      child = spawn(launch.command, launch.args, { cwd, detached: true, env: { ...process.env, TMPDIR: scratch, TMP: scratch, TEMP: scratch }, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      cleanup();
+      resolveCheck({ matched: false, code: null, output: `could not start the check: ${error?.message ?? error}` });
+      return;
+    }
+    let output = '';
+    let settled = false;
+    const collect = chunk => {
+      if (output.length < MAX_CHECK_OUTPUT_CHARS) output += String(chunk);
+    };
+    child.stdout?.on('data', collect);
+    child.stderr?.on('data', collect);
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolveCheck({ matched: false, code: null, output: `${output}\n(the check exceeded ${timeoutMs}ms and was stopped)`.trim().slice(0, MAX_CHECK_OUTPUT_CHARS) });
+    }, timeoutMs);
+    timer.unref?.();
+    const finish = code => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanup();
+      resolveCheck({ matched: code === 0, code, output: output.replace(/\s+/gu, ' ').trim().slice(0, MAX_CHECK_OUTPUT_CHARS) });
+    };
+    child.once('error', error => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanup();
+      resolveCheck({ matched: false, code: null, output: `the check failed to start: ${error?.message ?? error}` });
+    });
+    child.once('exit', code => finish(code));
+  });
+}