@mindstudio-ai/remy 0.1.305 → 0.1.307

package/dist/headless.js

@@ -3009,7 +3009,7 @@ var runScenarioTool = {
 var runMethodTool = {
   definition: {
     name: "runMethod",
-    description: 'Run a method in the dev environment and return the result. Use for testing methods after writing or modifying them. Returns output, captured console output, errors with stack traces, and duration. If it fails, check .logs/tunnel.log or .logs/requests.ndjson for more details. Returns synchronously \u2014 no need to sleep before checking results.\n\nBy default methods run unauthenticated. If the method is auth-gated (calls `auth.requireRole()`, filters on `auth.userId`, etc.), pass `userId: "testUser"` to run as the default test user \u2014 no scenario setup required, no userId lookup.',
+    description: 'Run a method in the dev environment and return the result. Use for testing methods after writing or modifying them. Returns output, captured console output, errors with stack traces, and duration. If it fails, check .logs/tunnel.log or .logs/requests.ndjson for more details. Returns synchronously \u2014 no need to sleep before checking results.\n\nBy default methods run unauthenticated. If the method is auth-gated (calls `auth.requireRole()`, filters on `auth.userId`, etc.), pass `userId: "testUser"` to run as the default test user \u2014 no scenario setup required, no userId lookup. For a method gated on `auth.requireRole("system")` \u2014 cron, webhook, and email work \u2014 pass `roles: ["system"]`; that works whether or not the app has auth.',
     inputSchema: {
       type: "object",
       properties: {
@@ -3028,7 +3028,7 @@ var runMethodTool = {
         roles: {
           type: "array",
           items: { type: "string" },
-          description: 'Optional. Role names for this request (e.g. ["admin"]). For auth-enabled apps, roles without a userId run as the dev test user holding exactly these roles \u2014 a real user row, so `auth.userId` and `requireRole` behave like production. For apps without auth, roles attach to an anonymous call. Applies to this call only.'
+          description: 'Optional. Role names for this request (e.g. ["admin"]). Roles without a userId bind to the dev test user holding exactly these roles \u2014 a real user row, so `auth.userId` and `requireRole` behave like production. `["system"]` is the exception and needs no user: it runs as the platform system identity, the same one cron, webhook, and email invocations get, so a system-gated method is testable in an app with no auth configured. Any other role requires an `auth` block in mindstudio.json \u2014 without one the app has no users to hold a role, and the call is rejected saying so. Applies to this call only.'
         }
       },
       required: ["method"]

package/dist/index.js

@@ -4200,7 +4200,7 @@ var init_runMethod = __esm({
     runMethodTool = {
       definition: {
         name: "runMethod",
-        description: 'Run a method in the dev environment and return the result. Use for testing methods after writing or modifying them. Returns output, captured console output, errors with stack traces, and duration. If it fails, check .logs/tunnel.log or .logs/requests.ndjson for more details. Returns synchronously \u2014 no need to sleep before checking results.\n\nBy default methods run unauthenticated. If the method is auth-gated (calls `auth.requireRole()`, filters on `auth.userId`, etc.), pass `userId: "testUser"` to run as the default test user \u2014 no scenario setup required, no userId lookup.',
+        description: 'Run a method in the dev environment and return the result. Use for testing methods after writing or modifying them. Returns output, captured console output, errors with stack traces, and duration. If it fails, check .logs/tunnel.log or .logs/requests.ndjson for more details. Returns synchronously \u2014 no need to sleep before checking results.\n\nBy default methods run unauthenticated. If the method is auth-gated (calls `auth.requireRole()`, filters on `auth.userId`, etc.), pass `userId: "testUser"` to run as the default test user \u2014 no scenario setup required, no userId lookup. For a method gated on `auth.requireRole("system")` \u2014 cron, webhook, and email work \u2014 pass `roles: ["system"]`; that works whether or not the app has auth.',
         inputSchema: {
           type: "object",
           properties: {
@@ -4219,7 +4219,7 @@ var init_runMethod = __esm({
             roles: {
               type: "array",
               items: { type: "string" },
-              description: 'Optional. Role names for this request (e.g. ["admin"]). For auth-enabled apps, roles without a userId run as the dev test user holding exactly these roles \u2014 a real user row, so `auth.userId` and `requireRole` behave like production. For apps without auth, roles attach to an anonymous call. Applies to this call only.'
+              description: 'Optional. Role names for this request (e.g. ["admin"]). Roles without a userId bind to the dev test user holding exactly these roles \u2014 a real user row, so `auth.userId` and `requireRole` behave like production. `["system"]` is the exception and needs no user: it runs as the platform system identity, the same one cron, webhook, and email invocations get, so a system-gated method is testable in an app with no auth configured. Any other role requires an `auth` block in mindstudio.json \u2014 without one the app has no users to hold a role, and the call is rejected saying so. Applies to this call only.'
             }
           },
           required: ["method"]

package/dist/prompt/skills/agentInterfaces.md

@@ -14,7 +14,7 @@ Guidance for designing conversational AI agents and their frontends. An agent in
 
 A good system prompt establishes who the agent is — personality, tone, judgment style, the kind of person they sound like. It doesn't enumerate every possible interaction or restate what tools already describe.
 
-Short and opinionated beats long and comprehensive. "Sounds like a sharp, organized friend — brief by default" gives the model more to work with than a page of behavioral rules. Define constraints through character, not checklists. Let the model's judgment work.
+Short and opinionated beats long and comprehensive. "Sounds like a sharp, organized friend — brief by default" gives the model more to work with than a page of behavioral rules. Define constraints through character, not checklists. Let the model's judgment work. Start minimal and add rules only for behaviors that actually misfire once the user has tested it — the thread log is the feedback loop, and `remy-admin agent threads get` reads a conversation verbatim (see "The agent CLI" below).
 
 Three things every compiled system prompt should carry, on top of the character:
 
@@ -112,17 +112,29 @@ await chat.deleteThread(thread.id);
 await chat.claimThread(thread.id);
 ```
 
-**Client tools** — a tool whose effect happens in the browser (open a sheet, navigate, highlight) is declared with `target: "client"` and a `name` + inline `inputSchema` instead of a `method` (names must not collide with method ids; the schema is authored — there's no method contract to derive it from). The agent's invocation arrives as the `client_tool_call` stream event / the `onClientToolCall` callback on `sendMessage`; run the action there. Fire-and-forget on this surface: the agent is told the action was displayed and keeps going — the user's next message closes the loop.
+**Client tools** — a tool whose effect happens in the browser (open a sheet, pick a file, confirm an action) is declared with `target: "client"` and a `name` + inline `inputSchema` instead of a `method` (names must not collide with method ids; the schema is authored — there's no method contract to derive it from). Register a handler and its **return value becomes the tool result**, so the agent learns what happened rather than assuming it did:
 
 ```js
-await chat.sendMessage(thread.id, text, {
-  onText: (delta) => append(delta),
-  onClientToolCall: (name, input) => {
-    if (name === 'showVerification') openVerifySheet(input);
-  },
+chat.registerClientTool('pickFile', async ({ prompt }) => {
+  const file = await openFilePicker(prompt);
+  return file ? { path: file.path } : { cancelled: true };
 });
+
+// Holding the turn on a person: the handler resolves when they decide.
+chat.registerClientTool(
+  'confirmDeploy',
+  ({ summary }) =>
+    new Promise((resolve) => {
+      showApprovalDialog(summary, {
+        onApprove: (note) => resolve({ approved: true, note }),
+        onReject: (reason) => resolve({ approved: false, reason }),
+      });
+    }),
+);
 ```
 
+The agent waits while the handler runs, up to 15 minutes — which is what makes confirm-before-acting a client tool rather than something you build a queue for. The SDK always answers, so the agent is never stuck: the return value, `{ error }` if the handler threw, `result_too_large` past ~32KB serialized, and `unhandled_client_tool` immediately when nothing is registered for that name; the platform supplies `client_timeout` if the window passes and `client_disconnected` if the page closes. Handlers live for the client's lifetime rather than one message. `onClientToolCall` on `sendMessage` behaves the same way for a one-off — whatever it returns is the result — and is consulted only when no handler is registered.
+
 **Sending messages (streaming):**
 
 `sendMessage` streams the agent's response via SSE. Use named callbacks for common events:
@@ -201,7 +213,7 @@ When the user sends a message, add it to the conversation immediately — don't
 
 ### Tool calls
 
-Show tool activity in the chat as a compact, inline status that appears when `onToolCallStart` fires and resolves when `onToolCallResult` arrives. Never show raw JSON, tool IDs, or internal details — just a human-readable description of what's happening.
+Show tool activity in the chat as a compact, inline status that appears when `onToolCallStart` fires and resolves when `onToolCallResult` arrives. Never show raw JSON, tool IDs, or internal details — just a human-readable description of what's happening. Tool calls should be interleaved into the conversation so they flow naturally as part of the agent's response.
 
 ### Input area
 
@@ -224,6 +236,21 @@ The chat UI uses the app's design system — colors, typography, voice from `@br
 - Avoid designs that look like dated messaging apps from 2015
 - Avoid robotic empty states ("Hello! I'm your AI assistant. How can I help you today?")
 
+## The agent CLI
+
+The `remy-admin agent` family is the conversation log — every thread the deployed agent has had, and each one's full transcript:
+
+```bash
+remy-admin agent threads list --limit 10   # newest activity first
+remy-admin agent threads get <threadId>    # full transcript: messages + tool calls
+```
+
+Transcripts are how you iterate on an agent: after the user tests it, read `agent threads get` for what was actually said and which tools ran with which arguments — a tool the agent never reached for, one it called with the wrong shape, a reply that ignored the result — and fix the system prompt and tool descriptions from that evidence rather than guesses.
+
+In the list, `toolErrorCount` and `hasTurnError` point at the conversations worth opening (a failed tool call; a turn that broke on a model error, rate limit, or credits instead of replying). `devSession` is true for your own test conversations through the dev tunnel, so you can tell them from real traffic.
+
+In a transcript, each message keeps the stored conversation's own shape: `user` for a person's message and also for a tool result (which carries `toolCallId`), `assistant` for the agent (carrying `toolCalls` when it asked for tools). Every method tool call also carries a `requestId` — `remy-admin requests get <requestId>` opens that call's input, output, `console.log` output and error, which is how you get from "the agent said something wrong" to the method that gave it bad data. Client tools run in the browser, so they have no requestId.
+
 ---
 
 # The wiring

package/dist/prompt/skills/auth.md

@@ -317,6 +317,8 @@ export async function regenerateCache(input: {}) {
 
 Web frontend calls (`/_/methods`), API interface calls (`/_/api`), and agent chat all run as the authenticated user — they don't get the system role unless the user has been explicitly assigned it. You can assign `system` to app users via the dashboard or SDK if they need to manually trigger these methods.
 
+The system role is a platform-minted identity, not a row in the app's users table, so it does not require auth. A cron-only app with no login and no user table can gate a method on `requireRole('system')` and it works. To exercise one in dev, run it with `roles: ["system"]` — `runMethod` gives it the same identity a real platform trigger gets, so the gate stays in place while you test.
+
 ## Login Page Example
 
 ```tsx
@@ -461,7 +463,7 @@ Auth works the same in dev/preview as in production — real verification codes
 
 All other emails and phone numbers receive real codes. There is no dev-mode bypass, no fake code, and no way to skip verification. When testing auth flows in the preview, use one of the test bypasses above or a real email/phone. (These dev bypasses work in dev sessions only and exist for you — they're distinct from *test accounts*, the platform setting for giving external reviewers a fixed-code login that works in production; see *Restricting Who Can Sign Up*.)
 
-This test account is the dev's standing identity: the preview's sign-in helper auto-fills it, the editor's Roles column edits its roles, and a scenario's `roles` field assigns roles to it after seeding. The `runMethod` tool's `userId: "testUser"` shortcut resolves to this same dev-bypass identity (as does `roles` without a `userId`). The platform find-or-creates a real users-table row for it on first call and caches the row's UUID for the rest of the dev session. **`auth.userId` inside the method is that UUID — not the literal string `"testUser"`.** The user row already exists, so don't try to insert it. If you need the UUID to seed app-specific rows that reference it (profiles, preferences, foreign keys), read it from any method response or query the users table directly: `SELECT id FROM users WHERE email = 'remy@mindstudio.ai'` (or `phone = '+15555555555'` for SMS-auth apps).
+This test account is the dev's standing identity: the preview's sign-in helper auto-fills it, the editor's Roles column edits its roles, and a scenario's `roles` field assigns roles to it after seeding. The `runMethod` tool's `userId: "testUser"` shortcut resolves to this same dev-bypass identity, as does `roles` without a `userId` (except `roles: ["system"]`, which is platform-minted and needs no user row — see *System Role*). The platform find-or-creates a real users-table row for it on first call and caches the row's UUID for the rest of the dev session. **`auth.userId` inside the method is that UUID — not the literal string `"testUser"`.** The user row already exists, so don't try to insert it. If you need the UUID to seed app-specific rows that reference it (profiles, preferences, foreign keys), read it from any method response or query the users table directly: `SELECT id FROM users WHERE email = 'remy@mindstudio.ai'` (or `phone = '+15555555555'` for SMS-auth apps).
 
 For **"Sign in with Remy"** apps (`auth.methods` is `["remy"]`, with no `email-code`/`sms-code`), `testUser` — and `setupBrowser`, and the editor's Roles column — resolve to **the developer's own delegated Remy identity**, not the `remy@mindstudio.ai` code-bypass user. `auth.userId` is still that user's real UUID, but the `remy@mindstudio.ai` email lookup above does not apply — read the UUID from a method response instead.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.305",
+  "version": "0.1.307",
   "description": "Remy coding agent",
   "repository": {
     "type": "git",