@openforge-app/plugin-sdk 0.2.3 → 0.2.5

package/README.md

@@ -1,6 +1,6 @@
 # @openforge-app/plugin-sdk
 
-Public SDK for building OpenForge plugins. See [`docs/plugin-authoring.md`](../../docs/plugin-authoring.md) for the complete package, runtime, Svelte-sharing, and CSS-loading contract.
+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`:
 
@@ -24,9 +24,3 @@ Automated releases use npm trusted publishing rather than a long-lived npm token
 `@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.
-
-## Current contract
-
-Version `0.2.1` publishes the API-v1 contract used by the OpenForge host, including agent-facing Plugin Command metadata, `PluginCommandInvocationContext`, and the `@openforge-app/plugin-sdk/testing` helpers. Legacy handoff-summary declarations (`Task.summary` and `tasks.updateSummary`) are no longer part of the contract.
-
-Desktop releases publish the SDK in the same workflow using the desktop git tag's semver; the manual publish workflow uses the checked-in package version. Both paths run `pnpm check:contract`, which packs the package, verifies all exported files, and compiles the current authoring contract against the tarball before publication.

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, ExternalReadTextFileChunksRequest, ExternalReadFileSystemAPI, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, NavigationAPI, OpenForgeContextChangeHandler, 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, ExternalReadTextFileChunksRequest, ExternalReadFileSystemAPI, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, NavigationAPI, OpenForgeContextChangeHandler, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, };

package/dist/context.d.ts

@@ -1,4 +1,4 @@
-import type { Disposable, OpenForgePackageMetadata, OpenForgePluginContext, SubscriptionSink, SupportedOpenForgeApiVersion } from './types';
+import type { Disposable, OpenForgeContextChangeHandler, OpenForgePackageMetadata, OpenForgePluginContext, SubscriptionSink, SupportedOpenForgeApiVersion } from './types';
 declare class SubscriptionSet implements SubscriptionSink {
     private readonly subscriptions;
     add(subscription: Disposable | (() => void)): void;
@@ -9,6 +9,7 @@ export declare class PluginContextImpl implements OpenForgePluginContext {
     readonly apiVersion: SupportedOpenForgeApiVersion;
     readonly packageMetadata: OpenForgePackageMetadata;
     readonly subscriptions: SubscriptionSet;
+    onDidChange(_handler: OpenForgeContextChangeHandler): Disposable;
     constructor(pluginId: string, apiVersion: SupportedOpenForgeApiVersion, packageMetadata: OpenForgePackageMetadata);
 }
 export {};

package/dist/context.js

@@ -21,6 +21,9 @@ export class PluginContextImpl {
     apiVersion;
     packageMetadata;
     subscriptions;
+    onDidChange(_handler) {
+        return { dispose: () => undefined };
+    }
     constructor(pluginId, apiVersion, packageMetadata) {
         this.pluginId = pluginId;
         this.apiVersion = apiVersion;

package/dist/domain.d.ts

@@ -150,6 +150,7 @@ export interface PullRequestInfo {
     merge_queue_state: string | null;
     readiness_updated_at: number | null;
 }
+export type PollOutcome = 'completed' | 'missing_github_token' | 'github_token_unavailable' | 'failed' | 'rate_limited';
 export interface PollResult {
     new_comments: number;
     ci_changes: number;
@@ -158,6 +159,7 @@ export interface PollResult {
     errors: number;
     rate_limited: boolean;
     rate_limit_reset_at: number | null;
+    outcome: PollOutcome;
 }
 export interface MergeStatusInfo {
     state: string;

package/dist/frontend.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSurfaceVisualFeedback, BrowserSurfaceRegion, BrowserSurfaceErrorCode, BrowserSurfaceNavigationError, BrowserSurfacesAPI, GetOrCreateBrowserSurfaceRequest, TaskBrowserSurfaceController, TaskBrowserSurfaceState } from './browserSurfaces';
-import type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendInjectionPointRegistry, FrontendTaskStartRegistry, FrontendTaskUIRegistry, FrontendViewRegistry, InjectionPointLocation, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, PluginIcon, PluginInjectionPointProps, PluginInjectionPointRegistration, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsSectionScope, PluginStorageScope, PluginSvgIcon, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginTaskUISectionProps, PluginTaskUISectionRegistration, PluginViewProps, PluginViewRegistration, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol } from './types';
+import type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendInjectionPointRegistry, FrontendTaskStartRegistry, FrontendTaskUIRegistry, FrontendViewRegistry, InjectionPointLocation, NavigationAPI, OpenForgeContextChangeHandler, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginInjectionPointRegistration, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsSectionScope, PluginStorageScope, PluginSvgIcon, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginTaskUISectionProps, PluginTaskUISectionRegistration, PluginViewProps, PluginViewRegistration, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, PtyBufferState, TerminalImageProtocol } from './types';
 export declare const OPENFORGE_FRONTEND_PLUGIN_MARKER = "__openforgeFrontendPlugin";
 export type MarkedFrontendPlugin<TPlugin extends FrontendPlugin = FrontendPlugin> = TPlugin & {
     readonly [OPENFORGE_FRONTEND_PLUGIN_MARKER]: true;
@@ -7,4 +7,4 @@ export type MarkedFrontendPlugin<TPlugin extends FrontendPlugin = FrontendPlugin
 export declare function defineFrontendPlugin<const TPlugin extends FrontendPlugin>(plugin: TPlugin): MarkedFrontendPlugin<TPlugin>;
 export { BrowserSurfaceError, isAllowedBrowserSurfaceUrl } from './browserSurfaces';
 export type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSurfaceVisualFeedback, BrowserSurfaceRegion, BrowserSurfaceErrorCode, BrowserSurfaceNavigationError, BrowserSurfacesAPI, GetOrCreateBrowserSurfaceRequest, TaskBrowserSurfaceController, TaskBrowserSurfaceState, };
-export type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendInjectionPointRegistry, FrontendTaskStartRegistry, FrontendTaskUIRegistry, FrontendViewRegistry, InjectionPointLocation, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, PluginIcon, PluginInjectionPointProps, PluginInjectionPointRegistration, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsSectionScope, PluginStorageScope, PluginSvgIcon, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginTaskUISectionProps, PluginTaskUISectionRegistration, PluginViewProps, PluginViewRegistration, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol, };
+export type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendInjectionPointRegistry, FrontendTaskStartRegistry, FrontendTaskUIRegistry, FrontendViewRegistry, InjectionPointLocation, NavigationAPI, OpenForgeContextChangeHandler, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginInjectionPointRegistration, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsSectionScope, PluginStorageScope, PluginSvgIcon, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginTaskUISectionProps, PluginTaskUISectionRegistration, PluginViewProps, PluginViewRegistration, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, PtyBufferState, TerminalImageProtocol, };

package/dist/index.d.ts

@@ -2,9 +2,9 @@ export { BrowserSurfaceError, isAllowedBrowserSurfaceUrl } from './browserSurfac
 export type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSurfaceVisualFeedback, BrowserSurfaceRegion, BrowserSurfaceErrorCode, BrowserSurfaceNavigationError, BrowserSurfacesAPI, GetOrCreateBrowserSurfaceRequest, TaskBrowserSurfaceController, TaskBrowserSurfaceState, } from './browserSurfaces';
 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 { TaskFollowUpError, MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, makePluginViewKey, parsePluginViewKey, } from './types';
-export type { AgentCommandDescriptor, AgentCommandMetadata, AgentCommandRuntime, AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, FileSystemAPI, ImplementationRun, InjectionPointLocation, JsonObject, JsonPrimitive, JsonSchema, JsonValue, MaybePromise, KeyValueConfigAPI, NotificationRequest, NavigationAPI, NotificationsAPI, OpenForgeCommonAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, OpenForgePluginCapability, OpenForgePluginContext, OpenForgePluginPackageJson, PluginCommandInvocationContext, PluginCommandInvocationSource, PluginComponentLoader, PluginComponentModule, PluginEntry, PluginIcon, PluginInjectionPointProps, PluginSettingsSectionProps, PluginState, PluginSvgIcon, PluginTaskPaneProps, PluginTaskUISectionProps, PluginViewProps, PluginStorage, PluginStorageScope, PluginViewKey, ProjectsAPI, ShellAPI, ShellResizeRequest, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskFollowUpDisposition, TaskFollowUpErrorCode, TaskFollowUpReceipt, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, TasksAPI, ValidationError, } from './types';
-export type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingBackgroundServiceContribution, TestingBackendMethodContribution, TestingCommandContribution, TestingContributionBase, TestingEventListenerContribution, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot, TestingRuntimeKind, TestingRuntimeScope, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingTaskUISectionContribution, TestingViewContribution, } from './testing';
+export { 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 { AgentCommandDescriptor, AgentCommandMetadata, AgentCommandRuntime, AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, BackendFileSystemAPI, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadTextFileChunksRequest, ExternalReadFileSystemAPI, FileSystemAPI, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, ImplementationRun, 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, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskFollowUpDisposition, TaskFollowUpErrorCode, TaskFollowUpReceipt, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, 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';
 export type { ProjectFileTreeEntry, ProjectFileTreeItemAccessibility, ProjectFileTreeKeyboardAction, ProjectFileTreeNode, } from './projectFileTree';

package/dist/index.js

@@ -1,7 +1,7 @@
 export { BrowserSurfaceError, isAllowedBrowserSurfaceUrl } from './browserSurfaces';
 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 { TaskFollowUpError, MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, makePluginViewKey, parsePluginViewKey, } from './types';
+export { 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 { parseStrictFiniteNumber } from './numberParsing';
 export { buildProjectFileTree, flattenVisibleProjectFileTree, formatProjectFileTreeSize, getProjectFileTreeDepth, getProjectFileTreeItemAccessibility, getProjectFileTreeKeyboardAction, getProjectFileTreeParentPath, hasProjectFileTreeShortcutModifier, projectFileTreePathToId, } from './projectFileTree';
 export { canMergePullRequest, getMergeReadiness, hasMergeConflicts, isClosedUnmergedPullRequest, isMergedPullRequest, isQueuedForMerge, isReadyToMerge, parseCheckRuns, preservePullRequestState, splitCheckRuns, } from './domain';

package/dist/manifest.d.ts

@@ -11,7 +11,7 @@ export declare const OPENFORGE_PACKAGE_METADATA_SCHEMA: {
     dependentRequired: {
         frontendStyles: string[];
     };
-    allOf: {
+    allOf: ({
         if: {
             properties: {
                 requires: {
@@ -19,13 +19,35 @@ export declare const OPENFORGE_PACKAGE_METADATA_SCHEMA: {
                         const: string;
                     };
                 };
+                enablement?: undefined;
             };
             required: string[];
         };
         then: {
             required: string[];
+            properties?: undefined;
         };
-    }[];
+    } | {
+        if: {
+            properties: {
+                requires?: undefined;
+                enablement: {
+                    const: string;
+                };
+            };
+            required: string[];
+        };
+        then: {
+            properties: {
+                requires: {
+                    contains: {
+                        const: string;
+                    };
+                };
+            };
+            required: string[];
+        };
+    })[];
     properties: {
         id: {
             type: string;
@@ -44,9 +66,36 @@ export declare const OPENFORGE_PACKAGE_METADATA_SCHEMA: {
             type: string;
             minLength: number;
         };
+        enablement: {
+            enum: string[];
+            default: string;
+            description: string;
+        };
         icon: {
-            type: string;
-            minLength: number;
+            oneOf: ({
+                properties?: undefined;
+                type: string;
+                minLength: number;
+                pattern: string;
+                additionalProperties?: undefined;
+                required?: undefined;
+            } | {
+                minLength?: undefined;
+                pattern?: undefined;
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    type: {
+                        const: string;
+                    };
+                    svg: {
+                        type: string;
+                        minLength: number;
+                        pattern: string;
+                    };
+                };
+            })[];
             description: string;
         };
         frontend: {

package/dist/manifest.js

@@ -1,4 +1,5 @@
 import packageMetadataSchemaData from './openforgePackageMetadataSchema.json';
+import { isPluginIconName, isPluginSvgIcon } from './pluginIconContract';
 import { SUPPORTED_OPENFORGE_API_VERSIONS } from './types';
 export const OPENFORGE_PACKAGE_METADATA_SCHEMA = packageMetadataSchemaData;
 export const OPENFORGE_PLUGIN_CAPABILITIES = packageMetadataSchemaData.properties.requires.items.enum;
@@ -27,6 +28,18 @@ function validateOptionalString(value, path) {
     }
     return [];
 }
+function validateEnablement(value) {
+    if (value === undefined || value === 'app' || value === 'project') {
+        return [];
+    }
+    return [{ path: 'enablement', message: 'Must be "app" or "project"' }];
+}
+function validatePluginIcon(value) {
+    if (value === undefined || isPluginIconName(value) || isPluginSvgIcon(value)) {
+        return [];
+    }
+    return [{ path: 'icon', message: 'Must be a non-empty Lucide icon name or { type: "svg", svg }' }];
+}
 function validateFrontendStyles(value) {
     if (value === undefined)
         return [];
@@ -97,7 +110,8 @@ export function validateOpenForgePackageMetadata(data) {
     errors.push(...validateApiVersion(data.apiVersion));
     errors.push(...validateRequiredString(data.displayName, 'displayName'));
     errors.push(...validateRequiredString(data.description, 'description'));
-    errors.push(...validateOptionalString(data.icon, 'icon'));
+    errors.push(...validateEnablement(data.enablement));
+    errors.push(...validatePluginIcon(data.icon));
     errors.push(...validateOptionalString(data.frontend, 'frontend'));
     errors.push(...validateFrontendStyles(data.frontendStyles));
     if (data.frontendStyles !== undefined && !isNonEmptyString(data.frontend)) {
@@ -105,6 +119,9 @@ export function validateOpenForgePackageMetadata(data) {
     }
     errors.push(...validateOptionalString(data.backend, 'backend'));
     errors.push(...validateRequires(data.requires));
+    if (data.enablement === 'app' && (!Array.isArray(data.requires) || !data.requires.includes('appEnablement'))) {
+        errors.push({ path: 'requires', message: 'App enablement requires the appEnablement capability' });
+    }
     if (Array.isArray(data.requires) && data.requires.includes('browserSurfaces') && !isNonEmptyString(data.frontend)) {
         errors.push({ path: 'requires', message: 'browserSurfaces capability requires a frontend entry' });
     }

package/dist/markdown.d.ts

@@ -2,7 +2,15 @@ export interface RenderMarkdownOptions {
     imageBaseUrl?: string | null;
     markdownFilePath?: string | null;
     deferRepositoryImages?: boolean;
+    deferRemoteMedia?: boolean;
 }
+/** How a deferred remote URL should be presented once it has been resolved. */
+export interface ResolvedMarkdownMedia {
+    url: string;
+    kind: 'image' | 'video';
+}
+/** Attribute holding the original URL of a `<img>`/`<a>` awaiting resolution. */
+export declare const MARKDOWN_REMOTE_MEDIA_ATTRIBUTE = "data-markdown-remote-src";
 export declare function resolveMarkdownRepositoryPath(value: string | null, markdownFilePath: string): string | null;
 export declare function getMarkdownRepositoryLinkSuffix(value: string): string;
 export declare function resolveMarkdownImageSrc(src: string | null, imageBaseUrl: string | null | undefined, markdownFilePath?: string): string | null;

package/dist/markdown.js

@@ -1,5 +1,7 @@
 import { marked } 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';
 const markedOptions = {
     gfm: true,
     breaks: true,
@@ -71,13 +73,57 @@ export function resolveMarkdownImageSrc(src, imageBaseUrl, markdownFilePath = ''
         return null;
     }
 }
-function prepareMarkdownImageSources(html, options) {
-    if (typeof document === 'undefined' || (!options.imageBaseUrl && !options.deferRepositoryImages))
+function isRemoteUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+const TEXT_NODE = 3;
+/**
+ * Whether nothing but a line break separates `anchor` from the end of its line.
+ * GitHub only turns a bare URL into an embedded player when it stands on its own
+ * line, so link markup mid-sentence stays a link.
+ */
+function isAtLineBoundary(from, step) {
+    let node = from;
+    while (node) {
+        if (node.nodeType !== TEXT_NODE)
+            return node.nodeName === 'BR';
+        if ((node.textContent ?? '').trim() !== '')
+            return false;
+        node = node[step];
+    }
+    return true;
+}
+function isBareLinkOnItsOwnLine(anchor, href) {
+    return (anchor.textContent ?? '').trim() === href
+        && isAtLineBoundary(anchor.previousSibling, 'previousSibling')
+        && isAtLineBoundary(anchor.nextSibling, 'nextSibling');
+}
+function deferRemoteMediaLinks(root) {
+    for (const anchor of root.querySelectorAll('a[href]')) {
+        const href = anchor.getAttribute('href')?.trim() ?? '';
+        if (!isRemoteUrl(href) || !isBareLinkOnItsOwnLine(anchor, href))
+            continue;
+        anchor.setAttribute(MARKDOWN_REMOTE_MEDIA_ATTRIBUTE, href);
+    }
+}
+function prepareMarkdownMediaSources(html, options) {
+    if (typeof document === 'undefined' ||
+        (!options.imageBaseUrl && !options.deferRepositoryImages && !options.deferRemoteMedia))
         return html;
     const template = document.createElement('template');
     template.innerHTML = html;
+    if (options.deferRemoteMedia) {
+        deferRemoteMediaLinks(template.content);
+    }
     for (const image of template.content.querySelectorAll('img[src]')) {
         const source = image.getAttribute('src')?.trim() ?? '';
+        // Hold the remote URL back so the caller can exchange it for one the
+        // renderer can actually load, instead of flashing a broken image first.
+        if (options.deferRemoteMedia && isRemoteUrl(source)) {
+            image.removeAttribute('src');
+            image.setAttribute(MARKDOWN_REMOTE_MEDIA_ATTRIBUTE, source);
+            continue;
+        }
         const shouldDefer = options.deferRepositoryImages && source.length > 0 && !hasAbsoluteOrSpecialUrl(source);
         if (shouldDefer) {
             image.removeAttribute('src');
@@ -99,5 +145,5 @@ function prepareMarkdownImageSources(html, options) {
 }
 export function renderMarkdownHtml(content, options = {}) {
     const rawHtml = marked.parse(content, markedOptions);
-    return sanitizeHtml(prepareMarkdownImageSources(rawHtml, options));
+    return sanitizeHtml(prepareMarkdownMediaSources(rawHtml, options));
 }

package/dist/openforgePackageMetadataSchema.json

@@ -27,6 +27,18 @@
                 "required": ["requires"]
             },
             "then": { "required": ["frontend"] }
+        },
+        {
+            "if": {
+                "properties": { "enablement": { "const": "app" } },
+                "required": ["enablement"]
+            },
+            "then": {
+                "properties": {
+                    "requires": { "contains": { "const": "appEnablement" } }
+                },
+                "required": ["requires"]
+            }
         }
     ],
     "properties": {
@@ -47,10 +59,33 @@
             "type": "string",
             "minLength": 1
         },
+        "enablement": {
+            "enum": ["app", "project"],
+            "default": "project",
+            "description": "Lifecycle ownership for this plugin package. Omission means project-owned enablement."
+        },
         "icon": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Semantic OpenForge icon key or package asset reference."
+            "oneOf": [
+                {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S"
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "svg"],
+                    "properties": {
+                        "type": { "const": "svg" },
+                        "svg": {
+                            "type": "string",
+                            "minLength": 1,
+                            "pattern": "\\S"
+                        }
+                    }
+                }
+            ],
+            "description": "Lucide icon name in kebab-case or inline SVG geometry using the PluginIcon contract."
         },
         "frontend": {
             "type": "string",
@@ -101,7 +136,9 @@
                     "config",
                     "projectConfig",
                     "browserSurfaces",
-                    "taskLinks"
+                    "taskLinks",
+                    "appEnablement",
+                    "customSidebarNavigation"
                 ]
             }
         }

package/dist/pluginIconContract.d.ts

@@ -0,0 +1,3 @@
+import type { PluginSvgIcon } from './types';
+export declare function isPluginIconName(value: unknown): value is string;
+export declare function isPluginSvgIcon(value: unknown): value is PluginSvgIcon;

package/dist/pluginIconContract.js

@@ -0,0 +1,12 @@
+export function isPluginIconName(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function isPluginSvgIcon(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const icon = value;
+    return Object.keys(icon).length === 2
+        && icon.type === 'svg'
+        && typeof icon.svg === 'string'
+        && icon.svg.trim().length > 0;
+}

package/dist/pluginIcons.js

@@ -1,4 +1,5 @@
 import DOMPurify from 'dompurify';
+import { isPluginSvgIcon } from './pluginIconContract';
 export const MAX_PLUGIN_SVG_ICON_CHARACTERS = 10_000;
 const ALLOWED_SVG_TAGS = ['svg', 'g', 'path', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon'];
 const ALLOWED_SVG_ATTRIBUTES = [
@@ -33,12 +34,6 @@ const ALLOWED_SVG_ATTRIBUTES = [
     'points',
 ];
 const SAFE_PAINT_VALUE = /^(?:none|currentColor|transparent|#[0-9a-f]{3,8}|[a-z]+|(?:rgb|rgba|hsl|hsla)\([\d\s.,%+\-/]+\))$/iu;
-function isPluginSvgIcon(value) {
-    return value !== null
-        && typeof value === 'object'
-        && value.type === 'svg'
-        && typeof value.svg === 'string';
-}
 function parseSvgRoot(markup) {
     const template = document.createElement('template');
     template.innerHTML = markup.trim();

package/dist/publicUiExports.mjs

@@ -8,6 +8,7 @@ const PUBLIC_UI_COMPONENT_NAMES = Object.freeze([
   'Modal',
   'PluginPageHeader',
   'PluginViewState',
+  'PluginSidebarLink',
   'FileTypeIcon',
 ])
 

package/dist/testing/commonApiFake.d.ts

@@ -1,4 +1,4 @@
-import type { FrontendOpenForgeAPI, OpenForgeCommonAPI } from '../types';
+import type { BackendOpenForgeAPI, FrontendOpenForgeAPI, OpenForgeCommonAPI } from '../types';
 import { type TestingRegistryServices } from './support';
 import type { TestingCommandContribution, TestingEventListenerContribution } from './contracts';
 export type TestingCommonApi = OpenForgeCommonAPI & Pick<FrontendOpenForgeAPI, 'navigation'>;
@@ -10,6 +10,7 @@ export declare class TestingCommonApiFake {
     private eventListenerSequence;
     constructor(services: TestingRegistryServices);
     createApi(): TestingCommonApi;
+    createBackendApi(): TestingCommonApi & Pick<BackendOpenForgeAPI, 'fs'>;
     getSnapshot(): {
         commands: TestingCommandContribution[];
         eventListeners: TestingEventListenerContribution[];

package/dist/testing/commonApiFake.js

@@ -1,4 +1,22 @@
+import { resolveExternalTextFileChunkSize } from '../types';
 import { assertFunction, assertTitle, commandDescriptor, createDisposable, isJsonValue, normalizeAgentCommandMetadata, } from './support';
+const UTF8_ENCODER = new TextEncoder();
+function* splitExternalTextFile(content, maxBytes) {
+    let chunk = '';
+    let chunkBytes = 0;
+    for (const character of content) {
+        const characterBytes = UTF8_ENCODER.encode(character).byteLength;
+        if (chunkBytes + characterBytes > maxBytes && chunk.length > 0) {
+            yield chunk;
+            chunk = '';
+            chunkBytes = 0;
+        }
+        chunk += character;
+        chunkBytes += characterBytes;
+    }
+    if (chunk.length > 0)
+        yield chunk;
+}
 export class TestingCommonApiFake {
     services;
     commands = new Map();
@@ -136,7 +154,7 @@ export class TestingCommonApiFake {
                 },
                 getBuffer: async (request) => {
                     this.services.calls.shellBuffers.push(request);
-                    return null;
+                    return { buffer: null, isLive: false };
                 },
             },
             notifications: {
@@ -183,6 +201,51 @@ export class TestingCommonApiFake {
         };
         return api;
     }
+    createBackendApi() {
+        const api = this.createApi();
+        return {
+            ...api,
+            fs: {
+                ...api.fs,
+                userData: {
+                    readDir: async (request = {}) => {
+                        this.services.calls.fsUserDataReadDirs.push(request);
+                        return [];
+                    },
+                    readTextFile: async (request) => {
+                        this.services.calls.fsUserDataReads.push(request);
+                        return '';
+                    },
+                    writeTextFile: async (request) => {
+                        this.services.calls.fsUserDataWrites.push(request);
+                    },
+                },
+                external: {
+                    readDir: async (request) => {
+                        this.services.calls.fsExternalReadDirs.push(request);
+                        return [];
+                    },
+                    readTextFile: async (request) => {
+                        this.services.calls.fsExternalReads.push(request);
+                        return '';
+                    },
+                    readTextFileChunks: (request) => {
+                        const chunkSizeBytes = resolveExternalTextFileChunkSize(request.chunkSizeBytes);
+                        const { root, path, signal } = request;
+                        this.services.calls.fsExternalReadTextFileChunks.push({ root, path, chunkSizeBytes });
+                        const content = this.services.externalTextFiles.find(file => file.root === root && file.path === path)?.content ?? '';
+                        return (async function* () {
+                            for (const chunk of splitExternalTextFile(content, chunkSizeBytes)) {
+                                signal?.throwIfAborted();
+                                yield chunk;
+                            }
+                            signal?.throwIfAborted();
+                        })();
+                    },
+                },
+            },
+        };
+    }
     getSnapshot() {
         return {
             commands: Array.from(this.commands.values()),

package/dist/testing/contracts.d.ts

@@ -1,12 +1,18 @@
 import type { BrowserSurfaceVisualFeedback } from '../browserSurfaces';
 import type { TestingOpenForgeRegistryFake } from './registryFake';
-import type { BackendMethodRegistration, BackendOpenForgeAPI, BackgroundServiceRegistration, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ConfigureStartPromptContributionRequest, CreateTaskRequest, FrontendOpenForgeAPI, InjectionPointLocation, JsonValue, NotificationRequest, OpenForgeNavigationRequest, OpenForgePackageMetadata, PluginSettingsSectionRegistration, PluginStorage, PluginTaskPaneTabRegistration, PluginTaskUISectionRegistration, PluginViewRegistration, ShellSpawnRequest, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskLinkOpenRequest, TaskStartPrefixContext } from '../types';
+import type { BackendMethodRegistration, BackendOpenForgeAPI, BackgroundServiceRegistration, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ConfigureStartPromptContributionRequest, CreateTaskRequest, FrontendOpenForgeAPI, InjectionPointLocation, JsonValue, NotificationRequest, OpenForgeNavigationRequest, OpenForgePackageMetadata, PluginSettingsSectionRegistration, PluginStorage, PluginTaskPaneTabRegistration, PluginTaskUISectionRegistration, PluginViewRegistration, ShellSpawnRequest, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskLinkOpenRequest, TaskStartPrefixContext, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadTextFileChunksRequest, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileWriteRequest } from '../types';
 import type { Task } from '../domain';
 export type TestingRuntimeScope = 'global' | 'project' | 'task';
 export type TestingRuntimeKind = 'commands' | 'events' | 'views' | 'taskPane' | 'taskUI' | 'settings' | 'backend' | 'background';
 export type TestingMaybePromise<T> = T | Promise<T>;
 export type TestingCommandHandler = (payload?: unknown) => TestingMaybePromise<unknown>;
 export type TestingEventHandler = (payload: unknown) => void;
+export interface TestingExternalTextFile extends ExternalReadFileRequest {
+    content: string;
+}
+export type TestingExternalTextFileChunksCall = Omit<ExternalReadTextFileChunksRequest, 'signal' | 'chunkSizeBytes'> & {
+    chunkSizeBytes: number;
+};
 export interface TestingOpenForgeApiOptions {
     pluginId?: string;
     projectId?: string | null;
@@ -21,6 +27,8 @@ export interface TestingOpenForgeApiOptions {
      * mirroring the host capability. Defaults to an empty list.
      */
     tasks?: Task[];
+    /** UTF-8 files returned by `fs.external.readTextFileChunks`. Defaults to none. */
+    externalTextFiles?: TestingExternalTextFile[];
 }
 export interface TestingOpenForgeApiCalls {
     commandInvocations: Array<{
@@ -74,6 +82,12 @@ export interface TestingOpenForgeApiCalls {
         path: string;
         content: string;
     }>;
+    fsUserDataReadDirs: UserDataDirectoryRequest[];
+    fsUserDataReads: UserDataFileRequest[];
+    fsUserDataWrites: UserDataFileWriteRequest[];
+    fsExternalReadDirs: ExternalReadDirectoryRequest[];
+    fsExternalReads: ExternalReadFileRequest[];
+    fsExternalReadTextFileChunks: TestingExternalTextFileChunksCall[];
     shellSpawns: ShellSpawnRequest[];
     shellWrites: Array<{
         taskId: string;

package/dist/testing/frontendContributionFake.js

@@ -102,6 +102,15 @@ export class TestingFrontendContributionFake {
         const qualifiedId = this.services.localQualifiedId('views', registration.id);
         assertTitle('views', registration.title);
         assertFunction('views', 'component', registration.component);
+        if (registration.navigationComponent !== undefined) {
+            assertFunction('views', 'navigationComponent', registration.navigationComponent);
+            if (registration.placement !== 'sidebar') {
+                throw new Error('views registration custom navigation requires sidebar placement');
+            }
+            if (!this.services.packageMetadata.requires?.includes('customSidebarNavigation')) {
+                throw new Error('views registration custom navigation requires the customSidebarNavigation capability');
+            }
+        }
         this.services.claims.claim('views', qualifiedId);
         const contribution = {
             ...registration,

package/dist/testing/registryFake.js

@@ -58,7 +58,7 @@ export class TestingOpenForgeRegistryFake {
         if (this.cachedBackendApi)
             return this.cachedBackendApi;
         const api = {
-            ...this.commonApi.createApi(),
+            ...this.commonApi.createBackendApi(),
             ...this.backendServices.createApi(),
             __testing: {
                 calls: this.calls,
@@ -104,6 +104,7 @@ export class TestingOpenForgeRegistryFake {
             apiVersion: 1,
             packageMetadata: this.packageMetadata,
             subscriptions,
+            onDidChange: () => ({ dispose: () => undefined }),
         };
     }
 }

package/dist/testing/support.d.ts

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

package/dist/testing/support.js

@@ -48,6 +48,12 @@ export function createTestingCalls() {
         taskStatusUpdates: [],
         configWrites: [],
         fsWrites: [],
+        fsUserDataReadDirs: [],
+        fsUserDataReads: [],
+        fsUserDataWrites: [],
+        fsExternalReadDirs: [],
+        fsExternalReads: [],
+        fsExternalReadTextFileChunks: [],
         shellSpawns: [],
         shellWrites: [],
         shellResizes: [],
@@ -196,6 +202,7 @@ export class TestingRegistryServices {
     storage;
     config = new Map();
     seededTasks;
+    externalTextFiles;
     claims = new TestingContributionClaims();
     constructor(options = {}) {
         this.pluginId = options.pluginId ?? 'test-plugin';
@@ -211,6 +218,7 @@ export class TestingRegistryServices {
         this.calls = createTestingCalls();
         this.storage = options.storage ?? createMemoryPluginStorage(this.calls);
         this.seededTasks = options.tasks ?? [];
+        this.externalTextFiles = options.externalTextFiles ?? [];
     }
     localQualifiedId(kind, id) {
         assertLocalId(kind, id);

package/dist/testing.d.ts

@@ -1,3 +1,3 @@
 export { createMockBackendOpenForgeApi, createMockFrontendOpenForgeApi, createMockOpenForgeApi, createMockPluginContext, createOpenForgeRegistryFake, TestingOpenForgeRegistryFake, } from './testing/registryFake';
 export { createMemoryPluginStorage, createTestingCalls, TestingSubscriptionSink, } from './testing/support';
-export type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingBackgroundServiceContribution, TestingBackendMethodContribution, TestingCommandContribution, TestingContributionBase, TestingEventListenerContribution, TestingInjectionPointContribution, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot, TestingRuntimeKind, TestingRuntimeScope, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingTaskUISectionContribution, TestingViewContribution, } from './testing/contracts';
+export type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingBackgroundServiceContribution, TestingBackendMethodContribution, TestingCommandContribution, TestingContributionBase, TestingExternalTextFile, TestingExternalTextFileChunksCall, TestingEventListenerContribution, TestingInjectionPointContribution, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot, TestingRuntimeKind, TestingRuntimeScope, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingTaskUISectionContribution, TestingViewContribution, } from './testing/contracts';

package/dist/types.d.ts

@@ -17,13 +17,16 @@ export interface ValidationError {
     path: string;
     message: string;
 }
-export type OpenForgePluginCapability = 'commands' | 'events' | 'views' | 'taskPane' | 'taskStart' | 'settings' | 'background' | 'backend' | 'storage' | 'context' | 'navigation' | 'tasks' | 'projects' | 'fs' | 'shell' | 'notifications' | 'attention' | 'system.openUrl' | 'system.writeClipboardText' | 'config' | 'projectConfig' | 'browserSurfaces' | 'taskLinks';
+declare const OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS: readonly ['commands', 'events', 'views', 'injectionPoints', 'taskPane', 'taskStart', 'settings', 'background', 'backend', 'storage', 'context', 'navigation', 'tasks', 'projects', 'fs', 'shell', 'notifications', 'attention', 'system.openUrl', 'system.writeClipboardText', 'config', 'projectConfig', 'browserSurfaces', 'taskLinks', 'appEnablement', 'customSidebarNavigation'];
+export type OpenForgePluginCapability = (typeof OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS)[number];
 export interface OpenForgePackageMetadata {
     id: string;
     apiVersion: SupportedOpenForgeApiVersion;
     displayName: string;
     description: string;
-    icon?: string;
+    /** Defaults to project-owned lifecycle when omitted. */
+    enablement?: 'app' | 'project';
+    icon?: PluginIcon;
     frontend?: string;
     frontendStyles?: string[];
     backend?: string;
@@ -54,6 +57,7 @@ export interface OpenForgeContextSnapshot {
     projectId: string | null;
     taskId?: string | null;
 }
+export type OpenForgeContextChangeHandler = (snapshot: OpenForgeContextSnapshot) => MaybePromise<void>;
 export interface OpenForgeNavigationSnapshot {
     activeProjectId: string | null;
     currentView: string;
@@ -85,6 +89,7 @@ export interface OpenForgePluginContext {
     apiVersion: SupportedOpenForgeApiVersion;
     packageMetadata: OpenForgePackageMetadata;
     subscriptions: SubscriptionSink;
+    onDidChange(handler: OpenForgeContextChangeHandler): Disposable;
 }
 export type FrontendPluginContext = OpenForgePluginContext;
 export type BackendPluginContext = OpenForgePluginContext;
@@ -188,6 +193,21 @@ export interface PluginViewProps extends Record<string, unknown> {
     api: FrontendOpenForgeAPI;
     context: OpenForgeContextSnapshot;
 }
+export interface PluginSidebarViewIdentity {
+    pluginId: string;
+    id: string;
+    qualifiedId: string;
+    title: string;
+    icon: PluginIcon;
+}
+export interface PluginSidebarNavigationProps extends Record<string, unknown> {
+    api: FrontendOpenForgeAPI;
+    context: OpenForgeContextSnapshot;
+    active: boolean;
+    collapsed: boolean;
+    view: PluginSidebarViewIdentity;
+    onActivate: () => void;
+}
 export interface PluginTaskPaneProps extends Record<string, unknown> {
     api: FrontendOpenForgeAPI;
     context: OpenForgeContextSnapshot;
@@ -230,6 +250,8 @@ export interface PluginViewRegistration {
     order?: number;
     shortcut?: string;
     component: PluginComponentLoader<PluginViewProps> | PluginComponent<PluginViewProps>;
+    /** Custom content for a sidebar-placed View's host-owned navigation slot. */
+    navigationComponent?: PluginComponentLoader<PluginSidebarNavigationProps> | PluginComponent<PluginSidebarNavigationProps>;
 }
 export interface PluginTaskPaneTabRegistration {
     id: string;
@@ -353,6 +375,49 @@ export interface FileSystemAPI {
         limit?: number;
     }): Promise<string[]>;
 }
+export interface UserDataDirectoryRequest {
+    path?: string | null;
+}
+export interface UserDataFileRequest {
+    path: string;
+}
+export interface UserDataFileWriteRequest extends UserDataFileRequest {
+    content: string;
+}
+export interface ExternalReadDirectoryRequest {
+    root: string;
+    path?: string | null;
+}
+export interface ExternalReadFileRequest {
+    root: string;
+    path: string;
+}
+export declare const DEFAULT_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES: number;
+export declare const MIN_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES = 4;
+export declare const MAX_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES: number;
+/** Applies the default external text chunk size and rejects values outside host limits. */
+export declare function resolveExternalTextFileChunkSize(chunkSizeBytes?: number): number;
+export interface ExternalReadTextFileChunksRequest extends ExternalReadFileRequest {
+    /** UTF-8 chunks contain at most this many bytes. Defaults to 64 KiB. */
+    chunkSizeBytes?: number;
+    /** Stops future reads. An in-flight host read may finish, but its result is discarded. */
+    signal?: AbortSignal;
+}
+export interface UserDataFileSystemAPI {
+    readDir(request?: UserDataDirectoryRequest): Promise<FileEntry[]>;
+    readTextFile(request: UserDataFileRequest): Promise<string>;
+    writeTextFile(request: UserDataFileWriteRequest): Promise<void>;
+}
+export interface ExternalReadFileSystemAPI {
+    readDir(request: ExternalReadDirectoryRequest): Promise<FileEntry[]>;
+    readTextFile(request: ExternalReadFileRequest): Promise<string>;
+    /** Lazily reads a UTF-8 file without retaining a host file handle between chunks. */
+    readTextFileChunks(request: ExternalReadTextFileChunksRequest): AsyncIterable<string>;
+}
+export interface BackendFileSystemAPI extends FileSystemAPI {
+    userData: UserDataFileSystemAPI;
+    external: ExternalReadFileSystemAPI;
+}
 export type TerminalImageProtocol = 'iterm2';
 export interface ShellSessionRequest {
     taskId: string;
@@ -371,12 +436,16 @@ export interface ShellResizeRequest extends ShellSessionRequest {
     cols: number;
     rows: number;
 }
+export interface PtyBufferState {
+    buffer: string | null;
+    isLive: boolean;
+}
 export interface ShellAPI {
     spawn(request: ShellSpawnRequest): Promise<number>;
     write(request: ShellWriteRequest): Promise<void>;
     resize(request: ShellResizeRequest): Promise<void>;
     kill(request: ShellSessionRequest): Promise<void>;
-    getBuffer(request: ShellSessionRequest): Promise<string | null>;
+    getBuffer(request: ShellSessionRequest): Promise<PtyBufferState>;
 }
 export interface CreateTaskRequest {
     initialPrompt: string;
@@ -518,6 +587,7 @@ export interface FrontendOpenForgeAPI extends OpenForgeCommonAPI {
     taskStart: FrontendTaskStartRegistry;
 }
 export interface BackendOpenForgeAPI extends OpenForgeCommonAPI {
+    fs: BackendFileSystemAPI;
     backend: BackendMethodRegistry;
     background: BackgroundServiceRegistry;
 }
@@ -534,3 +604,4 @@ export declare function parsePluginViewKey(key: PluginViewKey): {
     pluginId: string;
     viewId: string;
 };
+export {};

package/dist/types.js

@@ -10,6 +10,58 @@ export const SUPPORTED_OPENFORGE_API_VERSIONS = Object.freeze(readSupportedOpenF
 export const OPENFORGE_PLUGIN_API_VERSION = SUPPORTED_OPENFORGE_API_VERSIONS[0];
 export const MIN_SUPPORTED_API_VERSION = Math.min(...SUPPORTED_OPENFORGE_API_VERSIONS);
 export const MAX_SUPPORTED_API_VERSION = Math.max(...SUPPORTED_OPENFORGE_API_VERSIONS);
+const OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS = [
+    'commands',
+    'events',
+    'views',
+    'injectionPoints',
+    'taskPane',
+    'taskStart',
+    'settings',
+    'background',
+    'backend',
+    'storage',
+    'context',
+    'navigation',
+    'tasks',
+    'projects',
+    'fs',
+    'shell',
+    'notifications',
+    'attention',
+    'system.openUrl',
+    'system.writeClipboardText',
+    'config',
+    'projectConfig',
+    'browserSurfaces',
+    'taskLinks',
+    'appEnablement',
+    'customSidebarNavigation',
+];
+function assertOpenForgePluginCapabilitiesMatchSchema() {
+    const schemaCapabilities = packageMetadataSchemaData.properties.requires.items.enum;
+    if (!Array.isArray(schemaCapabilities) || !schemaCapabilities.every((capability) => typeof capability === 'string')) {
+        throw new Error('openforgePackageMetadataSchema.json properties.requires.items.enum must contain only strings');
+    }
+    if (schemaCapabilities.length !== OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS.length
+        || schemaCapabilities.some((capability, index) => capability !== OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS[index])) {
+        throw new Error('OpenForgePluginCapability must match openforgePackageMetadataSchema.json properties.requires.items.enum');
+    }
+}
+assertOpenForgePluginCapabilitiesMatchSchema();
+export const DEFAULT_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES = 64 * 1024;
+export const MIN_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES = 4;
+export const MAX_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES = 1024 * 1024;
+/** Applies the default external text chunk size and rejects values outside host limits. */
+export function resolveExternalTextFileChunkSize(chunkSizeBytes) {
+    const size = chunkSizeBytes ?? DEFAULT_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES;
+    if (!Number.isInteger(size)
+        || size < MIN_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES
+        || size > MAX_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES) {
+        throw new RangeError(`chunkSizeBytes must be an integer between ${MIN_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES} and ${MAX_EXTERNAL_TEXT_FILE_CHUNK_SIZE_BYTES}`);
+    }
+    return size;
+}
 export class TaskFollowUpError extends Error {
     code;
     constructor(code, message) {

package/dist/ui/MarkdownContent.svelte

@@ -1,12 +1,19 @@
 <script lang="ts">
   import { onDestroy } from 'svelte'
-  import { getMarkdownRepositoryLinkSuffix, renderMarkdownHtml, resolveMarkdownRepositoryPath } from '../markdown'
+  import {
+    getMarkdownRepositoryLinkSuffix,
+    MARKDOWN_REMOTE_MEDIA_ATTRIBUTE,
+    renderMarkdownHtml,
+    resolveMarkdownRepositoryPath,
+    type ResolvedMarkdownMedia,
+  } from '../markdown'
 
   interface Props {
     content: string
     imageBaseUrl?: string | null
     markdownFilePath?: string | null
     resolveRepositoryImage?: (repositoryPath: string) => Promise<string | null>
+    resolveRemoteMedia?: (url: string) => Promise<ResolvedMarkdownMedia | null>
     onOpenRepositoryPath?: (repositoryPath: string, suffix: string) => void | Promise<void>
     onOpenUrl?: (url: string) => void | Promise<void>
   }
@@ -16,6 +23,7 @@
     imageBaseUrl = null,
     markdownFilePath = null,
     resolveRepositoryImage,
+    resolveRemoteMedia,
     onOpenRepositoryPath,
     onOpenUrl,
   }: Props = $props()
@@ -26,6 +34,7 @@
     imageBaseUrl: resolveRepositoryImage ? null : imageBaseUrl,
     markdownFilePath,
     deferRepositoryImages: Boolean(resolveRepositoryImage),
+    deferRemoteMedia: Boolean(resolveRemoteMedia),
   }))
 
   async function resolveRepositoryImages(runId: number) {
@@ -47,12 +56,55 @@
     }))
   }
 
+  function applyResolvedMedia(element: Element, url: string, resolved: ResolvedMarkdownMedia | null) {
+    element.removeAttribute(MARKDOWN_REMOTE_MEDIA_ATTRIBUTE)
+
+    if (element instanceof HTMLImageElement) {
+      element.setAttribute('src', resolved?.url ?? url)
+      return
+    }
+
+    // A bare link only becomes a player when the caller says the upload is one;
+    // everything else stays the link the Markdown asked for.
+    if (resolved?.kind !== 'video') return
+
+    const video = document.createElement('video')
+    video.src = resolved.url
+    video.controls = true
+    video.preload = 'metadata'
+    element.replaceWith(video)
+  }
+
+  // Remote media is held back by the renderer so the caller can swap in a URL
+  // this app can load (GitHub only serves upload URLs to a browser session).
+  // Anything the caller does not handle falls back to what the Markdown said.
+  async function resolveRemoteMediaElements(runId: number) {
+    if (!root || !resolveRemoteMedia) return
+
+    const elements = Array.from(root.querySelectorAll(`[${MARKDOWN_REMOTE_MEDIA_ATTRIBUTE}]`))
+    await Promise.all(elements.map(async (element) => {
+      const url = element.getAttribute(MARKDOWN_REMOTE_MEDIA_ATTRIBUTE)
+      if (!url) return
+
+      let resolved: ResolvedMarkdownMedia | null = null
+      try {
+        resolved = await resolveRemoteMedia(url)
+      } catch {
+        // Fall back to the original URL when resolution is unavailable.
+      }
+
+      if (runId !== imageResolutionId) return
+      applyResolvedMedia(element, url, resolved)
+    }))
+  }
+
   $effect(() => {
     const runId = ++imageResolutionId
     void html
-    if (!root || !markdownFilePath || !resolveRepositoryImage) return
+    if (!root) return
 
     void resolveRepositoryImages(runId)
+    void resolveRemoteMediaElements(runId)
   })
 
   onDestroy(() => {

package/dist/ui/PluginSidebarLink.svelte

@@ -0,0 +1,54 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+
+  interface Props {
+    accessibleName: string
+    active: boolean
+    collapsed: boolean
+    onActivate: () => void
+    leading?: Snippet
+    label?: Snippet
+    trailing?: Snippet
+    class?: string
+  }
+
+  let {
+    accessibleName,
+    active,
+    collapsed,
+    onActivate,
+    leading,
+    label,
+    trailing,
+    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',
+    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,
+  ]}
+  title={collapsed ? accessibleName : undefined}
+  aria-label={accessibleName}
+  aria-current={active ? 'page' : undefined}
+  onclick={onActivate}
+  onkeydown={handleKeydown}
+>
+  {#if leading}
+    <span class="relative shrink-0">{@render leading()}</span>
+  {/if}
+  {#if !collapsed}
+    {#if label}<span class="min-w-0 text-sm font-medium">{@render label()}</span>{/if}
+    {#if trailing}<span class="ml-auto shrink-0">{@render trailing()}</span>{/if}
+  {/if}
+</button>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openforge-app/plugin-sdk",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -71,6 +71,7 @@
     "./ui/Modal.svelte": "./dist/ui/Modal.svelte",
     "./ui/PluginPageHeader.svelte": "./dist/ui/PluginPageHeader.svelte",
     "./ui/PluginViewState.svelte": "./dist/ui/PluginViewState.svelte",
+    "./ui/PluginSidebarLink.svelte": "./dist/ui/PluginSidebarLink.svelte",
     "./ui/FileTypeIcon.svelte": "./dist/ui/FileTypeIcon.svelte"
   },
   "files": [
@@ -92,17 +93,17 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "dompurify": "^3.4.13",
-    "marked": "^18.0.9"
+    "dompurify": "catalog:",
+    "marked": "catalog:"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
   "devDependencies": {
-    "@types/node": "26.2.0",
-    "svelte": "5.56.8",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.10",
+    "@types/node": "catalog:pinned",
+    "svelte": "catalog:pinned",
+    "typescript": "catalog:",
+    "vitest": "catalog:",
     "vscode-material-icons": "^0.1.1"
   }
 }