@try-works/dsh-righthand 0.1.18 → 0.1.20

package/src/client/index.ts

@@ -0,0 +1,184 @@
+/**
+ * Righthand panel client half: a collapsible right-side panel inside the
+ * DSH Web GUI showing the plugin's live state - settings, store keys,
+ * tasks and events - and mutating it through the /righthand/* routes the
+ * host half (src/gui.ts) registers. Same-plugin GUI: no separate package.
+ */
+
+import {
+  createElement as h,
+  useEffect,
+  useState,
+  type CSSProperties,
+} from 'react'
+import { createPortal } from 'react-dom'
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+
+/** Required services: the slot registry (client runtime). */
+export const inject = ['slots']
+
+const C = {
+  bg: '#15171a',
+  panel: '#1b1e23',
+  row: '#23272e',
+  border: '#2d323a',
+  text: '#e6e8ec',
+  dim: '#9aa3ad',
+  accent: '#3b82f6',
+  green: '#3fbf6e',
+  red: '#e5484d',
+  amber: '#d9a13b',
+}
+
+interface State {
+  settings: Record<string, unknown>
+  storeKeys: string[]
+  tasks: any[]
+  events: any[]
+}
+
+const EMPTY: State = { settings: {}, storeKeys: [], tasks: [], events: [] }
+
+function fmt(s: unknown, n: number): string {
+  try { const t = JSON.stringify(s); return t === undefined ? '' : (t.length > n ? t.slice(0, n) + '...' : t) }
+  catch { return String(s) }
+}
+
+function Row(props: { label: string; value: string; tone?: string }): ReturnType<typeof h> {
+  return h('div', { style: { display: 'flex', gap: 8, justifyContent: 'space-between', padding: '4px 0', borderBottom: '1px solid ' + C.border, fontSize: 12 } },
+    h('span', { style: { color: C.dim, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }, props.label),
+    h('span', { style: { color: props.tone ?? C.text, fontFamily: 'monospace', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', maxWidth: '55%' } }, props.value),
+  )
+}
+
+function Btn(props: { label: string; onClick: () => void; tone?: string; danger?: boolean }): ReturnType<typeof h> {
+  const base: CSSProperties = {
+    background: C.row, color: props.danger ? C.red : (props.tone ?? C.text),
+    border: '1px solid ' + C.border, borderRadius: 6, padding: '3px 10px',
+    fontSize: 11, cursor: 'pointer', whiteSpace: 'nowrap'
+  }
+  return h('button', { style: base, onClick: props.onClick }, props.label)
+}
+
+function Section(props: { title: string; children?: any }): ReturnType<typeof h> {
+  return h('div', { style: { marginTop: 14 } },
+    h('div', { style: { fontSize: 11, letterSpacing: '0.12em', textTransform: 'uppercase', color: C.dim, marginBottom: 6 } }, props.title),
+    props.children,
+  )
+}
+
+function RighthandPanel(): ReturnType<typeof h> {
+  const [collapsed, setCollapsed] = useState(false)
+  const [state, setState] = useState<State>(EMPTY)
+  const [error, setError] = useState('')
+  const [patch, setPatch] = useState('{}')
+  const [newKey, setNewKey] = useState('')
+  const [newValue, setNewValue] = useState('')
+
+  const load = (): void => {
+    fetch('/righthand/state').then(r => r.json()).then((d: State) => { setState(d); setError('') })
+      .catch((e: Error) => setError(String(e)))
+  }
+  useEffect(() => { load() }, [])
+
+  const post = (path: string, body: unknown, then: () => void): void => {
+    fetch(path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) })
+      .then(r => r.json()).then((d: any) => { if (!d.ok && d.error) setError(String(d.error)); then() })
+      .catch((e: Error) => setError(String(e)))
+  }
+
+  const railStyle: CSSProperties = {
+    position: 'fixed', right: 0, top: 0, bottom: 0, width: 44, background: C.panel,
+    borderLeft: '1px solid ' + C.border, display: 'flex', flexDirection: 'column',
+    alignItems: 'center', paddingTop: 12, gap: 10, zIndex: 9998
+  }
+  const panelStyle: CSSProperties = {
+    position: 'fixed', right: 0, top: 0, bottom: 0, width: 340, background: C.bg,
+    borderLeft: '1px solid ' + C.border, padding: 12, overflowY: 'auto', zIndex: 9998,
+    fontFamily: 'ui-sans-serif, system-ui, sans-serif', color: C.text, fontSize: 13
+  }
+
+  const toggle = h('button', {
+    style: { background: 'none', border: 'none', color: C.dim, fontSize: 18, cursor: 'pointer' },
+    onClick: () => setCollapsed(!collapsed),
+  }, collapsed ? '<' : '>')
+
+  const refreshBtn = h(Btn, { label: 'Refresh', onClick: load })
+
+  if (collapsed) {
+    return createPortal(h('div', { style: railStyle, 'data-dsh-righthand-panel': 'collapsed' },
+      toggle,
+      h('span', { style: { color: C.green, fontSize: 10, width: 8, height: 8, borderRadius: '50%', background: C.green } }),
+      h('span', { style: { color: C.dim, fontSize: 11, writingMode: 'vertical-rl', letterSpacing: '0.12em', userSelect: 'none' } }, 'Righthand'),
+    ), document.body)
+  }
+
+  return createPortal(h('div', { style: panelStyle, 'data-dsh-righthand-panel': 'expanded' },
+    h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 4 } },
+      h('span', { style: { fontWeight: 600, letterSpacing: '0.05em' } }, 'Righthand'),
+      h('span', { style: { display: 'flex', gap: 6 } }, refreshBtn, toggle),
+    ),
+    error !== '' ? h('div', { style: { color: C.red, fontSize: 11, marginBottom: 8 } }, error) : null,
+
+    h(Section, { title: 'Settings' },
+      Object.entries(state.settings).map(([k, v]) => h(Row, { key: k, label: k, value: fmt(v, 90) })),
+      h('div', { style: { display: 'flex', gap: 6, marginTop: 8 } },
+        h('input', {
+          value: patch, onChange: (e: any) => setPatch(e.target.value),
+          style: { flex: 1, background: C.row, color: C.text, border: '1px solid ' + C.border, borderRadius: 6, padding: '3px 8px', fontSize: 11, fontFamily: 'monospace' },
+        }),
+        h(Btn, { label: 'Patch', onClick: () => {
+          try { const p = JSON.parse(patch); post('/righthand/settings/set', { patch: p }, load) }
+          catch { setError('patch must be JSON') }
+        } }),
+      ),
+    ),
+
+    h(Section, { title: 'Store (' + state.storeKeys.length + ')' },
+      state.storeKeys.length === 0 ? h('div', { style: { color: C.dim, fontSize: 12 } }, '(empty)') : null,
+      state.storeKeys.map(k => h('div', { key: k, style: { display: 'flex', gap: 6, alignItems: 'center', padding: '2px 0' } },
+        h('span', { style: { flex: 1, fontFamily: 'monospace', fontSize: 12, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }, k),
+        h(Btn, { label: 'Delete', danger: true, onClick: () => post('/righthand/store/delete', { key: k }, load) }),
+      )),
+      h('div', { style: { display: 'flex', gap: 6, marginTop: 8 } },
+        h('input', { placeholder: 'key', value: newKey, onChange: (e: any) => setNewKey(e.target.value), style: { flex: 1, background: C.row, color: C.text, border: '1px solid ' + C.border, borderRadius: 6, padding: '3px 8px', fontSize: 11, fontFamily: 'monospace' } }),
+        h('input', { placeholder: 'json value', value: newValue, onChange: (e: any) => setNewValue(e.target.value), style: { flex: 1, background: C.row, color: C.text, border: '1px solid ' + C.border, borderRadius: 6, padding: '3px 8px', fontSize: 11, fontFamily: 'monospace' } }),
+        h(Btn, { label: 'Put', onClick: () => {
+          if (newKey === '') { setError('key required'); return }
+          try { const v = JSON.parse(newValue === '' ? 'null' : newValue); post('/righthand/store/put', { key: newKey, value: v }, () => { load(); setNewKey(''); setNewValue('') }) }
+          catch { setError('value must be JSON') }
+        } }),
+      ),
+    ),
+
+    h(Section, { title: 'Tasks (' + state.tasks.length + ')' },
+      state.tasks.length === 0 ? h('div', { style: { color: C.dim, fontSize: 12 } }, '(none)') : null,
+      state.tasks.map((t: any) => h('div', { key: t.id, style: { display: 'flex', gap: 6, alignItems: 'center', padding: '2px 0' } },
+        h('span', { style: { flex: 1, fontSize: 12, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }, (t.state === 'done' ? '[x] ' : t.state === 'failed' ? '[!] ' : '[ ] ') + t.title),
+        h(Btn, { label: 'Done', tone: C.green, onClick: () => post('/righthand/task/update', { id: t.id, state: 'done' }, load) }),
+        h(Btn, { label: 'Fail', danger: true, onClick: () => post('/righthand/task/update', { id: t.id, state: 'failed' }, load) }),
+      )),
+    ),
+
+    h(Section, { title: 'Events (' + state.events.length + ')' },
+      state.events.length === 0 ? h('div', { style: { color: C.dim, fontSize: 12 } }, '(none)') : null,
+      state.events.map((e: any) => h('div', { key: e.id, style: { display: 'flex', gap: 6, alignItems: 'center', padding: '2px 0' } },
+        h('span', { style: { flex: 1, fontSize: 12, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }, e.title + ' @ ' + e.at + ' [' + e.state + ']'),
+        e.state === 'pending' ? h(Btn, { label: 'Cancel', danger: true, onClick: () => post('/righthand/event/cancel', { id: e.id }, load) }) : null,
+      )),
+    ),
+  ), document.body)
+}
+
+/**
+ * Client plugin body: register the panel into the frame-wide overlay slot.
+ */
+export function apply(ctx: ClientContext): void {
+  ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+    name: 'shell.overlay',
+    id: 'righthand-panel',
+    order: 60,
+  }, RighthandPanel))
+}

package/src/events-tools.ts

@@ -13,6 +13,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
 import type { Domain } from '@deepseek-ai/dsh-storage-domain'
 import { z } from 'zod'
+import { genCall, genResult } from './cards.ts'
 
 export const name = 'righthand-events'
 export const inject = ['tools', 'storageDomain']
@@ -134,6 +135,8 @@ export function apply(ctx: Context): void {
       },
       render: (_args, value) => [{ type: 'text', text: 'event ' + value.id + ': ' + value.title + ' at ' + value.at }],
     },
+    presentCall: (args: any) => genCall('Reminder: ' + args.title + ' at ' + args.at, 'edit'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const d = await ensure()
       const at = new Date(args.at)
@@ -166,6 +169,8 @@ export function apply(ctx: Context): void {
       },
       render: (_args, value) => [{ type: 'text', text: value.due.length === 0 ? '(nothing due)' : value.due.map((e: any) => e.title + ' at ' + e.at).join(' / ') }],
     },
+    presentCall: () => genCall('Due events', 'read'),
+    presentResult: (_args, result) => genResult(result),
     async execute() {
       const d = await ensure()
       const now = Date.now()
@@ -192,6 +197,8 @@ export function apply(ctx: Context): void {
       schema: { type: 'array', items: { type: 'json' } },
       render: (_args, value) => [{ type: 'text', text: value.length === 0 ? '(no events)' : (value as any[]).map((e: any) => e.at + ' ' + e.title + ' [' + e.state + ']').join(' / ') }],
     },
+    presentCall: () => genCall('Events', 'read'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const events = await all()
       const wanted = args.state ?? null
@@ -213,6 +220,8 @@ export function apply(ctx: Context): void {
       schema: { type: 'array', items: { type: 'string' } },
       render: (_args, value) => [{ type: 'text', text: value.length === 0 ? '(no free slot)' : (value as string[]).join(' / ') }],
     },
+    presentCall: (args: any) => genCall('Free slots (' + args.durationMinutes + 'm)', 'read'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const events = await all()
       return freeSlots(events, new Date(), args.durationMinutes, args.horizonHours ?? 24)
@@ -236,6 +245,8 @@ export function apply(ctx: Context): void {
       },
       render: (_args, value) => [{ type: 'text', text: 'cancelled ' + value.id + ': ' + value.existed }],
     },
+    presentCall: (args: any) => genCall('Cancel event ' + args.id, 'edit'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const d = await ensure()
       const e = d.table('events').get(args.id)

package/src/exec-tools.ts

@@ -9,7 +9,9 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools'
 import type { SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { genCall, genResult, textOf } from './cards.ts'
 import type {} from '@deepseek-ai/dsh-jobs'
 
 export const name = 'righthand-exec'
@@ -41,6 +43,12 @@ export function apply(ctx: Context): void {
         },
       },
       render: (_args, value) => [{ type: 'text', text: `exit ${value.exitCode ?? ('signal ' + value.signal)}; stdout=${value.stdout.length}b stderr=${value.stderr.length}b` }],
+      presentationMeta: (_args, value) => ({ exitCode: value.exitCode ?? null, signal: value.signal ?? null }),
+    },
+    presentCall: (args: any): ToolCallView => ({ card: 'terminal', title: args.argv.join(' '), description: 'run one command (bounded collect)' }),
+    presentResult: (_args, result): ToolResultView => {
+      const meta = result.meta as any
+      return { card: 'terminal', output: textOf(result.content) + '\n' + (meta?.exitCode ?? ''), exitCode: meta?.exitCode ?? undefined, signal: meta?.signal ?? undefined }
     },
     async execute(args, exec) {
       const maxBytes = args.maxOutputBytes ?? 4096
@@ -89,6 +97,8 @@ export function apply(ctx: Context): void {
       },
       render: (_args, value) => [{ type: 'text', text: `started background job ${value.jobId} (${value.label})` }],
     },
+    presentCall: (args: any): ToolCallView => genCall('Background job: ' + (args.label ?? args.argv[0]), 'execute'),
+    presentResult: (_args, result): ToolResultView => genResult(result),
     async execute(args, exec) {
       const label = args.label ?? args.argv.join(' ')
       const jobId = ctx.jobs.start({

package/src/files-tools.ts

@@ -15,6 +15,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { signRequest, presignGet } from './sigv4.ts'
+import { genCall, genResult } from './cards.ts'
 
 export const name = 'righthand-files'
 export const inject = ['tools', 'credentials', 'settings']
@@ -178,6 +179,8 @@ export function apply(ctx: Context, config: FilesConfig = {}): void {
       },
       render: (_args, value) => [{ type: 'text', text: 'stored ' + value.key + ' (' + value.size + ' bytes)' }],
     },
+    presentCall: (args: any) => genCall('Upload ' + args.key, 'edit'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const c = await client()
       return c.put(args.key, args.content, args.contentType)
@@ -203,6 +206,8 @@ export function apply(ctx: Context, config: FilesConfig = {}): void {
       },
       render: (_args, value) => [{ type: 'text', text: value.found && typeof value.content === 'string' ? value.content : '(absent)' }],
     },
+    presentCall: (args: any) => genCall('Read object ' + args.key, 'read'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const c = await client()
       const out = await c.get(args.key)
@@ -231,6 +236,8 @@ export function apply(ctx: Context, config: FilesConfig = {}): void {
       },
       render: (_args, value) => [{ type: 'text', text: value.entries.length + ' objects' }],
     },
+    presentCall: () => genCall('List bucket', 'read'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const c = await client()
       const entries = await c.list(args.prefix, args.maxKeys)
@@ -257,6 +264,8 @@ export function apply(ctx: Context, config: FilesConfig = {}): void {
       },
       render: (_args, value) => [{ type: 'text', text: value.url }],
     },
+    presentCall: (args: any) => genCall('Share ' + args.key + ' for ' + (args.minutes ?? 60) + ' min', 'execute'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const minutes = Math.min(Math.max(args.minutes ?? 60, 1), 10080)
       const c = await client()
@@ -282,6 +291,8 @@ export function apply(ctx: Context, config: FilesConfig = {}): void {
       },
       render: (_args, value) => [{ type: 'text', text: 'deleted ' + value.key + ': ' + value.existed }],
     },
+    presentCall: (args: any) => genCall('Delete object ' + args.key, 'delete'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const c = await client()
       return c.delete(args.key)

package/src/gui.ts

@@ -0,0 +1,157 @@
+/**
+ * gui.ts - the righthand GUI host half: HTTP routes under /righthand/* on
+ * the DSH web server that read and mutate the same domains the tools use.
+ * The client half (src/client/index.ts) renders these as a panel inside the
+ * DSH Web GUI. Mounts only when a webServer exists (the Web surface);
+ * elsewhere the child fiber simply does not start.
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { storeDomain } from './store-tools.ts'
+import { taskDomain } from './task-tools.ts'
+import { eventsDomain } from './events-tools.ts'
+// Type-only: activates the cordis Context merge for ctx.webServer.
+import type {} from '@deepseek-ai/dsh-host-webserver'
+
+export const name = 'righthand-gui'
+export const inject = ['webServer', 'storageDomain', 'settings']
+
+const ns = settingsNamespace('righthand')
+
+function json(res: ServerResponse, code: number, body: unknown): void {
+  const text = JSON.stringify(body)
+  res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(text)
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let bytes = 0
+    req.on('data', (c: Buffer) => {
+      bytes += c.length
+      if (bytes > 65536) { reject(new Error('body too large')); req.destroy() }
+      else chunks.push(c)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+export function apply(ctx: Context): void {
+  let domains: { store: any; tasks: any; events: any } | undefined
+  let ready: Promise<void> | undefined
+
+  ctx.effect(() => {
+    ready = (async () => {
+      const [store, tasks, events] = await Promise.all([
+        ctx.storageDomain.open(storeDomain),
+        ctx.storageDomain.open(taskDomain),
+        ctx.storageDomain.open(eventsDomain),
+      ])
+      domains = { store, tasks, events }
+    })()
+    return () => { }
+  })
+
+  const ensure = async (): Promise<NonNullable<typeof domains>> => {
+    if (domains === undefined) { await ready }
+    if (domains === undefined) throw new Error('righthand domains not open')
+    return domains
+  }
+
+  const getSettings = () => {
+    const v = ctx.settings.get(ns) as Record<string, unknown> | undefined
+    return v ?? {}
+  }
+
+  const disposers: Array<() => void> = []
+  ctx.effect(() => () => { for (const d of disposers.splice(0)) d() })
+
+  const route = (path: string, handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>): void => {
+    disposers.push(ctx.webServer.register({ kind: 'exact', path, handler }))
+  }
+
+  route('/righthand/state', async (_req, res) => {
+    try {
+      const d = await ensure()
+      const storeKeys = [...d.store.table('rows').keys()]
+      const tasks = [...d.tasks.table('tasks').entries()]
+      const events = [...d.events.table('events').entries()]
+      json(res, 200, {
+        settings: getSettings(),
+        storeKeys,
+        tasks: tasks.map(([id, row]) => ({ id, ...row })),
+        events: events.map(([id, row]) => ({ id, ...row })),
+      })
+    } catch (e) {
+      json(res, 500, { error: String(e) })
+    }
+  })
+
+  route('/righthand/settings/set', async (req, res) => {
+    try {
+      const body = JSON.parse(await readBody(req))
+      await ctx.settings.update(ns, body.patch)
+      json(res, 200, { ok: true })
+    } catch (e) {
+      json(res, 400, { error: String(e) })
+    }
+  })
+
+  route('/righthand/store/put', async (req, res) => {
+    try {
+      const d = await ensure()
+      const body = JSON.parse(await readBody(req))
+      if (typeof body.key !== 'string' || body.key === '') throw new Error('key required')
+      await d.store.table('rows').put(body.key, { value: body.value ?? null, updatedAt: new Date().toISOString() })
+      const writes = d.store.global.get()
+      await d.store.global.set({ writes: writes.writes + 1 })
+      json(res, 200, { ok: true })
+    } catch (e) {
+      json(res, 400, { error: String(e) })
+    }
+  })
+
+  route('/righthand/store/delete', async (req, res) => {
+    try {
+      const d = await ensure()
+      const body = JSON.parse(await readBody(req))
+      const existed = await d.store.table('rows').delete(body.key)
+      json(res, 200, { ok: true, existed })
+    } catch (e) {
+      json(res, 400, { error: String(e) })
+    }
+  })
+
+  route('/righthand/task/update', async (req, res) => {
+    try {
+      const d = await ensure()
+      const body = JSON.parse(await readBody(req))
+      const row = await d.tasks.table('tasks').get(body.id)
+      if (row === undefined) { json(res, 404, { error: 'task not found' }); return }
+      const next: any = { ...row }
+      if (typeof body.state === 'string') next.state = body.state
+      if (body.result !== undefined) next.result = body.result
+      await d.tasks.table('tasks').put(body.id, next)
+      json(res, 200, { ok: true })
+    } catch (e) {
+      json(res, 400, { error: String(e) })
+    }
+  })
+
+  route('/righthand/event/cancel', async (req, res) => {
+    try {
+      const d = await ensure()
+      const body = JSON.parse(await readBody(req))
+      const row = await d.events.table('events').get(body.id)
+      if (row === undefined) { json(res, 404, { error: 'event not found' }); return }
+      await d.events.table('events').put(body.id, { ...row, state: 'cancelled' })
+      json(res, 200, { ok: true })
+    } catch (e) {
+      json(res, 400, { error: String(e) })
+    }
+  })
+}

package/src/index.ts

@@ -25,6 +25,7 @@
  * - notify-tools:    rh_notify_send over ntfy.sh (keyless)
  * - exec-tools:      rh_run / rh_run_bg over ctx.subprocess + ctx.jobs
  * - guard-tools:     tools/pre-execute policy (config.rules)
+ * - gui:             /righthand/* web routes + the client panel (src/client)
  * - skills:          the packaged dsh-righthand skill (ctx.skills)
  *
  * @module @try-works/dsh-righthand
@@ -42,6 +43,7 @@ import * as placesTools from './places-tools.ts'
 import * as filesTools from './files-tools.ts'
 import * as eventsTools from './events-tools.ts'
 import * as notifyTools from './notify-tools.ts'
+import * as guiTools from './gui.ts'
 import * as righthandSkills from './skills.ts'
 import type { GuardRule } from './guard-tools.ts'
 
@@ -73,12 +75,13 @@ export function apply(ctx: Context, config: RighthandConfig = {}): void {
   ctx.plugin(filesTools)
   ctx.plugin(eventsTools)
   ctx.plugin(notifyTools)
+  ctx.plugin(guiTools)
   ctx.plugin(guardTools, { rules: config.rules ?? [] })
   ctx.plugin(righthandSkills)
 }
 
 // Individual modules stay importable for selective mounting.
-export { storeTools, secretsTools, execTools, taskTools, textTools, weatherTools, placesTools, filesTools, eventsTools, notifyTools, guardTools, righthandSkills }
+export { storeTools, secretsTools, execTools, taskTools, textTools, weatherTools, placesTools, filesTools, eventsTools, notifyTools, guiTools, guardTools, righthandSkills }
 export { SKILL_NAME, SKILL_DESCRIPTION, skillDirectory, skillBody } from './skills.ts'
 export type { GuardRule } from './guard-tools.ts'
 export { guardFactsFor } from './guard-tools.ts'

package/src/notify-tools.ts

@@ -10,6 +10,7 @@ import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { guardedFetch } from './weather-tools.ts'
+import { genCall, genResult } from './cards.ts'
 
 export const name = 'righthand-notify'
 export const inject = ['tools', 'settings']
@@ -45,6 +46,8 @@ export function apply(ctx: Context, config: NotifyConfig = {}): void {
       },
       render: (_args, value) => [{ type: 'text', text: 'notified ' + value.topic }],
     },
+    presentCall: (args: any) => genCall('Notify: ' + args.message.slice(0, 60), 'execute'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const settings = ctx.settings.get(ns) as { defaultNotifyTopic?: string } | undefined
       const topic = args.topic ?? config.topic ?? settings?.defaultNotifyTopic ?? ''

package/src/places-tools.ts

@@ -12,6 +12,7 @@
 import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { guardedFetch } from './weather-tools.ts'
+import { genCall, genResult } from './cards.ts'
 
 export const name = 'righthand-places'
 export const inject = ['tools']
@@ -122,6 +123,8 @@ export function apply(ctx: Context, config: PlacesConfig = {}): void {
         return [{ type: 'text', text }]
       },
     },
+    presentCall: (args: any) => genCall('Places: ' + args.query, 'search'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const limit = Math.min(Math.max(1, Math.round(args.limit ?? 5)), 20)
       const qs = new URLSearchParams({ q: args.query, format: 'jsonv2', addressdetails: '1', limit: String(limit) })
@@ -153,6 +156,8 @@ export function apply(ctx: Context, config: PlacesConfig = {}): void {
       },
       render: (_args, value) => [{ type: 'text', text: value.displayName }],
     },
+    presentCall: (args: any) => genCall('Reverse geocode ' + args.latitude + ', ' + args.longitude, 'fetch'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const qs = new URLSearchParams({ lat: String(args.latitude), lon: String(args.longitude), format: 'jsonv2', addressdetails: '1' })
       const body = await guardedFetch(cfg.nominatimUrl + '/reverse?' + qs.toString(), { init: { headers: nomHeaders } })
@@ -181,6 +186,8 @@ export function apply(ctx: Context, config: PlacesConfig = {}): void {
       },
       render: (_args, value) => [{ type: 'text', text: value.elevation + ' m' }],
     },
+    presentCall: (args: any) => genCall('Elevation at ' + args.latitude + ', ' + args.longitude, 'fetch'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const qs = new URLSearchParams({ latitude: String(args.latitude), longitude: String(args.longitude) })
       const body = await guardedFetch(cfg.elevationUrl + '?' + qs.toString())
@@ -207,6 +214,8 @@ export function apply(ctx: Context, config: PlacesConfig = {}): void {
         return [{ type: 'text', text }]
       },
     },
+    presentCall: (args: any) => genCall('Nearby: ' + args.query + ' within ' + (args.radiusKm ?? 1) + ' km', 'search'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const radius = Math.min(Math.max(0.1, Number(args.radiusKm ?? 1)), 20)
       const limit = Math.min(Math.max(1, Math.round(args.limit ?? 5)), 20)

package/src/secrets-tools.ts

@@ -11,6 +11,7 @@ import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { genCall, genResult } from './cards.ts'
 import z from '@deepseek-ai/schemastery'
 
 export const name = 'righthand-secrets'
@@ -56,6 +57,8 @@ export function apply(ctx: Context): void {
       },
       render: (_args, value) => [{ type: 'text', text: `${value.ref}: configured=${value.configured}${value.source ? ' (source=' + value.source + ')' : ''}, writable=${value.writable}` }],
     },
+    presentCall: (args: any) => genCall('Check credential ' + args.ref, 'read'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       const ref = credentialRef(args.ref)
       const info = await ctx.credentials.describe(ref)
@@ -81,6 +84,8 @@ export function apply(ctx: Context): void {
       },
       render: (_args, value) => [{ type: 'text', text: `stored credential ${value.ref} (value not echoed)` }],
     },
+    presentCall: (args: any) => genCall('Store credential ' + args.ref, 'edit'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       if (args.value.length === 0) throw new Error('credential value must be non-empty')
       await ctx.credentials.set(credentialRef(args.ref), args.value)
@@ -105,6 +110,8 @@ export function apply(ctx: Context): void {
       },
       render: (_args, value) => [{ type: 'text', text: `removed credential ${value.ref}` }],
     },
+    presentCall: (args: any) => genCall('Remove credential ' + args.ref, 'delete'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       await ctx.credentials.unset(credentialRef(args.ref))
       return { ref: args.ref, removed: true }
@@ -119,6 +126,8 @@ export function apply(ctx: Context): void {
       schema: { type: 'object', additionalProperties: true },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
+    presentCall: () => genCall('righthand settings', 'read'),
+    presentResult: (_args, result) => genResult(result),
     async execute() {
       const v = scope.get()
       return { accountId: v.accountId, defaultScriptPrefix: v.defaultScriptPrefix, defaultZone: v.defaultZone, defaultR2Bucket: v.defaultR2Bucket, defaultNotifyTopic: v.defaultNotifyTopic }
@@ -141,6 +150,8 @@ export function apply(ctx: Context): void {
       },
       render: () => [{ type: 'text', text: 'settings updated' }],
     },
+    presentCall: (args: any) => genCall('Patch righthand settings (' + Object.keys(args.patch).join(', ') + ')', 'edit'),
+    presentResult: (_args, result) => genResult(result),
     async execute(args) {
       await scope.update(args.patch as Partial<RighthandSettings>)
       return { applied: true }

package/src/store-tools.ts

@@ -8,6 +8,7 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools'
 import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
 import type { Domain } from '@deepseek-ai/dsh-storage-domain'
 import { z } from 'zod'
@@ -110,6 +111,8 @@ export function apply(ctx: Context): void {
       },
       render: (_args, value) => [{ type: 'text', text: `stored ${value.key} (writes=${value.writes})` }],
     },
+    presentCall: (args: any): ToolCallView => ({ card: 'generic', title: 'Store ' + args.key, kind: 'edit' }),
+    presentResult: (_args, result): ToolResultView => ({ card: 'generic', content: result.content }),
     async execute(args) {
       const s = await ensure()
       const row = await s.put(args.key, args.value)
@@ -136,6 +139,8 @@ export function apply(ctx: Context): void {
       },
       render: (_args, value) => [{ type: 'text', text: value.found ? `${value.key} = ${JSON.stringify(value.value)}` : `${value.key} (absent)` }],
     },
+    presentCall: (args: any): ToolCallView => ({ card: 'generic', title: 'Read ' + args.key, kind: 'read' }),
+    presentResult: (_args, result): ToolResultView => ({ card: 'generic', content: result.content }),
     async execute(args) {
       const s = await ensure()
       const row = await s.get(args.key)
@@ -161,6 +166,8 @@ export function apply(ctx: Context): void {
       },
       render: (_args, value) => [{ type: 'text', text: `deleted ${value.key}: ${value.existed}` }],
     },
+    presentCall: (args: any): ToolCallView => ({ card: 'generic', title: 'Delete ' + args.key, kind: 'delete' }),
+    presentResult: (_args, result): ToolResultView => ({ card: 'generic', content: result.content }),
     async execute(args) {
       const s = await ensure()
       const existed = await s.delete(args.key)
@@ -176,6 +183,8 @@ export function apply(ctx: Context): void {
       schema: { type: 'array', items: { type: 'string' } },
       render: (_args, keys) => [{ type: 'text', text: keys.length === 0 ? '(empty)' : keys.join('\n') }],
     },
+    presentCall: (): ToolCallView => ({ card: 'generic', title: 'List store keys', kind: 'read' }),
+    presentResult: (_args, result): ToolResultView => ({ card: 'generic', content: result.content }),
     async execute() {
       const s = await ensure()
       return s.list()