From 93ac5b12340832721e6cbbe96de9d8cc73946fb1 Mon Sep 17 00:00:00 2001 From: Max Thomas Date: Thu, 12 Nov 2026 15:34:33 -0600 Subject: [PATCH] feat(pip): give late AI quips their own window and keep limits in main A quip that arrived late got only what was left of the local line's 12 seconds, and the line could expire under a pending request, which then cancelled a reply that had already been paid for. The local line now stays up while a request is pending (capped at 25 s), a quip that lands gets a full 12 s from arrival, and a failed request leaves the local line with the rest of its own time. The AI cooldown was enforced in both the renderer and main. The renderer copy is gone: main decides and the status line shows the reason it returns. A moment that ends before the 600 ms request delay never reaches main and consumes no attempt. Long turns may now ask for a quip; crashes, helpers joining and nudges stay local. Requests also carry a plain-language situation, so the model is not guessing what an event id like "dizzy" means. Co-Authored-By: Claude Opus 5.5 --- src/docs/settings.md | 4 +- src/main/codex/pip-comment-client.test.ts | 3 + src/main/codex/pip-comment-client.ts | 4 +- src/main/ipc/pip-handlers.test.ts | 2 + .../components/sidebar/PipPanel.test.ts | 100 ++++++++++++++++++ src/renderer/hooks/usePip.ts | 18 +++- src/renderer/hooks/usePipComments.ts | 20 ++-- src/shared/pip.ts | 17 ++- 8 files changed, 154 insertions(+), 14 deletions(-) diff --git a/src/docs/settings.md b/src/docs/settings.md index d6f385d0..6bf41fd7 100644 --- a/src/docs/settings.md +++ b/src/docs/settings.md @@ -193,7 +193,9 @@ Local reactions use session labels, focus, status metadata, and a text-free typi - Enable **AI quips through Codex** in **Personality & comments** to get occasional generated comments using your local Codex CLI's ChatGPT sign-in. This uses your subscription allowance. API-key sign-in is not used for Pip. AI comments are off by default. - Pip selects **GPT-6 Luna**, or **GPT-5.6 Luna** if the current model is absent from the installed CLI's catalog, with the lowest supported reasoning effort and standard speed. It never silently falls back to a larger model. If sign-in, model access, or the connection is unavailable, local quips continue. -- Requests are limited to one every two minutes and twelve attempts per hour, including failures. Each request is a fresh, temporary conversation. Quiet, collapse, hide, and minimize cancel pending requests; missed events are not replayed. +- Pip can ask for a quip when the focused session starts working, waits for input or a permission, finishes a turn (including a long one), or stops; when another session needs you; when you press **Enter**; and when it gets dizzy. Crashes, helpers joining, and operational nudges keep local lines. +- Requests are limited to one every two minutes and twelve attempts per hour, including failures. Tether enforces both limits outside the panel, and the status line under **Share submitted prompts** shows why a moment got a local line instead. A moment that ends within a fraction of a second, before its request is sent, does not count. Each request is a fresh, temporary conversation. Quiet, collapse, hide, and minimize cancel pending requests; missed events are not replayed. +- While a quip is on its way, the local line stays up rather than expiring under it. A quip that arrives gets its own 12 seconds; if none arrives, the local line keeps the rest of its time. A newer comment, or the end of what the line describes, discards a reply that is still pending. - By default Pip supplies only the event (for example, an input wait or Enter press) and chosen personality. Session labels, project paths, draft text, and terminal output are excluded from that context. Codex runs the temporary conversation in Tether's neutral app directory rather than your project. - Separately enable **Share submitted prompts** for specific jokes. Pip reads up to 400 characters of the latest available prompt submitted within the past five minutes from an already-attributed **local Claude or Codex transcript**. Remote sessions and other CLIs use activity only. Common credentials are scrubbed, but arbitrary private text may remain; enabling this sends that excerpt to OpenAI. Pip does not collect draft keystrokes or inspect project files. Tether does not save excerpts or generated comments. diff --git a/src/main/codex/pip-comment-client.test.ts b/src/main/codex/pip-comment-client.test.ts index 4f19ba35..8b2abd21 100644 --- a/src/main/codex/pip-comment-client.test.ts +++ b/src/main/codex/pip-comment-client.test.ts @@ -1,3 +1,4 @@ +import { PIP_AI_SITUATIONS } from '../../shared/pip'; import { EventEmitter } from 'node:events'; import { PassThrough } from 'node:stream'; import { describe, it, expect, vi } from 'vitest'; @@ -70,6 +71,8 @@ describe('Pip bounded Codex turn', () => { expect(f.resolver.mock.calls[0][0]).toMatchObject({ args: expect.arrayContaining(['--disable', 'hooks']) }); f.thread(); expect(f.writes.find(row => row.method === 'turn/start')?.params).toMatchObject({ effort: 'low', serviceTier: 'default' }); + const input = JSON.parse((f.writes.find(row => row.method === 'turn/start')!.params as { input: { text: string }[] }).input[0].text); + expect(input).toEqual({ event: 'submitted', situation: PIP_AI_SITUATIONS.submitted, submittedPromptExcerpt: 'Fix my loop' }); f.frame({ id: 6, result: { turn: { id: 'quip' } } }); f.frame({ method: 'item/completed', params: { threadId: 'other', item: { type: 'agentMessage', text: 'Wrong thread' } } }); f.frame({ method: 'item/completed', params: { threadId: 'pip', turnId: 'quip', item: { type: 'agentMessage', text: ' Bold\nkeyboard energy. ' } } }); diff --git a/src/main/codex/pip-comment-client.ts b/src/main/codex/pip-comment-client.ts index 3faea4da..a588b7e9 100644 --- a/src/main/codex/pip-comment-client.ts +++ b/src/main/codex/pip-comment-client.ts @@ -1,7 +1,7 @@ import { spawn } from 'node:child_process'; import { JsonLineParser, spawnOptions, disposeChild, type CodexAppServerClientOptions } from './app-server-client'; import { resolveCodexExecutable, resolveWindowsSystemExecutable } from './executable-resolver'; -import type { PipAiEvent, PipCommentResult, PipSettings } from '../../shared/pip'; +import { PIP_AI_SITUATIONS, type PipAiEvent, type PipCommentResult, type PipSettings } from '../../shared/pip'; import packageJson from '../../../package.json'; type JsonObject = Record; @@ -122,7 +122,7 @@ export function generatePipComment(options: PipCommentClientOptions): Promise { expect(() => validatePipRequest(raw)).toThrow('Invalid'); } expect(mocks.generate).not.toHaveBeenCalled(); + expect(validatePipRequest({ event: 'longTurn', sessionId: 'a' }).event).toBe('longTurn'); + for (const event of ['crashed', 'delegated', 'quotaHigh']) expect(() => validatePipRequest({ ...request, event })).toThrow('Invalid'); }); it('does not read prompts or generate until AI is explicitly enabled', async () => { await mocks.handlers.get(IPC.PIP_COMMENT)!(trusted, request); diff --git a/src/renderer/components/sidebar/PipPanel.test.ts b/src/renderer/components/sidebar/PipPanel.test.ts index 26e180d4..9d2775b6 100644 --- a/src/renderer/components/sidebar/PipPanel.test.ts +++ b/src/renderer/components/sidebar/PipPanel.test.ts @@ -18,6 +18,7 @@ import { PipPanel } from './PipPanel'; import { DEFAULT_PIP_SETTINGS, type PipSettings } from '../../lib/pip-settings'; import { PIP_COMMENT_COOLDOWN_MS, PIP_EXPRESSION_MS, PIP_NAP_DELAY_MS, PIP_SPEECH_MS, type PipSession } from '../../lib/pip-behavior'; import { reportPipActivity } from '../../lib/pip-activity'; +import { PIP_AI_WAIT_MS } from '../../hooks/usePip'; let container: HTMLDivElement; let root: Root; @@ -124,6 +125,105 @@ describe('Pip sidebar interactions', () => { expect(line()).not.toBe('Stale quip'); }); + it('gives a late AI quip a full window from when it lands', async () => { + let resolve!: (value: unknown) => void; + const comment = vi.fn(() => new Promise(done => { resolve = done; })); + vi.stubGlobal('electronAPI', { pip: { comment, cancelComment: vi.fn().mockResolvedValue(undefined) } }); + settings = { ...settings, aiComments: true }; + await render(); + await state('waiting', 'permission'); + const local = line(); + await advance(600); + // The local line outlives its own 12 seconds while the quip is on its way. + await advance(PIP_SPEECH_MS + 2000); + expect(line()).toBe(local); + await act(async () => resolve({ status: 'ready', line: 'Worth the wait.', model: 'gpt-6-luna', reason: null })); + expect(line()).toBe('Worth the wait.'); + await advance(PIP_SPEECH_MS - 1); + expect(line()).toBe('Worth the wait.'); + await advance(1); + expect(line()).not.toBe('Worth the wait.'); + expect(line()).not.toBe(local); + }); + + it('lets the local line keep only its own time when no quip comes back', async () => { + let resolve!: (value: unknown) => void; + const comment = vi.fn(() => new Promise(done => { resolve = done; })); + vi.stubGlobal('electronAPI', { pip: { comment, cancelComment: vi.fn().mockResolvedValue(undefined) } }); + settings = { ...settings, aiComments: true }; + await render(); + await state('waiting', 'permission'); + const local = line(); + await advance(600 + 4000); + await act(async () => resolve({ status: 'unavailable', line: null, model: null, reason: 'AI comments unavailable. Using local quips.' })); + await advance(PIP_SPEECH_MS - 4600 - 1); + expect(line()).toBe(local); + await advance(1); + expect(line()).not.toBe(local); + }); + + it('does not hold a line forever for a reply that never arrives', async () => { + const comment = vi.fn(() => new Promise(() => {})); + vi.stubGlobal('electronAPI', { pip: { comment, cancelComment: vi.fn().mockResolvedValue(undefined) } }); + settings = { ...settings, aiComments: true }; + await render(); + await state('waiting', 'permission'); + const local = line(); + await advance(600); + await advance(PIP_AI_WAIT_MS - 600 - 1); + expect(line()).toBe(local); + await advance(1); + expect(line()).not.toBe(local); + }); + + it('sends nothing for a moment that ends before the request goes out', async () => { + const comment = vi.fn(); + const cancelComment = vi.fn(); + vi.stubGlobal('electronAPI', { pip: { comment, cancelComment } }); + settings = { ...settings, aiComments: true }; + await render(); + await state('waiting', 'permission'); + await advance(300); + await state('running'); + await advance(PIP_SPEECH_MS); + expect(comment).not.toHaveBeenCalled(); + expect(cancelComment).not.toHaveBeenCalled(); + }); + + it('leaves the AI cooldown to main and shows the reason it gives back', async () => { + const comment = vi.fn() + .mockResolvedValueOnce({ status: 'ready', line: 'First quip.', model: 'gpt-6-luna', reason: null }) + .mockResolvedValueOnce({ status: 'paused', line: null, model: null, reason: 'Taking a breather between AI comments.' }); + vi.stubGlobal('electronAPI', { pip: { comment, cancelComment: vi.fn().mockResolvedValue(undefined) } }); + settings = { ...settings, aiComments: true }; + await render(); + await click('.pip-options-toggle'); + await state('waiting', 'permission'); + await advance(600); + expect(line()).toBe('First quip.'); + await state('running'); + await state('waiting', 'permission'); + await advance(600); + expect(comment).toHaveBeenCalledTimes(2); + expect(container.querySelector('.pip-ai-status')?.textContent).toBe('Taking a breather between AI comments.'); + expect(line()).not.toBe('First quip.'); + }); + + it('asks for a quip when a long turn hands back', async () => { + const comment = vi.fn().mockResolvedValue({ status: 'ready', line: 'Marathon done.', model: 'gpt-6-luna', reason: null }); + vi.stubGlobal('electronAPI', { pip: { comment, cancelComment: vi.fn().mockResolvedValue(undefined) } }); + settings = { ...settings, aiComments: true }; + await render(); + await state('idle'); + await advance(PIP_COMMENT_COOLDOWN_MS); + await state('running'); + await advance(6 * 60_000); + await state('waiting', 'input'); + await advance(600); + expect(comment).toHaveBeenLastCalledWith({ event: 'longTurn', sessionId: 'a' }); + expect(line()).toBe('Marathon done.'); + }); + it('keeps AI requests off by default and exposes separate prompt consent', async () => { const comment = vi.fn(); vi.stubGlobal('electronAPI', { pip: { comment } }); diff --git a/src/renderer/hooks/usePip.ts b/src/renderer/hooks/usePip.ts index 103c8b00..803cd7fe 100644 --- a/src/renderer/hooks/usePip.ts +++ b/src/renderer/hooks/usePip.ts @@ -63,6 +63,12 @@ function usePipGaze(panelRef: RefObject, motionAllowed: bool }, [motionAllowed]); } +/** + * Longest a line is held open for a pending AI quip. Main gives up on a backend after 20 seconds, + * so this only matters if the reply never comes back at all. + */ +export const PIP_AI_WAIT_MS = 25_000; + const NO_CHILDREN: ReadonlyMap = new Map(); const NO_NUDGES: readonly PipNudge[] = []; @@ -84,6 +90,7 @@ export function usePip( const [reducedMotion, setReducedMotion] = useState(() => globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false); const [expression, setExpression] = useState(null); const [speech, setSpeech] = useState(null); + const speechAt = useRef(0); const [typing, setTyping] = useState(false); const [napping, setNapping] = useState(false); const sleeping = useRef(false); @@ -123,6 +130,7 @@ export function usePip( const cooled = now - lastComment.current >= PIP_COMMENT_COOLDOWN_MS; if (!force && tier !== PIP_TIER_URGENT && !cooled && tier <= lastTier.current) return; setSpeech(moment); + speechAt.current = now; lastComment.current = now; lastTier.current = tier; spoken.current.set(event.kind, moment.variation + 1); @@ -164,9 +172,15 @@ export function usePip( useEffect(() => { if (!active || !speech) return; - const timer = setTimeout(() => setSpeech(null), PIP_SPEECH_MS); + // A line waits for its AI quip instead of expiring under it. A quip gets a full window from when + // it lands; otherwise the local line keeps whatever is left of its own. + const elapsed = Date.now() - speechAt.current; + let left = Math.max(0, PIP_SPEECH_MS - elapsed); + if (comments.pending) left = Math.max(0, PIP_AI_WAIT_MS - elapsed); + else if (comments.line) left = PIP_SPEECH_MS; + const timer = setTimeout(() => setSpeech(null), left); return () => clearTimeout(timer); - }, [active, speech]); + }, [active, speech, comments.pending, comments.line]); useEffect(() => { setTyping(false); diff --git a/src/renderer/hooks/usePipComments.ts b/src/renderer/hooks/usePipComments.ts index 19a99ac5..d1202976 100644 --- a/src/renderer/hooks/usePipComments.ts +++ b/src/renderer/hooks/usePipComments.ts @@ -1,25 +1,29 @@ -import { useEffect, useRef, useState } from 'react'; -import { PIP_AI_COOLDOWN_MS, PIP_AI_EVENTS, type PipAiEvent, type PipCommentResult, type PipSettings } from '../../shared/pip'; +import { useEffect, useState } from 'react'; +import { PIP_AI_EVENTS, type PipAiEvent, type PipCommentResult, type PipSettings } from '../../shared/pip'; import type { PipEvent } from '../lib/pip-behavior'; export interface PipMoment { event: PipEvent; variation: number; } +/** Delay before asking, so the CLI can append its submitted prompt to its transcript. */ +export const PIP_AI_REQUEST_DELAY_MS = 600; + +/** + * Asks main for a quip about the current spoken moment. Main owns the cooldown and hourly limit and + * answers with the reason when it declines, so the renderer keeps no limit of its own. A moment that + * ends before the request is sent never reaches main and so never counts as an attempt. + */ export function usePipComments(moment: PipMoment | null, sessionId: string | null, active: boolean, settings: PipSettings) { - const lastRequest = useRef(-Infinity); const [reply, setReply] = useState<{ moment: PipMoment; sessionId: string | null; value: PipCommentResult } | null>(null); const [pending, setPending] = useState(false); const enabled = active && settings.aiComments && !settings.quiet; useEffect(() => { setReply(null); setPending(false); - if (!enabled || !moment || !PIP_AI_EVENTS.includes(moment.event.kind as PipAiEvent) - || Date.now() - lastRequest.current < PIP_AI_COOLDOWN_MS) return; + if (!enabled || !moment || !PIP_AI_EVENTS.includes(moment.event.kind as PipAiEvent)) return; let cancelled = false; let requested = false; - // Give the CLI a moment to append its submitted prompt to its transcript. const timer = setTimeout(() => { if (!window.electronAPI?.pip) return; requested = true; - lastRequest.current = Date.now(); setPending(true); window.electronAPI.pip.comment({ event: moment.event.kind as PipAiEvent, sessionId }).then(value => { if (!cancelled) { setReply({ moment, sessionId, value }); setPending(false); } @@ -29,7 +33,7 @@ export function usePipComments(moment: PipMoment | null, sessionId: string | nul setPending(false); } }); - }, 600); + }, PIP_AI_REQUEST_DELAY_MS); return () => { cancelled = true; clearTimeout(timer); diff --git a/src/shared/pip.ts b/src/shared/pip.ts index 8dec68c3..b7f14504 100644 --- a/src/shared/pip.ts +++ b/src/shared/pip.ts @@ -37,8 +37,23 @@ export function readPipSettings(raw: string | null): PipSettings { export const PIP_AI_COOLDOWN_MS = 120_000; export const PIP_AI_HOURLY_LIMIT = 12; -export const PIP_AI_EVENTS = ['working', 'permission', 'ready', 'stopped', 'attention', 'submitted', 'dizzy'] as const; +/** + * Events that may ask for an AI quip. `longTurn` is the only PR 3 reaction here: crashes are not + * joke material, helpers joining is frequent, and nudges stay local by design. + */ +export const PIP_AI_EVENTS = ['working', 'permission', 'ready', 'longTurn', 'stopped', 'attention', 'submitted', 'dizzy'] as const; export type PipAiEvent = typeof PIP_AI_EVENTS[number]; +/** Plain-language situations sent to a quip backend, so the model is not guessing at event ids. */ +export const PIP_AI_SITUATIONS: Readonly> = { + working: 'The coding agent started working.', + permission: 'The coding agent is waiting for the person to approve a permission prompt.', + ready: 'The coding agent finished its turn and is waiting for the person.', + longTurn: 'The coding agent just finished a turn that took several minutes.', + stopped: 'The session was stopped.', + attention: 'A different session in the background needs the person.', + submitted: 'The person just pressed Enter to send something to the agent.', + dizzy: 'The person is switching between sessions very quickly.', +}; /** Deliberately contains no keystrokes, prompts, labels, paths, or terminal output. */ export interface PipCommentRequest { event: PipAiEvent; sessionId: string | null; } export interface PipCommentResult {