komrad

create_guide

Write a guide to the caller's own diff, which komrad keeps against a snapshot of the caller's checkout taken now.

writesnot idempotentMCP toolGuide

A guide walks a reader through how the change works in a few guide sections. Each guide section has a title, a narrative, and the ranges of lines the narrative talks about. A range can carry a comment. Line numbers count in the diff from the snapshot's base_sha to its sha, which the response returns.

Calling it#

curl -X POST http://127.0.0.1:8787/komrad.guide.v1.GuideService/CreateGuide \
  -H 'Content-Type: application/json' \
  -d '{}'

Request#

CreateGuideRequest#

FieldTypeDescription
sectionsGuideSection[]

at most 12 items

The guide's sections, in the order a reader meets them.

Response#

CreateGuideResponse#

FieldTypeDescription
guideGuide

The guide as komrad keeps it, with the snapshot it explains.

Types#

GuideSection#

GuideSection is one part of a guide: a title, a narrative, and the ranges of lines the narrative talks about.

FieldTypeDescription
titlestring*

at most 200 characters

must not contain control characters

The guide section's title, a short phrase that names what the guide section shows.

narrativestring

at most 4000 characters

The guide section's narrative, markdown that explains in plain sentences how the code in its ranges works, with fenced code blocks drawn highlighted. Empty for a guide section that only points at code.

rangesGuideRange[]

at most 10 items

The ranges of the diff the guide section talks about. Empty for a guide section that only explains.

Guide#

Guide is a writer's explanation of its diff as it stood at one snapshot, made of guide sections. Guide sections can share lines, and a guide can leave lines out.

FieldTypeDescription
iduuid*

The guide's id.

task_iduuid*

The id of the task whose diff the guide explains.

snapshotReviewSnapshot

The snapshot the guide explains. The guide's line numbers count in the diff from the snapshot's base_sha to its sha.

author_agent_iduuid

The id of the writer that wrote the guide. Unset once that agent was deleted.

created_attimestamp

When the guide was created.

sectionsGuideSection[]

The guide's sections, in the order a reader meets them.

GuideRange#

GuideRange is a range of lines in one file of the diff a guide explains.

FieldTypeDescription
file_pathstring

must be a relative path without a leading / or ~ or a .. segment

The file's path, relative to the repository root.

old_startint32

at least 0

The first line of the range on the old side of the diff, counting from one. Zero for a range only on the new side.

old_endint32

at least 0

The last line of the range on the old side of the diff.

new_startint32

at least 0

The first line of the range on the new side of the diff, counting from one. Zero for a range only on the old side.

new_endint32

at least 0

The last line of the range on the new side of the diff.

commentstring

at most 2000 characters

What the writer says about the range's lines. Empty for a range with nothing to point out.

ReviewSnapshot#

ReviewSnapshot is a snapshot of a task's worktree, saved as a commit, that a review is written against. A snapshot never changes.

FieldTypeDescription
iduuid*

The snapshot's id.

task_iduuid*

The id of the task the snapshot was taken of.

ordinalint32

The snapshot's number within its task, counting from one.

base_shastring

The commit on the base branch that the task's branch started from when the snapshot was taken.

shastring

The commit holding the whole worktree, tracked and untracked files alike.

created_attimestamp

When the snapshot was taken.