@hybridaione/hybridclaw 0.1.21 → 0.1.24

package/CHANGELOG.md

@@ -8,6 +8,65 @@
 
 ### Fixed
 
+## [0.1.24](https://github.com/HybridAIOne/hybridclaw/tree/v0.1.24)
+
+### Added
+
+- **Discord edit-in-place streaming pipeline**: Added end-to-end assistant text delta streaming from container runtime to Discord delivery, including NDJSON `text` events and incremental Discord message edits.
+- **Discord stream/chunk primitives**: Added `src/discord-stream.ts` (stream lifecycle manager with throttled edits and rollover) and `src/chunk.ts` (boundary-aware chunking with code-fence preservation and line limits).
+- **Discord conversational event handling**: Added message debounce batching, in-flight run tracking, message edit/delete interruption handling, and thumbs-down reaction feedback capture for subsequent context.
+
+### Changed
+
+- **Discord reply delivery semantics**: Replaced fixed 2000-char truncation with complete multi-message delivery and chunk-safe send/edit behavior.
+- **Discord responsiveness model**: Message handling now keeps typing indicators alive during long turns, updates presence while processing, and acknowledges queued work with processing reactions.
+- **Discord context assembly**: Conversation turns now prepend reply-chain/thread context and include parsed attachment context (inline text/code where readable, metadata fallback for unsupported types).
+
+### Fixed
+
+- **Long response truncation**: Removed `.slice(0, 2000)` response truncation paths that dropped tail content and broke code blocks.
+- **Perceived Discord stalls**: Fixed single-shot typing behavior by introducing a periodic typing loop for long-running turns.
+- **Mid-turn user correction handling**: Edited/deleted source messages now cancel in-flight processing and clean up partial streamed output to prevent orphaned replies.
+- **Screenshot reply verbosity in Discord**: Image-attachment responses now suppress workspace-path narration and default to concise delivery text (`Here it is.`/`Here they are.`).
+
+## [0.1.23](https://github.com/HybridAIOne/hybridclaw/tree/v0.1.23)
+
+### Added
+
+- **Token usage observability fields**: `model.usage` audit events now include prompt/completion/total token counts (API-reported when available, deterministic estimates as fallback), model-call counts, and char-level prompt/completion sizing.
+- **Context optimization telemetry**: Added `context.optimization` audit events with history compression statistics (per-message truncation count, dropped chars/messages, and applied history budgets).
+
+### Changed
+
+- **Runtime-config migration logging clarity**: Startup schema normalization now logs a dedicated `normalized config schema vN` message when version is unchanged, instead of reporting a misleading `migrated ... from vN to vN`.
+- **History prompt assembly**: Conversation history now applies per-message truncation plus head/tail-aware budget compression to reduce token load while preserving recent context.
+- **Bootstrap file truncation strategy**: Oversized workspace context files now use head/tail truncation (70/20 split) instead of head-only clipping.
+- **Prompt mode tiers**: Prompt hooks now support `full`/`minimal`/`none` modes; pre-compaction memory flush uses `minimal` mode to reduce static prompt overhead.
+
+### Fixed
+
+- **Local runtime-state git noise**: Added `.hybridclaw/` to `.gitignore` so container image fingerprint state files are no longer reported as untracked changes.
+
+## [0.1.22](https://github.com/HybridAIOne/hybridclaw/tree/v0.1.22)
+
+### Added
+
+- **Skills trust scanner**: Added `src/skills-guard.ts` with Hermes-derived regex threat detection (exfiltration, prompt injection, destructive ops, persistence, reverse shells, obfuscation, supply chain, credential exposure), structural checks (file count/size limits, binary blocking, symlink escape checks), and invisible-unicode detection.
+- **Skill scan cache**: Added mtime-signature + content-hash scanner caching to skip re-scan on unchanged skills.
+- **Extended SKILL frontmatter**: Added support for `always`, `requires.bins`, `requires.env`, and `metadata.hybridclaw.{tags,related_skills}` while preserving backward compatibility for existing fields.
+
+### Changed
+
+- **Skill discovery tiers**: Expanded skill discovery precedence to `extra < bundled < codex < claude < agents-personal < agents-project < workspace`, including `config.skills.extraDirs[]` and `.agents/skills` interop paths.
+- **Skill prompt embedding modes**: Implemented Always/Summary/Hidden behavior via frontmatter flags (`always`, `disable-model-invocation`) with `maxAlwaysChars=10000`, `maxSkillsPromptChars=30000`, and `maxSkillsInPrompt=150`.
+- **Skill eligibility gating**: Skills with unmet `requires` are now silently excluded from both prompt availability and slash-command resolution.
+- **Skill slash commands**: Added command-name sanitization (32-char max), reserved built-in command blocking, and deterministic collision deduplication (`-2`, `-3`, ...), while keeping `/skill name`, `/skill:name`, and `/<name>` invocation compatibility.
+- **Web tool routing guidance**: Tool descriptions and runtime prompt guidance now include explicit `web_fetch` vs browser decision rules, concrete SPA/auth/app categories, and quantified cost asymmetry.
+- **web_fetch escalation signaling**: `web_fetch` now emits structured escalation hints (`javascript_required`, `spa_shell_only`, `empty_extraction`, `boilerplate_only`, `bot_blocked`) and surfaces them in tool output for browser fallback routing.
+- **Browser extraction steering**: `browser_navigate` responses now include text preview metadata and explicit next-step hints (`browser_snapshot` with `mode="full"`), and docs/prompts now clarify that `browser_pdf` is export-only (not text extraction).
+
+### Fixed
+
 ## [0.1.21](https://github.com/HybridAIOne/hybridclaw/tree/v0.1.21)
 
 ### Added

package/README.md

@@ -11,6 +11,8 @@ npm install -g @hybridaione/hybridclaw
 hybridclaw onboarding
 ```
 
+Latest release: [v0.1.24](https://github.com/HybridAIOne/hybridclaw/releases/tag/v0.1.24)
+
 ## HybridAI Advantage
 
 - Security-focused foundation
@@ -75,9 +77,12 @@ HybridClaw best-in-class capabilities:
 - explicit trust-model acceptance during onboarding (recorded in `config.json`)
 - typed `config.json` runtime settings with defaults, validation, and hot reload
 - formal prompt hook orchestration (`bootstrap`, `memory`, `safety`)
+- Discord conversational UX: edit-in-place streaming responses, fence-safe chunking beyond Discord's 2000-char limit, typing keepalive, debounce batching, reply-chain-aware context, and concise attachment-first screenshot replies
+- token-efficient context assembly: per-message history truncation, hard history budgets with head/tail preservation, and head/tail truncation for oversized bootstrap files
 - proactive runtime layer with active-hours gating, push delegation (`single`/`parallel`/`chain`), depth-aware tool policy, and retry controls
 - structured audit trail: append-only hash-chained wire logs (`data/audit/<session>/wire.jsonl`) with tamper-evident immutability, normalized SQLite audit tables, and verification/search CLI commands
 - observability export: incremental `events:batch` forwarding with durable cursor tracking and bot-scoped ingest token lifecycle via `ingest-token:ensure`
+- model token telemetry in audit/observability events (`model.usage`) with API usage + deterministic fallback estimates
 - gateway lifecycle controls: managed + unmanaged restart/stop flows with graceful shutdown fallback paths
 - instruction-integrity approval flow: core instruction docs (`AGENTS.md`, `SECURITY.md`, `TRUST_MODEL.md`) are hash-verified against a local approved baseline before TUI start
 
@@ -87,6 +92,7 @@ HybridClaw uses typed runtime config in `config.json` (auto-created on first run
 
 - Start from `config.example.json` (reference)
 - Runtime watches `config.json` and hot-reloads most settings (model defaults, heartbeat, prompt hooks, limits, etc.)
+- `skills.extraDirs` adds additional enterprise/shared skill roots (lowest precedence tier)
 - `proactive.*` controls autonomous behavior (`activeHours`, `delegation`, `autoRetry`)
 - `observability.*` controls push ingest into HybridAI (`events:batch` endpoint, batching, identity metadata)
 - Some settings require restart to fully apply (for example HTTP bind host/port)
@@ -138,6 +144,7 @@ HybridClaw can forward structured audit records to HybridAI's ingest API:
 - transport: bearer ingest token auto-fetched via `POST /api/v1/agent-observability/ingest-token:ensure` using `HYBRIDAI_API_KEY`
 - delivery: incremental batches with persisted cursor (`observability_offsets` table), max 1000 events and max 2,000,000-byte payload per request
 - token handling: token cache is stored locally in SQLite (`observability_ingest_tokens`) and automatically refreshed on ingest auth failures
+- token visibility: `model.usage` payloads include `promptTokens`, `completionTokens`, `totalTokens`, plus estimated and API-native counters for accuracy/coverage
 
 Config keys (in `config.json`):
 
@@ -178,13 +185,25 @@ HybridClaw supports `SKILL.md`-based skills (`<skill-name>/SKILL.md`).
 
 You can place skills in:
 
-- `./skills/<skill-name>/SKILL.md` (project-level)
-- `<agent workspace>/skills/<skill-name>/SKILL.md` (agent-specific)
-- `$CODEX_HOME/skills/<skill-name>/SKILL.md`, `~/.codex/skills/<skill-name>/SKILL.md`, or `~/.claude/skills/<skill-name>/SKILL.md` (managed/shared)
+- any directory listed in `config.skills.extraDirs[]` (enterprise/shared)
+- bundled package skills (`<hybridclaw install>/skills/<skill-name>/SKILL.md`)
+- `$CODEX_HOME/skills/<skill-name>/SKILL.md` or `~/.codex/skills/<skill-name>/SKILL.md`
+- `~/.claude/skills/<skill-name>/SKILL.md`
+- `~/.agents/skills/<skill-name>/SKILL.md`
+- `./.agents/skills/<skill-name>/SKILL.md` (project)
+- `./skills/<skill-name>/SKILL.md` (workspace)
 
 Load precedence is:
 
-- managed/shared < project < agent workspace
+- `extra < bundled < codex < claude < agents-personal < agents-project < workspace`
+- skills are merged by `name`; higher-precedence sources override lower-precedence ones
+
+Security scanning is trust-aware:
+
+- `bundled` sources are treated as `builtin` and not scanned
+- `workspace` sources (`./skills/`, `./.agents/skills/`) are scanned; `caution` is allowed, `dangerous` is blocked
+- `personal` sources (`~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`) are scanned and blocked on `caution`/`dangerous`
+- scanner includes Hermes-derived regex checks, structural limits (50 files, 1MB total, 256KB/file, binary/symlink checks), invisible-unicode detection, and mtime+content-hash cache reuse
 
 ### Required format
 
@@ -196,6 +215,14 @@ name: repo-orientation
 description: Quickly map an unfamiliar repository and identify where a requested feature should be implemented.
 user-invocable: true
 disable-model-invocation: false
+always: false
+requires:
+  bins: [docker, git]
+  env: [GITHUB_TOKEN]
+metadata:
+  hybridclaw:
+    tags: [devops, docker]
+    related_skills: [kubernetes]
 ---
 
 # Repo Orientation
@@ -208,16 +235,25 @@ Supported frontmatter keys:
 - `description` (required)
 - `user-invocable` (optional, default `true`)
 - `disable-model-invocation` (optional, default `false`)
+- `always` (optional, default `false`; embeds full skill body in the system prompt up to `maxAlwaysChars=10000`, then demotes to summary)
+- `requires.bins` / `requires.env` (optional; skill is excluded unless requirements are met)
+- `metadata.hybridclaw.tags` / `metadata.hybridclaw.related_skills` (optional metadata namespace)
 
 ### Using skills
 
-Skills are listed to the model as metadata (`name`, `description`, `location`), and the model reads `SKILL.md` on demand with the `read` tool.
+Skills are listed to the model as metadata (`name`, `description`, `location`), and the model reads `SKILL.md` on demand with the `read` tool. Skills with `always: true` are embedded directly in the system prompt.
+
+Prompt embedding modes:
+
+- `Always`: `always: true` embeds full body in `<skill_always ...>` (budgeted by `maxAlwaysChars=10000`)
+- `Summary`: default mode, emits only XML metadata under `<available_skills>`
+- `Hidden`: `disable-model-invocation: true` excludes the skill from model prompt metadata (still invocable by slash command when `user-invocable: true`)
 
 Explicit invocation is supported via:
 
 - `/skill <name> [input]`
 - `/skill:<name> [input]`
-- `/<name> [input]` (when `user-invocable: true`)
+- `/<name> [input]` (when `user-invocable: true`; command names are sanitized to lowercase `a-z0-9-`, max 32 chars, with `-2`/`-3` dedup and built-in command-name blocking)
 
 Example skill in this repo:
 
@@ -233,8 +269,8 @@ The agent has access to these sandboxed tools inside the container:
 - `memory` — durable memory files (`MEMORY.md`, `USER.md`, `memory/YYYY-MM-DD.md`)
 - `session_search` — search/summarize historical sessions from transcript archives
 - `delegate` — push-based background subagent tasks (`single`, `parallel`, `chain`) with auto-announced completion (no polling)
-- `web_fetch` — fetch a URL and extract readable content (HTML → markdown/text)
-- `browser_*` (optional) — interactive browser automation (`navigate`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `screenshot`, `pdf`, `close`)
+- `web_fetch` — plain HTTP fetch + extraction for static/read-only content (docs, articles, READMEs, JSON/text APIs, direct files)
+- `browser_*` (optional) — full browser automation for JS-rendered or interactive pages (`navigate`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `screenshot`, `pdf`, `close`)
 
 `delegate` mode examples:
 
@@ -244,6 +280,12 @@ The agent has access to these sandboxed tools inside the container:
 
 Browser tooling notes:
 
+- Routing default: prefer `web_fetch` first for read-only retrieval.
+- Use browser tools for SPAs/web apps/auth flows/interaction tasks, or when `web_fetch` returns escalation hints (`javascript_required`, `spa_shell_only`, `empty_extraction`, `boilerplate_only`, `bot_blocked`).
+- Cost profile: browser calls are typically ~10-100x slower/more expensive than `web_fetch`.
+- Browser read flow: after `browser_navigate`, use `browser_snapshot` with `mode="full"` to extract content, then `browser_scroll` + `browser_snapshot` for additional lazy-loaded sections.
+- `browser_pdf` is for export artifacts, not text extraction.
+
 - The shipped container image preinstalls `agent-browser` and Chromium (Playwright).
 - You can override the binary via `AGENT_BROWSER_BIN` if needed.
 - User-directed authenticated browser-flow testing is supported (including filling/submitting login forms on the requested site).

package/config.example.json

@@ -6,6 +6,9 @@
     "trustModelVersion": "",
     "trustModelAcceptedBy": ""
   },
+  "skills": {
+    "extraDirs": []
+  },
   "discord": {
     "prefix": "!claw"
   },

package/container/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "hybridclaw-agent",
-  "version": "0.1.21",
+  "version": "0.1.24",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hybridclaw-agent",
-      "version": "0.1.21",
+      "version": "0.1.24",
       "dependencies": {
         "@mozilla/readability": "^0.6.0",
         "agent-browser": "^0.15.1",

package/container/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hybridclaw-agent",
-  "version": "0.1.21",
+  "version": "0.1.24",
   "type": "module",
   "scripts": {
     "build": "tsc",

package/container/src/browser-tools.ts

@@ -56,6 +56,24 @@ const EXTRACT_IFRAMES_SCRIPT = `(() => {
   }));
 })()`;
 
+const EXTRACT_TEXT_PREVIEW_SCRIPT = `(() => {
+  const bodyText = document.body ? String(document.body.innerText || '') : '';
+  const normalized = bodyText
+    .replace(/\\r/g, '')
+    .replace(/[ \\t]+\\n/g, '\\n')
+    .replace(/\\n{3,}/g, '\\n\\n')
+    .trim();
+  const previewLimit = 6000;
+  return {
+    text_length: normalized.length,
+    preview: normalized.slice(0, previewLimit),
+    preview_truncated: normalized.length > previewLimit,
+    has_noscript: Boolean(document.querySelector('noscript')),
+    root_shell: Boolean(document.querySelector('div#root:empty, div#app:empty, div#__next:empty')),
+    ready_state: String(document.readyState || ''),
+  };
+})()`;
+
 const NETWORK_TIMINGS_SCRIPT = `(() => {
   const entries = performance.getEntriesByType('resource');
   return entries
@@ -563,6 +581,19 @@ function buildBotDetectionWarning(titleValue: unknown): Record<string, unknown>
   };
 }
 
+function buildReadExtractionHint(params: {
+  contentLength: number;
+  hasNoscript: boolean;
+  rootShell: boolean;
+}): string {
+  const base =
+    'For content extraction, call browser_snapshot with {"mode":"full"} next. For long or lazy-loaded pages, run browser_scroll then browser_snapshot again.';
+  if (params.hasNoscript || params.rootShell || params.contentLength < 200) {
+    return `${base} This page currently looks dynamic/app-shell-like; do not conclude "inaccessible" before snapshot attempts.`;
+  }
+  return `${base} Avoid browser_pdf for text extraction; PDF export is for artifact output.`;
+}
+
 function extractVisionTextContent(content: unknown): string {
   if (typeof content === 'string') return content.trim();
   if (!Array.isArray(content)) return '';
@@ -754,12 +785,31 @@ export async function executeBrowserTool(name: string, args: Record<string, unkn
         const data = (result.data || {}) as Record<string, unknown>;
         const title = String(data.title || '');
         const botWarning = buildBotDetectionWarning(title);
+        const textEval = await runBrowserEval(effectiveSessionId, EXTRACT_TEXT_PREVIEW_SCRIPT, 20_000);
+        const textData = textEval.success ? asRecord(textEval.result) : null;
+        const contentPreview = typeof textData?.preview === 'string' ? textData.preview : '';
+        const contentLength =
+          typeof textData?.text_length === 'number' && Number.isFinite(textData.text_length)
+            ? Math.max(0, Math.floor(textData.text_length))
+            : 0;
+        const contentPreviewTruncated = textData?.preview_truncated === true;
+        const hasNoscript = textData?.has_noscript === true;
+        const rootShell = textData?.root_shell === true;
+        const readyState = typeof textData?.ready_state === 'string' ? textData.ready_state : '';
+        const extractionHint = buildReadExtractionHint({ contentLength, hasNoscript, rootShell });
         // Best-effort priming so browser_network has request listeners active quickly.
         await runAgentBrowser(effectiveSessionId, 'network', ['requests']).catch(() => undefined);
         return success({
           url: data.url || parsed.toString(),
           title,
           session_id: effectiveSessionId,
+          content_text_length: contentLength,
+          ...(contentPreview ? { content_preview: contentPreview } : {}),
+          ...(contentPreview ? { content_preview_truncated: contentPreviewTruncated } : {}),
+          ...(readyState ? { ready_state: readyState } : {}),
+          ...(hasNoscript ? { has_noscript: true } : {}),
+          ...(rootShell ? { root_shell: true } : {}),
+          read_extraction_hint: extractionHint,
           ...(botWarning ? { bot_detection_warning: botWarning } : {}),
         });
       }
@@ -1000,7 +1050,7 @@ export const BROWSER_TOOL_DEFINITIONS: ToolDefinition[] = [
     function: {
       name: 'browser_navigate',
       description:
-        'Navigate to an HTTP/HTTPS URL in a browser session. Private/loopback hosts are blocked by default (SSRF guard).',
+        'Navigate to a URL in a full browser session with JavaScript execution and dynamic rendering. Use for SPAs (React/Vue/Angular/Svelte), auth/login flows, dashboards/web apps (Notion, Google Docs, Airtable, Jira, etc.), interaction tasks (click/type/submit/scroll), bot/captcha/consent flows, or when web_fetch returns escalation hints (javascript_required, spa_shell_only, empty_extraction, boilerplate_only, bot_blocked). Prefer web_fetch instead for static docs/articles/wikis, direct API JSON/XML/text endpoints, and simple read-only retrieval. Important: browser_navigate opens the page but does not replace content extraction; for read/summarize tasks call browser_snapshot with mode="full" next. Browser usage is typically ~10-100x slower/more expensive than web_fetch. Private/loopback hosts are blocked by default (SSRF guard).',
       parameters: {
         type: 'object',
         properties: {
@@ -1015,7 +1065,7 @@ export const BROWSER_TOOL_DEFINITIONS: ToolDefinition[] = [
     function: {
       name: 'browser_snapshot',
       description:
-        'Return an accessibility-tree snapshot of the current page with element refs usable by browser_click/browser_type.',
+        'Return an accessibility-tree snapshot of the current page with element refs usable by browser_click/browser_type. Use this to actually read page content after browser_navigate; for extraction tasks prefer mode="full" and repeat after browser_scroll on long/lazy-loaded pages.',
       parameters: {
         type: 'object',
         properties: {
@@ -1134,7 +1184,7 @@ export const BROWSER_TOOL_DEFINITIONS: ToolDefinition[] = [
     function: {
       name: 'browser_pdf',
       description:
-        'Save the current page as PDF. Output path is constrained under /workspace/.browser-artifacts for safety.',
+        'Save the current page as PDF artifact. Output path is constrained under /workspace/.browser-artifacts for safety. Use for export/sharing only, not for text extraction or summarization.',
       parameters: {
         type: 'object',
         properties: {

package/container/src/hybridai-client.ts

@@ -1,4 +1,4 @@
-import type { ChatCompletionResponse, ChatMessage, ToolDefinition } from './types.js';
+import type { ChatCompletionResponse, ChatMessage, ToolCall, ToolDefinition } from './types.js';
 
 export class HybridAIRequestError extends Error {
   status: number;
@@ -12,18 +12,45 @@ export class HybridAIRequestError extends Error {
   }
 }
 
-export async function callHybridAI(
-  baseUrl: string,
-  apiKey: string,
+interface StreamToolCallDelta {
+  index?: number;
+  id?: string;
+  type?: 'function';
+  function?: {
+    name?: string;
+    arguments?: string;
+  };
+}
+
+interface StreamChoiceChunk {
+  delta?: {
+    role?: string;
+    content?: string | null;
+    tool_calls?: StreamToolCallDelta[];
+  };
+  message?: {
+    role?: string;
+    content?: string | null;
+    tool_calls?: ToolCall[];
+  };
+  finish_reason?: string | null;
+}
+
+interface StreamChunkPayload {
+  id?: string;
+  model?: string;
+  usage?: ChatCompletionResponse['usage'];
+  choices?: StreamChoiceChunk[];
+}
+
+function buildRequestBody(
   model: string,
   chatbotId: string,
   enableRag: boolean,
   messages: ChatMessage[],
   tools: ToolDefinition[],
-): Promise<ChatCompletionResponse> {
-  const url = `${baseUrl}/v1/chat/completions`;
-
-  const body: Record<string, unknown> = {
+): Record<string, unknown> {
+  return {
     model,
     chatbot_id: chatbotId,
     messages,
@@ -31,6 +58,65 @@ export async function callHybridAI(
     tool_choice: 'auto',
     enable_rag: enableRag,
   };
+}
+
+function parseStreamPayloadLine(rawLine: string): string | null {
+  const trimmed = rawLine.trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith(':')) return null;
+  if (trimmed.startsWith('event:')) return null;
+  if (trimmed.startsWith('id:')) return null;
+  if (trimmed.startsWith('data:')) {
+    return trimmed.slice(5).trim();
+  }
+  return trimmed;
+}
+
+function ensureToolCall(toolCalls: ToolCall[], index: number): ToolCall {
+  while (toolCalls.length <= index) {
+    toolCalls.push({
+      id: '',
+      type: 'function',
+      function: {
+        name: '',
+        arguments: '',
+      },
+    });
+  }
+  return toolCalls[index];
+}
+
+function mergeToolCallDelta(target: ToolCall, delta: StreamToolCallDelta): void {
+  if (typeof delta.id === 'string' && delta.id) {
+    target.id = target.id ? `${target.id}${delta.id}` : delta.id;
+  }
+  if (typeof delta.type === 'string') {
+    target.type = delta.type;
+  }
+  if (delta.function) {
+    if (typeof delta.function.name === 'string' && delta.function.name) {
+      target.function.name = target.function.name
+        ? `${target.function.name}${delta.function.name}`
+        : delta.function.name;
+    }
+    if (typeof delta.function.arguments === 'string' && delta.function.arguments) {
+      target.function.arguments += delta.function.arguments;
+    }
+  }
+}
+
+export async function callHybridAI(
+  baseUrl: string,
+  apiKey: string,
+  model: string,
+  chatbotId: string,
+  enableRag: boolean,
+  messages: ChatMessage[],
+  tools: ToolDefinition[],
+): Promise<ChatCompletionResponse> {
+  const url = `${baseUrl}/v1/chat/completions`;
+
+  const body = buildRequestBody(model, chatbotId, enableRag, messages, tools);
 
   const response = await fetch(url, {
     method: 'POST',
@@ -48,3 +134,179 @@ export async function callHybridAI(
 
   return (await response.json()) as ChatCompletionResponse;
 }
+
+export async function callHybridAIStream(
+  baseUrl: string,
+  apiKey: string,
+  model: string,
+  chatbotId: string,
+  enableRag: boolean,
+  messages: ChatMessage[],
+  tools: ToolDefinition[],
+  onTextDelta: (delta: string) => void,
+): Promise<ChatCompletionResponse> {
+  const url = `${baseUrl}/v1/chat/completions`;
+  const body = {
+    ...buildRequestBody(model, chatbotId, enableRag, messages, tools),
+    stream: true,
+  };
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'text/event-stream, application/x-ndjson, application/json',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new HybridAIRequestError(response.status, text);
+  }
+
+  const contentType = (response.headers.get('content-type') || '').toLowerCase();
+  if (
+    contentType.includes('application/json')
+    && !contentType.includes('ndjson')
+    && !contentType.includes('event-stream')
+  ) {
+    return (await response.json()) as ChatCompletionResponse;
+  }
+
+  if (!response.body) {
+    return (await response.json()) as ChatCompletionResponse;
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+
+  let buffer = '';
+  let streamId = '';
+  let streamModel = model;
+  let finishReason: string | null = null;
+  let usage: ChatCompletionResponse['usage'] | undefined;
+  let role: string = 'assistant';
+  let textContent = '';
+  const toolCalls: ToolCall[] = [];
+  let sawPayload = false;
+  let streamDone = false;
+
+  const consumePayload = (payloadText: string): void => {
+    if (!payloadText || payloadText === '[DONE]') {
+      if (payloadText === '[DONE]') streamDone = true;
+      return;
+    }
+
+    let payload: StreamChunkPayload;
+    try {
+      payload = JSON.parse(payloadText) as StreamChunkPayload;
+    } catch {
+      return;
+    }
+
+    sawPayload = true;
+    if (typeof payload.id === 'string' && payload.id) streamId = payload.id;
+    if (typeof payload.model === 'string' && payload.model) streamModel = payload.model;
+    if (payload.usage && typeof payload.usage === 'object') usage = payload.usage;
+
+    const choice = Array.isArray(payload.choices) ? payload.choices[0] : undefined;
+    if (!choice) return;
+
+    if (choice.message) {
+      const message = choice.message;
+      if (typeof message.role === 'string' && message.role) role = message.role;
+      if (typeof message.content === 'string') {
+        const nextContent = message.content;
+        const delta = nextContent.startsWith(textContent)
+          ? nextContent.slice(textContent.length)
+          : nextContent;
+        textContent = nextContent;
+        if (delta) onTextDelta(delta);
+      }
+      if (Array.isArray(message.tool_calls) && message.tool_calls.length > 0) {
+        toolCalls.length = 0;
+        for (const call of message.tool_calls) {
+          toolCalls.push({
+            id: call.id || '',
+            type: call.type || 'function',
+            function: {
+              name: call.function?.name || '',
+              arguments: call.function?.arguments || '',
+            },
+          });
+        }
+      }
+    }
+
+    if (choice.delta) {
+      const delta = choice.delta;
+      if (typeof delta.role === 'string' && delta.role) role = delta.role;
+      if (typeof delta.content === 'string' && delta.content) {
+        textContent += delta.content;
+        onTextDelta(delta.content);
+      }
+      if (Array.isArray(delta.tool_calls) && delta.tool_calls.length > 0) {
+        for (const callDelta of delta.tool_calls) {
+          const index = typeof callDelta.index === 'number' && callDelta.index >= 0 ? callDelta.index : 0;
+          const target = ensureToolCall(toolCalls, index);
+          mergeToolCallDelta(target, callDelta);
+        }
+      }
+    }
+
+    if (typeof choice.finish_reason === 'string' && choice.finish_reason) {
+      finishReason = choice.finish_reason;
+    }
+  };
+
+  try {
+    while (!streamDone) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+
+      for (const rawLine of lines) {
+        const payloadText = parseStreamPayloadLine(rawLine);
+        if (!payloadText) continue;
+        consumePayload(payloadText);
+        if (streamDone) break;
+      }
+    }
+
+    if (!streamDone && buffer.trim()) {
+      const payloadText = parseStreamPayloadLine(buffer);
+      if (payloadText) {
+        consumePayload(payloadText);
+      }
+    }
+  } finally {
+    reader.releaseLock();
+    decoder.decode();
+  }
+
+  if (!sawPayload) {
+    throw new Error('Streaming response ended without payload');
+  }
+
+  const finalFinishReason = finishReason || (toolCalls.length > 0 ? 'tool_calls' : 'stop');
+  return {
+    id: streamId || 'stream',
+    model: streamModel,
+    choices: [
+      {
+        message: {
+          role,
+          content: textContent || null,
+          ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+        },
+        finish_reason: finalFinishReason,
+      },
+    ],
+    ...(usage ? { usage } : {}),
+  };
+}