@alecsibilia/luca 14.0.0-alpha.3 → 14.0.0-alpha.5

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.5
+
+No changes in this release.
+
+## 14.0.0-alpha.4
+
+No changes in this release.
+
 ## 14.0.0-alpha.3
 
 No changes in this release.

package/README.md

@@ -38,14 +38,16 @@ This is Luca v14, in alpha. Old Luca (v13) is still on npm; see [Coming from v13
 5. Write a spec with `/to-spec`, then split it into tickets with `/to-tickets`.
 6. In a Paseo chat, type `/luca-run <spec number>`. The board shows the run in the side panel, and the run ends in one pull request.
 
+If a ticket gets stuck, Luca comments on the spec and waits for your one-word reply. Type `/luca-unstick` in Claude Code or a Paseo chat, in the repo: it reads why, says what to do, and posts the reply once you say yes.
+
 ## Commands
 
 | Command | What it does |
 | ------- | ------------ |
-| `luca init` | Sets up this computer, once (safe to run again): MuninnDB and its Claude Code entry, the board in Paseo with its engine and Bun paths, and the planning skills (`to-spec`, `to-tickets`, `setup-matt-pocock-skills`, `grilling`, `domain-modeling`). It asks before turning on Paseo's plugins, and leaves skills you already have alone. `--skip-skills` skips the skills. Inside a git repo, it then runs `luca setup` for that repo. |
+| `luca init` | Sets up this computer, once (safe to run again): MuninnDB and its Claude Code entry, the board in Paseo with its engine and Bun paths, the planning skills (`to-spec`, `to-tickets`, `setup-matt-pocock-skills`, `grilling`, `domain-modeling`), and Luca's own `/luca-unstick` skill. It asks before turning on Paseo's plugins, and leaves skills you already have alone (it only replaces its own `/luca-unstick`). `--skip-skills` skips the planning skills. Inside a git repo, it then runs `luca setup` for that repo. |
 | `luca setup` | Gets the repo in this folder ready: the labels a run needs (and the `release:*` labels when the repo uses changesets), `.luca/config.json` (a new one gets the repo's GitHub name as its vault; an existing vault is kept), and a check of GitHub sub-issues and dependencies. `--base <branch>` names the base branch. |
 | `luca doctor` | Checks this computer, this repo when you're in one, and what v13 left behind. Each problem comes with its exact fix. `luca doctor --fix` fixes what's safe without asking: it never deletes (v13 files go to a dated backup folder) and never commits, and it lists the repo files to commit. |
-| `luca upgrade` | Moves to the newest Luca on your channel: `alpha` stays on `alpha`, and it never goes back to v13. It refuses while any run is going (stuck runs and limit waits count) and lists them. A run that crashed, with no engine running it, doesn't stop it: upgrade says how to resume it on the new version. Then it reloads the board and says when to run `/reload-skills`. |
+| `luca upgrade` | Moves to the newest Luca on your channel: `alpha` stays on `alpha`, and it never goes back to v13. It refuses while any run is going (stuck runs and limit waits count) and lists them. A run that crashed, with no engine running it, doesn't stop it: upgrade says how to resume it on the new version. Then it reloads the board, copies the new `/luca-unstick` skill, and says when to run `/reload-skills`. |
 | `luca upgrade --to <version>` | Installs that exact version, an older one too, to go back when a version breaks. |
 
 `init`, `setup`, and `upgrade` end with their part of `luca doctor`'s checks.
@@ -88,6 +90,7 @@ This is the one package that goes to npm. It's TypeScript source with no build a
 | ------ | ---------- |
 | `engine/` | The engine's source, from [`packages/engine/src`](../engine/src). Both bins point into it. |
 | `board/` | The board plugin's folder, from [`packages/board`](../board): `paseo-plugin.json`, its entry points, its client, server, and shared code, and its own `package.json`, so Paseo can install it as a folder source. |
+| `skills/` | Luca's own Claude Code skills, such as `luca-unstick`, from [`packages/engine/skills`](../engine/skills). `luca init` and `luca upgrade` copy them to `~/.claude/skills`. |
 | `LICENSE` | The repo's license. |
 
 Test files and test helpers stay out. The engine and the board stay private workspace packages, and this package lists every package they import at runtime as its own dependency.

package/board/client/board-panel.tsx

@@ -6,12 +6,7 @@ import {
     useWorkspace,
     type PluginWorkspacePanelProps,
 } from '@getpaseo/plugin/client'
-import {
-    Icon,
-    ScrollView,
-    copyText,
-    useToast,
-} from '@getpaseo/plugin/client/react-native'
+import { Icon, ScrollView } from '@getpaseo/plugin/client/react-native'
 import { ExternalLink } from '@getpaseo/plugin/client/ui'
 import { useQuery } from '@tanstack/react-query'
 import { Pressable, StyleSheet, Text, View } from 'react-native'
@@ -31,6 +26,7 @@ import {
     usageLineWaitText,
     useNow,
 } from './board-look'
+import { StuckActions } from './stuck-actions'
 
 import { boardReadRpc } from '../shared/board-rpc'
 import {
@@ -54,6 +50,7 @@ import {
     type TicketCard,
     type TicketStage,
 } from '../shared/board-state'
+import { postedText, type PostedReply } from '../shared/reply-actions'
 
 /**
  * The side panel: one run of this workspace, top to bottom. Plan usage, a
@@ -118,6 +115,9 @@ const LENS_STAGES: { stage: LensState; title: string; icon: string }[] = [
 /** A card or stage key. */
 type Key = string
 
+/** The key of the fold for tickets left out for a person (#499). */
+const FOR_A_PERSON: Key = 'for_a_person'
+
 type DotKind = 'done' | 'current' | 'todo' | 'skip' | 'stopped'
 
 const makeStyles = ({
@@ -251,21 +251,6 @@ const makeStyles = ({
             fontSize: 12,
             fontWeight: '700',
         },
-        replyRow: {
-            flexDirection: 'row',
-            flexWrap: 'wrap',
-            alignItems: 'center',
-            gap: 5,
-        },
-        reply: {
-            color: colors.foreground,
-            backgroundColor: colors.surface2,
-            borderRadius: 4,
-            paddingHorizontal: 6,
-            paddingVertical: 2,
-            fontSize: 12,
-            fontFamily: MONO,
-        },
         rule: { height: 1, backgroundColor: colors.border, marginVertical: 4 },
         reviewTitle: {
             color: colors.foreground,
@@ -436,56 +421,21 @@ const StepLine = ({
     )
 }
 
-/** The exact replies; tap one to copy it. */
-const Replies = ({
-    replies,
-    spec_number,
-    styles,
-}: {
-    replies: string[]
-    spec_number: number | null
-    styles: Styles
-}) => {
-    const toast = useToast()
-    const copy = async ({ reply }: { reply: string }) => {
-        try {
-            await copyText(reply)
-            toast.show(`Copied "${reply}"`, { variant: 'success' })
-        } catch {
-            toast.error('Could not copy. Select the text and use Copy.')
-        }
-    }
-    return (
-        <View style={styles.replyRow}>
-            <Text style={styles.label}>
-                Reply on{' '}
-                {spec_number === null
-                    ? 'the spec issue'
-                    : `spec issue #${spec_number}`}{' '}
-                with
-            </Text>
-            {replies.map((reply) => (
-                <Pressable
-                    key={reply}
-                    accessibilityRole="button"
-                    accessibilityLabel={`Copy the reply ${reply}`}
-                    onPress={() => void copy({ reply })}
-                >
-                    <Text style={styles.reply} selectable>
-                        {reply}
-                    </Text>
-                </Pressable>
-            ))}
-        </View>
-    )
-}
-
 const NeedsYouCard = ({
     item,
+    run_id,
     spec_number,
+    posted,
+    chat_agent_id,
     theme,
     styles,
-}: { item: NeedsYou; spec_number: number | null } & Look) => (
+}: {
+    item: NeedsYou
+    run_id: string
+    spec_number: number | null
+    posted: PostedReply[]
+    chat_agent_id: string | null
+} & Look) => (
     <View style={[styles.card, styles.cardStuck]}>
         <View style={styles.cardTop}>
             <Icon
@@ -515,10 +465,13 @@ const NeedsYouCard = ({
                 ))}
             </>
         ) : null}
-        <Replies
-            replies={item.replies}
+        <StuckActions
+            run_id={run_id}
+            item={item}
             spec_number={spec_number}
-            styles={styles}
+            posted={posted}
+            chat_agent_id={chat_agent_id}
+            theme={theme}
         />
     </View>
 )
@@ -1063,11 +1016,12 @@ export const BoardPanel = ({
     )
     const [folded, setFolded] = useState<ReadonlySet<Key>>(
         () =>
-            new Set(
-                TICKET_STAGES.filter((entry) => entry.folded).map(
+            new Set<Key>([
+                ...TICKET_STAGES.filter((entry) => entry.folded).map(
                     (entry) => entry.stage
-                )
-            )
+                ),
+                FOR_A_PERSON,
+            ])
     )
     const look = { theme, styles }
     const state = board.data?.selected ?? null
@@ -1092,6 +1046,15 @@ export const BoardPanel = ({
 
     const { run } = state
     const runs = board.data?.runs ?? []
+    const posted = board.data?.posted ?? []
+    const chat_agent_id = board.data?.chat_agent_id ?? null
+    // Replies the board posted whose stuck item is gone: say what came of them.
+    const answered = posted.filter(
+        (entry) =>
+            !state.needs_you.some(
+                (item) => item.key === entry.key && item.since === entry.since
+            )
+    )
     const card = (ticket: TicketCard) => {
         const key = `ticket-${ticket.number}`
         return (
@@ -1253,14 +1216,29 @@ export const BoardPanel = ({
                     <View style={styles.stageBody}>
                         {state.needs_you.map((item) => (
                             <NeedsYouCard
-                                key={item.key}
+                                key={`${item.key}-${item.since}`}
                                 item={item}
+                                run_id={run.run_id}
                                 spec_number={run.spec_number}
+                                posted={posted}
+                                chat_agent_id={chat_agent_id}
                                 {...look}
                             />
                         ))}
                     </View>
                 ) : null}
+                {answered.length > 0 ? (
+                    <View style={styles.stageBody}>
+                        {answered.map((entry) => (
+                            <Text
+                                key={`${entry.key}-${entry.since}`}
+                                style={styles.muted}
+                            >
+                                {postedText({ posted: entry })}
+                            </Text>
+                        ))}
+                    </View>
+                ) : null}
             </Section>
 
             {TICKET_STAGES.map((entry) => {
@@ -1293,6 +1271,39 @@ export const BoardPanel = ({
                 )
             })}
 
+            {state.for_a_person.length > 0 ? (
+                <Section styles={styles}>
+                    <StageHeader
+                        title="For a person"
+                        hint="left out of this run: a person does these, or they wait on one"
+                        icon="User"
+                        count={state.for_a_person.length}
+                        color={theme.colors.foregroundMuted}
+                        folded={folded.has(FOR_A_PERSON)}
+                        onPress={() =>
+                            setFolded((set) =>
+                                toggled({ set, key: FOR_A_PERSON })
+                            )
+                        }
+                        {...look}
+                    />
+                    {folded.has(FOR_A_PERSON) ? null : (
+                        <View style={styles.stageBody}>
+                            {state.for_a_person.map((ticket) => (
+                                <Text
+                                    key={ticket.number}
+                                    style={styles.muted}
+                                    numberOfLines={2}
+                                >
+                                    #{ticket.number} {ticket.title} ·{' '}
+                                    {ticket.why}
+                                </Text>
+                            ))}
+                        </View>
+                    )}
+                </Section>
+            ) : null}
+
             {showsFinalReview({ state }) ? (
                 <>
                     <View style={styles.rule} />

package/board/client/stuck-actions.tsx

@@ -0,0 +1,269 @@
+import { useMemo, useState } from 'react'
+
+import type { PluginTheme } from '@getpaseo/plugin'
+import { usePaseo, useRpc } from '@getpaseo/plugin/client'
+import { copyText, useToast } from '@getpaseo/plugin/client/react-native'
+import { Pressable, StyleSheet, Text, View } from 'react-native'
+
+import { MONO } from './board-look'
+
+import { replyPostRpc } from '../shared/board-rpc'
+import {
+    confirmReplyText,
+    postedFor,
+    postedText,
+    replyButtons,
+    unstickCommand,
+    type PostedReply,
+    type ReplyButton,
+} from '../shared/reply-actions'
+
+/**
+ * The actions on stuck work (#503), in the side panel and in the chat's
+ * stuck rows: a button per reply the engine takes, which asks to confirm
+ * and then posts the reply on the spec issue through `reply.post`, and
+ * "Help me", which sends `/luca-unstick` to a chat's agent.
+ */
+
+const makeStyles = ({ theme }: { theme: PluginTheme }) => {
+    const { colors } = theme
+    return StyleSheet.create({
+        box: { gap: 6 },
+        row: {
+            flexDirection: 'row',
+            flexWrap: 'wrap',
+            alignItems: 'center',
+            gap: 6,
+        },
+        label: {
+            color: colors.foregroundMuted,
+            fontSize: 12,
+            fontWeight: '700',
+        },
+        text: { color: colors.foreground, fontSize: 12 },
+        muted: { color: colors.foregroundMuted, fontSize: 12 },
+        danger: { color: colors.statusDanger, fontSize: 12 },
+        success: { color: colors.statusSuccess, fontSize: 12 },
+        button: {
+            borderWidth: 1,
+            borderColor: colors.border,
+            backgroundColor: colors.surface2,
+            borderRadius: 6,
+            paddingHorizontal: 9,
+            paddingVertical: 4,
+        },
+        buttonText: {
+            color: colors.foreground,
+            fontSize: 12,
+            fontFamily: MONO,
+        },
+        primary: {
+            borderRadius: 6,
+            paddingHorizontal: 10,
+            paddingVertical: 4,
+            backgroundColor: colors.accent,
+        },
+        primaryText: {
+            color: colors.accentForeground,
+            fontSize: 12,
+            fontWeight: '700',
+        },
+        posted: { borderColor: colors.statusSuccess },
+        postedText: { color: colors.statusSuccess },
+        locked: { opacity: 0.45 },
+    })
+}
+
+type Styles = ReturnType<typeof makeStyles>
+
+/** What a reply button reads, for its state. */
+const buttonLabel = ({ button }: { button: ReplyButton }): string => {
+    switch (button.state) {
+        case 'sending':
+            return `${button.reply} · posting…`
+        case 'posted':
+            return `${button.reply} · posted`
+        default:
+            return button.reply
+    }
+}
+
+const ReplyButtonView = ({
+    button,
+    onPress,
+    styles,
+}: {
+    button: ReplyButton
+    onPress: () => void
+    styles: Styles
+}) => (
+    <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Post the reply ${button.reply}`}
+        accessibilityState={{ disabled: button.state !== 'ready' }}
+        disabled={button.state !== 'ready'}
+        onPress={onPress}
+        style={[
+            styles.button,
+            button.state === 'posted' ? styles.posted : null,
+            button.state === 'locked' ? styles.locked : null,
+        ]}
+    >
+        <Text
+            style={[
+                styles.buttonText,
+                button.state === 'posted' ? styles.postedText : null,
+            ]}
+        >
+            {buttonLabel({ button })}
+        </Text>
+    </Pressable>
+)
+
+/**
+ * A stuck item's reply buttons and "Help me". `posted` is what the board
+ * says it posted (from `board.read`); a post made here shows at once too.
+ * `chat_agent_id` is the chat "Help me" sends `/luca-unstick` to; without
+ * one, the command is copied instead.
+ */
+export const StuckActions = ({
+    run_id,
+    item,
+    spec_number,
+    posted,
+    chat_agent_id,
+    theme,
+}: {
+    run_id: string
+    item: { key: string; ticket: number | null; since: string }
+    spec_number: number | null
+    posted: PostedReply[]
+    chat_agent_id: string | null
+    theme: PluginTheme
+}) => {
+    const styles = useMemo(() => makeStyles({ theme }), [theme])
+    const postReply = useRpc(replyPostRpc)
+    const paseo = usePaseo()
+    const toast = useToast()
+    const [confirming, setConfirming] = useState<string | null>(null)
+    const [sending, setSending] = useState<string | null>(null)
+    const [mine, setMine] = useState<PostedReply | null>(null)
+    const [note, setNote] = useState<{ ok: boolean; text: string } | null>(null)
+
+    const known = [...posted, ...(mine ? [mine] : [])]
+    const buttons = replyButtons({ item, posted: known, sending })
+    const done = postedFor({ item, posted: known })
+    const command = unstickCommand({ run_id, ticket: item.ticket })
+
+    const post = async ({ reply }: { reply: string }) => {
+        setConfirming(null)
+        setSending(reply)
+        setNote(null)
+        try {
+            const output = await postReply({ run_id, key: item.key, reply })
+            if (output.posted) setMine(output.posted)
+            setNote({ ok: output.ok, text: output.message })
+        } catch (error) {
+            setNote({
+                ok: false,
+                text: `Couldn't post \`${reply}\`: ${String(error)}`,
+            })
+        } finally {
+            setSending(null)
+        }
+    }
+
+    const helpMe = async () => {
+        if (chat_agent_id !== null) {
+            try {
+                await paseo.agents.ref(chat_agent_id).send(command)
+                toast.show(`Sent ${command} to the run's chat.`, {
+                    variant: 'success',
+                })
+                return
+            } catch {
+                // The chat may be gone: copy it instead.
+            }
+        }
+        try {
+            await copyText(command)
+            toast.show(`Copied ${command}. Paste it in a chat.`, {
+                variant: 'success',
+            })
+        } catch {
+            toast.error(`Could not copy. Type ${command} in a chat.`)
+        }
+    }
+
+    return (
+        <View style={styles.box}>
+            <Text style={styles.label}>
+                Reply on{' '}
+                {spec_number === null
+                    ? 'the spec issue'
+                    : `spec issue #${spec_number}`}
+            </Text>
+            <View style={styles.row}>
+                {buttons.map((button) => (
+                    <ReplyButtonView
+                        key={button.reply}
+                        button={button}
+                        onPress={() => {
+                            setNote(null)
+                            setConfirming(button.reply)
+                        }}
+                        styles={styles}
+                    />
+                ))}
+            </View>
+            {confirming !== null && done === null && sending === null ? (
+                <View style={styles.row}>
+                    <Text style={styles.text}>
+                        {confirmReplyText({ reply: confirming, spec_number })}
+                    </Text>
+                    <Pressable
+                        accessibilityRole="button"
+                        accessibilityLabel={`Yes, post ${confirming}`}
+                        onPress={() => void post({ reply: confirming })}
+                        style={styles.primary}
+                    >
+                        <Text style={styles.primaryText}>Post</Text>
+                    </Pressable>
+                    <Pressable
+                        accessibilityRole="button"
+                        accessibilityLabel="Cancel"
+                        onPress={() => setConfirming(null)}
+                        style={styles.button}
+                    >
+                        <Text style={styles.buttonText}>Cancel</Text>
+                    </Pressable>
+                </View>
+            ) : null}
+            {note !== null && !(note.ok && done !== null) ? (
+                <Text style={note.ok ? styles.success : styles.danger}>
+                    {note.text}
+                </Text>
+            ) : null}
+            {done !== null ? (
+                <Text style={styles.success}>
+                    {postedText({ posted: done })}
+                </Text>
+            ) : null}
+            <View style={styles.row}>
+                <Pressable
+                    accessibilityRole="button"
+                    accessibilityLabel={`Help me: ${command}`}
+                    onPress={() => void helpMe()}
+                    style={styles.button}
+                >
+                    <Text style={styles.buttonText}>Help me</Text>
+                </Pressable>
+                <Text style={styles.muted}>
+                    {chat_agent_id === null
+                        ? `copies ${command}`
+                        : `sends ${command} to the run's chat`}
+                </Text>
+            </View>
+        </View>
+    )
+}

package/board/client/timeline-rows.tsx

@@ -20,6 +20,7 @@ import {
     usageColor,
     useNow,
 } from './board-look'
+import { StuckActions } from './stuck-actions'
 
 import type { EventRow, LimitRow, RunRow, StuckRow } from '../shared/board-rows'
 import { currentStepText, USAGE_LABEL } from '../shared/board-state'
@@ -294,9 +295,14 @@ export const EventRowLine = ({
     )
 }
 
-/** Stuck work, with the exact replies; resolved in place. */
+/**
+ * Stuck work, with a button per reply and "Help me", which sends
+ * `/luca-unstick` to this chat (#503); resolved in place. A row added
+ * before the buttons shows the replies as text.
+ */
 export const StuckRowCard = ({
     item,
+    agentId,
     theme,
     layout,
 }: PluginTimelineItemProps<StuckRow>) => {
@@ -333,20 +339,41 @@ export const StuckRowCard = ({
                             · {line}
                         </Text>
                     ))}
-                    <View style={styles.replyRow}>
-                        <Text style={styles.muted}>
-                            Reply with a comment on{' '}
-                            {row.spec_number === null
-                                ? 'the spec issue'
-                                : `spec issue #${row.spec_number}`}
-                            :
-                        </Text>
-                        {row.replies.map((reply) => (
-                            <Text key={reply} style={styles.reply} selectable>
-                                {reply}
+                    {row.run_id !== null &&
+                    row.key !== null &&
+                    row.since !== null ? (
+                        <StuckActions
+                            run_id={row.run_id}
+                            item={{
+                                key: row.key,
+                                ticket: row.ticket,
+                                since: row.since,
+                            }}
+                            spec_number={row.spec_number}
+                            posted={[]}
+                            chat_agent_id={agentId}
+                            theme={theme}
+                        />
+                    ) : (
+                        <View style={styles.replyRow}>
+                            <Text style={styles.muted}>
+                                Reply with a comment on{' '}
+                                {row.spec_number === null
+                                    ? 'the spec issue'
+                                    : `spec issue #${row.spec_number}`}
+                                :
                             </Text>
-                        ))}
-                    </View>
+                            {row.replies.map((reply) => (
+                                <Text
+                                    key={reply}
+                                    style={styles.reply}
+                                    selectable
+                                >
+                                    {reply}
+                                </Text>
+                            ))}
+                        </View>
+                    )}
                 </>
             ) : (
                 <Text style={styles.muted}>{row.resolution}</Text>

package/board/index.server.ts

@@ -23,6 +23,7 @@ import {
     boardReadRpc,
     boardVersionRpc,
     engineEventRpc,
+    replyPostRpc,
     runStartRpc,
 } from './shared/board-rpc'
 import { PLUGIN_ID } from './shared/board-state'
@@ -40,7 +41,8 @@ const log = (message: string) => console.error(`[${PLUGIN_ID}] ${message}`)
  * The board plugin's daemon side: the engine settings (their usage lines
  * kept in a file for the engine), `run.start` (launch a
  * run from `/luca-run`), `engine.event` (the engine's journal records in),
- * and `board.read` (the side panel's poll). On start, and every 15 s after,
+ * `board.read` (the side panel's poll), and `reply.post` (a reply button on
+ * stuck work posts its word on the spec, #503). On start, and every 15 s after,
  * it checks for runs whose engine is gone and restarts the ones that can go
  * on (#375). The logic lives in `createBoardServer`; this entry only wires it
  * to Paseo.
@@ -130,6 +132,10 @@ export default function contribute(server: PluginServerContext) {
         connect({ context })
         return board.readBoard(input)
     })
+    server.handle(replyPostRpc, (input, context) => {
+        connect({ context })
+        return board.postReply(input)
+    })
     // Fixed as loaded: after an upgrade it differs until a reload.
     server.handle(boardVersionRpc, () => ({ version: LUCA_VERSION }))
 

package/board/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luca/board",
-    "version": "14.0.0-alpha.3",
+    "version": "14.0.0-alpha.5",
     "private": true,
     "type": "module"
 }