@mindstudio-ai/remy 0.1.0

package/README.md

@@ -0,0 +1,314 @@
+# Remy
+
+A spec-building and coding agent for MindStudio apps.
+
+Remy helps users design, spec, build, and iterate on MindStudio projects. It runs locally in a terminal or as a headless subprocess in the MindStudio sandbox. It has tools for reading/writing specs and code, running shell commands, searching code, prompting users with structured forms, and (in the sandbox) TypeScript language server integration. LLM calls are routed through the MindStudio platform for billing and model routing.
+
+## Quick Start
+
+```bash
+# Make sure you're logged in (shares credentials with @mindstudio-ai/agent)
+mindstudio login
+
+# Navigate to your project
+cd my-mindstudio-app
+
+# Run remy
+npx remy
+```
+
+## Usage
+
+```
+$ remy [options]
+
+Options:
+  --api-key <key>    API key (overrides env/config)
+  --base-url <url>   Platform API base URL
+  --model <id>       Model ID (defaults to org's default model)
+  --headless         Run in headless mode (stdin/stdout JSON protocol)
+  --lsp-url <url>    LSP sidecar URL (enables LSP tools when set)
+```
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/clear` | Clear conversation history and start a fresh session |
+| `Escape` | Cancel the current turn (while agent is running) |
+
+### Session Persistence
+
+Remy saves conversation history to `.remy-session.json` in the working directory after each turn and before blocking on external tools. On restart, it picks up where you left off. Use `/clear` to start fresh.
+
+## Tools
+
+Remy's tool set depends on the project state. The sandbox tells remy whether the project has generated code in `dist/` via the `projectHasCode` field on messages.
+
+### Always Available
+
+| Tool | Description |
+|------|-------------|
+| `setViewMode` | Switch the IDE view (intake, preview, spec, code, databases, scenarios, logs) |
+| `promptUser` | Ask the user structured questions (form or inline display) |
+| `clearSyncStatus` | Clear sync flags after syncing spec and code |
+
+### Spec Tools
+
+Available in all sessions. Used for authoring and editing MSFM specs in `src/`.
+
+| Tool | Description |
+|------|-------------|
+| `readSpec` | Read a spec file with line numbers (paths must start with `src/`) |
+| `writeSpec` | Create or overwrite a spec file (creates parent dirs) |
+| `editSpec` | Heading-addressed edits (replace, insert, delete by heading path) |
+| `listSpecFiles` | List all files in the `src/` directory tree |
+
+### Code Tools
+
+Available when the project has generated code (`projectHasCode: true`).
+
+| Tool | Description |
+|------|-------------|
+| `readFile` | Read a file with line numbers |
+| `writeFile` | Create or overwrite a file (creates parent dirs) |
+| `editFile` | Targeted string replacement (must be unique match) |
+| `bash` | Run a shell command |
+| `grep` | Search file contents |
+| `glob` | Find files by pattern |
+| `listDir` | List directory contents |
+| `editsFinished` | Signal that file edits are complete for live preview |
+
+### LSP Tools (sandbox only)
+
+Available when `--lsp-url` is passed.
+
+| Tool | Description |
+|------|-------------|
+| `lspDiagnostics` | Type errors and warnings for a file, with suggested quick fixes |
+| `restartProcess` | Restart a managed sandbox process (e.g., dev server after npm install) |
+
+### Sync Tools (sync turns only)
+
+Available when the sandbox sends a `runCommand: "sync"` message.
+
+| Tool | Description |
+|------|-------------|
+| `presentSyncPlan` | Present a markdown sync plan to the user for approval (streams content) |
+
+### Tool Streaming
+
+Tools can opt into streaming via a `streaming` config on the tool definition:
+
+- **Content streaming** (writeSpec, writeFile, presentSyncPlan): Streams `tool_input_delta` events with progressive content as the LLM generates tool arguments. Tools can provide a `transform` function to customize the streamed output (e.g., writeSpec/writeFile compute a progressive diff).
+- **Input streaming** (promptUser): Streams progressive `tool_start` events with `partial: true` as structured input (like a questions array) builds up.
+- **No streaming** (all other tools): `tool_start` fires once when the complete tool arguments are available.
+
+Streaming is driven by `tool_input_delta` (Anthropic) or `tool_input_args` (Gemini) SSE events from the platform.
+
+## Architecture
+
+```
+User input
+  → Agent loop (src/agent.ts)
+    → POST /_internal/v2/agent/chat (SSE stream)
+      ← text, thinking, tool_input_delta, tool_input_args, tool_use events
+    → Execute tools locally in parallel
+      → External tools (promptUser, setViewMode, etc.) wait for sandbox response
+    → Send tool results back
+    → Loop until done
+    → Save session to .remy-session.json
+```
+
+The agent core (`src/agent.ts`) is a pure async function with no UI dependencies. The TUI (`src/tui/`) is an Ink + React layer on top. Headless mode (`src/headless.ts`) provides the same agent over a stdin/stdout JSON protocol for the sandbox.
+
+### Project Structure
+
+```
+src/
+  index.tsx              CLI entry point
+  agent.ts               Core tool-call loop (pure async, no UI)
+  api.ts                 SSE streaming client for platform API
+  parsePartialJson.ts    Partial JSON parser for streaming tool input
+  session.ts             .remy-session.json persistence
+  config.ts              API key/URL resolution
+  logger.ts              Structured logging
+  headless.ts            stdin/stdout JSON protocol for sandbox
+
+  prompt/
+    index.ts             System prompt builder (mode-aware)
+    actions/             Built-in prompts for runCommand actions
+      sync.md
+    static/              Behavioral instruction fragments
+      identity.md
+      intake.md
+      authoring.md
+      instructions.md
+      lsp.md
+      projectContext.ts  Reads manifest, spec metadata, file listing at runtime
+    compiled/            Platform docs distilled for agent consumption
+    sources/             Raw source docs (fetched + manual)
+
+  tools/
+    index.ts             Tool registry with streaming config interface
+    _helpers/
+      diff.ts            Unified diff generator
+      lsp.ts             LSP sidecar HTTP client
+    spec/                Spec and external tools
+      readSpec.ts
+      writeSpec.ts
+      editSpec.ts
+      listSpecFiles.ts
+      setViewMode.ts
+      promptUser.ts
+      clearSyncStatus.ts
+      presentSyncPlan.ts
+      _helpers.ts        Heading resolution, path validation
+    code/                Code tools (file editing, shell, search)
+      readFile.ts
+      writeFile.ts
+      editFile/
+        index.ts
+        _helpers.ts
+      bash.ts
+      grep.ts
+      glob.ts
+      listDir.ts
+      editsFinished.ts
+      lspDiagnostics.ts
+      restartProcess.ts
+
+  tui/                   Interactive terminal UI (Ink + React)
+    App.tsx
+    InputPrompt.tsx
+    MessageList.tsx
+    ThinkingBlock.tsx
+    ToolCall.tsx
+```
+
+### External Tools
+
+Some tools are resolved by the sandbox rather than executed locally. Remy emits `tool_start`, then waits for the sandbox to send back a `tool_result` via stdin. This is used for tools that require sandbox/user interaction:
+
+- `promptUser` — renders a form or inline prompt, blocks until user responds
+- `setViewMode` — switches the IDE view mode
+- `clearSyncStatus` — clears sync dirty flags and updates git sync ref
+- `presentSyncPlan` — renders a full-screen markdown plan for user approval
+
+### Project Instructions
+
+Remy automatically loads project-level agent instructions on startup. It checks for these files in order (first match wins):
+
+`CLAUDE.md`, `claude.md`, `.claude/instructions.md`, `AGENTS.md`, `agents.md`, `.agents.md`, `COPILOT.md`, `copilot.md`, `.copilot-instructions.md`, `.github/copilot-instructions.md`, `REMY.md`, `remy.md`, `.cursorrules`, `.cursorules`
+
+## Headless Mode
+
+Run `remy --headless` for programmatic control via newline-delimited JSON. This is how the sandbox C&C server runs remy as a managed child process.
+
+### Input Actions (stdin)
+
+Send JSON commands, one per line.
+
+#### `message`
+
+Send a user message to the agent.
+
+```json
+{"action": "message", "text": "fix the bug in auth.ts", "projectHasCode": true}
+```
+
+Fields:
+- `text` — the user message (required unless `runCommand` is set)
+- `projectHasCode` — controls tool availability (default: `true`)
+- `viewContext` — `{ mode, openFiles?, activeFile? }` for prompt context
+- `attachments` — array of `{ url, extractedTextUrl? }` for file attachments
+- `runCommand` — triggers a built-in action prompt (e.g., `"sync"`)
+
+When `runCommand` is set, the message text is replaced with a built-in prompt and the user message is marked as `hidden` in conversation history (sent to the LLM but not shown in the UI).
+
+#### `tool_result`
+
+Send the result of an external tool back to the agent.
+
+```json
+{"action": "tool_result", "id": "toolu_abc123", "result": "ok"}
+```
+
+#### `get_history`
+
+Return the full conversation history.
+
+```json
+{"action": "get_history"}
+```
+
+Messages with `hidden: true` were generated by `runCommand` actions and should not be displayed in the UI.
+
+#### `cancel`
+
+Cancel the current turn.
+
+```json
+{"action": "cancel"}
+```
+
+#### `clear`
+
+Clear conversation history and delete the session file.
+
+```json
+{"action": "clear"}
+```
+
+### Output Events (stdout)
+
+Events are emitted as newline-delimited JSON.
+
+#### Lifecycle Events
+
+| Event | Fields | Description |
+|-------|--------|-------------|
+| `ready` | | Headless mode initialized, ready for input |
+| `session_restored` | `messageCount` | Previous session loaded |
+| `session_cleared` | | Session history cleared |
+| `stopping` | | Shutdown initiated |
+| `stopped` | | Shutdown complete |
+
+#### Agent Events (streamed during message processing)
+
+| Event | Fields | Description |
+|-------|--------|-------------|
+| `turn_started` | | Agent began processing a message |
+| `text` | `text` | Streaming text chunk |
+| `thinking` | `text` | Agent's internal reasoning |
+| `tool_start` | `id`, `name`, `input`, `partial?` | Tool execution started. `partial: true` means more `tool_start` events will follow for this id (progressive input streaming). |
+| `tool_input_delta` | `id`, `name`, `result` | Progressive tool content (streaming tools only) |
+| `tool_done` | `id`, `name`, `result`, `isError` | Tool execution completed |
+| `turn_done` | | Agent finished responding |
+| `turn_cancelled` | | Turn was cancelled |
+| `error` | `error` | Error message |
+| `history` | `messages` | Response to `get_history` |
+
+### Logging
+
+In headless mode, structured logs go to **stderr**. Stdout is reserved for the JSON protocol. Log levels: `error`, `warn`, `info`, `debug`.
+
+In interactive mode, logs go to `.remy-debug.log` in the working directory (default level: `error`). Override with `--log-level`.
+
+## Development
+
+```bash
+npm install
+npm run build         # Build with tsup
+npm run dev           # Watch mode
+npm run typecheck     # Type check only
+```
+
+## Config
+
+Remy reads credentials from `~/.mindstudio-local-tunnel/config.json`, using the active environment's `apiKey` and `apiBaseUrl`.
+
+Resolution order for API key:
+1. `--api-key` flag
+2. `MINDSTUDIO_API_KEY` environment variable
+3. `~/.mindstudio-local-tunnel/config.json` (active environment)

package/dist/actions/publish.md

@@ -0,0 +1,12 @@
+This is an automated action triggered by the user pressing "Publish" in the editor.
+
+The user wants to deploy their app. Pushing to the `main` branch triggers a production deploy.
+
+Review the current state of the working tree — what has changed since the last commit, what's been committed since the last push, and the overall shape of recent work. Write a user-friendly changelog with `presentPublishPlan` — summarize what changed in plain language ("added vendor approval workflow", "fixed invoice totals", "updated the dashboard layout"). Reference specific code or file paths only when it helps clarity. This is what the user will see before deploying.
+
+If approved:
+- Stage and commit any uncommitted changes with a clean, descriptive commit message
+- Push to main
+- Let the user know their app is deploying
+
+If dismissed, acknowledge and do nothing.

package/dist/actions/sync.md

@@ -0,0 +1,19 @@
+This is an automated action triggered by the user pressing "Sync" in the editor.
+
+The user has manually edited files since the last sync. The `refs/sync-point` git ref marks the last known-good sync state. It's created using a temporary git index that captures the full working tree (including unstaged changes) as a tree object — so it represents exactly what the files looked like at sync time, not just what was committed.
+
+To see what the user changed, run: `git diff refs/sync-point -- src/ dist/`
+
+This compares the sync-point tree against the current working tree. Do not add `HEAD` or any other ref — the command as written diffs directly against the working tree, which is what you want.
+
+In the diff output: lines prefixed with `-` are what was in the file at last sync. Lines prefixed with `+` are the user's current edits. Sync should bring the other side in line with the `+` side.
+
+Analyze the changes and write a sync plan with `presentSyncPlan` — a clear markdown summary of what changed and what you intend to update. Write it for a human: describe changes in plain language ("renamed the greeting field", "added a note about error handling"), not as a list of file paths and code diffs. Reference specific code or file paths only when it helps clarity. The user will review and approve before you make changes.
+
+If approved:
+- If spec files (`src/`) changed, update the corresponding code in `dist/` to match
+- If code files (`dist/`) changed, update the corresponding spec in `src/` to match
+- If both changed, reconcile — spec is the source of truth for intent, but respect code changes that add implementation detail
+- When all files are synced, call `clearSyncStatus`
+
+If dismissed, acknowledge and do nothing.

package/dist/compiled/README.md

@@ -0,0 +1,100 @@
+# Compiled Prompt Fragments
+
+This directory contains distilled prompt fragments generated from the source
+docs in `docs/developer-guide/` (project root). These are loaded by `../index.ts` and injected
+into Remy's system prompt at runtime.
+
+## How to compile
+
+The compilation is done manually in a session with an LLM (Claude Code or
+similar). Work through the source docs and compile them into prompt-ready
+fragments.
+
+### Step 1: Compile with an LLM
+
+Open a session and ask it to work through the compilation. Give it these
+instructions:
+
+---
+
+**You will compile source docs into prompt fragments for Remy, a coding agent
+that builds MindStudio apps. The compiled fragments go in `src/prompt/compiled/`
+and are loaded into the agent's system prompt at runtime.**
+
+**Work through this one source file at a time, sequentially.** For each one:
+1. Read the source doc thoroughly
+2. Decide whether it should become its own fragment, be merged with a related
+   source, or be skipped entirely
+3. Present your draft of the compiled fragment
+4. Wait for review and feedback before moving to the next one
+
+Do not parallelize this work. Do not generate multiple fragments at once. Each
+fragment deserves careful attention — these are the instructions a coding agent
+will follow to build real products, and mistakes here propagate into every app
+it builds.
+
+Source files are in `docs/developer-guide/` at the project root.
+
+## How to think about compilation
+
+**Your audience is an LLM acting as a coding agent.** It needs to produce
+correct code, not learn concepts. Everything you write should be optimized
+for an agent that is actively building a MindStudio app and needs to get
+the details right.
+
+### What to keep
+
+- **API signatures, parameter types, return types, and code examples.**
+  These must be exactly right. The agent will copy these patterns directly
+  into the code it writes. A wrong type or a missing parameter means broken
+  code in production.
+- **Concrete examples, specific error cases, explicit constraints, enumerated
+  edge cases.** These are the highest-value content. A source doc that says
+  "ensure data integrity, including checking for duplicate keys, null foreign
+  references, and orphaned records" — the specific checks ARE the value.
+  Collapsing that to "ensure data integrity" loses the actionable detail.
+- **Tables and structured reference data.** Manifest fields, db predicates,
+  interface config schemas, role API methods — these are lookup references
+  the agent will consult while writing code. Keep them complete.
+- **Rules and constraints that affect correctness.** "Only packages declared
+  in package.json are available at runtime" is the kind of detail that
+  prevents hard-to-debug errors.
+
+### What to strip
+
+- **Setup instructions, installation steps, CLI commands.** The agent isn't
+  setting up a dev environment — it's writing code inside one.
+- **Platform internals and deployment pipeline details.** How the platform
+  builds and deploys is not the agent's concern.
+- **Conceptual explanations and philosophy.** "Why" something was designed
+  a certain way is rarely useful mid-task. Keep the "what" and "how."
+- **Marketing language, feature pitches, comparative positioning.**
+- **Cross-references to other docs** ("see Section X for details"). The
+  fragment should be self-contained.
+
+### Fragment format
+
+```markdown
+# Fragment Title
+
+Brief one-line context.
+
+## Section
+...content...
+```
+
+No YAML frontmatter. No meta-commentary. Just the reference content the
+agent needs. Each fragment should make sense on its own — the agent may
+not see all fragments in every session.
+
+---
+
+### Step 2: Review
+
+Read through the compiled fragments and verify code examples are accurate.
+The LLM may hallucinate API details — cross-check against the source docs.
+
+### Step 3: Commit
+
+The compiled fragments are committed to git. They're the snapshot the agent
+uses at runtime.

package/dist/compiled/auth.md

@@ -0,0 +1,77 @@
+# Roles & Auth
+
+MindStudio apps use role-based access control. Roles are defined in the manifest, assigned to users in the editor, and enforced in methods. The backend is the authority — methods enforce access control via `auth.requireRole()`. The frontend can read roles for conditional rendering, but enforcement always happens server-side.
+
+**Roles are optional.** Many apps don't need them — single-user apps, internal tools, simple utilities. If the app doesn't have multiple user types with different permissions, skip roles entirely. Only add them when the app explicitly needs to distinguish who can do what.
+
+## Defining Roles
+
+In `mindstudio.json`:
+
+```json
+{
+  "roles": [
+    { "id": "requester", "name": "Requester", "description": "Can submit vendor requests and purchase orders." },
+    { "id": "approver", "name": "Approver", "description": "Reviews and approves purchase orders." },
+    { "id": "admin", "name": "Administrator", "description": "Full access to all app functions." },
+    { "id": "ap", "name": "Accounts Payable", "description": "Processes invoices and payments." }
+  ]
+}
+```
+
+- `id` — kebab-case, used in code (`auth.requireRole('admin')`)
+- `name` — display name shown in the editor
+- `description` — what this role can do (useful for the agent and for users in the role assignment UI)
+
+Roles are synced to the platform on deploy. Adding or removing roles in the manifest creates or deletes them on the next push.
+
+## Backend Auth API
+
+```typescript
+import { auth } from '@mindstudio-ai/agent';
+```
+
+### `auth.requireRole(...roles)`
+
+Throws a 403 error if the current user doesn't have **any** of the specified roles. Use at the top of methods to gate access.
+
+```typescript
+auth.requireRole('admin');                // single role
+auth.requireRole('admin', 'approver');    // any of these
+```
+
+### `auth.hasRole(...roles)`
+
+Returns `boolean`. Same logic as `requireRole` but doesn't throw. Use for conditional behavior within a method.
+
+### `auth.userId`
+
+The current user's UUID. Always available.
+
+### `auth.roles`
+
+Array of role names assigned to the current user.
+
+### `auth.getUsersByRole(role)`
+
+Returns an array of user IDs that have the specified role. Useful for things like "notify all admins."
+
+## Frontend Auth
+
+```typescript
+import { auth } from '@mindstudio-ai/interface';
+
+auth.userId;            // current user's ID
+auth.name;              // display name
+auth.email;             // email address
+auth.profilePictureUrl; // URL or null
+```
+
+The frontend SDK provides display-only auth context. Role checking for UI purposes (showing/hiding elements) is done by reading role data from the backend:
+
+```typescript
+const { isAdmin, pendingCount } = await api.getDashboard();
+{isAdmin && <AdminPanel />}
+```
+
+The frontend is untrusted — anyone can modify JavaScript in the browser. Access control must be enforced server-side in methods. The frontend shows or hides UI based on role data from the backend, but the backend is the authority.