@openforge-app/plugin-sdk 0.2.11 → 0.3.0

package/README.md

@@ -1,26 +1,238 @@
 # @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.
+TypeScript SDK for building trusted OpenForge plugins. It includes API version 1 types, frontend and backend entry-point helpers, package metadata validation, testing fakes, Vite helpers, and shared Svelte components.
 
-Styled frontend plugins must declare Vite/Svelte's emitted CSS artifacts in `package.json#openforge.frontendStyles`:
+OpenForge plugins run trusted code. Install plugins only from authors you trust.
+
+## Install
+
+```sh
+pnpm add @openforge-app/plugin-sdk
+```
+
+Frontend plugins also use the Svelte 5 runtime supplied by OpenForge. Add Svelte as a peer dependency and as a development dependency in the plugin package:
+
+```sh
+pnpm add -D svelte@^5 @sveltejs/vite-plugin-svelte vite
+```
+
+```json
+{
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  }
+}
+```
+
+## Package metadata
+
+Declare the plugin in `package.json#openforge` and publish every built file named by the metadata:
 
 ```json
 {
+  "name": "@acme/openforge-notes",
+  "version": "1.0.0",
+  "type": "module",
+  "files": ["dist"],
+  "dependencies": {
+    "@openforge-app/plugin-sdk": "latest"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
   "openforge": {
+    "id": "acme.notes",
+    "apiVersion": 1,
+    "displayName": "Notes",
+    "description": "Project notes",
+    "icon": "notebook-text",
     "frontend": "./dist/frontend.js",
-    "frontendStyles": ["./dist/plugin.css"]
+    "frontendStyles": ["./dist/plugin.css"],
+    "backend": "./dist/backend.mjs",
+    "requires": ["views", "storage", "backend"]
   }
 }
 ```
 
-The host validates, attaches, reloads, and removes these package-relative stylesheets with the frontend plugin lifecycle.
+`openforge.apiVersion` controls compatibility with the OpenForge host. It is separate from the npm package version. The current host contract uses API version `1`.
+
+OpenForge loads built artifacts from the installed package. It does not compile plugin source during installation.
+
+## Frontend entry point
+
+Use `@openforge-app/plugin-sdk/frontend` for renderer contributions such as views, task UI, settings, commands, and events:
+
+```ts
+import { defineFrontendPlugin } from '@openforge-app/plugin-sdk/frontend'
+
+export default defineFrontendPlugin({
+  activate(openforge, context) {
+    context.subscriptions.add(openforge.views.register({
+      id: 'notes',
+      title: 'Notes',
+      icon: 'notebook-text',
+      placement: 'rail',
+      component: () => import('./NotesView.svelte'),
+    }))
+  },
+})
+```
+
+Add every registration and cleanup handle to `context.subscriptions`. OpenForge disposes them when it deactivates or reloads the plugin.
+
+Task reads support project-filtered invalidation subscriptions. Notifications may be coalesced and contain identity plus a reason, not a Task snapshot. Repeat only the bounded read your view needs:
+
+```ts
+export default defineFrontendPlugin({
+  activate(openforge, context) {
+    const projectId = openforge.context.getSnapshot().projectId
+    if (!projectId) return
+
+    context.subscriptions.add(openforge.tasks.onDidChange(projectId, (event) => {
+      const refresh = event.taskId
+        ? openforge.tasks.detail(event.projectId, event.taskId)
+        : openforge.tasks.active(event.projectId)
+      void refresh.then((result) => {
+        // Update plugin-owned state from the bounded result.
+      }).catch(console.error)
+    }))
+  },
+})
+```
+
+The reason is one of `created`, `updated`, `completed`, `attention`, or `execution`. Add the returned disposable to `context.subscriptions`; explicit disposal, deactivation, reload, and uninstall then stop delivery.
+
+Frontend bundles must share Svelte with the host. Use the SDK's Vite external helper:
+
+```ts
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+import { openforgePluginViteExternals } from '@openforge-app/plugin-sdk/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [svelte()],
+  build: {
+    lib: {
+      entry: 'src/frontend.ts',
+      formats: ['es'],
+      fileName: 'frontend',
+    },
+    rollupOptions: {
+      external: openforgePluginViteExternals,
+    },
+  },
+})
+```
+
+Svelte library builds emit CSS separately. List each emitted CSS file in `openforge.frontendStyles`; otherwise OpenForge will not load it.
+
+## Backend entry point
+
+Use `@openforge-app/plugin-sdk/backend` for Node dependencies, plugin-local RPC methods, and background services:
+
+```ts
+import { defineBackendPlugin } from '@openforge-app/plugin-sdk/backend'
+
+export default defineBackendPlugin({
+  activate(openforge, context) {
+    context.subscriptions.add(openforge.backend.registerMethod('ping', {
+      input: { type: 'object', additionalProperties: false },
+      output: {
+        type: 'object',
+        required: ['ok'],
+        properties: { ok: { type: 'boolean' } },
+      },
+      handler: async () => ({ ok: true }),
+    }))
+  },
+})
+```
+
+Backend plugins run in the trusted Node plugin host. They cannot register Svelte views, task UI, settings sections, or frontend navigation.
+
+## Testing
+
+`@openforge-app/plugin-sdk/testing` provides mock APIs and a registry fake for registration, capability, storage, and cleanup tests:
+
+```ts
+import { describe, expect, it } from 'vitest'
+import { createOpenForgeRegistryFake } from '@openforge-app/plugin-sdk/testing'
+import plugin from '../src/frontend'
+
+describe('frontend plugin', () => {
+  it('registers its view', async () => {
+    const registry = createOpenForgeRegistryFake({
+      pluginId: 'acme.notes',
+      projectId: 'P-1',
+    })
+
+    await registry.activateFrontend(plugin)
+
+    expect(registry.snapshot.views).toMatchObject([
+      { id: 'notes', qualifiedId: 'acme.notes.notes', title: 'Notes' },
+    ])
+  })
+})
+```
+
+Use `registry.emitTaskChange(...)` to drive invalidation behavior without importing host events or renderer stores:
+
+```ts
+registry.emitTaskChange({
+  projectId: 'P-1',
+  taskId: 'T-42',
+  reason: 'updated',
+})
+```
+
+## Public entry points
+
+The package exports these modules:
+
+| Import | Purpose |
+| --- | --- |
+| `@openforge-app/plugin-sdk` | Shared types, metadata validation, constants, and domain helpers |
+| `@openforge-app/plugin-sdk/frontend` | Frontend plugin definition and renderer types |
+| `@openforge-app/plugin-sdk/backend` | Backend plugin definition and Node-host types |
+| `@openforge-app/plugin-sdk/testing` | Mock APIs, storage, subscriptions, and registry fakes |
+| `@openforge-app/plugin-sdk/vite` | Host-runtime externals for plugin builds |
+| `@openforge-app/plugin-sdk/package-metadata-schema.json` | JSON Schema for `package.json#openforge` |
+| `@openforge-app/plugin-sdk/domain` | Shared OpenForge domain types |
+| `@openforge-app/plugin-sdk/prStatusPresentation` | Pull request status presentation helpers |
+| `@openforge-app/plugin-sdk/markdown` | Markdown rendering helpers |
+| `@openforge-app/plugin-sdk/numberParsing` | Numeric parsing helpers |
+| `@openforge-app/plugin-sdk/projectFileTree` | Project file tree helpers |
+| `@openforge-app/plugin-sdk/sanitize` | HTML and SVG sanitization helpers |
+| `@openforge-app/plugin-sdk/pluginIcons` | Plugin icon validation and sanitization |
+| `@openforge-app/plugin-sdk/fileIcons` | File-type icon lookup helpers |
+| `@openforge-app/plugin-sdk/collapsibleSectionState` | Persisted collapse-state helpers |
+| `@openforge-app/plugin-sdk/taskBrowserDevToolsShortcuts` | Task Browser DevTools shortcut helpers |
+
+Shared Svelte components use explicit imports. The package exports:
+
+- `@openforge-app/plugin-sdk/ui/Button.svelte`
+- `@openforge-app/plugin-sdk/ui/Checkbox.svelte`
+- `@openforge-app/plugin-sdk/ui/CollapsibleSection.svelte`
+- `@openforge-app/plugin-sdk/ui/FileTypeIcon.svelte`
+- `@openforge-app/plugin-sdk/ui/MarkdownContent.svelte`
+- `@openforge-app/plugin-sdk/ui/Modal.svelte`
+- `@openforge-app/plugin-sdk/ui/PluginPageHeader.svelte`
+- `@openforge-app/plugin-sdk/ui/PluginPageShell.svelte`
+- `@openforge-app/plugin-sdk/ui/PluginSidebarLink.svelte`
+- `@openforge-app/plugin-sdk/ui/PluginViewState.svelte`
+- `@openforge-app/plugin-sdk/ui/ProjectFileTree.svelte`
+- `@openforge-app/plugin-sdk/ui/ResizablePanel.svelte`
+Use only documented package exports. Do not import OpenForge renderer stores, Electron or preload APIs, Rust internals, app IPC wrappers, or files under this package's `src/` directory.
+
+## Documentation
 
-## Publishing
+- [Plugin authoring guide](https://github.com/koenvg/openforge/blob/main/docs/plugin-authoring.md)
+- [SDK reference](https://github.com/koenvg/openforge/blob/main/docs/plugins/sdk-reference.md)
 
-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.
+The authoring guide documents package metadata, capabilities, frontend and backend runtime boundaries, storage, task APIs, browser surfaces, and CSS loading. The SDK reference lists the public types and shared UI components.
 
 ## 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.
+The SDK is available under the [MIT License](./LICENSE). Plugins may use, modify, and redistribute it under those terms, including in commercial and private plugins.
 
-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.
+The OpenForge desktop application has a separate license. The SDK license does not grant permission to commercially resell or redistribute the app.

package/dist/domain.d.ts

@@ -14,8 +14,10 @@ export type WritableBoardStatus = Exclude<BoardStatus, 'done'>;
 export type WorktreeSource = 'newBranchFromMain' | 'existingBranch' | 'disabled';
 export interface Task {
     id: string;
+    /** @deprecated Use `TaskDetail.prompt` in the bounded Task read APIs. */
     initial_prompt: string;
     status: BoardStatus;
+    /** @deprecated Legacy execution override retained for API version 1 compatibility. */
     prompt: string | null;
     /** Explicit display title; null means fall back to the prompt-derived title. */
     title: string | null;
@@ -37,6 +39,53 @@ export interface Task {
     created_at: number;
     updated_at: number;
 }
+export interface TaskLabel {
+    id: number;
+    projectId: string;
+    name: string;
+}
+export interface TaskReference {
+    id: string;
+    status: BoardStatus;
+    projectId: string;
+    title: string;
+    dependsOn: string[];
+}
+export interface TaskSummary extends TaskReference {
+    createdAt: number;
+    updatedAt: number;
+    promptPreview: string;
+    labels: TaskLabel[];
+    sourceTicketUrl: string | null;
+}
+export interface TaskDetail extends TaskSummary {
+    prompt: string;
+    agent: string | null;
+    permissionMode: string | null;
+    worktreeSource: WorktreeSource | null;
+    worktreeBranch: string | null;
+    titleSource: 'manual' | 'generated' | null;
+    titleGeneratedAt: number | null;
+}
+export interface ActiveTasks {
+    tasks: TaskDetail[];
+    related: TaskReference[];
+}
+export interface CompletedTaskQuery {
+    /** At most 200 Unicode characters. ASCII case-insensitive; non-ASCII casing is exact. */
+    search?: string;
+    /** At most 20 Task Label names; each trimmed name is at most 40 Unicode characters. */
+    labels?: string[];
+    cursor?: string | null;
+}
+export interface CompletedTaskPage {
+    tasks: TaskSummary[];
+    nextCursor: string | null;
+}
+export interface TaskRead {
+    task: TaskDetail;
+    related: TaskReference[];
+}
 export interface GitBranchInfo {
     name: string;
     is_current: boolean;
@@ -601,7 +650,7 @@ export interface FileEntry {
 }
 /** File content with type information */
 export interface FileContent {
-    type: 'text' | 'image' | 'binary' | 'document' | 'large-file';
+    type: 'text' | 'image' | 'video' | 'binary' | 'document' | 'large-file';
     content: string;
     mimeType: string | null;
     size: number;

package/dist/fileIcons.js

@@ -35,6 +35,7 @@ const EXTENSION_ICONS = {
     svg: 'svg',
     png: 'image', jpg: 'image', jpeg: 'image', gif: 'image',
     webp: 'image', bmp: 'image', ico: 'image', avif: 'image',
+    mp4: 'video', m4v: 'video', webm: 'video', ogv: 'video', ogg: 'video', mov: 'video',
     pdf: 'pdf',
     zip: 'zip', tar: 'zip', gz: 'zip', tgz: 'zip', rar: 'zip', '7z': 'zip',
     lock: 'lock',

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSur
 export { OPENFORGE_PACKAGE_METADATA_SCHEMA, OPENFORGE_PLUGIN_CAPABILITIES, isOpenForgePackageMetadata, isPluginPackageMetadata, isSupportedOpenForgeApiVersion, validateOpenForgePackageMetadata, validatePluginPackageMetadata, } from './manifest';
 export { createMemoryPluginStorage, createMockBackendOpenForgeApi, createMockFrontendOpenForgeApi, createMockOpenForgeApi, createMockPluginContext, createOpenForgeRegistryFake, createTestingCalls, TestingOpenForgeRegistryFake, TestingSubscriptionSink, } from './testing';
 export { MAX_AGENT_SESSION_PAGE_SIZE, DEFAULT_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES, MAX_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES, MIN_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES, TaskFollowUpError, MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, resolveExternalTextFileChunkSize, makePluginViewKey, parsePluginViewKey, } from './types';
-export type { AgentSessionCursor, AgentSessionOverlap, AgentSessionsAPI, AgentSessionSummary, AgentSessionSummaryPage, AgentSessionTaskSummary, AgentSessionWorkspace, AgentCommandDescriptor, AgentCommandMetadata, AgentCommandRuntime, AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, BackendFileSystemAPI, ExternalFileMetadata, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadTextFileChunksRequest, ExternalReadFileSystemAPI, FileSystemAPI, UserDataDirectoryRequest, UserDataFileAppendResult, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, ImplementationRun, ListAgentSessionsRequest, ListTaskSessionsRequest, InjectionPointLocation, JsonObject, JsonPrimitive, JsonSchema, JsonValue, MaybePromise, KeyValueConfigAPI, NotificationRequest, NavigationAPI, NotificationsAPI, OpenForgeCommonAPI, OpenForgeContextChangeHandler, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, OpenForgePluginCapability, OpenForgePluginContext, OpenForgePluginPackageJson, PluginCommandInvocationContext, PluginCommandInvocationSource, PluginComponentLoader, PluginComponentModule, PluginEntry, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginSettingsSectionProps, PluginState, PluginSvgIcon, PluginTaskPaneProps, PluginTaskUISectionProps, PluginViewProps, PluginStorage, PluginStorageScope, PluginViewKey, ProjectsAPI, PtyBufferState, ShellAPI, ShellResizeRequest, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol, TerminalViewSnapshot, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskFollowUpDisposition, TaskFollowUpErrorCode, TaskFollowUpReceipt, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TasksAPI, ValidationError, } from './types';
+export type { AgentSessionCursor, AgentSessionOverlap, AgentSessionsAPI, AgentSessionSummary, AgentSessionSummaryPage, AgentSessionTaskSummary, AgentSessionWorkspace, AgentCommandDescriptor, AgentCommandMetadata, AgentCommandRuntime, AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, BackendFileSystemAPI, ExternalFileMetadata, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadTextFileChunksRequest, ExternalReadFileSystemAPI, FileSystemAPI, UserDataDirectoryRequest, UserDataFileAppendResult, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, ImplementationRun, ListAgentSessionsRequest, ListTaskSessionsRequest, InjectionPointLocation, JsonObject, JsonPrimitive, JsonSchema, JsonValue, MaybePromise, KeyValueConfigAPI, NotificationRequest, NavigationAPI, NotificationsAPI, OpenForgeCommonAPI, OpenForgeContextChangeHandler, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, OpenForgePluginCapability, OpenForgePluginContext, OpenForgePluginPackageJson, PluginCommandInvocationContext, PluginCommandInvocationSource, PluginComponentLoader, PluginComponentModule, PluginEntry, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginSettingsSectionProps, PluginState, PluginSvgIcon, PluginTaskPaneProps, PluginTaskUISectionProps, PluginViewProps, PluginStorage, PluginStorageScope, PluginViewKey, ProjectsAPI, PtyBufferState, ShellAPI, ShellResizeRequest, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol, TerminalViewSnapshot, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskFollowUpDisposition, TaskFollowUpErrorCode, TaskFollowUpReceipt, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TaskChangeEvent, TaskChangeReason, TaskOperationsAPI, TasksAPI, ValidationError, } from './types';
 export type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingBackgroundServiceContribution, TestingBackendMethodContribution, TestingCommandContribution, TestingContributionBase, TestingExternalTextFile, TestingExternalTextFileChunksCall, TestingEventListenerContribution, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot, TestingRuntimeKind, TestingRuntimeScope, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingTaskUISectionContribution, TestingViewContribution, } from './testing';
 export { parseStrictFiniteNumber } from './numberParsing';
 export { buildProjectFileTree, flattenVisibleProjectFileTree, formatProjectFileTreeSize, getProjectFileTreeDepth, getProjectFileTreeItemAccessibility, getProjectFileTreeKeyboardAction, getProjectFileTreeParentPath, hasProjectFileTreeShortcutModifier, projectFileTreePathToId, } from './projectFileTree';

package/dist/markdown.js

@@ -1,10 +1,16 @@
-import { marked } from 'marked';
+import { marked, Renderer } from 'marked';
 import { sanitizeHtml } from './sanitize';
 /** Attribute holding the original URL of a `<img>`/`<a>` awaiting resolution. */
 export const MARKDOWN_REMOTE_MEDIA_ATTRIBUTE = 'data-markdown-remote-src';
+class MarkdownRenderer extends Renderer {
+    table(token) {
+        return `<div class="markdown-table-scroll">${super.table(token)}</div>`;
+    }
+}
 const markedOptions = {
     gfm: true,
     breaks: true,
+    renderer: new MarkdownRenderer(),
 };
 const RENDERED_MARKDOWN_CACHE_CAPACITY = 100;
 const renderedMarkdownCache = new Map();

package/dist/testing/commonApiFake.d.ts

@@ -1,14 +1,16 @@
-import type { BackendOpenForgeAPI, FrontendOpenForgeAPI, OpenForgeCommonAPI } from '../types';
+import type { BackendOpenForgeAPI, FrontendOpenForgeAPI, TaskChangeEvent, OpenForgeCommonAPI } from '../types';
 import { type TestingRegistryServices } from './support.js';
 import type { TestingCommandContribution, TestingEventListenerContribution } from './contracts';
-export type TestingCommonApi = OpenForgeCommonAPI & Pick<FrontendOpenForgeAPI, 'navigation'>;
+export type TestingCommonApi = Omit<OpenForgeCommonAPI, 'tasks'> & Pick<FrontendOpenForgeAPI, 'tasks' | 'navigation'>;
 export declare class TestingCommonApiFake {
     private readonly services;
     private readonly commands;
     private readonly eventListeners;
     private readonly eventHandlers;
+    private readonly taskChangeHandlers;
     private eventListenerSequence;
     constructor(services: TestingRegistryServices);
+    emitTaskChange(event: TaskChangeEvent): void;
     createApi(): TestingCommonApi;
     createBackendApi(): TestingCommonApi & Pick<BackendOpenForgeAPI, 'fs'>;
     getSnapshot(): {

package/dist/testing/commonApiFake.js

@@ -115,15 +115,172 @@ function* splitExternalTextFile(content, maxBytes) {
     if (chunk.length > 0)
         yield chunk;
 }
+function isTestingImageReferenceDefinition(line) {
+    const separator = line.indexOf(':');
+    if (separator < 0)
+        return false;
+    const marker = line.slice(0, separator);
+    const value = line.slice(separator + 1);
+    const imageNumber = marker.startsWith('[image#') && marker.endsWith(']')
+        ? marker.slice('[image#'.length, -1)
+        : null;
+    return imageNumber !== null
+        && imageNumber.length > 0
+        && /^\d+$/u.test(imageNumber)
+        && value.trimStart().startsWith('data:image/')
+        && value.includes(';base64,');
+}
+function testingTaskPromptPreview(task) {
+    const lines = task.initial_prompt
+        .split(/\r?\n/u)
+        .filter(line => !isTestingImageReferenceDefinition(line));
+    while (lines.at(-1)?.trim() === '')
+        lines.pop();
+    return [...lines.join('\n')].slice(0, 120).join('');
+}
+function testingTaskTitle(task, preview) {
+    const explicitTitle = task.title?.trim();
+    if (explicitTitle)
+        return explicitTitle;
+    const fallback = preview.split(/\r?\n/u).map(line => line.trim()).find(Boolean) || task.id;
+    return [...fallback].slice(0, 120).join('');
+}
+function taskReference(task) {
+    const preview = testingTaskPromptPreview(task);
+    if (!task.project_id)
+        throw new Error(`Task ${task.id} must belong to a project`);
+    return {
+        id: task.id,
+        status: task.status,
+        projectId: task.project_id,
+        title: testingTaskTitle(task, preview),
+        dependsOn: [...task.depends_on],
+    };
+}
+function taskSummary(task, labels = []) {
+    return {
+        ...taskReference(task),
+        createdAt: task.created_at,
+        updatedAt: task.updated_at,
+        promptPreview: testingTaskPromptPreview(task),
+        labels: [...labels],
+        sourceTicketUrl: task.source_ticket_url,
+    };
+}
+function taskDetail(task, labels = []) {
+    return {
+        ...taskSummary(task, labels),
+        prompt: task.initial_prompt,
+        agent: task.agent,
+        permissionMode: task.permission_mode,
+        worktreeSource: task.worktree_source,
+        worktreeBranch: task.worktree_branch,
+        titleSource: task.title_source,
+        titleGeneratedAt: task.title_generated_at,
+    };
+}
+function asciiLowercase(value) {
+    return value.replace(/[A-Z]/gu, character => character.toLowerCase());
+}
+function compareCompletedTasks(left, right) {
+    if (left.updated_at !== right.updated_at)
+        return right.updated_at - left.updated_at;
+    if (left.id === right.id)
+        return 0;
+    return left.id > right.id ? -1 : 1;
+}
+function testingCompletedTaskScope(projectId, query) {
+    return {
+        projectId,
+        search: asciiLowercase(query.search?.trim() ?? ''),
+        labels: [...new Set((query.labels ?? [])
+                .map(name => name.trim().toLowerCase())
+                .filter(Boolean))].sort(),
+    };
+}
+function encodeTestingCompletedTaskCursor(cursor) {
+    return `testing:${encodeURIComponent(JSON.stringify(cursor))}`;
+}
+function decodeTestingCompletedTaskCursor(encoded, scope) {
+    try {
+        if (!encoded.startsWith('testing:'))
+            throw new Error('wrong cursor format');
+        const cursor = JSON.parse(decodeURIComponent(encoded.slice('testing:'.length)));
+        if (cursor.version !== 1
+            || !Number.isSafeInteger(cursor.updatedAt)
+            || typeof cursor.id !== 'string'
+            || JSON.stringify(cursor.scope) !== JSON.stringify(scope)) {
+            throw new Error('invalid cursor payload');
+        }
+        return cursor;
+    }
+    catch {
+        throw new Error('Invalid Task cursor');
+    }
+}
+function listTestingCompletedTasks(allTasks, projectId, query = {}, labelsByTaskId = new Map()) {
+    if (!projectId.trim())
+        throw new RangeError('projectId is required');
+    const submittedLabels = query.labels ?? [];
+    if (submittedLabels.length > 20) {
+        throw new RangeError('Completed Task reads support at most 20 Task Label filters');
+    }
+    if (submittedLabels.some(name => [...name.trim()].length > 40)) {
+        throw new RangeError('Completed Task Label filters must be 40 characters or fewer');
+    }
+    if ([...(query.search?.trim() ?? '')].length > 200) {
+        throw new RangeError('Completed Task search must be 200 characters or fewer');
+    }
+    const scope = testingCompletedTaskScope(projectId, query);
+    const labels = new Set(scope.labels);
+    const cursor = query.cursor ? decodeTestingCompletedTaskCursor(query.cursor, scope) : null;
+    const matching = allTasks
+        .filter(task => task.status === 'done' && task.project_id === projectId)
+        .filter(task => {
+        const summary = taskSummary(task, labelsByTaskId.get(task.id));
+        return !scope.search || [summary.id, summary.title, summary.promptPreview]
+            .some(value => asciiLowercase(value).includes(scope.search));
+    })
+        .filter(task => {
+        if (labels.size === 0)
+            return true;
+        const names = taskSummary(task, labelsByTaskId.get(task.id))
+            .labels.map(label => label.name.toLowerCase());
+        return [...labels].every(label => names.includes(label));
+    })
+        .sort(compareCompletedTasks);
+    const remaining = cursor
+        ? matching.filter(task => task.updated_at < cursor.updatedAt
+            || (task.updated_at === cursor.updatedAt && task.id < cursor.id))
+        : matching;
+    const pageTasks = remaining.slice(0, 50);
+    const tasks = pageTasks.map(task => taskSummary(task, labelsByTaskId.get(task.id)));
+    const last = pageTasks.at(-1);
+    const nextCursor = remaining.length > 50 && last
+        ? encodeTestingCompletedTaskCursor({
+            version: 1,
+            scope,
+            updatedAt: last.updated_at,
+            id: last.id,
+        })
+        : null;
+    return { tasks, nextCursor };
+}
 export class TestingCommonApiFake {
     services;
     commands = new Map();
     eventListeners = new Map();
     eventHandlers = new Map();
+    taskChangeHandlers = new Map();
     eventListenerSequence = 0;
     constructor(services) {
         this.services = services;
     }
+    emitTaskChange(event) {
+        for (const handler of this.taskChangeHandlers.get(event.projectId) ?? []) {
+            handler(event);
+        }
+    }
     createApi() {
         const api = {
             commands: {
@@ -238,6 +395,16 @@ export class TestingCommonApiFake {
                 },
             },
             tasks: {
+                onDidChange: (projectId, handler) => {
+                    const handlers = this.taskChangeHandlers.get(projectId) ?? new Set();
+                    handlers.add(handler);
+                    this.taskChangeHandlers.set(projectId, handlers);
+                    return createDisposable(() => {
+                        handlers.delete(handler);
+                        if (handlers.size === 0)
+                            this.taskChangeHandlers.delete(projectId);
+                    });
+                },
                 list: async (request) => {
                     const projectId = request?.projectId ?? null;
                     const includeDone = request?.includeDone ?? false;
@@ -245,12 +412,54 @@ export class TestingCommonApiFake {
                     return this.services.seededTasks.filter((task) => {
                         if (projectId !== null && task.project_id !== projectId)
                             return false;
-                        if (!includeDone && task.status === 'done')
+                        if (projectId !== null && !includeDone && task.status === 'done')
                             return false;
                         return true;
                     });
                 },
-                get: async () => null,
+                get: async (taskId) => this.services.seededTasks.find(task => task.id === taskId) ?? null,
+                active: async (projectId) => {
+                    this.services.calls.taskActiveRequests.push({ projectId });
+                    const activeTasks = this.services.seededTasks.filter(task => task.project_id === projectId && task.status !== 'done');
+                    const activeIds = new Set(activeTasks.map(task => task.id));
+                    const relatedIds = new Set();
+                    for (const task of this.services.seededTasks) {
+                        if (activeIds.has(task.id)) {
+                            for (const dependencyId of task.depends_on)
+                                relatedIds.add(dependencyId);
+                        }
+                        else if (task.depends_on.some(dependencyId => activeIds.has(dependencyId))) {
+                            relatedIds.add(task.id);
+                        }
+                    }
+                    return {
+                        tasks: activeTasks.map(task => taskDetail(task, this.services.seededTaskLabelAssignments.get(task.id))),
+                        related: this.services.seededTasks
+                            .filter(task => relatedIds.has(task.id) && !activeIds.has(task.id))
+                            .map(taskReference),
+                    };
+                },
+                completed: async (projectId, query = {}) => {
+                    this.services.calls.taskCompletedRequests.push({ projectId, ...query });
+                    return listTestingCompletedTasks(this.services.seededTasks, projectId, query, this.services.seededTaskLabelAssignments);
+                },
+                detail: async (projectId, taskId) => {
+                    this.services.calls.taskDetailRequests.push({ projectId, taskId });
+                    const task = this.services.seededTasks.find(candidate => candidate.id === taskId && candidate.project_id === projectId);
+                    if (!task)
+                        return null;
+                    const relatedIds = new Set(task.depends_on);
+                    for (const candidate of this.services.seededTasks) {
+                        if (candidate.depends_on.includes(taskId))
+                            relatedIds.add(candidate.id);
+                    }
+                    return {
+                        task: taskDetail(task, this.services.seededTaskLabelAssignments.get(task.id)),
+                        related: this.services.seededTasks
+                            .filter(candidate => relatedIds.has(candidate.id))
+                            .map(taskReference),
+                    };
+                },
                 create: async (request) => {
                     this.services.calls.taskCreations.push(request);
                     return {
@@ -334,7 +543,8 @@ export class TestingCommonApiFake {
             },
             fs: {
                 readDir: async () => [],
-                readFile: async () => ({ type: 'text', content: '', mimeType: null, size: 0 }),
+                readFile: async ({ path }) => this.services.projectFileContents[path]
+                    ?? { type: 'text', content: '', mimeType: null, size: 0 },
                 writeFile: async (request) => {
                     this.services.calls.fsWrites.push(request);
                 },

package/dist/testing/contracts.d.ts

@@ -1,7 +1,8 @@
 import type { BrowserSurfaceVisualFeedback } from '../browserSurfaces';
+import type { CompletedTaskQuery } from '../domain';
 import type { TestingOpenForgeRegistryFake } from './registryFake';
 import type { BackendMethodRegistration, BackendOpenForgeAPI, BackgroundServiceRegistration, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ConfigureStartPromptContributionRequest, CreateTaskRequest, FrontendOpenForgeAPI, InjectionPointLocation, AgentSessionWorkspace, ListAgentSessionsRequest, ListTaskSessionsRequest, JsonValue, NotificationRequest, OpenForgeNavigationRequest, OpenForgePackageMetadata, PluginSettingsSectionRegistration, PluginStorage, PluginTaskPaneTabRegistration, PluginReviewRowActionRegistration, PluginTaskUISectionRegistration, PluginViewRegistration, ShellSpawnRequest, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskStartPrefixContext, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadTextFileChunksRequest, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileWriteRequest } from '../types';
-import type { AgentSession, Task } from '../domain';
+import type { AgentSession, FileContent, Task, TaskLabel } from '../domain';
 export type TestingRuntimeScope = 'global' | 'project' | 'task';
 export type TestingRuntimeKind = 'commands' | 'events' | 'views' | 'taskPane' | 'taskUI' | 'reviewUI' | 'settings' | 'backend' | 'background';
 export type TestingMaybePromise<T> = T | Promise<T>;
@@ -16,6 +17,10 @@ export interface TestingExternalTextFile extends ExternalReadFileRequest {
 export type TestingExternalTextFileChunksCall = Omit<ExternalReadTextFileChunksRequest, 'signal' | 'chunkSizeBytes'> & {
     chunkSizeBytes: number;
 };
+export interface TestingTaskLabelAssignment {
+    taskId: string;
+    labels: TaskLabel[];
+}
 export interface TestingOpenForgeApiOptions {
     pluginId?: string;
     projectId?: string | null;
@@ -26,12 +31,16 @@ export interface TestingOpenForgeApiOptions {
     storage?: PluginStorage;
     /** Initial files exposed through `fs.userData`. Defaults to none. */
     userDataTextFiles?: UserDataFileWriteRequest[];
+    /** File contents returned by `fs.readFile`, keyed by project-relative path. */
+    projectFileContents?: Readonly<Record<string, FileContent>>;
     /**
      * Tasks returned by `tasks.list`. The mock filters them by the requested
      * `projectId` (when given) and drops `done` tasks unless `includeDone: true`,
      * mirroring the host capability. Defaults to an empty list.
      */
     tasks?: Task[];
+    /** Task Label assignments used by canonical Task projections. */
+    taskLabelAssignments?: TestingTaskLabelAssignment[];
     /** Agent Sessions returned by `tasks.listSessions`. Defaults to an empty list. */
     agentSessions?: AgentSession[];
     /** Compact workspace context keyed by Task ID for `agentSessions.list`. Defaults to none. */
@@ -76,6 +85,16 @@ export interface TestingOpenForgeApiCalls {
         projectId: string | null;
         includeDone: boolean;
     }>;
+    taskActiveRequests: Array<{
+        projectId: string;
+    }>;
+    taskCompletedRequests: Array<{
+        projectId: string;
+    } & CompletedTaskQuery>;
+    taskDetailRequests: Array<{
+        projectId: string;
+        taskId: string;
+    }>;
     agentSessionListRequests: ListAgentSessionsRequest[];
     taskSessionListRequests: ListTaskSessionsRequest[];
     taskStatusUpdates: Array<{

package/dist/testing/registryFake.d.ts

@@ -1,5 +1,5 @@
 import type { TaskBrowserSurfaceState } from '../browserSurfaces';
-import type { BackendPlugin, BackendPluginContext, FrontendPlugin, FrontendPluginContext, OpenForgePackageMetadata, PluginStorage } from '../types';
+import type { BackendPlugin, BackendPluginContext, FrontendPlugin, FrontendPluginContext, OpenForgePackageMetadata, TaskChangeEvent, PluginStorage } from '../types';
 import type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot } from './contracts';
 import { TestingSubscriptionSink } from './support.js';
 export declare class TestingOpenForgeRegistryFake {
@@ -28,6 +28,7 @@ export declare class TestingOpenForgeRegistryFake {
     createBackendContext(): BackendPluginContext;
     activateFrontend(plugin: FrontendPlugin): Promise<void>;
     activateBackend(plugin: BackendPlugin): Promise<void>;
+    emitTaskChange(event: TaskChangeEvent): void;
     setBrowserSurfaceState(taskId: string, id: string, patch: Partial<TaskBrowserSurfaceState>): void;
     disposeAll(): Promise<void>;
     getSnapshot(): TestingOpenForgeRegistrySnapshot;

package/dist/testing/registryFake.js

@@ -82,6 +82,9 @@ export class TestingOpenForgeRegistryFake {
         await plugin.activate(this.backendApi, this.createBackendContext());
         await this.backendServices.startNewBackgroundServices(existingServices);
     }
+    emitTaskChange(event) {
+        this.commonApi.emitTaskChange(event);
+    }
     setBrowserSurfaceState(taskId, id, patch) {
         this.frontendContributions.setBrowserSurfaceState(taskId, id, patch);
     }

package/dist/testing/support.d.ts

@@ -1,5 +1,5 @@
 import type { AgentSessionWorkspace, AgentCommandMetadata, CommandDescriptor, Disposable, JsonValue, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, PluginStorage, StartPromptContribution, SubscriptionSink } from '../types';
-import type { AgentSession, Task } from '../domain';
+import type { AgentSession, FileContent, Task, TaskLabel } from '../domain';
 import type { TestingCommandContribution, TestingMaybePromise, TestingExternalTextFile, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingRuntimeKind } from './contracts';
 export declare function createDisposable(dispose: () => TestingMaybePromise<void>): Disposable;
 export declare class TestingSubscriptionSink implements SubscriptionSink {
@@ -31,10 +31,12 @@ export declare class TestingRegistryServices {
     readonly storage: PluginStorage;
     readonly config: Map<string, JsonValue>;
     readonly seededTasks: Task[];
+    readonly seededTaskLabelAssignments: Map<string, TaskLabel[]>;
     readonly seededAgentSessions: AgentSession[];
     readonly agentSessionWorkspaces: Readonly<Record<string, AgentSessionWorkspace>>;
     readonly externalTextFiles: TestingExternalTextFile[];
     readonly userDataTextFiles: Map<string, string>;
+    readonly projectFileContents: Readonly<Record<string, FileContent>>;
     readonly claims: TestingContributionClaims;
     constructor(options?: TestingOpenForgeApiOptions);
     localQualifiedId(kind: TestingRuntimeKind, id: string): string;

package/dist/testing/support.js

@@ -44,6 +44,9 @@ export function createTestingCalls() {
         taskImplementationStarts: [],
         taskFollowUps: [],
         taskListRequests: [],
+        taskActiveRequests: [],
+        taskCompletedRequests: [],
+        taskDetailRequests: [],
         agentSessionListRequests: [],
         taskSessionListRequests: [],
         taskStatusUpdates: [],
@@ -205,10 +208,12 @@ export class TestingRegistryServices {
     storage;
     config = new Map();
     seededTasks;
+    seededTaskLabelAssignments;
     seededAgentSessions;
     agentSessionWorkspaces;
     externalTextFiles;
     userDataTextFiles = new Map();
+    projectFileContents;
     claims = new TestingContributionClaims();
     constructor(options = {}) {
         this.pluginId = options.pluginId ?? 'test-plugin';
@@ -224,9 +229,11 @@ export class TestingRegistryServices {
         this.calls = createTestingCalls();
         this.storage = options.storage ?? createMemoryPluginStorage(this.calls);
         this.seededTasks = options.tasks ?? [];
+        this.seededTaskLabelAssignments = new Map((options.taskLabelAssignments ?? []).map(assignment => [assignment.taskId, assignment.labels]));
         this.seededAgentSessions = options.agentSessions ?? [];
         this.agentSessionWorkspaces = options.agentSessionWorkspaces ?? {};
         this.externalTextFiles = options.externalTextFiles ?? [];
+        this.projectFileContents = options.projectFileContents ?? {};
         for (const file of options.userDataTextFiles ?? []) {
             this.userDataTextFiles.set(file.path, file.content);
         }

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { Component } from 'svelte';
 import type { BrowserSurfacesAPI } from './browserSurfaces';
-import type { BoardStatus, AgentSession, CommandInfo, FileContent, FileEntry, Project, ProjectAttention, ReviewPullRequest, Task, TaskWorkspaceInfo, WorktreeSource, WritableBoardStatus } from './domain';
+import type { BoardStatus, AgentSession, CommandInfo, FileContent, FileEntry, Project, ProjectAttention, ActiveTasks, CompletedTaskPage, CompletedTaskQuery, TaskRead, TaskDetail, ReviewPullRequest, Task, TaskWorkspaceInfo, WorktreeSource, WritableBoardStatus } from './domain';
 export type SupportedOpenForgeApiVersion = 1;
 export declare const SUPPORTED_OPENFORGE_API_VERSIONS: readonly [1, ...1[]];
 export declare const OPENFORGE_PLUGIN_API_VERSION: SupportedOpenForgeApiVersion;
@@ -202,6 +202,7 @@ export interface PluginTaskPaneProps extends Record<string, unknown> {
     api: FrontendOpenForgeAPI;
     context: OpenForgeContextSnapshot;
     taskId: string;
+    task: TaskDetail;
     projectId: string | null;
 }
 export interface PluginTaskUISectionProps extends PluginTaskPaneProps {
@@ -609,19 +610,31 @@ export interface AgentSessionSummaryPage {
 export interface AgentSessionsAPI {
     list(request: ListAgentSessionsRequest): Promise<AgentSessionSummaryPage>;
 }
-export interface TasksAPI {
+export type TaskChangeReason = 'created' | 'updated' | 'completed' | 'attention' | 'execution';
+/**
+ * A coalescible signal that one or more bounded Task reads may now be stale.
+ * It never contains a Task snapshot.
+ */
+export interface TaskChangeEvent {
+    projectId: string;
+    taskId: string | null;
+    reason: TaskChangeReason;
+}
+export interface TaskOperationsAPI {
     /**
-     * Lists tasks, optionally scoped to a project. By default done tasks are
-     * excluded (matching the app board's active-only view); pass
-     * `includeDone: true` to include tasks in the terminal `done` state. The
-     * unscoped listing (no `projectId`) always returns all states, so
-     * `includeDone` only affects the project-scoped path.
+     * Lists legacy Task rows. Project-scoped reads exclude Completed Tasks unless
+     * `includeDone` is true; unscoped reads preserve the complete legacy array.
+     * @deprecated Use `active`, `completed`, or `detail`. Removed in version 2.
      */
     list(request?: {
         projectId?: string | null;
         includeDone?: boolean;
     }): Promise<Task[]>;
+    /** @deprecated Use `detail`. Removed in version 2. */
     get(taskId: string): Promise<Task | null>;
+    active(projectId: string): Promise<ActiveTasks>;
+    completed(projectId: string, query?: CompletedTaskQuery): Promise<CompletedTaskPage>;
+    detail(projectId: string, taskId: string): Promise<TaskRead | null>;
     create(request: CreateTaskRequest): Promise<Task>;
     /**
      * Opens the host's create-task dialog pre-filled, letting the user edit the
@@ -642,6 +655,13 @@ export interface TasksAPI {
     /** Returns matching Agent Sessions newest first. */
     listSessions(request: ListTaskSessionsRequest): Promise<AgentSession[]>;
 }
+export interface TasksAPI extends TaskOperationsAPI {
+    /**
+     * Subscribes to coalescible Task invalidations for one Project.
+     * Repeat the relevant bounded read instead of treating events as snapshots.
+     */
+    onDidChange(projectId: string, handler: (event: TaskChangeEvent) => void): Disposable;
+}
 export interface ProjectsAPI {
     list(): Promise<Project[]>;
     get(projectId: string): Promise<Project | null>;
@@ -673,7 +693,7 @@ export interface OpenForgeCommonAPI {
         getSnapshot(): OpenForgeContextSnapshot;
     };
     agentSessions: AgentSessionsAPI;
-    tasks: TasksAPI;
+    tasks: TaskOperationsAPI;
     projects: ProjectsAPI;
     fs: FileSystemAPI;
     shell: ShellAPI;
@@ -684,6 +704,7 @@ export interface OpenForgeCommonAPI {
     projectConfig: KeyValueConfigAPI;
 }
 export interface FrontendOpenForgeAPI extends OpenForgeCommonAPI {
+    tasks: TasksAPI;
     browserSurfaces: BrowserSurfacesAPI;
     navigation: NavigationAPI;
     views: FrontendViewRegistry;

package/dist/ui/PluginSidebarLink.svelte

@@ -23,17 +23,12 @@
     class: className,
   }: Props = $props()
 
-  function handleKeydown(event: KeyboardEvent): void {
-    if (event.key !== 'Enter' && event.key !== ' ') return
-    event.preventDefault()
-    onActivate()
-  }
 </script>
 
 <button
   type="button"
   class={[
-    'relative mx-2 flex min-h-11 w-auto items-center rounded-lg gap-3 py-2.5 cursor-pointer transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary',
+    'relative mx-2 flex min-h-11 w-[calc(100%_-_1rem)] items-center rounded-lg gap-3 py-2.5 cursor-pointer transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary',
     collapsed ? 'justify-center px-0' : 'px-3',
     active ? 'bg-primary/10 text-primary' : 'text-base-content/55 hover:bg-base-200 hover:text-base-content',
     className,
@@ -42,7 +37,6 @@
   aria-label={accessibleName}
   aria-current={active ? 'page' : undefined}
   onclick={onActivate}
-  onkeydown={handleKeydown}
 >
   {#if leading}
     <span class="relative shrink-0">{@render leading()}</span>

package/dist/ui/icons/video.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <path d="M24,6l2,6H22L20,6H17l2,6H15L13,6H10l2,6H8L6,6H5A3,3,0,0,0,2,9V23a3,3,0,0,0,3,3H27a3,3,0,0,0,3-3V6Z" style="fill: #ff9800"/>
+</svg>

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@openforge-app/plugin-sdk",
-  "version": "0.2.11",
+  "version": "0.3.0",
+  "description": "TypeScript SDK for building trusted OpenForge frontend and backend plugins.",
+  "homepage": "https://github.com/koenvg/openforge/blob/main/docs/plugin-authoring.md",
+  "keywords": [
+    "openforge",
+    "plugin",
+    "sdk",
+    "svelte"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",