@peakflo/agent-harness 0.2.24 → 0.2.25-rc.2

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.
@@ -110,6 +110,12 @@ export declare function isProtocolSupported(peerProtocolVersion: unknown, floor?
110
110
  */
111
111
  export declare const FINAL_HTTP_STATUSES: readonly number[];
112
112
  export declare function isFinalStatus(status: number): boolean;
113
+ /**
114
+ * `/ingest` only: every 4xx is final except 408 (timeout) and 429 (rate
115
+ * limit). A 4xx there is about the batch itself, so the same bytes would get
116
+ * the same answer. Other routes keep `FINAL_HTTP_STATUSES`.
117
+ */
118
+ export declare function isFinalIngestStatus(status: number): boolean;
113
119
  /** Stable, machine-readable error codes. */
114
120
  export declare const CONTRACT_ERROR_CODES: {
115
121
  readonly protocolUnsupported: "protocol_version_unsupported";
@@ -124,6 +130,8 @@ export declare const CONTRACT_ERROR_CODES: {
124
130
  readonly leaseExpired: "lease_expired";
125
131
  readonly leaseNotOwned: "lease_not_owned";
126
132
  readonly sessionUnknown: "session_unknown";
133
+ /** `/ingest`: the batch holds text Postgres cannot store. Not retryable. */
134
+ readonly invalidTranscriptEncoding: "invalid_transcript_encoding";
127
135
  readonly rateLimited: "rate_limited";
128
136
  };
129
137
  /**
package/dist/contract.js CHANGED
@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
12
12
  exports.EPHEMERAL_PART_TYPES = exports.PERSISTED_PART_TYPES = exports.ROUTES = exports.MAX_INGEST_PARTS = exports.MAX_INGEST_PART_BYTES = exports.DEFAULT_BASE_DELAY_MS = exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_LEASE_TTL_MS = exports.MISSED_HEARTBEATS_BEFORE_OFFLINE = exports.DEFAULT_HEARTBEAT_INTERVAL_MS = exports.MAX_LEASE_WAIT_SECONDS = exports.DEFAULT_LEASE_WAIT_SECONDS = exports.CONTRACT_ERROR_CODES = exports.FINAL_HTTP_STATUSES = exports.PROTOCOL_VERSION_HEADER = exports.MIN_SUPPORTED_PROTOCOL_VERSION = exports.HARNESS_UPGRADE_EXIT_CODE = exports.MIN_PROTOCOL_VERSION_FOR_NO_CEILING = exports.PROTOCOL_VERSION = void 0;
13
13
  exports.isProtocolSupported = isProtocolSupported;
14
14
  exports.isFinalStatus = isFinalStatus;
15
+ exports.isFinalIngestStatus = isFinalIngestStatus;
15
16
  exports.ingestPartByteLength = ingestPartByteLength;
16
17
  exports.isEphemeralPartType = isEphemeralPartType;
17
18
  exports.isPersistablePart = isPersistablePart;
@@ -133,6 +134,16 @@ exports.FINAL_HTTP_STATUSES = [
133
134
  function isFinalStatus(status) {
134
135
  return exports.FINAL_HTTP_STATUSES.includes(status);
135
136
  }
137
+ /**
138
+ * `/ingest` only: every 4xx is final except 408 (timeout) and 429 (rate
139
+ * limit). A 4xx there is about the batch itself, so the same bytes would get
140
+ * the same answer. Other routes keep `FINAL_HTTP_STATUSES`.
141
+ */
142
+ function isFinalIngestStatus(status) {
143
+ if (isFinalStatus(status))
144
+ return true;
145
+ return status >= 400 && status < 500 && status !== 408 && status !== 429;
146
+ }
136
147
  /** Stable, machine-readable error codes. */
137
148
  exports.CONTRACT_ERROR_CODES = {
138
149
  protocolUnsupported: 'protocol_version_unsupported',
@@ -147,6 +158,8 @@ exports.CONTRACT_ERROR_CODES = {
147
158
  leaseExpired: 'lease_expired',
148
159
  leaseNotOwned: 'lease_not_owned',
149
160
  sessionUnknown: 'session_unknown',
161
+ /** `/ingest`: the batch holds text Postgres cannot store. Not retryable. */
162
+ invalidTranscriptEncoding: 'invalid_transcript_encoding',
150
163
  rateLimited: 'rate_limited'
151
164
  };
152
165
  /* -------------------------------------------------------------------------- */
@@ -155,6 +155,10 @@ export declare class ControlPlaneClient {
155
155
  * visible product defect — the user watches text stop arriving. Retrying is
156
156
  * safe: the upsert is keyed on (sessionId, partId), so a replayed batch is
157
157
  * idempotent.
158
+ *
159
+ * EVERY 4xx IS FINAL HERE except 408 and 429. A 4xx says THIS BATCH is
160
+ * wrong (400 invalid body or text, 413 too large, 422), and sending the
161
+ * same bytes five more times over ~31 s cannot change that answer.
158
162
  */
159
163
  ingest(sessionId: string, request: Omit<IngestRequest, 'protocolVersion'>): Promise<IngestResponse>;
160
164
  acknowledgeSteer(sessionId: string, leaseId: string, turnId: string, consumed: boolean): Promise<{
@@ -328,6 +328,10 @@ class ControlPlaneClient {
328
328
  * visible product defect — the user watches text stop arriving. Retrying is
329
329
  * safe: the upsert is keyed on (sessionId, partId), so a replayed batch is
330
330
  * idempotent.
331
+ *
332
+ * EVERY 4xx IS FINAL HERE except 408 and 429. A 4xx says THIS BATCH is
333
+ * wrong (400 invalid body or text, 413 too large, 422), and sending the
334
+ * same bytes five more times over ~31 s cannot change that answer.
331
335
  */
332
336
  async ingest(sessionId, request) {
333
337
  return this.withRetry('ingest', () => this.send({
@@ -335,7 +339,7 @@ class ControlPlaneClient {
335
339
  path: contract_1.ROUTES.ingest(sessionId),
336
340
  token: this.requireCredential(),
337
341
  body: { protocolVersion: contract_1.PROTOCOL_VERSION, ...request }
338
- }));
342
+ }), contract_1.isFinalIngestStatus);
339
343
  }
340
344
  async acknowledgeSteer(sessionId, leaseId, turnId, consumed) {
341
345
  return this.withRetry('steer-ack', () => this.send({
@@ -443,7 +447,7 @@ class ControlPlaneClient {
443
447
  * `FINAL_HTTP_STATUSES` is shared with the control plane instead of being
444
448
  * retyped on each side.
445
449
  */
446
- async withRetry(label, attemptFn) {
450
+ async withRetry(label, attemptFn, isFinal = contract_1.isFinalStatus) {
447
451
  let lastError;
448
452
  for (let attempt = 1; attempt <= this.maxAttempts; attempt += 1) {
449
453
  try {
@@ -451,7 +455,7 @@ class ControlPlaneClient {
451
455
  }
452
456
  catch (error) {
453
457
  lastError = error;
454
- if (error instanceof ControlPlaneError && error.final) {
458
+ if (error instanceof ControlPlaneError && isFinal(error.status)) {
455
459
  throw error;
456
460
  }
457
461
  if (attempt < this.maxAttempts) {
@@ -0,0 +1,42 @@
1
+ /**
2
+ * MAKE A VALUE STORABLE IN A POSTGRES `text` OR `jsonb` COLUMN.
3
+ *
4
+ * JavaScript strings can hold two things that PostgreSQL refuses:
5
+ *
6
+ * - U+0000 (NUL). A `text` parameter containing it fails with 22021
7
+ * ("invalid byte sequence for encoding UTF8: 0x00"); the same character
8
+ * inside JSON (`\u0000`) cast to `jsonb` fails with 22P05 ("unsupported
9
+ * Unicode escape sequence").
10
+ * - A LONE UTF-16 surrogate (a high surrogate not followed by a low one, or
11
+ * a low one not preceded by a high one). `JSON.stringify` writes it as a
12
+ * `\udXXX` escape and `jsonb` rejects that escape with 22P02.
13
+ *
14
+ * Both turn up in ordinary agent output: terminal captures, binary file reads
15
+ * and tool results cut in the middle of an emoji. One such character used to
16
+ * fail the WHOLE `/ingest` batch with a 500, so the turn lost its transcript.
17
+ *
18
+ * This removes NUL and replaces each lone surrogate with U+FFFD. Valid
19
+ * surrogate pairs (emoji) and every other character are unchanged. Object KEYS
20
+ * are cleaned as well as values, because a key is serialised into the same
21
+ * JSON. Nothing is copied when nothing changes.
22
+ *
23
+ * The counts are for a log line or a metric. Never log the content itself.
24
+ */
25
+ export interface PostgresTextSanitizeResult<T> {
26
+ value: T;
27
+ /** NUL characters removed. */
28
+ nulBytes: number;
29
+ /** Lone surrogates replaced with U+FFFD. */
30
+ loneSurrogates: number;
31
+ /** `nulBytes + loneSurrogates`. Zero means `value` is the input, unchanged. */
32
+ replacements: number;
33
+ }
34
+ export interface PostgresTextCounts {
35
+ nulBytes: number;
36
+ loneSurrogates: number;
37
+ }
38
+ /**
39
+ * Clean a string, array or plain object (recursively, keys and values) so
40
+ * Postgres accepts it in `text` and `jsonb`. See the file comment.
41
+ */
42
+ export declare function sanitizeForPostgres<T>(value: T): PostgresTextSanitizeResult<T>;
@@ -0,0 +1,122 @@
1
+ "use strict";
2
+ /*
3
+ * A COPY of `packages/core/src/utils/postgres-text.ts` (sanitizer half).
4
+ *
5
+ * The harness is published on its own and does not depend on
6
+ * `@pf-workflo/core`, so it cannot import the server's helper. Keep the two in
7
+ * step; the parity test in `__tests__/ingest-invalid-text.test.ts` runs both
8
+ * on one fixture table and fails if they disagree.
9
+ *
10
+ * The harness cleans every batch before `/ingest` so a NUL in a tool result
11
+ * cannot fail the batch even against a control plane that does not clean it.
12
+ */
13
+ /**
14
+ * MAKE A VALUE STORABLE IN A POSTGRES `text` OR `jsonb` COLUMN.
15
+ *
16
+ * JavaScript strings can hold two things that PostgreSQL refuses:
17
+ *
18
+ * - U+0000 (NUL). A `text` parameter containing it fails with 22021
19
+ * ("invalid byte sequence for encoding UTF8: 0x00"); the same character
20
+ * inside JSON (`\u0000`) cast to `jsonb` fails with 22P05 ("unsupported
21
+ * Unicode escape sequence").
22
+ * - A LONE UTF-16 surrogate (a high surrogate not followed by a low one, or
23
+ * a low one not preceded by a high one). `JSON.stringify` writes it as a
24
+ * `\udXXX` escape and `jsonb` rejects that escape with 22P02.
25
+ *
26
+ * Both turn up in ordinary agent output: terminal captures, binary file reads
27
+ * and tool results cut in the middle of an emoji. One such character used to
28
+ * fail the WHOLE `/ingest` batch with a 500, so the turn lost its transcript.
29
+ *
30
+ * This removes NUL and replaces each lone surrogate with U+FFFD. Valid
31
+ * surrogate pairs (emoji) and every other character are unchanged. Object KEYS
32
+ * are cleaned as well as values, because a key is serialised into the same
33
+ * JSON. Nothing is copied when nothing changes.
34
+ *
35
+ * The counts are for a log line or a metric. Never log the content itself.
36
+ */
37
+ Object.defineProperty(exports, "__esModule", { value: true });
38
+ exports.sanitizeForPostgres = sanitizeForPostgres;
39
+ /** Fast check: does the string contain NUL or ANY surrogate (paired or not)? */
40
+ // eslint-disable-next-line no-control-regex
41
+ const SUSPECT = /[\u0000\uD800-\uDFFF]/;
42
+ /*
43
+ * No `u` flag on purpose: the pattern must see UTF-16 code units, so that a
44
+ * lone surrogate is a single match. A high surrogate is lone when no low one
45
+ * follows; a low surrogate is lone when no high one comes before it.
46
+ */
47
+ const INVALID =
48
+ // eslint-disable-next-line no-control-regex
49
+ /\u0000|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
50
+ function cleanString(input, counts) {
51
+ if (!SUSPECT.test(input))
52
+ return input;
53
+ let changed = false;
54
+ const output = input.replace(INVALID, (match) => {
55
+ changed = true;
56
+ if (match === '\u0000') {
57
+ counts.nulBytes += 1;
58
+ return '';
59
+ }
60
+ counts.loneSurrogates += 1;
61
+ return '�';
62
+ });
63
+ return changed ? output : input;
64
+ }
65
+ function isPlainObject(value) {
66
+ if (value === null || typeof value !== 'object')
67
+ return false;
68
+ const proto = Object.getPrototypeOf(value);
69
+ return proto === Object.prototype || proto === null;
70
+ }
71
+ function walk(value, counts) {
72
+ if (typeof value === 'string')
73
+ return cleanString(value, counts);
74
+ if (Array.isArray(value)) {
75
+ let copy = null;
76
+ for (let i = 0; i < value.length; i += 1) {
77
+ const next = walk(value[i], counts);
78
+ if (next !== value[i]) {
79
+ copy ??= value.slice();
80
+ copy[i] = next;
81
+ }
82
+ }
83
+ return copy ?? value;
84
+ }
85
+ if (isPlainObject(value)) {
86
+ let changed = false;
87
+ const entries = [];
88
+ for (const [key, item] of Object.entries(value)) {
89
+ const nextKey = cleanString(key, counts);
90
+ const nextItem = walk(item, counts);
91
+ if (nextKey !== key || nextItem !== item)
92
+ changed = true;
93
+ entries.push([nextKey, nextItem]);
94
+ }
95
+ if (!changed)
96
+ return value;
97
+ // `Object.fromEntries` defines own properties, so a `__proto__` key from
98
+ // JSON.parse stays a plain key instead of replacing the prototype. When
99
+ // two keys become equal after cleaning, the later one wins.
100
+ const rebuilt = Object.fromEntries(entries);
101
+ return Object.getPrototypeOf(value) === null
102
+ ? Object.assign(Object.create(null), rebuilt)
103
+ : rebuilt;
104
+ }
105
+ // Numbers, booleans, null, undefined and class instances are left as they
106
+ // are: they are not JSON text that a client sent.
107
+ return value;
108
+ }
109
+ /**
110
+ * Clean a string, array or plain object (recursively, keys and values) so
111
+ * Postgres accepts it in `text` and `jsonb`. See the file comment.
112
+ */
113
+ function sanitizeForPostgres(value) {
114
+ const counts = { nulBytes: 0, loneSurrogates: 0 };
115
+ const cleaned = walk(value, counts);
116
+ return {
117
+ value: cleaned,
118
+ nulBytes: counts.nulBytes,
119
+ loneSurrogates: counts.loneSurrogates,
120
+ replacements: counts.nulBytes + counts.loneSurrogates
121
+ };
122
+ }
@@ -608,6 +608,25 @@ export declare class SessionRunner {
608
608
  * both sides agree on it; a limit only one side knows is not a limit.
609
609
  */
610
610
  private flush;
611
+ /**
612
+ * THE FINAL INGEST WAS REFUSED (400/413/422). Send it again with less, so
613
+ * the turn is recorded and the lease released instead of waiting for the
614
+ * watchdog:
615
+ *
616
+ * 1. no parts, same turn metadata and model messages;
617
+ * 2. no parts, no model messages, only the turn's id, times, stop
618
+ * reason and cost (what the lease release and billing need).
619
+ *
620
+ * Each step that is refused the same way is logged and the next is tried.
621
+ * Anything else, or a refusal of the last step, is thrown as before.
622
+ */
623
+ private sendRefusedFinal;
624
+ /**
625
+ * Remove NUL and replace lone UTF-16 surrogates before a batch leaves this
626
+ * runner: Postgres refuses both, and one such character in a tool result
627
+ * used to fail the whole batch. Logs counts only, never content.
628
+ */
629
+ private postgresSafe;
611
630
  /**
612
631
  * WHERE `resumeFromRev` FINALLY DOES SOMETHING.
613
632
  *
@@ -45,6 +45,7 @@ const mcp_preflight_1 = require("./mcp-preflight");
45
45
  const mcp_tool_store_1 = require("./mcp-tool-store");
46
46
  const mcp_toolset_1 = require("./mcp-toolset");
47
47
  const permission_mode_1 = require("./permission-mode");
48
+ const postgres_safe_text_1 = require("./postgres-safe-text");
48
49
  const projection_1 = require("./projection");
49
50
  const space_files_1 = require("./space-files");
50
51
  const task_files_1 = require("./task-files");
@@ -455,6 +456,19 @@ function resolveApproval(command, open) {
455
456
  : 'Denied (no option chosen).'
456
457
  };
457
458
  }
459
+ /** The HTTP status on a control-plane error, read without importing its class. */
460
+ function errorStatus(error) {
461
+ const status = error && typeof error === 'object'
462
+ ? error.status
463
+ : undefined;
464
+ return typeof status === 'number' ? status : undefined;
465
+ }
466
+ function errorCode(error) {
467
+ const code = error && typeof error === 'object'
468
+ ? error.code
469
+ : undefined;
470
+ return typeof code === 'string' ? code : undefined;
471
+ }
458
472
  class SessionRunner {
459
473
  deps;
460
474
  logger;
@@ -2518,10 +2532,108 @@ class SessionRunner {
2518
2532
  const token = this.credentialProxyToken;
2519
2533
  for (let i = 0; i < chunks.length; i += 1) {
2520
2534
  const isLast = i === chunks.length - 1;
2521
- await this.deps.ingest(sessionId, (0, credential_proxy_1.redactCredentialProxyTokenDeep)(chunks[i], token), isLast ? (0, credential_proxy_1.redactCredentialProxyTokenDeep)(turn, token) : undefined, isLast ? final : false, isLast
2522
- ? (0, credential_proxy_1.redactCredentialProxyTokenDeep)(modelMessages, token)
2523
- : undefined);
2535
+ const chunkParts = this.postgresSafe(sessionId, 'parts', (0, credential_proxy_1.redactCredentialProxyTokenDeep)(chunks[i], token));
2536
+ const chunkTurn = isLast
2537
+ ? this.postgresSafe(sessionId, 'turn', (0, credential_proxy_1.redactCredentialProxyTokenDeep)(turn, token))
2538
+ : undefined;
2539
+ const chunkFinal = isLast ? final : false;
2540
+ const chunkMessages = isLast
2541
+ ? this.postgresSafe(sessionId, 'modelMessages', (0, credential_proxy_1.redactCredentialProxyTokenDeep)(modelMessages, token))
2542
+ : undefined;
2543
+ try {
2544
+ await this.deps.ingest(sessionId, chunkParts, chunkTurn, chunkFinal, chunkMessages);
2545
+ }
2546
+ catch (error) {
2547
+ const status = errorStatus(error);
2548
+ const partIds = chunkParts.map((part) => part.partId);
2549
+ /*
2550
+ * A 400/413/422 REFUSES THIS BATCH'S CONTENT, not the turn. The
2551
+ * control plane will give the same answer however often it is sent
2552
+ * (`isFinalIngestStatus` already stopped the retries), so the batch is
2553
+ * DROPPED and the turn goes on. Its parts stay in the local store
2554
+ * (`harness.sqlite`), so the log names them for recovery.
2555
+ *
2556
+ * Every other failure (401/403/404/409/426, or a 5xx after the retry
2557
+ * ladder) still ends the turn, as before: the runner no longer owns
2558
+ * the session, or the control plane cannot be reached.
2559
+ */
2560
+ if (status === 400 || status === 413 || status === 422) {
2561
+ this.logger.error(`[SessionRunner] ingest-batch-dropped session=${sessionId} status=${status} ` +
2562
+ `code=${errorCode(error) ?? '(none)'} parts=${partIds.length} ` +
2563
+ `final=${chunkFinal} partIds=${partIds.slice(0, 20).join(',')}` +
2564
+ (partIds.length > 20 ? ',…' : '') +
2565
+ ' (the parts remain in the local transcript store)');
2566
+ // The FINAL ingest also releases the lease and records the turn, so
2567
+ // it must still get through. See `sendRefusedFinal`.
2568
+ if (chunkFinal) {
2569
+ await this.sendRefusedFinal(sessionId, chunkTurn, chunkMessages);
2570
+ }
2571
+ continue;
2572
+ }
2573
+ this.logger.error(`[SessionRunner] ingest-batch-failed session=${sessionId} status=${status ?? '(network)'} ` +
2574
+ `parts=${partIds.length} final=${chunkFinal} ` +
2575
+ `partIds=${partIds.slice(0, 20).join(',')}` +
2576
+ (partIds.length > 20 ? ',…' : '') +
2577
+ ' (the parts remain in the local transcript store)');
2578
+ throw error;
2579
+ }
2580
+ }
2581
+ }
2582
+ /**
2583
+ * THE FINAL INGEST WAS REFUSED (400/413/422). Send it again with less, so
2584
+ * the turn is recorded and the lease released instead of waiting for the
2585
+ * watchdog:
2586
+ *
2587
+ * 1. no parts, same turn metadata and model messages;
2588
+ * 2. no parts, no model messages, only the turn's id, times, stop
2589
+ * reason and cost (what the lease release and billing need).
2590
+ *
2591
+ * Each step that is refused the same way is logged and the next is tried.
2592
+ * Anything else, or a refusal of the last step, is thrown as before.
2593
+ */
2594
+ async sendRefusedFinal(sessionId, turn, modelMessages) {
2595
+ const minimal = turn
2596
+ ? {
2597
+ turnId: turn.turnId,
2598
+ startedAt: turn.startedAt,
2599
+ finishedAt: turn.finishedAt,
2600
+ stopReason: turn.stopReason,
2601
+ // Kept: the control plane bills the turn from it.
2602
+ costUsd: turn.costUsd
2603
+ }
2604
+ : undefined;
2605
+ const attempts = [
2606
+ { label: 'without-parts', turn, modelMessages },
2607
+ { label: 'minimal-turn', turn: minimal, modelMessages: undefined }
2608
+ ];
2609
+ for (let i = 0; i < attempts.length; i += 1) {
2610
+ const attempt = attempts[i];
2611
+ try {
2612
+ await this.deps.ingest(sessionId, [], attempt.turn, true, attempt.modelMessages);
2613
+ return;
2614
+ }
2615
+ catch (error) {
2616
+ const status = errorStatus(error);
2617
+ const refused = status === 400 || status === 413 || status === 422;
2618
+ if (!refused || i === attempts.length - 1)
2619
+ throw error;
2620
+ this.logger.error(`[SessionRunner] ingest-final-refused session=${sessionId} status=${status} ` +
2621
+ `code=${errorCode(error) ?? '(none)'} attempt=${attempt.label}`);
2622
+ }
2623
+ }
2624
+ }
2625
+ /**
2626
+ * Remove NUL and replace lone UTF-16 surrogates before a batch leaves this
2627
+ * runner: Postgres refuses both, and one such character in a tool result
2628
+ * used to fail the whole batch. Logs counts only, never content.
2629
+ */
2630
+ postgresSafe(sessionId, field, value) {
2631
+ const result = (0, postgres_safe_text_1.sanitizeForPostgres)(value);
2632
+ if (result.replacements > 0) {
2633
+ this.logger.warn(`[SessionRunner] ingest-sanitized session=${sessionId} field=${field} ` +
2634
+ `nulBytes=${result.nulBytes} loneSurrogates=${result.loneSurrogates}`);
2524
2635
  }
2636
+ return result.value;
2525
2637
  }
2526
2638
  /* ---------------------------------------------------------------- */
2527
2639
  /* Wiring */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@peakflo/agent-harness",
3
- "version": "0.2.24",
3
+ "version": "0.2.25-rc.2",
4
4
  "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
5
5
  "license": "MIT",
6
6
  "type": "commonjs",