@celljs/ta-web 0.0.0-stage → 4.6.0

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@celljs/ta-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.6.0",
+  "description": "The web client of ta serve: sessions, streaming messages, tool runs with diffs, and dialogs",
+  "keywords": [
+    "cell-component"
+  ],
+  "homepage": "https://github.com/cellbang/cell",
+  "bugs": {
+    "url": "https://github.com/cellbang/cell/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cellbang/cell.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "lib/browser/index.js",
+  "typings": "lib/browser/index.d.ts",
+  "files": [
+    "lib",
+    "esm",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -b && bun ../../scripts/build-esm.ts",
+    "clean": "rm -rf lib esm *.tsbuildinfo",
+    "test": "bun test --preload reflect-metadata ./lib",
+    "watch": "tsc -b -w --preserveWatchOutput"
+  },
+  "dependencies": {
+    "@celljs/core": "4.6.0",
+    "@celljs/react": "4.6.0",
+    "@celljs/ta-client": "4.6.0",
+    "@celljs/ta-protocol": "4.6.0",
+    "@celljs/ta-relay": "4.6.0",
+    "@celljs/widget": "4.6.0",
+    "katex": "^0.18.11",
+    "lucide-react": "^1.70.0",
+    "mermaid": "^12.3.0",
+    "monaco-editor": "^0.57.0",
+    "react": "^19.3.1",
+    "react-intl": "^7.1.14"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.5.0",
+    "@earendil-works/pi-coding-agent": "^1.5.0",
+    "@types/react": "^19.3.0",
+    "react-dom": "^19.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "cell": {
+    "modules": {
+      "frontend": [
+        "lib/browser/module"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "import": "./esm/browser/index.js",
+      "default": "./lib/browser/index.js"
+    },
+    "./package.json": "./package.json",
+    "./lib/browser": {
+      "import": "./esm/browser/index.js",
+      "default": "./lib/browser/index.js"
+    },
+    "./lib/*.js": {
+      "import": "./esm/*.js",
+      "default": "./lib/*.js"
+    },
+    "./lib/*": {
+      "import": "./esm/*.js",
+      "default": "./lib/*.js"
+    },
+    "./*": "./*"
+  }
+}

package/src/browser/assistant/assistant-export.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'bun:test';
+import type { SessionMessage } from '@celljs/ta-client';
+import { AssistantExport } from './assistant-export';
+
+const labels = { user: 'Me', ta: 'Rex', task: 'Task', status: (status: string) => status.toUpperCase() };
+
+describe('AssistantExport', () => {
+    it('writes what the user and the double said, and how each task ended', () => {
+        const messages = [
+            { role: 'user', content: 'Fix the tests' },
+            {
+                role: 'assistant',
+                content: [
+                    { type: 'thinking', thinking: '…' },
+                    { type: 'text', text: 'Started t1.' },
+                ],
+            },
+            { role: 'toolResult', content: [{ type: 'text', text: 'ok' }] },
+            { role: 'user', content: '<task_update id="t1" title="Fix the tests" status="done">\nAll green.\n</task_update>' },
+            { role: 'assistant', content: [{ type: 'toolCall', name: 'get_task' }] },
+        ] as unknown as SessionMessage[];
+        expect(AssistantExport.markdown(messages, labels)).toBe(
+            ['# Rex', '', '## Me', '', 'Fix the tests', '', '## Rex', '', 'Started t1.', '', '## Task · Fix the tests · DONE', '', 'All green.', ''].join('\n'),
+        );
+    });
+
+    it('has nothing to export before the double answered', () => {
+        expect(AssistantExport.markdown([{ role: 'user', content: 'hi' }] as unknown as SessionMessage[], labels)).toBeUndefined();
+    });
+});

package/src/browser/assistant/assistant-export.ts

@@ -0,0 +1,41 @@
+import type { SessionMessage } from '@celljs/ta-client';
+import { MessageUtil } from '../util/message';
+import type { AssistantTask } from './assistant-protocol';
+
+/** A message of how a task ended, which the double gets from its tasks (assistant.ts). */
+const TASK_UPDATE = /^<task_update id="[^"]+" title="([^"]*)" status="(\w+)">\n?([\s\S]*?)\n?<\/task_update>$/;
+
+export interface ExportLabels {
+    user: string;
+    /** The name of the double. */
+    ta: string;
+    task: string;
+    status(status: AssistantTask['status']): string;
+}
+
+export namespace AssistantExport {
+    /** The conversation with the double as Markdown: what the user and the double said, and how the tasks ended; undefined when the double has said nothing yet. */
+    export function markdown(messages: readonly SessionMessage[], labels: ExportLabels): string | undefined {
+        if (!messages.some(message => message.role === 'assistant')) {
+            return undefined;
+        }
+        const parts = [`# ${labels.ta}`];
+        for (const message of messages) {
+            if (message.role !== 'user' && message.role !== 'assistant') {
+                continue;
+            }
+            const text = MessageUtil.text(MessageUtil.blocks(message)).trim();
+            if (!text) {
+                continue;
+            }
+            const update = message.role === 'user' ? TASK_UPDATE.exec(text) : null;
+            if (update) {
+                const [, title, status, result] = update;
+                parts.push('', `## ${labels.task} · ${title} · ${labels.status(status as AssistantTask['status'])}`, '', result.trim());
+            } else {
+                parts.push('', `## ${message.role === 'user' ? labels.user : labels.ta}`, '', text);
+            }
+        }
+        return `${parts.join('\n')}\n`;
+    }
+}

package/src/browser/assistant/assistant-extension.spec.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it, mock } from 'bun:test';
+import type { WebEditor, WebExtensionAPI, WebView } from '../extension/web-extension-api';
+
+// The views need the page (the application of Cell reads `window`): only their names matter here.
+mock.module('./assistant-view', () => ({
+    ASSISTANT_NAME: 'assistant',
+    ASSISTANT_TASKS_VIEW: 'tasks',
+    AssistantPanel: () => null,
+    AssistantTasks: () => null,
+    AssistantTaskView: () => null,
+}));
+
+function setup(working = false) {
+    const views = new Map<string, WebView>();
+    const editors: WebEditor[] = [];
+    const asked: string[] = [];
+    const listeners: (() => void)[] = [];
+    const assistant = {
+        name: '',
+        prompt: 'Be brief.',
+        prompts: [] as string[],
+        stopped: 0,
+        store: () => ({ state: { working, messages: [] } }),
+        rename(name: string) {
+            assistant.name = name;
+            for (const listener of listeners) {
+                listener();
+            }
+        },
+        setPrompt: async (prompt: string) => void assistant.prompts.push(prompt),
+        stop: async () => void assistant.stopped++,
+    };
+    const notified: string[] = [];
+    const pi = {
+        ui: {
+            language: 'zh-CN',
+            openEditor: (editor: WebEditor) => editors.push(editor),
+            notify: (text: string) => notified.push(text),
+            input: async (title: string, _placeholder: string, options: { value: string }) => {
+                asked.push(`${title}:${options.value}`);
+                return '小绿';
+            },
+            editor: async (title: string, prefill: string) => {
+                asked.push(`${title}:${prefill}`);
+                return 'Be kind.';
+            },
+        },
+        registerView: (name: string, view: WebView) => views.set(name, view),
+    } as unknown as WebExtensionAPI;
+    const { AssistantWebExtension } = require('./assistant-extension') as typeof import('./assistant-extension');
+    const extension = new AssistantWebExtension();
+    Object.assign(extension, {
+        assistant,
+        persisted: { subscribe: (listener: () => void) => listeners.push(listener) },
+        workbench: { state: { server: { cwd: '/work' } } },
+    });
+    extension.activate(pi);
+    return { views, editors, asked, assistant, notified };
+}
+
+const settled = () => new Promise(resolve => setTimeout(resolve, 0));
+
+describe('AssistantWebExtension', () => {
+    it('shows its tasks in the workbench, and each task as a tab of it', () => {
+        const { views, editors } = setup();
+        expect([...views].map(([name, view]) => [name, view.location ?? 'page'])).toEqual([
+            ['assistant', 'page'],
+            ['tasks', 'panel'],
+        ]);
+        expect((views.get('tasks')?.title as () => string)()).toBe('分身的任务');
+        const list = (views.get('tasks')?.render as unknown as () => { props: { onOpen(task: object): void } })();
+        list.props.onOpen({ id: 't1', title: 'Fix the tests' });
+        list.props.onOpen({ id: 't1', title: 'Fix the tests' });
+        expect(editors.map(editor => [editor.id, editor.title])).toEqual([
+            ['assistant:task:t1', 'Fix the tests'],
+            ['assistant:task:t1', 'Fix the tests'],
+        ]);
+    });
+
+    it('has a … to stop, start over, rename, change its prompt, copy its directory and export, and its title is its name', async () => {
+        const { views, asked, assistant } = setup();
+        const page = () => views.get('assistant') as WebView;
+        const menu = () => page().menu?.() ?? [];
+        expect(menu().map(section => section.map(item => [item.key, item.label, !!item.disabled]))).toEqual([
+            [
+                ['stop', '停止', true],
+                ['restart', '重新开始', false],
+            ],
+            [
+                ['rename', '重命名', false],
+                ['prompt', '系统提示词', false],
+                ['copyCwd', '复制工作目录', false],
+            ],
+            [['export', '导出为 Markdown', false]],
+        ]);
+        expect((page().title as () => string)()).toBe('我的分身');
+        const first = page();
+        menu()[1][0].run();
+        await settled();
+        expect(asked).toEqual(['重命名:我的分身']);
+        // Renamed, the page is registered again, so that the lists show the new name.
+        expect(page()).not.toBe(first);
+        expect((page().title as () => string)()).toBe('小绿');
+        menu()[1][1].run();
+        await settled();
+        expect(asked[1]).toStartWith('系统提示词');
+        expect(asked[1]).toEndWith(':Be brief.');
+        expect(assistant.prompts).toEqual(['Be kind.']);
+    });
+
+    it('does not change the prompt while the double works, which would cut its run short', async () => {
+        const { views, assistant, notified } = setup(true);
+        const menu = (views.get('assistant') as WebView).menu?.() ?? [];
+        expect(menu[0][0].disabled).toBe(false);
+        menu[0][0].run();
+        menu[1][1].run();
+        await settled();
+        expect(assistant.stopped).toBe(1);
+        expect(assistant.prompts).toEqual([]);
+        expect(notified).toEqual(['分身正在工作，等它做完或先停止再改。']);
+    });
+});

package/src/browser/assistant/assistant-extension.ts

@@ -0,0 +1,137 @@
+import { Autowired, Component } from '@celljs/core';
+import { Bot, Copy, Download, ListTodo, Pencil, RotateCcw, ScrollText, Square } from 'lucide-react';
+import * as React from 'react';
+import type { WebExtensionAPI, WebExtensionFactory, WebMenuItem } from '../extension/web-extension-api';
+import { BuiltinWebExtension } from '../extension/web-extension-protocol';
+import { type MessageId, message } from '../i18n/messages';
+import { TaState } from '../state/state-protocol';
+import { TaWorkbench } from '../workbench-protocol';
+import { AssistantExport } from './assistant-export';
+import { type AssistantTask, TaAssistant } from './assistant-protocol';
+import { ASSISTANT_NAME, ASSISTANT_TASKS_VIEW, AssistantPanel, AssistantTasks, AssistantTaskView } from './assistant-view';
+
+function download(name: string, text: string): void {
+    const url = URL.createObjectURL(new Blob([text], { type: 'text/markdown;charset=utf-8' }));
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = name;
+    link.click();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+/**
+ * The double, as a built-in web extension: a page of its own, with a … where the side bar lists it.
+ * Its tasks are a tool of the workbench on the right, and each task opens there as a tab.
+ */
+@Component(BuiltinWebExtension)
+export class AssistantWebExtension implements BuiltinWebExtension {
+    readonly name = ASSISTANT_NAME;
+    readonly title = 'ta.builtin.assistant';
+    readonly description = 'ta.builtin.assistantHint';
+
+    @Autowired(TaAssistant)
+    protected readonly assistant: TaAssistant;
+
+    @Autowired(TaState)
+    protected readonly persisted: TaState;
+
+    @Autowired(TaWorkbench)
+    protected readonly workbench: TaWorkbench;
+
+    readonly activate: WebExtensionFactory = pi => {
+        const openTask = (task: AssistantTask) =>
+            pi.ui.openEditor({
+                id: `${ASSISTANT_NAME}:task:${task.id}`,
+                title: task.title,
+                icon: ListTodo,
+                render: () => React.createElement(AssistantTaskView, { taskId: task.id }),
+            });
+        const registerPage = () =>
+            pi.registerView('assistant', {
+                title: () => this.assistant.name || message(pi.ui.language, 'ta.builtin.assistant'),
+                icon: Bot,
+                render: () => React.createElement(AssistantPanel, { onTask: openTask }),
+                menu: () => this.menu(pi),
+            });
+        registerPage();
+        pi.registerView(ASSISTANT_TASKS_VIEW, {
+            title: () => message(pi.ui.language, 'ta.assistant.tasksTool'),
+            icon: ListTodo,
+            location: 'panel',
+            render: () => React.createElement(AssistantTasks, { onOpen: openTask }),
+        });
+        // Its title is its name: the lists that show the page read it again when it is registered again.
+        let name = this.assistant.name;
+        return this.persisted.subscribe(() => {
+            if (this.assistant.name !== name) {
+                name = this.assistant.name;
+                registerPage();
+            }
+        });
+    };
+
+    /** The … of the page: stop, start over; its name, its system prompt, its directory; the conversation as a file. */
+    protected menu(pi: WebExtensionAPI): WebMenuItem[][] {
+        const t = (id: MessageId) => message(pi.ui.language, id);
+        const store = this.assistant.store();
+        const cwd = this.workbench.state.server?.cwd;
+        const title = () => this.assistant.name || t('ta.builtin.assistant');
+        const act = (action: () => unknown) => () => {
+            Promise.resolve()
+                .then(action)
+                .catch(error => pi.ui.notify(error instanceof Error ? error.message : String(error), 'error'));
+        };
+        const stop = act(() => this.assistant.stop());
+        const restart = act(async () => {
+            if (await pi.ui.confirm(t('ta.assistant.restartTitle'), t('ta.assistant.restartHint'))) {
+                await this.assistant.restart();
+            }
+        });
+        const rename = act(async () => {
+            const name = await pi.ui.input(t('ta.assistant.rename'), t('ta.builtin.assistant'), { value: title() });
+            if (name !== undefined) {
+                this.assistant.rename(name.trim() === t('ta.builtin.assistant') ? '' : name);
+            }
+        });
+        const editPrompt = act(async () => {
+            // The prompt is set when the conversation opens: it opens again, which would cut a run short.
+            if (this.assistant.store()?.state.working) {
+                pi.ui.notify(t('ta.assistant.busy'), 'warning');
+                return;
+            }
+            const prompt = await pi.ui.editor(t('ta.assistant.promptTitle'), this.assistant.prompt);
+            if (prompt !== undefined) {
+                await this.assistant.setPrompt(prompt);
+            }
+        });
+        const copyCwd = act(async () => {
+            await navigator.clipboard.writeText(cwd ?? '');
+            pi.ui.notify(t('ta.assistant.copied').replace('{path}', cwd ?? ''), 'info');
+        });
+        const exportMarkdown = act(() => {
+            const text = AssistantExport.markdown(this.assistant.store()?.state.messages ?? [], {
+                user: t('ta.assistant.you'),
+                ta: title(),
+                task: t('ta.assistant.tasks'),
+                status: status => t(`ta.task.${status}`),
+            });
+            if (text) {
+                download(`${title()}.md`, text);
+            } else {
+                pi.ui.notify(t('ta.assistant.nothingToExport'), 'info');
+            }
+        });
+        return [
+            [
+                { key: 'stop', label: t('ta.assistant.stop'), icon: Square, disabled: !store?.state.working, run: stop },
+                { key: 'restart', label: t('ta.assistant.restart'), icon: RotateCcw, disabled: !store, run: restart },
+            ],
+            [
+                { key: 'rename', label: t('ta.assistant.rename'), icon: Pencil, run: rename },
+                { key: 'prompt', label: t('ta.assistant.prompt'), icon: ScrollText, run: editPrompt },
+                { key: 'copyCwd', label: t('ta.assistant.copyCwd'), icon: Copy, disabled: !cwd, run: copyCwd },
+            ],
+            [{ key: 'export', label: t('ta.assistant.export'), icon: Download, run: exportMarkdown }],
+        ];
+    }
+}

package/src/browser/assistant/assistant-hooks.ts

@@ -0,0 +1,63 @@
+import { useInject } from '@celljs/react';
+import type { SessionState } from '@celljs/ta-client';
+import * as React from 'react';
+import { type AssistantState, type AssistantTask, TaAssistant } from './assistant-protocol';
+
+// The state of the double for its views: the assistant, its tasks, the time.
+
+export function useAssistant(): [AssistantState, TaAssistant] {
+    const assistant = useInject<TaAssistant>(TaAssistant);
+    const state = React.useSyncExternalStore(
+        listener => assistant.subscribe(listener),
+        () => assistant.state,
+    );
+    return [state, assistant];
+}
+
+/** The state of every task's session: tasks come and go, so this follows their stores by hand. */
+export function useTaskStates(assistant: TaAssistant, tasks: AssistantTask[]): Map<string, SessionState> {
+    const [states, setStates] = React.useState(() => new Map<string, SessionState>());
+    const ids = tasks.map(task => task.id).join(',');
+    // biome-ignore lint/correctness/useExhaustiveDependencies: follows the set of tasks, by id
+    React.useEffect(() => {
+        const stops = tasks.flatMap(task => {
+            const store = assistant.taskStore(task.id);
+            if (!store) {
+                return [];
+            }
+            const set = (state: SessionState) => setStates(previous => new Map(previous).set(task.id, state));
+            set(store.state);
+            return [store.subscribe(set)];
+        });
+        return () => {
+            for (const stop of stops) {
+                stop();
+            }
+        };
+    }, [assistant, ids]);
+    return states;
+}
+
+export function useNow(intervalMs: number): number {
+    const [now, setNow] = React.useState(Date.now());
+    React.useEffect(() => {
+        const timer = setInterval(() => setNow(Date.now()), intervalMs);
+        return () => clearInterval(timer);
+    }, [intervalMs]);
+    return now;
+}
+
+/** When the user last touched the page: ta dozes off when left alone. */
+export function useLastActive(): number {
+    const [lastActive, setLastActive] = React.useState(Date.now());
+    React.useEffect(() => {
+        const active = () => setLastActive(Date.now());
+        window.addEventListener('pointerdown', active);
+        window.addEventListener('keydown', active);
+        return () => {
+            window.removeEventListener('pointerdown', active);
+            window.removeEventListener('keydown', active);
+        };
+    }, []);
+    return lastActive;
+}

package/src/browser/assistant/assistant-protocol.ts

@@ -0,0 +1,55 @@
+import type { SessionStore } from '@celljs/ta-client';
+
+export const TaAssistant = Symbol('TaAssistant');
+
+export interface AssistantTask {
+    /** Short, for the model: `t1`, `t2`, … */
+    id: string;
+    title: string;
+    sessionId: string;
+    sessionFile?: string;
+    cwd: string;
+    status: 'running' | 'done' | 'failed' | 'stopped';
+    startedAt: number;
+    endedAt?: number;
+    /** The last words of the task's agent. */
+    result?: string;
+}
+
+export interface AssistantState {
+    /** The conversation with ta is open. */
+    ready: boolean;
+    error?: string;
+    tasks: AssistantTask[];
+    /** The time the last task ended, for a little celebration. */
+    lastFinished?: number;
+}
+
+/**
+ * ta as the user's double: one long conversation with the user, which hands work to tasks, each its own
+ * session of ta serve running in parallel, and tells the user how they ended. Handing out work is a
+ * set of client tools of that conversation, which this service runs: no server feature.
+ */
+export interface TaAssistant {
+    readonly state: AssistantState;
+    subscribe(listener: (state: AssistantState) => void): () => void;
+    /** Opens the conversation again, or for the first time; follows the tasks still running. */
+    start(): Promise<void>;
+    /** The conversation with ta. */
+    store(): SessionStore | undefined;
+    taskStore(taskId: string): SessionStore | undefined;
+    /** Says something to ta: a new message, or, while it works, one it reads at its next step. */
+    say(text: string): Promise<void>;
+    stopTask(taskId: string): Promise<void>;
+    /** What the user calls the double; empty, its default name. */
+    readonly name: string;
+    rename(name: string): void;
+    /** What the user adds to the role of the double, at the end of its system prompt. */
+    readonly prompt: string;
+    /** Opens the conversation again with it: the system prompt of a session is set when it opens. */
+    setPrompt(prompt: string): Promise<void>;
+    /** Stops what the double is doing; its tasks go on. */
+    stop(): Promise<void>;
+    /** A new conversation with the double, as pi's `/new`; the tasks stay. */
+    restart(): Promise<void>;
+}