[03-Developer] #260 in-app tool calling (Gemma 4 multi-turn)

ADR-0005 in-process tool runtime — 6 tools (catalog 2 + tracker 2 +
habit 2), ToolDispatcher with JSON-schema validation + modal ConfirmGate
for destructive ops, multi-turn LlmChatSession abstraction wired to
flutter_gemma 0.16.5 (ToolChoice.auto), ChatSessionController with
MAX_TURNS=4 safety + 8-turn history hint, ChatScreen entry behind AI
opt-in. R3/R7/R8 enforced inside handlers. 41 new tests (envelope,
catalog/tracker/habit tools, dispatcher, controller loop) — 151 total
passing.

Refs #260

app/lib/data/ai/gemma_llm_service.dart

@@ -3,6 +3,7 @@ import 'dart:io';
 import 'package:flutter/foundation.dart';
 import 'package:flutter_gemma/flutter_gemma.dart';
 
+import '../../ai/tools/tool_definition.dart' as tools;
 import 'llm_service.dart';
 
 /// HuggingFace access token injected at build time via
@@ -114,6 +115,93 @@ class GemmaLlmService implements LlmService {
       }
     }
   }
+
+  @override
+  Future<LlmChatSession> startChat({
+    required List<tools.ToolDefinition> tools,
+  }) async {
+    if (!_loaded || _model == null) {
+      throw StateError('LlmService not loaded');
+    }
+    final gemmaTools = tools
+        .map((t) => Tool(
+              name: t.name,
+              description: t.description,
+              parameters: Map<String, dynamic>.from(t.parametersSchema),
+            ))
+        .toList();
+    final chat = await _model!.createChat(
+      modelType: ModelType.gemma4,
+      supportsFunctionCalls: true,
+      // ToolChoice.auto = 모델이 자율 결정 (multi-tool + reply-only 모두 지원).
+      toolChoice: ToolChoice.auto,
+      tools: gemmaTools,
+    );
+    return _GemmaChatSession(chat);
+  }
+}
+
+class _GemmaChatSession implements LlmChatSession {
+  final dynamic _chat;
+  bool _closed = false;
+
+  _GemmaChatSession(this._chat);
+
+  @override
+  Stream<LlmChatEvent> sendUser(String text) {
+    if (_closed) {
+      throw StateError('LlmChatSession is closed');
+    }
+    return _run(Message.text(text: text, isUser: true));
+  }
+
+  @override
+  Stream<LlmChatEvent> sendToolResult({
+    required String toolName,
+    required Map<String, dynamic> result,
+  }) {
+    if (_closed) {
+      throw StateError('LlmChatSession is closed');
+    }
+    return _run(Message.toolResponse(toolName: toolName, response: result));
+  }
+
+  Stream<LlmChatEvent> _run(Message msg) async* {
+    await _chat.addQueryChunk(msg);
+    final Stream<ModelResponse> stream = _chat.generateChatResponseAsync();
+    await for (final event in stream) {
+      if (event is TextResponse) {
+        yield LlmTextChunk(event.token);
+      } else if (event is FunctionCallResponse) {
+        yield LlmFunctionCall(
+          event.name,
+          Map<String, dynamic>.from(event.args),
+        );
+        return; // model hands control back to caller for tool exec
+      } else if (event is ParallelFunctionCallResponse &&
+          event.calls.isNotEmpty) {
+        // ADR-0005: parallel calls collapsed to first — sequential dispatch.
+        final first = event.calls.first;
+        yield LlmFunctionCall(
+          first.name,
+          Map<String, dynamic>.from(first.args),
+        );
+        return;
+      }
+      // ThinkingResponse / other: skip.
+    }
+  }
+
+  @override
+  Future<void> close() async {
+    if (_closed) return;
+    _closed = true;
+    try {
+      await _chat.close();
+    } catch (_) {
+      // Best-effort cleanup.
+    }
+  }
 }
 
 /// Extracts the first `FunctionCallResponse(name == expectedName)` from

app/lib/data/ai/llm_service.dart

@@ -1,3 +1,5 @@
+import '../../ai/tools/tool_definition.dart';
+
 /// Abstract LLM backend.
 ///
 /// Concrete impls: `GemmaLlmService` (flutter_gemma) and `MockLlmService` (tests).
@@ -7,6 +9,7 @@
 /// - [generateStructured] returns a parsed JSON map matching the schema.
 ///   On schema/parse failure throws [FormatException].
 /// - [unload] is idempotent.
+/// - [startChat] opens a multi-turn chat session for tool calling (#260).
 abstract class LlmService {
   bool get isLoaded;
 
@@ -20,6 +23,45 @@ abstract class LlmService {
     String prompt,
     Map<String, dynamic> schema,
   );
+
+  /// Opens a chat session that supports multi-turn user input + tool result
+  /// submission with the supplied [tools]. See ADR-0005.
+  Future<LlmChatSession> startChat({
+    required List<ToolDefinition> tools,
+  });
+}
+
+/// Streaming chat session for the tool-calling loop.
+///
+/// Lifecycle: created by [LlmService.startChat], lives for a single chat
+/// screen, must be [close]d when the user dismisses the screen. Each
+/// `send*` call returns a stream of [LlmChatEvent]s until the model yields
+/// control (text done or a function call requested).
+abstract class LlmChatSession {
+  Stream<LlmChatEvent> sendUser(String text);
+
+  Stream<LlmChatEvent> sendToolResult({
+    required String toolName,
+    required Map<String, dynamic> result,
+  });
+
+  Future<void> close();
+}
+
+/// Events emitted by [LlmChatSession]. See ADR-0005 §C.
+sealed class LlmChatEvent {
+  const LlmChatEvent();
+}
+
+final class LlmTextChunk extends LlmChatEvent {
+  final String text;
+  const LlmTextChunk(this.text);
+}
+
+final class LlmFunctionCall extends LlmChatEvent {
+  final String name;
+  final Map<String, dynamic> args;
+  const LlmFunctionCall(this.name, this.args);
 }
 
 /// Programmable stub for tests. Use [enqueueResponse] / [enqueueError].
@@ -31,6 +73,12 @@ class MockLlmService implements LlmService {
   Map<String, dynamic>? lastSchema;
   Duration responseDelay = Duration.zero;
 
+  /// Queues consumed by [startChat] in order. Each entry is the event list
+  /// returned for a single `send*` call.
+  final List<List<LlmChatEvent>> chatScript = [];
+  int chatStartCount = 0;
+  MockLlmChatSession? lastChat;
+
   @override
   bool get isLoaded => _loaded;
 
@@ -52,6 +100,12 @@ class MockLlmService implements LlmService {
     _queue.add(_Response.error(error));
   }
 
+  /// Enqueue one batch of events that will be emitted on the next
+  /// `sendUser` or `sendToolResult` call. Items are streamed in order.
+  void enqueueChatEvents(List<LlmChatEvent> events) {
+    chatScript.add(events);
+  }
+
   @override
   Future<Map<String, dynamic>> generateStructured(
     String prompt,
@@ -73,6 +127,61 @@ class MockLlmService implements LlmService {
     if (r.error != null) throw r.error!;
     return r.value!;
   }
+
+  @override
+  Future<LlmChatSession> startChat({
+    required List<ToolDefinition> tools,
+  }) async {
+    if (!_loaded) {
+      throw StateError('LlmService not loaded');
+    }
+    chatStartCount += 1;
+    final session = MockLlmChatSession(chatScript);
+    lastChat = session;
+    return session;
+  }
+}
+
+/// Mock chat session that replays pre-queued events from [MockLlmService].
+class MockLlmChatSession implements LlmChatSession {
+  final List<List<LlmChatEvent>> _script;
+  int sendCount = 0;
+  final List<String> userInputs = [];
+  final List<(String, Map<String, dynamic>)> toolResults = [];
+  bool closed = false;
+
+  MockLlmChatSession(this._script);
+
+  Stream<LlmChatEvent> _emitNext() async* {
+    sendCount += 1;
+    if (_script.isEmpty) {
+      throw StateError('MockLlmChatSession: no queued events');
+    }
+    final batch = _script.removeAt(0);
+    for (final ev in batch) {
+      yield ev;
+    }
+  }
+
+  @override
+  Stream<LlmChatEvent> sendUser(String text) {
+    userInputs.add(text);
+    return _emitNext();
+  }
+
+  @override
+  Stream<LlmChatEvent> sendToolResult({
+    required String toolName,
+    required Map<String, dynamic> result,
+  }) {
+    toolResults.add((toolName, result));
+    return _emitNext();
+  }
+
+  @override
+  Future<void> close() async {
+    closed = true;
+  }
 }
 
 class _Response {