@nevescloud/pip 3.8.3 → 3.9.0

package/README.md

@@ -210,4 +210,4 @@ For a turn loop, tool dispatch, history, and an Anthropic provider, pair pip-cor
 
 ## Demo
 
-`docs/index.html` is a standalone demo wiring two stub providers (echo + reverse) through the runtime. Open it locally to play with the slash autocomplete, `/model` switching, and the chat shell without needing an API key.
+`docs/index.html` is a standalone demo wiring three stub providers (`echo`, `reverse`, `danger`) through the runtime. Open it locally to play with the slash autocomplete, `/model` switching, and the chat shell without needing an API key. The `danger` stub fires a `delete_thing` tool_use that's gated by a `preToolUse` hook (Run/Cancel via `askInChat`) — a working example of the runtime's hook events.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevescloud/pip",
-  "version": "3.8.3",
+  "version": "3.9.0",
   "description": "Floating assistant bubble + panel + chat runtime. ESM, no build.",
   "type": "module",
   "main": "pip-core.esm.js",

package/runtime.esm.js

@@ -51,6 +51,24 @@ export function createRuntime({
     }
   }
 
+  // Hook-style emit: awaits each handler in registration order and returns
+  // the first non-undefined return value. Lets host code on `preTurn` and
+  // `preToolUse` block, defer (e.g. await an askInChat approval), or mutate
+  // the action without a separate `hook(...)` channel.
+  async function emitAsync(name, payload) {
+    const set = listeners.get(name);
+    if (!set) return undefined;
+    for (const fn of set) {
+      try {
+        const ret = await fn(payload);
+        if (ret !== undefined) return ret;
+      } catch (e) {
+        console.warn(`[pip-runtime] handler for "${name}" threw`, e);
+      }
+    }
+    return undefined;
+  }
+
   function on(name, handler) {
     if (!listeners.has(name)) listeners.set(name, new Set());
     listeners.get(name).add(handler);
@@ -111,6 +129,26 @@ export function createRuntime({
     abortCtrl = new AbortController();
     emit('turnStart', { turnEl, userText });
 
+    // `added` snapshot: anything pushed after this index was produced by
+    // *this* turn (assistant messages + tool roundtrips). The user message
+    // was pushed in onSubmit before we entered, so it's excluded — hosts
+    // already have it in payload.userText.
+    const startIdx = messages.length;
+
+    // preTurn fires once per user message, after history is sealed and
+    // before any provider call. Handler can return { system } to override
+    // the system prompt for this turn loop — the use case is per-turn RAG
+    // injection that depends on userText. Returning undefined falls through
+    // to the configured systemFn().
+    const baseSystem = systemFn();
+    const preTurn = await emitAsync('preTurn', {
+      turnEl,
+      userText,
+      messages: messages.slice(),
+      system: baseSystem,
+    });
+    const turnSystem = preTurn?.system !== undefined ? preTurn.system : baseSystem;
+
     let buffer = '';
     let lastStopReason = null;
 
@@ -119,7 +157,7 @@ export function createRuntime({
         const stream = currentProvider({
           messages: messages.slice(),
           tools: buildToolList(),
-          system: systemFn(),
+          system: turnSystem,
           signal: abortCtrl.signal,
           // turnEl + setReplyText let renderer-shaped providers (e.g. the
           // local transformers wrapper) paint progress bars and <think>
@@ -176,13 +214,34 @@ export function createRuntime({
             emit('toolResult', { turnEl, name: tu.name, ok: false, error: err, id: tu.id });
             continue;
           }
+
+          // preToolUse fires per tool_use before the handler runs. Handler
+          // can return { approve: false, reason } to short-circuit (useful
+          // for human-in-the-loop gating via askInChat) or { input } to
+          // mutate the args. Falling through preserves the original call.
+          const directive = await emitAsync('preToolUse', {
+            turnEl, name: tu.name, input: tu.input, id: tu.id,
+          });
+          if (directive?.approve === false) {
+            const reason = directive.reason || `Denied by preToolUse hook`;
+            toolResults.push({
+              type: 'tool_result',
+              tool_use_id: tu.id,
+              content: reason,
+              is_error: true,
+            });
+            emit('toolResult', { turnEl, name: tu.name, ok: false, error: reason, id: tu.id });
+            continue;
+          }
+          const effectiveInput = directive?.input !== undefined ? directive.input : tu.input;
+
           try {
             const ctx = {
               signal: abortCtrl.signal,
               turnId: tu.id,
               runtime: handle,
             };
-            const result = await tool.handler(tu.input, ctx);
+            const result = await tool.handler(effectiveInput, ctx);
             const content = typeof result === 'string' ? result : JSON.stringify(result);
             toolResults.push({ type: 'tool_result', tool_use_id: tu.id, content });
             emit('toolResult', { turnEl, name: tu.name, ok: true, result, id: tu.id });
@@ -202,6 +261,13 @@ export function createRuntime({
 
       trim();
       persist();
+      emit('postTurn', {
+        turnEl,
+        userText,
+        added: messages.slice(startIdx),
+        text: buffer.trim(),
+        stopReason: lastStopReason,
+      });
       return buffer.trim();
     } catch (err) {
       if (err?.name === 'AbortError') {