playwriter 0.0.89 → 0.0.103

package/src/executor.ts

@@ -26,7 +26,7 @@ import { ScopedFS } from './scoped-fs.js'
 import {
   screenshotWithAccessibilityLabels,
   getAriaSnapshot,
-  resizeImage,
+  resizeImageForAgent,
   type ScreenshotResult,
   type SnapshotFormat,
 } from './aria-snapshot.js'
@@ -192,9 +192,18 @@ const ALLOWED_MODULES = new Set([
   'node:fs',
 ])
 
+export interface ExecuteScreenshot {
+  path: string
+  base64: string
+  mimeType: 'image/png'
+  snapshot: string
+  labelCount: number
+}
+
 export interface ExecuteResult {
   text: string
   images: Array<{ data: string; mimeType: string }>
+  screenshots: ExecuteScreenshot[]
   isError: boolean
 }
 
@@ -217,6 +226,8 @@ export interface CdpConfig {
   port?: number
   token?: string
   extensionId?: string | null
+  /** Direct CDP WebSocket URL — bypasses relay + extension, connects straight to Chrome */
+  directCdpUrl?: string
 }
 
 export interface SessionMetadata {
@@ -225,6 +236,15 @@ export interface SessionMetadata {
   profile: { email: string; id: string } | null
 }
 
+export interface SessionInfo {
+  id: string
+  stateKeys: string[]
+  extensionId: string | null
+  browser: string | null
+  profile: { email: string; id: string } | null
+  cwd: string | null
+}
+
 export interface ExecutorOptions {
   cdpConfig: CdpConfig
   sessionMetadata?: SessionMetadata
@@ -243,6 +263,23 @@ function isPromise(value: any): value is Promise<unknown> {
   return typeof value === 'object' && value !== null && typeof value.then === 'function'
 }
 
+/**
+ * Duck-type check for a Playwright ChannelOwner (Response, Page, Browser,
+ * Request, Frame, BrowserContext, etc.). Used to skip auto-printing these
+ * objects from the REPL — they're meant for programmatic use, and dumping
+ * them risks leaking internal fields. Users can still `console.log(obj)` to
+ * inspect them via the safe handler in playwright-core. See issue #82.
+ */
+export function isPlaywrightChannelOwner(value: any): boolean {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof value._type === 'string' &&
+    typeof value._guid === 'string' &&
+    value._connection !== undefined
+  )
+}
+
 export class PlaywrightExecutor {
   private isConnected = false
   private page: Page | null = null
@@ -272,14 +309,19 @@ export class PlaywrightExecutor {
   private cdpConfig: CdpConfig
   private logger: ExecutorLogger
   private sessionMetadata: SessionMetadata
+  private sessionCwd: string | null
   private hasWarnedExtensionOutdated = false
 
   constructor(options: ExecutorOptions) {
     this.cdpConfig = options.cdpConfig
     this.logger = options.logger || { log: console.log, error: console.error }
     this.sessionMetadata = options.sessionMetadata || { extensionId: null, browser: null, profile: null }
+    this.sessionCwd = options.cwd ? path.resolve(options.cwd) : null
     // ScopedFS expects an array of allowed directories. If cwd is provided, use it; otherwise use defaults.
-    this.scopedFs = new ScopedFS(options.cwd ? [options.cwd, '/tmp', os.tmpdir()] : undefined)
+    this.scopedFs = new ScopedFS(
+      this.sessionCwd ? [this.sessionCwd, '/tmp', os.tmpdir()] : undefined,
+      this.sessionCwd || undefined,
+    )
     this.sandboxedRequire = this.createSandboxedRequire(require)
   }
 
@@ -568,19 +610,55 @@ export class PlaywrightExecutor {
     }
   }
 
-  private async ensureConnection(): Promise<{ browser: Browser; page: Page }> {
-    if (this.isConnected && this.browser && this.page) {
-      return { browser: this.browser, page: this.page }
+  private isDirectCdpMode(): boolean {
+    return !!this.cdpConfig.directCdpUrl
+  }
+
+  /**
+   * Connect to Chrome and set up context/page. Shared by ensureConnection and reset.
+   * In direct CDP mode, connects straight to Chrome's WebSocket.
+   * In extension mode, checks extension status then connects via relay.
+   */
+  private async connectToBrowser(): Promise<{ browser: Browser; page: Page; context: BrowserContext }> {
+    if (this.isDirectCdpMode()) {
+      // Direct CDP: connect straight to Chrome, no relay or extension needed
+      const browser = await chromium.connectOverCDP(this.cdpConfig.directCdpUrl!)
+
+      browser.on('disconnected', () => {
+        this.logger.log('Browser disconnected, clearing connection state')
+        this.clearConnectionState()
+      })
+
+      const contexts = browser.contexts()
+      const context = contexts.length > 0 ? contexts[0] : await browser.newContext()
+
+      context.setDefaultTimeout(60000)
+      context.setDefaultNavigationTimeout(10000)
+
+      context.on('page', (page) => {
+        this.setupPageListeners(page)
+      })
+
+      context.pages().forEach((p) => this.setupPageListeners(p))
+
+      // In direct CDP mode, pages are always available (all tabs visible).
+      // Use the first non-closed page, or create one.
+      const pages = context.pages().filter((p) => !p.isClosed())
+      const page = pages.length > 0 ? pages[0] : await context.newPage()
+      this.setupPageListeners(page)
+
+      await this.setDeviceScaleFactorForMacOS(context)
+
+      return { browser, page, context }
     }
 
-    // Check extension status first to provide better error messages
+    // Extension mode: check status first for better error messages
     const extensionStatus = await this.checkExtensionStatus()
     if (!extensionStatus.connected) {
       throw new Error(EXTENSION_NOT_CONNECTED_ERROR)
     }
     this.warnIfExtensionOutdated(extensionStatus.playwriterVersion)
 
-    // Generate a fresh unique URL for each Playwright connection
     const cdpUrl = getCdpUrl(this.cdpConfig)
     const browser = await chromium.connectOverCDP(cdpUrl)
 
@@ -607,6 +685,16 @@ export class PlaywrightExecutor {
 
     await this.setDeviceScaleFactorForMacOS(context)
 
+    return { browser, page, context }
+  }
+
+  private async ensureConnection(): Promise<{ browser: Browser; page: Page }> {
+    if (this.isConnected && this.browser && this.page) {
+      return { browser: this.browser, page: this.page }
+    }
+
+    const { browser, page, context } = await this.connectToBrowser()
+
     this.browser = browser
     this.page = page
     this.context = context
@@ -656,39 +744,7 @@ export class PlaywrightExecutor {
     this.clearConnectionState()
     this.clearUserState()
 
-    // Check extension status first to provide better error messages
-    const extensionStatus = await this.checkExtensionStatus()
-    if (!extensionStatus.connected) {
-      throw new Error(EXTENSION_NOT_CONNECTED_ERROR)
-    }
-    this.warnIfExtensionOutdated(extensionStatus.playwriterVersion)
-
-    // Generate a fresh unique URL for each Playwright connection
-    const cdpUrl = getCdpUrl(this.cdpConfig)
-    const browser = await chromium.connectOverCDP(cdpUrl)
-
-    browser.on('disconnected', () => {
-      this.logger.log('Browser disconnected, clearing connection state')
-      this.clearConnectionState()
-    })
-
-    const contexts = browser.contexts()
-    const context = contexts.length > 0 ? contexts[0] : await browser.newContext()
-
-    // Action timeout (click, fill, hover, etc.) is longer to tolerate slower
-    // SPA/Turbo navigations and post-click settling on real sites.
-    // Navigation timeout (goto, reload) remains separate.
-    context.setDefaultTimeout(60000)
-    context.setDefaultNavigationTimeout(10000)
-
-    context.on('page', (page) => {
-      this.setupPageListeners(page)
-    })
-
-    context.pages().forEach((p) => this.setupPageListeners(p))
-    const page = await this.ensurePageForContext({ context, timeout: 10000 })
-
-    await this.setDeviceScaleFactorForMacOS(context)
+    const { browser, page, context } = await this.connectToBrowser()
 
     this.browser = browser
     this.page = page
@@ -971,6 +1027,15 @@ export class PlaywrightExecutor {
       }
 
       const screenshotCollector: ScreenshotResult[] = []
+      // Separate collector for images produced by resizeImageForAgent() calls.
+      // These get merged into result.images so the CLI can emit them via Kitty Graphics.
+      const resizedImageCollector: Array<{ data: string; mimeType: string }> = []
+
+      const resizeImageForAgentFn: typeof resizeImageForAgent = async (options) => {
+        const result = await resizeImageForAgent(options)
+        resizedImageCollector.push({ data: result.buffer.toString('base64'), mimeType: result.mimeType })
+        return result
+      }
 
       const screenshotWithAccessibilityLabelsFn = async (options: { page: Page; interactiveOnly?: boolean }) => {
         return screenshotWithAccessibilityLabels({
@@ -1052,6 +1117,7 @@ export class PlaywrightExecutor {
       let vmContextObj: any = {
         page,
         context,
+        browser: this.browser,
         state: this.userState,
         console: customConsole,
         snapshot,
@@ -1070,7 +1136,9 @@ export class PlaywrightExecutor {
         formatStylesAsText,
         getReactSource: getReactSourceFn,
         screenshotWithAccessibilityLabels: screenshotWithAccessibilityLabelsFn,
-        resizeImage,
+        resizeImageForAgent: resizeImageForAgentFn,
+        // Backward-compatible alias for resizeImageForAgent
+        resizeImage: resizeImageForAgentFn,
         ghostCursor: {
           show: showGhostCursor,
           hide: hideGhostCursor,
@@ -1091,6 +1159,7 @@ export class PlaywrightExecutor {
           const { page: newPage, context: newContext } = await self.reset()
           vmContextObj.page = newPage
           vmContextObj.context = newContext
+          vmContextObj.browser = self.browser
           return { page: newPage, context: newContext }
         },
         require: this.sandboxedRequire,
@@ -1138,7 +1207,12 @@ export class PlaywrightExecutor {
       // Only show return value if user explicitly used return
       if (hasExplicitReturn) {
         const resolvedResult = isPromise(result) ? await result : result
-        if (resolvedResult !== undefined) {
+        // Auto-returned Playwright handles (Response, Page, Browser, Request,
+        // Frame, etc.) are silently skipped — they're programmatic references,
+        // not useful display data. Users can `console.log(response)` or
+        // return specific fields (`return response.url()`) to see values.
+        // See issue #82.
+        if (resolvedResult !== undefined && !isPlaywrightChannelOwner(resolvedResult)) {
           const formatted =
             typeof resolvedResult === 'string'
               ? resolvedResult
@@ -1161,12 +1235,6 @@ export class PlaywrightExecutor {
         responseText = 'Code executed successfully (no output)'
       }
 
-      for (const screenshot of screenshotCollector) {
-        responseText += `\nScreenshot saved to: ${screenshot.path}\n`
-        responseText += `Labels shown: ${screenshot.labelCount}\n\n`
-        responseText += `Accessibility snapshot:\n${screenshot.snapshot}\n`
-      }
-
       const MAX_LENGTH = 10000
       let finalText = responseText.trim()
       if (finalText.length > MAX_LENGTH) {
@@ -1175,9 +1243,19 @@ export class PlaywrightExecutor {
           `\n\n[Truncated to ${MAX_LENGTH} characters. Use search to find specific content]`
       }
 
-      const images = screenshotCollector.map((s) => ({ data: s.base64, mimeType: s.mimeType }))
-
-      return { text: finalText, images, isError: false }
+      const images = [
+        ...screenshotCollector.map((s) => ({ data: s.base64, mimeType: s.mimeType })),
+        ...resizedImageCollector,
+      ]
+      const screenshots: ExecuteScreenshot[] = screenshotCollector.map((s) => ({
+        path: s.path,
+        base64: s.base64,
+        mimeType: s.mimeType,
+        snapshot: s.snapshot,
+        labelCount: s.labelCount,
+      }))
+
+      return { text: finalText, images, screenshots, isError: false }
     } catch (error: any) {
       const errorStack = error.stack || error.message
       const isTimeoutError =
@@ -1196,12 +1274,14 @@ export class PlaywrightExecutor {
       return {
         text: `${logsText}${warningText}\nError executing code: ${errorText}${resetHint}`,
         images: [],
+        screenshots: [],
         isError: true,
       }
     }
   }
 
   // When extension is connected but has no pages, auto-create only if PLAYWRITER_AUTO_ENABLE is set.
+  // In direct CDP mode, always create a page (no extension check needed).
   private async ensurePageForContext(options: { context: BrowserContext; timeout: number }): Promise<Page> {
     const { context, timeout } = options
     const pages = context.pages().filter((p) => !p.isClosed())
@@ -1209,6 +1289,14 @@ export class PlaywrightExecutor {
       return pages[0]
     }
 
+    // Direct CDP mode: always create a new page, no extension involved
+    if (this.isDirectCdpMode()) {
+      const page = await context.newPage()
+      this.setupPageListeners(page)
+      await page.waitForLoadState('domcontentloaded', { timeout }).catch(() => {})
+      return page
+    }
+
     const extensionStatus = await this.checkExtensionStatus()
     if (!extensionStatus.connected) {
       throw new Error(EXTENSION_NOT_CONNECTED_ERROR)
@@ -1256,10 +1344,21 @@ export class PlaywrightExecutor {
   getSessionMetadata(): SessionMetadata {
     return this.sessionMetadata
   }
+
+  getSessionInfo({ id }: { id: string }): SessionInfo {
+    return {
+      id,
+      stateKeys: this.getStateKeys(),
+      extensionId: this.sessionMetadata.extensionId,
+      browser: this.sessionMetadata.browser,
+      profile: this.sessionMetadata.profile,
+      cwd: this.sessionCwd,
+    }
+  }
 }
 
 /**
- * Session manager for multiple executors, keyed by session ID (typically cwd hash)
+ * Session manager for multiple executors, keyed by session ID.
  */
 export class ExecutorManager {
   private executors = new Map<string, PlaywrightExecutor>()
@@ -1271,14 +1370,27 @@ export class ExecutorManager {
     this.logger = options.logger || { log: console.log, error: console.error }
   }
 
-  getExecutor(options: { sessionId: string; cwd?: string; sessionMetadata?: SessionMetadata }): PlaywrightExecutor {
+  getExecutor(options: {
+    sessionId: string
+    cwd?: string
+    sessionMetadata?: SessionMetadata
+    /** Override cdpConfig for this session (e.g. direct CDP connection) */
+    cdpConfig?: CdpConfig
+  }): PlaywrightExecutor {
     const { sessionId, cwd, sessionMetadata } = options
     let executor = this.executors.get(sessionId)
     if (!executor) {
-      const baseConfig = typeof this.cdpConfig === 'function' ? this.cdpConfig(sessionId) : this.cdpConfig
-      const cdpConfig = sessionMetadata?.extensionId
-        ? { ...baseConfig, extensionId: sessionMetadata.extensionId }
-        : baseConfig
+      const cdpConfig = (() => {
+        // Per-session override takes priority (used for direct CDP sessions)
+        if (options.cdpConfig) {
+          return options.cdpConfig
+        }
+        const baseConfig = typeof this.cdpConfig === 'function' ? this.cdpConfig(sessionId) : this.cdpConfig
+        if (sessionMetadata?.extensionId) {
+          return { ...baseConfig, extensionId: sessionMetadata.extensionId }
+        }
+        return baseConfig
+      })()
       executor = new PlaywrightExecutor({
         cdpConfig,
         sessionMetadata,
@@ -1298,22 +1410,9 @@ export class ExecutorManager {
     return this.executors.get(sessionId) || null
   }
 
-  listSessions(): Array<{
-    id: string
-    stateKeys: string[]
-    extensionId: string | null
-    browser: string | null
-    profile: { email: string; id: string } | null
-  }> {
+  listSessions(): SessionInfo[] {
     return [...this.executors.entries()].map(([id, executor]) => {
-      const metadata = executor.getSessionMetadata()
-      return {
-        id,
-        stateKeys: executor.getStateKeys(),
-        extensionId: metadata.extensionId,
-        browser: metadata.browser,
-        profile: metadata.profile,
-      }
+      return executor.getSessionInfo({ id })
     })
   }
 }

package/src/executor.unit.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { shouldAutoReturn, wrapCode } from './executor.js'
+import { shouldAutoReturn, wrapCode, isPlaywrightChannelOwner } from './executor.js'
 
 describe('shouldAutoReturn', () => {
   it('returns true for simple expressions', () => {
@@ -135,3 +135,34 @@ describe('wrapCode', () => {
     expect(wrapCode('x = 5')).toBe('(async () => { x = 5 })()')
   })
 })
+
+describe('isPlaywrightChannelOwner', () => {
+  it('detects ChannelOwner-shaped objects', () => {
+    const fakeResponse = {
+      _type: 'Response',
+      _guid: 'response@abc123',
+      _connection: { _platform: { env: {} } },
+    }
+    expect(isPlaywrightChannelOwner(fakeResponse)).toBe(true)
+  })
+
+  it('rejects plain objects and primitives', () => {
+    expect(isPlaywrightChannelOwner(null)).toBe(false)
+    expect(isPlaywrightChannelOwner(undefined)).toBe(false)
+    expect(isPlaywrightChannelOwner('string')).toBe(false)
+    expect(isPlaywrightChannelOwner(42)).toBe(false)
+    expect(isPlaywrightChannelOwner({})).toBe(false)
+    expect(isPlaywrightChannelOwner([])).toBe(false)
+    expect(isPlaywrightChannelOwner({ url: 'https://example.com', status: 200 })).toBe(false)
+  })
+
+  it('rejects partial matches missing required fields', () => {
+    expect(isPlaywrightChannelOwner({ _type: 'Response' })).toBe(false)
+    expect(isPlaywrightChannelOwner({ _guid: 'abc' })).toBe(false)
+    expect(isPlaywrightChannelOwner({ _type: 'x', _guid: 'y' })).toBe(false)
+    // Missing _connection
+    expect(isPlaywrightChannelOwner({ _type: 'x', _guid: 'y' })).toBe(false)
+    // _type must be a string
+    expect(isPlaywrightChannelOwner({ _type: 123, _guid: 'y', _connection: {} })).toBe(false)
+  })
+})

package/src/kitty-graphics.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from 'vitest'
+import { buildKittySequence, canEmitKittyGraphics } from './kitty-graphics.js'
+
+// Minimal valid PNG (1x1 transparent pixel) as base64
+const TINY_PNG_B64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=='
+
+describe('kitty-graphics', () => {
+  describe('canEmitKittyGraphics', () => {
+    test('returns false when AGENT_GRAPHICS is not set', () => {
+      const prev = process.env.AGENT_GRAPHICS
+      delete process.env.AGENT_GRAPHICS
+      expect(canEmitKittyGraphics()).toBe(false)
+      if (prev !== undefined) {
+        process.env.AGENT_GRAPHICS = prev
+      }
+    })
+
+    test('returns true when AGENT_GRAPHICS=kitty', () => {
+      const prev = process.env.AGENT_GRAPHICS
+      process.env.AGENT_GRAPHICS = 'kitty'
+      expect(canEmitKittyGraphics()).toBe(true)
+      if (prev !== undefined) {
+        process.env.AGENT_GRAPHICS = prev
+      } else {
+        delete process.env.AGENT_GRAPHICS
+      }
+    })
+
+    test('returns true when AGENT_GRAPHICS contains kitty among others', () => {
+      const prev = process.env.AGENT_GRAPHICS
+      process.env.AGENT_GRAPHICS = 'kitty,iterm2'
+      expect(canEmitKittyGraphics()).toBe(true)
+      if (prev !== undefined) {
+        process.env.AGENT_GRAPHICS = prev
+      } else {
+        delete process.env.AGENT_GRAPHICS
+      }
+    })
+  })
+
+  describe('buildKittySequence', () => {
+    test('small payload produces single escape sequence', () => {
+      const result = buildKittySequence({ base64: 'AAAA' })
+      expect(result).toMatchInlineSnapshot(`"_Ga=T,f=100;AAAA\\"`)
+    })
+
+    test('sequence starts with APC and ends with ST', () => {
+      const result = buildKittySequence({ base64: 'AAAA' })
+      expect(result.startsWith('\x1b_G')).toBe(true)
+      expect(result.endsWith('\x1b\\')).toBe(true)
+    })
+
+    test('real PNG base64 produces valid sequence', () => {
+      const result = buildKittySequence({ base64: TINY_PNG_B64 })
+      // Should be a single chunk (small payload)
+      expect(result).toContain('a=T,f=100')
+      expect(result).toContain(TINY_PNG_B64)
+    })
+
+    test('large payload is chunked at 4096 bytes', () => {
+      // Create a payload larger than 4096 bytes
+      const bigPayload = 'A'.repeat(10000)
+      const result = buildKittySequence({ base64: bigPayload })
+
+      // Should have multiple escape sequences
+      // First chunk: a=T,f=100,m=1
+      expect(result).toContain('a=T,f=100,m=1')
+      // Last chunk: m=0
+      expect(result).toContain('\x1b_Gm=0;')
+      // Should NOT contain single-shot a=T,f=100; (without m=)
+      expect(result).not.toMatch(/a=T,f=100;/)
+    })
+
+    test('three-chunk payload has correct structure', () => {
+      // 9000 bytes = 3 chunks: 4096 + 4096 + 808
+      const payload = 'B'.repeat(9000)
+      const result = buildKittySequence({ base64: payload })
+
+      const sequences = result.split('\x1b\\').filter(Boolean)
+      expect(sequences.length).toBe(3)
+
+      // First: a=T,f=100,m=1
+      expect(sequences[0]).toContain('a=T,f=100,m=1')
+      // Middle: m=1
+      expect(sequences[1]).toContain('\x1b_Gm=1;')
+      // Last: m=0
+      expect(sequences[2]).toContain('\x1b_Gm=0;')
+    })
+  })
+
+  describe('round-trip with kitty-graphics-agent parser', () => {
+    test('emitted sequence can be parsed back to extract the image', async () => {
+      // Dynamically import the parser to test round-trip
+      let extractKittyGraphics: typeof import('kitty-graphics-agent/parser').extractKittyGraphics
+      try {
+        const mod = await import('kitty-graphics-agent/parser')
+        extractKittyGraphics = mod.extractKittyGraphics
+      } catch {
+        // kitty-graphics-agent not installed, skip
+        console.log('kitty-graphics-agent not installed, skipping round-trip test')
+        return
+      }
+
+      const sequence = buildKittySequence({ base64: TINY_PNG_B64 })
+      const output = `some text before\n${sequence}\nsome text after`
+      const result = extractKittyGraphics(output)
+
+      expect(result.cleanedOutput).toMatchInlineSnapshot(`
+        "some text before
+        
+        some text after"
+      `)
+      expect(result.images.length).toBe(1)
+      expect(result.images[0].mime).toBe('image/png')
+      expect(result.images[0].data).toBe(TINY_PNG_B64)
+    })
+
+    test('chunked sequence round-trips correctly', async () => {
+      let extractKittyGraphics: typeof import('kitty-graphics-agent/parser').extractKittyGraphics
+      try {
+        const mod = await import('kitty-graphics-agent/parser')
+        extractKittyGraphics = mod.extractKittyGraphics
+      } catch {
+        console.log('kitty-graphics-agent not installed, skipping round-trip test')
+        return
+      }
+
+      const bigPayload = 'A'.repeat(10000)
+      const sequence = buildKittySequence({ base64: bigPayload })
+      const result = extractKittyGraphics(sequence)
+
+      expect(result.cleanedOutput).toBe('')
+      expect(result.images.length).toBe(1)
+      expect(result.images[0].mime).toBe('image/png')
+      expect(result.images[0].data).toBe(bigPayload)
+    })
+  })
+})

package/src/kitty-graphics.ts

@@ -0,0 +1,79 @@
+// Kitty Graphics Protocol emitter for CLI output.
+// Emits base64-encoded PNG images as APC escape sequences so agents with
+// kitty-graphics-agent (or compatible parsers) can extract and pass them
+// to LLMs as media parts.
+//
+// Protocol format:
+//   \x1b_G<control_data>;<base64_payload>\x1b\\
+//
+// Only emits when AGENT_GRAPHICS env var contains 'kitty', signaling that
+// an agent is intercepting stdout and can handle Kitty Graphics Protocol.
+// See: https://github.com/remorses/kitty-graphics-agent
+
+// Kitty spec recommends max 4096 bytes per chunk payload
+const CHUNK_SIZE = 4096
+
+/**
+ * Check if the current environment supports Kitty Graphics Protocol output.
+ * Returns true when AGENT_GRAPHICS=kitty is set (agent is intercepting stdout).
+ */
+export function canEmitKittyGraphics(): boolean {
+  return process.env.AGENT_GRAPHICS?.includes('kitty') ?? false
+}
+
+/**
+ * Emit a PNG image to stdout using the Kitty Graphics Protocol.
+ * The image is chunked per the spec (4096 bytes per chunk).
+ *
+ * Only call this when canEmitKittyGraphics() returns true.
+ */
+export function emitKittyImage({ base64 }: { base64: string }): void {
+  const chunks = splitIntoChunks(base64, CHUNK_SIZE)
+
+  if (chunks.length === 1) {
+    // Single chunk: no chunked transfer needed
+    process.stdout.write(`\x1b_Ga=T,f=100;${chunks[0]}\x1b\\`)
+    return
+  }
+
+  // Multi-chunk: first chunk has full control data + m=1,
+  // continuation chunks have only m=1, last chunk has m=0
+  for (let i = 0; i < chunks.length; i++) {
+    const isFirst = i === 0
+    const isLast = i === chunks.length - 1
+    const control = isFirst ? 'a=T,f=100,m=1' : isLast ? 'm=0' : 'm=1'
+    process.stdout.write(`\x1b_G${control};${chunks[i]}\x1b\\`)
+  }
+}
+
+function splitIntoChunks(str: string, size: number): string[] {
+  if (str.length <= size) {
+    return [str]
+  }
+  const chunks: string[] = []
+  for (let i = 0; i < str.length; i += size) {
+    chunks.push(str.slice(i, i + size))
+  }
+  return chunks
+}
+
+/**
+ * Build the raw Kitty Graphics escape sequence string for a PNG image.
+ * Useful for testing without writing to stdout.
+ */
+export function buildKittySequence({ base64 }: { base64: string }): string {
+  const chunks = splitIntoChunks(base64, CHUNK_SIZE)
+
+  if (chunks.length === 1) {
+    return `\x1b_Ga=T,f=100;${chunks[0]}\x1b\\`
+  }
+
+  const parts: string[] = []
+  for (let i = 0; i < chunks.length; i++) {
+    const isFirst = i === 0
+    const isLast = i === chunks.length - 1
+    const control = isFirst ? 'a=T,f=100,m=1' : isLast ? 'm=0' : 'm=1'
+    parts.push(`\x1b_G${control};${chunks[i]}\x1b\\`)
+  }
+  return parts.join('')
+}