@farmslot/agent-runtime 0.8.1 → 0.9.0

package/dist/task-init/index.js

@@ -0,0 +1,120 @@
+// `task init`: the one producer of a task directory.
+//
+// A harness (or an engineer) calls `taskInit` with what it knows and gets the
+// same TASK.md, CHECKLIST.md, mark, and inputs/ a Farmslot dispatch writes. The
+// gateway composes the same pieces (`renderTemplatePlaceholders`,
+// `buildTaskDocument`, `writeTaskDir`) around its control-plane steps.
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { renderTemplatePlaceholders, } from '@farmslot/protocol';
+import { selectExecutionTemplate } from '../execution-template/select.js';
+import { executionTemplateReference, readExecutionTemplateSnapshot, } from '../execution-template/snapshot.js';
+import { buildHandoffMetadata, buildTaskDocument, HANDOFF_INPUT, } from './task-document.js';
+import { writeTaskDir } from './write.js';
+export * from './task-document.js';
+export * from './write.js';
+// The renderer lives in protocol; re-exported so CLI wrappers reach it through the runtime entry.
+export { renderTemplatePlaceholders } from '@farmslot/protocol';
+const require = createRequire(import.meta.url);
+/** Built-in terminal contract for a flow, as the gateway resolves it without project overrides. */
+export function builtinTerminalContract(flow, options = {}) {
+    const { resolveWorkerTerminalContract } = require('../../scripts/worker-terminal-contract.cjs');
+    return resolveWorkerTerminalContract(null, flow, options);
+}
+export async function taskInit(spec) {
+    const selected = selectExecutionTemplate({
+        sources: spec.template.sources,
+        flow: spec.flow,
+        platform: spec.platform,
+        runMode: spec.runMode,
+        ...(spec.domain ? { domain: spec.domain } : {}),
+        ...(spec.template.explicitId ? { explicitId: spec.template.explicitId } : {}),
+    });
+    const taskDirLabel = spec.taskDirLabel ?? spec.taskDir;
+    const vars = {
+        TICKET: spec.task.ticket ?? '',
+        TITLE: spec.task.title,
+        FLOW: spec.flow,
+        MODE: spec.runMode,
+        PLATFORM: spec.platform,
+        ...(spec.domain ? { DOMAIN: spec.domain } : {}),
+        TEMPLATE: selected.entry.id,
+        TASK_DIR: taskDirLabel,
+        ...(spec.task.sourceRef
+            ? /^https?:\/\//.test(spec.task.sourceRef)
+                ? { TICKET_URL: spec.task.sourceRef }
+                : { SOURCE_REF: spec.task.sourceRef }
+            : {}),
+        ...(spec.vars ?? {}),
+    };
+    const source = `Execution template ${selected.entry.id} (${selected.entry.sourceId})`;
+    const checklistMarkdown = renderTemplatePlaceholders(readExecutionTemplateSnapshot(selected.entry).markdown, vars, source);
+    const reference = executionTemplateReference(selected.entry, checklistMarkdown);
+    const executionTemplate = {
+        selectionReason: selected.reason,
+        ...reference,
+    };
+    const terminalContract = spec.terminalContract ?? builtinTerminalContract(spec.flow, { mode: spec.runMode });
+    const handoffMetadata = buildHandoffMetadata({
+        attemptId: spec.handoff.attemptId ?? randomUUID(),
+        surface: spec.handoff.surface,
+        project: spec.handoff.project,
+        flow: spec.flow,
+        repo: spec.handoff.repo,
+        domain: spec.domain,
+        title: spec.task.title,
+        sourceKind: spec.task.sourceKind,
+        ticket: spec.task.ticket,
+        sourceRef: spec.task.sourceRef,
+        terminalContract,
+        startedAt: spec.handoff.startedAt,
+        executionTemplate,
+    });
+    const taskMarkdown = buildTaskDocument({
+        flowType: spec.flow,
+        modePreamble: spec.modePreamble ?? '',
+        vars,
+        description: spec.task.description ?? '',
+        acceptanceCriteria: spec.task.acceptanceCriteria ?? [],
+        addendum: spec.addendum
+            ? renderTemplatePlaceholders(spec.addendum, vars, 'Task document addendum')
+            : null,
+        hasTicketData: spec.bugInput !== undefined,
+    });
+    const written = await writeTaskDir({
+        taskDir: spec.taskDir,
+        taskMarkdown,
+        checklistMarkdown,
+        markCommand: spec.markCommand,
+        handoff: handoffMetadata,
+        terminalContract,
+        bugInput: spec.bugInput,
+    });
+    return { ...written, executionTemplate, handoffMetadata };
+}
+/**
+ * Selected-template provenance for a task dir. Reads `inputs/handoff.json`;
+ * falls back to the pre-0.9 `inputs/template-provenance.json` for task dirs
+ * written before the merge. Drop the fallback next release.
+ */
+export function readTaskProvenance(taskDir) {
+    const handoffPath = path.join(taskDir, HANDOFF_INPUT);
+    if (existsSync(handoffPath)) {
+        const handoff = JSON.parse(readFileSync(handoffPath, 'utf-8'));
+        if (handoff.executionTemplate || handoff.templateProvenance) {
+            return {
+                ...(handoff.executionTemplate ? { executionTemplate: handoff.executionTemplate } : {}),
+                ...(handoff.templateProvenance ? { templateProvenance: handoff.templateProvenance } : {}),
+            };
+        }
+    }
+    const legacyPath = path.join(taskDir, 'inputs', 'template-provenance.json');
+    if (!existsSync(legacyPath))
+        return null;
+    const legacy = JSON.parse(readFileSync(legacyPath, 'utf-8'));
+    const { executionTemplate, ...templateProvenance } = legacy;
+    return { ...(executionTemplate ? { executionTemplate } : {}), templateProvenance };
+}
+//# sourceMappingURL=index.js.map

package/dist/task-init/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/task-init/index.ts"],"names":[],"mappings":"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"}

package/dist/task-init/task-document.d.ts

@@ -0,0 +1,98 @@
+import { type ExecutionTemplateReference, type TemplateProvenance, type WorkerTerminalContractDocument } from '@farmslot/protocol';
+export declare const HANDOFF_INPUT = "inputs/handoff.json";
+export declare const BUG_INPUT = "inputs/bug-input.json";
+/** Optional project-owned addendum rendered into TASK.md (relative to `templates/`). */
+export declare const TASK_DOCUMENT_ADDENDUM_TEMPLATE = "task-document.md";
+/**
+ * Acceptance criteria arrive as plain strings, but ticket adapters keep the
+ * author's list markers. Normalize to one bullet per criterion so TASK.md never
+ * carries a live `- [ ]` box that could be mistaken for a step.
+ */
+export declare function renderAcceptanceCriteria(items: ReadonlyArray<string>): string;
+export interface TaskDocumentInput {
+    flowType: string;
+    /** One blockquote line describing the run mode; empty string for none. */
+    modePreamble: string;
+    vars: Record<string, string>;
+    description: string;
+    acceptanceCriteria: ReadonlyArray<string>;
+    affectedArea?: string;
+    screenshotsMarkdown?: string;
+    commentsMarkdown?: string;
+    linkedTicketsMarkdown?: string;
+    linkedDescriptionsMarkdown?: string;
+    /** pr-complete: control-plane pre-fetched PR comment summary. */
+    commentSummaryMarkdown?: string;
+    /** Rendered project addendum (`templates/task-document.md`), if the project ships one. */
+    addendum?: string | null;
+    hasTicketData: boolean;
+}
+export declare function buildTaskDocument(input: TaskDocumentInput): string;
+export declare function readTaskDocumentAddendum(projectTemplatesDir: string): Promise<{
+    path: string;
+    content: string;
+} | null>;
+export type HandoffSourceKind = 'text' | 'file' | 'github-pr' | 'github-issue' | 'jira';
+/** Selected checklist, as `execution-template materialize --provenance` reports it. */
+export interface HandoffExecutionTemplate extends ExecutionTemplateReference {
+    selectionReason: string;
+}
+/**
+ * The one task record. `@farmslot/handoff closeout` reads the identity keys;
+ * replay and eval read `executionTemplate` / `templateProvenance`; everything
+ * else ignores keys it does not know.
+ */
+export interface HandoffMetadata {
+    schemaVersion: 1;
+    attemptId: string;
+    surface: string;
+    project: string;
+    repo?: string;
+    /** Effective run domain; empty string when none — the closeout parser requires the key. */
+    domain: string;
+    flow: string;
+    startedAt: string;
+    task: {
+        title: string;
+        sourceKind: HandoffSourceKind;
+        ticket?: string;
+        sourceRef?: string;
+    };
+    taskDocument: 'TASK.md';
+    report: string;
+    learnings: string;
+    executionTemplate?: HandoffExecutionTemplate;
+    /** Control-plane provenance (repo revisions, selection source); never carries the reference twice. */
+    templateProvenance?: Omit<TemplateProvenance, 'executionTemplate'>;
+}
+export declare function buildHandoffMetadata(input: {
+    attemptId: string;
+    surface: string;
+    project: string;
+    flow: string;
+    repo?: string;
+    domain?: string;
+    title: string;
+    sourceKind: HandoffSourceKind;
+    ticket?: string;
+    sourceRef?: string;
+    terminalContract: Pick<WorkerTerminalContractDocument, 'commands'>;
+    startedAt?: string;
+    executionTemplate?: HandoffExecutionTemplate;
+    templateProvenance?: Omit<TemplateProvenance, 'executionTemplate'>;
+}): HandoffMetadata;
+/**
+ * `owner/name` from a repository URL or scp-style remote. Undefined when the
+ * value is not portable (local path, credentialed URL, odd segments).
+ */
+export declare function portableRepoIdentity(raw: string): string | undefined;
+/**
+ * `owner/name` from a project's repository declaration (`repo_url` or `ci.repo`).
+ */
+export declare function portableProjectRepo(projectJson: {
+    repo_url?: unknown;
+    ci?: {
+        repo?: unknown;
+    };
+}): string | undefined;
+//# sourceMappingURL=task-document.d.ts.map

package/dist/task-init/task-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-document.d.ts","sourceRoot":"","sources":["../../src/task-init/task-document.ts"],"names":[],"mappings":"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"}

package/dist/task-init/task-document.js

@@ -0,0 +1,184 @@
+// TASK.md, the task document beside the CHECKLIST.md execution checklist.
+//
+// The execution template renders verbatim into CHECKLIST.md, the only file whose
+// checkboxes count as steps. TASK.md carries the task (description, acceptance
+// criteria, screenshots, comments), the run facts, the mark instructions, and
+// pointers to `inputs/`. One builder serves every surface: a control plane passes
+// its slot facts as extra vars; a harness passes only what it knows.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { EXECUTION_CHECKLIST_DOCUMENT, } from '@farmslot/protocol';
+export const HANDOFF_INPUT = 'inputs/handoff.json';
+export const BUG_INPUT = 'inputs/bug-input.json';
+/** Optional project-owned addendum rendered into TASK.md (relative to `templates/`). */
+export const TASK_DOCUMENT_ADDENDUM_TEMPLATE = 'task-document.md';
+/**
+ * Ordered keys of the `## Task` block. A key renders only when the caller set
+ * it, except the four every surface knows. Farmslot sets its slot facts; a
+ * harness sets FLOW/MODE/TEMPLATE; neither sees blank lines for the other's.
+ */
+const TASK_BLOCK_KEYS = [
+    { key: 'TICKET', required: true },
+    { key: 'TICKET_URL' },
+    { key: 'TITLE', required: true },
+    { key: 'FLOW' },
+    { key: 'MODE' },
+    { key: 'RUN_ID' },
+    { key: 'FAMILY_ID' },
+    { key: 'BRANCH' },
+    { key: 'PR_NUMBER' },
+    { key: 'PR_URL' },
+    { key: 'PR_BRANCH' },
+    { key: 'GH_REPO' },
+    { key: 'PR_INTEGRATION_NOTE', label: 'PR_INTEGRATION' },
+    { key: 'REVIEW_TIER' },
+    { key: 'RECIPE_STRATEGY' },
+    { key: 'BRANCH_UPDATE_STRATEGY' },
+    { key: 'HAS_RECIPE' },
+    { key: 'RECIPE_SOURCE' },
+    { key: 'TASK_DIR', required: true },
+    { key: 'SESSION' },
+    { key: 'REPO' },
+    { key: 'PLATFORM' },
+    { key: 'DOMAIN' },
+    { key: 'TEMPLATE' },
+    { key: 'SLOT_ID' },
+    { key: 'RUNTIME_DIR' },
+    { key: 'WATCHER_PORT' },
+    { key: 'CDP_PORT' },
+    { key: 'IOS_SIMULATOR' },
+    { key: 'ADB_SERIAL' },
+];
+/**
+ * Acceptance criteria arrive as plain strings, but ticket adapters keep the
+ * author's list markers. Normalize to one bullet per criterion so TASK.md never
+ * carries a live `- [ ]` box that could be mistaken for a step.
+ */
+export function renderAcceptanceCriteria(items) {
+    const normalized = items
+        .map((item) => item
+        .split('\n')
+        .map((line) => line
+        .trim()
+        .replace(/^[-*]\s+/, '')
+        .replace(/^\[(?: |x|X)\]\s*/, '')
+        .trim())
+        .filter(Boolean))
+        .filter((lines) => lines.length > 0)
+        // Continuation lines stay with their criterion, indented so they never start a list item.
+        .map(([first, ...rest]) => [`- ${first}`, ...rest.map((line) => `  ${line}`)].join('\n'));
+    return normalized.length > 0 ? normalized.join('\n') : '_Not specified_';
+}
+export function buildTaskDocument(input) {
+    const { vars } = input;
+    const taskDir = vars.TASK_DIR;
+    const title = vars.TITLE?.trim() || vars.TICKET || input.flowType;
+    const taskBlock = TASK_BLOCK_KEYS.filter(({ key, required }) => required || vars[key]?.trim())
+        .map(({ key, label }) => `${label ?? key}: ${vars[key] ?? ''}`)
+        .join('\n');
+    const sections = [`# ${input.flowType}: ${title}`, ''];
+    if (input.modePreamble.trim())
+        sections.push(input.modePreamble, '');
+    sections.push('## Task', '', '```text', taskBlock, 'STATUS: pending', '```', '', '## Description', '', input.description || '_No description_', '', '## Acceptance Criteria', '', renderAcceptanceCriteria(input.acceptanceCriteria));
+    if (input.affectedArea && input.affectedArea !== '_Not specified_') {
+        sections.push('', '## Affected Area', '', input.affectedArea);
+    }
+    if (input.screenshotsMarkdown && input.screenshotsMarkdown !== '_No screenshots_') {
+        sections.push('', '## Screenshots', '', input.screenshotsMarkdown);
+    }
+    if (input.commentsMarkdown && input.commentsMarkdown !== '_No comments_') {
+        sections.push('', '## Comments', '', input.commentsMarkdown);
+    }
+    if (input.linkedTicketsMarkdown && input.linkedTicketsMarkdown !== '_No linked tickets_') {
+        sections.push('', '## Linked Tickets', '', input.linkedTicketsMarkdown);
+    }
+    if (input.linkedDescriptionsMarkdown &&
+        input.linkedDescriptionsMarkdown !== '_No linked tickets_') {
+        sections.push('', '## Linked Ticket Descriptions', '', input.linkedDescriptionsMarkdown);
+    }
+    if (input.commentSummaryMarkdown?.trim()) {
+        sections.push('', '## Comment Summary', '', input.commentSummaryMarkdown.trim());
+    }
+    if (input.addendum?.trim()) {
+        sections.push('', input.addendum.trim());
+    }
+    sections.push('', '## Checklist', '', `Follow \`${taskDir}/${EXECUTION_CHECKLIST_DOCUMENT}\` top to bottom. That file is the only checklist that counts.`, `Marker: \`${taskDir}/mark\`, run from the repo root. \`mark start\` once when work begins, \`mark N\` after each step (visible 1-based number), then \`mark complete --mark-last\`, \`mark no-change --reason "…"\`, or \`mark blocked --reason "…"\`.`, 'Never hand-write `SIGNAL.json`. Do not add step checkboxes to this document; update `STATUS` above and append notes (for example `## Recipe ACs`) below.', '', '## Inputs', '', `Under \`${taskDir}/inputs/\`:`, '', `- \`${path.basename(HANDOFF_INPUT)}\` — run identity, selected checklist provenance, and terminal report paths`, '- `worker-terminal-contract.json` — artifacts required before a terminal mark');
+    if (input.hasTicketData) {
+        sections.push(`- \`${path.basename(BUG_INPUT)}\` — full ticket data as fetched`);
+    }
+    sections.push('');
+    return sections.join('\n');
+}
+export async function readTaskDocumentAddendum(projectTemplatesDir) {
+    const addendumPath = path.join(projectTemplatesDir, TASK_DOCUMENT_ADDENDUM_TEMPLATE);
+    if (!existsSync(addendumPath))
+        return null;
+    return { path: addendumPath, content: await readFile(addendumPath, 'utf-8') };
+}
+export function buildHandoffMetadata(input) {
+    const complete = input.terminalContract.commands.complete;
+    const ticket = input.ticket?.trim();
+    const sourceRef = input.sourceRef?.trim();
+    return {
+        schemaVersion: 1,
+        attemptId: input.attemptId,
+        surface: input.surface,
+        project: input.project,
+        ...(input.repo ? { repo: input.repo } : {}),
+        domain: input.domain ?? '',
+        flow: input.flow,
+        startedAt: input.startedAt ?? new Date().toISOString(),
+        task: {
+            title: input.title,
+            sourceKind: input.sourceKind,
+            ...(ticket ? { ticket } : {}),
+            ...(sourceRef ? { sourceRef } : {}),
+        },
+        taskDocument: 'TASK.md',
+        report: complete?.report ?? 'artifacts/report.md',
+        learnings: 'artifacts/learnings.md',
+        ...(input.executionTemplate ? { executionTemplate: input.executionTemplate } : {}),
+        ...(input.templateProvenance ? { templateProvenance: input.templateProvenance } : {}),
+    };
+}
+/**
+ * `owner/name` from a repository URL or scp-style remote. Undefined when the
+ * value is not portable (local path, credentialed URL, odd segments).
+ */
+export function portableRepoIdentity(raw) {
+    let pathname;
+    try {
+        const url = new URL(raw);
+        if (!['http:', 'https:', 'ssh:', 'git:'].includes(url.protocol))
+            return undefined;
+        pathname = url.pathname;
+    }
+    catch {
+        const scp = raw.match(/^(?:[^@/\s]+@)?[^:/\s]+:(.+)$/u);
+        if (scp)
+            pathname = scp[1];
+        else if (/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+$/u.test(raw))
+            pathname = raw;
+        else
+            return undefined;
+    }
+    const identity = pathname.replace(/^\/+|\/+$/gu, '').replace(/\.git$/iu, '');
+    const segments = identity.split('/');
+    const portable = segments.length > 0 &&
+        segments.every((segment) => segment !== '.' && segment !== '..' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(segment));
+    return portable ? identity : undefined;
+}
+/**
+ * `owner/name` from a project's repository declaration (`repo_url` or `ci.repo`).
+ */
+export function portableProjectRepo(projectJson) {
+    const candidates = [projectJson.repo_url, projectJson.ci?.repo].filter((value) => typeof value === 'string' && value.trim().length > 0);
+    for (const candidate of candidates) {
+        const identity = portableRepoIdentity(candidate.trim());
+        if (identity)
+            return identity;
+    }
+    return undefined;
+}
+//# sourceMappingURL=task-document.js.map

package/dist/task-init/task-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-document.js","sourceRoot":"","sources":["../../src/task-init/task-document.ts"],"names":[],"mappings":"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"}

package/dist/task-init/write.d.ts

@@ -0,0 +1,48 @@
+import { type WorkerTerminalContractDocument } from '@farmslot/protocol';
+import { type HandoffMetadata } from './task-document.js';
+export declare const TASK_DOCUMENT = "TASK.md";
+export declare const MARK_SHIM = "mark";
+/** Whole-command env override honoured by every `mark` shim. */
+export declare const MARK_COMMAND_ENV = "FARMSLOT_MARK_CMD";
+/**
+ * Quote one word for the shim's default command: double quotes keep spaces
+ * together while `$HOME` (a remote slot's home) still expands.
+ */
+export declare function quoteMarkCommandWord(word: string): string;
+/** Generic default: this package's mark engine. A control plane or harness passes its own. */
+export declare function defaultMarkCommand(): string;
+/**
+ * The `mark` shim. One env override, one recorded default; `markCommand` is a
+ * whole command line and stays unquoted so multi-word commands split and `$HOME`
+ * expands on the machine that runs it.
+ */
+export declare function buildMarkShim(markCommand: string): string;
+export interface WriteTaskDirInput {
+    /** Absolute task directory; created when missing. */
+    taskDir: string;
+    taskMarkdown: string;
+    /** null when the caller already wrote CHECKLIST.md (lightweight interactive dev). */
+    checklistMarkdown: string | null;
+    markCommand?: string;
+    handoff: HandoffMetadata;
+    terminalContract: WorkerTerminalContractDocument;
+    /** Ticket data as fetched, written to inputs/bug-input.json when present. */
+    bugInput?: unknown;
+    /**
+     * Transition only: also write `checklist-target.json` with the default target so
+     * a mark engine older than 0.9 (which fails closed without it) keeps working on
+     * slots not yet redeployed. Absent means the same thing. Remove next release.
+     */
+    writeChecklistManifest?: boolean;
+}
+export interface WrittenTaskDir {
+    taskDir: string;
+    taskDocument: string;
+    checklist: string | null;
+    mark: string;
+    handoff: string;
+    terminalContract: string;
+    bugInput: string | null;
+}
+export declare function writeTaskDir(input: WriteTaskDirInput): Promise<WrittenTaskDir>;
+//# sourceMappingURL=write.d.ts.map

package/dist/task-init/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/task-init/write.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,8BAA8B,EACpC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEpF,eAAO,MAAM,aAAa,YAAY,CAAC;AACvC,eAAO,MAAM,SAAS,SAAS,CAAC;AAChC,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAIpD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,8FAA8F;AAC9F,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAQzD;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,eAAe,CAAC;IACzB,gBAAgB,EAAE,8BAA8B,CAAC;IACjD,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CA8CpF"}

package/dist/task-init/write.js

@@ -0,0 +1,70 @@
+// The task-dir writer: the only code that lays out a task directory. A control
+// plane and a harness both call it, so the two surfaces cannot drift.
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CHECKLIST_TARGET_MANIFEST, EXECUTION_CHECKLIST_DOCUMENT, WORKER_TERMINAL_CONTRACT_INPUT, } from '@farmslot/protocol';
+import { BUG_INPUT, HANDOFF_INPUT } from './task-document.js';
+export const TASK_DOCUMENT = 'TASK.md';
+export const MARK_SHIM = 'mark';
+/** Whole-command env override honoured by every `mark` shim. */
+export const MARK_COMMAND_ENV = 'FARMSLOT_MARK_CMD';
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+/**
+ * Quote one word for the shim's default command: double quotes keep spaces
+ * together while `$HOME` (a remote slot's home) still expands.
+ */
+export function quoteMarkCommandWord(word) {
+    return `"${word.replace(/(["\\`])/g, '\\$1')}"`;
+}
+/** Generic default: this package's mark engine. A control plane or harness passes its own. */
+export function defaultMarkCommand() {
+    return `node ${quoteMarkCommandWord(path.join(packageRoot, 'scripts', 'mark-checklist-step.cjs'))}`;
+}
+/**
+ * The `mark` shim. One env override, one recorded default; `markCommand` is a
+ * whole command line and stays unquoted so multi-word commands split and `$HOME`
+ * expands on the machine that runs it.
+ */
+export function buildMarkShim(markCommand) {
+    return [
+        '#!/usr/bin/env bash',
+        'set -euo pipefail',
+        'DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"',
+        `exec \${${MARK_COMMAND_ENV}:-${markCommand}} "$DIR" "$@"`,
+        '',
+    ].join('\n');
+}
+export async function writeTaskDir(input) {
+    const taskDir = path.resolve(input.taskDir);
+    await mkdir(path.join(taskDir, 'inputs'), { recursive: true });
+    await mkdir(path.join(taskDir, 'artifacts'), { recursive: true });
+    const taskDocument = path.join(taskDir, TASK_DOCUMENT);
+    await writeFile(taskDocument, input.taskMarkdown, 'utf-8');
+    let checklist = null;
+    if (input.checklistMarkdown !== null) {
+        checklist = path.join(taskDir, EXECUTION_CHECKLIST_DOCUMENT);
+        await writeFile(checklist, input.checklistMarkdown, 'utf-8');
+    }
+    const mark = path.join(taskDir, MARK_SHIM);
+    await writeFile(mark, buildMarkShim(input.markCommand ?? defaultMarkCommand()), 'utf-8');
+    await chmod(mark, 0o755);
+    const handoff = path.join(taskDir, HANDOFF_INPUT);
+    await writeFile(handoff, `${JSON.stringify(input.handoff, null, 2)}\n`, 'utf-8');
+    const terminalContract = path.join(taskDir, WORKER_TERMINAL_CONTRACT_INPUT);
+    await writeFile(terminalContract, `${JSON.stringify(input.terminalContract, null, 2)}\n`, 'utf-8');
+    if (input.writeChecklistManifest) {
+        const checklistName = existsSync(path.join(taskDir, EXECUTION_CHECKLIST_DOCUMENT))
+            ? EXECUTION_CHECKLIST_DOCUMENT
+            : TASK_DOCUMENT;
+        await writeFile(path.join(taskDir, CHECKLIST_TARGET_MANIFEST), `${JSON.stringify({ checklist: checklistName, signal: 'SIGNAL.json' }, null, 2)}\n`, 'utf-8');
+    }
+    let bugInput = null;
+    if (input.bugInput !== undefined) {
+        bugInput = path.join(taskDir, BUG_INPUT);
+        await writeFile(bugInput, `${JSON.stringify(input.bugInput, null, 2)}\n`, 'utf-8');
+    }
+    return { taskDir, taskDocument, checklist, mark, handoff, terminalContract, bugInput };
+}
+//# sourceMappingURL=write.js.map

package/dist/task-init/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/task-init/write.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/agent-runtime",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,11 +17,20 @@
     "./scripts/checklist-target.cjs": "./scripts/checklist-target.cjs",
     "./scripts/worker-terminal-contract.cjs": "./scripts/worker-terminal-contract.cjs",
     "./scripts/check-task-artifact-contract.mjs": "./scripts/check-task-artifact-contract.mjs",
-    "./scripts/execution-template-cli.mjs": "./scripts/execution-template-cli.mjs"
+    "./scripts/execution-template-cli.mjs": "./scripts/execution-template-cli.mjs",
+    "./scripts/task-init-cli.mjs": "./scripts/task-init-cli.mjs",
+    "./native": {
+      "types": "./dist/native/index.d.ts",
+      "import": "./dist/native/index.js"
+    },
+    "./native/*": {
+      "types": "./dist/native/*.d.ts",
+      "import": "./dist/native/*.js"
+    }
   },
   "scripts": {
     "typecheck": "yarn workspace @farmslot/protocol build && tsc --noEmit --project tsconfig.json",
-    "test": "node test/mark-checklist-step.test.cjs && node test/checklist-target-sync.test.mjs && node test/package-exports.test.cjs && node test/check-task-artifact-contract.test.cjs && node test/recipe-quality-builder.test.cjs && node ../../scripts/quality/run-tsx-tests.mjs --cwd . --tsconfig tsconfig.json src/execution-template",
+    "test": "node test/mark-checklist-step.test.cjs && node test/checklist-target-sync.test.mjs && node test/package-exports.test.cjs && node test/check-task-artifact-contract.test.cjs && node test/recipe-quality-builder.test.cjs && node test/task-init.test.mjs && node ../../scripts/quality/run-tsx-tests.mjs --cwd . --tsconfig tsconfig.json src/execution-template && node ../../scripts/quality/run-tsx-tests.mjs --cwd . --tsconfig tsconfig.json src/native",
     "format": "prettier --write --ignore-path ../../.prettierignore .",
     "format:check": "prettier --check --ignore-path ../../.prettierignore .",
     "lint": "eslint \"src/**/*.ts\"",
@@ -32,7 +41,7 @@
     "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/agent-runtime"
   },
   "dependencies": {
-    "@farmslot/protocol": "0.21.0"
+    "@farmslot/protocol": "0.26.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/scripts/checklist-target.cjs

@@ -170,8 +170,8 @@ function readManifest(taskDir) {
 function manifestModeTeachingError(taskDir, reason) {
   const manifestPath = path.join(path.resolve(taskDir), CHECKLIST_TARGET_MANIFEST);
   return (
-    `Missing or invalid ${CHECKLIST_TARGET_MANIFEST} at ${manifestPath} (${reason}). ` +
-    'The gateway writes this file at task creation and on every role switch — re-run dispatch/prepare for this run, or write the manifest manually. ' +
+    `Invalid ${CHECKLIST_TARGET_MANIFEST} at ${manifestPath} (${reason}). ` +
+    'Absent means the worker default; a role switch writes this file to point at its own checklist — re-run the role switch, fix the JSON, or remove the file. ' +
     'Escape hatch: farmslot-agent mark <task-dir> --checklist FILE.md <step> [--signal FILE.json].'
   );
 }
@@ -244,8 +244,10 @@ function parseTaskDirMarkArgs(taskDir, rawArgs, { isMarkStepToken, usage }) {
 function resolveChecklistTarget(taskDir) {
   const normalizedDir = path.resolve(taskDir);
   const manifestPath = path.join(normalizedDir, CHECKLIST_TARGET_MANIFEST);
+  // Absent means the worker default (CHECKLIST.md when present, else TASK.md).
+  // Only a role switch writes the manifest, to point at its own checklist.
   if (!fs.existsSync(manifestPath)) {
-    throw new Error(manifestModeTeachingError(taskDir, 'file not found'));
+    return defaultWorkerTarget(normalizedDir);
   }
   const fromManifest = readManifest(normalizedDir);
   if (!fromManifest) {