@openforge-app/plugin-sdk 0.1.0

package/dist/backend.d.ts

@@ -0,0 +1,3 @@
+import type { BackendMethodRegistration, BackendMethodRegistry, BackendOpenForgeAPI, BackendPlugin, BackendPluginContext, BackgroundServiceRegistration, BackgroundServiceRegistry, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, 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, };

package/dist/backend.js

@@ -0,0 +1,3 @@
+export function defineBackendPlugin(plugin) {
+    return plugin;
+}

package/dist/context.d.ts

@@ -0,0 +1,14 @@
+import type { Disposable, OpenForgePackageMetadata, OpenForgePluginContext, SubscriptionSink, SupportedOpenForgeApiVersion } from './types';
+declare class SubscriptionSet implements SubscriptionSink {
+    private readonly subscriptions;
+    add(subscription: Disposable | (() => void)): void;
+    disposeAll(): Promise<void>;
+}
+export declare class PluginContextImpl implements OpenForgePluginContext {
+    readonly pluginId: string;
+    readonly apiVersion: SupportedOpenForgeApiVersion;
+    readonly packageMetadata: OpenForgePackageMetadata;
+    readonly subscriptions: SubscriptionSet;
+    constructor(pluginId: string, apiVersion: SupportedOpenForgeApiVersion, packageMetadata: OpenForgePackageMetadata);
+}
+export {};

package/dist/context.js

@@ -0,0 +1,30 @@
+class SubscriptionSet {
+    subscriptions = new Set();
+    add(subscription) {
+        this.subscriptions.add(subscription);
+    }
+    async disposeAll() {
+        const subscriptions = [...this.subscriptions];
+        this.subscriptions.clear();
+        await Promise.all(subscriptions.map(async (subscription) => {
+            if (typeof subscription === 'function') {
+                subscription();
+            }
+            else {
+                await subscription.dispose();
+            }
+        }));
+    }
+}
+export class PluginContextImpl {
+    pluginId;
+    apiVersion;
+    packageMetadata;
+    subscriptions;
+    constructor(pluginId, apiVersion, packageMetadata) {
+        this.pluginId = pluginId;
+        this.apiVersion = apiVersion;
+        this.packageMetadata = packageMetadata;
+        this.subscriptions = new SubscriptionSet();
+    }
+}

package/dist/domain.d.ts

@@ -0,0 +1,579 @@
+import type { PluginViewKey } from './types';
+export type { PluginViewKey } from './types';
+export type BoardStatus = 'backlog' | 'doing' | 'done';
+/**
+ * The subset of {@link BoardStatus} a client may assign to a task.
+ *
+ * `'done'` is a legacy, recognized-but-unreachable status (AVIV-118 removed the
+ * Done lane and its reopen path). Assigning it hides the task from every board
+ * surface with no runtime cleanup, so it stays readable on existing rows but is
+ * never a valid write target. The backend rejects it regardless; this type gives
+ * plugin and renderer callers a compile-time signal.
+ */
+export type WritableBoardStatus = Exclude<BoardStatus, 'done'>;
+export type WorktreeSource = 'newBranchFromMain' | 'existingBranch' | 'disabled';
+export interface Task {
+    id: string;
+    initial_prompt: string;
+    status: BoardStatus;
+    prompt: string | null;
+    /** Explicit display title; null means fall back to the prompt-derived title. */
+    title: string | null;
+    /** Origin of the explicit display title; manual titles are never overwritten by automation. */
+    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.
+     */
+    handoff_notes_enabled: boolean;
+    depends_on: string[];
+    project_id: string | null;
+    created_at: number;
+    updated_at: number;
+}
+export interface GitBranchInfo {
+    name: string;
+    is_current: boolean;
+    is_remote: boolean;
+}
+/**
+ * How an existing branch relates to its `origin/<branch>` remote-tracking ref,
+ * as reported by the read-only `inspectExistingBranch` pre-flight. Drives whether
+ * a task can start silently or must prompt the user to resolve divergence.
+ */
+export type ExistingBranchRelation = 'localOnly' | 'remoteOnly' | 'autoFastForward' | 'diverged';
+/** How to resolve a diverged existing branch when creating its worktree. */
+export type DivergenceResolution = 'auto' | 'keepLocal' | 'resetToRemote';
+/** A compact, display-oriented description of a single commit. */
+export interface CommitSummary {
+    shortSha: string;
+    subject: string;
+    author: string;
+    relativeDate: string;
+}
+/**
+ * Read-only plan describing how an existing branch relates to its origin remote
+ * at Start time. Produced without creating a worktree or mutating any branch.
+ */
+export interface ExistingBranchPlan {
+    relation: ExistingBranchRelation;
+    /** Local-only commits (`origin/foo..foo`), capped; lost by a reset-to-remote. */
+    ahead: CommitSummary[];
+    /** Remote-only commits (`foo..origin/foo`), capped; on the remote but not local. */
+    behind: CommitSummary[];
+    /** True when the ahead list was truncated to the cap (more commits exist). */
+    aheadTruncated: boolean;
+    /** True when the behind list was truncated to the cap (more commits exist). */
+    behindTruncated: boolean;
+    /** False when the origin fetch failed, so the comparison may be stale. */
+    remoteReachable: boolean;
+}
+export interface AgentSession {
+    id: string;
+    ticket_id: string;
+    opencode_session_id: string | null;
+    stage: string;
+    status: string;
+    checkpoint_data: string | null;
+    pty_instance_id: number | null;
+    error_message: string | null;
+    created_at: number;
+    updated_at: number;
+    provider: string;
+    claude_session_id: string | null;
+    pi_session_id: string | null;
+}
+export interface ClaudeInstallStatus {
+    installed: boolean;
+    path: string | null;
+    version: string | null;
+    authenticated: boolean;
+}
+export interface CheckpointNotification {
+    ticketId: string;
+    ticketKey: string | null;
+    sessionId: string;
+    stage: string;
+    message: string;
+    timestamp: number;
+}
+export interface PrComment {
+    id: number;
+    pr_id: number;
+    author: string;
+    body: string;
+    comment_type: string;
+    file_path: string | null;
+    line_number: number | null;
+    addressed: number;
+    created_at: number;
+}
+export interface PullRequestInfo {
+    id: number;
+    pr_number: number;
+    ticket_id: string;
+    repo_owner: string;
+    repo_name: string;
+    title: string;
+    url: string;
+    state: string;
+    head_sha: string;
+    ci_status: string | null;
+    ci_check_runs: string | null;
+    review_status: string | null;
+    mergeable: boolean | null;
+    mergeable_state: string | null;
+    merged_at: number | null;
+    created_at: number;
+    updated_at: number;
+    draft: boolean;
+    is_queued: boolean;
+    unaddressed_comment_count: number;
+    merge_readiness_status: MergeReadinessStatus | null;
+    merge_readiness_action: MergeReadinessAction | null;
+    merge_readiness_blockers: string | MergeReadinessDetail[] | null;
+    merge_readiness_warnings: string | MergeReadinessDetail[] | null;
+    readiness_source_head_sha: string | null;
+    merge_group_sha: string | null;
+    required_checks_policy_known: boolean | null;
+    required_reviews_policy_known: boolean | null;
+    merge_queue_required: boolean | null;
+    merge_queue_state: string | null;
+    readiness_updated_at: number | null;
+}
+export interface PollResult {
+    new_comments: number;
+    ci_changes: number;
+    review_changes: number;
+    pr_changes: number;
+    errors: number;
+    rate_limited: boolean;
+    rate_limit_reset_at: number | null;
+}
+export interface MergeStatusInfo {
+    state: string;
+    mergeable: boolean | null;
+    mergeable_state: string | null;
+}
+export interface PullRequestTerminalStateInfo {
+    state: string;
+    merged_at?: number | null;
+}
+export interface MergeReadinessInfo extends MergeStatusInfo {
+    ci_status?: string | null;
+    review_status?: string | null;
+    draft?: boolean;
+    is_queued?: boolean;
+    unaddressed_comment_count?: number;
+    head_sha?: string | null;
+    updated_at?: number | null;
+    merge_readiness_status?: MergeReadinessStatus | null;
+    merge_readiness_action?: MergeReadinessAction | null;
+    merge_readiness_blockers?: string | MergeReadinessDetail[] | null;
+    merge_readiness_warnings?: string | MergeReadinessDetail[] | null;
+    readiness_source_head_sha?: string | null;
+    readiness_updated_at?: number | null;
+}
+export interface MergeReadinessOptions {
+    requireBranchUpToDate?: boolean;
+    requireConversationResolution?: boolean;
+    requireMergeQueue?: boolean;
+}
+export type MergeReadinessStatus = 'ready_to_merge' | 'ready_to_enqueue' | 'queued_pull_request' | 'readiness_unknown' | 'blocked';
+export type MergeReadinessAction = 'merge' | 'enqueue' | 'wait_for_queue' | 'wait_for_github' | 'resolve_blockers';
+export interface MergeReadinessDetail {
+    code: string;
+    message: string;
+}
+export interface MergeReadinessFreshness {
+    sourceSha: string | null;
+    checkedAt: number | null;
+}
+export interface MergeReadinessResult {
+    status: MergeReadinessStatus;
+    action: MergeReadinessAction;
+    blockers: MergeReadinessDetail[];
+    warnings: MergeReadinessDetail[];
+    freshness: MergeReadinessFreshness;
+}
+export declare function isClosedOrMergedPullRequest(state: string): boolean;
+export declare function isMergedPullRequest(pr: PullRequestTerminalStateInfo): boolean;
+export declare function isClosedUnmergedPullRequest(pr: PullRequestTerminalStateInfo): boolean;
+export declare function hasMergeConflicts(pr: MergeStatusInfo): boolean;
+export declare function getPersistedMergeReadiness(pr: MergeReadinessInfo): MergeReadinessResult | null;
+/**
+ * Explains whether a pull request is ready for a direct merge, queue enqueueing,
+ * waiting on GitHub/merge queue, or blocked by hard requirements.
+ */
+export declare function getMergeReadiness(pr: MergeReadinessInfo, options?: MergeReadinessOptions): MergeReadinessResult;
+/** Check if a PR is ready for a direct merge action. */
+export declare function isReadyToMerge(pr: MergeReadinessInfo, options?: MergeReadinessOptions): boolean;
+/** Check if a user-initiated merge affordance may be shown/executed now. */
+export declare function canMergePullRequest(pr: MergeReadinessInfo): boolean;
+/** Check if a user-initiated merge-queue enqueue affordance may be shown/executed now. */
+export declare function canEnqueuePullRequest(pr: MergeReadinessInfo): boolean;
+export declare function getMostAttentionWorthyPullRequest<T extends MergeReadinessInfo>(prs: T[]): T | null;
+export interface QueuedStatusInfo {
+    state: string;
+    is_queued: boolean;
+}
+/** Check if GitHub reports a PR as queued in a merge queue. */
+export declare function isQueuedForMerge(pr: QueuedStatusInfo): boolean;
+/** Preserves optimistic and definitive states across transient background syncs */
+export declare function preservePullRequestState(oldPr: PullRequestInfo | undefined, newPr: PullRequestInfo): PullRequestInfo;
+export interface CheckRunInfo {
+    id: number;
+    name: string;
+    status: string;
+    conclusion: string | null;
+    html_url: string;
+}
+export interface CiFailureNotification {
+    task_id: string;
+    pr_id: number;
+    pr_title: string;
+    ci_status: string;
+    timestamp: number;
+}
+export interface RateLimitNotification {
+    reset_at: number | null;
+    timestamp: number;
+}
+export interface AgentInfo {
+    name: string;
+}
+/** Command info from provider command endpoints — used for / autocomplete */
+export interface CommandInfo {
+    name: string;
+    description: string | null;
+    source: string | null;
+    agent: string | null;
+}
+/** Extended agent info from provider agent endpoints — used for @ autocomplete */
+export interface AutocompleteAgentInfo {
+    name: string;
+    hidden: boolean | null;
+    mode: string | null;
+}
+/** Model option from OpenCode GET /provider endpoint */
+export interface ProviderModelInfo {
+    provider_id: string;
+    model_id: string;
+    name: string;
+}
+export interface AutocompleteItem {
+    label: string;
+    description: string | null;
+    type: 'file' | 'directory' | 'agent' | 'skill' | 'command';
+    source?: string | null;
+}
+export interface OpenCodeEvent {
+    event_type: string;
+    data: string;
+}
+export interface Project {
+    id: string;
+    name: string;
+    path: string;
+    created_at: number;
+    updated_at: number;
+}
+export interface ProjectAttention {
+    project_id: string;
+    needs_input: number;
+    running_agents: number;
+    ci_failures: number;
+    unaddressed_comments: number;
+    completed_agents: number;
+}
+export interface WorktreeInfo {
+    id: number;
+    task_id: string;
+    project_id: string;
+    repo_path: string;
+    worktree_path: string;
+    branch_name: string;
+    status: string;
+    created_at: number;
+    updated_at: number;
+}
+export interface TaskWorkspaceInfo {
+    id: number;
+    task_id: string;
+    project_id: string;
+    workspace_path: string;
+    repo_path: string;
+    kind: string;
+    branch_name: string | null;
+    provider_name: string;
+    status: string;
+    created_at: number;
+    updated_at: number;
+}
+export interface AgentEvent {
+    task_id: string;
+    event_type: string;
+    data: string;
+    timestamp: number;
+}
+export interface ImplementationStatus {
+    task_id: string;
+    workspace_path: string;
+    /** @deprecated Direct-TTY providers no longer expose or require an OpenCode server port. */
+    port: number;
+    session_id: string;
+}
+/**
+ * A GitHub label attached to a pull request. `color` is a 6-digit hex string
+ * without a leading '#', exactly as GitHub returns it (e.g. "b60205").
+ */
+export interface PrLabel {
+    name: string;
+    color: string;
+}
+/** PR authored by the authenticated user — cached from GitHub Search API */
+export interface AuthoredPullRequest {
+    id: number;
+    number: number;
+    title: string;
+    body: string | null;
+    state: string;
+    draft: boolean;
+    html_url: string;
+    user_login: string;
+    user_avatar_url: string | null;
+    repo_owner: string;
+    repo_name: string;
+    head_ref: string;
+    base_ref: string;
+    head_sha: string;
+    additions: number;
+    deletions: number;
+    changed_files: number;
+    ci_status: string | null;
+    ci_check_runs: string | null;
+    review_status: string | null;
+    mergeable: boolean | null;
+    mergeable_state: string | null;
+    merged_at: number | null;
+    is_queued: boolean;
+    task_id: string | null;
+    created_at: number;
+    updated_at: number;
+    /** GitHub labels on the PR. Empty when the PR has no labels. */
+    labels: PrLabel[];
+}
+/** PR from GitHub Search API — review requested for the authenticated user */
+export interface ReviewPullRequest {
+    id: number;
+    number: number;
+    title: string;
+    body: string | null;
+    state: string;
+    draft: boolean;
+    html_url: string;
+    user_login: string;
+    user_avatar_url: string | null;
+    repo_owner: string;
+    repo_name: string;
+    head_ref: string;
+    base_ref: string;
+    head_sha: string;
+    additions: number;
+    deletions: number;
+    changed_files: number;
+    mergeable: boolean | null;
+    mergeable_state: string | null;
+    created_at: number;
+    updated_at: number;
+    viewed_at: number | null;
+    viewed_head_sha: string | null;
+    /** GitHub labels on the PR. Empty when the PR has no labels. */
+    labels: PrLabel[];
+}
+/** 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). */
+export declare function hasDoNotReviewLabel(pr: {
+    labels: PrLabel[];
+}): boolean;
+/** File diff from PR files endpoint */
+export interface PrFileDiff {
+    sha: string;
+    filename: string;
+    status: string;
+    additions: number;
+    deletions: number;
+    changes: number;
+    patch: string | null;
+    previous_filename: string | null;
+    is_truncated: boolean;
+    patch_line_count: number | null;
+}
+/** Commit info from git log for per-commit diff viewing */
+export interface CommitInfo {
+    sha: string;
+    short_sha: string;
+    message: string;
+    author: string;
+    date: string;
+}
+/** PR overview comment (both review and general comments) */
+export interface PrOverviewComment {
+    id: number;
+    body: string;
+    author: string;
+    avatar_url: string | null;
+    comment_type: string;
+    file_path: string | null;
+    line_number: number | null;
+    created_at: string;
+}
+/** Inline review comment from GitHub PR */
+export interface ReviewComment {
+    id: number;
+    pr_number: number;
+    repo_owner: string;
+    repo_name: string;
+    path: string;
+    line: number | null;
+    side: string | null;
+    body: string;
+    author: string;
+    created_at: string;
+    in_reply_to_id: number | null;
+}
+/** Comment to include in a review submission */
+export interface ReviewSubmissionComment {
+    path: string;
+    line: number;
+    side: string;
+    body: string;
+}
+/** Review submission payload */
+export interface ReviewSubmission {
+    event: "APPROVE" | "REQUEST_CHANGES" | "COMMENT";
+    body: string;
+    comments: ReviewSubmissionComment[];
+}
+/** Self-review comment for task implementation review */
+export interface SelfReviewComment {
+    id: number;
+    task_id: string;
+    round: number;
+    comment_type: string;
+    file_path: string | null;
+    line_number: number | null;
+    body: string;
+    created_at: number;
+    archived_at: number | null;
+}
+/** One file referenced by a walkthrough step. `hunk_indexes === null` means the entire file's diff belongs to the step. */
+export interface PrWalkthroughStepFile {
+    filename: string;
+    hunk_indexes: number[] | null;
+}
+/** One concept-sized step in a PR walkthrough — as if the author had landed a small commit. */
+export interface PrWalkthroughStep {
+    id: string;
+    title: string;
+    summary: string;
+    files: PrWalkthroughStepFile[];
+}
+/** A cached AI-generated walkthrough of a PR, keyed by (pr_id, head_sha).
+ * `steps_json` is the agent's raw structured response. Parse + validate it
+ * against the live PR diffs before rendering (see walkthroughParse). */
+export interface PrWalkthrough {
+    pr_id: number;
+    head_sha: string;
+    walkthrough_session_key: string | null;
+    status: 'generating' | 'ready' | 'error';
+    steps_json: string | null;
+    error_message: string | null;
+    created_at: number;
+    updated_at: number;
+}
+/** Agent review comment for AI-powered PR review */
+export interface AgentReviewComment {
+    id: number;
+    review_pr_id: number;
+    review_session_key: string;
+    comment_type: string;
+    file_path: string | null;
+    line_number: number | null;
+    side: string | null;
+    body: string;
+    status: string;
+    opencode_session_id: string | null;
+    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 */
+export type AppView = CoreAppView | PluginViewKey;
+export interface PtySpawnRequest {
+    task_id: string;
+    cols: number;
+    rows: number;
+}
+export interface PtyEvent {
+    task_id: string;
+    data: string;
+    instance_id?: number;
+}
+/** File entry metadata */
+export interface FileEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    size: number | null;
+    modifiedAt: number | null;
+}
+/** File content with type information */
+export interface FileContent {
+    type: 'text' | 'image' | 'binary' | 'document' | 'large-file';
+    content: string;
+    mimeType: string | null;
+    size: number;
+}
+export declare function parseCheckRuns(json: string | null): CheckRunInfo[];
+/** Split check runs into visible (non-passing) and a count of hidden passing checks. */
+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;
+    duration_ms: number;
+}
+export type WhisperModelSizeId = 'tiny' | 'base' | 'small' | 'medium' | 'large';
+export interface WhisperModelStatus {
+    size: WhisperModelSizeId;
+    display_name: string;
+    downloaded: boolean;
+    model_path: string | null;
+    model_size_bytes: number | null;
+    model_name: string;
+    disk_size_mb: number;
+    ram_usage_mb: number;
+    is_active: boolean;
+}
+/** Permission mode for Claude Code sessions */
+export type PermissionMode = 'default' | 'auto' | 'acceptEdits' | 'plan' | 'bypassPermissions' | 'dontAsk';