* docs(serve): v0.16-alpha known limits + SDK QWEN_SERVER_TOKEN env fallback (PR 27) First PR in the F5 release chain (PR 27 → 28 → 30a → 31) per the 2026-05-24 v0.16-alpha scope freeze in #4175 (text-only chat / coding + local-only deployment). ## SDK ergonomic micro-change (~50 LOC + 4 tests) `DaemonClient` constructor falls back to `QWEN_SERVER_TOKEN` env var when `opts.token` is absent — closes the asymmetry where the daemon side already honors this var (--token CLI flag fallback, already in main since PR 15) but the SDK forced clients to thread it through every construction. Properties: - Browser-safe via `globalThis.process` indirection (the SDK is imported by @qwen-code/webui; literal process.env access would explode at module load on browser bundles) - Whitespace stripped (matches daemon-side trim — handy for `export QWEN_SERVER_TOKEN=\"\$(cat token.txt)\"` where cat adds a trailing newline) - Empty / whitespace-only treated as unset (a stale `export QWEN_SERVER_TOKEN=\"\"` won't accidentally send Authorization: Bearer with no token) - Resolved at construction, not lazily per-request (later process.env mutations don't affect already-built clients) - Explicit opts.token wins over env Tests: 4 new in DaemonClient.test.ts `bearer auth` describe covering env fallback / explicit-wins / empty-treated-unset / whitespace-stripped. Plus a defensive snapshot/restore on the existing 'omits Authorization when no token' test so an inherited test-runner export of QWEN_SERVER_TOKEN doesn't turn that assertion into a false positive. This SDK fallback is the entire ergonomic replacement for PR 29's SDK env/file fallback. PR 29's other features (auto-gen daemon token, instance-path keying, stale cleanup) remain deferred to v0.16.x — all are DX improvements over the boot-time security gate already shipped in PR 15. ## v0.16-alpha docs (~120 LOC markdown) - docs/users/qwen-serve.md: new "v0.16-alpha known limits" section enumerating product surface (text-only ✅, multimodal ❌), deployment surface (local launchers ✅, containerized ❌, multi- daemon ❌, BYO-token ✅), and hardening posture (boot security gate ✅, mutation gate ✅, MCP guardrails ✅, prompt absolute deadline ⏸️, rate limiting ⏸️, --max-body-size ⏸️). Adds an alpha banner at the top of the file. - docs/developers/examples/daemon-client-quickstart.md: documents the SDK env fallback in both the Hello-daemon intro and the Authentication section, with the "export + no-token-arg" recommended path called out for local dev. Verification: 125/125 DaemonClient.test.ts pass (121 existing + 4 new); 4/4 daemon-public-surface.test.ts pass (constructor signature unchanged); tsc clean on packages/sdk-typescript; eslint --max-warnings 0 clean on touched .ts files. Part of #4175. * fix(sdk): #4473 round 1 fold-in — 2 copilot doc threads adopted T1 [copilot DaemonClient.ts:144 — stale line refs in readTokenFromEnv JSDoc]: removed `runQwenServe.ts:175` (token resolution actually lives at line 302-318 today, would drift again on next refactor) and `docs/users/qwen-serve.md:173`. Replaced with stable symbol/section references ("runQwenServe token-resolution path"; "qwen-serve user guide CLI flags section"). T2 [copilot daemon-client-quickstart.md:33 — `~/.qwen/server-token` implies built-in path that doesn't exist]: PR 27 explicitly defers token auto-generation + file-store fallback (PR 29 deferred features). The example incorrectly suggested a standard file location. Replaced with two explicit user-managed alternatives: - `openssl rand -hex 32` one-shot - `cat ./my-token-file` user-managed file Both threads were accurate suggestions caught at the right time (zero behavior change; pure docstring/example accuracy). Verification: 125/125 DaemonClient tests pass; tsc + eslint clean on touched files.
240 lines
6.7 KiB
TypeScript
240 lines
6.7 KiB
TypeScript
/**
|
|
* @license
|
|
* Copyright 2026 Qwen Team
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
import path from 'node:path';
|
|
import { afterEach, describe, expect, it } from 'vitest';
|
|
import {
|
|
TestRig,
|
|
createToolCallErrorMessage,
|
|
printDebugInfo,
|
|
validateModelOutput,
|
|
} from '../test-helper.js';
|
|
|
|
type NotebookCell = {
|
|
id?: string;
|
|
cell_type: 'code' | 'markdown' | 'raw';
|
|
metadata: Record<string, unknown>;
|
|
source: string | string[];
|
|
execution_count?: number | null;
|
|
outputs?: unknown[];
|
|
};
|
|
|
|
type NotebookContent = {
|
|
cells: NotebookCell[];
|
|
metadata: Record<string, unknown>;
|
|
nbformat: number;
|
|
nbformat_minor: number;
|
|
};
|
|
|
|
const sourceText = (source: string | string[]) =>
|
|
Array.isArray(source) ? source.join('') : source;
|
|
|
|
const promptPath = (filePath: string) => filePath.split(path.sep).join('/');
|
|
|
|
const readNotebook = (rig: TestRig, fileName: string): NotebookContent =>
|
|
JSON.parse(rig.readFile(fileName)) as NotebookContent;
|
|
|
|
const baseNotebook = (cells: NotebookCell[]): NotebookContent => ({
|
|
cells,
|
|
metadata: {
|
|
kernelspec: {
|
|
display_name: 'Python 3',
|
|
language: 'python',
|
|
name: 'python3',
|
|
},
|
|
language_info: {
|
|
name: 'python',
|
|
},
|
|
},
|
|
nbformat: 4,
|
|
nbformat_minor: 5,
|
|
});
|
|
|
|
const expectReadThenNotebookEdit = (rig: TestRig, result: string) => {
|
|
const logs = rig.readToolLogs();
|
|
const foundTools = logs.map((t) => t.toolRequest.name);
|
|
const readIndex = foundTools.findIndex((name) => name === 'read_file');
|
|
const notebookEditIndex = foundTools.findIndex(
|
|
(name) => name === 'notebook_edit',
|
|
);
|
|
|
|
if (readIndex === -1 || notebookEditIndex === -1) {
|
|
printDebugInfo(rig, result, { foundTools });
|
|
}
|
|
|
|
expect(
|
|
readIndex,
|
|
createToolCallErrorMessage('read_file', foundTools, result),
|
|
).toBeGreaterThanOrEqual(0);
|
|
expect(
|
|
notebookEditIndex,
|
|
createToolCallErrorMessage('notebook_edit', foundTools, result),
|
|
).toBeGreaterThan(readIndex);
|
|
};
|
|
|
|
const expectNoSuccessfulRawNotebookWrites = (
|
|
rig: TestRig,
|
|
notebookFileName: string,
|
|
) => {
|
|
const rawNotebookWrites = rig
|
|
.readToolLogs()
|
|
.filter(
|
|
(log) =>
|
|
['edit', 'write_file'].includes(log.toolRequest.name) &&
|
|
log.toolRequest.success &&
|
|
log.toolRequest.args.includes(notebookFileName),
|
|
);
|
|
|
|
expect(rawNotebookWrites).toEqual([]);
|
|
};
|
|
|
|
describe('notebook_edit integration', () => {
|
|
let rig: TestRig;
|
|
|
|
afterEach(async () => {
|
|
await rig?.cleanup();
|
|
});
|
|
|
|
it('replaces a code cell after reading the notebook and clears stale outputs', async () => {
|
|
rig = new TestRig();
|
|
await rig.setup('notebook edit replace code cell clears outputs');
|
|
|
|
const fileName = 'analysis.ipynb';
|
|
const notebookPath = rig.createFile(
|
|
fileName,
|
|
JSON.stringify(
|
|
baseNotebook([
|
|
{
|
|
id: 'intro',
|
|
cell_type: 'markdown',
|
|
metadata: {},
|
|
source: ['# Analysis\n'],
|
|
},
|
|
{
|
|
id: 'load-data',
|
|
cell_type: 'code',
|
|
metadata: {},
|
|
source: ['old_value = 1\n', 'print(old_value)\n'],
|
|
execution_count: 7,
|
|
outputs: [
|
|
{
|
|
output_type: 'stream',
|
|
name: 'stdout',
|
|
text: ['1\n'],
|
|
},
|
|
],
|
|
},
|
|
]),
|
|
null,
|
|
1,
|
|
),
|
|
);
|
|
|
|
const prompt = `Read the notebook at ${promptPath(notebookPath)} with read_file first.
|
|
Then use notebook_edit, not edit or write_file, to replace the code cell whose id is load-data.
|
|
Set the new source exactly to:
|
|
|
|
result = 41 + 1
|
|
print(result)
|
|
|
|
Do not change any other cell.`;
|
|
|
|
const result = await rig.run(prompt);
|
|
|
|
expectReadThenNotebookEdit(rig, result);
|
|
expectNoSuccessfulRawNotebookWrites(rig, fileName);
|
|
validateModelOutput(result, null, 'Notebook replace');
|
|
|
|
const notebook = readNotebook(rig, fileName);
|
|
const target = notebook.cells.find((cell) => cell.id === 'load-data');
|
|
|
|
expect(target).toBeDefined();
|
|
expect(target?.cell_type).toBe('code');
|
|
expect(sourceText(target!.source).trimEnd()).toBe(
|
|
'result = 41 + 1\nprint(result)',
|
|
);
|
|
expect(target?.execution_count).toBeNull();
|
|
expect(target?.outputs).toEqual([]);
|
|
expect(sourceText(notebook.cells[0]!.source)).toBe('# Analysis\n');
|
|
});
|
|
|
|
it('inserts a markdown cell and deletes a target cell using notebook_edit', async () => {
|
|
rig = new TestRig();
|
|
await rig.setup('notebook edit insert and delete cells');
|
|
|
|
const fileName = 'workflow.ipynb';
|
|
const notebookPath = rig.createFile(
|
|
fileName,
|
|
JSON.stringify(
|
|
baseNotebook([
|
|
{
|
|
id: 'intro',
|
|
cell_type: 'markdown',
|
|
metadata: {},
|
|
source: ['# Workflow\n'],
|
|
},
|
|
{
|
|
id: 'remove-me',
|
|
cell_type: 'markdown',
|
|
metadata: {},
|
|
source: ['This temporary cell should be deleted.\n'],
|
|
},
|
|
{
|
|
id: 'calculate',
|
|
cell_type: 'code',
|
|
metadata: {},
|
|
source: ['value = 10\n'],
|
|
execution_count: null,
|
|
outputs: [],
|
|
},
|
|
]),
|
|
null,
|
|
1,
|
|
),
|
|
);
|
|
|
|
const insertedMarkdown =
|
|
'## Inserted Note\nThis cell was inserted by NotebookEdit.';
|
|
const prompt = `Read the notebook at ${promptPath(notebookPath)} with read_file first.
|
|
Then use notebook_edit, not edit or write_file, for both changes:
|
|
1. Insert a markdown cell after the cell whose id is intro. Its source must be exactly:
|
|
|
|
${insertedMarkdown}
|
|
|
|
2. Delete the cell whose id is remove-me.
|
|
Do not change the calculate code cell.`;
|
|
|
|
const result = await rig.run(prompt);
|
|
|
|
expectReadThenNotebookEdit(rig, result);
|
|
expectNoSuccessfulRawNotebookWrites(rig, fileName);
|
|
validateModelOutput(result, null, 'Notebook insert/delete');
|
|
|
|
const successfulNotebookEdits = rig
|
|
.readToolLogs()
|
|
.filter(
|
|
(log) =>
|
|
log.toolRequest.name === 'notebook_edit' && log.toolRequest.success,
|
|
);
|
|
expect(successfulNotebookEdits.length).toBeGreaterThanOrEqual(2);
|
|
|
|
const notebook = readNotebook(rig, fileName);
|
|
const cellIds = notebook.cells.map((cell) => cell.id);
|
|
const insertedCell = notebook.cells.find((cell) =>
|
|
sourceText(cell.source).includes('Inserted Note'),
|
|
);
|
|
|
|
expect(cellIds).toHaveLength(3);
|
|
expect(cellIds).not.toContain('remove-me');
|
|
expect(notebook.cells[0]?.id).toBe('intro');
|
|
expect(insertedCell).toBeDefined();
|
|
expect(insertedCell?.cell_type).toBe('markdown');
|
|
expect(sourceText(insertedCell!.source).trimEnd()).toBe(insertedMarkdown);
|
|
expect(notebook.cells.at(-1)?.id).toBe('calculate');
|
|
expect(sourceText(notebook.cells.at(-1)!.source)).toBe('value = 10\n');
|
|
});
|
|
});
|