@kliebhan/pi-prompt-autocomplete 0.1.2 → 0.2.1

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.
Files changed (5) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +43 -6
  3. package/core.ts +670 -26
  4. package/index.ts +577 -68
  5. package/package.json +2 -2
package/core.ts CHANGED
@@ -56,6 +56,7 @@ export const PROMPT_AUTOCOMPLETE_SYSTEM_PROMPT = renderMiniTemplate(
56
56
 
57
57
  export const DEFAULT_PREFERRED_MODEL = "current active model";
58
58
  export const DEFAULT_PROMPT_AUTOCOMPLETE_ENABLED = false;
59
+ export const DEFAULT_STREAM_RESPONSES = true;
59
60
  export const DEFAULT_DEBOUNCE_MS = 350;
60
61
  export const DEFAULT_MIN_PROMPT_CHARS = 1;
61
62
  export const DEFAULT_MAX_SUGGESTION_CHARS = 160;
@@ -86,11 +87,21 @@ export interface PromptAutocompleteCacheIdentity {
86
87
  recentContext: string;
87
88
  }
88
89
 
90
+ export type PromptAutocompletePrefixContextIdentity = Omit<PromptAutocompleteCacheIdentity, "draft">;
91
+
92
+ function hashPromptAutocompleteIdentity(identity: object): string {
93
+ return createHash("sha256").update(JSON.stringify(identity)).digest("hex");
94
+ }
95
+
89
96
  export function buildPromptAutocompleteCacheKey(identity: PromptAutocompleteCacheIdentity): string {
90
- const digest = createHash("sha256")
91
- .update(JSON.stringify(identity))
92
- .digest("hex");
93
- return `${identity.modelLabel}|${digest}`;
97
+ return `${identity.modelLabel}|${hashPromptAutocompleteIdentity(identity)}`;
98
+ }
99
+
100
+ /** Identify every request discriminator except the evolving prompt draft. */
101
+ export function buildPromptAutocompletePrefixContextKey(
102
+ identity: PromptAutocompletePrefixContextIdentity,
103
+ ): string {
104
+ return `${identity.modelLabel}|prefix|${hashPromptAutocompleteIdentity(identity)}`;
94
105
  }
95
106
 
96
107
  export class ExpiringLruCache<T> {
@@ -125,12 +136,25 @@ export class ExpiringLruCache<T> {
125
136
  return entry.value;
126
137
  }
127
138
 
128
- set(key: string, value: T): void {
139
+ set(key: string, value: T, options: { expiresAt?: number } = {}): void {
140
+ const now = this.now();
141
+ const expiresAt = options.expiresAt ?? now + this.ttlMs;
129
142
  this.entries.delete(key);
130
- this.entries.set(key, { value, expiresAt: this.now() + this.ttlMs });
143
+ if (expiresAt <= now) return;
144
+ this.entries.set(key, { value, expiresAt });
131
145
  this.prune();
132
146
  }
133
147
 
148
+ getExpiration(key: string): number | undefined {
149
+ const entry = this.entries.get(key);
150
+ if (!entry) return undefined;
151
+ if (entry.expiresAt <= this.now()) {
152
+ this.entries.delete(key);
153
+ return undefined;
154
+ }
155
+ return entry.expiresAt;
156
+ }
157
+
134
158
  clear(): void {
135
159
  this.entries.clear();
136
160
  }
@@ -173,10 +197,13 @@ export class SequenceOwnedSlot<T extends { seq: number }> {
173
197
  }
174
198
  }
175
199
 
176
- export interface CoalescedRequestEntry<T> {
200
+ export interface CoalescedRequestEntry<T, P = never> {
177
201
  promise: Promise<T>;
178
202
  controller: AbortController;
179
- subscribers: Set<string>;
203
+ subscribers: Set<symbol>;
204
+ progressSubscribers: Map<symbol, (progress: P) => void>;
205
+ latestProgress?: P;
206
+ hasProgress: boolean;
180
207
  settled: boolean;
181
208
  }
182
209
 
@@ -218,29 +245,47 @@ export function createOwnerRefCounter(): OwnerRefCounter {
218
245
  };
219
246
  }
220
247
 
221
- export function acquireCoalescedRequest<T>(
222
- inFlightRequests: Map<string, CoalescedRequestEntry<T>>,
248
+ export function acquireCoalescedRequest<T, P = never>(
249
+ inFlightRequests: Map<string, CoalescedRequestEntry<T, P>>,
223
250
  key: string,
224
251
  subscriberId: string,
225
- start: (signal: AbortSignal) => Promise<T>,
252
+ start: (signal: AbortSignal, publish: (progress: P) => void) => Promise<T>,
253
+ onProgress?: (progress: P) => void,
226
254
  ): CoalescedRequestSubscription<T> {
227
255
  let entry = inFlightRequests.get(key);
228
256
  let created = false;
257
+ let runStart: (() => void) | undefined;
229
258
 
230
259
  if (!entry) {
231
260
  const controller = new AbortController();
232
- const subscribers = new Set<string>();
233
- let runStart: () => void = () => undefined;
261
+ const subscribers = new Set<symbol>();
262
+ const progressSubscribers = new Map<symbol, (progress: P) => void>();
234
263
  const promise = new Promise<T>((resolve, reject) => {
235
264
  runStart = () => {
236
265
  try {
237
- Promise.resolve(start(controller.signal)).then(resolve, reject);
266
+ Promise.resolve(
267
+ start(controller.signal, (progress) => {
268
+ if (!entry) return;
269
+ entry.latestProgress = progress;
270
+ entry.hasProgress = true;
271
+ // Snapshot the callbacks so one subscriber may release itself
272
+ // without skipping another subscriber. A UI callback must never
273
+ // turn a successful provider request into a failed shared request.
274
+ for (const callback of [...entry.progressSubscribers.values()]) {
275
+ try {
276
+ callback(progress);
277
+ } catch {
278
+ // Subscriber failures are isolated from the shared request.
279
+ }
280
+ }
281
+ }),
282
+ ).then(resolve, reject);
238
283
  } catch (error) {
239
284
  reject(error);
240
285
  }
241
286
  };
242
287
  });
243
- let entryForFinally: CoalescedRequestEntry<T> | undefined;
288
+ let entryForFinally: CoalescedRequestEntry<T, P> | undefined;
244
289
  const settledPromise = promise.finally(() => {
245
290
  if (!entryForFinally) return;
246
291
  entryForFinally.settled = true;
@@ -248,9 +293,11 @@ export function acquireCoalescedRequest<T>(
248
293
  inFlightRequests.delete(key);
249
294
  }
250
295
  });
251
- const nextEntry: CoalescedRequestEntry<T> = {
296
+ const nextEntry: CoalescedRequestEntry<T, P> = {
252
297
  controller,
253
298
  subscribers,
299
+ progressSubscribers,
300
+ hasProgress: false,
254
301
  settled: false,
255
302
  promise: settledPromise,
256
303
  };
@@ -259,14 +306,28 @@ export function acquireCoalescedRequest<T>(
259
306
  entry = nextEntry;
260
307
  inFlightRequests.set(key, entry);
261
308
  created = true;
262
- // Start only after the entry is visible in the map, so synchronous start
263
- // failures still settle through the shared promise and clean up the map.
264
- runStart();
265
309
  }
266
310
 
267
- entry.subscribers.add(subscriberId);
268
- let released = false;
311
+ // A symbol makes subscriptions collision-proof even if two editor instances
312
+ // happen to produce the same human-readable activation/sequence label.
313
+ const subscriberToken = Symbol(subscriberId);
314
+ entry.subscribers.add(subscriberToken);
315
+ if (onProgress) {
316
+ entry.progressSubscribers.set(subscriberToken, onProgress);
317
+ if (entry.hasProgress) {
318
+ try {
319
+ onProgress(entry.latestProgress as P);
320
+ } catch {
321
+ // Replay has the same isolation contract as live progress.
322
+ }
323
+ }
324
+ }
325
+
326
+ // Start only after the first subscriber is registered, so synchronous
327
+ // progress cannot race past it. The entry is already visible for coalescing.
328
+ runStart?.();
269
329
 
330
+ let released = false;
270
331
  return {
271
332
  promise: entry.promise,
272
333
  created,
@@ -277,10 +338,11 @@ export function acquireCoalescedRequest<T>(
277
338
  if (released) return;
278
339
  released = true;
279
340
 
341
+ entry?.subscribers.delete(subscriberToken);
342
+ entry?.progressSubscribers.delete(subscriberToken);
343
+
280
344
  const current = inFlightRequests.get(key);
281
345
  if (current !== entry) return;
282
-
283
- current.subscribers.delete(subscriberId);
284
346
  if (current.subscribers.size === 0 && !current.settled) {
285
347
  current.controller.abort();
286
348
  inFlightRequests.delete(key);
@@ -289,7 +351,7 @@ export function acquireCoalescedRequest<T>(
289
351
  };
290
352
  }
291
353
 
292
- export function cancelAllCoalescedRequests<T>(inFlightRequests: Map<string, CoalescedRequestEntry<T>>): void {
354
+ export function cancelAllCoalescedRequests<T, P>(inFlightRequests: Map<string, CoalescedRequestEntry<T, P>>): void {
293
355
  for (const entry of inFlightRequests.values()) {
294
356
  if (!entry.settled) {
295
357
  entry.controller.abort();
@@ -298,6 +360,243 @@ export function cancelAllCoalescedRequests<T>(inFlightRequests: Map<string, Coal
298
360
  inFlightRequests.clear();
299
361
  }
300
362
 
363
+ /**
364
+ * Session-scoped autocomplete accounting.
365
+ *
366
+ * Counters are deliberately in-memory and per-session: they exist so a user can
367
+ * answer "what did autocomplete cost me", not to build a usage history.
368
+ *
369
+ * Token counts come from the provider. The cost figure does not: pi derives it
370
+ * locally by multiplying those tokens with its own model price table
371
+ * (`calculateCost` in @earendil-works/pi-ai), so it is an estimate that can
372
+ * disagree with an actual invoice. Naming reflects that.
373
+ */
374
+ export interface PromptAutocompleteUsageStats {
375
+ /** Provider calls actually issued, including calls that later failed. */
376
+ providerRequests: number;
377
+ /** Issued calls that produced no usable suggestions because of an error or abort. */
378
+ failedRequests: number;
379
+ /** Requests served from the local cache without contacting a provider. */
380
+ cacheHits: number;
381
+ /** Cache hits obtained by consuming a prefix of a previous suggestion. */
382
+ prefixReuseHits: number;
383
+ /** Active ghost-text suggestions offered to the editor. */
384
+ suggestionsOffered: number;
385
+ /** Full-suggestion accept actions, including visible streamed partials. */
386
+ fullAccepts: number;
387
+ /** Word/chunk accept actions, including visible streamed partials. */
388
+ chunkAccepts: number;
389
+ /** Provider calls with a measured completion or rejection latency. */
390
+ latencySamples: number;
391
+ /** Sum used to derive mean provider latency without retaining request history. */
392
+ totalLatencyMs: number;
393
+ /** Responses that carried token counts. Totals are partial when this is below providerRequests. */
394
+ tokenReports: number;
395
+ /** Responses that carried a cost figure. */
396
+ costReports: number;
397
+ totalTokens: number;
398
+ /** Locally estimated cost, summed from pi's model price table. */
399
+ estimatedCost: number;
400
+ }
401
+
402
+ /** Shape of the usage report this module consumes. Every field is optional at runtime. */
403
+ export interface ProviderUsageReport {
404
+ input?: number;
405
+ output?: number;
406
+ cacheRead?: number;
407
+ cacheWrite?: number;
408
+ totalTokens?: number;
409
+ cost?: { total?: number };
410
+ }
411
+
412
+ export function createPromptAutocompleteUsageStats(): PromptAutocompleteUsageStats {
413
+ return {
414
+ providerRequests: 0,
415
+ failedRequests: 0,
416
+ cacheHits: 0,
417
+ prefixReuseHits: 0,
418
+ suggestionsOffered: 0,
419
+ fullAccepts: 0,
420
+ chunkAccepts: 0,
421
+ latencySamples: 0,
422
+ totalLatencyMs: 0,
423
+ tokenReports: 0,
424
+ costReports: 0,
425
+ totalTokens: 0,
426
+ estimatedCost: 0,
427
+ };
428
+ }
429
+
430
+ interface NumericField {
431
+ /** Whether the field carried a usable number. Zero counts; malformed does not. */
432
+ present: boolean;
433
+ value: number;
434
+ }
435
+
436
+ const MISSING_FIELD: NumericField = { present: false, value: 0 };
437
+
438
+ /**
439
+ * Read one numeric field exactly once, without trusting the object.
440
+ *
441
+ * The usage object is plain data in practice, but a throwing getter must not be
442
+ * able to turn accounting into a failed suggestion, and a side-effecting getter
443
+ * must not be able to report one value to the total and another to the
444
+ * completeness check. Zero is a legitimate report; negative and non-finite
445
+ * values are malformed and count as missing.
446
+ */
447
+ function readNumericField(source: Record<string, unknown> | undefined, key: string): NumericField {
448
+ if (!source) return MISSING_FIELD;
449
+
450
+ let value: unknown;
451
+ try {
452
+ value = source[key];
453
+ } catch {
454
+ return MISSING_FIELD;
455
+ }
456
+
457
+ if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return MISSING_FIELD;
458
+ return { present: true, value };
459
+ }
460
+
461
+ function readCostRecord(usage: Record<string, unknown>): Record<string, unknown> | undefined {
462
+ let cost: unknown;
463
+ try {
464
+ cost = usage.cost;
465
+ } catch {
466
+ return undefined;
467
+ }
468
+
469
+ return typeof cost === "object" && cost !== null ? (cost as Record<string, unknown>) : undefined;
470
+ }
471
+
472
+ /**
473
+ * Fold one usage report into the session totals.
474
+ *
475
+ * Providers disagree about which fields they populate, so each field is
476
+ * optional. Token and cost reports are counted separately because a response
477
+ * can carry tokens without a cost figure. An explicit total wins over the
478
+ * component fields; otherwise the components are summed, including cached
479
+ * tokens, which are billed as well.
480
+ */
481
+ export function recordProviderUsage(stats: PromptAutocompleteUsageStats, usage: unknown): void {
482
+ if (typeof usage !== "object" || usage === null) return;
483
+
484
+ const report = usage as Record<string, unknown>;
485
+ const costRecord = readCostRecord(report);
486
+
487
+ const reportedTotal = readNumericField(report, "totalTokens");
488
+ const components = [
489
+ readNumericField(report, "input"),
490
+ readNumericField(report, "output"),
491
+ readNumericField(report, "cacheRead"),
492
+ readNumericField(report, "cacheWrite"),
493
+ ];
494
+ const cost = readNumericField(costRecord, "total");
495
+
496
+ const hasTokenReport = reportedTotal.present || components.some((field) => field.present);
497
+ if (!hasTokenReport && !cost.present) return;
498
+
499
+ if (hasTokenReport) stats.tokenReports += 1;
500
+ if (cost.present) stats.costReports += 1;
501
+
502
+ stats.totalTokens += reportedTotal.present
503
+ ? reportedTotal.value
504
+ : components.reduce((sum, field) => sum + field.value, 0);
505
+ stats.estimatedCost += cost.value;
506
+ }
507
+
508
+ function formatEstimatedCost(cost: number): string {
509
+ if (cost <= 0) return "$0";
510
+ // Autocomplete requests are cheap; a real cost must never render as $0.
511
+ if (cost < 0.00001) return "<$0.00001";
512
+ return cost < 0.01 ? `$${cost.toFixed(5)}` : `$${cost.toFixed(4)}`;
513
+ }
514
+
515
+ export function recordProviderLatency(stats: PromptAutocompleteUsageStats, elapsedMs: number): void {
516
+ if (!Number.isFinite(elapsedMs) || elapsedMs < 0) return;
517
+ stats.latencySamples += 1;
518
+ stats.totalLatencyMs += elapsedMs;
519
+ }
520
+
521
+ function formatUsageTotals(stats: PromptAutocompleteUsageStats): string {
522
+ const tokensPartial = stats.tokenReports < stats.providerRequests;
523
+ const costPartial = stats.costReports < stats.providerRequests;
524
+ return [
525
+ `${stats.totalTokens} tok${tokensPartial ? "+" : ""}`,
526
+ `~${formatEstimatedCost(stats.estimatedCost)} est${costPartial ? "+" : ""}`,
527
+ ].join(", ");
528
+ }
529
+
530
+ function formatDetailedUsageTotals(stats: PromptAutocompleteUsageStats): string {
531
+ const tokensPartial = stats.tokenReports < stats.providerRequests;
532
+ const costPartial = stats.costReports < stats.providerRequests;
533
+ const tokenUnit = stats.totalTokens === 1 ? "token" : "tokens";
534
+ return [
535
+ `${stats.totalTokens} ${tokenUnit}${tokensPartial ? "+" : ""}`,
536
+ `estimated cost ~${formatEstimatedCost(stats.estimatedCost)}${costPartial ? "+" : ""}`,
537
+ ].join(", ");
538
+ }
539
+
540
+ /**
541
+ * Render session accounting for the status line.
542
+ *
543
+ * Cost is labelled as an estimate because pi derives it from a local price
544
+ * table rather than from the provider. Totals are marked partial when some
545
+ * responses reported nothing, so silence is never shown as a cheaper request.
546
+ */
547
+ export function formatUsageStats(stats: PromptAutocompleteUsageStats): string {
548
+ const segments = [`${stats.providerRequests} req`, `${stats.cacheHits} cached`];
549
+
550
+ if (stats.failedRequests > 0) {
551
+ segments.push(`${stats.failedRequests} failed`);
552
+ }
553
+
554
+ segments.push(formatUsageTotals(stats));
555
+ return segments.join(", ");
556
+ }
557
+
558
+ /** Render the reachable, user-facing metrics for the current session. */
559
+ export function formatPromptAutocompleteStats(stats: PromptAutocompleteUsageStats): string {
560
+ const exactCacheHits = Math.max(0, stats.cacheHits - stats.prefixReuseHits);
561
+ const accepts = stats.fullAccepts + stats.chunkAccepts;
562
+ const meanLatency = stats.latencySamples > 0
563
+ ? `${Math.round(stats.totalLatencyMs / stats.latencySamples)} ms (${stats.latencySamples} sample${stats.latencySamples === 1 ? "" : "s"})`
564
+ : "n/a";
565
+
566
+ return [
567
+ "Prompt Autocomplete — current session",
568
+ `Requests: ${stats.providerRequests} issued, ${stats.failedRequests} failed`,
569
+ `Cache: ${stats.cacheHits} hits (${exactCacheHits} exact, ${stats.prefixReuseHits} prefix)`,
570
+ `Suggestions: ${stats.suggestionsOffered} offered, ${accepts} accepted (${stats.fullAccepts} full, ${stats.chunkAccepts} word/chunk)`,
571
+ `Usage: ${formatDetailedUsageTotals(stats)}`,
572
+ `Mean provider latency: ${meanLatency}`,
573
+ ].join("\n");
574
+ }
575
+
576
+ /**
577
+ * Runtime overrides set by slash commands.
578
+ *
579
+ * These outrank CLI flags for the lifetime of the process. An unset field means
580
+ * "defer to the flag", which is what lets a new session pick up a changed flag
581
+ * while still honouring an explicit in-session decision.
582
+ */
583
+ export interface PromptAutocompleteRuntimeOverrides {
584
+ enabled?: boolean;
585
+ allowWhileStreaming?: boolean;
586
+ streamResponses?: boolean;
587
+ debug?: boolean;
588
+ }
589
+
590
+ export type PromptAutocompleteSettingSource = "flag" | "session";
591
+
592
+ export function resolveOverride<T>(override: T | undefined, flagValue: T): T {
593
+ return override ?? flagValue;
594
+ }
595
+
596
+ export function describeSettingSource(override: unknown): PromptAutocompleteSettingSource {
597
+ return override === undefined ? "flag" : "session";
598
+ }
599
+
301
600
  interface SuggestionPayload {
302
601
  completions?: unknown;
303
602
  suggestions?: unknown;
@@ -316,6 +615,31 @@ function trimAndCollapse(text: string): string {
316
615
  return text.trim().replace(/\s+/g, " ");
317
616
  }
318
617
 
618
+ function stripUnsafeTerminalControls(text: string): string {
619
+ // Keep tab/newline because multiline suggestions intentionally support both.
620
+ // Everything else in C0/C1 can alter terminal state (ESC/CSI/OSC), move the
621
+ // cursor, or hide text and must never reach the renderer.
622
+ return text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, "");
623
+ }
624
+
625
+ function truncateAtFirstUnpairedSurrogate(text: string): string {
626
+ for (let index = 0; index < text.length; index += 1) {
627
+ const code = text.charCodeAt(index);
628
+ if (code >= 0xD800 && code <= 0xDBFF) {
629
+ const next = text.charCodeAt(index + 1);
630
+ if (next >= 0xDC00 && next <= 0xDFFF) {
631
+ index += 1;
632
+ continue;
633
+ }
634
+ return text.slice(0, index);
635
+ }
636
+ if (code >= 0xDC00 && code <= 0xDFFF) {
637
+ return text.slice(0, index);
638
+ }
639
+ }
640
+ return text;
641
+ }
642
+
319
643
  function truncateWithEllipsis(text: string, maxChars: number): string {
320
644
  if (text.length <= maxChars) return text;
321
645
  if (maxChars <= 1) return "…";
@@ -738,6 +1062,206 @@ function salvageTruncatedJsonSuggestions(text: string): string[] {
738
1062
  return [];
739
1063
  }
740
1064
 
1065
+ interface StreamingJsonString {
1066
+ value: string;
1067
+ complete: boolean;
1068
+ }
1069
+
1070
+ /** Decode only the complete part of an unterminated JSON string literal. */
1071
+ function readStreamingJsonString(text: string, startIndex: number): StreamingJsonString | undefined {
1072
+ if (text[startIndex] !== '"') return undefined;
1073
+
1074
+ const complete = readJsonStringLiteral(text, startIndex);
1075
+ if (complete) return { value: complete.value, complete: true };
1076
+
1077
+ let safeEnd = startIndex + 1;
1078
+ let i = safeEnd;
1079
+ while (i < text.length) {
1080
+ const char = text[i];
1081
+ if (char === '"') break;
1082
+ if (char === "\\") {
1083
+ const escaped = text[i + 1];
1084
+ if (escaped === undefined) break;
1085
+ if (escaped === "u") {
1086
+ const digits = text.slice(i + 2, i + 6);
1087
+ if (!/^[0-9a-fA-F]{4}$/.test(digits)) break;
1088
+ i += 6;
1089
+ safeEnd = i;
1090
+ continue;
1091
+ }
1092
+ if (!/["\\/bfnrt]/.test(escaped)) break;
1093
+ i += 2;
1094
+ safeEnd = i;
1095
+ continue;
1096
+ }
1097
+ // Raw control characters are invalid inside JSON strings. Do not turn a
1098
+ // malformed response into editor text just because the stream is partial.
1099
+ if (char.charCodeAt(0) < 0x20) break;
1100
+ i += 1;
1101
+ safeEnd = i;
1102
+ }
1103
+
1104
+ try {
1105
+ const parsed = JSON.parse(`${text.slice(startIndex, safeEnd)}"`) as unknown;
1106
+ if (typeof parsed !== "string") return undefined;
1107
+ // A provider chunk may split a UTF-16 surrogate pair. Truncate at the first
1108
+ // unmatched half even when more decoded characters follow it.
1109
+ const value = truncateAtFirstUnpairedSurrogate(parsed);
1110
+ return { value, complete: false };
1111
+ } catch {
1112
+ return undefined;
1113
+ }
1114
+ }
1115
+
1116
+ function readFirstStreamingArrayString(text: string, startIndex: number): StreamingJsonString | undefined {
1117
+ let i = startIndex;
1118
+ while (i < text.length) {
1119
+ i = skipJsonWhitespace(text, i);
1120
+ if (text[i] === ",") {
1121
+ i += 1;
1122
+ continue;
1123
+ }
1124
+ if (text[i] === "]") return undefined;
1125
+ if (text[i] === '"') return readStreamingJsonString(text, i);
1126
+
1127
+ const skipped = skipJsonValue(text, i);
1128
+ if (!skipped.complete || skipped.end <= i) return undefined;
1129
+ i = skipped.end;
1130
+ }
1131
+ return undefined;
1132
+ }
1133
+
1134
+ function findFirstStreamingSuggestion(text: string): StreamingJsonString | undefined {
1135
+ const stripped = stripCodeFences(text).trim();
1136
+ if (stripped.startsWith("[")) {
1137
+ return readFirstStreamingArrayString(stripped, 1);
1138
+ }
1139
+
1140
+ let i = 0;
1141
+ while (i < stripped.length) {
1142
+ if (stripped[i] !== "{") {
1143
+ i += 1;
1144
+ continue;
1145
+ }
1146
+
1147
+ const starts = findTopLevelSuggestionArrayStartsInObject(stripped, i);
1148
+ for (const key of SUGGESTION_ARRAY_KEYS) {
1149
+ const start = starts[key];
1150
+ if (typeof start !== "number") continue;
1151
+ return readFirstStreamingArrayString(stripped, start);
1152
+ }
1153
+
1154
+ const skipped = skipJsonValue(stripped, i);
1155
+ i = skipped.complete && skipped.end > i ? skipped.end : i + 1;
1156
+ }
1157
+
1158
+ return undefined;
1159
+ }
1160
+
1161
+ const STREAMING_GRAPHEME_SEGMENTER = (() => {
1162
+ if (typeof Intl.Segmenter !== "function") return undefined;
1163
+ try {
1164
+ return new Intl.Segmenter(undefined, { granularity: "grapheme" });
1165
+ } catch {
1166
+ return undefined;
1167
+ }
1168
+ })();
1169
+
1170
+ function dropLastGrapheme(text: string): string {
1171
+ if (!STREAMING_GRAPHEME_SEGMENTER) {
1172
+ // Safety over partial UX on minimal-ICU builds: without a grapheme
1173
+ // segmenter we cannot prove that a ZWJ/combining sequence is complete.
1174
+ return "";
1175
+ }
1176
+ const segments = [...STREAMING_GRAPHEME_SEGMENTER.segment(text)];
1177
+ const last = segments.at(-1);
1178
+ return last ? text.slice(0, last.index) : "";
1179
+ }
1180
+
1181
+ function truncateSuggestionAtGraphemeBoundary(text: string, maxChars: number): string {
1182
+ if (text.length <= maxChars) return text;
1183
+ if (maxChars <= 0) return "";
1184
+ if (maxChars === 1) return "…";
1185
+
1186
+ if (!STREAMING_GRAPHEME_SEGMENTER) {
1187
+ // Do not guess a UTF-16/code-point boundary on minimal-ICU builds. A single
1188
+ // ellipsis is bounded and cannot split an unknown grapheme cluster.
1189
+ return "…";
1190
+ }
1191
+
1192
+ const available = maxChars - 1;
1193
+ let end = 0;
1194
+ for (const segment of STREAMING_GRAPHEME_SEGMENTER.segment(text)) {
1195
+ const nextEnd = segment.index + segment.segment.length;
1196
+ if (nextEnd > available) break;
1197
+ end = nextEnd;
1198
+ }
1199
+ return `${text.slice(0, end)}…`;
1200
+ }
1201
+
1202
+ function completedStreamingPrefix(text: string): string {
1203
+ const safe = dropLastGrapheme(text);
1204
+ if (!safe) return "";
1205
+
1206
+ // Any whitespace-delimited language advances only after a full chunk. This
1207
+ // covers accented Latin text as well as ASCII and avoids treating one accent
1208
+ // as evidence that the unfinished word is a no-space script.
1209
+ let boundaryEnd = 0;
1210
+ for (const match of safe.matchAll(/\S\s+/gu)) {
1211
+ boundaryEnd = (match.index ?? 0) + match[0].length;
1212
+ }
1213
+ if (boundaryEnd > 0) return safe.slice(0, boundaryEnd);
1214
+ if (/\s/u.test(safe)) return "";
1215
+
1216
+ // Scripts that conventionally omit spaces can still advance one complete
1217
+ // grapheme behind. Require the whole prefix to be made from those scripts or
1218
+ // symbols, so an emoji followed by a partial Latin word does not leak it.
1219
+ return /^[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}\p{Extended_Pictographic}\p{Regional_Indicator}\p{M}\p{P}\p{S}\u200D]+$/u.test(safe)
1220
+ ? safe
1221
+ : "";
1222
+ }
1223
+
1224
+ function unresolvedNormalizationPrefix(draft: string, suggestion: string): boolean {
1225
+ const trimmedStart = suggestion.replace(/^[ \t]+/, "");
1226
+ const comparable = trimmedStart.trimEnd();
1227
+ if (!comparable) return true;
1228
+
1229
+ // The final normalizer removes repeated draft/current-word prefixes. Wait
1230
+ // until the model has emitted enough text for that transformation to settle.
1231
+ if (draft.toLocaleLowerCase().startsWith(comparable.toLocaleLowerCase())) return true;
1232
+ const currentWord = getTrailingWordFragment(draft);
1233
+ if (currentWord.toLocaleLowerCase().startsWith(comparable.toLocaleLowerCase())) return true;
1234
+
1235
+ // Wrapping quotes, fences, and labels are removed only once their closing
1236
+ // syntax arrives. Publishing them early would force the ghost text to shrink.
1237
+ if (/^["'`]/.test(trimmedStart)) return true;
1238
+ if (/^(?:continuation|completion|suggestion)\s*:?[ \t]*$/i.test(trimmedStart)) return true;
1239
+ return false;
1240
+ }
1241
+
1242
+ /**
1243
+ * Parse the first model suggestion from an in-progress JSON response.
1244
+ *
1245
+ * Only structured suggestion arrays are eligible, so partial JSON/prose can
1246
+ * never leak into the editor. Incomplete strings are held one grapheme behind;
1247
+ * ASCII text additionally waits for a completed whitespace-delimited chunk.
1248
+ */
1249
+ export function parsePartialPromptSuggestion(
1250
+ draft: string,
1251
+ rawResponse: string,
1252
+ maxChars = DEFAULT_MAX_SUGGESTION_CHARS,
1253
+ ): string | undefined {
1254
+ const parsed = findFirstStreamingSuggestion(rawResponse);
1255
+ if (!parsed) return undefined;
1256
+
1257
+ const candidate = parsed.complete ? parsed.value : completedStreamingPrefix(parsed.value);
1258
+ if (!candidate || (!parsed.complete && unresolvedNormalizationPrefix(draft, candidate))) {
1259
+ return undefined;
1260
+ }
1261
+
1262
+ return normalizePromptSuggestion(draft, candidate, maxChars);
1263
+ }
1264
+
741
1265
  function toStringArray(value: unknown): string[] {
742
1266
  if (!Array.isArray(value)) return [];
743
1267
  return value.filter((item): item is string => typeof item === "string");
@@ -966,7 +1490,7 @@ export function normalizePromptSuggestion(
966
1490
  rawSuggestion: string,
967
1491
  maxChars = DEFAULT_MAX_SUGGESTION_CHARS,
968
1492
  ): string | undefined {
969
- let suggestion = rawSuggestion.replace(/\r/g, "");
1493
+ let suggestion = stripUnsafeTerminalControls(truncateAtFirstUnpairedSurrogate(rawSuggestion)).replace(/\r/g, "");
970
1494
  if (!suggestion.trim()) return undefined;
971
1495
  if (/^<NO_COMPLETION>$/i.test(suggestion.trim())) return undefined;
972
1496
 
@@ -983,7 +1507,7 @@ export function normalizePromptSuggestion(
983
1507
 
984
1508
  suggestion = normalizeLeadingBoundarySpacing(draft, suggestion);
985
1509
  suggestion = maybePrefixSpace(draft, suggestion);
986
- suggestion = truncateWithEllipsis(suggestion, maxChars);
1510
+ suggestion = truncateSuggestionAtGraphemeBoundary(suggestion, maxChars);
987
1511
 
988
1512
  if (!suggestion.trim()) return undefined;
989
1513
  return suggestion;
@@ -1009,6 +1533,75 @@ export function normalizePromptSuggestions(
1009
1533
  return normalized;
1010
1534
  }
1011
1535
 
1536
+ export interface PromptAutocompletePrefixReuseResult {
1537
+ /** Suggestions normalized for the extended draft. */
1538
+ suggestions: string[];
1539
+ /** Original cached suggestions, parallel to `suggestions`, for selection continuity. */
1540
+ origins: string[];
1541
+ }
1542
+
1543
+ function isSafeConsumedSuggestionPrefix(
1544
+ cachedDraft: string,
1545
+ suggestion: string,
1546
+ consumedLength: number,
1547
+ ): boolean {
1548
+ if (consumedLength <= 0 || consumedLength > suggestion.length) return false;
1549
+
1550
+ const target = cachedDraft + suggestion;
1551
+ const boundary = cachedDraft.length + consumedLength;
1552
+ if (!STREAMING_GRAPHEME_SEGMENTER) {
1553
+ // Minimal-ICU fallback: accept only a newly consumed ASCII prefix that is
1554
+ // not followed by a combining/variation/joining code point. For richer
1555
+ // text, decline reuse rather than guess across the draft/suggestion seam.
1556
+ const consumed = suggestion.slice(0, consumedLength);
1557
+ const remainder = suggestion.slice(consumedLength);
1558
+ return /^[\x00-\x7F]*$/.test(consumed) && !/^[\p{M}\u200D]/u.test(remainder);
1559
+ }
1560
+
1561
+ if (boundary === target.length) return true;
1562
+ // `containing` asks ICU for the segment at the seam without materializing or
1563
+ // walking every grapheme in an arbitrarily long draft.
1564
+ return STREAMING_GRAPHEME_SEGMENTER.segment(target).containing(boundary)?.index === boundary;
1565
+ }
1566
+
1567
+ /**
1568
+ * Reuse terminal cached suggestions when the draft only consumed their prefix.
1569
+ *
1570
+ * Matching is deliberately exact and forward-only. Cached origins have already
1571
+ * passed the production normalizer; slicing them directly preserves the target
1572
+ * exactly. Re-running model-response heuristics on a suffix could delete a
1573
+ * legitimate repeated word or alter punctuation/indentation.
1574
+ */
1575
+ export function reusePromptAutocompleteSuggestions(
1576
+ cachedDraft: string,
1577
+ currentDraft: string,
1578
+ cachedSuggestions: readonly string[],
1579
+ maxChars = DEFAULT_MAX_SUGGESTION_CHARS,
1580
+ maxAlternatives = DEFAULT_MAX_ALTERNATIVES,
1581
+ ): PromptAutocompletePrefixReuseResult | undefined {
1582
+ if (currentDraft.length <= cachedDraft.length || !currentDraft.startsWith(cachedDraft)) {
1583
+ return undefined;
1584
+ }
1585
+
1586
+ const consumed = currentDraft.slice(cachedDraft.length);
1587
+ const suggestions: string[] = [];
1588
+ const origins: string[] = [];
1589
+
1590
+ for (const origin of cachedSuggestions) {
1591
+ if (!origin.startsWith(consumed)) continue;
1592
+ if (!isSafeConsumedSuggestionPrefix(cachedDraft, origin, consumed.length)) continue;
1593
+
1594
+ const suggestion = truncateSuggestionAtGraphemeBoundary(origin.slice(consumed.length), maxChars);
1595
+ if (!suggestion.trim() || suggestions.includes(suggestion)) continue;
1596
+
1597
+ suggestions.push(suggestion);
1598
+ origins.push(origin);
1599
+ if (suggestions.length >= maxAlternatives) break;
1600
+ }
1601
+
1602
+ return suggestions.length > 0 ? { suggestions, origins } : undefined;
1603
+ }
1604
+
1012
1605
  export function extractNextSuggestionChunk(suggestion: string): string | undefined {
1013
1606
  if (!suggestion) return undefined;
1014
1607
 
@@ -1036,3 +1629,54 @@ export function formatModelLabel(model: Model<Api> | undefined): string {
1036
1629
  if (!model) return "none";
1037
1630
  return `${model.provider}/${model.id}`;
1038
1631
  }
1632
+
1633
+ /**
1634
+ * Host capabilities needed to decide whether an interactive editor slot exists.
1635
+ *
1636
+ * Pi exposes `ExtensionContext.mode`. Forks of the Pi extension API (for
1637
+ * example prime-agent, which is based on an older API revision) ship
1638
+ * `hasUI` without `mode`.
1639
+ */
1640
+ export interface EditorHostCapabilities {
1641
+ /** `ExtensionContext.mode` when the host provides it. */
1642
+ mode?: unknown;
1643
+ /** `ExtensionContext.hasUI` when the host provides it. */
1644
+ hasUI?: unknown;
1645
+ /** Whether the host exposes a usable custom-editor slot. */
1646
+ canInstallEditor?: unknown;
1647
+ }
1648
+
1649
+ /**
1650
+ * Decide whether the host runs an interactive terminal editor.
1651
+ *
1652
+ * A host that reports `mode` is authoritative: only `"tui"` may own the editor,
1653
+ * so `rpc`, `json`, and `print` stay excluded exactly as before. Only a host
1654
+ * that omits `mode` entirely is treated as a forked API revision, and then only
1655
+ * when it reports UI availability *and* exposes the custom-editor slot. Any
1656
+ * other reported value, including `null`, fails closed.
1657
+ *
1658
+ * Capabilities alone cannot prove that a host really installs custom editors:
1659
+ * some forks expose a no-op editor slot in headless front-ends. The caller must
1660
+ * still verify the installation after mounting.
1661
+ */
1662
+ export function isInteractiveEditorHost(host: EditorHostCapabilities): boolean {
1663
+ if (typeof host.mode === "string") return host.mode === "tui";
1664
+ if (host.mode !== undefined) return false;
1665
+ return host.hasUI === true && host.canInstallEditor === true;
1666
+ }
1667
+
1668
+ /**
1669
+ * Whether streamed responses can be requested from the host's pi-ai module.
1670
+ *
1671
+ * A host that exposes the simple completion API without `streamSimple` must use
1672
+ * the completion path instead of failing every request. When the module exposes
1673
+ * neither function the extension is not running inside a host that maps them,
1674
+ * so streaming support stays unknown and is reported only once a request runs.
1675
+ */
1676
+ export function hostSupportsStreamedResponses(api: {
1677
+ completeSimple?: unknown;
1678
+ streamSimple?: unknown;
1679
+ }): boolean {
1680
+ if (typeof api.streamSimple === "function") return true;
1681
+ return typeof api.completeSimple !== "function";
1682
+ }