subharness 0.0.4 → 0.0.7

package/dist/runtime/coordinator.js

@@ -5,32 +5,51 @@ import { terminal } from './types.js';
 import { dashboardHarness, dashboardTitle } from './dashboard.js';
 import { resolveDashboardWorkspace } from './dashboard-workspace.js';
 import { ApprovalRegistry } from './approval-registry.js';
+import { createSnapshotWatch, detached } from './snapshots.js';
+import { paginate } from './pagination.js';
+import { responseReplay, terminalInterval } from './sdk-observation.js';
+import { sdkSessionSummary as projectSessionSummary, sdkTaskSnapshot as projectTaskSnapshot, sdkTaskSummary as projectTaskSummary } from './sdk-projection.js';
 export class Coordinator {
     factory;
     now;
+    instanceId;
     sessions = new Map();
     tasks = new Map();
     dashboardHistory;
     closed = false;
+    closeComplete = false;
+    closePromise;
+    membership = 0;
     approvals = new ApprovalRegistry(id => this.approvalChanged(this.task(id)));
-    constructor(factory, now = Date.now) {
+    constructor(factory, now = Date.now, instanceId = randomUUID()) {
         this.factory = factory;
         this.now = now;
+        this.instanceId = instanceId;
     }
     parentContext(token) {
         const session = [...this.sessions.values()].find(session => session.token === token);
         const task = session?.active ? this.task(session.active) : undefined;
         if (!session || !task || task.stopping || terminal(task.state))
             throw new AgentError('INVALID_PARENT', 'The parent context is no longer active.');
-        return { taskId: task.id, reference: session.input.reference, cwd: session.input.cwd };
+        return { taskId: task.id, sessionId: session.id, reference: session.input.reference, cwd: session.input.cwd };
     }
-    run(input) {
-        this.validateAdmission(undefined, input.prompt, input.parentToken);
-        const selected = 'kind' in input.reference ? input.reference.harness.kind : undefined;
+    createSession(input, prepared) {
+        if (this.closed)
+            throw new AgentError('COORDINATOR_UNAVAILABLE', 'The coordinator is shutting down.');
+        const selected = 'kind' in input.reference && input.reference.kind === 'harness'
+            ? input.reference.harness.kind : undefined;
         const session = { id: `ses_${randomUUID()}`, token: randomUUID(), input,
-            tasks: [], paused: false, commands: Promise.resolve(), controls: 0, harness: dashboardHarness(selected),
-            workspace: resolveDashboardWorkspace(input.cwd) };
+            tasks: [], paused: false, commands: Promise.resolve(), controls: 0, nextOrdinal: 1,
+            membership: ++this.membership, prepared,
+            harness: dashboardHarness(selected), workspace: 'kind' in input.reference && input.reference.kind === 'inline'
+                ? Promise.resolve({ directory: input.cwd }) : resolveDashboardWorkspace(input.cwd), state: 'open' };
         this.sessions.set(session.id, session);
+        return session.id;
+    }
+    run(input, prepared) {
+        this.validateAdmission(undefined, input.prompt, input.parentToken);
+        const { prompt, parentToken, ...creation } = input;
+        const session = this.session(this.createSession(creation, prepared));
         return this.admit(session, input.prompt, false, input.parentToken);
     }
     async send(id, prompt, delivery, parentToken) {
@@ -68,26 +87,30 @@ export class Coordinator {
         return this.command(session, operation);
     }
     async observe(id, after, readerToken, signal) {
+        if (signal?.aborted)
+            throw new AgentError('OBSERVATION_CLOSED', 'The observer disconnected.');
         const task = this.task(id);
-        const position = after ? task.responses.findIndex(response => response.responseId === after) : -1;
-        if (after && position === -1)
+        const hasCursor = after !== undefined;
+        const position = hasCursor ? task.responses.findIndex(response => response.responseId === after) : -1;
+        if (hasCursor && position === -1)
             throw new AgentError('UNKNOWN_RESPONSE', 'The response does not belong to this task.');
         for (;;) {
             const response = task.responses[position + 1];
             if (response) {
                 if (terminal(response.state))
                     this.acknowledge(task, readerToken);
-                return response;
+                return detached(response);
             }
             if (terminal(task.state)) {
                 this.acknowledge(task, readerToken);
-                return { version: 1, type: 'terminal', taskId: id,
-                    sessionId: task.sessionId, state: task.state, ...(task.error ? { error: task.error } : {}) };
+                return detached({ version: 1, type: 'terminal', taskId: id,
+                    sessionId: task.sessionId, state: task.state, ...(task.error ? { error: task.error } : {}),
+                    stopUnconfirmed: task.stopUnconfirmed ?? false });
             }
             const requests = this.pendingApprovals(task);
             if (requests.length)
-                return { version: 1, type: 'approval_required', taskId: id,
-                    sessionId: task.sessionId, state: task.state, requests };
+                return detached({ version: 1, type: 'approval_required', taskId: id,
+                    sessionId: task.sessionId, state: task.state, requests });
             await waitForChange(task.changed, signal);
         }
     }
@@ -108,6 +131,94 @@ export class Coordinator {
                     truncated: !full && response.text.length > 4000
                 } } : {}) };
     }
+    snapshot(id) {
+        const task = this.task(id);
+        const response = task.responses.at(-1);
+        return detached({
+            ...this.summary(task),
+            revision: task.revision,
+            ...(task.parentId ? { parentTaskId: task.parentId } : {}),
+            children: [...task.children].map(childId => this.summary(this.task(childId))),
+            requests: this.pendingApprovals(task),
+            ...(response ? { latestResponse: { responseId: response.responseId, text: response.text, state: response.state } } : {}),
+            ...(task.error ? { error: task.error } : {}),
+            stopUnconfirmed: task.stopUnconfirmed ?? false,
+        });
+    }
+    sessionSnapshot(id) {
+        const session = this.session(id);
+        return detached({
+            sessionId: session.id,
+            state: session.state,
+            paused: session.paused,
+            ...(session.active ? { active: this.summary(this.task(session.active)) } : {}),
+            queued: session.tasks.map(taskId => this.summary(this.task(taskId))),
+        });
+    }
+    sdkTaskSnapshot(id) {
+        const task = this.task(id);
+        return detached(projectTaskSnapshot(task, candidate => this.sdkSummary(candidate), candidate => this.task(candidate), this.sdkPendingApprovals(task)));
+    }
+    async sdkSessionSnapshot(id) {
+        const session = this.session(id);
+        const workspace = await session.workspace;
+        return detached({ ...this.sdkSessionSummaryResolved(session, workspace),
+            queued: session.tasks.map(taskId => this.sdkSummary(this.task(taskId))) });
+    }
+    taskDetails(id) {
+        const task = this.task(id);
+        return detached({ ...this.sdkTaskSnapshot(id), prompt: task.prompt });
+    }
+    taskResult(id, signal) {
+        const task = this.task(id);
+        return terminalInterval(task, () => this.sdkTaskSnapshot(id), signal).then(({ snapshot, response }) => {
+            if (snapshot.state === 'completed') {
+                if (!response)
+                    throw new AgentError('HARNESS_FAILED', 'The completed task has no final response.');
+                return detached({ taskId: task.id, sessionId: task.sessionId, responseId: response.responseId, text: response.text });
+            }
+            if (snapshot.state === 'cancelled')
+                throw new AgentError('CANCELLED', 'The task was cancelled.');
+            if (snapshot.state === 'interrupted')
+                throw new AgentError('INTERRUPTED', 'The task was interrupted.');
+            throw new AgentError(snapshot.error?.code ?? 'HARNESS_FAILED', snapshot.error?.message ?? 'Task execution failed.');
+        });
+    }
+    taskResponses(id, after, signal) {
+        const task = this.task(id);
+        const start = after === undefined ? 0 : task.responses.findIndex(response => response.responseId === after) + 1;
+        if (after !== undefined && start === 0)
+            throw new AgentError('UNKNOWN_RESPONSE', 'The response does not belong to this task.');
+        return responseReplay(task, start, signal);
+    }
+    watchTask(id, signal) {
+        const task = this.task(id);
+        return createSnapshotWatch(() => this.sdkTaskSnapshot(id), changed => {
+            task.watchers.add(changed);
+            return () => task.watchers.delete(changed);
+        }, signal);
+    }
+    async listSessions(options) {
+        const page = paginate([...this.sessions.values()], options, { instance: this.instanceId, collection: 'sessions', filter: '' }, value => value.membership);
+        return detached({ items: await Promise.all(page.items.map(session => this.sdkSessionSummary(session))),
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}) });
+    }
+    listTasks(options) {
+        const sessionId = options?.sessionId;
+        if (sessionId !== undefined)
+            this.session(sessionId);
+        const candidates = [...this.tasks.values()].filter(task => sessionId === undefined || task.sessionId === sessionId);
+        const page = paginate(candidates, options, { instance: this.instanceId, collection: 'tasks', filter: sessionId ?? '' }, value => value.membership);
+        return detached({ items: page.items.map(task => this.sdkSummary(task)), ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}) });
+    }
+    respondSdk(id, response) { return this.approvals.respondSdk(id, response); }
+    watch(id, signal) {
+        const task = this.task(id);
+        return createSnapshotWatch(() => this.snapshot(task.id), changed => {
+            task.watchers.add(changed);
+            return () => task.watchers.delete(changed);
+        }, signal);
+    }
     respond(id, content, parentToken) {
         const request = this.approvals.request(id);
         if (parentToken !== undefined) {
@@ -245,13 +356,92 @@ export class Coordinator {
             return { version: 1, type: 'started', sessionId: id, taskId: task.id, state: task.state, resumed: true };
         });
     }
-    async close() {
+    close() {
         this.closed = true;
-        for (const task of this.tasks.values())
-            if (!terminal(task.state))
-                task.stopping = true;
         this.approvals.close();
-        await Promise.allSettled([...this.sessions.values()].map(async (session) => (await session.driver)?.close()));
+        if (this.closeComplete)
+            return Promise.resolve();
+        if (this.closePromise)
+            return this.closePromise;
+        const attempt = (async () => {
+            const results = await Promise.allSettled([...this.sessions].map(([id]) => this.closeSession(id)));
+            const failures = results.flatMap(result => result.status === 'rejected'
+                ? this.cleanupErrors(result.reason, 'Runner cleanup could not be confirmed.') : []);
+            if (failures.length)
+                throw new AggregateError(failures, 'Coordinator cleanup failed.');
+            this.closeComplete = true;
+        })();
+        this.closePromise = attempt.finally(() => { this.closePromise = undefined; });
+        return this.closePromise;
+    }
+    closeSession(id) {
+        const session = this.session(id);
+        if (session.state === 'closed')
+            return Promise.resolve();
+        if (session.closePromise)
+            return session.closePromise;
+        session.state = 'closing';
+        const attempt = this.cleanupSession(session);
+        session.closePromise = attempt.finally(() => { session.closePromise = undefined; });
+        return session.closePromise;
+    }
+    async cleanupSession(session) {
+        const targets = [...this.tasks.values()].filter(task => task.sessionId === session.id &&
+            (!terminal(task.state) || task.stopUnconfirmed));
+        let preparedFailure = false;
+        const preparedClose = !session.preparedClosed && session.prepared
+            ? session.prepared.close().then(() => { session.preparedClosed = true; }, () => { preparedFailure = true; })
+            : Promise.resolve();
+        let stopped = await Promise.allSettled(targets.map(task => this.stop(task, 'cancelled')));
+        await session.commands.catch(() => undefined);
+        let driverClosedDuringAttempt = false;
+        const failures = [];
+        if (!session.driverClosed && session.driver) {
+            let driver;
+            try {
+                driver = await session.driver;
+            }
+            catch {
+                session.driverClosed = true;
+                driverClosedDuringAttempt = true;
+            }
+            if (driver) {
+                try {
+                    await driver.close();
+                    session.driverClosed = true;
+                    driverClosedDuringAttempt = true;
+                    for (const task of this.tasks.values())
+                        if (task.sessionId === session.id)
+                            task.nativeActive = false;
+                }
+                catch {
+                    failures.push(new AgentError('HARNESS_FAILED', 'Native session cleanup could not be confirmed.'));
+                }
+            }
+        }
+        await preparedClose;
+        if (preparedFailure)
+            failures.push(new AgentError('HARNESS_FAILED', 'Prepared execution cleanup could not be confirmed.'));
+        if ((driverClosedDuringAttempt || session.preparedClosed) && stopped.some(result => result.status === 'rejected')) {
+            const retry = targets.filter(task => task.stopUnconfirmed);
+            stopped = await Promise.allSettled(retry.map(task => this.stop(task, 'cancelled')));
+        }
+        failures.push(...stopped.flatMap(result => result.status === 'rejected'
+            ? [new AgentError('CANCEL_FAILED', 'Task execution could not be confirmed stopped.')] : []));
+        if (failures.length)
+            throw new AggregateError(failures, 'Session cleanup failed.');
+        session.paused = false;
+        session.state = 'closed';
+    }
+    cleanupErrors(reason, message) {
+        if (reason instanceof AggregateError) {
+            const errors = [...reason.errors];
+            return errors.length ? errors.map(error => error instanceof AgentError
+                ? new AgentError(error.code, error.message) : new AgentError('HARNESS_FAILED', message)) : [];
+        }
+        return [reason instanceof AgentError
+                ? new AgentError(reason.code, reason.message)
+                : new AgentError('HARNESS_FAILED', message)];
     }
     async cancel(id) {
         const task = this.task(id);
@@ -297,7 +487,7 @@ export class Coordinator {
                 stops.push(session.driver.then(async (driver) => {
                     await driver.interrupt();
                     task.nativeActive = false;
-                }));
+                }, () => { task.nativeActive = false; }));
             const outcomes = await Promise.allSettled(stops);
             if (outcomes.some(outcome => outcome.status === 'rejected'))
                 throw new Error('Cancellation unconfirmed');
@@ -308,7 +498,7 @@ export class Coordinator {
             task.error = { code: 'CANCEL_FAILED', message: 'Native execution could not be confirmed stopped.' };
             task.stopUnconfirmed = true;
             session.paused = true;
-            this.notify(task);
+            this.publish(task);
             throw new AgentError('CANCEL_FAILED', task.error.message);
         }
         task.nativeActive = false;
@@ -319,7 +509,7 @@ export class Coordinator {
             session.active = undefined;
             session.paused = false;
         }
-        this.notify(task);
+        this.publish(task);
         this.deliver(task);
     }
     admit(session, prompt, front = false, parentToken) {
@@ -327,9 +517,12 @@ export class Coordinator {
         const blockedByTaskId = session.paused ? session.active : undefined;
         const task = { id: `tsk_${randomUUID()}`, sessionId: session.id, prompt, title: dashboardTitle(prompt),
             parentId: parent?.id, state: 'queued', responses: [], children: new Set(), inbox: [], nativeActive: false,
-            stopping: false, updatedAt: this.now(), changed: new Set() };
+            stopping: false, updatedAt: this.now(), revision: 1, ordinal: session.nextOrdinal++, membership: ++this.membership,
+            changed: new Set(), watchers: new Set() };
         this.tasks.set(task.id, task);
         parent?.children.add(task.id);
+        if (parent)
+            this.publish(parent);
         if (front)
             session.tasks.unshift(task.id);
         else
@@ -341,6 +534,8 @@ export class Coordinator {
     validateAdmission(session, prompt, parentToken, replacement = false) {
         if (this.closed)
             throw new AgentError('COORDINATOR_UNAVAILABLE', 'The coordinator is shutting down.');
+        if (session && session.state !== 'open')
+            throw new AgentError('SESSION_CLOSED', 'The session is closing or closed.');
         if (typeof prompt !== 'string' || !prompt.trim() || Buffer.byteLength(prompt) > 1024 * 1024)
             throw new AgentError('INVALID_ARGUMENT', 'Prompt must contain text and cannot exceed 1 MiB.');
         if (!replacement && session && session.tasks.length >= 100)
@@ -358,7 +553,7 @@ export class Coordinator {
         return parent;
     }
     dispatch(session) {
-        if (this.closed || session.active || session.paused || session.controls)
+        if (this.closed || session.state !== 'open' || session.active || session.paused || session.controls)
             return;
         const id = session.tasks.shift();
         if (!id)
@@ -370,11 +565,13 @@ export class Coordinator {
         const session = this.session(task.sessionId);
         const dispatchedAt = this.now();
         task.dispatchedAt ??= dispatchedAt;
-        this.touch(task, dispatchedAt);
         task.state = 'running';
         task.nativeActive = true;
+        this.touch(task, dispatchedAt);
+        this.publish(task);
         try {
-            session.driver ??= this.factory({ ...session.input, sessionId: session.id, token: session.token,
+            const open = session.prepared ? session.prepared.open.bind(session.prepared) : this.factory;
+            session.driver ??= open({ ...session.input, sessionId: session.id, token: session.token,
                 onApproval: async (request, signal) => {
                     const active = session.active ? this.task(session.active) : undefined;
                     if (this.closed || !active || active.stopping || !active.nativeActive || terminal(active.state))
@@ -384,9 +581,13 @@ export class Coordinator {
             const driver = await session.driver;
             if (driver.selectedHarness) {
                 const harness = dashboardHarness(driver.selectedHarness);
-                if (session.harness !== harness) {
+                if (session.selectedHarness !== driver.selectedHarness) {
+                    session.selectedHarness = driver.selectedHarness;
                     session.harness = harness;
                     this.touch(task);
+                    for (const candidate of this.tasks.values())
+                        if (candidate.sessionId === session.id)
+                            this.publish(candidate);
                 }
             }
             if (task.stopping)
@@ -406,7 +607,7 @@ export class Coordinator {
                 this.touch(task, respondedAt);
             task.responses.push({ version: 1, type: 'response', sessionId: session.id, taskId: task.id,
                 responseId: `rsp_${randomUUID()}`, state: task.state, text });
-            this.notify(task);
+            this.publish(task);
             if (task.state === 'completed') {
                 session.active = undefined;
                 this.deliver(task);
@@ -428,7 +629,7 @@ export class Coordinator {
             task.error = task.stopUnconfirmed
                 ? { code: 'CANCEL_FAILED', message: 'Descendant execution could not be confirmed stopped.' } : errorInfo(error);
             session.paused = true;
-            this.notify(task);
+            this.publish(task);
             this.deliver(task);
         }
     }
@@ -454,7 +655,34 @@ export class Coordinator {
             results.map(result => `${result.taskId} [${result.state}]:\n${result.text}`).join('\n\n');
         void this.execute(task, prompt);
     }
+    summary(task) {
+        const selectedHarness = this.session(task.sessionId).selectedHarness;
+        return { taskId: task.id, sessionId: task.sessionId, state: task.state,
+            ...(selectedHarness ? { selectedHarness } : {}) };
+    }
+    sdkSummary(task) {
+        return projectTaskSummary(task, this.session(task.sessionId).selectedHarness);
+    }
+    async sdkSessionSummary(session) {
+        const workspace = await session.workspace;
+        return this.sdkSessionSummaryResolved(session, workspace);
+    }
+    sdkSessionSummaryResolved(session, workspace) {
+        return projectSessionSummary(session, workspace, task => this.sdkSummary(task), id => this.task(id));
+    }
+    sdkPendingApprovals(task) {
+        return [...this.approvals.sdkPendingFor(task.id),
+            ...[...task.children].flatMap(id => this.sdkPendingApprovals(this.task(id)))];
+    }
     touch(task, at = this.now()) { task.updatedAt = at; }
+    publish(task) {
+        let current = task;
+        while (current) {
+            current.revision++;
+            this.notify(current);
+            current = current.parentId ? this.task(current.parentId) : undefined;
+        }
+    }
     pendingApprovals(task) {
         return [...this.approvals.pendingFor(task.id), ...[...task.children].flatMap(id => this.pendingApprovals(this.task(id)))];
     }
@@ -464,12 +692,18 @@ export class Coordinator {
         this.touch(task);
         let current = task;
         while (current) {
+            current.revision++;
             this.notify(current);
             current = current.parentId ? this.task(current.parentId) : undefined;
         }
     }
-    notify(task) { for (const resolve of task.changed)
-        resolve(); task.changed.clear(); }
+    notify(task) {
+        for (const resolve of task.changed)
+            resolve();
+        task.changed.clear();
+        for (const update of task.watchers)
+            update();
+    }
     task(id) { const task = this.tasks.get(id); if (!task)
         throw new AgentError('UNKNOWN_TASK', 'Task is unavailable in this coordinator.'); return task; }
     session(id) { const session = this.sessions.get(id); if (!session)