@cognisphere-sh/cognisphere-harness 0.12.0 → 0.14.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.
Files changed (38) hide show
  1. package/CHANGELOG.md +77 -11
  2. package/LICENSE +21 -0
  3. package/dist-web/assets/{file-editor-CQSmlsy_.js → file-editor-CqGYKmT3.js} +1 -1
  4. package/dist-web/assets/{index-1Hg12QW0.js → index-CDE-jsH8.js} +3 -3
  5. package/dist-web/index.html +1 -1
  6. package/home-template/config.example +0 -6
  7. package/home-template/docs/base-harness/README.md +11 -4
  8. package/home-template/scripts/build.sh +0 -5
  9. package/home-template/scripts/lib/remote-bootstrap.sh +2 -6
  10. package/home-template/scripts/setup-server.sh +7 -39
  11. package/package.json +9 -6
  12. package/skills/cognisphere-upgrade/SKILL.md +1 -1
  13. package/skills/create-plugin/SKILL.md +2 -2
  14. package/src/agents/base-agent/bootstrap/bootstrap.sh +2 -18
  15. package/src/agents/base-agent/extensions/context-meta.ts +4 -1
  16. package/src/agents/base-agent/system_prompts/0-base_prompt.md +3 -0
  17. package/src/api/agents.ts +3 -13
  18. package/src/api/credentials.ts +0 -15
  19. package/src/api/models.ts +2 -8
  20. package/src/api/secrets.ts +3 -3
  21. package/src/cli/index.ts +1 -1
  22. package/src/cli/init.ts +0 -12
  23. package/src/core/agent-manager.ts +12 -47
  24. package/src/core/config.ts +6 -0
  25. package/src/core/main.ts +10 -2
  26. package/src/core/model-access.ts +55 -0
  27. package/src/core/models-catalog.ts +72 -40
  28. package/src/core/models-store.ts +3 -4
  29. package/src/core/oauth-logins.ts +7 -3
  30. package/src/core/pi-delivery-receipts.ts +69 -0
  31. package/src/core/pi-models-sync.ts +2 -2
  32. package/src/core/queue.ts +7 -25
  33. package/src/core/rpc.ts +55 -49
  34. package/src/core/runner.ts +141 -131
  35. package/src/core/secrets.ts +2 -3
  36. package/src/core/types.ts +1 -1
  37. package/src/plugins/artifacts/index.ts +1 -1
  38. package/src/agents/base-agent/extensions/harness-bridge.ts +0 -63
@@ -9,7 +9,8 @@ import {
9
9
  statSync,
10
10
  writeFileSync,
11
11
  } from "node:fs";
12
- import { join } from "node:path";
12
+ import { extname, join } from "node:path";
13
+ import { fileURLToPath } from "node:url";
13
14
  import type { AgentDb } from "./queue.js";
14
15
  import { PiRpcClient } from "./rpc.js";
15
16
  import type { PiMessage } from "./rpc.js";
@@ -22,11 +23,26 @@ import type {
22
23
  import { AGENT_TOOLS } from "./types.js";
23
24
  import type { Logger } from "./logger.js";
24
25
 
26
+ /** Loaded into every pi child (see spawnPi). Same extension as this file, so it
27
+ * resolves whether the harness runs from `.ts` sources or compiled `.js`. */
28
+ const DELIVERY_RECEIPTS_EXTENSION = fileURLToPath(
29
+ new URL(`./pi-delivery-receipts${extname(fileURLToPath(import.meta.url))}`, import.meta.url),
30
+ );
31
+
32
+ /** The `pi` CLI of our pinned `@earendil-works/pi-coding-agent` dependency
33
+ * (its `bin.pi`, next to the package's `dist/index.js` entry), run with this
34
+ * Node. Spawning it instead of a `pi` on PATH keeps the binary and the types
35
+ * on the one version pinned in package.json. */
36
+ const PI_CLI = fileURLToPath(
37
+ new URL("./bundle/cli.js", import.meta.resolve("@earendil-works/pi-coding-agent")),
38
+ );
39
+
25
40
  const RESERVED_META = new Set([
26
41
  "Timestamp",
27
42
  "Plugin",
28
43
  "Channel",
29
44
  "ThreadId",
45
+ "EventId",
30
46
  "IsSilent",
31
47
  "Retry",
32
48
  "Continuation",
@@ -74,6 +90,7 @@ export function buildHarnessMetadata(m: BatchMessage, tz: string): string {
74
90
  `Plugin: ${m.pluginId}`,
75
91
  `Channel: ${m.channelId}`,
76
92
  `ThreadId: ${m.threadId}`,
93
+ `EventId: ${m.id}`,
77
94
  ];
78
95
  if (m.isSilent) lines.push("IsSilent: true");
79
96
  if (m.attempts > 0) lines.push("Retry: true");
@@ -145,13 +162,9 @@ function endOfTurn(messages: PiMessage[]): { complete: boolean; errorTag: string
145
162
 
146
163
  interface ActiveBatch {
147
164
  threadId: string;
148
- /** User-message groups in dispatch order. `[0]` is the prompt's rows (the
149
- * resend + fresh rows; empty on a continue batch, whose prompt is just the
150
- * nudge). `[k≥1]` is the k-th steer's rows — a single-row group for a live
151
- * `notify` steer, or the whole drained resend+fresh set for a continue
152
- * batch's combined steer. Maps each user-message entry pi appends to the
153
- * row ids sharing it (stdin is serial → append order = dispatch order). */
154
- messageGroups: number[][];
165
+ /** Rows sent this batch, in the prompt or as a steer (resend + fresh rows;
166
+ * continue rows are tracked in `continueIds`). */
167
+ sentIds: Set<number>;
155
168
  /** Canonical pi session id for this thread; assigned in processBatch
156
169
  * before spawn, used to locate the JSONL post-batch. */
157
170
  sessionId: string;
@@ -168,25 +181,13 @@ interface ActiveBatch {
168
181
  * via {@link AgentRunner.drainQueuedAsSteers}. */
169
182
  isContinue: boolean;
170
183
  /** Continue rows — already delivered on a prior batch (their `pi_entry_id`
171
- * is set). NOT part of `messageGroups`: their text is not re-rendered (only
172
- * the continuation nudge) and they keep their prior entry id, so they map to
173
- * no user-message index this batch. Counted as delivered unconditionally. */
184
+ * is set). Not in `sentIds`: their text is not re-rendered (only the
185
+ * continuation nudge) and they keep their prior entry id. Counted as
186
+ * delivered unconditionally. */
174
187
  continueIds: Set<number>;
175
- /** Count of user messages pi has appended this batch (prompt = 1, then one
176
- * per delivered steer). Drives the post-batch delivery split. */
177
- deliveredCount: number;
178
- /** entryIds already bound to a row this batch. The harness-bridge sweeps
179
- * pi's *entire* session JSONL (one file reused across all of a thread's
180
- * batches), so on batch ≥2 it re-reports every historical user entry at a
181
- * session-absolute index. We therefore ignore the reported index and bind
182
- * each genuinely-new entryId — one not seen before for this batch — to the
183
- * next unfilled message group in arrival order. This dedup is the seen-set;
184
- * `nextGroupForEntry` is the arrival-order cursor into `messageGroups`. */
185
- seenEntryIds: Set<string>;
186
- /** Index of the next `messageGroups` slot to bind a new entryId to. Advances
187
- * in dispatch order (group 0 = prompt, then steers), mirroring the order pi
188
- * appends user entries to the session. */
189
- nextGroupForEntry: number;
188
+ /** Sent rows pi confirmed saving: a delivery receipt named them. The only
189
+ * delivery signal — the same receipt sets the row's `pi_entry_id`. */
190
+ deliveredIds: Set<number>;
190
191
  }
191
192
 
192
193
  export interface RunnerOpts {
@@ -211,6 +212,12 @@ export interface RunnerOpts {
211
212
  * `ModelsStore`, so newly-added provider keys work without an agent reload.
212
213
  */
213
214
  resolveProviderEnv?: (providerId: string) => Record<string, string>;
215
+ /** The shared model check (`model-access.ts`); a thread override it
216
+ * rejects falls back to the agent default at spawn. */
217
+ modelUnavailableReason?: (providerId: string, modelId: string) => string | null;
218
+ /** Test-only: the command started instead of the bundled pi, with pi's
219
+ * arguments appended (e.g. `[process.execPath, "test/fake-pi.ts", script]`). */
220
+ piCommand?: string[];
214
221
  log: Logger;
215
222
  }
216
223
 
@@ -336,25 +343,15 @@ export class AgentRunner extends EventEmitter {
336
343
  attempts: 0,
337
344
  };
338
345
  const steerText = `${buildHarnessMetadata(msg, this.opts.timezone)}\n${payload.text}`;
339
- const group = [id];
340
- active.messageGroups.push(group);
341
- try {
342
- active.rpc.sendSteer(steerText);
343
- // The row was enqueued as 'queued' but dequeueBatch never saw it;
344
- // advance it to in_flight now that it's live in the streaming batch
345
- // so the DB/UI reflect that it's being processed, not still waiting.
346
- this.opts.db.markInFlight([id]);
347
- this.opts.log.debug(
348
- { threadId, id, plugin: payload.pluginId },
349
- "steer dispatched",
350
- );
351
- } catch (err) {
352
- // Drop the group we just pushed. Safe under single-threaded JS because
353
- // notify() runs to completion before the next call interleaves.
354
- const idx = active.messageGroups.indexOf(group);
355
- if (idx >= 0) active.messageGroups.splice(idx, 1);
356
- this.opts.log.error({ err, threadId, id }, "steer failed; row kept pending");
357
- }
346
+ active.sentIds.add(id);
347
+ // The row was enqueued as 'queued' but dequeueBatch never saw it;
348
+ // advance it to in_flight now that it's live in the streaming batch
349
+ // so the DB/UI reflect that it's being processed, not still waiting.
350
+ // If the steer never lands, it has no receipt and the post-batch split
351
+ // retries it as not-delivered.
352
+ this.opts.db.markInFlight([id]);
353
+ this.steer(active, [id], steerText);
354
+ this.opts.log.debug({ threadId, id, plugin: payload.pluginId }, "steer dispatched");
358
355
  return id;
359
356
  }
360
357
 
@@ -421,12 +418,9 @@ export class AgentRunner extends EventEmitter {
421
418
  }
422
419
  const active: ActiveBatch = {
423
420
  threadId,
424
- // messageGroups[0] = the prompt's rows (resend + fresh; empty on a
425
- // continue batch). Steers append groups [1..]. Continue rows are
426
- // tracked separately in continueIds (see the ActiveBatch doc).
427
- messageGroups: [
421
+ sentIds: new Set(
428
422
  batch.filter((m) => m.retryMode !== "continue").map((m) => m.id),
429
- ],
423
+ ),
430
424
  sessionId,
431
425
  phase: "spawning",
432
426
  cancelled: false,
@@ -436,12 +430,7 @@ export class AgentRunner extends EventEmitter {
436
430
  continueIds: new Set(
437
431
  batch.filter((m) => m.retryMode === "continue").map((m) => m.id),
438
432
  ),
439
- deliveredCount: 0,
440
- // Pre-seed with entryIds already bound on this thread (prior batches),
441
- // so the bridge's re-report of historical entries from the reused
442
- // session JSONL is skipped — only this batch's new entries bind.
443
- seenEntryIds: new Set(this.opts.db.entryIdsForThread(threadId)),
444
- nextGroupForEntry: 0,
433
+ deliveredIds: new Set(),
445
434
  };
446
435
  this.active.set(threadId, active);
447
436
  try {
@@ -486,27 +475,15 @@ export class AgentRunner extends EventEmitter {
486
475
  childExited = true;
487
476
  });
488
477
 
489
- // Real-time delivery + entry-id capture from the pi event stream:
490
- // - each user message pi appends (the prompt, then each steer) fires
491
- // onUserMessageStart → we count deliveries in dispatch order;
492
- // - the harness-bridge extension reports each user entry's id, which we
493
- // bind to the matching row immediately (so a row that later fails
494
- // still carries its pi_entry_id → it retries as 'continue').
495
- rpc.onUserMessageStart(() => {
496
- active.deliveredCount++;
497
- });
498
- // The bridge's reported `index` is session-absolute and unusable here:
499
- // pi reuses one session JSONL across a thread's batches, so on batch ≥2
500
- // it re-reports every historical user entry. We ignore the index and
501
- // instead bind each genuinely-new entryId — deduped via seenEntryIds —
502
- // to the next unfilled message group in arrival order (which matches the
503
- // order pi appends entries: prompt, then each steer).
504
- rpc.onHarnessEntry(({ entryId }) => {
505
- if (active.seenEntryIds.has(entryId)) return;
506
- active.seenEntryIds.add(entryId);
507
- const group = this.rowsForUserIndex(active, active.nextGroupForEntry);
508
- active.nextGroupForEntry++;
509
- for (const id of group) {
478
+ // Delivery receipts (pi-delivery-receipts.ts): each user message pi
479
+ // saves is reported with the `EventId`s it contains. A receipt both marks
480
+ // the row delivered and links it to the entry, so a row that later fails
481
+ // retries as 'continue'. Receipts for rows outside this batch are history
482
+ // from earlier batches (pi reuses one session file per thread).
483
+ rpc.onDeliveryReceipt(({ entryId, eventIds }) => {
484
+ for (const id of eventIds) {
485
+ if (!active.sentIds.has(id)) continue;
486
+ active.deliveredIds.add(id);
510
487
  this.opts.db.setRowEntryId(id, sessionId, entryId);
511
488
  }
512
489
  });
@@ -534,14 +511,31 @@ export class AgentRunner extends EventEmitter {
534
511
  "prompt",
535
512
  );
536
513
 
514
+ // A batch finishes when pi settles, not at agent_end: after agent_end pi
515
+ // may still retry, recover from context overflow, or run a steer that
516
+ // arrived late. Completion is judged from the latest run's messages.
537
517
  let endMessages: PiMessage[] | null = null;
538
- const agentEnded = new Promise<void>((resolve) => {
539
- rpc!.onAgentEnd((messages) => {
540
- endMessages = messages;
518
+ let settled = false;
519
+ rpc.onAgentEnd((messages) => {
520
+ endMessages = messages;
521
+ });
522
+ const agentSettled = new Promise<void>((resolve) => {
523
+ rpc!.onAgentSettled(() => {
524
+ settled = true;
541
525
  resolve();
542
526
  });
543
527
  });
544
- await rpc.sendPrompt(promptText);
528
+ const disposition = await rpc.sendPrompt(promptText);
529
+ if (disposition === "handled") {
530
+ // An extension input handler consumed the prompt: no run starts and
531
+ // no receipt or settle will come. The rows were dealt with.
532
+ log.info({ threadId }, "prompt handled by an extension; batch done");
533
+ active.phase = "completing";
534
+ await this.ensureChildExited(rpc, log);
535
+ childExited = true;
536
+ this.opts.db.markBatchDone([...active.continueIds, ...active.sentIds], sessionId);
537
+ return;
538
+ }
545
539
  active.phase = "streaming";
546
540
  // Drain anything queued for this thread into the live batch as one
547
541
  // combined steer: on a continue batch the resend + fresh rows left behind
@@ -551,12 +545,12 @@ export class AgentRunner extends EventEmitter {
551
545
  // of waiting for the next batch. doNotSteer rows are skipped (left queued)
552
546
  // inside drainQueuedAsSteers.
553
547
  this.drainQueuedAsSteers(active, log);
554
- // Race agent_end against pi exit; if pi exits first without emitting
555
- // agent_end, treat it as a crash.
556
- await Promise.race([agentEnded, rpc.waitExit()]);
557
- // Pi responds to an abort frame by emitting agent_end cleanly, so the
558
- // race resolves successfully on user-cancel too. Route to the catch
559
- // branch (which sees `active.cancelled`) instead of finalizing.
548
+ // Race agent_settled against pi exit; if pi exits first, treat it as a
549
+ // crash.
550
+ await Promise.race([agentSettled, rpc.waitExit()]);
551
+ // On abort the race resolves too (pi settles, or exits once stdin
552
+ // closes). Route to the catch branch (which sees `active.cancelled`)
553
+ // instead of finalizing.
560
554
  if (active.cancelled) {
561
555
  throw new Error("batch aborted");
562
556
  }
@@ -564,14 +558,14 @@ export class AgentRunner extends EventEmitter {
564
558
  await this.ensureChildExited(rpc, log);
565
559
  childExited = true;
566
560
 
567
- // Verdict: completion comes purely from the shape of the agent_end
568
- // frame's messages (no JSONL read). No agent_end at all ⇒ crash.
561
+ // Verdict: completion comes purely from the shape of the last agent_end
562
+ // frame's messages (no JSONL read). Exit before settling ⇒ crash.
569
563
  let complete: boolean;
570
564
  let errorTag: string;
571
- if (endMessages === null) {
565
+ if (!settled || endMessages === null) {
572
566
  complete = false;
573
567
  const stderr = rpc.stderrSnapshot()?.slice(-512) ?? "";
574
- errorTag = `[crash] pi exited without agent_end. stderr: ${stderr}`;
568
+ errorTag = `[crash] pi exited before agent_settled. stderr: ${stderr}`;
575
569
  } else {
576
570
  ({ complete, errorTag } = endOfTurn(endMessages));
577
571
  }
@@ -583,7 +577,7 @@ export class AgentRunner extends EventEmitter {
583
577
  // batch — requeue rather than cancel. Delivered rows already carry
584
578
  // their pi_entry_id, so they retry as continue; the rest as resend.
585
579
  const r = this.opts.db.markBatchFailed(
586
- [...active.continueIds, ...active.messageGroups.flat()],
580
+ [...active.continueIds, ...active.sentIds],
587
581
  "[shutdown] runner stopped mid-batch",
588
582
  this.maxAttempts,
589
583
  sessionId,
@@ -594,7 +588,7 @@ export class AgentRunner extends EventEmitter {
594
588
  );
595
589
  } else if (active.cancelled) {
596
590
  this.opts.db.markBatchCancelled(
597
- [...active.continueIds, ...active.messageGroups.flat()],
591
+ [...active.continueIds, ...active.sentIds],
598
592
  sessionId,
599
593
  );
600
594
  log.info({ threadId }, "batch cancelled");
@@ -603,7 +597,7 @@ export class AgentRunner extends EventEmitter {
603
597
  const tagged = msg.startsWith("[") ? msg : `[runner_error] ${msg}`;
604
598
  const errFull = stderr ? `${tagged}\n--stderr--\n${stderr}` : tagged;
605
599
  const r = this.opts.db.markBatchFailed(
606
- [...active.continueIds, ...active.messageGroups.flat()],
600
+ [...active.continueIds, ...active.sentIds],
607
601
  errFull,
608
602
  this.maxAttempts,
609
603
  sessionId,
@@ -652,27 +646,10 @@ export class AgentRunner extends EventEmitter {
652
646
  rpc.killGroup();
653
647
  }
654
648
 
655
- /**
656
- * Map a user-message dispatch index to the row id(s) sharing that entry.
657
- * Index 0 is the prompt (the resend/fresh rows on a non-continue batch;
658
- * empty on a continue batch, whose prompt is just the nudge). Index N≥1 is
659
- * the N-th steer — a single-row group for a live `notify` steer, or the
660
- * whole drained resend+fresh group for a continue batch.
661
- */
662
- private rowsForUserIndex(active: ActiveBatch, index: number): number[] {
663
- return active.messageGroups[index] ?? [];
664
- }
665
-
666
- /** Rows that actually reached the model this batch: continue rows (delivered
667
- * on a prior batch) plus every user-message index pi appended. */
649
+ /** Rows that actually reached the model this batch: continue rows
650
+ * (delivered on a prior batch) plus every row a receipt confirmed. */
668
651
  private deliveredRowIds(active: ActiveBatch): Set<number> {
669
- const delivered = new Set<number>(active.continueIds);
670
- // messageGroups[k] is delivered once pi has appended k+1 user messages, so
671
- // every group index < deliveredCount has landed (group 0 = prompt).
672
- for (let k = 0; k < active.deliveredCount; k++) {
673
- for (const id of active.messageGroups[k] ?? []) delivered.add(id);
674
- }
675
- return delivered;
652
+ return new Set([...active.continueIds, ...active.deliveredIds]);
676
653
  }
677
654
 
678
655
  /**
@@ -687,7 +664,7 @@ export class AgentRunner extends EventEmitter {
687
664
  errorTag: string,
688
665
  log: Logger,
689
666
  ): void {
690
- const allIds = [...active.continueIds, ...active.messageGroups.flat()];
667
+ const allIds = [...active.continueIds, ...active.sentIds];
691
668
  const delivered = this.deliveredRowIds(active);
692
669
  const undelivered = allIds.filter((id) => !delivered.has(id));
693
670
  const deliveredIds = allIds.filter((id) => delivered.has(id));
@@ -729,26 +706,41 @@ export class AgentRunner extends EventEmitter {
729
706
  * once the batch is streaming — covers a continue batch's left-behind
730
707
  * resend+fresh rows and any batch's spawn-window arrivals. `excludeDoNotSteer`
731
708
  * leaves `doNotSteer` rows queued for the next batch (they opt out of being
732
- * steered into a live turn). The rows are tracked as one group in
733
- * `messageGroups` before sending, so a broken pipe leaves them classified as
709
+ * steered into a live turn). The rows are added to `sentIds` before
710
+ * sending, so a broken pipe leaves them classified as
734
711
  * not-delivered (→ resend) by the post-batch split rather than orphaned
735
712
  * in_flight. resend rows carry `Retry: true` via their metadata.
736
713
  */
737
714
  private drainQueuedAsSteers(active: ActiveBatch, log: Logger): void {
738
715
  const rows = this.opts.db.dequeueBatch(active.threadId, { excludeDoNotSteer: true });
739
716
  if (rows.length === 0) return;
740
- active.messageGroups.push(rows.map((m) => m.id));
717
+ for (const m of rows) active.sentIds.add(m.id);
741
718
  const steerText = rows
742
719
  .map((m) => `${buildHarnessMetadata(m, this.opts.timezone)}\n${m.text}`)
743
720
  .join("\n\n");
744
- try {
745
- active.rpc!.sendSteer(steerText);
746
- log.debug({ threadId: active.threadId, drained: rows.length }, "drained queued as one steer");
747
- } catch (err) {
748
- // Pipe broke; pi is gone. The group stays in messageGroups — the delivery
749
- // split marks it not-delivered → resend on the next batch.
750
- log.error({ err, threadId: active.threadId, count: rows.length }, "drain steer failed");
751
- }
721
+ this.steer(active, rows.map((m) => m.id), steerText);
722
+ log.debug({ threadId: active.threadId, drained: rows.length }, "drained queued as one steer");
723
+ }
724
+
725
+ /**
726
+ * Send `ids` (already in `sentIds`) as one steer. If an extension input
727
+ * handler consumes it (`handled`), no session entry or receipt will come,
728
+ * so the rows are done. If it fails (pipe broke, pi rejected it, no ack),
729
+ * the rows stay in sentIds without a receipt and the post-batch split
730
+ * retries them as not-delivered.
731
+ */
732
+ private steer(active: ActiveBatch, ids: number[], text: string): void {
733
+ active.rpc!.sendSteer(text).then(
734
+ (disposition) => {
735
+ if (disposition !== "handled") return;
736
+ for (const id of ids) active.sentIds.delete(id);
737
+ this.opts.db.markBatchDone(ids, active.sessionId);
738
+ this.opts.log.info({ threadId: active.threadId, ids }, "steer handled by an extension");
739
+ },
740
+ (err: unknown) => {
741
+ this.opts.log.error({ err, threadId: active.threadId, ids }, "steer failed; rows retry");
742
+ },
743
+ );
752
744
  }
753
745
 
754
746
  private spawnPi(
@@ -780,10 +772,17 @@ export class AgentRunner extends EventEmitter {
780
772
  // directory from `resolve(path, "..")` so we don't need `--session-dir`.
781
773
  // We drop `--continue` because the explicit path makes "continue" implicit.
782
774
  const sessionFile = join(sessionDir, `${sessionId}.jsonl`);
783
- // Per-thread model override (set via the UI); falls back to the agent's
784
- // agent.json model for any unset field. A cross-provider override has its
785
- // credentials injected into `env` below.
786
- const override = this.opts.db.getThreadModel(threadId);
775
+ // Per-thread model override (set via the UI). One the operator can no
776
+ // longer use (signed out, key removed, model disabled) falls back to the
777
+ // agent's agent.json model instead of failing every attempt. A
778
+ // cross-provider override has its credentials injected into `env` below.
779
+ let override = this.opts.db.getThreadModel(threadId);
780
+ const unusable =
781
+ override && this.opts.modelUnavailableReason?.(override.provider, override.modelId);
782
+ if (unusable) {
783
+ log.warn({ threadId, reason: unusable }, "thread model unavailable; using agent default");
784
+ override = null;
785
+ }
787
786
  const provider = override?.provider ?? this.opts.agentJson.model.provider;
788
787
  const modelId = override?.modelId ?? this.opts.agentJson.model.id;
789
788
  const thinking =
@@ -801,6 +800,9 @@ export class AgentRunner extends EventEmitter {
801
800
  "--no-prompt-templates",
802
801
  "--no-themes",
803
802
  "--no-context-files",
803
+ // Never load an agent folder's `.pi/` settings, extensions or prompts,
804
+ // whatever project-trust decisions exist.
805
+ "--no-approve",
804
806
  ];
805
807
 
806
808
  // Skills: pi's --skill loader (`loadSkillsFromDir`) recurses into
@@ -814,10 +816,16 @@ export class AgentRunner extends EventEmitter {
814
816
  // No recursion — so we pass each first-level child of `extensions/` as its
815
817
  // own `--extension`. We verify the entry point exists before passing the
816
818
  // path to pi; otherwise pi crashes the whole run on a missing module.
819
+ // Delivery receipts load from the package, never the agent folder: the
820
+ // runner can't tell which rows reached pi without them.
821
+ args.push("--extension", DELIVERY_RECEIPTS_EXTENSION);
817
822
  const extensionsRoot = join(agentDir, "extensions");
818
823
  if (existsDir(extensionsRoot)) {
819
824
  for (const entry of readdirSync(extensionsRoot, { withFileTypes: true })) {
820
825
  if (entry.name.startsWith(".")) continue;
826
+ // ponytail: agents created before delivery receipts still carry this copy of the
827
+ // old entry-id reporter; the receipts replace it.
828
+ if (entry.name === "harness-bridge.ts") continue;
821
829
  const path = join(extensionsRoot, entry.name);
822
830
  if (entry.isDirectory()) {
823
831
  const hasEntry =
@@ -878,6 +886,7 @@ export class AgentRunner extends EventEmitter {
878
886
 
879
887
  log.debug(
880
888
  {
889
+ pi: PI_CLI,
881
890
  argv: args.length,
882
891
  threadId,
883
892
  venv: env.VIRTUAL_ENV,
@@ -885,7 +894,8 @@ export class AgentRunner extends EventEmitter {
885
894
  },
886
895
  "spawn pi",
887
896
  );
888
- const child = spawn("pi", args, {
897
+ const [cmd, ...cmdArgs] = this.opts.piCommand ?? [process.execPath, PI_CLI];
898
+ const child = spawn(cmd!, [...cmdArgs, ...args], {
889
899
  cwd: agentDir,
890
900
  env,
891
901
  stdio: ["pipe", "pipe", "pipe"],
@@ -2,7 +2,7 @@
2
2
  * Secrets resolution for agents and their plugins.
3
3
  *
4
4
  * v0: file-based, plaintext. Read from `<harnessRoot>/.secrets/secrets.json`
5
- * at boot (cached per process). Encryption is deferred — see HLD §15.
5
+ * on first access (cached per store). See docs/low-level/core.md for configuration.
6
6
  *
7
7
  * Format (uniform — every entry under `<agentId>` is a bucket):
8
8
  *
@@ -20,8 +20,7 @@
20
20
  *
21
21
  * Top-level keys starting with `_` are ignored — used for inline docs in
22
22
  * the auto-created placeholder. PUT /api/secrets calls `invalidate()` and
23
- * auto-restarts the affected agents so edits reach the pi runtime
24
- * immediately — no server bounce needed.
23
+ * soft-reloads affected running agents after their active batches drain.
25
24
  */
26
25
 
27
26
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
package/src/core/types.ts CHANGED
@@ -234,7 +234,7 @@ export interface ProviderCatalogEntry {
234
234
  /**
235
235
  * Per-provider configuration as written to `<harnessRoot>/.secrets/models.json`.
236
236
  * `credentials` keys mirror the catalog entry's `CredField.key`s.
237
- * Plaintext on disk in v0 (HLD §15); empty/missing values === unset.
237
+ * Plaintext on disk; empty/missing values === unset.
238
238
  * `enabledModels` is the operator-curated allowlist — agents may only
239
239
  * select from this list. May contain model IDs not in the catalog.
240
240
  */
@@ -190,7 +190,7 @@ export default class ArtifactsPlugin implements Plugin {
190
190
  };
191
191
 
192
192
  // Agent-facing listing, read by `scripts/artifacts/artifact`. Insider-only,
193
- // same shared-secret scheme as agent-messaging — see docs/api.md §10.
193
+ // same shared-secret scheme as agent-messaging — see docs/low-level/api.md §10.
194
194
  if (req.method === "GET" && scope === "api" && slug === "list" && !verb) {
195
195
  const expected = process.env.COGNISPHERE_WEBHOOK_SECRET;
196
196
  if (expected && req.headers["x-webhook-secret"] !== expected) {
@@ -1,63 +0,0 @@
1
- /**
2
- * harness-bridge — a pi extension loaded into every spawned `pi --mode rpc`
3
- * child (see `runner.ts:spawnPi`). Its sole job is to report each user-message
4
- * session **entry id** back to the harness in real time, so the parent can
5
- * link a queued event row to its place in pi's session JSONL without reading
6
- * the file and without waiting for the child to exit (which matters because a
7
- * failed batch never reaches a post-exit read).
8
- *
9
- * Transport: `ctx.ui.setStatus("cognisphere", <json>)`. In RPC mode this is a
10
- * fire-and-forget `extension_ui_request{method:"setStatus"}` frame on stdout,
11
- * which the harness's `PiRpcClient` already receives. The extension never
12
- * touches the harness DB — it has no knowledge of harness row ids — it only
13
- * reports `{ index, entryId }` in dispatch order; the parent maps index→row.
14
- *
15
- * Why a sweep instead of reading the entry in the `message_end` handler: pi
16
- * emits the extension event *before* it appends the message to the session
17
- * (agent-session: emit then `appendMessage`), so the entry id does not exist
18
- * yet at `message_end` time. Instead we re-scan `getEntries()` on every event
19
- * and emit any newly-appeared user-message entries; the id reliably lands on
20
- * the next event after the user message (typically the assistant's
21
- * `message_start`).
22
- */
23
- import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
24
- import type { SessionEntry } from "@earendil-works/pi-coding-agent";
25
-
26
- const STATUS_KEY = "cognisphere";
27
-
28
- export default function harnessBridge(pi: ExtensionAPI): void {
29
- // Number of user-message entries already reported for the current run.
30
- let reported = 0;
31
-
32
- const isUserMessageEntry = (e: SessionEntry): boolean =>
33
- e.type === "message" && e.message.role === "user";
34
-
35
- const sweep = (ctx: ExtensionContext): void => {
36
- const userEntries = ctx.sessionManager.getEntries().filter(isUserMessageEntry);
37
- for (let i = reported; i < userEntries.length; i++) {
38
- const entry = userEntries[i];
39
- if (!entry) continue;
40
- ctx.ui.setStatus(
41
- STATUS_KEY,
42
- JSON.stringify({ kind: "user_entry", index: i, entryId: entry.id }),
43
- );
44
- }
45
- reported = userEntries.length;
46
- };
47
-
48
- // One prompt = one run. Reset the per-run counter, then sweep any entries
49
- // pi may already have appended (e.g. the initial prompt) by the time the
50
- // next event fires.
51
- pi.on("agent_start", (_event, ctx) => {
52
- reported = 0;
53
- sweep(ctx);
54
- });
55
-
56
- // Re-scan on the events that follow a user message being appended (initial
57
- // prompt and each steer). Covering several event types makes the capture
58
- // robust to exactly when pi persists the entry.
59
- pi.on("message_start", (_event, ctx) => sweep(ctx));
60
- pi.on("turn_start", (_event, ctx) => sweep(ctx));
61
- pi.on("turn_end", (_event, ctx) => sweep(ctx));
62
- pi.on("agent_end", (_event, ctx) => sweep(ctx));
63
- }