precis

1import type { EngineInterface, Register } from 'claude-code'
2
3import { drawOffer, platformTarget, refreshOffer } from './switch'
4
5const TOOL = 'mcp__precis__summarize'
6
7/** What the engine answers a call of a plugin's tool that its permission check let through. */
8const UNSERVED = 'no tool.call hook answered this call'
9
10/** The tool's arguments, as the model gives them and as the permission check reads them. */
11type Args = { path?: string; token_budget?: number }
12
13/** This machine's target, and the binary bundle this plugin carries, if any. */
14type Platform = { target: string | undefined; bundle: { target: string; path: string } | undefined }
15
16/** What the session needs once: where it runs, and the binary that runs there. */
17type Setup = { platform: Promise<Platform>; binary: Promise<string | undefined> }
18
19export const register: Register = (on, options) => {
20  const tokenBudget = Number(options.token_budget)
21  let setup: Setup | undefined
22  // The input each call's permission check read, by `tool_use_id`: a
23  // PreToolUse hook's rewrite shows here and not on the call's own `e`.
24  const checked = new Map<string, Args>()
25
26  drawOffer(on)
27
28  on('session.start', async ($, e, next) => {
29    const bin = await (setup ??= setUp($)).binary
30    if (bin !== undefined) {
31      await $.tool.register({
32        name: 'summarize',
33        description: await about($, bin),
34        inputSchema: {
35          type: 'object',
36          properties: {
37            path: {
38              type: 'string',
39              description: 'Directory or file to summarize. Default: the working directory.',
40            },
41            token_budget: {
42              type: 'integer',
43              minimum: 1,
44              description: `Output budget in o200k_base tokens. Default: ${tokenBudget}.`,
45            },
46          },
47        },
48        isDeferred: false,
49      })
50    }
51    return next(e)
52  })
53
54  on('tool.check', { tool: TOOL }, ($, e, next) => {
55    if (e.tool_use_id !== undefined) checked.set(e.tool_use_id, e.input as Args)
56    return next(e)
57  })
58
59  on('tool.call', { tool: TOOL }, async ($, e, next) => {
60    const args = e as Args
61    const bin = await (setup ??= setUp($)).binary
62    if (bin === undefined) return { deny: 'precis has no binary to run' }
63    const path = await expandHome($, args.path ?? '.')
64    const read = await readDecision($, path)
65    if ('deny' in read) return read
66    if (read.decision === 'ask') {
67      const decided = await next(e)
68      const input = checked.get(e.tool_use_id)
69      checked.delete(e.tool_use_id)
70      if (decided.isError !== true || !decided.text?.includes(UNSERVED)) return decided
71      if (input === undefined || input.path !== args.path || input.token_budget !== args.token_budget) {
72        return { deny: 'A hook changed the path or budget before the permission check; precis runs only what it checked' }
73      }
74    }
75    const run = await $.process.run(
76      [bin, '--token-budget', String(args.token_budget ?? tokenBudget), '--', path],
77      { timeoutMs: 120_000 },
78    )
79    if (run.exitCode !== 0) return { deny: run.stderr.trim() }
80    return { result: run.stdout === '' ? run.stderr.trim() : run.stdout }
81  })
82
83  // The main conversation's context, not subagents'. A compacted conversation
84  // keeps what it needs of the overview in its summary, and a resumed one
85  // still holds it.
86  on('classic.SessionStart', async ($, e, next) => {
87    if (e.source !== 'startup' && e.source !== 'clear') return next(e)
88    const { platform, binary } = (setup ??= setUp($))
89    const [below, overview] = await Promise.all([
90      next(e),
91      workingDirOverview($, binary, tokenBudget),
92      offerFix($, platform),
93    ])
94    if (overview === undefined) return below
95    return { ...below, additionalContext: [...(below.additionalContext ?? []), overview] }
96  })
97}
98
99function setUp($: EngineInterface): Setup {
100  const platform = detectPlatform($)
101  return { platform, binary: bundledBinary($, platform) }
102}
103
104async function workingDirOverview(
105  $: EngineInterface,
106  binary: Promise<string | undefined>,
107  tokenBudget: number,
108): Promise<string | undefined> {
109  const bin = await binary
110  if (bin === undefined) return undefined
111  const run = await $.process
112    .run([bin, '--token-budget', String(tokenBudget), '.'], { timeoutMs: 60_000 })
113    .catch((error: unknown) => {
114      $.ui.log(`precis: ${String(error)}`)
115      return undefined
116    })
117  if (run === undefined) return undefined
118  if (run.exitCode !== 0) {
119    $.ui.log(`precis: ${run.stderr.trim()}`)
120    return undefined
121  }
122  if (run.stdout === '') return undefined
123  const fence = '`'.repeat(Math.max(3, longestBacktickRun(run.stdout) + 1))
124  return `## precis\n\nOutput of \`${TOOL}\` on the working directory:\n\n${fence}\n${run.stdout.trimEnd()}\n${fence}`
125}
126
127/**
128 * The precis binary: `PRECIS_DEV` when set, for a plugin loaded from source,
129 * which bundles none; else the one this plugin bundles for this machine,
130 * unpacked on first use. A bundle for another machine is the switch row's to
131 * report.
132 */
133async function bundledBinary($: EngineInterface, platform: Promise<Platform>): Promise<string | undefined> {
134  const dev = await $.env.get('PRECIS_DEV')
135  if (dev !== undefined) return dev
136  const { target, bundle } = await platform
137  if (target === undefined) {
138    $.ui.log('precis: no plugin build for this machine; install the standalone CLI')
139    return undefined
140  }
141  if (bundle === undefined) {
142    $.ui.log('precis: no binary bundled; set PRECIS_DEV to run the plugin from source')
143    return undefined
144  }
145  if (bundle.target !== target) return undefined
146  const run = await $.process.run(['bash', `${$.plugin.root}/scripts/unpack.sh`, bundle.path])
147  if (run.exitCode === 0) return run.stdout.trim()
148  $.ui.log(`precis: ${run.stderr.trim()}`)
149  return undefined
150}
151
152async function detectPlatform($: EngineInterface): Promise<Platform> {
153  const bin = `${$.plugin.root}/bin`
154  const [target, entries] = await Promise.all([platformTarget($), $.fs.list(bin).catch(() => [])])
155  for (const { name } of entries) {
156    const bundled = name.match(/^precis-(.+)\.tar\.xz$/)
157    if (bundled) return { target, bundle: { target: bundled[1]!, path: `${bin}/${name}` } }
158  }
159  return { target, bundle: undefined }
160}
161
162/** Offers this machine's plugin in place of one bundling another's binary. */
163async function offerFix($: EngineInterface, platform: Promise<Platform>): Promise<void> {
164  const { target, bundle } = await platform
165  const isWrong = target !== undefined && bundle !== undefined && bundle.target !== target
166  await refreshOffer(
167    $,
168    isWrong
169      ? {
170          severity: 'problem',
171          text: 'wrong platform variant installed',
172          label: 'Fix',
173          from: `precis-${bundle.target}@precis`,
174          to: `precis-${target}@precis`,
175        }
176      : undefined,
177  )
178}
179
180/** The part of `precis --help` above its usage line: what it does and the notation. */
181async function about($: EngineInterface, bin: string): Promise<string> {
182  const { stdout } = await $.process.run([bin, '--help'])
183  return stdout.split('\n\nUsage:')[0]!.trim()
184}
185
186async function expandHome($: EngineInterface, path: string): Promise<string> {
187  if (path !== '~' && !path.startsWith('~/')) return path
188  return `${await $.env.get('HOME')}${path.slice(1)}`
189}
190
191/**
192 * Read's decision on `path`, or why precis may not read it. A plugin's own
193 * tool reaches the permission check only through `next`, which ends at the
194 * engine's error for a call no hook served, so the tool follows Read's
195 * decision on the same path and puts only Read's ask to the permission mode:
196 * the dialog, the auto-mode classifier, a headless host's refusal. Plan mode
197 * refuses every call that reaches it, so an allow skips it.
198 */
199async function readDecision(
200  $: EngineInterface,
201  path: string,
202): Promise<{ decision: 'allow' | 'ask' } | { deny: string }> {
203  const stat = await $.fs.stat(path, { resolve: true }).catch(() => undefined)
204  if (stat === undefined) return { deny: `${path} does not exist` }
205  const target = stat.realPath ?? path
206  const { decision, reason } = await $.tool.check({ tool: 'Read', input: { file_path: target } })
207  if (decision === 'deny') return { deny: reason ?? `Reading ${target} is denied` }
208  return { decision }
209}
210
211function longestBacktickRun(text: string): number {
212  return Math.max(0, ...(text.match(/`+/g) ?? []).map(run => run.length))
213}
214

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, On, PluginState } from 'claude-code'
3
4import { noticeRows } from './notice-band'
5
6// Moving an install onto the precis plugin built for this machine, offered as
7// a row in the band above the prompt. Both plugins carry this file;
8// plugin_shared_files_match keeps the copies identical.
9
10/** A plugin to put in another's place, and the row that offers it. */
11export type Switch = Omit<NonNullable<PluginState['precis']['offer']>, 'busy'>
12
13const offer = atom({ plugin: 'precis', key: 'offer' } as const, null)
14const dismissed = atom({ plugin: 'precis', key: 'dismissed' } as const, false)
15
16/** The target triple the `precis-<target>` plugins are named by, or undefined off macOS and Linux on x86_64 or arm64. */
17export async function platformTarget($: EngineInterface): Promise<string | undefined> {
18  const { stdout } = await $.process.run(['uname', '-sm']).catch(() => ({ stdout: '' }))
19  const [os, arch] = stdout.trim().split(/\s+/)
20  const osPart = os === 'Darwin' ? 'apple-darwin' : os === 'Linux' ? 'unknown-linux-gnu' : undefined
21  const archPart = arch === 'x86_64' ? 'x86_64' : arch === 'arm64' || arch === 'aarch64' ? 'aarch64' : undefined
22  return osPart && archPart ? `${archPart}-${osPart}` : undefined
23}
24
25/** Puts `found` in the band, or takes the row down when there is none. */
26export async function refreshOffer($: EngineInterface, found: Switch | undefined): Promise<void> {
27  await update($, offer, () => found ?? null)
28}
29
30/** Draws the offered switch as a band row whose button makes it. */
31export function drawOffer(on: On): void {
32  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
33    const [below, current, isDismissed] = await Promise.all([next(e), read($, offer), read($, dismissed)])
34    if (current === null || isDismissed) return below
35
36    const ui = $.ui.resolve(e)
37    const notice = {
38      id: 'switch',
39      severity: current.severity,
40      text: current.text,
41      actions: [{ id: 'switch', label: current.label, kind: 'plugin' as const }],
42      busy: current.busy,
43    }
44    const rows = noticeRows(ui, 'precis', [notice], {
45      onAction: () => makeSwitch($, current),
46      onDismiss: () => update($, dismissed, () => true),
47    })
48    return (
49      <ui.Box flexDirection="column">
50        {rows}
51        {below}
52      </ui.Box>
53    )
54  })
55}
56
57async function makeSwitch($: EngineInterface, current: Switch) {
58  const setBusy = (busy: string | undefined) =>
59    update($, offer, value => (value === null ? value : { ...value, busy }))
60  await setBusy('switching…')
61  const error = await switchPlugin($, current.from, current.to).catch(String)
62  if (error !== undefined) {
63    await setBusy(undefined)
64    $.ui.toast(`Switch failed: ${error}`)
65    return
66  }
67  // Both plugins are named precis and so share this state: the row goes
68  // before the reload hands it to the plugin just installed.
69  await update($, offer, () => null)
70  $.ui.toast(`Switched to ${current.to.replace(/@precis$/, '')}`)
71  await $.command.run({ command: 'reload-plugins' })
72}
73
74/**
75 * Installs `to` where `from` is enabled and takes `from` out there.
76 * Resolves the error text when a step fails.
77 *
78 * A platform's plugin in a checked-in project file would break teammates on
79 * other machines, so a project that enables `from` gets `to` installed and
80 * `from` disabled in local settings, its own file untouched.
81 */
82async function switchPlugin($: EngineInterface, from: string, to: string): Promise<string | undefined> {
83  const sources = ['user', 'project', 'local'] as const
84  const settings = await Promise.all(sources.map(source => $.settings.read({ source })))
85  const enabledIn = sources.filter((_, index) => {
86    const enabled = settings[index]!.enabledPlugins as Record<string, unknown> | undefined
87    return enabled?.[from] === true
88  })
89  const scope = enabledIn.includes('user') ? 'user' : 'local'
90  // A local uninstall clears the local entry a disable writes, so the
91  // disable comes last.
92  const steps = [
93    ['install', to, '--scope', scope],
94    ...enabledIn.filter(source => source !== 'project').map(source => ['uninstall', from, '--scope', source]),
95    ...(enabledIn.includes('project') ? [['disable', from, '--scope', 'local']] : []),
96  ]
97  for (const step of steps) {
98    const { exitCode, stdout, stderr } = await $.process.run(['claude', 'plugin', ...step], { timeoutMs: 120_000 })
99    if (exitCode !== 0) return (stderr.trim() || stdout.trim() || `claude plugin ${step[0]} failed`).split('\n')[0]
100  }
101  return undefined
102}
103

1import type { EngineInterface, RenderElement } from 'claude-code'
2
3// One plugin's rows in the band above the prompt, drawn without `$`: each
4// plugin's own `ui.render` hook reads its state and stacks this over what the
5// plugins beneath drew, so third-party plugins on the band keep working.
6//
7// A plugin cannot import another's files, so each plugin that shows notices
8// carries this file; plugins/notice-band.test.ts keeps the copies identical.
9// The `notices` its check prints are this file's `Notice` as JSON.
10
11export type Severity = 'urgent' | 'problem' | 'action' | 'info'
12
13export type NoticeAction = {
14  id: string
15  label: string
16  // command: a slash command; copy: `command` goes on the clipboard, for a
17  // terminal command that is interactive; plugin: the plugin's own handler decides.
18  kind: 'command' | 'copy' | 'plugin'
19  command?: string
20}
21
22export type Notice = {
23  id: string
24  severity: Severity
25  // The whole message: rows wrap rather than hide what the person needs to act.
26  text: string
27  actions?: NoticeAction[]
28  // Set on "updated" notices: a dismissal holds until the plugin's next
29  // version. Without it, a dismissal holds for this session only.
30  version?: string
31  // What a pressed button is doing ("restarting…"): drawn after the text in
32  // place of the buttons, so the row never looks inert. Set by the plugin.
33  busy?: string
34}
35
36export type NoticeHandlers = {
37  onAction: (notice: Notice, action: NoticeAction) => unknown
38  onDismiss: (notice: Notice) => unknown
39}
40
41const MARK: Record<Severity, { rank: number; glyph: string; color: string }> = {
42  urgent: { rank: 0, glyph: '✖', color: 'error' },
43  problem: { rank: 1, glyph: '!', color: 'warning' },
44  action: { rank: 2, glyph: '›', color: 'suggestion' },
45  info: { rank: 3, glyph: '↑', color: 'ide' },
46}
47
48export function noticeRows(
49  ui: ReturnType<EngineInterface['ui']['resolve']>,
50  plugin: string,
51  notices: Notice[],
52  { onAction, onDismiss }: NoticeHandlers,
53): RenderElement[] {
54  const { Box, Button, Text } = ui
55
56  return [...notices]
57    .sort((a, b) => MARK[a.severity].rank - MARK[b.severity].rank)
58    .map(notice => {
59      const mark = MARK[notice.severity]
60      const key = `${plugin}:${notice.id}`
61
62      const buttons = (notice.busy ? [] : (notice.actions ?? [])).map((action, index) => (
63        <Button
64          key={`${key}:${action.id}`}
65          label={action.label}
66          variant={index === 0 ? 'primary' : 'secondary'}
67          onPress={() => onAction(notice, action)}
68        />
69      ))
70      // An info row is a state, not a request: the band's own collapse hides it.
71      if (notice.severity !== 'info' && !notice.busy) {
72        buttons.push(<Button key={`${key}:dismiss`} label="Dismiss" dimColor onPress={() => onDismiss(notice)} />)
73      }
74
75      // The buttons wrap under the text where the row does not fit.
76      return (
77        <Box key={key} flexDirection="row" flexWrap="wrap" justifyContent="space-between" columnGap={2}>
78          <Text>
79            <Text color={mark.color} weight="semibold">
80              {mark.glyph}{' '}
81            </Text>
82            <Text weight="semibold">{plugin}</Text> {notice.busy ? `${notice.text} · ${notice.busy}` : notice.text}
83          </Text>
84          {/* Grows to fill its line, so the buttons stay right-aligned when they wrap. */}
85          <Box flexDirection="row" flexGrow={1} justifyContent="flex-end" columnGap={1}>
86            {buttons}
87          </Box>
88        </Box>
89      )
90    })
91}
92

1declare module 'claude-code' {
2  interface PluginState {
3    precis: {
4      // The switch hooks/switch.tsx offers in the band, with what its button
5      // is doing while it runs; null when there is none.
6      offer: {
7        severity: 'urgent' | 'problem' | 'action' | 'info'
8        text: string
9        label: string
10        from: string
11        to: string
12        busy?: string
13      } | null
14      dismissed: boolean
15    }
16  }
17}
18