@jitsusama/agentic-harness.core 0.1.0

package/dist/review/draft/handle.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A draft you can hold.
+ *
+ * The pure layer underneath is the composable one: plain state
+ * and functions that return new state. This is the ergonomic
+ * one, for the common case of a person working through a review
+ * over an afternoon. It persists after every change, so nothing
+ * is lost to a crash, and it prunes itself after publishing, so
+ * a retry sends what failed and not what already landed.
+ */
+import type { Anchor } from "../anchor.js";
+import type { ReviewTarget } from "../change.js";
+import type { Message, Reaction, Thread, Verdict } from "../conversation.js";
+import type { ReviewProvider } from "../provider.js";
+import type { PlanContext, PublishPlan } from "./plan.js";
+import type { PublishOutcome } from "./publish.js";
+import type { RenderOptions, ReviewDocument } from "./render.js";
+import { type DraftState } from "./state.js";
+import type { DraftStore } from "./store.js";
+/** What a draft handle needs to do its job. */
+export interface DraftDeps {
+    store: DraftStore;
+}
+/** A live draft, persisted as it changes. */
+export interface ReviewDraft {
+    readonly id: string;
+    /** The draft as it stands. */
+    readonly state: DraftState;
+    /** Add an anchored remark. Returns its item id. */
+    addFinding(finding: {
+        anchor: Anchor;
+        body: string;
+    }): Promise<string>;
+    /** Reply into an existing thread. Returns its item id. */
+    replyTo(thread: Thread, body: string): Promise<string>;
+    resolveThread(thread: Thread): Promise<string>;
+    /** Queue reopening a thread that is currently resolved. */
+    reopenThread(thread: Thread): Promise<string>;
+    react(subject: Message, reaction: Reaction): Promise<string>;
+    setVerdict(verdict: Verdict, summary?: string): Promise<void>;
+    remove(itemId: string): Promise<void>;
+    plan(context: PlanContext): PublishPlan;
+    /** Publish, then keep only what did not land. */
+    publish(plan: PublishPlan, provider: ReviewProvider): Promise<PublishOutcome>;
+    render(options?: RenderOptions): ReviewDocument;
+}
+/**
+ * Open the draft for a target, resuming the one already in
+ * flight when there is one. Resuming rather than starting
+ * afresh is the behaviour a person expects: coming back to a
+ * review should find the review, not a blank page beside it.
+ */
+export declare function openDraft(target: ReviewTarget, deps: DraftDeps): Promise<ReviewDraft>;
+/** Pick a draft back up by id. */
+export declare function resumeDraft(id: string, deps: DraftDeps): Promise<ReviewDraft | undefined>;

package/dist/review/draft/handle.js

@@ -0,0 +1,110 @@
+/**
+ * A draft you can hold.
+ *
+ * The pure layer underneath is the composable one: plain state
+ * and functions that return new state. This is the ergonomic
+ * one, for the common case of a person working through a review
+ * over an afternoon. It persists after every change, so nothing
+ * is lost to a crash, and it prunes itself after publishing, so
+ * a retry sends what failed and not what already landed.
+ */
+import { compilePlan } from "./plan.js";
+import { publishPlan } from "./publish.js";
+import { renderDraft } from "./render.js";
+import { addFinding, addReaction, addReply, addResolution, addUnresolution, emptyDraft, removeItem, setVerdict, } from "./state.js";
+/**
+ * A short random tail, so two drafts about the same change
+ * cannot collide on their file name.
+ */
+function tail() {
+    return Math.random().toString(36).slice(2, 6);
+}
+/**
+ * A legible id. It names what the draft is about, because a
+ * person looking at the store should be able to tell which
+ * draft is which without opening them.
+ */
+function newDraftId(target) {
+    const subject = target.kind === "proposal"
+        ? target.change.id
+        : target.kind === "range"
+            ? target.head
+            : (target.refs.at(-1) ?? "stack");
+    const slug = subject.replace(/[^A-Za-z0-9._-]/g, "-");
+    return `${target.kind}-${slug}-${tail()}`;
+}
+/** Wrap a state in a handle that persists every change. */
+function handleFor(initial, deps) {
+    let state = initial;
+    async function commit(next) {
+        state = next;
+        await deps.store.save(state);
+    }
+    /** Apply an operation that appends one item, and name it. */
+    async function append(apply) {
+        await commit(apply(state));
+        const added = state.items.at(-1);
+        return added ? added.id : "";
+    }
+    return {
+        get id() {
+            return state.id;
+        },
+        get state() {
+            return state;
+        },
+        addFinding: (finding) => append((current) => addFinding(current, finding)),
+        replyTo: (thread, body) => append((current) => addReply(current, thread, body)),
+        resolveThread: (thread) => append((current) => addResolution(current, thread)),
+        reopenThread: (thread) => append((current) => addUnresolution(current, thread)),
+        react: (subject, reaction) => append((current) => addReaction(current, subject, reaction)),
+        async setVerdict(verdict, summary) {
+            await commit(setVerdict(state, verdict, summary));
+        },
+        async remove(itemId) {
+            await commit(removeItem(state, itemId));
+        },
+        plan: (context) => compilePlan(state, context),
+        async publish(plan, provider) {
+            const outcome = await publishPlan(plan, provider);
+            let next = state;
+            for (const entry of outcome.outcomes) {
+                if (!entry.ok)
+                    continue;
+                for (const itemId of entry.itemIds) {
+                    next = removeItem(next, itemId);
+                }
+                // The verdict rode on the review, so it has landed too.
+                const carriedVerdict = entry.op.kind === "review" || entry.op.kind === "comment";
+                if (carriedVerdict) {
+                    next = { ...next, verdict: undefined, summary: undefined };
+                }
+            }
+            await commit(next);
+            return outcome;
+        },
+        render: (options) => renderDraft(state, options),
+    };
+}
+/**
+ * Open the draft for a target, resuming the one already in
+ * flight when there is one. Resuming rather than starting
+ * afresh is the behaviour a person expects: coming back to a
+ * review should find the review, not a blank page beside it.
+ */
+export async function openDraft(target, deps) {
+    const [existing] = await deps.store.forTarget(target);
+    if (existing) {
+        const state = await deps.store.load(existing.id);
+        if (state)
+            return handleFor(state, deps);
+    }
+    const fresh = emptyDraft(newDraftId(target), target);
+    await deps.store.save(fresh);
+    return handleFor(fresh, deps);
+}
+/** Pick a draft back up by id. */
+export async function resumeDraft(id, deps) {
+    const state = await deps.store.load(id);
+    return state ? handleFor(state, deps) : undefined;
+}

package/dist/review/draft/plan.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Compiling a draft into what will actually be sent.
+ *
+ * This is where the asymmetries between backends are paid
+ * for, once, in the open. A draft says what the reviewer
+ * means; a provider's capabilities say what it will accept;
+ * the plan says what is therefore going to happen, including
+ * what will land somewhere other than where it was aimed and
+ * what will not land at all.
+ *
+ * Nothing here talks to a network. A plan can be shown to a
+ * person before a single request is made, which is the whole
+ * point: degradation announced up front is a decision, and
+ * degradation discovered from a rejected request is a
+ * surprise.
+ */
+import type { Capabilities } from "../capabilities.js";
+import type { ChangeState, ReviewTarget } from "../change.js";
+import type { AnchoredComment, Message, Reaction, Thread, Verdict } from "../conversation.js";
+import type { DiffModel } from "../diff.js";
+import type { DraftState } from "./state.js";
+/** What the compiler needs to know beyond the draft itself. */
+export interface PlanContext {
+    capabilities: Capabilities;
+    /**
+     * Diff to validate anchors against. Without one, anchors
+     * are taken on trust: better to let the backend judge than
+     * to invent a refusal.
+     */
+    diff?: DiffModel;
+    /** True when the reviewer authored the change. */
+    ownChange?: boolean;
+    /** Where the change stands, when known. */
+    changeState?: ChangeState;
+}
+/** One request that will be made. */
+export type PlannedOp = {
+    kind: "review";
+    verdict: Verdict;
+    body: string;
+    comments: AnchoredComment[];
+    itemIds: string[];
+} | {
+    kind: "comment";
+    body: string;
+    itemIds: string[];
+} | {
+    /**
+     * One anchored remark, posted on its own.
+     *
+     * For a remark a batch review will not carry. Both backends
+     * surveyed reject a whole review that contains a file-level
+     * comment while accepting the same comment posted alone, so this
+     * is what keeps one such remark from costing every other remark
+     * beside it.
+     */
+    kind: "commentOn";
+    comment: AnchoredComment;
+    itemIds: string[];
+} | {
+    kind: "reply";
+    thread: Thread;
+    body: string;
+    itemIds: string[];
+} | {
+    kind: "resolve";
+    thread: Thread;
+    itemIds: string[];
+} | {
+    kind: "unresolve";
+    thread: Thread;
+    itemIds: string[];
+} | {
+    kind: "react";
+    subject: Message;
+    reaction: Reaction;
+    itemIds: string[];
+};
+/** An item that will land, but not the way it was asked for. */
+export interface Degradation {
+    itemId: string;
+    /** What was asked for. */
+    from: string;
+    /** What will happen instead. */
+    to: string;
+    reason: string;
+}
+/** Something that will not happen, and why. */
+export interface PlanRefusal {
+    /** Item it came from, absent when it is about the verdict. */
+    itemId?: string;
+    subject: string;
+    reason: string;
+}
+/** Everything that will happen when this draft is published. */
+export interface PublishPlan {
+    target: ReviewTarget;
+    ops: PlannedOp[];
+    degraded: Degradation[];
+    refused: PlanRefusal[];
+}
+/**
+ * Compile a draft into an explicit plan.
+ *
+ * Findings and the verdict become one review where the
+ * provider batches anchored comments, since that is one
+ * notification rather than a dozen. Replies, resolutions and
+ * reactions are their own requests because no backend accepts
+ * them inside a review. The review goes first, so its
+ * comments exist before anything refers to them.
+ */
+export declare function compilePlan(state: DraftState, context: PlanContext): PublishPlan;

package/dist/review/draft/plan.js

@@ -0,0 +1,343 @@
+/**
+ * Compiling a draft into what will actually be sent.
+ *
+ * This is where the asymmetries between backends are paid
+ * for, once, in the open. A draft says what the reviewer
+ * means; a provider's capabilities say what it will accept;
+ * the plan says what is therefore going to happen, including
+ * what will land somewhere other than where it was aimed and
+ * what will not land at all.
+ *
+ * Nothing here talks to a network. A plan can be shown to a
+ * person before a single request is made, which is the whole
+ * point: degradation announced up front is a decision, and
+ * degradation discovered from a rejected request is a
+ * surprise.
+ */
+import { anchorable, describeAnchor as sharedDescribeAnchor, } from "../anchor.js";
+import { bullet } from "./continuation.js";
+/** A verdict taking no position, which is the safe default. */
+const NEUTRAL_VERDICT = "comment";
+/** Where a finding was aimed, for a reader of the plan. */
+function describeAnchor(anchor) {
+    if (anchor.subject !== "line")
+        return sharedDescribeAnchor(anchor);
+    return `${sharedDescribeAnchor(anchor)} (${anchor.blob})`;
+}
+/** A finding rendered into prose, for when it cannot anchor. */
+function inlineFinding(finding) {
+    return bullet(describeAnchor(finding.anchor), finding.body);
+}
+/**
+ * Assemble the review body: the reviewer's summary, then any
+ * findings that could not be anchored, so nothing the person
+ * wrote is silently dropped.
+ */
+function reviewBody(summary, spilled) {
+    const parts = [];
+    if (summary)
+        parts.push(summary);
+    if (spilled.length > 0) {
+        parts.push("Remarks that could not be attached to a line:", spilled.map(inlineFinding).join("\n"));
+    }
+    return parts.join("\n\n");
+}
+/** Narrow a multi-line anchor to its last line. */
+function collapseRange(anchor) {
+    if (anchor.subject !== "line")
+        return anchor;
+    const { startLine, ...rest } = anchor;
+    void startLine;
+    return rest;
+}
+/**
+ * Decide how one finding will travel: as an anchored comment,
+ * as a narrowed anchored comment, or as prose in the body.
+ */
+function sortFinding(finding, conversation, diff) {
+    const spillTo = "the review body";
+    if (finding.anchor.subject === "file") {
+        if (conversation.fileLevelComments === "never") {
+            return {
+                spill: finding,
+                degradation: {
+                    itemId: finding.id,
+                    from: "a file-level comment",
+                    to: spillTo,
+                    reason: "this provider does not anchor comments to a whole file",
+                },
+            };
+        }
+        if (conversation.fileLevelComments === "standalone") {
+            // Out of the batch and onto its own post, which is where both
+            // backends surveyed will take it. In the batch it does not merely
+            // fail, it takes the whole review down with it, so this is not a
+            // preference: a review carrying one file-level remark was rejected
+            // entirely, and every other remark in it was lost to a retry.
+            //
+            // No degradation is recorded, because nothing about the remark
+            // changed. It lands where it was aimed, said by the same person
+            // about the same file; only the request carrying it is different,
+            // and that is the provider's business rather than the author's.
+            return { alone: { anchor: finding.anchor, body: finding.body } };
+        }
+    }
+    if (diff) {
+        const check = anchorable(diff, finding.anchor);
+        if (!check.anchored) {
+            return {
+                spill: finding,
+                degradation: {
+                    itemId: finding.id,
+                    from: `an anchor at ${describeAnchor(finding.anchor)}`,
+                    to: spillTo,
+                    reason: `the anchor does not land on this diff (${check.reason})`,
+                },
+            };
+        }
+    }
+    const ranged = finding.anchor.subject === "line" &&
+        finding.anchor.startLine !== undefined &&
+        finding.anchor.startLine !== finding.anchor.line;
+    if (ranged && !conversation.multiLineRanges) {
+        return {
+            comment: { anchor: collapseRange(finding.anchor), body: finding.body },
+            degradation: {
+                itemId: finding.id,
+                from: `a range at ${describeAnchor(finding.anchor)}`,
+                to: "a single-line comment on its last line",
+                reason: "this provider does not accept multi-line ranges",
+            },
+        };
+    }
+    return { comment: { anchor: finding.anchor, body: finding.body } };
+}
+/** Whether a verdict is allowed, and why not when it is not. */
+function verdictRefusal(verdict, summary, conversation, context) {
+    if (conversation.bodyRequiredFor?.includes(verdict) && !summary) {
+        return `this provider requires a summary for a ${verdict} verdict`;
+    }
+    if (context.ownChange &&
+        conversation.selfVerdicts &&
+        !conversation.selfVerdicts.includes(verdict)) {
+        return `this provider does not accept a ${verdict} verdict on your own change`;
+    }
+    if (context.changeState === "merged" &&
+        conversation.verdictsAfterMerge &&
+        !conversation.verdictsAfterMerge.includes(verdict)) {
+        return `this provider does not accept a ${verdict} verdict once merged`;
+    }
+    return undefined;
+}
+/** Nothing can be published: say so for every part of the draft. */
+function refuseEverything(state) {
+    const reason = "this target has no conversation to publish to; render the " +
+        "review as a document instead";
+    const refused = state.items.map((item) => ({
+        itemId: item.id,
+        subject: item.kind,
+        reason,
+    }));
+    if (state.verdict)
+        refused.push({ subject: "verdict", reason });
+    return { ops: [], degraded: [], refused };
+}
+/**
+ * Plan the review itself: the verdict, the summary, and every
+ * finding, each either anchored or folded into the body.
+ */
+function planReview(state, conversation, context) {
+    const degraded = [];
+    const refused = [];
+    const comments = [];
+    /** Remarks the batch will not carry, each posted on its own. */
+    const alone = [];
+    const spilled = [];
+    const itemIds = [];
+    const findings = state.items.filter((item) => item.kind === "finding");
+    for (const finding of findings) {
+        itemIds.push(finding.id);
+        if (!conversation.anchoredBatchReview) {
+            spilled.push(finding);
+            degraded.push({
+                itemId: finding.id,
+                from: "an anchored comment",
+                to: "prose in a top-level message",
+                reason: "this provider cannot post anchored comments in a review",
+            });
+            continue;
+        }
+        const sorted = sortFinding(finding, conversation, context.diff);
+        if (sorted.degradation)
+            degraded.push(sorted.degradation);
+        if (sorted.spill)
+            spilled.push(sorted.spill);
+        if (sorted.alone) {
+            alone.push({ comment: sorted.alone, itemId: finding.id });
+            continue;
+        }
+        if (!sorted.comment)
+            continue;
+        const cap = conversation.maxBatchComments;
+        if (cap !== undefined && comments.length >= cap) {
+            spilled.push(finding);
+            degraded.push({
+                itemId: finding.id,
+                from: "an anchored comment",
+                to: "the review body",
+                reason: `this provider caps a batch at ${cap} comments`,
+            });
+            continue;
+        }
+        comments.push(sorted.comment);
+    }
+    let verdict = state.verdict;
+    if (verdict) {
+        const reason = verdictRefusal(verdict, state.summary, conversation, context);
+        if (reason) {
+            refused.push({ subject: `${verdict} verdict`, reason });
+            verdict = undefined;
+        }
+    }
+    // Each on its own, so one that the backend refuses costs only itself.
+    const standalone = alone.map(({ comment, itemId }) => ({
+        kind: "commentOn",
+        comment,
+        itemIds: [itemId],
+    }));
+    if (findings.length === 0 && verdict === undefined) {
+        return { ops: standalone, degraded, refused };
+    }
+    // Nothing left for the review itself is possible now that a remark can
+    // travel on its own: a draft holding one file-level finding and no
+    // verdict has its whole content in the standalone ops, and an empty
+    // review posted beside them would be a message saying nothing.
+    const onlyStandalone = comments.length === 0 &&
+        spilled.length === 0 &&
+        verdict === undefined &&
+        state.summary === undefined &&
+        standalone.length > 0;
+    if (onlyStandalone)
+        return { ops: standalone, degraded, refused };
+    const body = reviewBody(state.summary, spilled);
+    const op = conversation.anchoredBatchReview
+        ? {
+            kind: "review",
+            verdict: verdict ?? NEUTRAL_VERDICT,
+            body,
+            comments,
+            itemIds,
+        }
+        : { kind: "comment", body, itemIds };
+    return { ops: [op, ...standalone], degraded, refused };
+}
+/**
+ * Plan the parts no backend accepts inside a review: replies
+ * into existing threads, resolutions and reactions.
+ */
+function planThreadWork(state, conversation) {
+    const ops = [];
+    const refused = [];
+    for (const item of state.items) {
+        if (item.kind === "reply") {
+            // A thread with no anchor is a top-level message the provider hung off
+            // the change, and not every backend lets a reply thread onto one. The
+            // capability saying so was declared by every provider and read by none,
+            // so this was planned as landing and rejected at submit: the worst
+            // moment to find out, and the exact case the capability exists for.
+            if (item.thread.anchor === undefined && !conversation.topLevelThreading) {
+                refused.push({
+                    itemId: item.id,
+                    subject: "reply",
+                    reason: "this provider cannot thread a reply onto a top-level message; " +
+                        "say it as a comment on the change instead",
+                });
+            }
+            else {
+                ops.push({
+                    kind: "reply",
+                    thread: item.thread,
+                    body: item.body,
+                    itemIds: [item.id],
+                });
+            }
+        }
+        else if (item.kind === "resolution") {
+            if (item.thread.resolved) {
+                refused.push({
+                    itemId: item.id,
+                    subject: "resolution",
+                    reason: "that thread is already resolved",
+                });
+            }
+            else {
+                ops.push({
+                    kind: "resolve",
+                    thread: item.thread,
+                    itemIds: [item.id],
+                });
+            }
+        }
+        else if (item.kind === "unresolution") {
+            if (!item.thread.resolved) {
+                refused.push({
+                    itemId: item.id,
+                    subject: "unresolution",
+                    reason: "that thread is not resolved",
+                });
+            }
+            else {
+                ops.push({
+                    kind: "unresolve",
+                    thread: item.thread,
+                    itemIds: [item.id],
+                });
+            }
+        }
+        else if (item.kind === "reaction") {
+            if (conversation.reactions.includes(item.reaction)) {
+                ops.push({
+                    kind: "react",
+                    subject: item.subject,
+                    reaction: item.reaction,
+                    itemIds: [item.id],
+                });
+            }
+            else {
+                refused.push({
+                    itemId: item.id,
+                    subject: "reaction",
+                    reason: conversation.reactions.length === 0
+                        ? "this provider does not support reactions"
+                        : `this provider does not accept the ${item.reaction} reaction`,
+                });
+            }
+        }
+    }
+    return { ops, degraded: [], refused };
+}
+/**
+ * Compile a draft into an explicit plan.
+ *
+ * Findings and the verdict become one review where the
+ * provider batches anchored comments, since that is one
+ * notification rather than a dozen. Replies, resolutions and
+ * reactions are their own requests because no backend accepts
+ * them inside a review. The review goes first, so its
+ * comments exist before anything refers to them.
+ */
+export function compilePlan(state, context) {
+    const conversation = context.capabilities.conversation;
+    const parts = conversation
+        ? [
+            planReview(state, conversation, context),
+            planThreadWork(state, conversation),
+        ]
+        : [refuseEverything(state)];
+    return {
+        target: state.target,
+        ops: parts.flatMap((part) => part.ops),
+        degraded: parts.flatMap((part) => part.degraded),
+        refused: parts.flatMap((part) => part.refused),
+    };
+}

package/dist/review/draft/publish.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Running a plan, honestly.
+ *
+ * Publishing a review is several requests, and the interesting
+ * case is the one where some of them work. A posted review
+ * with one failed reply is not a failure to report as "could
+ * not publish", because the review is now on the change and
+ * saying otherwise would have someone post it twice. So every
+ * operation reports its own outcome, execution continues past
+ * a failure, and the caller learns exactly which items landed.
+ */
+import type { Posted } from "../conversation.js";
+import type { ReviewProvider } from "../provider.js";
+import type { PlannedOp, PublishPlan } from "./plan.js";
+/** What became of one planned operation. */
+export interface OpOutcome {
+    op: PlannedOp;
+    ok: boolean;
+    /** Items the operation carried, whether it landed or not. */
+    itemIds: string[];
+    posted?: Posted;
+    error?: string;
+}
+/** What became of the whole plan. */
+export interface PublishOutcome {
+    /** True only when every operation landed. */
+    ok: boolean;
+    outcomes: OpOutcome[];
+}
+/**
+ * Run a compiled plan against a provider.
+ *
+ * Operations run in the order the plan puts them and a
+ * failure does not stop the ones after it, because the
+ * alternative is a review posted with half its replies
+ * missing and no record of which half.
+ */
+export declare function publishPlan(plan: PublishPlan, provider: ReviewProvider): Promise<PublishOutcome>;