@repo-os/repoos 0.5.45

package/dist/server/freeform.d.ts

@@ -0,0 +1,55 @@
+/** Fields extracted from the agent's generated file, fed to createTask. */
+export interface GeneratedTaskInput {
+    title: string;
+    type?: string;
+    priority?: string;
+    area?: string;
+    assignedTo?: string;
+    body: string;
+    /**
+     * Whether the agent's output actually contained a `---` frontmatter block
+     * (#0345). False means the agent replied with something other than the
+     * requested file content — e.g. a status message like "Done, I wrote the
+     * file" instead of the file itself — and `title`/`body` are a best-effort
+     * fallback (the raw output verbatim), not real task content. Callers
+     * should treat `false` as a failed generation, not a usable result.
+     */
+    hadFrontmatter: boolean;
+}
+/**
+ * A short, human title for a raw explanation, for the no-agent fallback.
+ * First non-empty, non-delimiter line of the explanation wins; otherwise the
+ * first 60 chars. Delimiter lines (a line that is exactly `---`) are skipped so
+ * a stray frontmatter delimiter can never become a title.
+ */
+export declare function explanationTitle(explanation: string): string;
+/**
+ * Drop leaked tool-call markup from an agent's answer.
+ *
+ * Only whole lines are removed, and only outside fenced code blocks, so a task
+ * that legitimately quotes markup in a code block keeps it. When a removal
+ * strands a second consecutive blank line, one is dropped so cutting a block
+ * out of the middle of a body doesn't leave a gap. A body with no leaked
+ * tokens is returned unchanged.
+ */
+export declare function stripToolCallMarkup(output: string): string;
+/**
+ * Parse the PM agent's generated markdown into createTask input. Never throws:
+ * anything unparsable falls back to treating the whole output as the body with
+ * a derived title, so input survives a bad agent response.
+ *
+ * The agent's answer is the task file verbatim, so any tool-call markup it
+ * leaked would be persisted as body text — it is stripped before parsing so a
+ * leaked token can never become the title either.
+ */
+export declare function parseGeneratedTask(rawOutput: string): GeneratedTaskInput;
+/**
+ * Build the PM agent's prompt from a raw explanation.
+ *
+ * The system already persists the raw explanation under a `## Original prompt`
+ * section before the PM runs, so the PM is told not to duplicate it. It should
+ * still end with the structured body only; the system re-ensures the section.
+ */
+export declare function pmPrompt(explanation: string): string;
+/** The persisted setting key that controls the drawer's default mode. */
+export declare const DEFAULT_TASK_MODE_KEY = "defaultTaskMode";

package/dist/server/freeform.js

@@ -0,0 +1,179 @@
+import { FM_DELIM, parseDocument } from "../core/frontmatter.js";
+const TASK_TYPES = ["feature", "bug", "chore", "spec", "refactor"];
+const PRIORITIES = ["p0", "p1", "p2", "p3"];
+/**
+ * A short, human title for a raw explanation, for the no-agent fallback.
+ * First non-empty, non-delimiter line of the explanation wins; otherwise the
+ * first 60 chars. Delimiter lines (a line that is exactly `---`) are skipped so
+ * a stray frontmatter delimiter can never become a title.
+ */
+export function explanationTitle(explanation) {
+    const line = explanation
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => Boolean(l) && l !== FM_DELIM) ?? "";
+    if (line.length > 0) {
+        return line.length <= 60 ? line : `${line.slice(0, 57).trimEnd()}…`;
+    }
+    const flat = explanation
+        .replace(/\s+/g, " ")
+        .replace(/\s*---\s*/g, " ")
+        .trim();
+    return flat.length <= 60 ? flat || "Untitled task" : `${flat.slice(0, 57).trimEnd()}…`;
+}
+function firstMatch(value, allowed, fallback) {
+    const v = typeof value === "string" ? value.toLowerCase().trim() : "";
+    return allowed.find((a) => a === v) ?? fallback;
+}
+/**
+ * The control-token names a leaked tool call is built from. Kept as bare names
+ * so every dialect below is matched by one pattern.
+ */
+const TOOL_TOKEN_NAMES = "tool_calls?|tool\u2581calls?|function_calls|function_results|invoke|parameter";
+/**
+ * A line that is nothing but a tool-call control token. Models that render
+ * tool calls as inline markup can emit these into plain prose when a turn is
+ * cut short, in several dialects: bare (`<parameter>`), namespaced
+ * (`<ns:invoke>`), and special-token wrapped, where the delimiter is either an
+ * ASCII or a fullwidth vertical bar.
+ *
+ * Deliberately anchored to the whole line: a task body legitimately discusses
+ * markup inline (`the <input> element`), and only a lone control token on its
+ * own line is unambiguous leakage.
+ */
+const TOOL_TOKEN_LINE = new RegExp(`^<\\/?[\uff5c|]?\\s*(?:[\\w.-]+[:\u2581\uff5c|])?(?:${TOOL_TOKEN_NAMES})(?:[_\u2581](?:begin|end))?\\b[^>]*[\uff5c|]?\\s*\\/?>$`);
+/** True for a fenced-code-block delimiter line (``` or ~~~). */
+function isFence(line) {
+    return /^(?:```|~~~)/.test(line);
+}
+/**
+ * Drop leaked tool-call markup from an agent's answer.
+ *
+ * Only whole lines are removed, and only outside fenced code blocks, so a task
+ * that legitimately quotes markup in a code block keeps it. When a removal
+ * strands a second consecutive blank line, one is dropped so cutting a block
+ * out of the middle of a body doesn't leave a gap. A body with no leaked
+ * tokens is returned unchanged.
+ */
+export function stripToolCallMarkup(output) {
+    const kept = [];
+    let inFence = false;
+    let removed = false;
+    for (const line of output.split("\n")) {
+        const trimmed = line.trim();
+        if (isFence(trimmed))
+            inFence = !inFence;
+        if (!inFence && TOOL_TOKEN_LINE.test(trimmed)) {
+            removed = true;
+            continue;
+        }
+        const previous = kept[kept.length - 1];
+        if (removed && !inFence && trimmed === "" && previous !== undefined && previous.trim() === "") {
+            continue;
+        }
+        kept.push(line);
+    }
+    return removed ? kept.join("\n").trim() : output;
+}
+/**
+ * Parse the PM agent's generated markdown into createTask input. Never throws:
+ * anything unparsable falls back to treating the whole output as the body with
+ * a derived title, so input survives a bad agent response.
+ *
+ * The agent's answer is the task file verbatim, so any tool-call markup it
+ * leaked would be persisted as body text — it is stripped before parsing so a
+ * leaked token can never become the title either.
+ */
+export function parseGeneratedTask(rawOutput) {
+    const output = stripToolCallMarkup(rawOutput);
+    const { data, body, hadFrontmatter } = parseDocument(output.trim());
+    const rawTitle = typeof data.title === "string" && data.title.trim()
+        ? data.title.trim()
+        : typeof data.title === "number"
+            ? String(data.title)
+            : "";
+    if (hadFrontmatter) {
+        // A frontmatter block was present (open, closed, or embedded-in-body).
+        // Use its parsed fields; the title falls back to the body's first line so
+        // a delimiter can never leak into the title.
+        return {
+            title: rawTitle || explanationTitle(body),
+            type: firstMatch(data.type, TASK_TYPES),
+            priority: firstMatch(data.priority, PRIORITIES),
+            area: typeof data.area === "string" && data.area.trim() ? data.area.trim() : undefined,
+            assignedTo: typeof data.assigned_to === "string" && data.assigned_to.trim()
+                ? data.assigned_to.trim()
+                : undefined,
+            body: body.trim(),
+            hadFrontmatter: true,
+        };
+    }
+    // No usable frontmatter: the agent didn't return the file content it was
+    // asked for (e.g. a "Done, I wrote it" status reply instead — #0345). Keep
+    // the raw output as a best-effort title/body so nothing here throws, but
+    // `hadFrontmatter: false` tells the caller this is not real task content —
+    // it must not be allowed to overwrite the draft.
+    return { title: explanationTitle(output), body: output.trim(), hadFrontmatter: false };
+}
+/** The task-file conventions the PM agent must follow, inlined into its prompt. */
+const TASK_CONVENTIONS = [
+    "Task files are markdown with YAML frontmatter, like:",
+    "---",
+    'id: "0001"        # assigned by the system — do NOT include',
+    "title: Short imperative title",
+    "type: feature     # feature | bug | chore | spec | refactor",
+    "status: inbox     # assigned by the system — do NOT include",
+    "priority: p2      # p0 | p1 | p2 | p3",
+    "area: web         # the part of the product, e.g. web, core, cli, ui, api",
+    "assigned_to: ai   # ai | human | unassigned",
+    "branch: feat/slug # derived from the title — do NOT include",
+    "created_at: ...   # assigned by the system — do NOT include",
+    "updated_at: ...   # assigned by the system — do NOT include",
+    "---",
+    "",
+    "The body follows with markdown sections, in order:",
+    "- ## Problem — what's broken or missing, why it matters",
+    "- ## Desired UX — what the end experience should be",
+    "- ## Acceptance criteria — a concrete checkbox list (- [ ] ...)",
+    "- ## Notes for AI — constraints, files to touch, things NOT to do",
+    "- ## Scope (optional) — what this task covers and what is deferred",
+    "- ## Related (optional) — related task ids or docs",
+    "- ## Activity — leave it out; the system appends entries",
+    "",
+    "Flesh out each section with concrete detail drawn ONLY from the explanation.",
+    "Do not invent requirements the user did not imply. When a detail is genuinely",
+    "ambiguous, pick a reasonable default and state the assumption in Notes for AI.",
+    "Do not ask clarifying questions.",
+].join("\n");
+/**
+ * Build the PM agent's prompt from a raw explanation.
+ *
+ * The system already persists the raw explanation under a `## Original prompt`
+ * section before the PM runs, so the PM is told not to duplicate it. It should
+ * still end with the structured body only; the system re-ensures the section.
+ */
+export function pmPrompt(explanation) {
+    return [
+        "You are the PM agent for RepoOS. Turn the user's rough explanation into a",
+        "complete, well-formed task file that drops straight into the repo's work/ dir.",
+        "",
+        "The user's explanation:",
+        "",
+        "```",
+        explanation.trim(),
+        "```",
+        "",
+        "The raw explanation is already stored by the system under a",
+        "'## Original prompt' section, so do NOT repeat it in your output — write",
+        "the structured body only (the section is re-appended for you).",
+        "",
+        "Task-file conventions (follow them exactly):",
+        "",
+        TASK_CONVENTIONS,
+        "",
+        "Respond with ONLY the markdown file content, starting with the opening '---'",
+        "line and with no preamble, commentary, or code fences.",
+    ].join("\n");
+}
+/** The persisted setting key that controls the drawer's default mode. */
+export const DEFAULT_TASK_MODE_KEY = "defaultTaskMode";

package/dist/server/handoff.d.ts

@@ -0,0 +1,99 @@
+import type { RepoOSConfig, Status, Task } from "../core/types.js";
+import type { AgentHandoffRequest, AgentRunner } from "./agents.js";
+import type { TaskCheckManager, TaskCheckListener } from "./task-check.js";
+export type HandoffStep = "validate" | "check" | "commit" | "review" | "main" | "done";
+export interface HandoffResult {
+    ok: boolean;
+    detail?: string;
+    step: HandoffStep;
+}
+/**
+ * Finalize one capability issued by an active runner turn.
+ *
+ * Enforces a hard deadline (600s) on the entire finalization process. If any
+ * step (validate, check, commit, review, main) exceeds the deadline, the
+ * finalization is abandoned and returned as failed. This ensures the handoff
+ * promise never hangs indefinitely.
+ */
+export declare function handoffTask(config: RepoOSConfig, task: Task, request: AgentHandoffRequest, onProgress?: (step: HandoffStep) => void, onStatusChange?: (task: Task, prev: Status, next: Status) => void, 
+/** Records this finalization's `repoos check` run for the Debug tab (0310). */
+taskChecks?: TaskCheckManager, onTaskCheckEvent?: TaskCheckListener): Promise<HandoffResult>;
+/**
+ * On a finalization failure at the `check` step, automatically resume the
+ * same engineer session with the check output and ask it to fix (or re-verify,
+ * if the failure looks transient) and re-hand-off — up to
+ * `MAX_CHECK_RETRY_ATTEMPTS` times. Every other failure step (validate,
+ * commit, review, main) is structural/environmental, not something a plain
+ * retry of the same session fixes, so only `check` is retried.
+ *
+ * Returns true when a retry was scheduled. On give-up (cap reached, or no
+ * engineer configured) the failure reason is persisted to the task's Activity
+ * log via `AgentRunner.persistHandoffFailure` so the task watchdog classifies
+ * it correctly instead of falling back to its generic
+ * "exited without handoff" guess.
+ */
+export declare function scheduleCheckFailureRetry(config: RepoOSConfig, task: Task, result: HandoffResult, runner: AgentRunner, 
+/** Called right after `check_retry_count` is persisted so the live index
+ *  (and its SSE `task.updated` event) picks up the new count immediately —
+ *  this write bypasses `patchTaskFile`, so nothing else refreshes it. */
+onFileChange?: (absPath: string) => void): boolean;
+/**
+ * On a close-out `validating`-phase failure caused by a REAL merge conflict
+ * (the candidate's merge of the feature branch into itself failed with named
+ * conflicting paths — not the task's own bookkeeping file or `dist/`/
+ * `screenshots/`, which auto-resolve, and not an infra failure), automatically
+ * resume the task's engineer session and ask it to merge main into ITS OWN
+ * branch and resolve the conflict there — the exact manual recovery
+ * docs/close-out-pipeline.md prescribes (#0271 follow-up: this was
+ * previously always a human/agent-operator manual step, discovered when
+ * task #0282 sat failed until someone noticed).
+ *
+ * Unlike `scheduleCheckFailureRetry`, this does NOT ask the engineer to
+ * re-emit the handoff signal — the task is already `review`, and a fresh
+ * handoff attempt against an already-`review` task just short-circuits as
+ * "already finalized" (see the check near the top of `handoffTask`) without
+ * re-running the close-out. Instead, server.ts's `agent.exited` handler
+ * watches for this exact session ending while its job is still the
+ * failed-on-this-conflict record, and re-enqueues the close-out itself —
+ * the same action a human clicking "Move to done" again performs. The
+ * engineer's job is just to fix the branch and end its turn.
+ *
+ * Otherwise mirrors `scheduleCheckFailureRetry` closely: same retry cap
+ * shape, same give-up-to-persistHandoffFailure fallback, same
+ * do-not-flip-status behavior (the task stays in `review` — TaskCard.vue can
+ * label this state the same way it labels a check-failure retry). Capped,
+ * because a conflict that survives two resolve attempts is very likely the
+ * agent resolving it WRONG in a way that reintroduces the same conflict, not
+ * something a third attempt fixes — same logic `MAX_CHECK_RETRY_ATTEMPTS`
+ * already encodes.
+ *
+ * Returns true when a retry was scheduled.
+ */
+export declare function scheduleMergeConflictRetry(config: RepoOSConfig, task: Task, reason: string, runner: AgentRunner, 
+/** Same purpose as in `scheduleCheckFailureRetry` — let the live index pick
+ *  up the new retry count immediately via its own SSE event. */
+onFileChange?: (absPath: string) => void): boolean;
+/**
+ * Third instance of the same pattern (#0271 follow-up), for the task-watchdog's
+ * `exited-without-handoff` classification (task-watchdog.ts): a session ran to
+ * completion but its final line wasn't exactly `::repoos-handoff-ready::`, so no
+ * handoff ever fired. Previously the watchdog could only surface this — move
+ * the task to `review`/`ready` and leave a human to notice and click Restart
+ * (task #0268 sat this way until someone asked "why hasn't this recovered on
+ * its own").
+ *
+ * Unlike the other two, this failure has no specific diagnostic to hand back —
+ * "you didn't finish right" is vaguer than a named conflict or check output —
+ * so it's a strictly weaker signal, which is exactly why the watchdog didn't
+ * already do this: auto-resuming on a vague prompt risks looping on genuine
+ * confusion, not just fixing a rendering hiccup. The cap bounds that risk the
+ * same way it bounds the other two; on exhaustion this returns false and the
+ * caller (task-watchdog.ts) falls through to its EXISTING surface behavior —
+ * there is no separate give-up path here, unlike the other two schedulers,
+ * because surfacing already IS the correct terminal state the watchdog was
+ * built for.
+ *
+ * Returns true when a retry was scheduled; false means "give up, surface it
+ * the normal way" — either the cap was hit or no engineer is configured.
+ */
+export declare function scheduleHandoffSignalRetry(config: RepoOSConfig, task: Task, runner: AgentRunner, onFileChange?: (absPath: string) => void): boolean;