Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,8 @@ A paired client can list your registered projects and their sessions (with what
notes, message sessions, spawn background ones and follow them live, read your inbox (what sessions said to you
and how spawns ended) and answer a session's question with `say` and `re`, and chat with Claude Code in a
project: read-only in your checkout, or with edits in a worktree and branch of its own that you merge when you
want it. It names projects, never paths, and nothing outside a registered project is visible.
want it. Or chat with the Rinai agent for a project's board (`board: true`): it reads and changes the board
through `gh rinai` and has nothing else, no shell and no file access. It names projects, never paths, and nothing outside a registered project is visible.
The wire is in [docs/yap.md](docs/yap.md#remote), and `sdk/remote.ts` is a typed client for it with no
dependencies:

Expand Down
26 changes: 21 additions & 5 deletions docs/yap.md
Original file line number Diff line number Diff line change
Expand Up @@ -308,20 +308,36 @@ token was given it by the user.

| Verb | Body | Answer |
|---|---|---|
| `hello` | | `{ protocol: "yap", version, verbs, extensions }`; the remote extensions are `board`, `spawn`, `doing`, `inbox` and `chat` |
| `projects` | | `[{ name, base }]` |
| `hello` | | `{ protocol: "yap", version, verbs, extensions }`; the remote extensions are `board`, `spawn`, `doing`, `inbox`, `chat` and `board-chat` |
| `projects` | | `[{ name, base, board }]`; `board` is the project's Rinai board, `owner/repo`, or null |
| `sessions` | | live sessions in projects: `[{ project, id, name, at, files, doing?, unanswered }]`; `unanswered` is `[{ id, kind, text }]`, its questions and blockers to the user nobody has answered |
| `spawns` | `id`?, `since`? | background sessions in projects, newest first: `[{ project, id, name, task, from, started, done?, ok?, result?, steps }]`; `id` picks one and adds its `log` after line `since`, as locally |
| `notes` | `project` | the project's board |
| `note` | `project`, `text` | pins a note |
| `say` | `project`, `text`, `to`?, `kind`?, `re`? | messages a session there, or all of them: `{ id, to, woke }`. With `re`, the id (or 8 characters of it) of a session's question or blocker, it answers it: with no `to` it goes to the asker and leaves its `unanswered` |
| `inbox` | `since`?, `project`? | what sessions said to the user and how background sessions ended, oldest first, after `since`: `[{ project, id, seq, kind, origin, from, sender, text, at, re?, ok? }]`, every project or one. Poll it with the highest `seq` you have |
| `spawn` | `project`, `text` | starts a background session on the task: `{ id }` |
| `chat` | `project`, `text`, `thread`?, `edits`? | a message in a chat, a new thread when none is named: `{ thread }` at once (an edits thread's worktree is made behind it; a failure comes as an `error` event). 409 while the thread is still answering |
| `chat.read` | `thread`, `after`? | `{ thread, project, branch, busy, events }`, the events numbered after `after`: `you`, `text`, `tool` (one line per tool call), `done`, `error` |
| `chat` | `project`, `text`, `thread`?, `edits`?, `board`? | a message in a chat, a new thread when none is named: `{ thread }` at once (an edits thread's worktree is made behind it; a failure comes as an `error` event). 409 while the thread is still answering |
| `chat.read` | `thread`, `after`? | `{ thread, project, branch, board, busy, events }`, the events numbered after `after`: `you`, `text`, `tool` (one line per tool call), `done`, `error` |
| `chat.stop` | `thread` | stops the turn running |
| `chat.drop` | `thread` | forgets the thread; an edits thread's worktree and branch are removed, unmerged work with them |
| `chats` | `project`? | threads, newest first: `[{ thread, project, branch, busy, at, title }]` |
| `chats` | `project`? | threads, newest first: `[{ thread, project, branch, board, busy, at, title }]` |

A **board chat** (`board: true`, set when the thread starts; a daemon that has them says `board-chat` in `hello`, and an older one would start a read chat instead, so a client checks) is the Rinai agent for the project's board. It has
no built-in tool at all, no Read and no Bash: only `src/board.ts`, an MCP server whose tools (board, search,
brief, goals, pulse, cycle; move, priority, claim, cycle_add, cycle_remove, cycle_order, file, comment, update,
goal, ungoal) each run `gh rinai -R <that board> <verb>` as an argument list, never through a shell; a comment,
an update or a body goes on stdin, and a short argument with a double quote and no space (which gh on Windows
drops) is refused. gh's own sign-in variables (`GH_TOKEN`, `GH_HOST`, `GH_CONFIG_DIR` and the like) and
`RINAI_URL` reach it. It runs
outside the checkout, in `~/.yap/chats/<project>/board`, with `--permission-mode dontAsk` and no settings file
read; the user's settings come in through `--settings` less their permissions, hooks and MCP servers, so a Bedrock or
helper sign-in and their model still work. Claude Code's Bash rules could not hold it: commands Claude Code judges read-only, `cat`
and a `; whoami` after an allowed command among them, ran past the allow list, so a chat with Bash or Read could
post a file in a comment. A comment injected on a public repo can reach this board's own cards and no further.
It is told to read the board before answering, to make a change the user asked for in so many words, and to list
the changes for a broad ask (reorganize, triage) and wait for a go. A project with no GitHub remote has no board,
and the call says so.

A chat is one Claude Code session per thread: the first turn names it, every later one resumes it. Without
`edits` it reads and searches the project's own checkout and changes nothing. With `edits` (set when the thread
Expand Down
8 changes: 7 additions & 1 deletion sdk/remote.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ export interface Hello {
export interface Project {
name: string
base: string
/** The project's Rinai board, `owner/repo`, when it has a GitHub remote. */
board?: string | null
}

export interface Session {
Expand Down Expand Up @@ -88,6 +90,8 @@ export interface ChatRead {
project: string
/** The thread's worktree branch when it may edit, else null. */
branch: string | null
/** A board chat's board: the Rinai agent for it. */
board?: string | null
busy: boolean
events: ChatEvent[]
}
Expand All @@ -96,6 +100,8 @@ export interface ChatThread {
thread: string
project: string
branch: string | null
/** A board chat's board: the Rinai agent for it. */
board?: string | null
busy: boolean
at: number
title: string
Expand Down Expand Up @@ -203,7 +209,7 @@ export class Yap {
* A message in a chat with Claude Code on the machine; a new thread when none is named. Read-only in the project,
* unless the thread starts with `edits`: then it runs in a worktree and `yap/chat-*` branch of its own.
*/
chat(project: string, text: string, o: { thread?: string; edits?: boolean } = {}) {
chat(project: string, text: string, o: { thread?: string; edits?: boolean; board?: boolean } = {}) {
return this.verb<{ thread: string }>('chat', { project, text, ...o })
}

Expand Down
69 changes: 54 additions & 15 deletions src/agent.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
import { homedir, tmpdir } from 'node:os'
import { join } from 'node:path'
import { GH_ENV } from './board'
import { childEnv } from './env'
import type { Agent, AgentRun, AgentRunner } from './ports'

Expand All @@ -17,7 +18,9 @@ export class Agents implements AgentRunner {
* report under the peer's id through YAP_SESSION, the way a Claude peer's do under --session-id.
*/
export class CodexCli implements AgentRunner {
async run({ cwd, prompt, signal, peer }: AgentRun) {
async run({ cwd, prompt, signal, peer, only }: AgentRun) {
// Codex has no way to drop its own tools for an MCP server's alone: a board run here would not be confined.
if (only) throw new Error('a board chat runs on Claude Code only')
const dir = mkdtempSync(join(tmpdir(), 'yap-codex-'))
const last = join(dir, 'last.txt')
try {
Expand Down Expand Up @@ -50,22 +53,19 @@ function codexAuth() {

/** Headless Claude Code. One process per run, so every run starts with a clean context. */
export class ClaudeCli implements AgentRunner {
async run({ cwd, prompt, readOnly, schema, signal, onActivity, onText, peer, chat }: AgentRun) {
const args = ['claude', '-p', '--output-format', 'stream-json', '--verbose']
// No human is there to answer a prompt: anything that would ask is denied.
args.push('--permission-prompts', 'none', '--strict-mcp-config')
// A chat keeps its session so the next message resumes it; every other run starts clean and leaves nothing.
if (chat) args.push(chat.resume ? '--resume' : '--session-id', chat.session, '--append-system-prompt', chat.system)
else args.push('--no-session-persistence')
if (readOnly) args.push('--tools', 'Read,Grep,Glob')
else args.push('--permission-mode', 'auto')
if (schema) args.push('--json-schema', JSON.stringify(schema))
if (peer) args.push('--session-id', peer)
async run(o: AgentRun) {
const { cwd, prompt, signal, onActivity, onText, peer, chat } = o
// Only a board run reads no settings file, so only it needs the user's carried in.
const args = claudeArgs(o, o.only ? carried() : {})
// A board run's folder is yap's own and may not exist yet: it is where the run stands, nothing is read there.
if (o.only) mkdirSync(cwd, { recursive: true })

// YAP_AGENT keeps the crew out of the session registry: its hooks see it and stay quiet. A peer's hooks report,
// so they need to find this daemon.
const yap = peer ? Object.fromEntries(['YAP_HOME', 'YAP_PORT'].filter(k => process.env[k]).map(k => [k, process.env[k]!])) : { YAP_AGENT: '1' }
const p = Bun.spawn(args, { cwd, stdin: 'pipe', stdout: 'pipe', stderr: 'pipe', signal, windowsHide: true, env: { ...childEnv(), ...auth(), ...yap } })
// A board run's server is gh: a gh signed in by environment needs that environment. The run has no shell to read it.
const gh = o.only ? Object.fromEntries(GH_ENV.filter(k => process.env[k]).map(k => [k, process.env[k]!])) : {}
const p = Bun.spawn(args, { cwd, stdin: 'pipe', stdout: 'pipe', stderr: 'pipe', signal, windowsHide: true, env: { ...childEnv(), ...auth(), ...yap, ...gh } })
p.stdin.write(prompt)
p.stdin.end()
const stderr = new Response(p.stderr).text()
Expand Down Expand Up @@ -106,6 +106,45 @@ export class ClaudeCli implements AgentRunner {
}
}

/** The `claude` command line for a run. Pure, so the check can read it. */
export function claudeArgs({ readOnly, only, schema, peer, chat }: AgentRun, settings: Record<string, unknown> = {}) {
const args = ['claude', '-p', '--output-format', 'stream-json', '--verbose']
// No human is there to answer a prompt: anything that would ask is denied.
args.push('--permission-prompts', 'none', '--strict-mcp-config')
// A chat keeps its session so the next message resumes it; every other run starts clean and leaves nothing.
if (chat) args.push(chat.resume ? '--resume' : '--session-id', chat.session, '--append-system-prompt', chat.system)
else args.push('--no-session-persistence')
if (only) {
// No built-in tool, only the server's. dontAsk refuses whatever is not allowed, and no settings file is read: a
// user's defaultMode bypassPermissions or allow rules would otherwise win. Their sign-in settings come back in.
args.push('--tools', '', '--mcp-config', JSON.stringify({ mcpServers: { [only.name]: { command: only.command, args: only.args } } }))
args.push('--allowedTools', `mcp__${only.name}`, '--permission-mode', 'dontAsk', '--setting-sources', '')
if (Object.keys(settings).length) args.push('--settings', JSON.stringify(settings))
} else if (readOnly) args.push('--tools', 'Read,Grep,Glob')
else args.push('--permission-mode', 'auto')
if (schema) args.push('--json-schema', JSON.stringify(schema))
if (peer) args.push('--session-id', peer)
return args
}

/**
* What of the user's Claude Code settings a run that reads none keeps: everything but what could widen it. How they
* sign in (apiKeyHelper, Bedrock's awsAuthRefresh, forceLoginMethod, a gateway's env), their model, stay; their
* permissions, hooks and MCP servers do not.
*/
export function carriedFrom(s: Record<string, unknown>) {
const WIDEN = ['permissions', 'hooks', 'enableAllProjectMcpServers', 'enabledMcpjsonServers', 'disabledMcpjsonServers', 'mcpServers', 'statusLine', 'enabledPlugins', 'extraKnownMarketplaces']
return Object.fromEntries(Object.entries(s).filter(([k]) => !WIDEN.includes(k)))
}
function carried() {
try {
const dir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude')
return carriedFrom(JSON.parse(readFileSync(join(dir, 'settings.json'), 'utf8')))
} catch {
return {}
}
}

/**
* Claude's own credentials, if it signs in with one. They reach the shell commands it runs too: Claude Code's
* CLAUDE_CODE_SUBPROCESS_ENV_SCRUB would keep them out, but in 2.1.310 it also makes auto mode deny every write.
Expand Down
Loading
Loading