pi-studio 0.11.9 → 0.11.10

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.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,11 @@ All notable changes to `pi-studio` are documented here.
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.11.10] — 2026-11-03
8
+
9
+ ### Changed
10
+ - With pi-repl 0.12.1 or later loaded in the same Pi, the agent is told of each REPL record entry once. pi-repl keeps track of what the agent has been told about its own `pi-repl-*` sessions, including the one Studio's REPL pane shows and those the agent used through Studio's REPL tools. Its reports come at the start of a run, as before, and now also in Studio's REPL tool results. Studio tells the agent about the rest. Before, both told it about the `pi-repl-*` sessions. Without pi-repl, or with pi-repl 0.12.0 or older, Studio tells it about every session, as before.
11
+
7
12
  ## [0.11.9] — 2026-11-03
8
13
 
9
14
  ### Added
package/README.md CHANGED
@@ -136,7 +136,7 @@ Icons in exported PDFs need Mermaid CLI 11.12+ (`npm install -g @mermaid-js/merm
136
136
 
137
137
  ### REPL
138
138
 
139
- The REPL pane runs code in tmux sessions. It can start its own, and it shares a record of submissions and output with [pi-repl](https://github.com/omaclaren/pi-repl) when both use the same session. Pane echo sets how much submitted code goes into the raw tmux history, as in pi-repl: up to 20 lines with Summary, the default, up to 40 with Full, and none with Off. Your sends and notes are recorded under your name (**Sending as**, under Quick send). An image or PDF an entry's code saved while it ran, such as a plot, shows under it when the code or output names it. The agent is told of record entries it hasn't seen, such as your sends, other clients' sends and late output, when a run starts and with its REPL tools' results. The record format is in [`shared/REPL_SESSION_RECORD_PROTOCOL.md`](./shared/REPL_SESSION_RECORD_PROTOCOL.md).
139
+ The REPL pane runs code in tmux sessions. It can start its own, and it shares a record of submissions and output with [pi-repl](https://github.com/omaclaren/pi-repl) when both use the same session. Pane echo sets how much submitted code goes into the raw tmux history, as in pi-repl: up to 20 lines with Summary, the default, up to 40 with Full, and none with Off. Your sends and notes are recorded under your name (**Sending as**, under Quick send). An image or PDF an entry's code saved while it ran, such as a plot, shows under it when the code or output names it. The agent is told of record entries it hasn't seen, such as your sends, other clients' sends and late output, when a run starts and with its REPL tools' results. With pi-repl 0.12.1 or later loaded too, pi-repl tells it about its own `pi-repl-*` sessions, also in Studio's tool results, and Studio about the rest, so nothing is told twice. The record format is in [`shared/REPL_SESSION_RECORD_PROTOCOL.md`](./shared/REPL_SESSION_RECORD_PROTOCOL.md).
140
140
 
141
141
  ### Side questions
142
142
 
package/ROADMAP.md CHANGED
@@ -4,7 +4,7 @@ This is the current planning source of truth for Studio work. `NEXT-STAGE.md` is
4
4
 
5
5
  ## Current status (3 Nov 2026)
6
6
 
7
- `0.11.9` is the current release, and Studio is in a feature freeze from it, for use in normal work. Before the freeze, `0.11.9` added the images and PDFs a REPL entry's code saved, shown under the entry, and a PDF header that fits on one line. During the freeze, changes are limited to fixes for failures in normal use, lost data, effects on other people's processes or files, and security. [TODO.md](TODO.md) lists the known limits and what comes after the freeze.
7
+ `0.11.10` is the current release. Studio is in a feature freeze from `0.11.9`, for use in normal work. Before the freeze, `0.11.9` added the images and PDFs a REPL entry's code saved, shown under the entry, and a PDF header that fits on one line. `0.11.10`, the one change approved in the freeze, works with pi-repl `0.12.1` so that, with both loaded, the agent is told each REPL record entry once. During the freeze, changes are limited to fixes for failures in normal use, lost data, effects on other people's processes or files, and security. [TODO.md](TODO.md) lists the known limits and what comes after the freeze.
8
8
 
9
9
  `0.10.0` (14 Oct) made the buffer-first workspace the default, as **dual editor mode** (Prompt and Document), with **single editor mode** one switch away (footer button, `/studio --single`). It went through real course use as private alpha candidates 49–69. The `PI_STUDIO_*` flags described further down are development overrides only: when any is set it decides, and the mode switch is hidden.
10
10
 
@@ -13,6 +13,7 @@ The `0.11` releases brought the REPL pane up to pi-repl `0.11.7`: Ruby, Java, Oc
13
13
  ### Parity at the freeze
14
14
 
15
15
  - **pi-repl `0.11.7` and agent-repl `0.5.0`.** Studio's copies of the shared record, names, protocol, control-file, display, C++, gnuplot and M-language helpers are byte-identical to pi-repl's, and agent-repl carries the same record, names and protocol files. Two helpers differ: pi-repl generalised `repl-session-stop.js` and `repl-gnuplot-processes.js` for LFortran. Studio doesn't run LFortran, and won't paste into pi-repl's LFortran session ("This session takes code only through pi-repl").
16
+ - **pi-repl `0.12.1`'s record-activity channel.** pi-repl `0.12.0` started telling its agent about other clients' record entries itself. With both loaded, Studio `0.11.10` leaves the `pi-repl-*` sessions to pi-repl over Pi's event bus (protocol 2), and puts pi-repl's report in its own REPL results. Studio still has its older copy of pi-repl's activity module and protocol document, which are re-vendored after the freeze.
16
17
  - **pi-markdown-preview `0.26.2` and agent-markdown-preview `0.13.2`.** Their REPL page reads the same records with the same record-directory check. Both show the images and PDFs an entry's code saved, by the same rules: a file shows when the entry names it and it was written in that entry's turn. Studio has them from `0.11.9`; the preview packages' REPL page has its latest rules on an unreleased branch.
17
18
 
18
19
  ## Release approach
package/index.ts CHANGED
@@ -94,8 +94,10 @@ import {
94
94
  REPL_ACTIVITY_RUN_START_BUDGET,
95
95
  buildReplActivityReport,
96
96
  confirmReplActivityDelivered,
97
+ createPiReplRecordActivityLink,
97
98
  createReplActivityState,
98
99
  holdReplActivityCommit,
100
+ isPiReplSessionName,
99
101
  listReplRecordEntries,
100
102
  readReplRecordInert,
101
103
  recordActivityMode,
@@ -14278,38 +14280,60 @@ export default function (pi: ExtensionAPI) {
14278
14280
  percent: null,
14279
14281
  };
14280
14282
  // The selected REPL session, the count of explicit actions and `shown`.
14281
- const studioReplSelection = createReplSelection<StudioReplSessionInfo>();
14283
+ // pi-repl's view of its own sessions, when it's loaded too and reports (studio-repl-activity.js,
14284
+ // D5): told what Studio's pane shows whenever that changes.
14285
+ const piReplActivity = createPiReplRecordActivityLink(pi.events);
14286
+ const studioReplSelection = createReplSelection<StudioReplSessionInfo>({ onChange: (session) => piReplActivity.pane(session?.sessionName ?? null) });
14282
14287
  // What Studio's agent has been told of its REPL sessions' records (PANE-AWARENESS-DESIGN.md,
14283
14288
  // draft 3, after D5 of the shared design for people's sends). Read when Studio loads.
14284
14289
  const replActivityMode = recordActivityMode();
14285
14290
  const replActivity = createReplActivityState();
14286
14291
  // The session showing in Studio's REPL pane, where the person's Quick sends go, and those
14287
14292
  // this conversation has sent to or named.
14288
- const replActivitySessionNames = (): string[] => [...new Set(
14289
- [studioReplSelection.session?.sessionName, ...replActivity.used].filter((name): name is string => Boolean(name)),
14293
+ // While pi-repl reports, its own sessions are its to report.
14294
+ const replActivitySessionNames = (leaveToPiRepl = false): string[] => [...new Set(
14295
+ [studioReplSelection.session?.sessionName, ...replActivity.used].filter((name): name is string => Boolean(name) && !(leaveToPiRepl && isPiReplSessionName(name))),
14290
14296
  )];
14297
+ // A session this conversation sent to or named, for Studio's reports and pi-repl's.
14298
+ const useReplActivitySession = (sessionName: string) => {
14299
+ replActivity.used.add(sessionName);
14300
+ piReplActivity.used(sessionName);
14301
+ };
14291
14302
  // The report a tool result carries, held until its text is seen in what the model is given.
14292
14303
  // The agent's own send isn't reported back to it, but is marked as told in the version its
14293
- // result shows, once that result's text (`own.text`) is seen too.
14294
- const prepareReplActivityForResult = async (toolCallId: string, own?: { sessionName: string; id: string; text: string }, budget = REPL_ACTIVITY_RESULT_BUDGET): Promise<string> => {
14304
+ // result shows, once that result's text (`own.text`) is seen too. While pi-repl reports, its
14305
+ // report of its own sessions comes first, in the room Studio's report of the rest leaves.
14306
+ const prepareReplActivityForResult = async (toolCallId: string, ownSend?: { sessionName: string; id: string; text: string; status: string }, budget = REPL_ACTIVITY_RESULT_BUDGET): Promise<string> => {
14295
14307
  if (replActivityMode === "off") return "";
14308
+ const leaveToPiRepl = piReplActivity.reports();
14309
+ const toPiRepl = Boolean(ownSend && leaveToPiRepl && isPiReplSessionName(ownSend.sessionName));
14310
+ const own = toPiRepl ? undefined : ownSend;
14311
+ let studioReport = "";
14296
14312
  try {
14297
- const names = replActivitySessionNames();
14298
- if (!names.length) return "";
14299
- const observations = await observeStudioReplActivity(names);
14300
- const observedOwn = own ? observations.find((observed) => observed.ok && observed.sessionName === own.sessionName) : undefined;
14301
- const ownEntry = observedOwn?.ok ? observedOwn.record.entries.find((entry) => entry.id === own?.id) : undefined;
14302
- const report = buildReplActivityReport(replActivity, observations, {
14303
- budget,
14304
- exclude: new Set(own ? [own.id] : []),
14305
- own: own && ownEntry ? [{ sessionName: own.sessionName, id: own.id, version: replEntryVersion(ownEntry), text: own.text }] : [],
14306
- });
14307
- holdReplActivityCommit(replActivity, `tool:${toolCallId}`, report.commit);
14308
- return report.text;
14313
+ const names = replActivitySessionNames(leaveToPiRepl);
14314
+ if (names.length) {
14315
+ const observations = await observeStudioReplActivity(names);
14316
+ const observedOwn = own ? observations.find((observed) => observed.ok && observed.sessionName === own.sessionName) : undefined;
14317
+ const ownEntry = observedOwn?.ok ? observedOwn.record.entries.find((entry) => entry.id === own?.id) : undefined;
14318
+ const report = buildReplActivityReport(replActivity, observations, {
14319
+ budget,
14320
+ exclude: new Set(own ? [own.id] : []),
14321
+ own: own && ownEntry ? [{ sessionName: own.sessionName, id: own.id, version: replEntryVersion(ownEntry), text: own.text }] : [],
14322
+ });
14323
+ holdReplActivityCommit(replActivity, `tool:${toolCallId}`, report.commit);
14324
+ studioReport = report.text;
14325
+ }
14309
14326
  } catch {
14310
14327
  // The tool's own result stands without it.
14311
- return "";
14312
14328
  }
14329
+ const piReplReport = leaveToPiRepl
14330
+ ? await piReplActivity.report({
14331
+ budget: budget - (studioReport ? studioReport.length + 2 : 0),
14332
+ cwd: process.cwd(),
14333
+ own: toPiRepl && ownSend ? { sessionName: ownSend.sessionName, id: ownSend.id, text: ownSend.text, shown: [ownSend.status] } : undefined,
14334
+ })
14335
+ : "";
14336
+ return [piReplReport, studioReport].filter(Boolean).join("\n\n");
14313
14337
  };
14314
14338
  const REPL_ACTIVITY_GUIDELINES = replActivityMode === "off" ? [] : [
14315
14339
  "Studio tells you about new entries in its REPL sessions' shared records (the user's sends and notes, other agents', pi-repl's)"
@@ -14431,7 +14455,7 @@ export default function (pi: ExtensionAPI) {
14431
14455
  parameters: STUDIO_REPL_STATUS_TOOL_PARAMS,
14432
14456
  async execute(toolCallId, params) {
14433
14457
  const selected = selectStudioReplSessionForTool({ sessionName: params.sessionName, target: params.target });
14434
- if (params.sessionName && selected.session?.sessionName === params.sessionName) replActivity.used.add(params.sessionName);
14458
+ if (params.sessionName && selected.session?.sessionName === params.sessionName) useReplActivitySession(params.sessionName);
14435
14459
  const recordEntries = selected.session ? getStudioReplJournalEntries(selected.session.sessionName) : [];
14436
14460
  const lines = [
14437
14461
  `Active Studio REPL: ${studioReplSelection.session?.sessionName || "none"}`,
@@ -14531,7 +14555,7 @@ export default function (pi: ExtensionAPI) {
14531
14555
  // The agent's send is an explicit choice when admitted, before it waits for the
14532
14556
  // session's lease; only a ticket still current lets its result select (Sol, Astra).
14533
14557
  const ticket = studioReplSelection.choose({ session: selected.session });
14534
- replActivity.used.add(selected.session.sessionName);
14558
+ useReplActivitySession(selected.session.sessionName);
14535
14559
  // Every exit after admission tells the pages Studio's selection: the result when
14536
14560
  // it selects, otherwise a repl_state, so a failure can't leave them behind (Sol).
14537
14561
  let published = false;
@@ -14690,7 +14714,7 @@ export default function (pi: ExtensionAPI) {
14690
14714
  } : {}),
14691
14715
  });
14692
14716
  // What else the session's record holds that the agent hasn't been told, before its own result.
14693
- const activity = await prepareReplActivityForResult(toolCallId, { sessionName: currentSession.sessionName, id: journalEntry.id, text });
14717
+ const activity = await prepareReplActivityForResult(toolCallId, { sessionName: currentSession.sessionName, id: journalEntry.id, text, status: journalEntry.status });
14694
14718
  return {
14695
14719
  content: [{ type: "text", text: activity ? `${activity}\n\n${text}` : text }],
14696
14720
  details: {
@@ -21069,7 +21093,7 @@ export default function (pi: ExtensionAPI) {
21069
21093
  pi.on("before_agent_start", async () => {
21070
21094
  if (replActivityMode !== "on") return undefined;
21071
21095
  try {
21072
- const names = replActivitySessionNames();
21096
+ const names = replActivitySessionNames(piReplActivity.reports());
21073
21097
  if (!names.length) return undefined;
21074
21098
  const report = buildReplActivityReport(replActivity, await observeStudioReplActivity(names), { budget: REPL_ACTIVITY_RUN_START_BUDGET });
21075
21099
  if (!report.text) return undefined;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-studio",
3
- "version": "0.11.9",
3
+ "version": "0.11.10",
4
4
  "description": "Two-pane browser workspace for pi with prompt/response editing, annotations, critiques, active quiz, prompt/response history, live previews, and tmux-backed REPL/literate REPL workflows",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -63,6 +63,86 @@ const PERSON_CHANNELS = [
63
63
  { prefix: /^studio:(?:send|note):/, origin: "pi-studio", channel: "Pi Studio" },
64
64
  ];
65
65
 
66
+ /*
67
+ * pi-repl's view of its own sessions, when it's loaded in the same Pi (D5 of the shared design,
68
+ * agreed with pi-repl's session on 3 Nov; REPL_SESSION_RECORD_PROTOCOL.md, "One view per agent").
69
+ * Studio asks on Pi's event bus whether pi-repl is there, at each run's start and each REPL tool
70
+ * result. If it answers with protocol 2 or later, Studio leaves the `pi-repl-*` sessions to it:
71
+ * it tells pi-repl what Studio's pane shows and which of them Studio's agent used, and each of
72
+ * Studio's REPL results carries pi-repl's report of them, the agent's own send aside. Without
73
+ * that answer (no pi-repl, or 0.12.0's protocol 1, which can't report into Studio's results),
74
+ * Studio tells it nothing and tells its agent of every session itself, as before.
75
+ */
76
+ export const PI_REPL_RECORD_ACTIVITY_CHANNEL = "pi-repl:record-activity:v1";
77
+ // The first protocol whose pi-repl reports into Studio's results.
78
+ export const PI_REPL_REPORT_PROTOCOL = 2;
79
+ // How long a result waits for pi-repl's report; pi-repl gives its own reads 2 seconds.
80
+ export const PI_REPL_REPORT_DEADLINE_MS = 3_000;
81
+ // The sessions pi-repl's view takes: its own tools' sessions, as pi-repl names them.
82
+ export const PI_REPL_SESSION_NAME = /^pi-repl-[a-z0-9][a-z0-9-]{0,80}$/;
83
+
84
+ /** Whether pi-repl, when it reports, keeps this session's view. */
85
+ export function isPiReplSessionName(name) {
86
+ return typeof name === "string" && PI_REPL_SESSION_NAME.test(name);
87
+ }
88
+
89
+ /**
90
+ * Studio's side of the channel, on Pi's event bus (`pi.events`). pi-repl answers a probe at once,
91
+ * while the emit runs, and a report when it has read the records. A missing or failing bus is no
92
+ * answer.
93
+ */
94
+ export function createPiReplRecordActivityLink(events, { deadlineMs = PI_REPL_REPORT_DEADLINE_MS } = {}) {
95
+ let paneTold;
96
+ const emit = (message) => {
97
+ try {
98
+ events?.emit?.(PI_REPL_RECORD_ACTIVITY_CHANNEL, message);
99
+ return true;
100
+ } catch {
101
+ // Studio goes on as if pi-repl weren't there.
102
+ return false;
103
+ }
104
+ };
105
+ const reports = () => {
106
+ let protocol = 0;
107
+ emit({ kind: "probe", reply: (answer) => { protocol = Number(answer?.protocol) || 0; } });
108
+ return protocol >= PI_REPL_REPORT_PROTOCOL;
109
+ };
110
+ return {
111
+ /** Whether pi-repl answers now with a protocol that reports into Studio's results. */
112
+ reports,
113
+ /** A `pi-repl-*` session Studio's agent sent to or named. */
114
+ used(sessionName) {
115
+ if (isPiReplSessionName(sessionName) && reports()) emit({ kind: "used", sessionName });
116
+ },
117
+ /** The session Studio's pane shows, told when it changes: null for none, or one that isn't pi-repl's. */
118
+ pane(sessionName) {
119
+ const name = isPiReplSessionName(sessionName) ? sessionName : null;
120
+ if (name === paneTold || !reports()) return;
121
+ paneTold = name;
122
+ emit({ kind: "pane", sessionName: name });
123
+ },
124
+ /**
125
+ * pi-repl's report for one of Studio's results, within `budget`: of the sessions Studio's
126
+ * agent used and its pane, what the agent hasn't been told, its own send (`own`) aside.
127
+ * pi-repl holds it until its text is seen in what the model is given. Empty when there is
128
+ * nothing to tell or no reply in time; a late one is dropped, so its entries come round again.
129
+ * @param {{ budget: number, cwd?: string, own?: { sessionName: string, id: string, text: string, shown: string[] } }} request
130
+ * @returns {Promise<string>}
131
+ */
132
+ report({ budget, cwd, own }) {
133
+ return new Promise((resolve) => {
134
+ const timer = setTimeout(() => resolve(""), deadlineMs);
135
+ const reply = (text) => {
136
+ clearTimeout(timer);
137
+ resolve(typeof text === "string" ? text : "");
138
+ };
139
+ const ownSend = own && isPiReplSessionName(own.sessionName) ? { sessionName: own.sessionName, id: own.id, text: own.text, shown: [...own.shown] } : undefined;
140
+ if (!emit({ kind: "report", budget, ...(cwd ? { cwd } : {}), ...(ownSend ? { own: ownSend } : {}), reply })) reply("");
141
+ });
142
+ },
143
+ };
144
+ }
145
+
66
146
  /**
67
147
  * Who sent an entry and how, as D5 reads the record (P3): an agent's label; a person's name
68
148
  * under a person's request-ID prefix on its matching origin; otherwise "User", "via Pi Studio"
@@ -32,8 +32,13 @@ const sameSelection = (left, right) => (left.session || right.session
32
32
  ? sameReplSessionLifetime(left.session, right.session)
33
33
  : left.runtime === right.runtime);
34
34
 
35
- /** @template {ReplSessionLifetime} S */
36
- export function createReplSelection() {
35
+ /**
36
+ * `onChange`, when given, is called with the selected session (or null) whenever the selection
37
+ * changes, such as to tell pi-repl what Studio's pane shows (candidate 118).
38
+ * @template {ReplSessionLifetime} S
39
+ * @param {{ onChange?: (session: S | null) => void }} [options]
40
+ */
41
+ export function createReplSelection({ onChange } = {}) {
37
42
  /** @type {{ session?: S, runtime?: string | null }} */
38
43
  let selected = { runtime: null };
39
44
  let shown = 0;
@@ -44,8 +49,10 @@ export function createReplSelection() {
44
49
  /** @param {{ session?: S | null, runtime?: string | null }} target */
45
50
  const show = (target) => {
46
51
  const next = toSelection(target);
47
- if (!sameSelection(selected, next)) shown += 1;
52
+ const changed = !sameSelection(selected, next);
53
+ if (changed) shown += 1;
48
54
  selected = next;
55
+ if (changed) onChange?.(selected.session ?? null);
49
56
  };
50
57
 
51
58
  return {