@farmslot/agent-runtime 0.8.0 → 0.9.0

package/scripts/execution-template-cli.mjs

@@ -32,7 +32,7 @@ function takeValue(args, i, flag) {
   return value;
 }
 
-async function loadRuntime() {
+export async function loadRuntime() {
   if (!existsSync(distEntry)) {
     throw new Error(
       `compiled package missing at ${distEntry}; run yarn workspace @farmslot/agent-runtime build`,
@@ -58,7 +58,7 @@ function parseDomainDir(value) {
   return { domain, root: value.slice(separator + 1) };
 }
 
-function parseCatalogArgs(args, { materialize = false } = {}) {
+export function parseCatalogArgs(args, { materialize = false } = {}) {
   const opts = {
     dirs: [],
     domainDirs: [],
@@ -101,7 +101,7 @@ function parseCatalogArgs(args, { materialize = false } = {}) {
   return opts;
 }
 
-function buildSources(opts, runtime) {
+export function buildSources(opts, runtime) {
   const sources = [];
   const domainSourceIds = new Set();
   for (const [index, dir] of opts.dirs.entries()) {
@@ -328,7 +328,9 @@ async function main() {
   else usage(2);
 }
 
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/scripts/mark-checklist-step.cjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 const fs = require('node:fs');
 const path = require('node:path');
+const { randomUUID } = require('node:crypto');
 const { spawnSync } = require('node:child_process');
 const {
   expandedArtifactsForCommand,
@@ -43,7 +44,7 @@ function printHelp() {
     [
       usageLine,
       '',
-      'Task-dir mode: farmslot-agent mark <task-dir> <step> — requires checklist-target.json written by the gateway at task creation or role switch.',
+      'Task-dir mode: farmslot-agent mark <task-dir> <step> — marks CHECKLIST.md (or TASK.md) unless checklist-target.json, written by a role switch, points elsewhere.',
       'Override: farmslot-agent mark <task-dir> --checklist SELF-REVIEW.md <step> — optional --signal; signal defaults from checklist name.',
       'Bootstrap: ./mark start — role-owned signal with status running (no checklist box).',
       'Progress: ./mark 1, ./mark 2, ... — checks the box and appends checklistTiming.',
@@ -137,7 +138,7 @@ if (terminalCommand === 'no-change' || terminalCommand === 'blocked') {
   }
 }
 
-const SIGNAL_PASSTHROUGH_KEYS = ['role', 'contextId', 'prNumber'];
+const SIGNAL_PASSTHROUGH_KEYS = ['role', 'contextId', 'attemptId', 'prNumber'];
 
 function pickSignalPassthrough(signal) {
   const out = {};
@@ -361,6 +362,7 @@ function assertTerminalPackagedEvidence(taskPath, taskDir, terminalCommand) {
 function buildSignalUpdate(signal, terminal, target, timing, events, now, taskPath, _taskDir) {
   const base = {
     ...pickSignalPassthrough(signal),
+    ...(isStartCommand ? { attemptId: randomUUID() } : {}),
     step: target?.label ?? signal.step ?? 'complete',
     checklistTiming: {
       schemaVersion: 1,

package/scripts/task-init-cli.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * `farmslot-agent task init`: write a task directory from a selected execution
+ * template. Thin wrappers (mm-harness) add their own defaults and forward here.
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { buildSources, loadRuntime, parseCatalogArgs } from './execution-template-cli.mjs';
+
+function usage(exitCode = 0) {
+  const text = [
+    'Usage: task init <task-dir> --flow f --run-mode m --platform p --template id --title t [options]',
+    '',
+    '  Template sources: --dir <path> --domain-dir <domain=path> --project-worker <path>',
+    '                    --package-templates <path> [--package-id id] [--project-name name] [--domain d]',
+    '  Task:             --title t [--task-text s | --task-file path] [--ticket key] [--source-ref url]',
+    '  Identity:         [--surface s] [--project name] [--repo owner/name] [--attempt-id id]',
+    '  Rendering:        [--var KEY=VALUE]... [--task-dir-label label] [--mode-preamble text]',
+    '                    [--addendum-file path] [--mark-command "cmd"] [--json]',
+    '',
+    'Writes TASK.md, CHECKLIST.md, mark, inputs/handoff.json, inputs/worker-terminal-contract.json.',
+  ].join('\n');
+  (exitCode === 0 ? console.log : console.error)(text);
+  process.exit(exitCode);
+}
+
+function takeValue(args, i, flag) {
+  const value = args[i + 1];
+  if (value === undefined) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+function parseArgs(args) {
+  const opts = {
+    taskDir: null,
+    template: null,
+    title: null,
+    taskText: null,
+    taskFile: null,
+    ticket: null,
+    sourceRef: null,
+    surface: 'cli',
+    project: null,
+    repo: null,
+    attemptId: null,
+    vars: {},
+    taskDirLabel: null,
+    modePreamble: null,
+    addendumFile: null,
+    markCommand: null,
+    json: false,
+  };
+  const catalogArgs = [];
+  // The task dir is the first positional, before any flag, as the usage line says.
+  if (args[0] && !args[0].startsWith('-')) opts.taskDir = args.shift();
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--template') opts.template = takeValue(args, i++, arg);
+    else if (arg === '--title') opts.title = takeValue(args, i++, arg);
+    else if (arg === '--task-text') opts.taskText = takeValue(args, i++, arg);
+    else if (arg === '--task-file') opts.taskFile = takeValue(args, i++, arg);
+    else if (arg === '--ticket') opts.ticket = takeValue(args, i++, arg);
+    else if (arg === '--source-ref') opts.sourceRef = takeValue(args, i++, arg);
+    else if (arg === '--surface') opts.surface = takeValue(args, i++, arg);
+    else if (arg === '--project') opts.project = takeValue(args, i++, arg);
+    else if (arg === '--repo') opts.repo = takeValue(args, i++, arg);
+    else if (arg === '--attempt-id') opts.attemptId = takeValue(args, i++, arg);
+    else if (arg === '--task-dir-label') opts.taskDirLabel = takeValue(args, i++, arg);
+    else if (arg === '--mode-preamble') opts.modePreamble = takeValue(args, i++, arg);
+    else if (arg === '--addendum-file') opts.addendumFile = takeValue(args, i++, arg);
+    else if (arg === '--mark-command') opts.markCommand = takeValue(args, i++, arg);
+    else if (arg === '--var') {
+      const pair = takeValue(args, i++, arg);
+      const eq = pair.indexOf('=');
+      if (eq <= 0) throw new Error('--var must use KEY=VALUE');
+      opts.vars[pair.slice(0, eq)] = pair.slice(eq + 1);
+    } else if (arg === '--json') {
+      opts.json = true;
+      catalogArgs.push(arg);
+    } else if (arg === '-h' || arg === '--help') usage(0);
+    else catalogArgs.push(arg);
+  }
+  if (!opts.taskDir) throw new Error('task init requires <task-dir>');
+  if (!opts.template) throw new Error('task init requires --template <id>');
+  if (!opts.title) throw new Error('task init requires --title');
+  const catalog = parseCatalogArgs([...catalogArgs, '--id', opts.template]);
+  if (!catalog.flow) throw new Error('task init requires --flow');
+  if (!catalog.runMode) throw new Error('task init requires --run-mode');
+  if (!catalog.platform) throw new Error('task init requires --platform');
+  return { opts, catalog };
+}
+
+function gitOutput(args) {
+  try {
+    return execFileSync('git', args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    // Not a git checkout, or no remote: identity falls back to the directory name.
+    return '';
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === '-h' || args[0] === '--help') usage(0);
+  const { opts, catalog } = parseArgs(args);
+  const runtime = await loadRuntime();
+
+  const description = opts.taskFile
+    ? readFileSync(path.resolve(opts.taskFile), 'utf8').trim()
+    : (opts.taskText ?? '').trim();
+  const toplevel = gitOutput(['rev-parse', '--show-toplevel']);
+  const originUrl = gitOutput(['remote', 'get-url', 'origin']);
+  const repo = opts.repo ?? (originUrl ? runtime.portableRepoIdentity(originUrl) : undefined);
+  const project =
+    opts.project ??
+    (repo ? repo.split('/').pop() : path.basename(toplevel || process.cwd())).toLowerCase();
+  // Rendered inside taskInit with the same vars as the checklist, so an addendum
+  // that works on the farm works here.
+  const addendum = opts.addendumFile ? readFileSync(path.resolve(opts.addendumFile), 'utf8') : null;
+
+  const result = await runtime.taskInit({
+    taskDir: path.resolve(opts.taskDir),
+    taskDirLabel: opts.taskDirLabel ?? opts.taskDir,
+    flow: catalog.flow,
+    runMode: catalog.runMode,
+    platform: catalog.platform,
+    ...(catalog.domain ? { domain: catalog.domain } : {}),
+    template: { sources: buildSources(catalog, runtime), explicitId: opts.template },
+    task: {
+      title: opts.title,
+      description,
+      sourceKind: opts.taskFile ? 'file' : 'text',
+      ...(opts.ticket ? { ticket: opts.ticket } : {}),
+      ...(opts.sourceRef ? { sourceRef: opts.sourceRef } : {}),
+    },
+    handoff: {
+      surface: opts.surface,
+      project,
+      ...(repo ? { repo } : {}),
+      ...(opts.attemptId ? { attemptId: opts.attemptId } : {}),
+    },
+    vars: opts.vars,
+    ...(opts.modePreamble ? { modePreamble: opts.modePreamble } : {}),
+    addendum,
+    ...(opts.markCommand ? { markCommand: opts.markCommand } : {}),
+  });
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(`Task document: ${result.taskDocument}\nChecklist: ${result.checklist}\n`);
+  }
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/scripts/worker-terminal-contract.cjs

@@ -286,8 +286,11 @@ function templateBodyScope(content) {
 /**
  * Deterministic structure checks beyond terminal artifact contract.
  * @param {string} templateContent
+ * @param {{ roleChecklist?: boolean }} [options] roleChecklist: a nested-loop role
+ *   checklist (self-review, self-review-fix, ci-fix) rendered beside an existing
+ *   task dir; it may keep its own `## Task` block.
  */
-function lintWorkerTemplateStructure(templateContent) {
+function lintWorkerTemplateStructure(templateContent, options = {}) {
   /** @type {string[]} */
   const issues = [];
   if (/(?<!\{)\{TASK_DIR\}(?!\})/.test(templateContent)) {
@@ -302,8 +305,17 @@ function lintWorkerTemplateStructure(templateContent) {
     issues.push('terminal template missing `## Checklist` or `## Completion signal` section');
   }
 
-  if (!templateContent.includes('## Task') && !templateContent.includes('TASK_DIR:')) {
-    issues.push('missing `## Task` block or `TASK_DIR:` metadata');
+  // The task writer generates TASK.md (ticket block, description, acceptance
+  // criteria) and renders the flow template into CHECKLIST.md. A flow template
+  // that still carries the old `## Task` header duplicates that block inside
+  // the checklist.
+  if (
+    !options.roleChecklist &&
+    (/^## Task\s*$/m.test(templateContent) || /^TASK_DIR:\s/m.test(templateContent))
+  ) {
+    issues.push(
+      'carries a `## Task` block or `TASK_DIR:` line — the task writer generates TASK.md; keep only the checklist',
+    );
   }
 
   const scope = templateBodyScope(templateContent);