Assistant instructions and conversation scripts

Both createAssistant(ctx, options) and each assistants entry accept instructions?: boolean and scripts?: boolean, defaulting to false.

persist?: boolean (default true): set false for assistants about live documents; their conversations stay in memory and start empty on each app run. Only opted-in assistants receive the corresponding header controls. ai-help does not opt in and keeps its existing toolbar.

import type { AiApi, ConversationScript } from "@app/kernel/plugin-api";
const ai = ctx.useApi("ai"); // inferred AiApi
const assistant = ai?.createAssistant(ctx, {
  assistantId: "model", title: "my-plugin.model.title",
  instructions: true, scripts: true,
});

Instructions opens a multiline editor with Save/Cancel. The committed text is memory-only, scoped to the panel, and added to every system prompt under Project specific instructions: with priority over generic guidelines. ai.getInstructions(panelId) and ai.setInstructions(panelId, text) work even if the button is hidden. The handler for ai/instructions.changed stores { panelId, text }; another plugin can listen to that event to persist the text in its own document and use setInstructions when restoring it.

Export script saves the active conversation as Markdown using the platform file service. Replay script accepts pasted Markdown or an opened .md file. Loading restores the script instructions and starts a new conversation without sending any request. The panel then shows Next question and Run to the end controls, plus progress and the next question. Next question waits for a completed answer (including tool approvals) before allowing another step; Run to the end sends the remaining questions in order. Recorded answers and introductory prose are never executed or sent back to the model. Action tools still require explicit approval; playback waits for all pending actions. Stop, session changes, provider errors and failed tools halt playback.

The pure helpers are exposed as ai.formatScript({ title, instructions, turns: [{ question, answer }] }) and ai.parseScript(markdown) (returning { title, instructions, questions }). The typed API also exposes ai.exportScript(panelId) and ai.replayScript(panelId, markdown). replayScript only loads the script; emit ai/script.next or ai/script.all with { assistantId: panelId } to execute one question or all remaining questions. The format uses an H1 title, a fenced **Project specific instructions:** block, repeated fenced **User:** questions and **Assistant:** answers; existing scripts with inline Assistant answers are accepted. Fences adapt to embedded backticks; unclosed blocks are rejected.

Notes (TSX) includes a declarative notes-tsx:assistant panel with both options enabled and depends on ai as well as documents. Its read-only notes_current_context tool reads currently open notes and their live text, tasks, status labels, dates, subtasks and precedences, highlighting the active document. It shares AI Support’s configured provider; its read tool never edits notes, while explicitly offered semantic actions remain subject to approval. Reload Notes after updating its bundle to see the assistant in the left rail.