@kkelly-offical/kkcode 0.1.2

package/src/session/longagent-plan.mjs

@@ -0,0 +1,329 @@
+import { newId } from "../core/types.mjs"
+import { processTurnLoop } from "./loop.mjs"
+
+function stripFence(text = "") {
+  const raw = String(text || "").trim()
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i)
+  if (fenced) return fenced[1].trim()
+  return raw
+}
+
+function parseJsonLoose(text = "") {
+  const raw = stripFence(text)
+  try {
+    return JSON.parse(raw)
+  } catch {
+    const start = raw.indexOf("{")
+    const end = raw.lastIndexOf("}")
+    if (start >= 0 && end > start) {
+      try {
+        return JSON.parse(raw.slice(start, end + 1))
+      } catch {
+        return null
+      }
+    }
+    return null
+  }
+}
+
+function normalizeFileList(value) {
+  if (!Array.isArray(value)) return []
+  return [...new Set(value
+    .map((v) => String(v || "").trim())
+    .filter(Boolean)
+    .slice(0, 80))]
+}
+
+function normalizeStringList(value) {
+  if (!Array.isArray(value)) return []
+  return value
+    .map((v) => String(v || "").trim())
+    .filter(Boolean)
+    .slice(0, 50)
+}
+
+function normalizeTask(task, stageId, defaults = {}) {
+  const baseId = String(task?.taskId || task?.id || "").trim()
+  const taskId = baseId || `${stageId}_task_${newId("t").slice(-6)}`
+  const prompt = String(task?.prompt || "").trim()
+  if (!prompt) return null
+  const timeoutMs = Number(task?.timeoutMs || defaults.timeoutMs || 600000)
+  const maxRetries = Number(task?.maxRetries ?? defaults.maxRetries ?? 2)
+  return {
+    taskId,
+    prompt,
+    subagentType: task?.subagentType ? String(task.subagentType) : undefined,
+    category: task?.category ? String(task.category) : undefined,
+    plannedFiles: normalizeFileList(task?.plannedFiles),
+    acceptance: normalizeStringList(task?.acceptance),
+    timeoutMs: Number.isFinite(timeoutMs) && timeoutMs >= 1000 ? timeoutMs : 600000,
+    maxRetries: Number.isFinite(maxRetries) && maxRetries >= 0 ? maxRetries : 2
+  }
+}
+
+function normalizeStage(stage, defaults = {}, idx = 0) {
+  const stageId = String(stage?.stageId || stage?.id || `stage_${idx + 1}`).trim() || `stage_${idx + 1}`
+  const name = String(stage?.name || `Stage ${idx + 1}`).trim() || `Stage ${idx + 1}`
+  const tasks = Array.isArray(stage?.tasks)
+    ? stage.tasks.map((t) => normalizeTask(t, stageId, defaults)).filter(Boolean)
+    : []
+  return {
+    stageId,
+    name,
+    passRule: "all_success",
+    tasks
+  }
+}
+
+export function defaultStagePlan(objective, defaults = {}) {
+  const stageId = "stage_1"
+  return {
+    planId: newId("plan"),
+    objective: String(objective || "").trim(),
+    stages: [
+      {
+        stageId,
+        name: "Execution",
+        passRule: "all_success",
+        tasks: [
+          {
+            taskId: `${stageId}_task_1`,
+            prompt: String(objective || "").trim(),
+            plannedFiles: [],
+            acceptance: ["Task objective is fully usable"],
+            timeoutMs: Number(defaults.timeoutMs || 600000),
+            maxRetries: Number(defaults.maxRetries ?? 2)
+          }
+        ]
+      }
+    ]
+  }
+}
+
+export function validateAndNormalizeStagePlan(input, { objective = "", defaults = {} } = {}) {
+  if (!input || typeof input !== "object") {
+    return { plan: defaultStagePlan(objective, defaults), errors: ["plan is not object"] }
+  }
+
+  const plan = {
+    planId: String(input.planId || newId("plan")),
+    objective: String(input.objective || objective || "").trim(),
+    stages: Array.isArray(input.stages)
+      ? input.stages.map((s, idx) => normalizeStage(s, defaults, idx))
+      : []
+  }
+
+  const errors = []
+  if (!plan.objective) errors.push("objective is empty")
+  if (!plan.stages.length) errors.push("no stages")
+  for (const stage of plan.stages) {
+    if (!stage.tasks.length) errors.push(`stage "${stage.stageId}" has no tasks`)
+    // Early file isolation check — detect overlapping file ownership at plan time
+    const ownership = new Map()
+    for (const task of stage.tasks) {
+      for (const file of task.plannedFiles || []) {
+        if (ownership.has(file)) {
+          errors.push(`stage "${stage.stageId}": file "${file}" claimed by "${ownership.get(file)}" and "${task.taskId}"`)
+        } else {
+          ownership.set(file, task.taskId)
+        }
+      }
+    }
+  }
+
+  // Cross-stage dependency check: later stages should not own files already owned by earlier stages
+  const globalOwnership = new Map()
+  for (const stage of plan.stages) {
+    for (const task of stage.tasks) {
+      for (const file of task.plannedFiles || []) {
+        if (globalOwnership.has(file)) {
+          const prev = globalOwnership.get(file)
+          errors.push(`file "${file}" appears in stage "${prev}" and "${stage.stageId}" — split into dependency chain or deduplicate`)
+        } else {
+          globalOwnership.set(file, stage.stageId)
+        }
+      }
+    }
+  }
+
+  // Quality score: penalize tasks with no files or no acceptance criteria
+  let qualityScore = 100
+  let totalTasks = 0
+  for (const stage of plan.stages) {
+    for (const task of stage.tasks) {
+      totalTasks += 1
+      if (!task.plannedFiles.length) qualityScore -= 15
+      if (!task.acceptance.length) qualityScore -= 10
+    }
+  }
+  qualityScore = Math.max(0, Math.min(100, qualityScore))
+
+  if (errors.length) {
+    return {
+      plan: defaultStagePlan(objective || plan.objective, defaults),
+      errors,
+      qualityScore: 0
+    }
+  }
+  return { plan, errors: [], qualityScore }
+}
+
+export async function runIntakeDialogue({
+  objective,
+  model,
+  providerType,
+  sessionId,
+  configState,
+  baseUrl = null,
+  apiKeyEnv = null,
+  agent = null,
+  signal = null,
+  maxRounds = 6
+}) {
+  const rounds = Math.max(1, Number(maxRounds || 6))
+  const transcript = []
+  let summary = ""
+
+  for (let i = 1; i <= rounds; i++) {
+    const prompt = [
+      "You are performing pre-planning intake for a long-running coding task.",
+      "Ask the most critical clarifying questions, then answer them with explicit assumptions.",
+      "Return STRICT JSON:",
+      `{"enough":boolean,"summary":"...","qa":[{"q":"...","a":"..."}]}`,
+      "",
+      `Round: ${i}/${rounds}`,
+      `Objective: ${objective}`,
+      summary ? `Previous summary: ${summary}` : ""
+    ].filter(Boolean).join("\n")
+
+    const out = await processTurnLoop({
+      prompt,
+      mode: "ask",
+      model,
+      providerType,
+      sessionId,
+      configState,
+      baseUrl,
+      apiKeyEnv,
+      agent,
+      signal,
+      output: { write: () => {} },
+      allowQuestion: true
+    })
+
+    const parsed = parseJsonLoose(out.reply)
+    if (parsed && Array.isArray(parsed.qa)) {
+      for (const item of parsed.qa.slice(0, 10)) {
+        const q = String(item?.q || "").trim()
+        const a = String(item?.a || "").trim()
+        if (q || a) transcript.push({ q, a })
+      }
+      summary = String(parsed.summary || "").trim() || summary
+      const enough = Boolean(parsed.enough)
+      if (enough && i >= 2) break
+      continue
+    }
+
+    const fallbackLine = String(out.reply || "").trim()
+    if (fallbackLine) {
+      transcript.push({ q: `Round ${i} synthesis`, a: fallbackLine })
+      summary = fallbackLine
+    }
+    if (i >= 2) break
+  }
+
+  return {
+    transcript,
+    summary: summary || String(objective || "").trim()
+  }
+}
+
+export async function buildStagePlan({
+  objective,
+  intakeSummary = "",
+  model,
+  providerType,
+  sessionId,
+  configState,
+  baseUrl = null,
+  apiKeyEnv = null,
+  agent = null,
+  signal = null,
+  defaults = {}
+}) {
+  const plannerPrompt = [
+    "Generate a stage plan for parallel execution of a coding task.",
+    "Return STRICT JSON ONLY with this schema:",
+    '{"planId":"...","objective":"...","stages":[{"stageId":"...","name":"...","passRule":"all_success","tasks":[{"taskId":"...","prompt":"...","subagentType":"...","category":"...","plannedFiles":["..."],"acceptance":["..."],"timeoutMs":600000,"maxRetries":2}]}]}',
+    "",
+    "## Planning Rules",
+    "",
+    "### File Assignment (CRITICAL)",
+    "- Files that import from each other MUST be in the same task",
+    "- A module and its tests MUST be in the same task",
+    "- A component and its type definitions MUST be in the same task",
+    "- Each task should own 2-8 files. If only 1 file, merge with related task. If >10 files, split.",
+    "- NO file may appear in multiple tasks within the same stage",
+    "",
+    "### Stage Ordering",
+    "- Stages execute sequentially; tasks within a stage execute in parallel",
+    "- Order: Infrastructure/utilities → Core logic → Integration/UI → Tests/Validation",
+    "- If Task B depends on Task A's output (e.g. imports from files Task A creates), they MUST be in different stages (A's stage before B's stage)",
+    "",
+    "### Task Requirements",
+    "- passRule must be all_success",
+    "- each stage must have 1..8 tasks",
+    "- each task MUST include: prompt (detailed instructions), plannedFiles (specific file paths), acceptance (machine-verifiable criteria)",
+    "- keep task scope independent for parallel execution",
+    "- task prompts should be self-contained — the sub-agent has no context beyond what you write",
+    "",
+    "### Acceptance Criteria Rules",
+    "- MUST be machine-verifiable (e.g. 'node --check passes', 'npm test passes', 'function X is exported from Y')",
+    "- NEVER use subjective criteria (e.g. 'code quality is good', 'implementation is clean')",
+    "- Each task MUST have at least one acceptance criterion from these categories:",
+    "  1. Syntax: 'node --check <file>' or 'python -m py_compile <file>'",
+    "  2. Build: 'npm run build succeeds' (if applicable)",
+    "  3. Functional: 'function X exists and handles Y' or 'API endpoint returns Z'",
+    "  4. Test: 'npm test passes' or 'specific test file passes'",
+    "- The FINAL stage should include a synthesis acceptance criterion: 'all modified files parse without errors AND project builds successfully'",
+    "",
+    "### Example (2-stage plan)",
+    '{"planId":"plan_ex","objective":"Add user auth","stages":[',
+    '  {"stageId":"s1","name":"Auth core","passRule":"all_success","tasks":[',
+    '    {"taskId":"s1_auth","prompt":"Implement JWT auth middleware...","plannedFiles":["src/auth/jwt.mjs","src/auth/jwt.test.mjs"],"acceptance":["node --check src/auth/jwt.mjs passes","npm test -- auth passes"],"timeoutMs":600000,"maxRetries":2}',
+    '  ]},{"stageId":"s2","name":"Auth routes","passRule":"all_success","tasks":[',
+    '    {"taskId":"s2_routes","prompt":"Add login/register routes using auth from s1...","plannedFiles":["src/routes/auth.mjs","src/routes/auth.test.mjs"],"acceptance":["node --check passes","npm test passes"],"timeoutMs":600000,"maxRetries":2}',
+    "  ]}]}",
+    "",
+    `## Objective`,
+    objective,
+    intakeSummary ? `\n## Intake Summary\n${intakeSummary}` : ""
+  ].filter(Boolean).join("\n")
+
+  const out = await processTurnLoop({
+    prompt: plannerPrompt,
+    mode: "plan",
+    model,
+    providerType,
+    sessionId,
+    configState,
+    baseUrl,
+    apiKeyEnv,
+    agent,
+    signal,
+    output: { write: () => {} },
+    allowQuestion: true
+  })
+
+  const parsed = parseJsonLoose(out.reply)
+  if (!parsed) {
+    return {
+      plan: defaultStagePlan(objective, defaults),
+      errors: ["planner returned unparseable response — falling back to single-stage plan"],
+      qualityScore: 0,
+      rawReply: out.reply
+    }
+  }
+  const { plan, errors, qualityScore } = validateAndNormalizeStagePlan(parsed, { objective, defaults })
+  return { plan, errors, qualityScore, rawReply: out.reply }
+}

package/src/session/longagent-scaffold.mjs

@@ -0,0 +1,100 @@
+import { processTurnLoop } from "./loop.mjs"
+import { EventBus } from "../core/events.mjs"
+import { EVENT_TYPES } from "../core/constants.mjs"
+
+function buildScaffoldPrompt(objective, stagePlan) {
+  const allFiles = new Set()
+  const taskSpecs = []
+
+  for (const stage of stagePlan.stages || []) {
+    for (const task of stage.tasks || []) {
+      for (const file of task.plannedFiles || []) {
+        allFiles.add(file)
+      }
+      taskSpecs.push({
+        taskId: task.taskId,
+        prompt: task.prompt,
+        plannedFiles: task.plannedFiles,
+        acceptance: task.acceptance
+      })
+    }
+  }
+
+  const fileList = [...allFiles].sort()
+  if (!fileList.length) return null
+
+  return [
+    "You are in SCAFFOLDING mode. Your job is to create stub files that define contracts for parallel implementation agents.",
+    "",
+    `## Objective: ${objective}`,
+    "",
+    "## Files to scaffold:",
+    ...fileList.map((f) => `- ${f}`),
+    "",
+    "## Task specifications (for context):",
+    JSON.stringify(taskSpecs, null, 2),
+    "",
+    "## Scaffolding rules:",
+    "1. Create EVERY file listed above using the `write` tool.",
+    "2. For Python files: write function/class signatures with docstrings describing inputs, outputs, and behavior. Use `pass` or `...` as body.",
+    "3. For Vue/React components: write component stubs with props/events/slots documented in comments. Include the component shell structure.",
+    "4. For TypeScript/JavaScript: write export signatures with JSDoc or TSDoc describing the interface contract.",
+    "5. For config/data files: write the expected schema structure with placeholder values and comments.",
+    "6. For test files: write test suite structure with describe/it blocks and comments describing what each test should verify.",
+    "7. Each file MUST have a header comment explaining: purpose, dependencies, interfaces it implements/exports.",
+    "8. Do NOT implement business logic. Only define the contract (signatures, types, interfaces).",
+    "9. Include import statements that reference other scaffolded files so the dependency graph is explicit.",
+    "10. When done with ALL files, say [SCAFFOLD_COMPLETE].",
+    "",
+    "Start creating all stub files now."
+  ].join("\n")
+}
+
+export async function runScaffoldPhase({
+  objective,
+  stagePlan,
+  model,
+  providerType,
+  sessionId,
+  configState,
+  baseUrl = null,
+  apiKeyEnv = null,
+  agent = null,
+  signal = null,
+  toolContext = {}
+}) {
+  const prompt = buildScaffoldPrompt(objective, stagePlan)
+  if (!prompt) {
+    return { scaffolded: false, fileCount: 0, files: [], errors: [] }
+  }
+
+  const out = await processTurnLoop({
+    prompt,
+    mode: "agent",
+    model,
+    providerType,
+    sessionId,
+    configState,
+    baseUrl,
+    apiKeyEnv,
+    agent,
+    signal,
+    allowQuestion: false,
+    toolContext
+  })
+
+  // Extract files created from tool events
+  const createdFiles = (out.toolEvents || [])
+    .filter((e) => e.name === "write" && e.status === "completed")
+    .map((e) => e.args?.path)
+    .filter(Boolean)
+
+  return {
+    scaffolded: true,
+    fileCount: createdFiles.length,
+    files: createdFiles,
+    usage: out.usage,
+    toolEvents: out.toolEvents,
+    errors: []
+  }
+}