@openforge-app/plugin-sdk 0.1.0 → 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koen Van Geert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @openforge-app/plugin-sdk
+
+Public SDK for building OpenForge plugins. [`docs/plugin-authoring.md`](../../docs/plugin-authoring.md) is the canonical guide for the package, runtime, Svelte-sharing, and CSS-loading contract.
+
+Styled frontend plugins must declare Vite/Svelte's emitted CSS artifacts in `package.json#openforge.frontendStyles`:
+
+```json
+{
+  "openforge": {
+    "frontend": "./dist/frontend.js",
+    "frontendStyles": ["./dist/plugin.css"]
+  }
+}
+```
+
+The host validates, attaches, reloads, and removes these package-relative stylesheets with the frontend plugin lifecycle.
+
+## Publishing
+
+Automated releases use npm trusted publishing rather than a long-lived npm token. Configure the package's npm Trusted Publisher with repository `koenvg/openforge`, workflow `publish-plugin-sdk.yml`, and environment `npm-publish`. The workflow is the caller npm validates even though the shared publish steps live in `reusable-publish-plugin-sdk.yml`. For a failed tag release, dispatch this workflow manually with the missing `package_version` and disable dry-run.
+
+## License
+
+`@openforge-app/plugin-sdk` is licensed under the MIT License. Plugin authors may use it for personal, internal, open source, or commercial plugin development, including redistribution and modification under the MIT terms.
+
+This MIT license applies to the SDK package only. The OpenForge desktop application is licensed separately under the repository root `LICENSE` and is source-available/proprietary; the app may not be commercially resold or redistributed without permission.

package/dist/backend.d.ts

@@ -1,3 +1,3 @@
-import type { BackendMethodRegistration, BackendMethodRegistry, BackendOpenForgeAPI, BackendPlugin, BackendPluginContext, BackgroundServiceRegistration, BackgroundServiceRegistry, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot } from './types';
+import type { BackendFileSystemAPI, BackendMethodRegistration, BackendMethodRegistry, BackendOpenForgeAPI, BackendPlugin, BackendPluginContext, BackgroundServiceRegistration, BackgroundServiceRegistry, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadFileSystemAPI, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot } from './types';
 export declare function defineBackendPlugin<const TPlugin extends BackendPlugin>(plugin: TPlugin): TPlugin;
-export type { BackendMethodRegistration, BackendMethodRegistry, BackendOpenForgeAPI, BackendPlugin, BackendPluginContext, BackgroundServiceRegistration, BackgroundServiceRegistry, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, };
+export type { BackendFileSystemAPI, BackendMethodRegistration, BackendMethodRegistry, BackendOpenForgeAPI, BackendPlugin, BackendPluginContext, BackgroundServiceRegistration, BackgroundServiceRegistry, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadFileSystemAPI, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, };

package/dist/browserSurfaces.d.ts

@@ -0,0 +1,78 @@
+import type { Disposable } from './types';
+export type BrowserSurfaceErrorCode = 'CAPABILITY_UNAVAILABLE' | 'HOST_UNAVAILABLE' | 'INVALID_TASK' | 'PLUGIN_NOT_ENABLED' | 'INVALID_ID' | 'INVALID_URL' | 'INVALID_BOUNDS' | 'CAPTURE_UNAVAILABLE' | 'CAPTURE_FAILED' | 'SURFACE_ACCESS_DENIED' | 'SURFACE_DESTROYED';
+export declare class BrowserSurfaceError extends Error {
+    readonly code: BrowserSurfaceErrorCode;
+    constructor(code: BrowserSurfaceErrorCode, message: string);
+}
+export interface BrowserSurfaceNavigationError {
+    code: string;
+    message: string;
+    url: string;
+}
+export interface TaskBrowserSurfaceState {
+    url: string;
+    title: string;
+    loading: boolean;
+    canGoBack: boolean;
+    canGoForward: boolean;
+    error: BrowserSurfaceNavigationError | null;
+}
+export interface BrowserSurfaceCapture {
+    artifactId: string;
+    /** Absolute local PNG path retained for the Task Agent after acknowledgement. */
+    absolutePath: string;
+    mediaType: 'image/png';
+    width: number;
+    height: number;
+    url: string;
+    title: string;
+    capturedAt: string;
+    dataUrl: string;
+}
+export interface GetOrCreateBrowserSurfaceRequest {
+    taskId: string;
+    id: string;
+    initialUrl?: string;
+}
+export interface BrowserSurfaceRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface BrowserSurfaceFeedbackSelection {
+    region: BrowserSurfaceRegion;
+    comment: string;
+    /** Host-assigned number rendered on the live page. Older hosts may omit it. */
+    annotationNumber?: number;
+}
+export interface BrowserSurfaceVisualFeedback {
+    annotationNumber: number;
+    url: string;
+    region: BrowserSurfaceRegion;
+    comment: string;
+}
+export interface TaskBrowserSurfaceController {
+    attach(element: HTMLElement): Promise<Disposable>;
+    detach(): Promise<void>;
+    destroy(): Promise<void>;
+    getState(): Promise<TaskBrowserSurfaceState>;
+    onStateChanged(handler: (state: TaskBrowserSurfaceState) => void): Disposable;
+    navigate(url: string): Promise<TaskBrowserSurfaceState>;
+    goBack(): Promise<TaskBrowserSurfaceState>;
+    goForward(): Promise<TaskBrowserSurfaceState>;
+    reload(): Promise<TaskBrowserSurfaceState>;
+    stop(): Promise<TaskBrowserSurfaceState>;
+    selectVisibleRegion(): Promise<BrowserSurfaceFeedbackSelection | null>;
+    cancelVisibleRegionSelection(): Promise<void>;
+    clearVisualFeedback(): Promise<void>;
+    replaceVisualFeedback(feedback: readonly BrowserSurfaceVisualFeedback[]): Promise<void>;
+    captureExists(artifactId: string): Promise<boolean>;
+    captureVisibleViewport(): Promise<BrowserSurfaceCapture>;
+    discardCapture(artifactId: string): Promise<void>;
+}
+export interface BrowserSurfacesAPI {
+    getOrCreate(request: GetOrCreateBrowserSurfaceRequest): Promise<TaskBrowserSurfaceController>;
+    resetSession(): Promise<void>;
+}
+export declare function isAllowedBrowserSurfaceUrl(value: string): boolean;

package/dist/browserSurfaces.js

@@ -0,0 +1,17 @@
+export class BrowserSurfaceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'BrowserSurfaceError';
+        this.code = code;
+    }
+}
+export function isAllowedBrowserSurfaceUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/browserSurfacesTesting.d.ts

@@ -0,0 +1,60 @@
+import type { BrowserSurfacesAPI, BrowserSurfaceVisualFeedback, GetOrCreateBrowserSurfaceRequest, TaskBrowserSurfaceState } from './browserSurfaces';
+export interface TestingBrowserSurfaceCalls {
+    browserSurfaceGetOrCreate: GetOrCreateBrowserSurfaceRequest[];
+    browserSurfaceAttachments: Array<{
+        taskId: string;
+        id: string;
+        element: HTMLElement;
+    }>;
+    browserSurfaceDetaches: Array<{
+        taskId: string;
+        id: string;
+    }>;
+    browserSurfaceDestroys: Array<{
+        taskId: string;
+        id: string;
+    }>;
+    browserSurfaceNavigations: Array<{
+        taskId: string;
+        id: string;
+        url: string;
+    }>;
+    browserSurfaceControls: Array<{
+        taskId: string;
+        id: string;
+        action: 'goBack' | 'goForward' | 'reload' | 'stop';
+    }>;
+    browserSurfaceSelections: Array<{
+        taskId: string;
+        id: string;
+    }>;
+    browserSurfaceFeedbackClears: Array<{
+        taskId: string;
+        id: string;
+    }>;
+    browserSurfaceFeedbackReplacements: Array<{
+        taskId: string;
+        id: string;
+        feedback: BrowserSurfaceVisualFeedback[];
+    }>;
+    browserSurfaceCaptureChecks: Array<{
+        taskId: string;
+        id: string;
+        artifactId: string;
+    }>;
+    browserSurfaceCaptures: Array<{
+        taskId: string;
+        id: string;
+    }>;
+    browserSurfaceCaptureDiscards: Array<{
+        taskId: string;
+        id: string;
+        artifactId: string;
+    }>;
+    browserSurfaceSessionResets: Array<Record<string, never>>;
+}
+export interface TestingBrowserSurfaces {
+    readonly api: BrowserSurfacesAPI;
+    setState(taskId: string, id: string, patch: Partial<TaskBrowserSurfaceState>): void;
+}
+export declare function createTestingBrowserSurfaces(calls: TestingBrowserSurfaceCalls): TestingBrowserSurfaces;

package/dist/browserSurfacesTesting.js

@@ -0,0 +1,240 @@
+import { BrowserSurfaceError, isAllowedBrowserSurfaceUrl, } from './browserSurfaces';
+function disposable(dispose) {
+    let disposed = false;
+    return {
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            await dispose();
+        },
+    };
+}
+function surfaceKey(taskId, id) {
+    return `${taskId}\u0000${id}`;
+}
+function copyState(state) {
+    return { ...state, error: state.error ? { ...state.error } : null };
+}
+function validateIdentity(taskId, id) {
+    if (!taskId.trim())
+        throw new BrowserSurfaceError('INVALID_TASK', 'Task Browser Surface requires a non-empty Task ID');
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(id)) {
+        throw new BrowserSurfaceError('INVALID_ID', 'Task Browser Surface id must be a stable non-empty local identifier');
+    }
+}
+class TestingTaskBrowserSurface {
+    taskId;
+    id;
+    calls;
+    onDestroyed;
+    state;
+    history;
+    historyIndex = 0;
+    listeners = new Set();
+    currentAttachment = 0;
+    destroyed = false;
+    nextAnnotationNumber = 1;
+    capturedArtifactIds = new Set();
+    constructor(taskId, id, initialUrl, calls, onDestroyed) {
+        this.taskId = taskId;
+        this.id = id;
+        this.calls = calls;
+        this.onDestroyed = onDestroyed;
+        const url = initialUrl ?? 'about:blank';
+        this.history = [url];
+        this.state = {
+            url,
+            title: '',
+            loading: false,
+            canGoBack: false,
+            canGoForward: false,
+            error: null,
+        };
+    }
+    async attach(element) {
+        this.assertLive();
+        const attachment = ++this.currentAttachment;
+        this.calls.browserSurfaceAttachments.push({ taskId: this.taskId, id: this.id, element });
+        return disposable(async () => {
+            if (this.destroyed || attachment !== this.currentAttachment)
+                return;
+            await this.detach();
+        });
+    }
+    async detach() {
+        this.assertLive();
+        this.currentAttachment += 1;
+        this.calls.browserSurfaceDetaches.push({ taskId: this.taskId, id: this.id });
+    }
+    async destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.listeners.clear();
+        this.calls.browserSurfaceDestroys.push({ taskId: this.taskId, id: this.id });
+        this.onDestroyed();
+    }
+    async getState() {
+        this.assertLive();
+        return copyState(this.state);
+    }
+    onStateChanged(handler) {
+        this.assertLive();
+        this.listeners.add(handler);
+        return disposable(() => { this.listeners.delete(handler); });
+    }
+    async navigate(url) {
+        this.assertLive();
+        if (!isAllowedBrowserSurfaceUrl(url)) {
+            throw new BrowserSurfaceError('INVALID_URL', 'Task Browser Surfaces only allow HTTP(S) navigation');
+        }
+        this.calls.browserSurfaceNavigations.push({ taskId: this.taskId, id: this.id, url });
+        this.history.splice(this.historyIndex + 1);
+        this.history.push(url);
+        this.historyIndex = this.history.length - 1;
+        this.publish({ url, title: '', error: null });
+        return this.getState();
+    }
+    async goBack() {
+        this.assertLive();
+        this.calls.browserSurfaceControls.push({ taskId: this.taskId, id: this.id, action: 'goBack' });
+        if (this.historyIndex > 0)
+            this.historyIndex -= 1;
+        this.publish({ url: this.history[this.historyIndex], error: null });
+        return this.getState();
+    }
+    async goForward() {
+        this.assertLive();
+        this.calls.browserSurfaceControls.push({ taskId: this.taskId, id: this.id, action: 'goForward' });
+        if (this.historyIndex < this.history.length - 1)
+            this.historyIndex += 1;
+        this.publish({ url: this.history[this.historyIndex], error: null });
+        return this.getState();
+    }
+    async reload() {
+        this.assertLive();
+        this.calls.browserSurfaceControls.push({ taskId: this.taskId, id: this.id, action: 'reload' });
+        this.publish({ error: null });
+        return this.getState();
+    }
+    async stop() {
+        this.assertLive();
+        this.calls.browserSurfaceControls.push({ taskId: this.taskId, id: this.id, action: 'stop' });
+        this.publish({ loading: false });
+        return this.getState();
+    }
+    async selectVisibleRegion() {
+        this.assertLive();
+        this.calls.browserSurfaceSelections.push({ taskId: this.taskId, id: this.id });
+        return {
+            region: { x: 0.1, y: 0.1, width: 0.4, height: 0.4 },
+            comment: 'Example visual feedback',
+            annotationNumber: this.nextAnnotationNumber++,
+        };
+    }
+    async cancelVisibleRegionSelection() {
+        this.assertLive();
+    }
+    async clearVisualFeedback() {
+        this.assertLive();
+        this.calls.browserSurfaceFeedbackClears.push({ taskId: this.taskId, id: this.id });
+        this.nextAnnotationNumber = 1;
+    }
+    async replaceVisualFeedback(feedback) {
+        this.assertLive();
+        this.calls.browserSurfaceFeedbackReplacements.push({
+            taskId: this.taskId,
+            id: this.id,
+            feedback: feedback.map(marker => ({ ...marker, region: { ...marker.region } })),
+        });
+        this.nextAnnotationNumber = feedback.reduce((maximum, marker) => Math.max(maximum, marker.annotationNumber), 0) + 1;
+    }
+    async captureExists(artifactId) {
+        this.assertLive();
+        if (!artifactId.trim())
+            throw new BrowserSurfaceError('INVALID_ID', 'Browser Surface capture requires an artifact ID');
+        this.calls.browserSurfaceCaptureChecks.push({ taskId: this.taskId, id: this.id, artifactId });
+        return this.capturedArtifactIds.has(artifactId);
+    }
+    async captureVisibleViewport() {
+        this.assertLive();
+        this.calls.browserSurfaceCaptures.push({ taskId: this.taskId, id: this.id });
+        const artifactId = `capture-${this.calls.browserSurfaceCaptures.length}`;
+        this.capturedArtifactIds.add(artifactId);
+        return {
+            artifactId,
+            absolutePath: `/tmp/openforge-browser-captures/${this.taskId}/capture-${this.calls.browserSurfaceCaptures.length}.png`,
+            mediaType: 'image/png',
+            width: 800,
+            height: 600,
+            url: this.state.url,
+            title: this.state.title,
+            capturedAt: '2026-01-01T00:00:00.000Z',
+            dataUrl: 'data:image/png;base64,iVBORw0KGgo=',
+        };
+    }
+    async discardCapture(artifactId) {
+        this.assertLive();
+        if (!artifactId.trim())
+            throw new BrowserSurfaceError('INVALID_ID', 'Browser Surface capture requires an artifact ID');
+        this.calls.browserSurfaceCaptureDiscards.push({ taskId: this.taskId, id: this.id, artifactId });
+        this.capturedArtifactIds.delete(artifactId);
+    }
+    setState(patch) {
+        this.assertLive();
+        this.state = copyState({ ...this.state, ...patch });
+        this.notify();
+    }
+    publish(patch) {
+        this.state = {
+            ...this.state,
+            ...patch,
+            canGoBack: this.historyIndex > 0,
+            canGoForward: this.historyIndex < this.history.length - 1,
+        };
+        this.notify();
+    }
+    notify() {
+        for (const listener of this.listeners)
+            listener(copyState(this.state));
+    }
+    assertLive() {
+        if (this.destroyed)
+            throw new BrowserSurfaceError('SURFACE_DESTROYED', 'Task Browser Surface has been destroyed');
+    }
+}
+export function createTestingBrowserSurfaces(calls) {
+    const surfaces = new Map();
+    const api = {
+        async getOrCreate(request) {
+            const recorded = request.initialUrl === undefined ? { taskId: request.taskId, id: request.id } : { ...request };
+            calls.browserSurfaceGetOrCreate.push(recorded);
+            validateIdentity(request.taskId, request.id);
+            const key = surfaceKey(request.taskId, request.id);
+            let surface = surfaces.get(key);
+            if (!surface) {
+                if (request.initialUrl !== undefined && !isAllowedBrowserSurfaceUrl(request.initialUrl)) {
+                    throw new BrowserSurfaceError('INVALID_URL', 'Task Browser Surfaces only allow HTTP(S) initial URLs');
+                }
+                surface = new TestingTaskBrowserSurface(request.taskId, request.id, request.initialUrl, calls, () => surfaces.delete(key));
+                surfaces.set(key, surface);
+            }
+            return surface;
+        },
+        async resetSession() {
+            calls.browserSurfaceSessionResets.push({});
+            for (const surface of Array.from(surfaces.values()))
+                await surface.destroy();
+        },
+    };
+    return {
+        api,
+        setState(taskId, id, patch) {
+            const surface = surfaces.get(surfaceKey(taskId, id));
+            if (!surface)
+                throw new BrowserSurfaceError('SURFACE_DESTROYED', 'Task Browser Surface is not live');
+            surface.setState(patch);
+        },
+    };
+}

package/dist/domain.d.ts

@@ -23,17 +23,15 @@ export interface Task {
     title_source: 'manual' | 'generated' | null;
     /** Unix timestamp for the first generated title write; null means generation has not written yet. */
     title_generated_at: number | null;
-    summary: string | null;
     agent: string | null;
     permission_mode: string | null;
     worktree_source: WorktreeSource | null;
     worktree_branch: string | null;
     /**
-     * Whether the task's start prompt includes the OpenForge handoff-notes
-     * (task management) block. Defaults to true; false opts the task out so the
-     * agent is not instructed to maintain Handoff Notes.
+     * Optional link to the source ticket this task originated from (e.g. a GitHub
+     * issue URL or Jira browse link). `null` when no ticket was provided.
      */
-    handoff_notes_enabled: boolean;
+    source_ticket_url: string | null;
     depends_on: string[];
     project_id: string | null;
     created_at: number;
@@ -90,6 +88,7 @@ export interface AgentSession {
     provider: string;
     claude_session_id: string | null;
     pi_session_id: string | null;
+    grok_session_id: string | null;
 }
 export interface ClaudeInstallStatus {
     installed: boolean;
@@ -114,6 +113,8 @@ export interface PrComment {
     file_path: string | null;
     line_number: number | null;
     addressed: number;
+    /** 1 when GitHub considers the comment outdated (its diff line changed). */
+    outdated: number;
     created_at: number;
 }
 export interface PullRequestInfo {
@@ -250,12 +251,25 @@ export interface RateLimitNotification {
 export interface AgentInfo {
     name: string;
 }
-/** Command info from provider command endpoints — used for / autocomplete */
+/** Command info from provider command endpoints — used for / autocomplete and injectable catalogs */
 export interface CommandInfo {
     name: string;
     description: string | null;
     source: string | null;
     agent: string | null;
+    /** Where it comes from: "personal" | "project" | "plugin" | "builtin". Optional enrichment — only claude-code populates it. */
+    origin?: string | null;
+    /** "auto+manual" | "manual-only" — derived from disable-model-invocation / command semantics */
+    triggerMode?: string | null;
+    /** false => hidden background skill; injectable catalogs drop it */
+    userInvocable?: boolean | null;
+    /** e.g. ".claude" | ".agents"; null for builtin/plugin */
+    sourceDir?: string | null;
+    /** stable on-disk identity under the source skills dir — for a skill, its folder name
+     * (a single path component, e.g. "pr-writer"); for a command, the file name. null for builtin */
+    sourcePath?: string | null;
+    /** full SKILL.md body for a consumer's reading pane; null when there is no source file */
+    content?: string | null;
 }
 /** Extended agent info from provider agent endpoints — used for @ autocomplete */
 export interface AutocompleteAgentInfo {
@@ -294,6 +308,17 @@ export interface ProjectAttention {
     unaddressed_comments: number;
     completed_agents: number;
 }
+export type TaskAttentionState = 'idle' | 'needs-input' | 'paused' | 'agent-done' | 'failed' | 'interrupted' | 'pr-draft' | 'pr-open' | 'ci-failed' | 'changes-requested' | 'unaddressed-comments' | 'ready-to-merge' | 'ready-to-enqueue' | 'pr-queued' | 'pr-merged' | 'pr-closed' | 'ci-running' | 'review-pending' | 'merge-conflict';
+/** Backend-owned, Task-only Needs Attention read model. */
+export interface TaskAttentionRow {
+    task_id: string;
+    project_id: string;
+    project_name: string;
+    title: string;
+    state: TaskAttentionState;
+    reason: string;
+    activity_at: number;
+}
 export interface WorktreeInfo {
     id: number;
     task_id: string;
@@ -401,9 +426,13 @@ export interface ReviewPullRequest {
 }
 /** GitHub label that suppresses a PR from review counting and grays out its card. */
 export declare const DO_NOT_REVIEW_LABEL = "DO NOT REVIEW";
-/** True when the PR carries the "DO NOT REVIEW" label (case-insensitive, trimmed). */
+/**
+ * True when the PR carries the "DO NOT REVIEW" label (case-insensitive, trimmed).
+ * Tolerates a missing or null `labels` field so a single implementation can back
+ * both the plugin PR views and the app-side sort/badge helpers.
+ */
 export declare function hasDoNotReviewLabel(pr: {
-    labels: PrLabel[];
+    labels?: PrLabel[] | null;
 }): boolean;
 /** File diff from PR files endpoint */
 export interface PrFileDiff {
@@ -516,6 +545,43 @@ export interface AgentReviewComment {
     created_at: number;
     updated_at: number;
 }
+/** One message in a local "Ask the AI author" Q&A thread. Never sent to GitHub. */
+export interface AiThreadMessage {
+    role: 'user' | 'ai';
+    body: string;
+    created_at: number;
+}
+/**
+ * Where a Q&A thread is anchored: a specific diff line, a walkthrough step, or a
+ * specific AI review comment (a follow-up like "why did you suggest this?"). The
+ * `comment` variant carries the AI comment's id (so its suggestion can be quoted
+ * as context) plus the denormalized diff location so it renders inline like a
+ * line-anchored thread.
+ */
+export type AiThreadAnchor = {
+    type: 'line';
+    filename: string;
+    line: number;
+    side: 'LEFT' | 'RIGHT';
+} | {
+    type: 'step';
+    step_id: string;
+} | {
+    type: 'comment';
+    comment_id: number;
+    filename: string;
+    line: number;
+    side: 'LEFT' | 'RIGHT';
+};
+/** A private, per-commit reviewer↔AI conversation, stored locally (never on GitHub). */
+export interface AiThread {
+    id: string;
+    anchor: AiThreadAnchor;
+    status: 'draft' | 'pending' | 'answered' | 'error';
+    messages: AiThreadMessage[];
+    created_at: number;
+    updated_at: number;
+}
 /** App-level view for top-bar navigation */
 export type CoreAppView = 'board' | 'settings' | 'global_settings' | 'files';
 /** App-level view for top-bar navigation */
@@ -551,13 +617,6 @@ export declare function splitCheckRuns(checks: CheckRunInfo[]): {
     visible: CheckRunInfo[];
     passingCount: number;
 };
-export interface Action {
-    id: string;
-    name: string;
-    prompt: string;
-    builtin: boolean;
-    enabled: boolean;
-}
 export type VoiceInputState = 'idle' | 'recording' | 'transcribing' | 'error';
 export interface TranscriptionResult {
     text: string;

package/dist/domain.js

@@ -293,7 +293,11 @@ export function preservePullRequestState(oldPr, newPr) {
 }
 /** GitHub label that suppresses a PR from review counting and grays out its card. */
 export const DO_NOT_REVIEW_LABEL = 'DO NOT REVIEW';
-/** True when the PR carries the "DO NOT REVIEW" label (case-insensitive, trimmed). */
+/**
+ * True when the PR carries the "DO NOT REVIEW" label (case-insensitive, trimmed).
+ * Tolerates a missing or null `labels` field so a single implementation can back
+ * both the plugin PR views and the app-side sort/badge helpers.
+ */
 export function hasDoNotReviewLabel(pr) {
     return (pr.labels ?? []).some((label) => label.name.trim().toUpperCase() === DO_NOT_REVIEW_LABEL);
 }

package/dist/fileIcons.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_FILE_ICON = "file";
+export declare const DEFAULT_FOLDER_ICON = "folder";
+export declare const DEFAULT_FOLDER_OPEN_ICON = "folder-open";
+export declare function getFileIconName(filename: string): string;
+export declare function getFolderIconName(open: boolean): string;
+export declare const BUNDLED_ICON_NAMES: readonly string[];