@toddzheng024/dscode-bundle 0.7.23 → 0.7.24

package/plugins/triggers/options.mjs

@@ -0,0 +1,109 @@
+// 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');
+  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}`);
+  }
+  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;
+  }
+}

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,57 @@
+// 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 { 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 } = {}) {
+  return new Promise(resolveCheck => {
+    let child;
+    try {
+      child = spawn('/bin/sh', ['-c', check], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      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;
+      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+      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);
+      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);
+      resolveCheck({ matched: false, code: null, output: `the check failed to start: ${error?.message ?? error}` });
+    });
+    child.once('exit', code => finish(code));
+  });
+}

package/plugins/triggers/run.mjs

@@ -0,0 +1,156 @@
+// The run decision: everything that must be true before an event may start a
+// session, and the record left afterwards. This is the safety half of the
+// mechanism, so it is deliberately small and entirely testable: an unattended
+// run must never overlap its own previous run, must never fire twice for one
+// event, and must never exceed the limits its definition declares.
+//
+// It does NOT run an agent: executing the session (Host plugin, `dscode trigger
+// run`, the goal service) is separate work. `planTriggerRun` answers "may this
+// run start, and with what identity", `finishTriggerRun` records how it ended.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { appendRun, readRuns } from './log.mjs';
+
+/** Grace added to a run's timeout before its lock is treated as abandoned. */
+export const LOCK_STALE_GRACE_MS = 60000;
+
+/** One trigger's single-flight lock. */
+export const lockPath = (home, triggerId) => join(home, 'triggers', 'locks', `${triggerId}.json`);
+
+/** True when a process id exists; EPERM means it exists but belongs to someone else. */
+export function alivePid(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function readLock(home, triggerId) {
+  try {
+    const lock = JSON.parse(readFileSync(lockPath(home, triggerId), 'utf8'));
+    return typeof lock?.runId === 'string' ? lock : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeLock(home, handle) {
+  const path = lockPath(home, handle.triggerId);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, JSON.stringify(handle) + '\n', { mode: 0o600 });
+}
+
+/**
+ * Decide whether one event may start a run, and take the lock when it may.
+ *
+ * Order matters: a disabled trigger never runs; a repeated event is recognised
+ * before any lock is touched; the rolling day and the minimum interval are
+ * checked against recorded runs; and only then does a live lock stop the run.
+ * An identity is REQUIRED: without one the duplicate check is inert, so a
+ * re-drained event would start a second session. A scheduled source passes the
+ * planned instant, an external producer passes its own event id.
+ * @param definition - a normalized definition (plugins/triggers/config.mjs).
+ * @param options - `{ home, now, eventId, isAlive, runId }`; `eventId` is required.
+ * @returns `{ action: 'run', handle }` or `{ action: 'skip', reason }`.
+ * @throws {Error} when `eventId` is missing or empty.
+ */
+export function planTriggerRun(definition, { home, now = Date.now(), eventId, isAlive = alivePid, runId = randomUUID() } = {}) {
+  if (typeof eventId !== 'string' || eventId.trim() === '') throw new Error('planTriggerRun needs an eventId: it is how a repeated firing is recognised');
+  if (!definition.enabled) return { action: 'skip', reason: 'disabled' };
+  if (!existsSync(definition.workspace)) return { action: 'skip', reason: 'workspace_missing' };
+  const recorded = readRuns(home, { triggerId: definition.id, limit: 0 }).filter(entry => entry.outcome !== 'skipped');
+  if (recorded.some(entry => entry.eventId === eventId)) return { action: 'skip', reason: 'duplicate' };
+  const lastDay = recorded.filter(entry => now - entry.startedAt < 24 * 60 * 60 * 1000);
+  if (lastDay.length >= definition.limits.maxRunsPerDay) return { action: 'skip', reason: 'over_daily_limit' };
+  const newest = recorded[0];
+  if (newest !== undefined && now - newest.startedAt < definition.limits.minIntervalSeconds * 1000) return { action: 'skip', reason: 'too_soon' };
+
+  const lock = readLock(home, definition.id);
+  if (lock !== undefined) {
+    // A dead holder is reclaimed at once. A live pid is normally the run itself,
+    // but a recycled pid would look alive forever, so a lock older than the run's
+    // own timeout (plus a grace) is abandoned regardless.
+    const abandoned = now - lock.startedAt > definition.limits.timeoutSeconds * 1000 + LOCK_STALE_GRACE_MS;
+    if (isAlive(lock.pid) && !abandoned) return { action: 'skip', reason: 'already_running' };
+  }
+  const handle = { triggerId: definition.id, runId, startedAt: now, pid: process.pid, eventId };
+  writeLock(home, handle);
+  return { action: 'run', handle };
+}
+
+/**
+ * Drop a lock this run owns, without recording anything.
+ * A lock whose contents cannot be read is left in place rather than deleted: an
+ * unreadable lock may belong to another run, and deleting it would let two
+ * sessions run for one trigger. It ages out on its own.
+ */
+export function releaseTriggerRun(home, handle) {
+  const lock = readLock(home, handle.triggerId);
+  if (lock === undefined || lock.runId !== handle.runId) return false;
+  try {
+    rmSync(lockPath(home, handle.triggerId));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Decide whether a run in flight should stop, and how it ended. Called after
+ * every turn and by the timeout, so it only reads durable goal state plus the
+ * spend the metrics ledger reports.
+ *
+ * Completion wins over a rejected approval: the goal was reached, and the
+ * rejection is recorded in the run tail. When a cap or the timeout stops a run
+ * that needed a human, `approval_required` is the reason — that is the failure an
+ * operator has to fix.
+ * @param state - `{ goal, costUsd, limits, approvalsRejected }`.
+ * @returns `{ stop: false }` or `{ stop: true, outcome, reason, exitCode }`.
+ */
+export function decideStop({ goal, costUsd, limits, approvalsRejected = false } = {}) {
+  const capped = approvalsRejected ? 'approval_required' : undefined;
+  // A goal that is gone was cleared: nothing left to continue for.
+  if (goal === undefined || goal === null) return { stop: true, outcome: 'completed', reason: null, exitCode: 0 };
+  if (goal.phase === 'complete') return { stop: true, outcome: 'completed', reason: null, exitCode: 0 };
+  if (goal.phase === 'blocked') return { stop: true, outcome: 'blocked', reason: 'goal_blocked', exitCode: 3 };
+  if (goal.phase === 'paused') return { stop: true, outcome: 'failed', reason: 'goal_paused', exitCode: 3 };
+  if (Number.isFinite(limits?.maxCostUsd) && Number.isFinite(costUsd) && costUsd >= limits.maxCostUsd) {
+    return { stop: true, outcome: 'overrun', reason: capped ?? 'cost_cap', exitCode: 2 };
+  }
+  if (Number.isFinite(goal.maxGoalRounds) && goal.roundsStarted >= goal.maxGoalRounds) {
+    return { stop: true, outcome: 'overrun', reason: capped ?? 'round_cap', exitCode: 2 };
+  }
+  return { stop: false };
+}
+
+/**
+ * Record how a run ended and release its lock.
+ * @param home - the state directory.
+ * @param handle - the handle `planTriggerRun` returned.
+ * @param result - `{ outcome, reason?, exitCode, sessionId?, cost?, rounds?, cwd?, endedAt?, eventId? }`.
+ * @returns the appended record.
+ */
+export function finishTriggerRun(home, handle, result) {
+  const record = appendRun(home, {
+    triggerId: handle.triggerId,
+    runId: handle.runId,
+    startedAt: handle.startedAt,
+    endedAt: result.endedAt ?? Date.now(),
+    eventId: result.eventId ?? handle.eventId,
+    source: result.source ?? null,
+    outcome: result.outcome,
+    reason: result.reason ?? null,
+    exitCode: result.exitCode,
+    sessionId: result.sessionId ?? null,
+    cost: result.cost ?? null,
+    rounds: result.rounds ?? null,
+    cwd: result.cwd ?? handle.cwd ?? null,
+  });
+  releaseTriggerRun(home, handle);
+  return record;
+}

package/plugins/triggers/spool.mjs

@@ -0,0 +1,128 @@
+// The ingress: one cheap, uniform way to post an event into a trigger. A producer
+// drops a JSON file and returns; a later drain runs it. This is the whole public
+// surface of the mechanism (docs/triggers-design.md), so it stays dumb: it
+// validates that the payload is *data* and never carries authority, and it does
+// not know what a session, a goal or a model is.
+//
+// Delivery is at-most-once: an event file is consumed when a run is started, and
+// the run record carries its identity, so a re-emitted event needs a new id.
+
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The only keys an event body may carry; anything else is a producer mistake. */
+export const EVENT_FIELDS = Object.freeze(['source', 'title', 'text', 'fields']);
+
+/** Message body cap, matching what one session input accepts. */
+export const MAX_EVENT_TEXT_BYTES = 64000;
+
+/** Event identity cap: it names a spool file and a run record, not a payload. */
+export const MAX_EVENT_ID_CHARS = 200;
+
+const TRIGGER_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/u;
+
+class SpoolError extends Error {}
+
+const fail = message => { throw new SpoolError(message); };
+
+const isPlainObject = value => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** The spool directory of one trigger. */
+export const spoolPath = (home, triggerId) => join(home, 'triggers', 'spool', triggerId);
+
+/** One event's file name: the id is reversible, so a listing can name the event. */
+const eventFile = (triggerId, eventId) => `${encodeURIComponent(eventId)}.json`;
+
+/**
+ * Post one event.
+ * @param home - the state directory.
+ * @param triggerId - the target trigger.
+ * @param payload - `{ source?, title?, text?, fields? }`; every value is data.
+ * @param options - `{ eventId, now }`; `eventId` is the de-duplication identity and is required.
+ * @returns the stored event.
+ * @throws {SpoolError} on an unknown field, a non-scalar value, an oversized body or a missing id.
+ */
+export function emitEvent(home, triggerId, payload, { eventId, now = Date.now() } = {}) {
+  if (typeof triggerId !== 'string' || !TRIGGER_ID_PATTERN.test(triggerId)) fail('triggerId must be the definition id');
+  if (typeof eventId !== 'string' || eventId.trim() === '') fail('eventId is required: it is how a repeated delivery is recognised');
+  if (eventId.trim().length > MAX_EVENT_ID_CHARS) fail(`eventId is longer than ${MAX_EVENT_ID_CHARS} characters`);
+  if (/[\u0000-\u001f\u007f]/u.test(eventId)) fail('eventId must not contain control characters');
+  if (!isPlainObject(payload)) fail('an event must be an object');
+  const unknown = Object.keys(payload).filter(key => !EVENT_FIELDS.includes(key));
+  // This is the authority boundary: an event is data, so a payload may not name a
+  // permission, a session or a tool. A field that is not understood is refused
+  // rather than ignored, so a producer cannot believe it granted something.
+  if (unknown.length > 0) fail(`an event carries no such field: ${unknown.join(', ')} (accepted: ${EVENT_FIELDS.join(', ')})`);
+  const text = payload.text ?? '';
+  if (typeof text !== 'string') fail('event.text must be a string');
+  if (Buffer.byteLength(text, 'utf8') > MAX_EVENT_TEXT_BYTES) fail(`event.text is longer than ${MAX_EVENT_TEXT_BYTES} bytes`);
+  if (payload.source !== undefined && typeof payload.source !== 'string') fail('event.source must be a string');
+  if (payload.title !== undefined && typeof payload.title !== 'string') fail('event.title must be a string');
+  if (payload.fields !== undefined) {
+    if (!isPlainObject(payload.fields)) fail('event.fields must be an object of scalar values');
+    for (const [key, value] of Object.entries(payload.fields)) {
+      if (!['string', 'number', 'boolean'].includes(typeof value)) fail(`event.fields.${key} must be a string, number or boolean`);
+    }
+  }
+  const event = {
+    triggerId,
+    eventId: eventId.trim(),
+    ...(payload.source === undefined ? {} : { source: payload.source }),
+    ...(payload.title === undefined ? {} : { title: payload.title }),
+    text,
+    ...(payload.fields === undefined ? {} : { fields: payload.fields }),
+    receivedAt: now,
+  };
+  const directory = spoolPath(home, triggerId);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  writeFileSync(join(directory, eventFile(triggerId, event.eventId)), JSON.stringify(event) + '\n', { mode: 0o600 });
+  return event;
+}
+
+/**
+ * List one trigger's pending events, oldest first.
+ * @param home - the state directory.
+ * @param triggerId - the trigger.
+ * @param options - `{ limit }`.
+ * @returns the parsed events, unreadable files skipped.
+ */
+export function listEvents(home, triggerId, { limit = 50 } = {}) {
+  let entries;
+  try {
+    entries = readdirSync(spoolPath(home, triggerId)).filter(name => name.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  const events = [];
+  for (const name of entries.sort()) {
+    try {
+      events.push(JSON.parse(readFileSync(join(spoolPath(home, triggerId), name), 'utf8')));
+    } catch {
+      continue;
+    }
+  }
+  events.sort((left, right) => (left.receivedAt ?? 0) - (right.receivedAt ?? 0) || String(left.eventId).localeCompare(String(right.eventId)));
+  return limit === 0 ? events : events.slice(0, limit);
+}
+
+/**
+ * Consume one event, so a drain cannot start it twice.
+ * @returns true when a pending file was removed.
+ */
+export function consumeEvent(home, triggerId, eventId) {
+  try {
+    rmSync(join(spoolPath(home, triggerId), eventFile(triggerId, eventId)));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** One event as a single listing line. */
+export function formatEvent(event) {
+  const when = new Date(event.receivedAt ?? 0).toISOString().replace('T', ' ').slice(0, 19);
+  const source = event.source === undefined ? '' : ` [${event.source}]`;
+  const title = event.title === undefined ? '' : `${event.title}: `;
+  const text = String(event.text ?? '').replace(/\s+/gu, ' ').trim();
+  return `${when}${source} ${event.eventId} — ${title}${text.length > 80 ? `${text.slice(0, 79)}…` : text}`;
+}

package/presets/dscode/agent.cordis.yml

@@ -149,7 +149,7 @@
 # can resolve them. The human command and model-facing tool register into this
 # preset's scoped layers.
 - id: command-goal
-  name: '@deepseek-ai/dsh-command-goal'
+  name: '@toddzheng024/dscode-bundle/command-goal'
 
 - id: tool-goal
   name: '@deepseek-ai/dsh-tool-goal'

package/vendor/command-goal/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.