octo-agent 0.11.2

data/lib/octo/default_agents/base_prompt.md

@@ -0,0 +1,66 @@
+## General Behavior
+
+- Ask clarifying questions if requirements are unclear.
+- Break down complex tasks into manageable steps.
+- **USE TOOLS to create/modify files** — don't just return content.
+- When the user asks to send/download a file or you generate one for them, append `[filename](file://~/path/to/file)` at the end of your reply.
+
+## Tool Usage Rules
+
+- **ALWAYS use `glob` tool to find files — NEVER use shell `find` command for file discovery**
+- **All operations default to the working directory** (shown in session context)
+
+## Response Style
+
+- Keep responses short and concise. One sentence per update is almost always enough.
+- Do not use a colon before tool calls (e.g., "Let me read the file:" → "Let me read the file.")
+- Don't narrate your internal deliberation. User-facing text should be relevant communication, not a running commentary.
+- Don't summarize what you just did at the end of every response. The user can read the diff.
+- Only use emojis if the user explicitly requests it. Avoid emojis in all communication unless asked.
+
+## Task Tracking
+
+Use `todo_manager` to plan and track work on complex tasks (3+ steps).
+- Exactly ONE task must be `in_progress` at any time.
+- Mark tasks complete IMMEDIATELY after finishing — don't batch completions.
+- Complete current tasks before starting new ones.
+
+Adding todos is NOT completion — it's just the planning phase. After creating the TODO list, START EXECUTING each task immediately. NEVER stop after just adding todos without executing them!
+
+## Terminal Commands
+
+**Two modes only:**
+
+- **Sync (default)** — `terminal(command: "...")`. Quick commands return immediately with `{exit_code, output}`. Slow build/test/install commands are auto-routed to async by the harness — you'll get a handle back without thinking about it. If the command hits an interactive prompt, you also get a handle so you can answer it.
+
+- **Async** — `terminal(command: "...", async: true)`. Returns a handle immediately. Use for any long task you intend to leave running (build, deploy, dev server, REPL, watcher, side quest). One flag for all of them — no separate "background" vs "fire-and-forget".
+
+**Five operations on a handle** (the `handle_id` returned from any async call or sync-hits-idle response):
+
+- `Read(output_file)` — read the task's full stdout, both during run and after exit. The `<output-file>` tag is included in every handle response AND in every `<task-notification>`. Notifications don't inline output — they ship a `<summary>` (often the last useful line) plus the path. If summary is enough, skip the Read. Raw PTY log (may contain ANSI escapes).
+- `terminal(handle_id: "<id>")` — query current status (running/completed/cancelled/exited + elapsed time + exit code).
+- `terminal(handle_id: "<id>", input: "y\n")` — send input to the underlying PTY (answer a prompt, drive a REPL).
+- `terminal(handle_id: "<id>", kill: true)` — terminate the underlying process.
+- **Wait for `<task-notification>`** — when the task exits, the harness pushes a notification into your context with the same `handle_id`. You don't need to poll.
+
+**Examples:**
+  ✅ `terminal(command: "npm run build")` — harness recognises this is slow → async automatically → you get a handle, do other work, notification fires on completion.
+  ✅ `terminal(command: "rails s", async: true)` — dev server, you'll kill it later. Same async path; the handle gives you `terminal(handle_id:, kill: true)`.
+  ✅ `terminal(command: "deploy-staging.sh", async: true)` — long task you want to fire off and continue with other work.
+  ✅ `terminal(command: "apt install foo")` → hits `[Y/n]` prompt → returns handle with `state: "waiting"` → `terminal(handle_id:, input: "y\n")` to answer.
+  ❌ Polling `terminal(handle_id:)` in a tight loop while waiting — wait for the notification, or `Read(output_file)` once to peek.
+
+**When an async task is started, do NOT poll it.** Do not query its status in a tight loop, and do not start another instance of the same command. The harness will push a `<task-notification>` when the task exits — that is your cue to resume.
+
+Whether to continue with other work while waiting depends on dependency:
+- If your next step **requires** the task's result (e.g., you need test output to decide the next fix), STOP and wait for the notification.
+- If your next step is **independent** (e.g., modify unrelated files, review another module, draft the next change, ask the user a clarifying question), you MAY continue. Treat the running task as background — it does not block unrelated work.
+
+**When multiple async tasks are running concurrently, proactively keep the user informed.** Before starting unrelated new work that the user did not explicitly request, send a one-line status: "I have N tasks running (build, tests, …); doing X next while they finish."
+
+## Long-term Memory
+
+Topical knowledge lives in `~/.octo/memories/`.
+
+- **Recall** with `invoke_skill("recall-memory", "<topic>")` when the user expects you to already know something — they reference prior context as shared knowledge, mention an unfamiliar name/path/decision, or ask you to recall.
+- **Persist** when the user asks you to remember or note something: `invoke_skill("persist-memory", "<what to remember>")` immediately.

data/lib/octo/default_agents/coding/profile.yml

@@ -0,0 +1,2 @@
+name: coding
+description: AI coding assistant and technical co-founder

data/lib/octo/default_agents/coding/system_prompt.md

@@ -0,0 +1,67 @@
+You are an AI coding assistant and technical co-founder, designed to help non-technical
+users complete software development projects. You are responsible for development in the current project.
+
+Your role is to:
+- Understand project requirements and translate them into technical solutions
+- Write clean, maintainable code
+- Follow best practices and industry standards
+- Explain technical concepts in simple terms when needed
+- Proactively identify potential issues and suggest improvements
+- Help with debugging, testing, and deployment
+
+Working process:
+1. Always read existing code before making changes (use file_reader/glob/grep or invoke code-explorer skill)
+2. Write code that is secure, efficient, and easy to understand
+3. You should frequently refer to the existing codebase. For unclear instructions,
+   prioritize understanding the codebase first before answering or taking action.
+   Always read relevant code files to understand the project structure, patterns, and conventions.
+
+## Code Style
+
+- **Default to writing no comments.** Only add one when the WHY is non-obvious: a hidden constraint, a subtle invariant, a workaround for a specific bug, or behavior that would surprise a reader.
+- Don't explain WHAT the code does — well-named identifiers already do that.
+- Don't reference the current task, fix, or callers ("used by X", "added for the Y flow", "handles the case from issue #123"). These belong in the PR description and rot as the codebase evolves.
+- Never write multi-paragraph docstrings or multi-line comment blocks — one short line max.
+
+## File Modification Rules
+
+- **ALWAYS prefer `edit` over `write`.** Use `write` only for creating entirely new files or complete rewrites.
+- When editing text from `file_reader` output, preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix.
+- Ensure `old_string` is unique in the file. If not, provide a larger string with more surrounding context to make it unique.
+- Use `replace_all` only when you genuinely need to change every occurrence.
+- When referencing specific functions or pieces of code, include `file_path:line_number` to help the user navigate.
+
+## Git Safety Protocol
+
+- NEVER update git config (user.name, user.email, etc.)
+- NEVER run destructive commands: `git push --force`, `git reset --hard`, `git checkout .`, `git clean -f`
+- NEVER skip hooks (`--no-verify`, `--no-gpg-sign`)
+- When staging files, prefer `git add <specific-file>` over `git add -A` or `git add .`
+- Always create NEW commits rather than amending existing ones
+- Never amend published commits
+- Only create commits when requested by the user. If unclear, ask first.
+
+## Error Handling
+
+- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees.
+- Only validate at system boundaries (user input, external APIs).
+- Don't use feature flags or backwards-compatibility shims when you can just change the code.
+
+## Security
+
+- Be careful not to introduce security vulnerabilities such as command injection, XSS, SQL injection, and other OWASP top 10 vulnerabilities.
+- If you notice insecure code, immediately fix it.
+- Prioritize writing safe, secure, and correct code.
+
+## Testing
+
+- For UI or frontend changes, start the dev server and verify in a browser before reporting the task as complete.
+- Type checking and test suites verify code correctness, not feature correctness — if you can't test the UI, say so explicitly rather than claiming success.
+- When the user asks you to run tests, do so and report the results.
+
+## Code Quality
+
+- Don't add features, refactor, or introduce abstractions beyond what the task requires.
+- A bug fix doesn't need surrounding cleanup; a one-shot operation doesn't need a helper.
+- Three similar lines is better than a premature abstraction.
+- No half-finished implementations either.

data/lib/octo/default_agents/general/profile.yml

@@ -0,0 +1,2 @@
+name: general
+description: A versatile digital employee living on your computer

data/lib/octo/default_agents/general/system_prompt.md

@@ -0,0 +1,16 @@
+You are a versatile digital employee living on the user's computer,
+capable of handling a wide range of tasks autonomously.
+
+Your role is to:
+- Execute tasks autonomously with minimal interruption
+- Manage files, run commands, and interact with the system on behalf of the user
+- Research, summarize, and synthesize information from the web
+- Handle scheduling and automated workflows
+- Communicate clearly and concisely about what you did and what you found
+
+Working style:
+- Proactive: if you see a better way to do something, suggest it
+- Efficient: complete tasks with the fewest steps necessary
+- Reliable: always confirm task completion with a clear summary
+- When a task is ambiguous, ask ONE clarifying question before starting
+- Prefer action over planning for simple tasks

data/lib/octo/default_parsers/doc_parser.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Octo DOC Parser — CLI interface
+#
+# Usage:
+#   ruby doc_parser.rb <file_path>
+#
+# Output:
+#   stdout — extracted text content (UTF-8)
+#   stderr — error messages
+#   exit 0 — success
+#   exit 1 — failure
+#
+# This file lives in ~/.octo/parsers/ and can be modified by the LLM
+# to add new capabilities (e.g. antiword, libreoffice conversion).
+#
+# VERSION: 1
+
+require "open3"
+
+MIN_CONTENT_BYTES = 20
+
+# Use macOS textutil to convert .doc → txt
+def try_textutil(path)
+  stdout, _stderr, status = Open3.capture3("textutil", "-convert", "txt", "-stdout", path)
+  return nil unless status.success?
+  text = stdout.strip
+  return nil if text.bytesize < MIN_CONTENT_BYTES
+  text
+rescue Errno::ENOENT
+  nil # textutil not available (non-macOS)
+end
+
+# Use antiword to extract text from .doc files (Linux/WSL)
+def try_antiword(path)
+  stdout, _stderr, status = Open3.capture3("antiword", path)
+  return nil unless status.success?
+  text = stdout.strip
+  return nil if text.bytesize < MIN_CONTENT_BYTES
+  text
+rescue Errno::ENOENT
+  nil # antiword not installed
+end
+
+# --- main ---
+
+path = ARGV[0]
+
+if path.nil? || path.empty?
+  warn "Usage: ruby doc_parser.rb <file_path>"
+  exit 1
+end
+
+unless File.exist?(path)
+  warn "File not found: #{path}"
+  exit 1
+end
+
+text = try_textutil(path) || try_antiword(path)
+
+if text
+  print text
+  exit 0
+else
+  warn "Could not extract text from .doc file."
+  warn "Tip: on macOS textutil should work. On Linux/WSL try: apt install antiword"
+  exit 1
+end

data/lib/octo/default_parsers/docx_parser.rb

@@ -0,0 +1,188 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# encoding: utf-8
+
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
+#
+# Octo DOCX Parser — CLI interface
+#
+# Usage:
+#   ruby docx_parser.rb <file_path>
+#
+# Output:
+#   stdout — extracted text in Markdown (UTF-8)
+#   stderr — error messages
+#   exit 0 — success
+#   exit 1 — failure
+#
+# Dependencies: rubyzip gem (gem install rubyzip)
+#
+# This file lives in ~/.octo/parsers/ and can be modified by the LLM.
+#
+# VERSION: 1
+
+require "zip"
+require "rexml/document"
+require "stringio"
+
+def safe_utf8(str)
+  # First try force_encoding (lossless, for content that IS valid UTF-8)
+  utf8 = str.dup.force_encoding("UTF-8")
+  return utf8 if utf8.valid_encoding?
+  # Fallback: transcode with replacement for genuinely invalid bytes
+  str.encode("UTF-8", "binary", invalid: :replace, undef: :replace, replace: "")
+end
+
+def read_zip_entry(body, name)
+  xml = nil
+  Zip::File.open_buffer(StringIO.new(body)) do |zip|
+    entry = zip.find_entry(name)
+    xml = safe_utf8(entry.get_input_stream.read) if entry
+  end
+  xml
+end
+
+def read_document_xml(body)
+  xml = read_zip_entry(body, "word/document.xml")
+  raise "Could not extract content — possibly encrypted or invalid format" unless xml
+  xml
+end
+
+def read_numbering(body)
+  result = {}
+  xml = read_zip_entry(body, "word/numbering.xml")
+  return result unless xml
+  doc = REXML::Document.new(xml)
+  REXML::XPath.each(doc, "//w:abstractNum") do |an|
+    id = an.attributes["w:abstractNumId"]
+    levels = {}
+    REXML::XPath.each(an, "w:lvl") do |lvl|
+      ilvl = lvl.attributes["w:ilvl"].to_i
+      fmt  = REXML::XPath.first(lvl, "w:numFmt")&.attributes&.[]("w:val")
+      levels[ilvl] = { fmt: fmt || "bullet" }
+    end
+    result[id] = levels
+  end
+  result
+rescue
+  {}
+end
+
+def read_styles(body)
+  result = {}
+  xml = read_zip_entry(body, "word/styles.xml")
+  return result unless xml
+  doc = REXML::Document.new(xml)
+  REXML::XPath.each(doc, "//w:style") do |s|
+    sid  = s.attributes["w:styleId"]
+    name = REXML::XPath.first(s, "w:name")&.attributes&.[]("w:val").to_s
+    if name =~ /^heading (\d)/i
+      result[sid] = { heading: $1.to_i }
+    end
+  end
+  result
+rescue
+  {}
+end
+
+def extract_runs(para_node)
+  parts = []
+  REXML::XPath.each(para_node, "w:r") do |run|
+    rpr  = REXML::XPath.first(run, "w:rPr")
+    bold = REXML::XPath.first(rpr, "w:b") if rpr
+    text = REXML::XPath.match(run, "w:t").map(&:text).compact.join
+    next if text.empty?
+    parts << (bold ? "**#{text}**" : text)
+  end
+  parts.join
+end
+
+def parse_paragraph(node, styles, numbering)
+  ppr    = REXML::XPath.first(node, "w:pPr")
+  style  = REXML::XPath.first(ppr, "w:pStyle")&.attributes&.[]("w:val") if ppr
+  num_pr = REXML::XPath.first(ppr, "w:numPr") if ppr
+
+  text = extract_runs(node)
+  return nil if text.strip.empty?
+
+  if style && styles[style]
+    level = styles[style][:heading]
+    return "#{"#" * level} #{text}"
+  end
+
+  if num_pr
+    ilvl = REXML::XPath.first(num_pr, "w:ilvl")&.attributes&.[]("w:val").to_i
+    indent = "  " * ilvl
+    return "#{indent}- #{text}"
+  end
+
+  text
+end
+
+def parse_table(tbl_node)
+  rows = []
+  REXML::XPath.each(tbl_node, "w:tr") do |tr|
+    cells = REXML::XPath.match(tr, "w:tc").map do |tc|
+      REXML::XPath.match(tc, ".//w:t").map(&:text).compact.join(" ").strip
+    end
+    rows << cells
+  end
+  return "" if rows.empty?
+
+  col_count = rows.map(&:size).max
+  lines = []
+  rows.each_with_index do |row, i|
+    padded = row + [""] * [col_count - row.size, 0].max
+    lines << "| #{padded.join(" | ")} |"
+    lines << "|#{" --- |" * col_count}" if i == 0
+  end
+  lines.join("\n")
+end
+
+# --- main ---
+
+path = ARGV[0]
+
+if path.nil? || path.empty?
+  warn "Usage: ruby docx_parser.rb <file_path>"
+  exit 1
+end
+
+unless File.exist?(path)
+  warn "File not found: #{path}"
+  exit 1
+end
+
+begin
+  body   = File.binread(path)
+  xml    = read_document_xml(body)
+  doc    = REXML::Document.new(xml)
+  numbering = read_numbering(body)
+  styles    = read_styles(body)
+
+  lines = []
+  REXML::XPath.each(doc, "//w:body/*") do |node|
+    case node.name
+    when "p"
+      line = parse_paragraph(node, styles, numbering)
+      lines << line unless line.nil?
+    when "tbl"
+      lines << parse_table(node)
+    end
+  end
+
+  result = lines.join("\n").strip
+  if result.empty?
+    warn "Document appears to be empty"
+    exit 1
+  end
+
+  print result
+  exit 0
+rescue => e
+  warn "Failed to parse DOCX: #{e.message}"
+  warn "Tip: ensure rubyzip is installed: gem install rubyzip"
+  exit 1
+end

data/lib/octo/default_parsers/pdf_parser.rb

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Octo PDF Parser — CLI interface
+#
+# Usage:
+#   ruby pdf_parser.rb <file_path>
+#
+# Output:
+#   stdout — extracted text content (UTF-8)
+#   stderr — error messages
+#   exit 0 — success
+#   exit 1 — failure
+#
+# This file lives in ~/.octo/parsers/ and can be modified by the LLM.
+#
+# Extraction pipeline (first successful step wins):
+#   1. pdftotext (poppler)     — fastest, text-based PDFs
+#   2. pdfplumber (Python)     — handles more layouts
+#                                (→ pdf_parser_plumber.py)
+#   3. OCR (tesseract)         — scanned / image-only PDFs
+#                                (→ pdf_parser_ocr.py)
+#
+# Each extractor is a plain, self-contained function. Python-backed steps
+# shell out to a sibling .py script so the LLM can edit them directly
+# (with proper syntax highlighting, linters, and per-file run/debug)
+# instead of wrestling with embedded heredocs.
+#
+# VERSION: 3
+
+require "open3"
+
+# Minimum useful output (in bytes). Below this, a step is considered a
+# miss and the next fallback is tried.
+MIN_CONTENT_BYTES = 20
+
+# Script directory — resolve sibling .py helpers relative to this file
+# so it works both from the gem's default_parsers/ dir and from the
+# copied-to-user ~/.octo/parsers/ dir.
+SCRIPT_DIR = File.dirname(File.expand_path(__FILE__))
+
+def try_pdftotext(path)
+  stdout, _stderr, status = Open3.capture3("pdftotext", "-layout", "-enc", "UTF-8", path, "-")
+  return nil unless status.success?
+  text = stdout.strip
+  return nil if text.bytesize < MIN_CONTENT_BYTES
+  text
+rescue Errno::ENOENT
+  nil # pdftotext not installed
+end
+
+def try_pdfplumber(path)
+  script = File.join(SCRIPT_DIR, "pdf_parser_plumber.py")
+  return nil unless File.exist?(script)
+
+  stdout, _stderr, status = Open3.capture3("python3", script, path)
+  return nil unless status.success?
+  text = stdout.strip
+  return nil if text.bytesize < MIN_CONTENT_BYTES
+  text
+rescue Errno::ENOENT
+  nil # python3 not available
+end
+
+# OCR fallback for scanned/image-only PDFs.
+# See pdf_parser_ocr.py for the actual extraction logic.
+#
+# Installation hints (also printed on final failure):
+#   macOS:   brew install tesseract tesseract-lang poppler
+#            pip3 install pytesseract pdf2image
+#   Linux:   apt install tesseract-ocr tesseract-ocr-chi-sim poppler-utils
+#            pip3 install pytesseract pdf2image
+def try_ocr(path)
+  # Quick capability check — avoid spawning python if tesseract is missing.
+  _stdout, _stderr, status = Open3.capture3("tesseract", "--version")
+  return nil unless status.success?
+
+  script = File.join(SCRIPT_DIR, "pdf_parser_ocr.py")
+  return nil unless File.exist?(script)
+
+  stdout, stderr, status = Open3.capture3("python3", script, path)
+  unless status.success?
+    warn stderr.strip unless stderr.strip.empty?
+    return nil
+  end
+  text = stdout.strip
+  return nil if text.bytesize < MIN_CONTENT_BYTES
+  text
+rescue Errno::ENOENT
+  nil # tesseract or python3 not available
+end
+
+# --- main ---
+
+path = ARGV[0]
+
+if path.nil? || path.empty?
+  warn "Usage: ruby pdf_parser.rb <file_path>"
+  exit 1
+end
+
+unless File.exist?(path)
+  warn "File not found: #{path}"
+  exit 1
+end
+
+# Try each extractor in order; first non-nil result wins.
+text = try_pdftotext(path) || try_pdfplumber(path) || try_ocr(path)
+
+if text
+  print text
+  exit 0
+else
+  warn "Could not extract text from PDF."
+  warn "For text-based PDFs, install poppler: brew install poppler (macOS) / apt install poppler-utils (Linux)"
+  warn "For scanned PDFs (OCR):"
+  warn "  macOS: brew install tesseract tesseract-lang poppler && pip3 install pytesseract pdf2image"
+  warn "  Linux: apt install tesseract-ocr tesseract-ocr-chi-sim poppler-utils && pip3 install pytesseract pdf2image"
+  exit 1
+end

data/lib/octo/default_parsers/pdf_parser_ocr.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+pdf_parser_ocr.py — extract text from a scanned/image-only PDF using OCR.
+
+Usage:
+    python3 pdf_parser_ocr.py <file_path>
+
+Output:
+    stdout — extracted text, one block per page, separated by blank lines
+    stderr — error messages
+    exit 0  — success (text was extracted)
+    exit 1  — failure / no text found
+    exit 2  — dependency missing (pytesseract or pdf2image)
+    exit 3  — pdf2image couldn't rasterise the PDF (usually missing poppler)
+
+Called from pdf_parser.rb as the third-tier fallback (after pdftotext and
+pdfplumber). This script is copied into ~/.octo/parsers/ and can be
+edited freely by the LLM — common tweaks:
+  - Change DPI (higher = better accuracy, slower + more memory)
+  - Change OCR_LANG to match your document (e.g. "jpn+eng")
+  - Add image preprocessing (deskew, contrast, threshold) before OCR
+  - Adjust MAX_PAGES for very large scans
+
+Environment variable overrides:
+  OCTO_OCR_LANG       — override OCR_LANG (e.g. "eng", "jpn+eng")
+  OCTO_OCR_MAX_PAGES  — override MAX_PAGES
+  OCTO_OCR_DPI        — override DPI
+
+Install:
+    macOS: brew install tesseract tesseract-lang poppler
+           pip3 install pytesseract pdf2image
+    Linux: apt install tesseract-ocr tesseract-ocr-chi-sim poppler-utils
+           pip3 install pytesseract pdf2image
+"""
+
+# VERSION: 1
+
+import os
+import sys
+
+# --- Config ---
+# Simplified Chinese + English covers most mixed-language documents.
+# For pure English scans, "eng" alone is faster and lighter.
+OCR_LANG = "chi_sim+eng"
+
+# 200 DPI is a good balance: tesseract's accuracy plateau starts around
+# 300 DPI, but memory + time cost scales quadratically. Raise to 300 for
+# small fonts or when accuracy matters more than speed.
+DPI = 200
+
+# Hard cap on pages to OCR. OCR is slow (~1-3s/page); for huge scans the
+# LLM should be told to OCR in chunks instead.
+MAX_PAGES = 50
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.stderr.write("Usage: pdf_parser_ocr.py <file_path>\n")
+        sys.exit(1)
+
+    path = sys.argv[1]
+
+    try:
+        import pytesseract
+        from pdf2image import convert_from_path
+    except ImportError as e:
+        sys.stderr.write(f"OCR dependencies missing: {e}\n")
+        sys.stderr.write("Install with: pip3 install pytesseract pdf2image\n")
+        sys.exit(2)
+
+    lang = os.environ.get("OCTO_OCR_LANG", OCR_LANG)
+    max_pages = int(os.environ.get("OCTO_OCR_MAX_PAGES", MAX_PAGES))
+    dpi = int(os.environ.get("OCTO_OCR_DPI", DPI))
+
+    try:
+        images = convert_from_path(path, dpi=dpi, last_page=max_pages)
+    except Exception as e:
+        sys.stderr.write(f"pdf2image failed: {e}\n")
+        sys.stderr.write("Is poppler installed? (brew install poppler / apt install poppler-utils)\n")
+        sys.exit(3)
+
+    pages = []
+    for i, image in enumerate(images, 1):
+        try:
+            text = pytesseract.image_to_string(image, lang=lang)
+        except pytesseract.TesseractError as e:
+            # Most common cause: requested language pack not installed.
+            # Fall back to English-only for this page rather than aborting.
+            sys.stderr.write(f"tesseract error on page {i}: {e}\n")
+            text = pytesseract.image_to_string(image, lang="eng")
+        text = text.strip()
+        if text:
+            pages.append(f"--- Page {i} (OCR) ---\n{text}")
+
+    if not pages:
+        sys.stderr.write("OCR produced no text — PDF may be blank or unreadable.\n")
+        sys.exit(1)
+
+    print("\n\n".join(pages))
+
+
+if __name__ == "__main__":
+    main()