@wardby/cli 0.5.3 → 0.7.0

package/dist/providers/llm/openai.d.ts

@@ -27,7 +27,7 @@
  *   apply.
  */
 import OpenAI from "openai";
-import type { LlmMessage, LlmRequest, LlmStreamEvent, LlmToolDef } from "./types.js";
+import type { LlmMessage, LlmRequest, LlmStreamEvent, LlmStreamHooks, LlmToolDef } from "./types.js";
 import { type CatalogLookup } from "./catalog-lookup.js";
 import type { CatalogEntry } from "./catalog-types.js";
 import type { CatalogLlmAdapter } from "./routing.js";
@@ -44,7 +44,7 @@ export declare class OpenAiLlmProvider implements CatalogLlmAdapter {
      */
     constructor(apiKey?: string, client?: OpenAI, lookup?: CatalogLookup);
     withEntry(entry: CatalogEntry): OpenAiLlmProvider;
-    stream(req: LlmRequest, signal?: AbortSignal): AsyncIterable<LlmStreamEvent>;
+    stream(req: LlmRequest, signal?: AbortSignal, hooks?: LlmStreamHooks): AsyncIterable<LlmStreamEvent>;
     /**
      * OpenAI reports both `cached_tokens` and `cache_write_tokens` as subsets
      * of `input_tokens`. wardby's LlmUsage convention (claude-messages.ts,

package/dist/providers/llm/openai.js

@@ -27,6 +27,7 @@
  *   apply.
  */
 import OpenAI from "openai";
+import { simulatorModelClientOptions } from "../../config/test-simulators.js";
 import { encode as encodeCl100kBase } from "gpt-tokenizer/encoding/cl100k_base";
 import { encode as encodeO200kBase } from "gpt-tokenizer/encoding/o200k_base";
 import { computeCost } from "./pricing-core.js";
@@ -133,12 +134,14 @@ export class OpenAiLlmProvider {
         if (!apiKey) {
             throw new Error("OPENAI_API_KEY is not set — required by the OpenAI LlmProvider adapter.");
         }
-        this.client = new OpenAI({ apiKey });
+        // WARDBY_TEST_SIMULATORS (test only): the scripted model, with a placeholder key the
+        // credential-free fetch drops; the real key never goes there.
+        this.client = new OpenAI(simulatorModelClientOptions("openai") ?? { apiKey });
     }
     withEntry(entry) {
         return new OpenAiLlmProvider("", this.client, pinnedLookup(entry));
     }
-    async *stream(req, signal) {
+    async *stream(req, signal, hooks) {
         const entry = this.lookup(req.model);
         // Effort is sent only at a level the catalog says the model accepts and
         // dropped otherwise (the LlmRequest.effort contract). Temperature only
@@ -157,6 +160,7 @@ export class OpenAiLlmProvider {
             ...(sendTemperature ? { temperature: req.temperature } : {}),
         };
         const stream = await this.client.responses.create(params, { signal });
+        hooks?.onResponseStarted?.();
         let sawToolCall = false;
         for await (const event of stream) {
             switch (event.type) {

package/dist/providers/llm/routing.d.ts

@@ -1,6 +1,6 @@
 import type { ModelCatalog } from "./catalog.js";
 import { type CatalogEntry, type ModelProvider, type ResolvedCatalogEntry } from "./catalog-types.js";
-import type { LlmEffort, LlmMessage, LlmProvider, LlmRequest, LlmStreamEvent, LlmToolDef } from "./types.js";
+import type { LlmEffort, LlmMessage, LlmProvider, LlmRequest, LlmStreamEvent, LlmStreamHooks, LlmToolDef } from "./types.js";
 /** Effort levels `model` accepts, from the current catalog; no credentials needed (config-time validation). */
 export declare function modelSupportedEfforts(model: string): readonly LlmEffort[];
 export declare function modelAcceptsEffort(model: string, effort: LlmEffort): boolean;
@@ -24,7 +24,7 @@ export declare class RoutingLlmProvider implements LlmProvider {
     /** A provider bound to one run's stored entry: prices and shapes requests from it, never the live catalog. */
     forRun(entry: CatalogEntry): LlmProvider;
     private resolve;
-    stream(req: LlmRequest, signal?: AbortSignal): AsyncIterable<LlmStreamEvent>;
+    stream(req: LlmRequest, signal?: AbortSignal, hooks?: LlmStreamHooks): AsyncIterable<LlmStreamEvent>;
     countTokens(model: string, messages: LlmMessage[], tools?: LlmToolDef[]): Promise<number>;
     priceUsd(model: string, usage: {
         inputTokens: number;

package/dist/providers/llm/routing.js

@@ -54,8 +54,8 @@ export class RoutingLlmProvider {
     resolve(model) {
         return this.byProvider.get(this.entryFor(model).provider);
     }
-    stream(req, signal) {
-        return this.resolve(req.model).stream(req, signal);
+    stream(req, signal, hooks) {
+        return this.resolve(req.model).stream(req, signal, hooks);
     }
     countTokens(model, messages, tools) {
         return this.resolve(model).countTokens(model, messages, tools);

package/dist/providers/llm/types.d.ts

@@ -68,7 +68,9 @@ export interface LlmUsage {
 export type LlmStreamEvent = {
     type: "text";
     delta: string;
-} | {
+}
+/** `id` must be unique within a run, not only within a turn: a delegation keys its child run on it. */
+ | {
     type: "tool_call";
     id: string;
     name: string;
@@ -78,8 +80,16 @@ export type LlmStreamEvent = {
     stopReason: string;
     usage: LlmUsage;
 };
+/** Observers of a stream's progress that its events do not show. */
+export interface LlmStreamHooks {
+    /**
+     * Called once the provider's response has started. From then on the provider
+     * may bill output (thinking or reasoning included) before any event is yielded.
+     */
+    onResponseStarted?: () => void;
+}
 export interface LlmProvider {
-    stream(req: LlmRequest, signal?: AbortSignal): AsyncIterable<LlmStreamEvent>;
+    stream(req: LlmRequest, signal?: AbortSignal, hooks?: LlmStreamHooks): AsyncIterable<LlmStreamEvent>;
     /**
      * Pre-flight token count for budget enforcement. `tools`, when passed,
      * must be counted too — a provider bills the serialized tool schemas as

package/dist/providers/review-host/github-events.d.ts

@@ -6,8 +6,16 @@ type Json = Record<string, unknown>;
  * counts: anyone can write the marker into their own PR's description.
  */
 export declare function appMarkerRunId(pr: Json | null, slug: string): string | undefined;
+/** Why a mention was dropped before routing; never carries the body. */
+export interface DroppedMention {
+    eventName: string;
+    repository: string;
+    association: string;
+    reason: "author_association" | "not_a_user";
+}
+/** `onDropped` hears about a mention the author pre-filter dropped, so the caller can log it. */
 export declare function normalizeGitHubEvent(eventName: string, payload: unknown, app: {
     id: number;
     slug: string;
-}): HostEvent | null;
+}, onDropped?: (dropped: DroppedMention) => void): HostEvent | null;
 export {};

package/dist/providers/review-host/github-events.js

@@ -4,8 +4,14 @@
  */
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { normalizeGitHubRepository } from "../../coding/protocol.js";
+import { withoutMarkdownCode } from "../../core/markdown-code.js";
 const PR_ACTIONS = new Set(["opened", "synchronize", "reopened", "ready_for_review"]);
-const TRUSTED_ASSOCIATIONS = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
+/**
+ * GitHub labels an organization member whose membership is private CONTRIBUTOR
+ * or NONE, so both pass; first-time authors and mannequins are drive-by
+ * accounts that cannot have access to a repository they never committed to.
+ */
+const TRUSTED_ASSOCIATIONS = new Set(["OWNER", "MEMBER", "COLLABORATOR", "CONTRIBUTOR", "NONE"]);
 const SAFE_SHA = /^[0-9a-f]{40}$/;
 // GitHub's push payload includes at most 2048 commits.
 const PUSH_MAX_COMMITS = 2048;
@@ -37,9 +43,10 @@ function repositoryOf(payload) {
         return null;
     }
 }
+/** A mention of the App outside code: a mention quoted in code documents it, not requests a run. */
 function mentions(body, slug) {
     const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return new RegExp(`(^|[^\\w@.-])@${escaped}(?![\\w-])`, "i").test(body);
+    return new RegExp(`(^|[^\\w@.-])@${escaped}(?![\\w-])`, "i").test(withoutMarkdownCode(body));
 }
 const text = (value) => (typeof value === "string" ? value : "");
 function subjectOf(item) {
@@ -73,20 +80,27 @@ function priorRunIdOf(pr, slug) {
  * any org member, COLLABORATOR includes read and triage). The real gate is the
  * author's live repository permission, checked by id in core/host-events.ts.
  */
-function trustedHuman(association, user) {
-    return (typeof association === "string" &&
-        TRUSTED_ASSOCIATIONS.has(association) &&
-        user?.type === "User" &&
-        typeof user.login === "string" &&
-        int(user.id) !== null);
+function trustedHuman(association, user, drop) {
+    const label = typeof association === "string" ? association : "missing";
+    if (typeof association !== "string" || !TRUSTED_ASSOCIATIONS.has(association)) {
+        drop("author_association", label);
+        return false;
+    }
+    if (user?.type !== "User" || typeof user.login !== "string" || int(user.id) === null) {
+        drop("not_a_user", label);
+        return false;
+    }
+    return true;
 }
-export function normalizeGitHubEvent(eventName, payload, app) {
+/** `onDropped` hears about a mention the author pre-filter dropped, so the caller can log it. */
+export function normalizeGitHubEvent(eventName, payload, app, onDropped) {
     const p = obj(payload);
     if (!p)
         return null;
     const repository = repositoryOf(p);
     if (!repository)
         return null;
+    const drop = (reason, association) => onDropped?.({ eventName, repository, association, reason });
     if (eventName === "push") {
         const defaultBranch = obj(p.repository)?.default_branch;
         const { before, after } = p;
@@ -181,10 +195,10 @@ export function normalizeGitHubEvent(eventName, payload, app) {
             return null;
         const body = text(issue?.body);
         const user = obj(issue?.user);
-        if (!trustedHuman(issue?.author_association, user))
-            return null;
         if (!mentions(title, app.slug) && !mentions(body, app.slug))
             return null;
+        if (!trustedHuman(issue?.author_association, user, drop))
+            return null;
         if (p.action === "edited") {
             // Only the author's own edit, and only one that newly adds the mention — not every later edit.
             const sender = obj(p.sender);
@@ -209,6 +223,10 @@ export function normalizeGitHubEvent(eventName, payload, app) {
             body,
             author: user.login,
             authorId: String(user.id),
+            authorAssociation: String(issue?.author_association),
+            ...(typeof obj(p.repository)?.private === "boolean"
+                ? { repositoryPrivate: obj(p.repository)?.private }
+                : {}),
             subject: { title, body },
         };
     }
@@ -221,7 +239,7 @@ export function normalizeGitHubEvent(eventName, payload, app) {
         const commentId = int(comment?.id);
         if (typeof body !== "string" || !commentId || !mentions(body, app.slug))
             return null;
-        if (!trustedHuman(comment?.author_association, user))
+        if (!trustedHuman(comment?.author_association, user, drop))
             return null;
         const isInline = eventName === "pull_request_review_comment";
         const parent = obj(isInline ? p.pull_request : p.issue);
@@ -242,6 +260,10 @@ export function normalizeGitHubEvent(eventName, payload, app) {
             body,
             author: user.login,
             authorId: String(user.id),
+            authorAssociation: String(comment?.author_association),
+            ...(typeof obj(p.repository)?.private === "boolean"
+                ? { repositoryPrivate: obj(p.repository)?.private }
+                : {}),
             ...(subject ? { subject } : {}),
             ...(priorRunId ? { priorRunId } : {}),
         };

package/dist/providers/review-host/github.d.ts

@@ -5,7 +5,9 @@
  * and revokes it afterwards. See docs/private/2026-09-25-code-review-host-design.md §5.1.
  */
 import { type GitHubAppClient } from "../vcs/github.js";
-import { ReviewHostError, type CiView, type CodeReviewHost, type CommentInput, type CommentRef, type CompleteCheckInput, type EditCommentInput, type FileListView, type FileReadResult, type HostPermission, type HostUser, type PublishReviewInput, type PublishReviewResult, type PullRequestHead, type PullRequestOrigin, type PullRequestView, type StartCheckInput } from "./types.js";
+import { ReviewHostError, type CiView, type CodeReviewHost, type CommentInput, type AcknowledgeOutcome, type CommentRef, type CompleteCheckInput, type EditCommentInput, type FileListView, type FileReadResult, type HostPermission, type IssueReadResult, type HostUser, type OwnCheckView, type PublishReviewInput, type PublishReviewResult, type PullRequestHead, type PullRequestOrigin, type PullRequestView, type StartCheckInput, type UpsertNamedCheckInput } from "./types.js";
+/** wardby's proposed description in a pull request read is cut to this many bytes (UTF-8). */
+export declare const MAX_REVIEW_DESCRIPTION_PROPOSAL_BYTES: number;
 /** listFiles leaves out vendored trees and lockfiles; every host applies the same filter. */
 export declare function skippedInListing(path: string): boolean;
 type Json = Record<string, unknown>;
@@ -16,6 +18,7 @@ export declare class GitHubReviewHost implements CodeReviewHost {
     private readonly client;
     readonly provider: "github";
     constructor(client: GitHubAppClient);
+    appOwnerLogin(): Promise<string>;
     /** Runs `action` with a token for exactly `permissions`, translating failures to ReviewHostError. */
     protected withToken<T>(repository: string, permissions: Record<string, "read" | "write">, action: (get: (path: string, init?: RequestInit, expected?: number[]) => Promise<Response>, graphql: GraphQl) => Promise<T>): Promise<T>;
     repositoryPermission(repository: string, user: HostUser): Promise<{
@@ -43,11 +46,21 @@ export declare class GitHubReviewHost implements CodeReviewHost {
         sinceSha?: string;
         maxPatchChars: number;
         agentMarker: string;
+        patchCursor?: string;
     }): Promise<PullRequestView>;
+    /**
+     * wardby's proposed description from its description comment (the newest
+     * one this App wrote, found the way the writer finds it), trusted only for
+     * the head it was stamped with. Undefined when there is no pending proposal.
+     */
+    private descriptionProposalFor;
     readFile(repository: string, path: string, ref: string | undefined, window: {
         startLine: number;
         maxLines: number;
     }): Promise<FileReadResult>;
+    readIssue(repository: string, number: number, opts?: {
+        comments?: boolean;
+    }): Promise<IssueReadResult>;
     listFiles(repository: string, ref: string | undefined, pathPrefix?: string): Promise<FileListView>;
     publishReview(repository: string, input: PublishReviewInput): Promise<PublishReviewResult>;
     /**
@@ -60,15 +73,39 @@ export declare class GitHubReviewHost implements CodeReviewHost {
     private publishOnly;
     private findSummaryComment;
     private patchCheck;
+    /**
+     * Bodies here carry model or run text (repo_comment, a mention's status and reply), so every
+     * `<!--` that opens a wardby marker is escaped: no comment posted this way can hold one. Only
+     * publishReview writes the review marker, by its own path.
+     */
     comment(repository: string, input: CommentInput): Promise<{
         url: string;
         id: string;
     }>;
     editComment(repository: string, input: EditCommentInput): Promise<void>;
-    acknowledge(repository: string, target: CommentRef): Promise<void>;
+    acknowledge(repository: string, target: CommentRef, outcome?: AcknowledgeOutcome): Promise<void>;
     startCheck(repository: string, input: StartCheckInput): Promise<{
         checkId: string;
     }>;
     completeCheck(repository: string, input: CompleteCheckInput): Promise<void>;
+    /**
+     * Creates or updates, by fixed name, a check run on `input.headSha` that
+     * this App owns: lists the commit's check runs filtered to that name and
+     * patches the newest one `fromApp` owns, else creates one. Writes nothing
+     * when that run already carries the same status, conclusion, and output.
+     * A completed run is never moved back to in_progress (GitHub does not
+     * allow reopening a completed check run): a fresh one is created instead.
+     */
+    upsertNamedCheck(repository: string, input: UpsertNamedCheckInput): Promise<void>;
+    /** This App's newest check run per name on `headSha`, one request per name (at most MAX_OWN_CHECK_NAMES). */
+    readOwnChecks(repository: string, headSha: string, names: string[]): Promise<Map<string, OwnCheckView>>;
+    /**
+     * Marks a draft pull request ready for review, only when it is still open,
+     * a draft, at `expectedHeadSha`, and carries `expectedMarkerRunId` in its
+     * description's run marker (this App's own PR for that run). "skipped"
+     * covers every refusal, including a head that moved since the caller last
+     * checked it.
+     */
+    markReadyForReview(repository: string, prNumber: number, expectedHeadSha: string, expectedMarkerRunId: string): Promise<"marked" | "skipped">;
 }
 export {};