@steipete/summarize 0.8.2 → 0.10.0

package/dist/types/tty/progress/transcript.d.ts

@@ -1,10 +1,12 @@
 import type { LinkPreviewProgressEvent } from '@steipete/summarize-core/content';
 import type { OscProgressController } from '../osc-progress.js';
-export declare function createTranscriptProgressRenderer({ spinner, oscProgress, }: {
+import type { ThemeRenderer } from '../theme.js';
+export declare function createTranscriptProgressRenderer({ spinner, oscProgress, theme, }: {
     spinner: {
         setText: (text: string) => void;
     };
     oscProgress?: OscProgressController | null;
+    theme?: ThemeRenderer | null;
 }): {
     stop: () => void;
     onProgress: (event: LinkPreviewProgressEvent) => void;

package/dist/types/tty/spinner.d.ts

@@ -1,7 +1,9 @@
-export declare function startSpinner({ text, enabled, stream, }: {
+import { type Options as OraOptions } from 'ora';
+export declare function startSpinner({ text, enabled, stream, color, }: {
     text: string;
     enabled: boolean;
     stream: NodeJS.WritableStream;
+    color?: OraOptions['color'];
 }): {
     stop: () => void;
     clear: () => void;

package/dist/types/tty/theme.d.ts

@@ -0,0 +1,44 @@
+export declare const CLI_THEME_NAMES: readonly ["aurora", "ember", "moss", "mono"];
+export type CliThemeName = (typeof CLI_THEME_NAMES)[number];
+export type ThemeRole = 'heading' | 'accent' | 'accentStrong' | 'muted' | 'dim' | 'success' | 'warning' | 'error' | 'label' | 'value' | 'code';
+type ThemePalette = {
+    name: CliThemeName;
+    roles: Record<ThemeRole, string>;
+    spinner: 'cyan' | 'magenta' | 'yellow' | 'green' | 'gray' | 'blue';
+};
+export declare const DEFAULT_CLI_THEME: CliThemeName;
+export declare function listCliThemes(): CliThemeName[];
+export declare function isCliThemeName(value: string): value is CliThemeName;
+export declare function parseCliThemeName(raw: unknown, label: string): CliThemeName | null;
+export declare function resolveThemeNameFromSources({ cli, env, config, fallback, }: {
+    cli?: unknown;
+    env?: unknown;
+    config?: unknown;
+    fallback?: CliThemeName;
+}): CliThemeName;
+export declare function resolveTrueColor(env: Record<string, string | undefined>): boolean;
+type ThemeRendererOptions = {
+    themeName: CliThemeName;
+    enabled: boolean;
+    trueColor: boolean;
+};
+export type ThemeRenderer = {
+    name: CliThemeName;
+    enabled: boolean;
+    trueColor: boolean;
+    palette: ThemePalette;
+    heading: (text: string) => string;
+    accent: (text: string) => string;
+    accentStrong: (text: string) => string;
+    label: (text: string) => string;
+    value: (text: string) => string;
+    muted: (text: string) => string;
+    dim: (text: string) => string;
+    success: (text: string) => string;
+    warning: (text: string) => string;
+    error: (text: string) => string;
+    code: (text: string) => string;
+};
+export declare function createThemeRenderer({ themeName, enabled, trueColor, }: ThemeRendererOptions): ThemeRenderer;
+export declare function resolveThemePalette(themeName: CliThemeName): ThemePalette;
+export {};

package/dist/types/tty/website-progress.d.ts

@@ -1,11 +1,13 @@
 import type { LinkPreviewProgressEvent } from '@steipete/summarize-core/content';
 import type { OscProgressController } from './osc-progress.js';
-export declare function createWebsiteProgress({ enabled, spinner, oscProgress, }: {
+import type { ThemeRenderer } from './theme.js';
+export declare function createWebsiteProgress({ enabled, spinner, oscProgress, theme, }: {
     enabled: boolean;
     spinner: {
         setText: (text: string) => void;
     };
     oscProgress?: OscProgressController | null;
+    theme?: ThemeRenderer | null;
 }): {
     stop: () => void;
     onProgress: (event: LinkPreviewProgressEvent) => void;

package/dist/types/version.d.ts

@@ -1,4 +1,4 @@
-export declare const FALLBACK_VERSION = "0.8.2";
+export declare const FALLBACK_VERSION = "0.10.0";
 export declare function resolvePackageVersion(importMetaUrl?: string): string;
 export declare function resolveGitSha(importMetaUrl?: string): string | null;
 export declare function formatVersionLine(importMetaUrl?: string): string;

package/docs/README.md

@@ -4,17 +4,22 @@ summary: "Docs index for summarize behaviors and modes."
 
 # Docs
 
-- `docs/website.md` — normal websites (HTML extraction + Firecrawl fallback)
-- `docs/youtube.md` — YouTube transcript extraction (youtubei / captionTracks / Apify)
-- `docs/firecrawl.md` — Firecrawl mode + API key
-- `docs/llm.md` — LLM summarization + model config (Gateway/OpenAI)
+- `docs/chrome-extension.md` — Chrome side panel extension + daemon setup/troubleshooting
+- `docs/cache.md` — cache design + config (SQLite)
 - `docs/cli.md` — CLI models (Claude/Codex/Gemini)
-- `docs/model-auto.md` — automatic model selection (`--model auto`)
+- `docs/config.md` — config file location, precedence, and schema
+- `docs/extract-only.md` — extract mode (no summary LLM call)
+- `docs/firecrawl.md` — Firecrawl mode + API key
 - `docs/language.md` — output language (`--language` / config `language`)
-- `docs/cache.md` — cache design + config (SQLite)
+- `docs/llm.md` — LLM summarization + model config (Gateway/OpenAI)
 - `docs/manual-tests.md` — manual end-to-end test checklist
-- `docs/extract-only.md` — extract mode (no summary LLM call)
+- `docs/model-auto.md` — automatic model selection (`--model auto`)
+- `docs/openai.md` — OpenAI model usage + flags
+- `docs/releasing.md` — release checklist + Homebrew tap update
+- `docs/smoketest.md` — 20-case smoke test plan
+- `docs/website.md` — normal websites (HTML extraction + Firecrawl fallback)
+- `docs/youtube.md` — YouTube transcript extraction (youtubei / captionTracks / Apify)
 
 ## Website
 
-- Static site source: `docs/site/` (GitHub Pages via Actions)
+- Jekyll site source: `docs/` (Markdown → HTML via GitHub Pages Actions)

package/docs/_config.yml

@@ -0,0 +1,26 @@
+title: "summarize"
+description: "Summarize docs"
+markdown: kramdown
+highlighter: rouge
+
+plugins:
+  - jekyll-relative-links
+
+relative_links:
+  enabled: true
+  collections: true
+
+exclude:
+  - site
+
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default
+      permalink: /docs/:basename:output_ext
+
+kramdown:
+  input: GFM
+  hard_wrap: false
+  syntax_highlighter: rouge

package/docs/_layouts/default.html

@@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <meta name="color-scheme" content="dark light" />
+    {% assign page_title = page.title | default: page.name | default: "Docs" | replace: ".md", "" | replace: "-", " " %}
+    <title>{{ page_title }} — summarize</title>
+    <meta name="description" content="{{ page.summary | default: site.description | escape }}" />
+    <link rel="canonical" href="https://summarize.sh{{ page.url | replace: 'index.html', '' }}" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap"
+      rel="stylesheet"
+    />
+    <link rel="stylesheet" href="/assets/site.css" />
+  </head>
+  <body>
+    <main class="shell">
+      <header class="top">
+        <a class="brand" href="/" aria-label="summarize home">
+          <span class="brand__mark" aria-hidden="true">s</span>
+          <span class="brand__word">summarize</span>
+        </a>
+        <nav class="nav" aria-label="Primary">
+          <a data-nav="home" href="/">Home</a>
+          <a data-nav="docs" href="/docs/index.html">Docs</a>
+          <a href="https://github.com/steipete/summarize">GitHub</a>
+        </nav>
+      </header>
+
+      <section class="docShell">
+        <aside class="side" aria-label="Docs navigation">
+          <h2>Docs</h2>
+          <a href="/docs/index.html">Overview</a>
+          <a href="/docs/chrome-extension.html">Chrome extension</a>
+          <a href="/docs/website.html">Website mode</a>
+          <a href="/docs/youtube.html">YouTube mode</a>
+          <a href="/docs/extract-only.html">Extract</a>
+          <a href="/docs/llm.html">LLM</a>
+          <a href="/docs/openai.html">OpenAI</a>
+          <a href="/docs/firecrawl.html">Firecrawl</a>
+          <a href="/docs/config.html">Config</a>
+        </aside>
+
+        <article class="doc reveal">
+          {{ content }}
+        </article>
+      </section>
+
+      <footer class="footer">
+        <span>summarize — Link → clean text → summary.</span>
+        <span><a href="/docs/index.html">Docs</a> · <a href="https://github.com/steipete/summarize">Repo</a></span>
+      </footer>
+    </main>
+
+    <script type="module" src="/assets/site.js"></script>
+  </body>
+</html>

package/docs/agent.md

@@ -0,0 +1,333 @@
+---
+summary: "Automation agent for the Chrome side panel (daemon-backed)."
+read_when:
+  - "When working on automation tools, /v1/agent, or the side panel agent loop."
+---
+
+# Automation Agent (Side Panel + Daemon)
+
+Summarize can run as a **website automation agent** inside the Chrome side panel. This is **optional** and **gated by a checkbox** in Options.
+
+Scope:
+- **Off (default):** chat is Q&A only (no tools).
+- **On:** chat runs a tool-capable agent for web automation.
+
+Explicit exclusions (per product direction): **no update checker**, **no tutorial/welcome flow**, **no proxy config**, **no API key dialog**. All model calls go through the **local daemon**.
+
+## Architecture (High Level)
+
+1) **Side panel** maintains the agent loop + chat UI.
+2) **Background** handles tab data, extraction, and tool execution.
+3) **Content scripts** handle element picking and native-input bridge.
+4) **Daemon** provides `/v1/agent` (SSE stream of chunks + final assistant message).
+
+### Data Flow (Agent Loop)
+
+- User sends a message in the side panel.
+- Panel compacts history and sends `panel:agent` to background with:
+  - `messages` (pi-ai Message[])
+  - `tools` (names)
+  - `summary` (optional current summary markdown)
+- Background builds `pageContent` using the latest extract (summary + transcript/text + metadata).
+- Background calls daemon `POST /v1/agent` (SSE).
+- Daemon streams `chunk` events, then an `assistant` event (may include tool calls).
+- Panel executes tool calls locally, appends `toolResult` messages, and repeats `/v1/agent` until no tool calls remain.
+
+The daemon **never** executes tools. It only returns the next assistant message.
+
+## Settings + Permissions
+
+### Settings
+
+`automationEnabled` (boolean) lives in `apps/chrome-extension/src/lib/settings.ts`.
+
+- Options UI provides the toggle.
+- When disabled, the tool list is empty and the daemon uses the **chat-only** prompt.
+
+### Optional Permissions
+
+Defined in `apps/chrome-extension/wxt.config.ts` and requested via Options:
+
+- `debugger` – required for **native input** and the **debugger** tool.
+- `userScripts` – reserved for main-world script execution (not required for current REPL path).
+
+#### Chrome: enable User Scripts (if needed)
+
+1. `chrome://extensions`
+2. Open extension details
+3. Enable **Allow User Scripts**
+4. Reload the tab
+
+## Daemon Endpoint
+
+### `POST /v1/agent` (SSE)
+
+**Headers**
+- `Authorization: Bearer <token>`
+- `Content-Type: application/json`
+
+**Body**
+```
+{
+  "url": "https://...",
+  "title": "Page title",
+  "pageContent": "<summary + transcript + metadata>",
+  "cacheContent": "<transcript/text used for cache key>",
+  "messages": [/* pi-ai Message[] */],
+  "model": "auto" | "openai/..." | "anthropic/..." | ...,
+  "length": "short" | "xl" | "20k" | ...,
+  "language": "auto" | "en" | "de" | ...,
+  "tools": ["navigate", "repl", "ask_user_which_element", "skill", "debugger"],
+  "automationEnabled": true
+}
+```
+
+**Response (SSE, default)**
+```
+event: chunk
+data: { "text": "..." }
+
+event: assistant
+data: { /* AssistantMessage */ }
+
+event: done
+data: {}
+
+event: error
+data: { "message": "..." }
+```
+
+**Response (JSON)**
+Use `Accept: application/json` or `?format=json`.
+```
+{ "ok": true, "assistant": { /* AssistantMessage */ } }
+```
+
+### `POST /v1/agent/history`
+
+Returns cached chat history for the same cache key as `/v1/agent`.
+
+**Body**
+```
+{
+  "url": "https://...",
+  "pageContent": "<summary + transcript + metadata>",
+  "cacheContent": "<transcript/text used for cache key>",
+  "model": "auto" | "openai/..." | "anthropic/..." | ...,
+  "length": "short" | "xl" | "20k" | ...,
+  "language": "auto" | "en" | "de" | ...,
+  "automationEnabled": true
+}
+```
+
+**Response**
+```
+{ "ok": true, "messages": [/* Message[] */] }
+```
+
+### Model Resolution (Daemon)
+
+- **Fixed model** (explicit `model`): parsed as `<provider>/<model>`. Provider base URL overrides come from config/env (OpenAI, Anthropic, Google, xAI, ZAI). OpenRouter uses OpenAI-compatible completions.
+- **Auto model**: uses existing auto-selection logic (`buildAutoModelAttempts`), skipping CLI transports.
+- **Synthetic models**: created for OpenAI-compatible base URLs (local/openrouter).
+- `maxOutputTokens` defaults to 2048 or `maxOutputTokens` override.
+- CLI models are **not** supported in the daemon.
+
+## Page Content Payload
+
+`pageContent` is built from the latest extract and includes:
+
+- **Summary** (optional): current summary markdown (truncated to settings cap).
+- **Transcript/text**: timed transcript when available, otherwise extracted text.
+- **Metadata**: URL/title, source (`page` vs `url`), extraction strategy, markdown provider, Firecrawl usage, transcript provider + cache status, media duration, word counts, truncation flags.
+
+See `buildChatPageContent()` usage in `apps/chrome-extension/src/entrypoints/background.ts`.
+
+## Tools
+
+### 1) `navigate`
+Navigate the active tab.
+
+Params:
+```
+{ "url": "https://...", "newTab": false }
+```
+
+Result:
+```
+{ "finalUrl": "https://...", "title": "...", "tabId": 123 }
+```
+
+Notes:
+- Uses `chrome.tabs.update` or `chrome.tabs.create`.
+- Waits for tab status `complete` (15s timeout).
+
+### 2) `repl`
+Execute JavaScript in a sandbox, with `browserjs()` to run in the page context.
+
+Params:
+```
+{ "title": "...", "code": "..." }
+```
+
+Result:
+```
+{ "output": "console/return output", "files": [{ "fileName": "...", "mimeType": "...", "contentBase64": "..." }] }
+```
+
+REPL environment:
+- Runs in a **sandboxed iframe** (no DOM access to the panel).
+- `browserjs(fn, ...args)` runs the function **in the page context**.
+  - Uses `chrome.userScripts.execute` (main world) when available.
+  - Falls back to `chrome.scripting.executeScript` (isolated world).
+- `navigate({ url })` available inside the REPL (always use for navigation).
+- `sleep(ms)` helper.
+- Console output is captured and returned; return values are appended as `=> value`.
+- `returnFile(name, content, mimeType)` or `returnFile({ fileName, content, mimeType })` attaches files to the tool result.
+
+Safety:
+- Navigation inside REPL code (`window.location`, `history`, etc.) is rejected. Use `navigate()` instead.
+
+Page-context helpers (via `browserjs()`):
+- Skills libraries are auto-injected when domain patterns match the active URL.
+- If `debugger` permission is granted, native helpers are exposed:
+  - `nativeClick(selector)`
+  - `nativeType(selector, text)`
+  - `nativePress(key)`
+  - `nativeKeyDown(key)` / `nativeKeyUp(key)`
+
+### 3) `ask_user_which_element`
+Shows a click-to-select overlay and returns element metadata.
+
+Params:
+```
+{ "message": "Optional guidance" }
+```
+
+Result (example):
+```
+{
+  "selector": "#submit",
+  "xpath": "//button[1]",
+  "text": "Send",
+  "tagName": "button",
+  "attributes": { "type": "submit" },
+  "html": "<button ...>",
+  "boundingBox": { "x": 20, "y": 120, "width": 180, "height": 40 }
+}
+```
+
+Overlay UX:
+- Hover highlights element under cursor.
+- Click selects.
+- ↑ / ↓ moves up or down the DOM tree.
+- Esc cancels.
+
+### 4) `skill`
+CRUD for domain-specific libraries (stored in `chrome.storage.local`).
+
+Storage keys:
+- `automation.skills` (map of name → skill)
+- `automation.skillsSeeded` (one-time default seed)
+
+Actions:
+- `list` (optionally filtered by URL)
+- `get` (optionally includes library code)
+- `create` / `rewrite`
+- `update` (string replacement)
+- `delete`
+
+Default skills seed from `apps/chrome-extension/src/automation/default-skills.json`.
+
+Matching:
+- Glob-like domain patterns (supports `*` and `**`).
+- Match is done against hostname + path (e.g. `github.com/*/issues`).
+
+Notes:
+- `update` is intended for in-place string replacements; use `rewrite` to rename.
+- Skills libraries run inside `browserjs()` and must avoid navigation.
+
+### 5) `debugger` (optional)
+Runs JavaScript in the **main world** via the Chrome debugger. **Last resort** (shows Chrome debug banner).
+
+Params:
+```
+{ "action": "eval", "code": "..." }
+```
+
+Result:
+```
+{ "text": "...", "details": { ... } }
+```
+
+### 6) `summarize`
+Run the Summarize pipeline against a URL (summary or extract-only).
+
+Params:
+```
+{
+  "url": "https://...",
+  "extractOnly": false,
+  "format": "text",
+  "markdownMode": "readability",
+  "model": "openai/gpt-5-mini",
+  "length": "short",
+  "language": "auto",
+  "prompt": "Optional override",
+  "timeout": "2m",
+  "maxOutputTokens": "2k",
+  "noCache": false,
+  "firecrawl": "auto",
+  "preprocess": "auto",
+  "youtube": "auto",
+  "videoMode": "auto",
+  "timestamps": false,
+  "maxCharacters": 120000
+}
+```
+
+Result (summary):
+```
+{ "output": "..." }
+```
+
+Result (extract-only):
+```
+{ "output": "...", "details": { "content": "...", "title": "...", "wordCount": 123, ... } }
+```
+
+Notes:
+- URL-only (uses daemon URL pipeline).
+- Use `extractOnly: true` + `format: "markdown"` to return extracted Markdown.
+- When `format: "markdown"`, `markdownMode` defaults to `readability`.
+
+## Native Input Bridge (Debugger Permission)
+
+Native input events use the Chrome debugger protocol:
+
+- `browserjs()` posts a message to the content script.
+- Content script forwards to background (`automation:native-input`).
+- Background attaches debugger and dispatches:
+  - `Input.dispatchMouseEvent` (click)
+  - `Input.insertText` (type)
+  - `Input.dispatchKeyEvent` (press/keydown/keyup)
+
+If permission is missing, the call fails and the tool reports the error.
+
+## UX Notes
+
+- Automation is opt-in via Options checkbox.
+- Regular summarize flows remain unchanged.
+- Tool results are treated as **data**, not instructions. The system prompt still asks the assistant to repeat important tool-derived info in plain text.
+- Tool results are currently rendered in the chat UI for debugging; they may be hidden in the future.
+- When the active tab URL changes during a conversation, the panel appends a **navigation tool result** with the new URL, title, and matching skills. This keeps the agent aware of user-driven navigation.
+- REPL executions that call `browserjs()` show a small overlay with an **Abort** action; aborting stops the current agent loop (best-effort).
+
+## Where Things Live
+
+- **Daemon**: `src/daemon/server.ts`, `src/daemon/agent.ts`
+- **Automation tools**: `apps/chrome-extension/src/automation/`
+- **Element picker + native input bridge**: `apps/chrome-extension/src/entrypoints/automation.content.ts`
+- **Background agent proxy**: `apps/chrome-extension/src/entrypoints/background.ts`
+- **Side panel agent loop**: `apps/chrome-extension/src/entrypoints/sidepanel/`
+- **Options toggle**: `apps/chrome-extension/src/entrypoints/options/`