Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 18 additions & 7 deletions backend/app/mcp_server/workflow_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,7 @@ async def get_document(key: str, kind: str, version: int | None = None) -> dict[
return {
"kind": str(doc.kind), "version": doc.version, "status": str(doc.status), "body_md": doc.body_md,
"steps": list(doc.steps) if doc.steps is not None else None,
"follow_ups": list(doc.follow_ups or []),
"decision_comment": doc.decision_comment,
"decided_by": str(doc.decided_by) if doc.decided_by else None,
}
Expand Down Expand Up @@ -302,12 +303,21 @@ async def record_tests(
return {"id": str(row.id), "passed": row.passed}

@mcp.tool()
async def submit_design(key: str, markdown: str) -> dict[str, Any]:
"""Submit your design (markdown, at most 200,000 characters) for a human's approval."""
async def submit_design(
key: str, markdown: str, follow_ups: list[dict[str, Any]] | None = None
) -> dict[str, Any]:
"""Submit your design (markdown, at most 200,000 characters) for a human's approval. `follow_ups`: only
when the person agreed to split the work into phases, up to 10 tasks for the later phases, each {title,
type (story, task or bug), description_md}. Pass the full list with every version: leaving it out
proposes none. Nothing is created until a person approves the design, and they can change the list
first."""
async with tool_session() as (db, user):
task = await _task(db, user, key, "submit_design", write=True)
doc = await _submit(db, user, task, DocKind.design, markdown, None)
return {"kind": str(doc.kind), "version": doc.version, "status": str(doc.status)}
doc = await _submit(db, user, task, DocKind.design, markdown, None, follow_ups)
return {
"kind": str(doc.kind), "version": doc.version, "status": str(doc.status),
"follow_ups": len(doc.follow_ups),
}

@mcp.tool()
async def submit_plan(key: str, markdown: str, steps: list[dict[str, Any]]) -> dict[str, Any]:
Expand Down Expand Up @@ -403,9 +413,10 @@ async def _record_target(db: AsyncSession, user: User, task: Task) -> tuple[Agen


async def _submit(
db: AsyncSession, user: User, task: Task, kind: DocKind, markdown: str, steps: list[dict] | None
db: AsyncSession, user: User, task: Task, kind: DocKind, markdown: str, steps: list[dict] | None,
follow_ups: list[dict] | None = None,
) -> WorkflowDocument:
if current_run.get() is not None:
return await documents.submit(db, await live_run(db, task), task, kind, markdown, steps)
return await documents.submit(db, await live_run(db, task), task, kind, markdown, steps, follow_ups)
wf = await engine.lock_connect_only(db, user, task)
return await documents.submit_connect_only(db, wf, task, kind, markdown, steps)
return await documents.submit_connect_only(db, wf, task, kind, markdown, steps, follow_ups)
23 changes: 18 additions & 5 deletions backend/app/workflow/documents.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
from app.tasks.schemas import TaskCreate
from app.tasks.service import create_task, first_before_column, task_changed
from app.workflow import engine
from app.workflow.follow_ups import clean_proposed, clean_reviewed, create_on_approval
from app.workflow.models import (
DocKind,
DocStatus,
Expand Down Expand Up @@ -92,7 +93,8 @@ async def _newest_mockup(db, task_id: uuid.UUID) -> uuid.UUID | None:


async def submit(
db, run: AgentRun | None, task: Task, kind: DocKind | str, body_md: str, steps: list[dict] | None = None
db, run: AgentRun | None, task: Task, kind: DocKind | str, body_md: str, steps: list[dict] | None = None,
follow_ups: list[dict] | None = None,
) -> WorkflowDocument:
"""Record the next version of the task's design or plan; older submitted versions are superseded. The caller
commits. The workflow lock is taken first, as in questions.answer."""
Expand All @@ -107,10 +109,14 @@ async def submit(
if steps is None:
raise _422("steps_required")
clean = _clean_steps(steps)
if follow_ups:
raise _422("follow_ups_forbidden")
clean_follow_ups = []
else:
if steps is not None:
raise _422("steps_forbidden")
clean = None
clean_follow_ups = clean_proposed(follow_ups)
version = (
await db.scalar(
select(func.max(WorkflowDocument.version)).where(
Expand All @@ -129,7 +135,7 @@ async def submit(
.values(status=DocStatus.superseded)
)
doc = WorkflowDocument(
task_id=task.id, kind=kind, version=version, body_md=body_md, steps=clean,
task_id=task.id, kind=kind, version=version, body_md=body_md, steps=clean, follow_ups=clean_follow_ups,
status=DocStatus.submitted, submitted_run_id=run.id if run else None,
attached_mockup_ids=await _attached_mockups(db, task.id) if kind == DocKind.design else [],
mockup_id=await _newest_mockup(db, task.id) if kind == DocKind.design else None,
Expand All @@ -141,7 +147,8 @@ async def submit(


async def submit_connect_only(
db, wf: TaskWorkflow, task: Task, kind: DocKind | str, body_md: str, steps: list[dict] | None = None
db, wf: TaskWorkflow, task: Task, kind: DocKind | str, body_md: str, steps: list[dict] | None = None,
follow_ups: list[dict] | None = None,
) -> WorkflowDocument:
"""AGT-32: a connect-only agent submits its design (Brainstorm or Design) or plan (Plan) while the workflow
runs with no open question. The stage is checked here, as `submit` does not; the workflow then waits for
Expand All @@ -151,7 +158,7 @@ async def submit_connect_only(
await engine.require_connect_only_running(db, wf)
if wf.stage not in SUBMIT_STAGES[kind]:
raise HTTPException(status.HTTP_409_CONFLICT, "wrong_stage")
doc = await submit(db, None, task, kind, body_md, steps)
doc = await submit(db, None, task, kind, body_md, steps, follow_ups)
if kind == DocKind.design:
await engine.set_stage(db, wf, task, Stage.design)
await engine.wait_for(db, wf, NEEDS_OF[kind])
Expand All @@ -160,7 +167,7 @@ async def submit_connect_only(

async def decide(
db, user: User, task: Task, kind: DocKind | str, version: int, approve: bool, comment: str | None,
images: Sequence[uuid.UUID] = (),
images: Sequence[uuid.UUID] = (), follow_ups: list[dict] | None = None,
) -> None:
"""A human approves or rejects the document (WF-6 roles). The first decision wins (409 already_decided)."""
kind = DocKind(kind)
Expand All @@ -171,6 +178,8 @@ async def decide(
raise _422("too_large")
if not approve and not comment:
raise _422("comment_required")
# checked before anything is written; a rejection or a plan ignores the list
reviewed = clean_reviewed(follow_ups) if approve and kind == DocKind.design and follow_ups is not None else None
doc = (
await db.execute(
select(WorkflowDocument)
Expand All @@ -189,6 +198,8 @@ async def decide(
raise HTTPException(status.HTTP_409_CONFLICT, "already_decided")
if wf is None or wf.status != WorkflowStatus.waiting_human or wf.needs != NEEDS_OF[kind]:
raise HTTPException(status.HTTP_409_CONFLICT, "not_waiting_for_decision")
if approve and kind == DocKind.design and doc.follow_ups and reviewed is None:
raise _422("follow_ups_required") # a page that never showed the list

doc.status = DocStatus.approved if approve else DocStatus.rejected
doc.decided_by = user.id
Expand Down Expand Up @@ -216,6 +227,8 @@ async def decide(
requested_by=user.id,
)
elif kind == DocKind.design:
if reviewed is not None:
await create_on_approval(db, user, task, doc, reviewed)
await engine.set_stage(db, wf, task, Stage.plan) # the plan session is fresh
await engine.hand_to_agent(db, wf, task, RunRole.plan, requested_by=user.id)
else:
Expand Down
197 changes: 197 additions & 0 deletions backend/app/workflow/follow_ups.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
"""Follow-up tasks a design proposes for the later phases of a split task (MC-81): checked when the agent submits
the design and when a person approves it, and created on approval. Workflow runs never create tasks themselves."""

import uuid

from fastapi import HTTPException, status
from sqlalchemy import select

from app.auth.models import User
from app.core.text import strip_nul
from app.projects.models import Project
from app.tasks.models import LinkKind, Task, TaskLink, TaskType
from app.tasks.schemas import TaskCreate, TaskUpdate
from app.tasks.service import create_task, first_before_column, record_event, task_changed, update_task
from app.workflow.models import DocKind, DocStatus, WorkflowDocument

MAX_FOLLOW_UPS = 10
MAX_TITLE = 500
MAX_DESCRIPTION = 4_000
TYPES = frozenset({TaskType.story.value, TaskType.task.value, TaskType.bug.value})


def _422(code: str) -> HTTPException:
return HTTPException(status.HTTP_422_UNPROCESSABLE_CONTENT, code)


def _entry(item, *, reviewed: bool) -> dict:
if not isinstance(item, dict):
raise _422("invalid_follow_ups")
title, kind, description = item.get("title", ""), item.get("type", "task"), item.get("description_md", "")
if not all(isinstance(v, str) for v in (title, kind, description)) or kind not in TYPES:
raise _422("invalid_follow_ups")
title, description = strip_nul(title).strip(), strip_nul(description)
entry = {"title": title, "type": kind, "description_md": description, "task_id": None}
if reviewed:
create = item.get("create")
if not isinstance(create, bool):
raise _422("invalid_follow_ups")
entry["create"] = create
if not title and (not reviewed or entry["create"]):
raise _422("invalid_follow_ups")
if len(title) > MAX_TITLE or len(description) > MAX_DESCRIPTION:
raise _422("too_large")
return entry


def _list(items) -> list:
if not isinstance(items, list) or len(items) > MAX_FOLLOW_UPS:
raise _422("invalid_follow_ups")
return items


def clean_proposed(items) -> list[dict]:
"""What the agent passed to submit_design. None (left out) proposes none."""
if items is None:
return []
return [_entry(i, reviewed=False) for i in _list(items)]


def clean_reviewed(items) -> list[dict]:
"""What the person sent with the approval: the whole list in order, each with `create`. An unticked row the
person left without a title is dropped."""
entries = [_entry(i, reviewed=True) for i in _list(items)]
return [e for e in entries if e["title"]]


def task_path(project_key: str, number: int) -> str:
return f"/projects/{project_key}/tasks/{number}"


def backlink(project_key: str, number: int, version: int) -> str:
"""The line that ends a created task's description: where it came from."""
path = task_path(project_key, number)
return (f"Follow-up of [{project_key}-{number}]({path}), from its "
f"[approved design (v{version})]({path}#document-design-v{version}).")


async def _epic_id(db, task: Task) -> uuid.UUID | None:
if task.parent_id is None:
return None
parent = await db.get(Task, task.parent_id)
return parent.id if parent is not None and parent.type == TaskType.epic else None


async def _chat(db, task: Task):
"""The chat a round belongs to, else None."""
from app.chats.models import Chat # local: the chats modules import the workflow

return await db.get(Chat, task.chat_id) if task.in_chat and task.chat_id else None


async def create_on_approval(db, user: User, task: Task, doc: WorkflowDocument, reviewed: list[dict]) -> None:
"""Create the ticked entries of the approved design, in order: unassigned, in the first before-work column,
in the task's epic, each linked to the task and recorded on it. A chat round's tasks get no epic and no link,
and point back at the chat. The approved version keeps the reviewed list, with the created tasks' ids, and the
task's description gets the scope note. Runs inside decide's transaction: a failure undoes the approval too."""
project = await db.get(Project, task.project_id)
chat = await _chat(db, task)
if chat is not None: # a round is not on the board: its tasks are plain board tasks
epic_id, tail = None, f"From chat: [{chat.title}](/chats/{chat.id})"
else:
epic_id, tail = await _epic_id(db, task), backlink(project.key, task.number, doc.version)
entries, created = [], []
for item in reviewed:
entry = {"title": item["title"], "type": item["type"], "description_md": item["description_md"],
"task_id": None}
if item["create"]:
new = await create_task(db, user, project, TaskCreate(
title=item["title"], type=TaskType(item["type"]),
description_md=f"{item['description_md'].rstrip()}\n\n{tail}".lstrip(), parent_id=epic_id,
))
await task_changed(db, new, "task.created") # live boards show it
if chat is None:
db.add(TaskLink(source_id=task.id, target_id=new.id, kind=LinkKind.relates))
await record_event(db, task, user.id, "follow_up_created", {
"key": f"{project.key}-{new.number}", "title": new.title, "task_id": str(new.id),
"type": str(new.type), "design_version": doc.version,
})
entry["task_id"] = str(new.id)
created.append(new)
entries.append(entry)
doc.follow_ups = entries # a new list: edits inside nested dicts are not tracked
if created:
await _write_scope_note(db, user, project, task, doc, created, chat)


def scope_note(phases: list[tuple[str, str]], design_link: str) -> str:
"""`phases`: (key, path) of every follow-up task, in order. This task is phase 1."""
total = len(phases) + 1
links = ", ".join(f"[{key}]({path})" for key, path in phases)
later = "Phase 2" if total == 2 else f"Phases 2–{total}" # an en dash
return f"Scope: phase 1 of {total} (per the [approved design]({design_link})). {later} → {links}."


def _other_approved(task: Task, doc: WorkflowDocument):
return (WorkflowDocument.task_id == task.id, WorkflowDocument.kind == DocKind.design,
WorkflowDocument.status == DocStatus.approved, WorkflowDocument.id != doc.id)


async def earlier(db, task: Task, doc: WorkflowDocument) -> list[Task]:
"""Follow-up tasks the task's other approved design versions created and that still exist, oldest first."""
lists = (await db.execute(select(WorkflowDocument.follow_ups).where(*_other_approved(task, doc))
.order_by(WorkflowDocument.version))).scalars()
ids = [uuid.UUID(e["task_id"]) for entries in lists for e in (entries or []) if e.get("task_id")]
if not ids:
return []
found = {t.id: t for t in (await db.execute(select(Task).where(Task.id.in_(ids)))).scalars()}
return [found[i] for i in ids if i in found]


async def entries_out(db, project_key: str, doc: WorkflowDocument) -> list[dict]:
"""The version's follow-ups for the API: whether each was created, and its key while the task still exists."""
entries = doc.follow_ups or []
ids = [uuid.UUID(e["task_id"]) for e in entries if e.get("task_id")]
numbers = dict((await db.execute(select(Task.id, Task.number).where(Task.id.in_(ids)))).all()) if ids else {}
out = []
for e in entries:
number = numbers.get(uuid.UUID(e["task_id"])) if e.get("task_id") else None
out.append({"title": e["title"], "type": e["type"], "description_md": e["description_md"],
"created": e.get("task_id") is not None,
"task_key": f"{project_key}-{number}" if number is not None else None})
return out


async def creates_in(db, task: Task, doc: WorkflowDocument) -> dict | None:
"""A submitted design: the column and epic approving it would create its follow-up tasks in."""
if doc.kind != DocKind.design or doc.status != DocStatus.submitted:
return None
project = await db.get(Project, task.project_id)
column = await first_before_column(db, project)
epic = None
if await _chat(db, task) is None and (epic_id := await _epic_id(db, task)) is not None:
parent = await db.get(Task, epic_id)
epic = {"key": f"{project.key}-{parent.number}", "title": parent.title}
return {"column": column.name, "epic": epic}


async def _write_scope_note(db, user, project, task, doc, created: list[Task], chat) -> None:
phases = [(f"{project.key}-{t.number}", task_path(project.key, t.number))
for t in [*await earlier(db, task, doc), *created]]
design_link = (f"/chats/{chat.id}" if chat is not None
else f"{task_path(project.key, task.number)}#document-design-v{doc.version}")
note = scope_note(phases, design_link)
previous = await db.scalar(
select(WorkflowDocument.scope_note)
.where(*_other_approved(task, doc), WorkflowDocument.scope_note.is_not(None))
.order_by(WorkflowDocument.version.desc()).limit(1)
)
current = task.description_md or ""
if previous and previous in current: # the note the system wrote before, unedited: replace its last copy
i = current.rindex(previous)
text = current[:i] + note + current[i + len(previous):]
else:
text = f"{current.rstrip()}\n\n{note}" if current.strip() else note
# a normal description change: field_changed is recorded and the memory update is queued
await update_task(db, user, project, task, TaskUpdate(description_md=text))
doc.scope_note = note
2 changes: 2 additions & 0 deletions backend/app/workflow/methodology_history.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,12 @@
"9b8f73e6adbc875b1b23294505ec303a8943ff7b91d7479451d6253a0ca5a393",
"00277fef22ee863a94b51f13ee72976968543c59c6334b4cbffc1b092276381e",
"b20571982b08dfd817ef39072b2de6b88d80242bafce8f506147dc0bacef10a4",
"c357f68b3c86e3e3a235d3ebd6a0e2fca21f055ff838da518671d1750491b7e1",
],
"design_revision": [
"7b6bfa9f3eb82fdf3e709413ceb6f029ae88e91372eaa0462e06e1d0872db8fe",
"d9808506b33c95dc9e61e879db98128db3d589ef06013de90f0f883ab6fcb663",
"2033bae5b41b87aadfaf76d652bcbd0bddb722cc8555466db989fb3e9874ff0a",
],
"plan": [
"ee12eca000a1c412b2ff2d7d411acc22ee451d33151daa9fadd1a3a96b1ead8a",
Expand Down
Loading
Loading