Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion src/docs/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
3 changes: 3 additions & 0 deletions src/main/codex/pip-comment-client.test.ts
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -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. ' } } });
Expand Down
4 changes: 2 additions & 2 deletions src/main/codex/pip-comment-client.ts
Original file line number Diff line number Diff line change
@@ -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<string, unknown>;
Expand Down Expand Up @@ -122,7 +122,7 @@ export function generatePipComment(options: PipCommentClientOptions): Promise<Pi
if (!model || !threadId || result.model !== model.model || result.modelProvider !== 'openai' || object(result.thread).ephemeral !== true) { finish(); break; }
send({ id: 6, method: 'turn/start', params: {
threadId, model: model.model, ...(model.effort ? { effort: model.effort } : {}), serviceTier: 'default',
input: [{ type: 'text', text: JSON.stringify({ event: options.event, ...(options.prompt ? { submittedPromptExcerpt: options.prompt } : {}) }), text_elements: [] }],
input: [{ type: 'text', text: JSON.stringify({ event: options.event, situation: PIP_AI_SITUATIONS[options.event], ...(options.prompt ? { submittedPromptExcerpt: options.prompt } : {}) }), text_elements: [] }],
} });
} else if (message.id === 6) {
const id = object(object(message.result).turn).id;
Expand Down
2 changes: 2 additions & 0 deletions src/main/ipc/pip-handlers.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,8 @@ describe('Pip consent and IPC boundary', () => {
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);
Expand Down
100 changes: 100 additions & 0 deletions src/renderer/components/sidebar/PipPanel.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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 } });
Expand Down
18 changes: 16 additions & 2 deletions src/renderer/hooks/usePip.ts
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,12 @@ function usePipGaze(panelRef: RefObject<HTMLElement | null>, 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<string, number> = new Map();
const NO_NUDGES: readonly PipNudge[] = [];

Expand All @@ -84,6 +90,7 @@ export function usePip(
const [reducedMotion, setReducedMotion] = useState(() => globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false);
const [expression, setExpression] = useState<PipMoment | null>(null);
const [speech, setSpeech] = useState<PipMoment | null>(null);
const speechAt = useRef(0);
const [typing, setTyping] = useState(false);
const [napping, setNapping] = useState(false);
const sleeping = useRef(false);
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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);
Expand Down
20 changes: 12 additions & 8 deletions src/renderer/hooks/usePipComments.ts
Original file line number Diff line number Diff line change
@@ -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); }
Expand All @@ -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);
Expand Down
17 changes: 16 additions & 1 deletion src/shared/pip.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Record<PipAiEvent, string>> = {
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 {
Expand Down
Loading