Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

autonomous-device: scroll the focused terminal over LAN; rename the settings section to Autonomous robots (#98)

Leob2d40a00c18d
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index b2a3d2e77..cf8a76d9e 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -5201,6 +5201,8 @@ async function runForeground(session: AuthSession): Promise<void> {
// The dial's own carousel tick, borrowed: ring order and wrap from the cable host, `dial_focus` to
// the window, `app_focus` back. Without a window the forward is a no-op, so say so up front.
stepFocus: (direction, currentAgentId) => backend.hasLocalClient() ? cableHost.stepFocus(direction, currentAgentId) : Promise.resolve('no_app'),
+ // The dial's touchpad stroke, borrowed the same way: `dial_scroll` to the window's focused terminal.
+ scroll: (phase, dy, velocity) => { if (!backend.hasLocalClient()) return false; cableHost.scrolled(phase, dy, velocity); return true },
agents: () => registry.advertised().map(s => ({ agentId: s.agentId, name: projectDisplayName(s), engine: s.engine,
state: turnStartedAt.has(s.sessionId) ? 'running' : 'idle' })),
submit: submitAgent,
diff --git a/cli/src/lib/autonomous-device/service.spec.ts b/cli/src/lib/autonomous-device/service.spec.ts
index cd6634416..cc7825477 100644
--- a/cli/src/lib/autonomous-device/service.spec.ts
+++ b/cli/src/lib/autonomous-device/service.spec.ts
@@ -60,6 +60,42 @@ describe('Autonomous device local-agent service', () => {
} finally { vi.useRealTimers() }
})
+ describe('scroll', () => {
+ function scrollFixture(hasApp = true) {
+ const scroll = vi.fn((_phase: 'down' | 'move' | 'up', _dy: number, _velocity: number) => hasApp)
+ const service = new AutonomousDeviceService({ machineId: 'machine', scroll,
+ agents: () => [], submit: vi.fn(), stop: async () => true, answer: async () => true, cancelDelivery: () => true, recent: () => [] })
+ const send = (over: Record<string, unknown>) => service.request('device', { type: 'scroll', requestId: randomUUID(), ...over })
+ return { service, scroll, send }
+ }
+
+ it('advertises the capability', () => {
+ expect(AUTONOMOUS_DEVICE_CAPABILITIES).toContain('scroll')
+ })
+
+ it('forwards each phase of a stroke to the window, dy and velocity defaulting to 0', async () => {
+ const f = scrollFixture()
+ expect(await f.send({ phase: 'down' })).toMatchObject({ type: 'scroll_result' })
+ expect(await f.send({ phase: 'move', dy: -24 })).not.toHaveProperty('error')
+ expect(await f.send({ phase: 'up', dy: -3, velocity: -900 })).not.toHaveProperty('error')
+ expect(f.scroll.mock.calls).toEqual([['down', 0, 0], ['move', -24, 0], ['up', -3, -900]])
+ })
+
+ it('rejects a bad phase, a non-integer or oversized travel, and unknown fields', async () => {
+ const f = scrollFixture()
+ for (const over of [{ phase: 'flick' }, { phase: 'move', dy: 1.5 }, { phase: 'move', dy: 5000 }, { phase: 'up', velocity: 1e6 }, { phase: 'move', dy: 1, agentId: 'a' }]) {
+ expect(await f.send(over)).toMatchObject({ error: { code: 'INVALID_REQUEST' } })
+ }
+ expect(f.scroll).not.toHaveBeenCalled()
+ })
+
+ it('is FOCUS_UNAVAILABLE without a Desktop window, and when the machine has no scroll wiring', async () => {
+ expect(await scrollFixture(false).send({ phase: 'down' })).toMatchObject({ error: { code: 'FOCUS_UNAVAILABLE' } })
+ const bare = new AutonomousDeviceService({ machineId: 'm', agents: () => [], submit: vi.fn(), stop: async () => true, answer: async () => true, cancelDelivery: () => true, recent: () => [] })
+ expect(await bare.request('device', { type: 'scroll', requestId: randomUUID(), phase: 'down' })).toMatchObject({ error: { code: 'FOCUS_UNAVAILABLE' } })
+ })
+ })
+
describe('focus.step', () => {
const DESK = ['a', 'b', 'c']
function stepFixture(desk = DESK, acknowledge = true) {
diff --git a/cli/src/lib/autonomous-device/service.ts b/cli/src/lib/autonomous-device/service.ts
index 448f181da..1d1f35ebe 100644
--- a/cli/src/lib/autonomous-device/service.ts
+++ b/cli/src/lib/autonomous-device/service.ts
@@ -21,6 +21,12 @@ export interface AutonomousDeviceServiceOptions {
* acknowledgment is what makes the move real. `'no_app'` when no Desktop window is connected.
*/
stepFocus?: (direction: 'next' | 'previous', currentAgentId: string | undefined) => Promise<{ machineId: string; agentId: string } | 'no_agents' | 'no_app'>
+ /**
+ * One piece of a finger stroke for the focused terminal's scrollback, the way the USB dial's glass
+ * reports it — same `dial_scroll` forward, the terminal does the arithmetic. `false` when no Desktop
+ * window is connected to scroll.
+ */
+ scroll?: (phase: 'down' | 'move' | 'up', dy: number, velocity: number) => boolean
submit: (agentId: string, text: string, deliveryId: string) => void
cancelDelivery: (deliveryId: string) => boolean
stop: (agentId: string) => Promise<boolean>
@@ -38,10 +44,14 @@ export interface AutonomousDeviceServiceOptions {
emit?: (frame: AutonomousDeviceFrame) => void
}
interface Entry { deviceId: string; digest: string; receipt: AutonomousDeviceReceipt }
-const CAPABILITIES = ['focus.get', 'focus.ensure', 'focus.step', 'agents.list', 'turn.send', 'turn.stop', 'status', 'recap', 'question.answer', 'receipt.get'] as const
+const CAPABILITIES = ['focus.get', 'focus.ensure', 'focus.step', 'scroll', 'agents.list', 'turn.send', 'turn.stop', 'status', 'recap', 'question.answer', 'receipt.get'] as const
export const AUTONOMOUS_DEVICE_CAPABILITIES: string[] = [...CAPABILITIES]
const MUTATIONS = new Set(['turn.send', 'turn.stop', 'question.answer'])
const STEP_RESULTS_MAX = 512
+const SCROLL_PHASES = new Set(['down', 'move', 'up'])
+/** Device pixels per report and px/s: generous for any glass, tight enough that a bad value cannot fling a terminal for minutes. */
+const SCROLL_DY_MAX = 4096
+const SCROLL_VELOCITY_MAX = 100_000
const APP_FOCUS_WAIT_MS = 2000
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
const KEY = /^[A-Za-z0-9_-]{1,64}$/
@@ -127,6 +137,20 @@ export class AutonomousDeviceService {
return this.waitForAppFocus(Date.now() + APP_FOCUS_WAIT_MS, s => s.focusRevision !== before.focusRevision)
}
+ /**
+ * A stroke is a stream, not a mutation: no idempotency key, no receipt, nothing retained. A lost `move`
+ * is a shorter scroll; a lost `up` is what the next `down` closes on the app side, as for the dial.
+ */
+ private scroll(req: Record<string, unknown>): void {
+ const phase = req.phase
+ if (typeof phase !== 'string' || !SCROLL_PHASES.has(phase)) fail('INVALID_REQUEST', 'phase must be down, move or up')
+ const dy = req.dy ?? 0, velocity = req.velocity ?? 0
+ if (!Number.isInteger(dy) || Math.abs(dy as number) > SCROLL_DY_MAX) fail('INVALID_REQUEST', `dy must be an integer within ±${SCROLL_DY_MAX}`)
+ if (!Number.isInteger(velocity) || Math.abs(velocity as number) > SCROLL_VELOCITY_MAX) fail('INVALID_REQUEST', `velocity must be an integer within ±${SCROLL_VELOCITY_MAX}`)
+ if (!this.options.scroll) fail('FOCUS_UNAVAILABLE', 'Scrolling is not wired on this machine')
+ if (!this.options.scroll(phase as 'down' | 'move' | 'up', dy as number, velocity as number)) fail('FOCUS_UNAVAILABLE', 'Open Harness Desktop to scroll a terminal')
+ }
+
/** Enable-time fallback only. The desktop must acknowledge its selected pane. */
private ensureFocus(): Promise<ReturnType<AutonomousDeviceService['focusSnapshot']>> {
const current = this.focusSnapshot()
@@ -265,7 +289,7 @@ export class AutonomousDeviceService {
try {
if (!UUID.test(String(req.requestId))) fail('INVALID_REQUEST', 'requestId must be a UUIDv4')
if (!AUTONOMOUS_DEVICE_CAPABILITIES.includes(type)) fail('UNSUPPORTED_CAPABILITY', 'Operation is not supported')
- const allowed = ['type', 'requestId', ...(['agents.list', 'focus.get', 'focus.ensure'].includes(type) ? [] : type === 'receipt.get' ? ['idempotencyKey'] : type === 'focus.step' ? ['direction', 'idempotencyKey', 'focusRevision'] : ['machineId', 'agentId']),
+ const allowed = ['type', 'requestId', ...(['agents.list', 'focus.get', 'focus.ensure'].includes(type) ? [] : type === 'receipt.get' ? ['idempotencyKey'] : type === 'focus.step' ? ['direction', 'idempotencyKey', 'focusRevision'] : type === 'scroll' ? ['phase', 'dy', 'velocity'] : ['machineId', 'agentId']),
...(MUTATIONS.has(type) ? ['idempotencyKey'] : []), ...(type === 'turn.send' ? ['text', 'focusRevision'] : type === 'question.answer' ? ['questionRequestId', 'answers', 'focusRevision'] : type === 'recap' ? ['n'] : [])]
if (Object.keys(req).some(k => !allowed.includes(k))) fail('INVALID_REQUEST', 'Unknown request field')
if (type === 'receipt.get') {
@@ -275,6 +299,7 @@ export class AutonomousDeviceService {
if (type === 'focus.get') return response(this.focusSnapshot())
if (type === 'focus.ensure') return response(await this.ensureFocus())
if (type === 'focus.step') return response(await this.stepFocus(deviceId, req))
+ if (type === 'scroll') { this.scroll(req); return response({}) }
if ('focusRevision' in req && (typeof req.focusRevision !== 'string' || !req.focusRevision)) fail('INVALID_REQUEST', 'focusRevision must be a nonempty string')
if (type === 'agents.list') {
return response({ machineId: this.options.machineId, agents: this.options.agents().map(a => {
diff --git a/desktop/lib/autonomous_device/autonomous_device_cli.dart b/desktop/lib/autonomous_device/autonomous_device_cli.dart
index d5bee2a9c..ea4c059f5 100644
--- a/desktop/lib/autonomous_device/autonomous_device_cli.dart
+++ b/desktop/lib/autonomous_device/autonomous_device_cli.dart
@@ -18,9 +18,9 @@ class AutonomousDeviceCliException implements Exception {
final String code;
final String message;
String get userMessage => switch (code) {
- 'CODE_MISMATCH' => 'That code did not match. Generate a new code on your Autonomous device, then try again.',
- 'RATE_LIMITED' => 'Too many pairing attempts. Wait five minutes, then generate a new code on your Autonomous device and try again.',
- 'EXPIRED' => 'The pairing code expired. Generate a new code on your Autonomous device, then try again.',
+ 'CODE_MISMATCH' => 'That code did not match. Generate a new code on your Autonomous robot, then try again.',
+ 'RATE_LIMITED' => 'Too many pairing attempts. Wait five minutes, then generate a new code on your Autonomous robot and try again.',
+ 'EXPIRED' => 'The pairing code expired. Generate a new code on your Autonomous robot, then try again.',
_ => message,
};
bool get unsupported =>
@@ -29,7 +29,7 @@ class AutonomousDeviceCliException implements Exception {
String toString() => message;
}
-/// The CLI owns credentials and Autonomous device trust. Pair codes remain in memory only.
+/// The CLI owns credentials and Autonomous robot trust. Pair codes remain in memory only.
class AutonomousDeviceCli {
AutonomousDeviceCli({HarnessCliRunner? runner})
: _runner = runner ?? HarnessCliRunner();
@@ -48,7 +48,7 @@ class AutonomousDeviceCli {
deviceId.isEmpty) {
throw const AutonomousDeviceCliException(
'BAD_REQUEST',
- 'Enter the six-character code shown on your Autonomous device.',
+ 'Enter the six-character code shown on your Autonomous robot.',
);
}
return command(
@@ -93,7 +93,7 @@ class AutonomousDeviceCli {
// A timed-out mutation may have succeeded. Read state before retrying it.
throw const AutonomousDeviceCliException(
'TIMEOUT',
- 'The command timed out. Refresh the Autonomous device status before trying again.',
+ 'The command timed out. Refresh the Autonomous robot status before trying again.',
);
}
final output = await stdout;
@@ -111,7 +111,7 @@ class AutonomousDeviceCli {
if (error is Map) {
throw AutonomousDeviceCliException(
error['code']?.toString() ?? 'FAILED',
- error['message']?.toString() ?? 'The Autonomous device command failed.',
+ error['message']?.toString() ?? 'The Autonomous robot command failed.',
);
}
if (exitCode != 0 || result == null) {
@@ -121,7 +121,7 @@ class AutonomousDeviceCli {
).hasMatch('$output\n$errorOutput');
throw AutonomousDeviceCliException(
unsupported ? 'UNKNOWN_COMMAND' : 'FAILED',
- unsupported ? 'This Harness CLI does not support Autonomous devices.' : 'The Autonomous device command failed. Check that Harness is running and the device is on the same network.',
+ unsupported ? 'This Harness CLI does not support Autonomous robots.' : 'The Autonomous robot command failed. Check that Harness is running and the device is on the same network.',
);
}
return result;
diff --git a/desktop/lib/settings/sections/devices_section.dart b/desktop/lib/settings/sections/devices_section.dart
index 906debcfc..fde0d8107 100644
--- a/desktop/lib/settings/sections/devices_section.dart
+++ b/desktop/lib/settings/sections/devices_section.dart
@@ -197,14 +197,14 @@ class _DevicesSectionState extends State<DevicesSection> {
if (deviceId == null ||
!_discovered.any((device) => device['id'] == deviceId)) {
setState(
- () => _actionError = 'Select your discovered Autonomous device first.',
+ () => _actionError = 'Select your discovered Autonomous robot first.',
);
return;
}
if (!RegExp(r'^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{6}$').hasMatch(code)) {
setState(
() => _actionError =
- 'Enter the six-character code shown on your Autonomous device.',
+ 'Enter the six-character code shown on your Autonomous robot.',
);
return;
}
@@ -231,10 +231,10 @@ class _DevicesSectionState extends State<DevicesSection> {
Future<void> _revoke(Map<String, dynamic> device) async {
if (!await _confirm(
- 'Revoke Autonomous device?',
- 'Disconnect ${device['label'] ?? 'this Autonomous device'} and remove its access to this computer. '
+ 'Revoke Autonomous robot?',
+ 'Disconnect ${device['label'] ?? 'this Autonomous robot'} and remove its access to this computer. '
'It will need to pair again.',
- 'Revoke Autonomous device',
+ 'Revoke Autonomous robot',
)) {
return;
}
@@ -254,8 +254,8 @@ class _DevicesSectionState extends State<DevicesSection> {
child: OutlinedButton(onPressed: onPressed, child: Text(label)),
);
return SectionScaffold(
- title: 'Autonomous devices',
- subtitle: 'Connect directly to your Autonomous device.',
+ title: 'Autonomous robots',
+ subtitle: 'Connect directly to your Autonomous robot.',
child: SingleChildScrollView(
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
@@ -280,7 +280,7 @@ class _DevicesSectionState extends State<DevicesSection> {
),
if (_unsupported)
SettingRow(
- title: 'Update Harness CLI to use Autonomous devices.',
+ title: 'Update Harness CLI to use Autonomous robots.',
detail: 'Run this command in Terminal, then refresh this page.',
control: SizedBox(
width: SettingRow.controlWidth,
@@ -289,7 +289,7 @@ class _DevicesSectionState extends State<DevicesSection> {
const Expanded(child: SelectableText('harness update')),
AppIconButton(
icon: Icons.refresh_rounded,
- tooltip: 'Refresh Autonomous device status',
+ tooltip: 'Refresh Autonomous robot status',
onPressed: disabled
? null
: () => unawaited(_refresh()),
@@ -313,7 +313,7 @@ class _DevicesSectionState extends State<DevicesSection> {
if (!_unsupported && !_loading) ...[
for (final device in _devices) ...[
SettingRow(
- title: device['label']?.toString() ?? 'Autonomous device',
+ title: device['label']?.toString() ?? 'Autonomous robot',
// The fingerprint belongs to the device it identifies, not to
// a row of its own two lines below it.
detail: [
@@ -341,7 +341,7 @@ class _DevicesSectionState extends State<DevicesSection> {
: 'Pair another device',
alignTop: true,
detail: _discovered.isEmpty
- ? 'No Autonomous devices found. Keep your device on the same network, then refresh.'
+ ? 'No Autonomous robots found. Keep your device on the same network, then refresh.'
: 'Select your device and enter its six-character code. Separators are allowed, for example ABC-123.',
control: SizedBox(
width: SettingRow.controlWidth,
@@ -367,7 +367,7 @@ class _DevicesSectionState extends State<DevicesSection> {
value: device['id'] as String,
label:
device['name']?.toString() ??
- 'Autonomous device',
+ 'Autonomous robot',
),
],
onChanged: (value) => setState(() {
@@ -381,7 +381,7 @@ class _DevicesSectionState extends State<DevicesSection> {
const SizedBox(width: 8),
AppIconButton(
icon: Icons.refresh_rounded,
- tooltip: 'Refresh Autonomous device status',
+ tooltip: 'Refresh Autonomous robot status',
onPressed: disabled
? null
: () => unawaited(_refresh()),
diff --git a/desktop/lib/settings/settings_section.dart b/desktop/lib/settings/settings_section.dart
index 3c5de11ef..bd4537be2 100644
--- a/desktop/lib/settings/settings_section.dart
+++ b/desktop/lib/settings/settings_section.dart
@@ -11,7 +11,7 @@ import '../logging/debug_surface.dart';
enum SettingsSection {
account(LucideIcons.user300, 'Account'),
usage(LucideIcons.chartNoAxesColumn300, 'Usage'),
- devices(LucideIcons.zap300, 'Autonomous devices'),
+ devices(LucideIcons.zap300, 'Autonomous robots'),
shortcuts(LucideIcons.keyboard300, 'Keyboard shortcuts'),
debug(LucideIcons.bug300, 'Debug'),
tracking(LucideIcons.activity300, 'Tracking'),
diff --git a/desktop/test/autonomous_device_pairing_test.dart b/desktop/test/autonomous_device_pairing_test.dart
index 3b7f8b8ba..0731d2c13 100644
--- a/desktop/test/autonomous_device_pairing_test.dart
+++ b/desktop/test/autonomous_device_pairing_test.dart
@@ -47,12 +47,12 @@ class FakeAutonomousDeviceCli extends AutonomousDeviceCli {
devices.add({
'id': 'fingerprint-$deviceId',
'fingerprint': 'fingerprint-$deviceId',
- 'label': 'Autonomous device',
+ 'label': 'Autonomous robot',
'online': true,
});
return {
'state': 'paired',
- 'label': 'Autonomous device',
+ 'label': 'Autonomous robot',
'fingerprint': 'fingerprint-$deviceId',
};
}
@@ -113,7 +113,7 @@ void main() {
expect(find.byType(SettingRow), findsOneWidget);
expect(find.text('Pair'), findsOneWidget);
expect(find.text('Refresh'), findsNothing);
- expect(find.text('Pair an Autonomous device'), findsNothing);
+ expect(find.text('Pair an Autonomous robot'), findsNothing);
expect(find.text('Computer address'), findsNothing);
expect(find.text('Cancel pairing'), findsNothing);
},
@@ -163,7 +163,7 @@ void main() {
await submit(tester, 'ABC234');
expect(cli.submissions, isEmpty);
expect(
- find.text('Select your discovered Autonomous device first.'),
+ find.text('Select your discovered Autonomous robot first.'),
findsOneWidget,
);
});
@@ -222,7 +222,7 @@ void main() {
await refresh(tester);
expect(
find.text(
- 'That code did not match. Generate a new code on your Autonomous device, then try again.',
+ 'That code did not match. Generate a new code on your Autonomous robot, then try again.',
),
findsOneWidget,
);
@@ -263,7 +263,7 @@ void main() {
final cli = FakeAutonomousDeviceCli()..discovered = [];
await open(tester, cli);
expect(
- find.textContaining('No Autonomous devices found.'),
+ find.textContaining('No Autonomous robots found.'),
findsOneWidget,
);
await submit(tester, 'ABC234');
@@ -285,7 +285,7 @@ void main() {
]);
expect(
find.text(
- 'That code did not match. Generate a new code on your Autonomous device, then try again.',
+ 'That code did not match. Generate a new code on your Autonomous robot, then try again.',
),
findsNothing,
);
@@ -296,7 +296,7 @@ void main() {
testWidgets('unsupported CLI offers update guidance', (tester) async {
await open(tester, FakeAutonomousDeviceCli()..unsupported = true);
expect(
- find.text('Update Harness CLI to use Autonomous devices.'),
+ find.text('Update Harness CLI to use Autonomous robots.'),
findsOneWidget,
);
expect(codeField, findsNothing);
diff --git a/docs/autonomous-device-integration.md b/docs/autonomous-device-integration.md
index 94914a6d2..3f0805af1 100644
--- a/docs/autonomous-device-integration.md
+++ b/docs/autonomous-device-integration.md
@@ -135,6 +135,7 @@ a duplicate may return any retained receipt state. Supported operations:
| `focus.ensure` | none | Same snapshot as `focus.get`; enable-time first-agent fallback acknowledged by Desktop |
| `focus.get` | none | `focus:null\|{machineId,agentId,name?},focusRevision` |
| `focus.step` | `direction:"next"\|"previous",idempotencyKey,focusRevision` | Same snapshot as `focus.get`, after Desktop acknowledged the new agent — see *Stepping focus* |
+| `scroll` | `phase:"down"\|"move"\|"up",dy?,velocity?` | none — see *Scrolling the focused terminal* |
| `agents.list` | none | `machineId,agents:[{machineId,agentId,name,engine,state,recap?}]` — `recap` is the agent's newest turn headline (≤200 chars, the same string `recap` returns as `turns[0].recap`); absent until a turn has been summarised |
| `status` | `machineId,agentId` | `machineId,agentId,state,openQuestion:null\|{requestId,questions}` |
| `recap` | `machineId,agentId,n?` (default 3, integer 1–5) | `machineId,agentId,turns:[{kind,text,recap?,fullText?}]` |
@@ -308,3 +309,27 @@ the window can show one; the local daemon then reports the app's focus leaving t
to that target still returns `MACHINE_MISMATCH`. The OS remains responsible for showing that a
remote target is not supported for dispatch. Pairing, transport, credentials and task dispatch are
untouched; older CLIs do not list `focus.step` in hello capabilities.
+
+### Scrolling the focused terminal
+
+`scroll` is one report of a finger on the paired device's glass, forwarded to the terminal Desktop
+has in front — the same `dial_scroll` frame the USB dial sends, so the app treats both alike:
+
+```json
+{"type":"scroll","requestId":"<uuid>","phase":"move","dy":-24}
+{"type":"scroll","requestId":"<uuid>","phase":"up","dy":-3,"velocity":-900}
+```
+
+The device is a touchpad here: it reports **movement**, not a position, because it cannot know how
+tall the terminal is; the terminal owns the scrollback and does the arithmetic. A stroke is sent in
+pieces — `down` when the finger lands (the window stops any coasting), `move`s carrying `dy` device
+pixels travelled since the last report (positive = down the glass), and `up` when it lifts, whose
+`velocity` (device px/s, signed like `dy`) becomes the fling. `dy` and `velocity` default to 0 and
+must be integers within ±4096 and ±100000. Send `up` for every `down`: a stroke that never closes
+holds a drag open on the app side until the next `down`.
+
+A stroke is a stream, not a mutation: there is no `idempotencyKey`, no receipt, nothing retained, and
+nothing to retry — a lost `move` is a shorter scroll. Success is an empty `scroll_result`. Only the
+terminal Desktop has focused scrolls; a viewer pane does not. Errors: `FOCUS_UNAVAILABLE` when no
+Desktop window is connected; `INVALID_REQUEST` for a bad phase, a non-integer or out-of-range value,
+or any other field. Older CLIs do not list `scroll` in hello capabilities.
diff --git a/docs/vi/autonomous-device-integration_vi.md b/docs/vi/autonomous-device-integration_vi.md
index ec1f7c894..4fa4adf35 100644
--- a/docs/vi/autonomous-device-integration_vi.md
+++ b/docs/vi/autonomous-device-integration_vi.md
@@ -151,3 +151,27 @@ tile đó; daemon local khi đó báo focus của app rời máy này (`focus:nu
target remote nếu Desktop công bố ở đây), và `turn.send` tới target đó vẫn trả `MACHINE_MISMATCH`.
OS vẫn chịu trách nhiệm hiển thị rằng target remote chưa được hỗ trợ dispatch. Pairing, transport,
credential và flow gửi task không đổi; CLI cũ không liệt kê `focus.step` trong capabilities của hello.
+
+### Cuộn terminal đang focus
+
+`scroll` là một lần báo ngón tay trên mặt kính của thiết bị đã pair, chuyển thẳng tới terminal mà
+Desktop đang mở trước mặt — đúng frame `dial_scroll` mà dial USB gửi, nên app xử lý hai bên như nhau:
+
+```json
+{"type":"scroll","requestId":"<uuid>","phase":"move","dy":-24}
+{"type":"scroll","requestId":"<uuid>","phase":"up","dy":-3,"velocity":-900}
+```
+
+Ở đây thiết bị là một touchpad: nó báo **quãng di chuyển**, không phải vị trí, vì nó không biết
+terminal cao bao nhiêu; terminal giữ scrollback và tự tính. Một vuốt gửi thành nhiều mảnh — `down`
+khi ngón tay chạm (cửa sổ dừng mọi quán tính đang chạy), các `move` mang `dy` pixel thiết bị đã đi
+kể từ lần báo trước (dương = xuống dưới mặt kính), và `up` khi nhấc tay, với `velocity` (px/s của
+thiết bị, cùng dấu với `dy`) trở thành cú fling. `dy` và `velocity` mặc định 0, phải là số nguyên
+trong ±4096 và ±100000. Mỗi `down` phải có `up`: vuốt không đóng sẽ giữ trạng thái kéo bên app cho
+tới `down` kế tiếp.
+
+Một vuốt là stream, không phải mutation: không `idempotencyKey`, không receipt, không lưu gì, và
+không có gì để retry — mất một `move` chỉ là cuộn ngắn hơn. Thành công trả `scroll_result` rỗng.
+Chỉ terminal Desktop đang focus mới cuộn; pane viewer thì không. Lỗi: `FOCUS_UNAVAILABLE` khi không
+có cửa sổ Desktop; `INVALID_REQUEST` khi phase sai, giá trị không phải số nguyên hoặc ngoài khoảng,
+hoặc có field lạ. CLI cũ không liệt kê `scroll` trong capabilities của hello.