@openforge-app/plugin-sdk 0.2.9 → 0.2.10

package/dist/testing/commonApiFake.js

@@ -1,6 +1,71 @@
-import { resolveExternalTextFileChunkSize } from '../types.js';
+import { MAX_AGENT_SESSION_PAGE_SIZE, resolveExternalTextFileChunkSize } from '../types.js';
 import { assertFunction, assertTitle, commandDescriptor, createDisposable, isJsonValue, normalizeAgentCommandMetadata, } from './support.js';
 const UTF8_ENCODER = new TextEncoder();
+const UTF8_DECODER = new TextDecoder('utf-8', { fatal: true });
+const TERMINAL_AGENT_SESSION_STATUSES = new Set(['completed', 'failed', 'interrupted']);
+function encodeAgentSessionCursor(payload) {
+    const bytes = UTF8_ENCODER.encode(JSON.stringify(payload));
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+function parseAgentSessionCursor(cursor) {
+    try {
+        const base64 = cursor.replaceAll('-', '+').replaceAll('_', '/');
+        const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
+        const binary = atob(padded);
+        const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+        const payload = JSON.parse(UTF8_DECODER.decode(bytes));
+        const filters = payload.filters;
+        if (payload.version !== 1
+            || !Number.isSafeInteger(payload.createdAt)
+            || typeof payload.id !== 'string'
+            || payload.id.length === 0
+            || !filters
+            || typeof filters.provider !== 'string'
+            || !Number.isSafeInteger(filters.startInclusive)
+            || !Number.isSafeInteger(filters.endExclusive)
+            || (filters.taskId !== null && typeof filters.taskId !== 'string')) {
+            throw new Error('invalid payload');
+        }
+        return payload;
+    }
+    catch {
+        throw new TypeError('cursor is malformed');
+    }
+}
+function providerSessionId(session) {
+    switch (session.provider) {
+        case 'opencode': return session.opencode_session_id;
+        case 'claude-code': return session.claude_session_id;
+        case 'pi': return session.pi_session_id;
+        case 'grok': return session.grok_session_id;
+        default: return null;
+    }
+}
+function assertNonNegativeSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+    }
+}
+function testingExternalFileIdentity(file) {
+    return file.identity ?? `${file.root}:${file.path}`;
+}
+function readTestingExternalTextRange(file, startOffsetBytes, maxBytes, expectedIdentity) {
+    assertNonNegativeSafeInteger(startOffsetBytes, 'startOffsetBytes');
+    if (maxBytes !== undefined)
+        assertNonNegativeSafeInteger(maxBytes, 'maxBytes');
+    const identity = testingExternalFileIdentity(file);
+    if (expectedIdentity !== undefined && expectedIdentity !== identity) {
+        throw new Error(`External file identity changed: expected ${expectedIdentity}, received ${identity}`);
+    }
+    const bytes = UTF8_ENCODER.encode(file.content);
+    const endOffsetBytes = maxBytes === undefined
+        ? bytes.byteLength
+        : Math.min(bytes.byteLength, startOffsetBytes + maxBytes);
+    return UTF8_DECODER.decode(bytes.slice(startOffsetBytes, endOffsetBytes));
+}
 function* splitExternalTextFile(content, maxBytes) {
     let chunk = '';
     let chunkBytes = 0;
@@ -45,6 +110,100 @@ export class TestingCommonApiFake {
             context: {
                 getSnapshot: () => this.services.getContextSnapshot(),
             },
+            agentSessions: {
+                list: async (request) => {
+                    if (typeof request.provider !== 'string' || request.provider.trim().length === 0) {
+                        throw new TypeError('provider must be a non-empty string');
+                    }
+                    if (request.taskId !== undefined && (typeof request.taskId !== 'string' || request.taskId.trim().length === 0)) {
+                        throw new TypeError('taskId must be a non-empty string');
+                    }
+                    if (request.cursor !== undefined && (typeof request.cursor !== 'string' || request.cursor.length === 0)) {
+                        throw new TypeError('cursor must be a non-empty string');
+                    }
+                    if (!request.overlaps || typeof request.overlaps !== 'object') {
+                        throw new TypeError('overlaps must contain startInclusive and endExclusive');
+                    }
+                    assertNonNegativeSafeInteger(request.overlaps.startInclusive, 'overlaps.startInclusive');
+                    assertNonNegativeSafeInteger(request.overlaps.endExclusive, 'overlaps.endExclusive');
+                    if (request.overlaps.startInclusive >= request.overlaps.endExclusive) {
+                        throw new RangeError('overlaps must satisfy startInclusive < endExclusive');
+                    }
+                    if (!Number.isSafeInteger(request.pageSize)
+                        || request.pageSize < 1
+                        || request.pageSize > MAX_AGENT_SESSION_PAGE_SIZE) {
+                        throw new RangeError(`pageSize must be between 1 and ${MAX_AGENT_SESSION_PAGE_SIZE}`);
+                    }
+                    const filters = {
+                        provider: request.provider,
+                        startInclusive: request.overlaps.startInclusive,
+                        endExclusive: request.overlaps.endExclusive,
+                        taskId: request.taskId ?? null,
+                    };
+                    const cursor = request.cursor === undefined ? null : parseAgentSessionCursor(request.cursor);
+                    if (cursor !== null
+                        && (cursor.filters.provider !== filters.provider
+                            || cursor.filters.startInclusive !== filters.startInclusive
+                            || cursor.filters.endExclusive !== filters.endExclusive
+                            || cursor.filters.taskId !== filters.taskId)) {
+                        throw new TypeError('cursor does not match request filters');
+                    }
+                    this.services.calls.agentSessionListRequests.push({
+                        ...request,
+                        overlaps: { ...request.overlaps },
+                    });
+                    const taskById = new Map(this.services.seededTasks.map((task) => [task.id, task]));
+                    const rows = this.services.seededAgentSessions
+                        .filter((session) => taskById.has(session.ticket_id))
+                        .filter((session) => session.provider === request.provider)
+                        .filter((session) => request.taskId === undefined || session.ticket_id === request.taskId)
+                        .filter((session) => session.created_at < request.overlaps.endExclusive
+                        && (!TERMINAL_AGENT_SESSION_STATUSES.has(session.status)
+                            || session.updated_at > request.overlaps.startInclusive))
+                        .filter((session) => cursor === null
+                        || session.created_at > cursor.createdAt
+                        || (session.created_at === cursor.createdAt && session.id > cursor.id))
+                        .slice()
+                        .sort((left, right) => left.created_at - right.created_at
+                        || (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+                    const pageRows = rows.slice(0, request.pageSize);
+                    const items = pageRows.map((session) => {
+                        const task = taskById.get(session.ticket_id);
+                        if (!task)
+                            throw new Error(`Missing seeded Task for Agent Session ${session.id}`);
+                        const workspace = this.services.agentSessionWorkspaces[task.id];
+                        return {
+                            id: session.id,
+                            provider: session.provider,
+                            providerSessionId: providerSessionId(session),
+                            createdAt: session.created_at,
+                            updatedAt: session.updated_at,
+                            task: {
+                                id: task.id,
+                                title: task.title?.trim() || task.id,
+                                status: task.status,
+                                createdAt: task.created_at,
+                                updatedAt: task.updated_at,
+                            },
+                            workspace: workspace
+                                ? { rootPath: workspace.rootPath, kind: workspace.kind }
+                                : null,
+                        };
+                    });
+                    const last = pageRows.at(-1);
+                    return {
+                        items,
+                        nextCursor: rows.length > request.pageSize && last
+                            ? encodeAgentSessionCursor({
+                                version: 1,
+                                createdAt: last.created_at,
+                                id: last.id,
+                                filters,
+                            })
+                            : null,
+                    };
+                },
+            },
             tasks: {
                 list: async (request) => {
                     const projectId = request?.projectId ?? null;
@@ -125,6 +284,16 @@ export class TestingCommonApiFake {
                 },
                 getWorkspace: async () => null,
                 getLatestSession: async () => null,
+                listSessions: async (request) => {
+                    this.services.calls.taskSessionListRequests.push({ ...request });
+                    return this.services.seededAgentSessions
+                        .map((session, index) => ({ session, index }))
+                        .filter(({ session }) => session.ticket_id === request.taskId)
+                        .filter(({ session }) => request.provider === undefined || session.provider === request.provider)
+                        .filter(({ session }) => request.createdAtOrAfter === undefined || session.created_at >= request.createdAtOrAfter)
+                        .sort((left, right) => right.session.created_at - left.session.created_at || right.index - left.index)
+                        .map(({ session }) => session);
+                },
             },
             projects: {
                 list: async () => [],
@@ -146,7 +315,6 @@ export class TestingCommonApiFake {
                 write: async (request) => {
                     this.services.calls.shellWrites.push(request);
                 },
-                writeTerminalQueryResponse: async () => { },
                 resize: async (request) => {
                     this.services.calls.shellResizes.push(request);
                 },
@@ -215,10 +383,17 @@ export class TestingCommonApiFake {
                     },
                     readTextFile: async (request) => {
                         this.services.calls.fsUserDataReads.push(request);
-                        return '';
+                        return this.services.userDataTextFiles.get(request.path) ?? '';
                     },
                     writeTextFile: async (request) => {
                         this.services.calls.fsUserDataWrites.push(request);
+                        this.services.userDataTextFiles.set(request.path, request.content);
+                    },
+                    appendTextFile: async (request) => {
+                        this.services.calls.fsUserDataAppends.push(request);
+                        const content = `${this.services.userDataTextFiles.get(request.path) ?? ''}${request.content}`;
+                        this.services.userDataTextFiles.set(request.path, content);
+                        return { sizeBytes: UTF8_ENCODER.encode(content).byteLength };
                     },
                 },
                 external: {
@@ -230,14 +405,39 @@ export class TestingCommonApiFake {
                         this.services.calls.fsExternalReads.push(request);
                         return '';
                     },
+                    stat: async (request) => {
+                        this.services.calls.fsExternalStats.push(request);
+                        const file = this.services.externalTextFiles.find(candidate => candidate.root === request.root && candidate.path === request.path);
+                        if (!file)
+                            throw new Error(`External file not found: ${request.root}/${request.path}`);
+                        return {
+                            identity: testingExternalFileIdentity(file),
+                            sizeBytes: UTF8_ENCODER.encode(file.content).byteLength,
+                            modifiedAtMs: file.modifiedAtMs ?? null,
+                        };
+                    },
                     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 ?? '';
+                        const { root, path, signal, expectedIdentity, startOffsetBytes = 0, maxBytes, } = request;
+                        this.services.calls.fsExternalReadTextFileChunks.push({
+                            root,
+                            path,
+                            chunkSizeBytes,
+                            ...(expectedIdentity === undefined ? {} : { expectedIdentity }),
+                            ...(request.startOffsetBytes === undefined ? {} : { startOffsetBytes }),
+                            ...(maxBytes === undefined ? {} : { maxBytes }),
+                        });
+                        const file = this.services.externalTextFiles.find(candidate => candidate.root === root && candidate.path === path);
                         return (async function* () {
+                            signal?.throwIfAborted();
+                            if (!file)
+                                throw new Error(`External file not found: ${root}/${path}`);
+                            const content = readTestingExternalTextRange(file, startOffsetBytes, maxBytes, expectedIdentity);
                             for (const chunk of splitExternalTextFile(content, chunkSizeBytes)) {
                                 signal?.throwIfAborted();
+                                if (expectedIdentity !== undefined && testingExternalFileIdentity(file) !== expectedIdentity) {
+                                    throw new Error(`External file identity changed: expected ${expectedIdentity}, received ${testingExternalFileIdentity(file)}`);
+                                }
                                 yield chunk;
                             }
                             signal?.throwIfAborted();

package/dist/testing/contracts.d.ts

@@ -1,7 +1,7 @@
 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, PluginReviewRowActionRegistration, PluginTaskUISectionRegistration, PluginViewRegistration, ShellSpawnRequest, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskLinkOpenRequest, TaskStartPrefixContext, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadTextFileChunksRequest, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileWriteRequest } from '../types';
-import type { Task } from '../domain';
+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';
 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>;
@@ -9,6 +9,9 @@ export type TestingCommandHandler = (payload?: unknown) => TestingMaybePromise<u
 export type TestingEventHandler = (payload: unknown) => void;
 export interface TestingExternalTextFile extends ExternalReadFileRequest {
     content: string;
+    /** Defaults to a deterministic identity derived from root and path. */
+    identity?: string;
+    modifiedAtMs?: number | null;
 }
 export type TestingExternalTextFileChunksCall = Omit<ExternalReadTextFileChunksRequest, 'signal' | 'chunkSizeBytes'> & {
     chunkSizeBytes: number;
@@ -21,12 +24,18 @@ export interface TestingOpenForgeApiOptions {
     viewId?: string;
     packageMetadata?: OpenForgePackageMetadata;
     storage?: PluginStorage;
+    /** Initial files exposed through `fs.userData`. Defaults to none. */
+    userDataTextFiles?: UserDataFileWriteRequest[];
     /**
      * 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[];
+    /** 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. */
+    agentSessionWorkspaces?: Readonly<Record<string, AgentSessionWorkspace>>;
     /** UTF-8 files returned by `fs.external.readTextFileChunks`. Defaults to none. */
     externalTextFiles?: TestingExternalTextFile[];
 }
@@ -56,7 +65,6 @@ export interface TestingOpenForgeApiCalls {
     }>;
     openUrl: string[];
     clipboardWrites: string[];
-    taskLinkOpenRequests: TaskLinkOpenRequest[];
     navigationRequests: OpenForgeNavigationRequest[];
     notify: NotificationRequest[];
     taskCreations: CreateTaskRequest[];
@@ -68,6 +76,8 @@ export interface TestingOpenForgeApiCalls {
         projectId: string | null;
         includeDone: boolean;
     }>;
+    agentSessionListRequests: ListAgentSessionsRequest[];
+    taskSessionListRequests: ListTaskSessionsRequest[];
     taskStatusUpdates: Array<{
         taskId: string;
         status: string;
@@ -85,8 +95,10 @@ export interface TestingOpenForgeApiCalls {
     fsUserDataReadDirs: UserDataDirectoryRequest[];
     fsUserDataReads: UserDataFileRequest[];
     fsUserDataWrites: UserDataFileWriteRequest[];
+    fsUserDataAppends: UserDataFileWriteRequest[];
     fsExternalReadDirs: ExternalReadDirectoryRequest[];
     fsExternalReads: ExternalReadFileRequest[];
+    fsExternalStats: ExternalReadFileRequest[];
     fsExternalReadTextFileChunks: TestingExternalTextFileChunksCall[];
     shellSpawns: ShellSpawnRequest[];
     shellWrites: Array<{

package/dist/testing/frontendContributionFake.d.ts

@@ -1,8 +1,8 @@
-import { type TaskBrowserSurfaceState } from '../browserSurfaces.js';
+import type { TaskBrowserSurfaceState } from '../browserSurfaces';
 import type { FrontendOpenForgeAPI } from '../types';
 import { type TestingRegistryServices } from './support.js';
 import type { TestingInjectionPointContribution, TestingTaskStartPrefixProviderContribution, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingReviewRowActionContribution, TestingTaskUISectionContribution, TestingViewContribution } from './contracts';
-type TestingFrontendContributionApi = Pick<FrontendOpenForgeAPI, 'browserSurfaces' | 'taskLinks' | 'views' | 'taskUI' | 'reviewUI' | 'taskPane' | 'settings' | 'backend' | 'injectionPoints' | 'taskStart'>;
+type TestingFrontendContributionApi = Pick<FrontendOpenForgeAPI, 'browserSurfaces' | 'views' | 'taskUI' | 'reviewUI' | 'taskPane' | 'settings' | 'backend' | 'injectionPoints' | 'taskStart'>;
 export declare class TestingFrontendContributionFake {
     private readonly services;
     private readonly invokeBackendMethod;
@@ -14,7 +14,6 @@ export declare class TestingFrontendContributionFake {
     private readonly injectionPoints;
     private readonly taskStartPrefixProviders;
     private readonly browserSurfaces;
-    private taskLinkHandler;
     private api;
     constructor(services: TestingRegistryServices, invokeBackendMethod: (method: string, payload?: unknown) => Promise<unknown>);
     createApi(): TestingFrontendContributionApi;

package/dist/testing/frontendContributionFake.js

@@ -1,5 +1,4 @@
 import { createTestingBrowserSurfaces } from '../browserSurfacesTesting.js';
-import { isAllowedBrowserSurfaceUrl } from '../browserSurfaces.js';
 import { assertFunction, assertTitle, createDisposable, } from './support.js';
 export class TestingFrontendContributionFake {
     services;
@@ -12,7 +11,6 @@ export class TestingFrontendContributionFake {
     injectionPoints = new Map();
     taskStartPrefixProviders = new Map();
     browserSurfaces;
-    taskLinkHandler = null;
     api = null;
     constructor(services, invokeBackendMethod) {
         this.services = services;
@@ -24,36 +22,6 @@ export class TestingFrontendContributionFake {
             return this.api;
         const api = {
             browserSurfaces: this.browserSurfaces.api,
-            taskLinks: {
-                open: async (request) => {
-                    this.services.calls.taskLinkOpenRequests.push(request);
-                    if (!isAllowedBrowserSurfaceUrl(request.url)) {
-                        throw new Error('Task links must use a valid HTTP(S) URL');
-                    }
-                    if (this.taskLinkHandler === null) {
-                        this.services.calls.openUrl.push(request.url);
-                        return;
-                    }
-                    const result = await this.taskLinkHandler(request);
-                    if (result === 'declined') {
-                        this.services.calls.openUrl.push(request.url);
-                        return;
-                    }
-                    if (result !== 'handled') {
-                        throw new Error(`Task link handler returned an invalid result: ${String(result)}`);
-                    }
-                },
-                registerHandler: (handler) => {
-                    if (this.taskLinkHandler !== null) {
-                        throw new Error('A Task link handler is already registered');
-                    }
-                    this.taskLinkHandler = handler;
-                    return createDisposable(() => {
-                        if (this.taskLinkHandler === handler)
-                            this.taskLinkHandler = null;
-                    });
-                },
-            },
             views: {
                 register: (registration) => this.registerView(registration),
             },

package/dist/testing/support.d.ts

@@ -1,5 +1,5 @@
-import type { AgentCommandMetadata, CommandDescriptor, Disposable, JsonValue, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, PluginStorage, StartPromptContribution, SubscriptionSink } from '../types';
-import type { Task } from '../domain';
+import type { AgentSessionWorkspace, AgentCommandMetadata, CommandDescriptor, Disposable, JsonValue, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, PluginStorage, StartPromptContribution, SubscriptionSink } from '../types';
+import type { AgentSession, Task } 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,7 +31,10 @@ export declare class TestingRegistryServices {
     readonly storage: PluginStorage;
     readonly config: Map<string, JsonValue>;
     readonly seededTasks: Task[];
+    readonly seededAgentSessions: AgentSession[];
+    readonly agentSessionWorkspaces: Readonly<Record<string, AgentSessionWorkspace>>;
     readonly externalTextFiles: TestingExternalTextFile[];
+    readonly userDataTextFiles: Map<string, string>;
     readonly claims: TestingContributionClaims;
     constructor(options?: TestingOpenForgeApiOptions);
     localQualifiedId(kind: TestingRuntimeKind, id: string): string;

package/dist/testing/support.js

@@ -36,7 +36,6 @@ export function createTestingCalls() {
         emittedGlobalEvents: [],
         openUrl: [],
         clipboardWrites: [],
-        taskLinkOpenRequests: [],
         navigationRequests: [],
         notify: [],
         taskCreations: [],
@@ -45,14 +44,18 @@ export function createTestingCalls() {
         taskImplementationStarts: [],
         taskFollowUps: [],
         taskListRequests: [],
+        agentSessionListRequests: [],
+        taskSessionListRequests: [],
         taskStatusUpdates: [],
         configWrites: [],
         fsWrites: [],
         fsUserDataReadDirs: [],
         fsUserDataReads: [],
         fsUserDataWrites: [],
+        fsUserDataAppends: [],
         fsExternalReadDirs: [],
         fsExternalReads: [],
+        fsExternalStats: [],
         fsExternalReadTextFileChunks: [],
         shellSpawns: [],
         shellWrites: [],
@@ -202,7 +205,10 @@ export class TestingRegistryServices {
     storage;
     config = new Map();
     seededTasks;
+    seededAgentSessions;
+    agentSessionWorkspaces;
     externalTextFiles;
+    userDataTextFiles = new Map();
     claims = new TestingContributionClaims();
     constructor(options = {}) {
         this.pluginId = options.pluginId ?? 'test-plugin';
@@ -218,7 +224,12 @@ export class TestingRegistryServices {
         this.calls = createTestingCalls();
         this.storage = options.storage ?? createMemoryPluginStorage(this.calls);
         this.seededTasks = options.tasks ?? [];
+        this.seededAgentSessions = options.agentSessions ?? [];
+        this.agentSessionWorkspaces = options.agentSessionWorkspaces ?? {};
         this.externalTextFiles = options.externalTextFiles ?? [];
+        for (const file of options.userDataTextFiles ?? []) {
+            this.userDataTextFiles.set(file.path, file.content);
+        }
     }
     localQualifiedId(kind, id) {
         assertLocalId(kind, id);

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { Component } from 'svelte';
 import type { BrowserSurfacesAPI } from './browserSurfaces';
-import type { AgentSession, CommandInfo, FileContent, FileEntry, Project, ProjectAttention, ReviewPullRequest, Task, TaskWorkspaceInfo, WritableBoardStatus } from './domain';
+import type { BoardStatus, AgentSession, CommandInfo, FileContent, FileEntry, Project, ProjectAttention, ReviewPullRequest, Task, TaskWorkspaceInfo, 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;
@@ -17,7 +17,7 @@ export interface ValidationError {
     path: string;
     message: string;
 }
-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', 'reviewUI'];
+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', 'appEnablement', 'customSidebarNavigation', 'reviewUI'];
 export type OpenForgePluginCapability = (typeof OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS)[number];
 export interface OpenForgePackageMetadata {
     id: string;
@@ -74,16 +74,6 @@ export interface NavigationAPI {
     get(): OpenForgeNavigationSnapshot;
     navigate(request: OpenForgeNavigationRequest): Promise<OpenForgeNavigationSnapshot>;
 }
-export interface TaskLinkOpenRequest {
-    taskId: string;
-    url: string;
-}
-export type TaskLinkHandlerResult = 'handled' | 'declined';
-export type TaskLinkHandler = (request: TaskLinkOpenRequest) => Promise<TaskLinkHandlerResult>;
-export interface TaskLinksAPI {
-    open(request: TaskLinkOpenRequest): Promise<void>;
-    registerHandler(handler: TaskLinkHandler): Disposable;
-}
 export interface OpenForgePluginContext {
     pluginId: string;
     apiVersion: SupportedOpenForgeApiVersion;
@@ -409,6 +399,9 @@ export interface UserDataFileRequest {
 export interface UserDataFileWriteRequest extends UserDataFileRequest {
     content: string;
 }
+export interface UserDataFileAppendResult {
+    sizeBytes: number;
+}
 export interface ExternalReadDirectoryRequest {
     root: string;
     path?: string | null;
@@ -417,6 +410,12 @@ export interface ExternalReadFileRequest {
     root: string;
     path: string;
 }
+export interface ExternalFileMetadata {
+    /** Stable while the same filesystem object is appended in place. */
+    identity: string;
+    sizeBytes: number;
+    modifiedAtMs: number | null;
+}
 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;
@@ -425,17 +424,27 @@ export declare function resolveExternalTextFileChunkSize(chunkSizeBytes?: number
 export interface ExternalReadTextFileChunksRequest extends ExternalReadFileRequest {
     /** UTF-8 chunks contain at most this many bytes. Defaults to 64 KiB. */
     chunkSizeBytes?: number;
+    /** First byte to read. Must be a UTF-8 code point boundary. Defaults to zero. */
+    startOffsetBytes?: number;
+    /** Maximum total bytes to read. The range end must be a UTF-8 code point boundary. */
+    maxBytes?: number;
+    /** Fails the read if the file no longer has this identity. */
+    expectedIdentity?: string;
     /** 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>;
+    /** Atomically replaces the file and syncs its contents before resolving. */
     writeTextFile(request: UserDataFileWriteRequest): Promise<void>;
+    /** Appends and syncs content before returning the resulting UTF-8 byte size. */
+    appendTextFile(request: UserDataFileWriteRequest): Promise<UserDataFileAppendResult>;
 }
 export interface ExternalReadFileSystemAPI {
     readDir(request: ExternalReadDirectoryRequest): Promise<FileEntry[]>;
     readTextFile(request: ExternalReadFileRequest): Promise<string>;
+    stat(request: ExternalReadFileRequest): Promise<ExternalFileMetadata>;
     /** Lazily reads a UTF-8 file without retaining a host file handle between chunks. */
     readTextFileChunks(request: ExternalReadTextFileChunksRequest): AsyncIterable<string>;
 }
@@ -457,10 +466,6 @@ export interface ShellSpawnRequest extends ShellSessionRequest {
 export interface ShellWriteRequest extends ShellSessionRequest {
     data: string;
 }
-export interface ShellTerminalQueryResponseRequest extends ShellSessionRequest {
-    ptyInstanceId: number;
-    data: string;
-}
 export interface ShellResizeRequest extends ShellSessionRequest {
     cols: number;
     rows: number;
@@ -469,9 +474,9 @@ export interface TerminalViewSnapshot {
     instanceId: number;
     watermark: number;
     data: string;
+    compatibilityData?: string;
 }
 export interface PtyBufferState {
-    authority?: 'xterm-authoritative' | 'ghostty-authoritative';
     buffer: string | null;
     snapshot?: TerminalViewSnapshot | null;
     isLive: boolean;
@@ -480,7 +485,6 @@ export interface PtyBufferState {
 export interface ShellAPI {
     spawn(request: ShellSpawnRequest): Promise<number>;
     write(request: ShellWriteRequest): Promise<void>;
-    writeTerminalQueryResponse(request: ShellTerminalQueryResponseRequest): Promise<void>;
     resize(request: ShellResizeRequest): Promise<void>;
     kill(request: ShellSessionRequest): Promise<void>;
     getBuffer(request: ShellSessionRequest): Promise<PtyBufferState>;
@@ -542,6 +546,61 @@ export declare class TaskFollowUpError extends Error {
     readonly code: TaskFollowUpErrorCode;
     constructor(code: TaskFollowUpErrorCode, message: string);
 }
+export interface ListTaskSessionsRequest {
+    taskId: string;
+    /** Inclusive Unix timestamp in seconds. Omit to return the Task's full Agent Session history. */
+    createdAtOrAfter?: number;
+    /** Open-ended provider identifier such as `pi`. Omit to include every provider. */
+    provider?: string;
+}
+export declare const MAX_AGENT_SESSION_PAGE_SIZE = 250;
+export type AgentSessionCursor = string;
+export interface AgentSessionOverlap {
+    /** Inclusive lower bound as a Unix timestamp in seconds. */
+    startInclusive: number;
+    /** Exclusive upper bound as a Unix timestamp in seconds. */
+    endExclusive: number;
+}
+export interface ListAgentSessionsRequest {
+    /** Open-ended provider identifier such as `pi`. */
+    provider: string;
+    overlaps: AgentSessionOverlap;
+    /** Restrict the query to one Task without enumerating unrelated Tasks. */
+    taskId?: string;
+    /** Opaque cursor returned by the preceding page. */
+    cursor?: AgentSessionCursor;
+    /** Number of Agent Sessions to return, from 1 through 250. */
+    pageSize: number;
+}
+export interface AgentSessionTaskSummary {
+    id: string;
+    title: string;
+    status: BoardStatus;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface AgentSessionWorkspace {
+    rootPath: string;
+    kind: 'project' | 'worktree';
+}
+export interface AgentSessionSummary {
+    /** OpenForge Agent Session ID. */
+    id: string;
+    provider: string;
+    /** Provider-owned Agent Session ID, or null when the host has none. */
+    providerSessionId: string | null;
+    createdAt: number;
+    updatedAt: number;
+    task: AgentSessionTaskSummary;
+    workspace: AgentSessionWorkspace | null;
+}
+export interface AgentSessionSummaryPage {
+    items: AgentSessionSummary[];
+    nextCursor: AgentSessionCursor | null;
+}
+export interface AgentSessionsAPI {
+    list(request: ListAgentSessionsRequest): Promise<AgentSessionSummaryPage>;
+}
 export interface TasksAPI {
     /**
      * Lists tasks, optionally scoped to a project. By default done tasks are
@@ -570,6 +629,8 @@ export interface TasksAPI {
     sendFollowUp(request: SendTaskFollowUpRequest): Promise<TaskFollowUpReceipt>;
     getWorkspace(taskId: string): Promise<TaskWorkspaceInfo | null>;
     getLatestSession(taskId: string): Promise<AgentSession | null>;
+    /** Returns matching Agent Sessions newest first. */
+    listSessions(request: ListTaskSessionsRequest): Promise<AgentSession[]>;
 }
 export interface ProjectsAPI {
     list(): Promise<Project[]>;
@@ -601,6 +662,7 @@ export interface OpenForgeCommonAPI {
     context: {
         getSnapshot(): OpenForgeContextSnapshot;
     };
+    agentSessions: AgentSessionsAPI;
     tasks: TasksAPI;
     projects: ProjectsAPI;
     fs: FileSystemAPI;
@@ -613,7 +675,6 @@ export interface OpenForgeCommonAPI {
 }
 export interface FrontendOpenForgeAPI extends OpenForgeCommonAPI {
     browserSurfaces: BrowserSurfacesAPI;
-    taskLinks: TaskLinksAPI;
     navigation: NavigationAPI;
     views: FrontendViewRegistry;
     taskUI: FrontendTaskUIRegistry;