@turri-dev/cli 0.1.21 → 0.1.22

package/dist/chats.d.ts

@@ -67,9 +67,14 @@ export interface TurriHost {
     onNotice?(notice: Notice): void;
     /** A notice is over - answered, dismissed, or superseded by a newer one about its module: the host takes its card down. */
     onNoticeOver?(notice: Notice): void;
-    /** The sentinel's own tools beside turri's: a host's browser, say. */
+    /**
+     * The sentinel's own tools beside turri's - a host's browser, say - and its surface: where the person watches it use
+     * them, in the host's words. Given, the sentinel tries a release with those tools, keeping its shell for what they
+     * cannot show; absent, the person does not watch it, and the tools are only to test with as well.
+     */
     sentinel?: {
         tools?: ToolDefinition[];
+        surface?: string;
     };
 }
 /** What a chat's extension does for its chat when the session asks. */

package/dist/extension.js

@@ -522,7 +522,7 @@ function turriExtension(api, session, link) {
             }
         }
         if (isSentinel) {
-            const prompt = [event.systemPrompt, sentinelPrompt(cwd, { extraTools: hostSentinelTools.map((tool) => tool.name) }), projectConfigBlock(cwd), rulesBlock()].join("\n\n");
+            const prompt = [event.systemPrompt, sentinelPrompt(cwd, { extraTools: hostSentinelTools.map((tool) => tool.name), ...(host.sentinel?.surface !== undefined ? { surface: host.sentinel.surface } : {}) }), projectConfigBlock(cwd), rulesBlock()].join("\n\n");
             return { systemPrompt: host.systemPrompt !== undefined ? host.systemPrompt(prompt) : prompt };
         }
         return {

package/dist/sentinel.d.ts

@@ -27,9 +27,13 @@ export declare function pulseEndsBlock(sentinel: boolean): string;
  * does with it - and to tell the person so, and do nothing else about it.
  */
 export declare function landedNote(job: Job, released: DeployedProcess[]): string;
-/** Its identity and its task, in its system prompt in place of the conversation's. */
+/**
+ * Its identity and its task, in its system prompt in place of the conversation's. A host's `surface` - where the person
+ * watches it, in the host's words - stands in place of their not watching, and has it try a release with the host's tools.
+ */
 export declare function sentinelPrompt(cwd: string, options?: {
     extraTools?: string[];
+    surface?: string;
 }): string;
 /** What the sentinel is told of one finished pulse: the ledger's facts, the chats, and what was released. */
 export declare function sentinelBrief(job: Job, context: {

package/dist/sentinel.js

@@ -98,15 +98,25 @@ export function landedNote(job, released) {
         `Tell the person, in a line or two, what landed and that the sentinel is checking it${wasReleased ? " and testing the release" : ""}. Do nothing else about it: the pulse is the sentinel's now. Do not test it, release it, open it, run anything for it, or start other work because of it - whatever the project's guidance says to do when a pulse finishes.`,
     ].join("\n");
 }
-/** Its identity and its task, in its system prompt in place of the conversation's. */
+/**
+ * Its identity and its task, in its system prompt in place of the conversation's. A host's `surface` - where the person
+ * watches it, in the host's words - stands in place of their not watching, and has it try a release with the host's tools.
+ */
 export function sentinelPrompt(cwd, options = {}) {
     const guidance = readGuidance(cwd);
+    const tools = options.extraTools ?? [];
+    const surface = options.surface?.trim() ?? "";
+    const theirs = tools.length > 0 ? tools.join(", ") : "the host's tools";
     return [
         "<sentinel>",
         "You are turri's sentinel: a chat of turri's own, beside the chats the person talks to while they build their software",
         "with turri. Every pulse that finishes comes to you, as a message turri writes - what the pulse was, how it ended,",
-        "its ***plain diff, its log, and what was released. The person does not watch you: they are in another chat, and",
-        "hear from you only through notify_person.",
+        ...(surface === ""
+            ? ["its ***plain diff, its log, and what was released. The person does not watch you: they are in another chat, and", "hear from you only through notify_person."]
+            : [
+                "its ***plain diff, its log, and what was released. The person can watch you try a release, where the host shows it;",
+                "they talk to you in another chat, and hear what you find only through notify_person.",
+            ]),
         "",
         "For each pulse:",
         "1. Check how it went, from what turri tells you - and, when that is not enough, its log, the ledger (ledger, pulses),",
@@ -130,7 +140,19 @@ export function sentinelPrompt(cwd, options = {}) {
         "",
         "The person can talk to you here. When they tell you how to check - what to test, what to leave alone, where things",
         "run - keep it with keep_guidance, in their words, so it holds from now on.",
-        ...(options.extraTools !== undefined && options.extraTools.length > 0 ? ["", `The host gives you ${options.extraTools.join(", ")} to test with as well.`] : []),
+        ...(surface !== ""
+            ? [
+                "",
+                "Where the person watches you, in the host's words:",
+                "<surface>",
+                surface,
+                "</surface>",
+                `Try a release with ${theirs}, where the person can watch. Keep your shell for what those cannot show - logs, exit`,
+                "codes, files.",
+            ]
+            : tools.length > 0
+                ? ["", `The host gives you ${theirs} to test with as well.`]
+                : []),
         "</sentinel>",
         ...(guidance !== "" ? ["", "<guidance>", "What the person told you to keep in mind:", guidance, "</guidance>"] : []),
     ].join("\n");

package/docs/hosting.md

@@ -86,7 +86,10 @@ const turri = await createTurri({
   onNotice: (notice) => {},            // the sentinel puts something to the person: draw it in notice.chat
   onNoticeOver: (notice) => {},        // ...answered, dismissed or superseded: take its card down
   onConcluded: (conclusion) => {},     // the sentinel is done with a pulse: holds or wrong, told to conclusion.chat
-  sentinel: { tools: [browserTool] },  // the sentinel's own tools, beside turri's: what it tests a release with
+  sentinel: {
+    tools: [browserTool],               // the sentinel's own tools, beside turri's: what it tests a release with
+    surface: "...",                     // where the person watches it use them, in the host's words
+  },
 });
 
 const chat = await turri.openChat();   // { id, title, status, shown, session }: a fresh chat, shown
@@ -123,6 +126,7 @@ The [sentinel](sentinel.md) is one of the host's chats: turri opens it with the
 - **Conclusions.** As the sentinel is done with each pulse - all well or not - `onConcluded({ job, verdict: "holds" | "wrong", summary, module, pulse, chat })` comes, and the chat `chat` names - the one `focus` last named, as for a notice - shows it and its agent says so in a line.
 - **Its model.** The `sentinel` role in `models:`, else the chat's model - `models.chat`, else `harness-model` - with its thinking, set as its chat opens: not pi's default model, which may not be one the project's provider has. What the person then picks in its chat stands. See [its model](sentinel.md#its-model).
 - **Its tools.** `sentinel: { tools }` are [pi](https://pi.dev) tool definitions registered in the sentinel's chat alone and told to it in its prompt - the host's browser, say, for it to test a release with. The rest of the host's `extensions` are built into its chat too, but their tools are refused it: only its own read, and these.
+- **Its surface.** `sentinel: { surface }` is where the person watches the sentinel use those tools, in the host's own words - the preview pane its browser and terminal show in, say. Given, the sentinel's prompt has it, as a `<surface>` block, in place of the person not watching it: it tries a release with the host's tools, where the person can watch, and keeps its own shell for what those cannot show - logs, exit codes, files. Without it, the person does not watch the sentinel, and the host's tools are only to test with as well. As for the conversation, `systemPrompt` has the last word on its prompt.
 - **Its surface.** What it is told is its own prompt, not the conversation's: the host's `surface` is not in it; `systemPrompt` still has the last word.
 
 A surface for a desktop app might read:

package/docs/sentinel.md

@@ -47,7 +47,7 @@ The `sentinel` role in `models:` - else the chat's model, `models.chat` else `ha
 
 ## In a host
 
-A host sees the sentinel as one of its chats - `role: "sentinel"` in `chats()` and `onChats` - and never has focus moved to it. Each notice comes as `onNotice(notice)` - `{ id, chat, module, pulse, job, severity, summary, evidence, actions, state }`, `chat` the one to draw it in - and `onNoticeOver(notice)` when it is answered or superseded; `notices()` lists those open. `answer(id, { action } | { steer } | { dismiss: true })` answers one, as the terminal's dialog does. `onConcluded({ job, verdict: "holds" | "wrong", summary, module, pulse, chat })` comes as it is done with a pulse, all well or not - told to the chat `chat` too. The sentinel's own tools - a browser - are given with `createTurri({ sentinel: { tools } })`, and it is told it has them. See [running turri in a host](hosting.md#the-sentinel).
+A host sees the sentinel as one of its chats - `role: "sentinel"` in `chats()` and `onChats` - and never has focus moved to it. Each notice comes as `onNotice(notice)` - `{ id, chat, module, pulse, job, severity, summary, evidence, actions, state }`, `chat` the one to draw it in - and `onNoticeOver(notice)` when it is answered or superseded; `notices()` lists those open. `answer(id, { action } | { steer } | { dismiss: true })` answers one, as the terminal's dialog does. `onConcluded({ job, verdict: "holds" | "wrong", summary, module, pulse, chat })` comes as it is done with a pulse, all well or not - told to the chat `chat` too. The sentinel's own tools - a browser - are given with `createTurri({ sentinel: { tools } })`, and it is told it has them. `sentinel: { surface }` says, in the host's words, where the person watches it use them: then it tries a release with them, where the person can watch, and keeps its shell for what they cannot show - logs, exit codes, files. Without it, the person does not watch the sentinel, and the host's tools are only to test with as well. See [running turri in a host](hosting.md#the-sentinel).
 
 ## In the ledger
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "license": "MIT",
   "type": "module",
   "repository": {