@thinkfree.dev/tfo-sdk 0.2.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -115,6 +115,20 @@ await doc.getFileName(); // 'report.docx' — current name, inc
115
115
  - Values are not cached. Renames are reflected on every call.
116
116
  - Against an older editor that does not implement the metadata command, these methods (except the synchronous `getApplicationType()`) reject with `SDKError(TIMEOUT)`.
117
117
 
118
+ ### Admin AI provider settings (`getAiProviderConfig`)
119
+
120
+ ```ts
121
+ const config = await app.getAiProviderConfig();
122
+ // { aiProvider: 'openai-compatible', model: 'openai/gpt-5.6-luna', connectionMode: 'relay',
123
+ // relayRequest: { endpoint: 'https://office.example.com/ai-agent/relay', method: 'POST' },
124
+ // openAiCompatible: { preset: 'openrouter' } } — or null when the editor has no admin settings
125
+ ```
126
+
127
+ - The same provider/model the editor's built-in AI assistant uses. Build your relay-mode `aiProviderConfig` from it so a change in the editor's admin page is picked up without touching the host page.
128
+ - Never contains an API key. The relay server keeps the key.
129
+ - Returns `null` when the admin settings are missing or incomplete. Fall back to your own default in that case.
130
+ - Against an older editor that does not implement the command, rejects with `SDKError(TIMEOUT)`.
131
+
118
132
  ## Document handles (`getDocument`)
119
133
 
120
134
  | module | root handle | from the app handle |
@@ -149,9 +163,6 @@ const result = await tools[0].execute({ text: 'Hello' }); // the module's MCP
149
163
  // Frameworks with a registerTool callback (for example the Thinkfree Agent runtime) — register automatically
150
164
  await word.registerTools(modelContext);
151
165
 
152
- // Or dispatch directly (tool names are owned by the module catalog)
153
- await word.execute('insert_text', [{ text: 'Hello' }]);
154
-
155
166
  // System prompt provided by the module ('' when the module has none)
156
167
  const prompt = await word.getSystemPrompt();
157
168
  ```
@@ -163,6 +174,29 @@ In addition to the module catalog, the tool list contains **two SDK-defined tool
163
174
  - `get_api_reference` — looks up the document API reference (index, details by name, keyword search). The SDK answers locally from a bundled reference; the data lives in a separate chunk, `apiReference.generated.js`, loaded on first use.
164
175
  - `execute_script` — runs a JavaScript snippet inside the editor so multi-step or repetitive edits happen in one call. It reports without throwing, as `{ ok, status, logs }`.
165
176
 
177
+ ### Office toolkit — tools, prompt and tool results in one object
178
+
179
+ `createOfficeToolkit` packages the catalog, the system prompt and tool execution for your own LLM loop. It converts tools to the wire shape of your provider, appends tool-usage rules to the module prompt, and normalizes every tool result into one **`ToolResult`** shape (`{ success, data?, failure?: { code, message } }`) so the loop can branch on `failure.code` instead of parsing text.
180
+
181
+ ```ts
182
+ import { createOfficeToolkit } from '@thinkfree.dev/tfo-sdk';
183
+
184
+ const toolkit = await createOfficeToolkit(word, { provider: 'openai', preset: 'core' });
185
+
186
+ // toolkit.tools → pass to the LLM request as-is (openai · anthropic · vercel · generic shapes)
187
+ // toolkit.systemPrompt → module prompt + toolkit rules (+ your `prompt.extra`)
188
+ // tool_calls → ToolResult
189
+ const result = await toolkit.dispatch(call.function.name, JSON.parse(call.function.arguments));
190
+ if (!result.success && result.failure.code === 'stale') {
191
+ // the target no longer exists — look it up again before retrying
192
+ }
193
+ ```
194
+
195
+ - **Presets** filter the same catalog: `core` (default, everything but `execute_script`), `review` (read and comment tools only), `full`. Narrow further with `include`.
196
+ - **Failure codes** — `stale` · `no-op` · `capability` · `permission` · `invalid` · `internal`. Transport errors become `internal` failures; only a destroyed connection still throws.
197
+ - **Custom actions** — add partner tools with `customActions` (`partner_*` names — letters, digits, `_`, `-` only, so they satisfy the OpenAI/Anthropic tool-name rule; `run(ctx, args)` or a list of catalog `steps`).
198
+ - `withExecute(toolkit)` returns tools with an `execute` for runtimes that call tools themselves. `dispatchAll` runs a batch in order and stops at the first failure.
199
+
166
200
  Keep the tool set small and task-specific with `include`. See the guide on [document tools and errors](https://www.developers.thinkfree.com/docs/editor-sdk/tools-and-errors/) for framework-specific schema mappings, and the [Editor AI SDK](https://www.developers.thinkfree.com/docs/editor-ai-sdk/) docs for a complete tool-calling loop.
167
201
 
168
202
  ## Error handling