@narumitw/pi-codex-imagegen 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,408 @@
1
+ import { stripVTControlCharacters } from "node:util";
2
+ import {
3
+ DEFAULT_MAX_BYTES,
4
+ DEFAULT_MAX_LINES,
5
+ type ExtensionAPI,
6
+ type ExtensionContext,
7
+ type ExtensionUIContext,
8
+ getAgentDir,
9
+ resizeImage,
10
+ type ToolDefinition,
11
+ truncateHead,
12
+ } from "@earendil-works/pi-coding-agent";
13
+ import { Container, Image, Text } from "@earendil-works/pi-tui";
14
+ import { Type } from "typebox";
15
+ import { decodeImage, preflightOutput, publishImage } from "./artifacts.js";
16
+ import { generateImageRequest, getImageAuthStatus, MAX_PROMPT_CHARS } from "./image-client.js";
17
+ import { showImagegenMenu } from "./menu.js";
18
+ import { type ImagegenSettings, SettingsStore } from "./settings.js";
19
+
20
+ const TOOL_NAME = "codex_imagegen";
21
+ const MESSAGE_TYPE = "codex-imagegen:result";
22
+ const STATUS_KEY = "codex-imagegen";
23
+ const PARAMETERS = Type.Object({
24
+ prompt: Type.String({ minLength: 1, maxLength: MAX_PROMPT_CHARS, description: "Describe one image to generate." }),
25
+ path: Type.String({
26
+ description:
27
+ "Exact destination file path, relative to the session working directory or absolute. Uses write path handling, overwrites existing files, and follows symlinks. No extension is added or changed.",
28
+ }),
29
+ transparentBackground: Type.Optional(
30
+ Type.Boolean({ description: "Request a transparent background instead of the saved default." }),
31
+ ),
32
+ });
33
+ const OUTPUT_SCHEMA = Type.Object({
34
+ path: Type.String(),
35
+ mimeType: Type.String(),
36
+ width: Type.Number(),
37
+ height: Type.Number(),
38
+ requestId: Type.Optional(Type.String()),
39
+ });
40
+
41
+ interface ArtifactDetails {
42
+ path: string;
43
+ mimeType: string;
44
+ width: number;
45
+ height: number;
46
+ requestId?: string;
47
+ }
48
+ interface GeneratedImage extends ArtifactDetails {
49
+ data: string;
50
+ }
51
+ interface SessionState {
52
+ manager: ExtensionContext["sessionManager"];
53
+ controller: AbortController;
54
+ store: SettingsStore;
55
+ busy: boolean;
56
+ menuOpen: boolean;
57
+ ui?: Pick<ExtensionUIContext, "setStatus">;
58
+ active?: Promise<GeneratedImage>;
59
+ menuTask?: Promise<void>;
60
+ runtimeCurrent(): boolean;
61
+ watchers: number;
62
+ watcher?: ReturnType<typeof setInterval>;
63
+ }
64
+ interface Dependencies {
65
+ request: typeof generateImageRequest;
66
+ publish: typeof publishImage;
67
+ menu: typeof showImagegenMenu;
68
+ }
69
+
70
+ /** Only display text is normalized; raw prompts, paths, and result details are retained. */
71
+ export function displayText(value: string): string {
72
+ return stripVTControlCharacters(value).replace(/[\p{Cc}\p{Cf}\p{Cs}]/gu, "");
73
+ }
74
+
75
+ // Bound model-visible text separately from terminal display sanitization.
76
+ function modelText(value: string, fallback: string): string {
77
+ const result = truncateHead(value, { maxBytes: DEFAULT_MAX_BYTES - 128, maxLines: DEFAULT_MAX_LINES - 2 });
78
+ return result.truncated ? `${result.content || fallback}\n[Text truncated.]` : result.content;
79
+ }
80
+
81
+ export function createImagegenExtension(overrides: Partial<Dependencies> = {}) {
82
+ const dependencies: Dependencies = {
83
+ request: generateImageRequest,
84
+ publish: publishImage,
85
+ menu: showImagegenMenu,
86
+ ...overrides,
87
+ };
88
+ return (pi: ExtensionAPI) => {
89
+ const sessions = new Map<ExtensionContext["sessionManager"], SessionState>();
90
+ let current: SessionState | undefined;
91
+ let exposure: boolean | undefined;
92
+ let lifecycleGeneration = 0;
93
+
94
+ const isCurrent = (state: SessionState) =>
95
+ current === state &&
96
+ sessions.get(state.manager) === state &&
97
+ !state.controller.signal.aborted &&
98
+ state.runtimeCurrent();
99
+ const retainOwnership = (state: SessionState) => {
100
+ ++state.watchers;
101
+ if (!state.watcher) {
102
+ // Direct SDK AgentSession.dispose() invalidates public ctx getters without
103
+ // emitting session_shutdown. Poll only while an owned flow is active.
104
+ state.watcher = setInterval(() => {
105
+ if (isCurrent(state)) return;
106
+ state.controller.abort(new DOMException("Image generation runtime disposed", "AbortError"));
107
+ clearInterval(state.watcher);
108
+ state.watcher = undefined;
109
+ }, 100);
110
+ state.watcher.unref();
111
+ }
112
+ let retained = true;
113
+ return () => {
114
+ if (!retained) return;
115
+ retained = false;
116
+ if (--state.watchers === 0) {
117
+ clearInterval(state.watcher);
118
+ state.watcher = undefined;
119
+ }
120
+ };
121
+ };
122
+ const requireState = (ctx: ExtensionContext) => {
123
+ const state = sessions.get(ctx.sessionManager);
124
+ if (!state || !isCurrent(state)) throw new Error("Image generation is unavailable in this session.");
125
+ return state;
126
+ };
127
+ const check = (state: SessionState, signal?: AbortSignal, tool = false) => {
128
+ signal?.throwIfAborted();
129
+ if (!isCurrent(state)) throw new DOMException("Image generation session changed", "AbortError");
130
+ if (tool && !state.store.settings.toolEnabled)
131
+ throw new Error("codex_imagegen is disabled. Enable it in /codex-imagegen Settings.");
132
+ };
133
+
134
+ const generate = (
135
+ ctx: ExtensionContext,
136
+ state: SessionState,
137
+ params: { prompt: string; path: string; transparentBackground?: boolean },
138
+ callerSignal: AbortSignal | undefined,
139
+ tool: boolean,
140
+ ): Promise<GeneratedImage> => {
141
+ check(state, callerSignal, tool);
142
+ if (state.busy) throw new Error("An image generation is already running in this session.");
143
+ const { prompt, path, transparentBackground } = params;
144
+ if (typeof prompt !== "string" || !prompt.trim() || prompt.length > MAX_PROMPT_CHARS)
145
+ throw new Error("Enter an image prompt of 1 to 32000 characters.");
146
+ if (typeof path !== "string") throw new Error("Provide an output path for image generation.");
147
+ const settings = state.store.settings;
148
+ const cwd = ctx.cwd;
149
+ const signal = callerSignal ? AbortSignal.any([state.controller.signal, callerSignal]) : state.controller.signal;
150
+ const ownsRequest = () => isCurrent(state) && !signal.aborted && (!tool || state.store.settings.toolEnabled);
151
+ state.busy = true;
152
+ const releaseOwnership = retainOwnership(state);
153
+ if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, "Generating image");
154
+ const task = (async () => {
155
+ await preflightOutput({
156
+ cwd,
157
+ path,
158
+ signal,
159
+ isCurrent: ownsRequest,
160
+ });
161
+ check(state, signal, tool);
162
+ const response = await dependencies.request(
163
+ ctx.modelRegistry,
164
+ {
165
+ prompt,
166
+ transparentBackground: transparentBackground ?? settings.transparentBackground,
167
+ },
168
+ { signal, isCurrent: ownsRequest },
169
+ );
170
+ check(state, signal, tool);
171
+ const image = decodeImage(response.base64);
172
+ const saved = await dependencies.publish(image, {
173
+ cwd,
174
+ path,
175
+ signal,
176
+ isCurrent: ownsRequest,
177
+ });
178
+ check(state, signal, tool);
179
+ return {
180
+ path: saved.path,
181
+ data: image.bytes.toString("base64"),
182
+ mimeType: image.mimeType,
183
+ width: image.width,
184
+ height: image.height,
185
+ ...(response.requestId ? { requestId: response.requestId } : {}),
186
+ };
187
+ })();
188
+ state.active = task;
189
+ const release = () => {
190
+ if (state.active !== task) return;
191
+ state.active = undefined;
192
+ state.busy = false;
193
+ releaseOwnership();
194
+ if (isCurrent(state) && ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, undefined);
195
+ };
196
+ void task.then(release, release);
197
+ return task;
198
+ };
199
+
200
+ const definition: ToolDefinition<typeof PARAMETERS, ArtifactDetails> = {
201
+ name: TOOL_NAME,
202
+ label: "Codex Image Generation",
203
+ description:
204
+ "Generate one image through the experimental Codex image endpoint using Pi's OpenAI Codex OAuth login. Writes to the required exact path, overwrites existing files, and follows symlinks like write. Consumes account quota. No automatic retries. Image editing is unsupported.",
205
+ parameters: PARAMETERS,
206
+ outputSchema: OUTPUT_SCHEMA,
207
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
208
+ async execute(_id, params, signal, _onUpdate, ctx) {
209
+ try {
210
+ const state = requireState(ctx);
211
+ const result = await generate(ctx, state, params, signal, true);
212
+ check(state, signal, true);
213
+ const { data, ...details } = result;
214
+ return {
215
+ content: [
216
+ { type: "text", text: modelText(`Saved image: ${result.path}`, "Image saved. See the structured path.") },
217
+ { type: "image", data, mimeType: result.mimeType },
218
+ ],
219
+ details,
220
+ structuredContent: details,
221
+ };
222
+ } catch (error) {
223
+ const original = error instanceof Error ? error.message : String(error);
224
+ const bounded = modelText(original, "Image generation failed.");
225
+ if (bounded !== original) throw new Error(bounded);
226
+ throw error;
227
+ }
228
+ },
229
+ renderCall(args, theme) {
230
+ return new Text(
231
+ `${theme.fg("toolTitle", theme.bold("Codex image"))} ${displayText(args.prompt).slice(0, 160)}`,
232
+ 0,
233
+ 0,
234
+ );
235
+ },
236
+ renderResult(result, _options, theme) {
237
+ const path = result.details?.path;
238
+ const errorText = result.content.find((block) => block.type === "text");
239
+ const text = path
240
+ ? `Saved image: ${displayText(path)}`
241
+ : displayText(errorText?.type === "text" ? errorText.text : "Image generation failed.").slice(0, 500);
242
+ return new Text(theme.fg(path ? "success" : "error", text), 0, 0);
243
+ },
244
+ };
245
+ const setExposure = (enabled: boolean, force = false) => {
246
+ if (!force && exposure === enabled) return;
247
+ // Explicit user setting transitions are new prefix epochs. Ordinary turns never change the loadout.
248
+ pi.registerTool({ ...definition, exposure: enabled ? "direct" : "hidden" });
249
+ exposure = enabled;
250
+ };
251
+ setExposure(false);
252
+
253
+ pi.registerMessageRenderer<ArtifactDetails>(MESSAGE_TYPE, (message, _options, theme) => {
254
+ const content = new Container();
255
+ const path = typeof message.details?.path === "string" ? message.details.path : "(path unavailable)";
256
+ content.addChild(new Text(theme.fg("success", `Saved image: ${displayText(path)}`), 0, 0));
257
+ const image =
258
+ typeof message.content === "string" ? undefined : message.content.find((block) => block.type === "image");
259
+ let showImages = false;
260
+ try {
261
+ showImages = pi.getSettings().terminal?.showImages !== false;
262
+ } catch {
263
+ /* Export-only loaders have no active session. */
264
+ }
265
+ if (image?.type === "image" && showImages) {
266
+ content.addChild(new Image(image.data, image.mimeType, { fallbackColor: (text) => theme.fg("muted", text) }));
267
+ }
268
+ return content;
269
+ });
270
+
271
+ const dispose = async (state: SessionState) => {
272
+ if (isCurrent(state)) state.ui?.setStatus(STATUS_KEY, undefined);
273
+ state.controller.abort(new DOMException("Image generation session closed", "AbortError"));
274
+ clearInterval(state.watcher);
275
+ state.watcher = undefined;
276
+ await Promise.allSettled([state.active, state.menuTask, state.store.flush()]);
277
+ if (sessions.get(state.manager) === state) sessions.delete(state.manager);
278
+ if (current === state) current = undefined;
279
+ };
280
+
281
+ pi.on("session_start", async (_event, ctx) => {
282
+ const generation = ++lifecycleGeneration;
283
+ if (current) await dispose(current);
284
+ if (generation !== lifecycleGeneration) return;
285
+ const state: SessionState = {
286
+ manager: ctx.sessionManager,
287
+ controller: new AbortController(),
288
+ store: new SettingsStore(getAgentDir()),
289
+ busy: false,
290
+ menuOpen: false,
291
+ ui: ctx.hasUI ? ctx.ui : undefined,
292
+ watchers: 0,
293
+ runtimeCurrent: () => {
294
+ try {
295
+ return ctx.sessionManager === state.manager;
296
+ } catch {
297
+ return false;
298
+ }
299
+ },
300
+ };
301
+ current = state;
302
+ sessions.set(state.manager, state);
303
+ setExposure(false);
304
+ try {
305
+ const loaded = await state.store.load();
306
+ if (!isCurrent(state)) return;
307
+ setExposure(loaded.settings.toolEnabled);
308
+ if (loaded.warning) {
309
+ if (ctx.hasUI) ctx.ui.notify(loaded.warning, "warning");
310
+ else throw new Error("Invalid image generation settings.");
311
+ }
312
+ } catch {
313
+ if (!isCurrent(state)) return;
314
+ setExposure(false);
315
+ const message = "Could not load valid image generation settings. The tool remains disabled.";
316
+ if (ctx.hasUI) ctx.ui.notify(message, "error");
317
+ else throw new Error(message);
318
+ }
319
+ });
320
+ pi.on("session_shutdown", async (_event, ctx) => {
321
+ ++lifecycleGeneration;
322
+ const state = sessions.get(ctx.sessionManager);
323
+ if (state) await dispose(state);
324
+ });
325
+
326
+ pi.registerCommand("codex-imagegen", {
327
+ description: "Generate images and manage experimental Codex image settings",
328
+ handler: async (args, ctx) => {
329
+ if (args.trim()) throw new Error("/codex-imagegen accepts no arguments. Open its menu without arguments.");
330
+ if (ctx.mode !== "tui") {
331
+ const message =
332
+ "/codex-imagegen requires TUI mode. Edit pi-codex-imagegen.json manually; the enabled codex_imagegen tool also works headlessly.";
333
+ if (ctx.hasUI) {
334
+ ctx.ui.notify(message, "warning");
335
+ return;
336
+ }
337
+ throw new Error(message);
338
+ }
339
+ const state = requireState(ctx);
340
+ if (!ctx.isIdle() || state.busy || state.menuOpen)
341
+ throw new Error("Wait for the current operation before opening /codex-imagegen.");
342
+ state.menuOpen = true;
343
+ const releaseOwnership = retainOwnership(state);
344
+ try {
345
+ const menuTask = dependencies.menu(ctx, {
346
+ signal: state.controller.signal,
347
+ isCurrent: () => isCurrent(state),
348
+ getSettings: () => state.store.settings,
349
+ settingsPath: state.store.path,
350
+ getAuthStatus: () => getImageAuthStatus(ctx.modelRegistry),
351
+ isBusy: () => state.busy,
352
+ saveSettings: async (patch: Partial<ImagegenSettings>) => {
353
+ check(state);
354
+ if (!ctx.isIdle() || state.busy) throw new Error("Settings can change only while the session is idle.");
355
+ await state.store.save(patch, {
356
+ signal: state.controller.signal,
357
+ isCurrent: () => isCurrent(state) && ctx.isIdle() && !state.busy,
358
+ apply: (next) => {
359
+ if (isCurrent(state)) setExposure(next.toolEnabled, true);
360
+ },
361
+ });
362
+ check(state);
363
+ },
364
+ generate: async (prompt, path, signal) => {
365
+ const result = await generate(ctx, state, { prompt, path }, signal, false);
366
+ check(state, signal);
367
+ const { data, ...details } = result;
368
+ const settings = pi.getSettings();
369
+ let image = settings.images?.blockImages
370
+ ? undefined
371
+ : { type: "image" as const, data, mimeType: result.mimeType };
372
+ if (image && settings.images?.autoResize !== false) {
373
+ const resized = await resizeImage(Buffer.from(data, "base64"), result.mimeType);
374
+ check(state, signal);
375
+ if (resized) image = { type: "image", data: resized.data, mimeType: resized.mimeType };
376
+ }
377
+ if (pi.getSettings().images?.blockImages) image = undefined;
378
+ // Append at the tail without starting a model turn. Original image bytes stay on disk.
379
+ pi.sendMessage(
380
+ {
381
+ customType: MESSAGE_TYPE,
382
+ content: [
383
+ {
384
+ type: "text",
385
+ text: modelText(`Saved image: ${result.path}`, "Image saved. See the structured path."),
386
+ },
387
+ ...(image ? [image] : []),
388
+ ],
389
+ details,
390
+ display: true,
391
+ },
392
+ { triggerTurn: false },
393
+ );
394
+ },
395
+ });
396
+ state.menuTask = menuTask;
397
+ await menuTask;
398
+ } finally {
399
+ state.menuTask = undefined;
400
+ state.menuOpen = false;
401
+ releaseOwnership();
402
+ }
403
+ },
404
+ });
405
+ };
406
+ }
407
+
408
+ export default createImagegenExtension();