docs: ToolContext.userSpokeAt, conversationId and ToolResult.sequence

README.md

@@ -192,6 +192,23 @@ interface ToolResult<T, J> {
 }
 ```
 
+### ToolContext
+
+The execute function receives a `ToolContext`:
+
+```typescript
+interface ToolContext {
+  currentResult?: ToolResult | null;  // Currently selected result
+  app?: ToolContextApp;               // Host app features
+  userSpokeAt?: number;               // 2.1: when the user last spoke (Date.now() ms)
+  conversationId?: string;            // 2.2: which conversation the call belongs to
+}
+```
+
+`app` holds the host's functions (check one exists before calling it; `generateImage` and
+`editImages` are shared conventions). A tool that shows steps one at a time returns `sequence` on
+its results. See the [API reference](https://github.com/receptron/gui-chat-protocol/blob/main/spec/API_REFERENCE.md).
+
 ### View Component Props
 
 ```typescript

TEMPLATE.md

@@ -426,6 +426,15 @@ rollupOptions: {
 }
 ```
 
+### ⚠️ Reach the Host Only Through `context`
+
+`execute()` may run in the browser or on the host's server, so it doesn't `fetch` host routes or
+touch `window`. Use what `ToolContext` carries: `currentResult`, `app` (check a function exists
+before calling it; `generateImage(prompt)` and `editImages(prompt, imagePaths)` are shared
+conventions), `userSpokeAt` (gui-chat-protocol 2.1) and `conversationId` (2.2: keep in-memory state
+per conversation). A tool that shows steps one at a time returns `sequence` on its results (2.1).
+See the [API reference](https://github.com/receptron/gui-chat-protocol/blob/main/spec/API_REFERENCE.md), and [`@gui-chat-plugin/sequence`](https://github.com/receptron/gui-chat-plugins/tree/main/packages/sequence) for an example.
+
 ### ⚠️ File Structure Verification
 
 Required for `yarn dev` to work:
@@ -686,6 +695,14 @@ rollupOptions: {
 }
 ```
 
+### ⚠️ ホストには `context` 経由でのみアクセス
+
+`execute()` はブラウザでもホストのサーバーでも動くことがあるので、ホストのルートを `fetch` したり
+`window` に触れたりしないでください。`ToolContext` にあるものを使います：`currentResult`、`app`（呼ぶ前に関数があるか確かめる。
+`generateImage(prompt)` と `editImages(prompt, imagePaths)` は共通の決まりごと）、`userSpokeAt`（gui-chat-protocol 2.1）、
+`conversationId`（2.2：メモリに持つ状態は会話ごとに持つ）。1 ステップずつ見せるツールは結果に `sequence` を返します（2.1）。
+[API リファレンス](https://github.com/receptron/gui-chat-protocol/blob/main/spec/API_REFERENCE.md)と、例として [`@gui-chat-plugin/sequence`](https://github.com/receptron/gui-chat-plugins/tree/main/packages/sequence) を参照してください。
+
 ---
 
 ## チェックリスト

docs/getting-started.ja.md

@@ -531,7 +531,7 @@ execute(context: ToolContext, args: GreetingArgs): Promise<ToolResult>
 
 | 引数 | 説明 |
 |------|------|
-| `context` | 実行コンテキスト。`currentResult`（前回の結果）などを含む |
+| `context` | 実行コンテキスト。`currentResult`（前回の結果）、`app`（`generateImage` などホストの機能）、`userSpokeAt`、`conversationId`。詳しくは[プラグイン開発ガイド](./plugin-development-guide.md#toolcontext) |
 | `args` | LLMが渡した引数。definition.tsで定義したパラメータに基づく |
 
 ### ToolResultの構造（戻り値）

docs/getting-started.md

@@ -533,7 +533,7 @@ execute(context: ToolContext, args: GreetingArgs): Promise<ToolResult>
 
 | Argument | Description |
 |----------|-------------|
-| `context` | Execution context. Contains `currentResult` (previous result), etc. |
+| `context` | Execution context: `currentResult` (previous result), `app` (host features such as `generateImage`), `userSpokeAt` and `conversationId`. See the [plugin development guide](./plugin-development-guide.md#toolcontext) |
 | `args` | Arguments from LLM. Based on parameters defined in definition.ts |
 
 ### ToolResult Structure (Return Value)

docs/plugin-development-guide.md

@@ -142,6 +142,7 @@ interface ToolResult<T, J> {
   instructionsRequired?: boolean; // Always send instructions
   updating?: boolean;           // Update existing result
   viewState?: Record<string, unknown>; // Persistent UI state
+  sequence?: SequenceStep | null; // 2.1: this result is a step of a sequence (see below)
 }
 ```
 
@@ -151,9 +152,44 @@ interface ToolResult<T, J> {
 interface ToolContext {
   currentResult?: ToolResult | null;  // Currently selected result
   app?: ToolContextApp;               // Host app features
+  userSpokeAt?: number;               // 2.1: when the user last spoke (Date.now() ms)
+  conversationId?: string;            // 2.2: which conversation the call belongs to
 }
 ```
 
+- **`app`** is an open record: a host adds the functions it has, and a plugin checks for one before
+  calling it. Two are shared conventions with fixed shapes (MulmoChat, MulmoGlass):
+  `generateImage(prompt)` and `editImages(prompt, imagePaths)` (a new picture from 1 to 8 saved
+  ones under `artifacts/images/`). Both return a `ToolResult` whose `data.imageData` is the
+  picture and `data.imagePath` where it was saved.
+- **`userSpokeAt`** is absent when the host doesn't know; a plugin then doesn't wait for the user.
+- **`conversationId`**: a plugin that keeps state in memory between calls keeps it per
+  `conversationId`, so conversations sharing one host (browser tabs on one server) don't mix.
+  Compare it, don't parse it. Absent means one conversation.
+
+### Sequences (steps shown one at a time)
+
+A tool that shows a sequence one step per call, such as slides or a story's panels, returns
+`sequence` on each result: where the sequence is and the call for the next step. A host that
+supports sequences asks the model once to go on when it ends a reply mid-sequence, which models
+do. Set `sequence: null` for a step that wasn't shown, and leave it out on results that aren't
+steps. A step that waits for the user sets `waitsForUser`, and the plugin holds a later step until
+`context.userSpokeAt` is after the waiting step appeared.
+
+```typescript
+return {
+  toolName: TOOL_NAME, data, message, instructions,
+  sequence: {
+    step: 2, total: 5, kind: "slideshow", label: "Slide 2 of 5",
+    onShown: "explain it", nextCall: "call presentSlide for slide 3 of 5",
+  },
+};
+```
+
+The full shapes, and the host side (`createSequenceKeeper`), are in the
+[API reference](https://github.com/receptron/gui-chat-protocol/blob/main/spec/API_REFERENCE.md). [`@gui-chat-plugin/sequence`](https://github.com/receptron/gui-chat-plugins/tree/main/packages/sequence) (presentSlide, defineStoryboard,
+presentPanel) is a working example.
+
 ---
 
 ## Directory Structure