@onepointfour-packs/flaredeck-agent 0.2.81 → 0.2.83

package/dist/serve.js

@@ -5,6 +5,7 @@ import { ensureTmuxScrollback } from './tmux.js';
 import { START_SCRIPT as START_SCRIPT_NAME, webPart, browserBrief, crossWired, environmentBrief, environmentStillUp, notStartedBrief, startEnvironment, stopEnvironment, stopLeftoverEnvironments } from './environment.js';
 import { GIT_TOOL_NAMES, githubTools, publishBranch } from './github.js';
 import { freshGitHubToken } from './githubauth.js';
+import { answerFrom, createPresence, heldFor, modeCommand } from './presence.js';
 import { loadBaseBranch, loadMergeConfig, preflight, preflightBrief } from './preflight.js';
 import { pushStatus, StatusTracker } from './status.js';
 import { dispatchDecision, fetchTeam, myTeam, teamTools, TEAM_TOOL_NAMES } from './team.js';
@@ -504,6 +505,8 @@ export async function serve(opts) {
      * asking for help rather than waiting for it.
      */
     const parked = new Map();
+    /** Whether the manager's person is at this pane, and the questions held for them. See presence.ts. */
+    const presence = createPresence();
     /** Cards just released from a park, and what released them — told to the agent, once. */
     const released = new Map();
     /** Agent names, so a comment from a PERSON can be told from agents talking among themselves. */
@@ -717,10 +720,15 @@ export async function serve(opts) {
                 const cur = onCard;
                 if (!cur)
                     return null;
-                return flagCard({ card: cur.card, board: cur.board, code: cur.code }, reason, kind, ask);
+                // A question, from a manager, with its person at this pane: ask FlareDeck to keep it off
+                // their phone. FlareDeck decides whether it is theirs; a script request is never held.
+                const hold = isManager && !!ask && presence.mode() === 'local';
+                return flagCard({ card: cur.card, board: cur.board, code: cur.code }, reason, kind, ask, undefined, hold);
             },
             unflag: async (cur) => {
                 parked.delete(cur.card);
+                if (presence.take(cur.card))
+                    showPresence();
                 await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'clear-needs-human', {
                     card_id: cur.code || cur.card,
                     ...(cur.board ? { board_id: cur.board } : {}),
@@ -767,6 +775,7 @@ export async function serve(opts) {
             const row = (state.approvals ?? []).find((a) => a.requestId === requestId);
             if (!row || row.stage !== 'ready')
                 return;
+            presence.touch();
             answeredHere.set(requestId, verdict);
             row.stage = 'answered';
             row.verdict = verdict;
@@ -830,6 +839,17 @@ export async function serve(opts) {
     let isLead = false;
     /** A manager: above the leads, with no lead of its own. See MANAGER_BRIEF. */
     let isManager = false;
+    /** The mode and the held questions, as the pane draws them. */
+    const showPresence = () => {
+        if (!isManager) {
+            delete state.presence;
+            delete state.asks;
+            return;
+        }
+        state.presence = presence.mode();
+        const until = presence.deadline();
+        state.asks = presence.held().map((a) => ({ card: a.code || a.card, question: a.question, options: a.options, person: a.person, ...(until ? { until } : {}) }));
+    };
     const keepTool = (name) => offeredTo(isManager ? 'manager' : isLead ? 'lead' : 'worker', name);
     /** Cards already handed to the lead, so a retried tool call does not assign or message twice. */
     const handedBack = new Set();
@@ -859,9 +879,12 @@ export async function serve(opts) {
         // The role exists in FlareDeck before the harness has a manager mode (docs/spec-manager-role.md
         // §14). Said plainly, so nobody reads a manager account running here as a manager at work.
         isManager = team.you.role === 'manager';
+        showPresence();
         if (isManager) {
             log('event', 'You are a manager here — list-agents shows the teams that report to you and the machines they run on; machine-exec reaches those machines.');
-            log('warn', 'Manager mode is partial: the approval, heads-up and escalation steps are not built yet, so nothing here stops a promote or a delete. See docs/spec-manager-role.md §14.');
+            log('event', 'Your team\'s technical, access and information questions come to you first; what you cannot settle goes to the person the board names.');
+            log('event', 'At this pane? Type /local and questions for you are shown here instead of on your phone (back to /remote after ten minutes unanswered).');
+            log('warn', 'Not enforced yet: approvals and heads-ups. Nothing here stops a promote, a merge or a delete — those limits are instructions for now. See docs/spec-manager-role.md §14.');
         }
         selfId = team.you.agentId;
         teamIds = new Set(team.agents.filter((a) => a.reportsTo === team.you.agentId).map((a) => a.agentId));
@@ -1259,12 +1282,87 @@ export async function serve(opts) {
             });
         });
     };
+    /** Nobody answered here: the held question goes to the phone, as it stands on the card. */
+    const sendOn = async (a) => {
+        const label = a.code || a.card;
+        try {
+            const out = await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'set-needs-human', {
+                card_id: a.code || a.card, ...(a.board ? { board_id: a.board } : {}), push_held: true,
+            });
+            log('warn', `${label}: ${out.split('\n').find((l) => l.startsWith('**Told**'))?.replace(/\*\*/g, '') ?? out.split('\n')[0]}`);
+        }
+        catch (e) {
+            log('warn', `${label}: could not send the question on to ${a.person}'s phone (${e instanceof Error ? e.message : String(e)}) — it is still on the card`);
+        }
+    };
+    const setMode = (mode) => {
+        if (!isManager) {
+            log('warn', '/local and /remote are for a manager\'s pane: they decide where questions for the person the manager reports to are shown.');
+            return;
+        }
+        presence.set(mode);
+        if (mode === 'local') {
+            log('you', 'local — questions for you are shown here and kept off your phone. One left unanswered for ten minutes goes to your phone, and this goes back to remote.');
+        }
+        else {
+            const waiting = presence.release();
+            log('you', `remote — questions go to FlareDeck and your phone${waiting.length ? `, including the ${waiting.length} waiting here` : ''}.`);
+            for (const a of waiting)
+                void sendOn(a);
+        }
+        showPresence();
+    };
+    /**
+     * Answered at the pane. Written on the card first — an answer that exists only in a terminal is
+     * one nobody else can find — then the flag comes off and the card goes back to the agent.
+     */
+    const answerHeld = async (a, answer) => {
+        presence.take(a.card);
+        showPresence();
+        const label = a.code || a.card;
+        log('you', `${label}: ${answer}`);
+        const ref = { card_id: a.code || a.card, ...(a.board ? { board_id: a.board } : {}) };
+        try {
+            await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'create-card-comment', {
+                ...ref, comment: `**${a.person} answered at ${state.agent}'s pane.**\n\n> ${a.question}\n\n${answer}`,
+            });
+            await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'clear-needs-human', ref);
+        }
+        catch (e) {
+            log('warn', `${label}: the answer could not be written to the card (${e instanceof Error ? e.message : String(e)}) — the agent still gets it`);
+        }
+        parked.delete(a.card);
+        resumeParked({ card: a.card, ...(a.board ? { board: a.board } : {}), ...(a.code ? { code: a.code } : {}) }, `${a.person} answered your question at this pane.\n\nYou asked: ${a.question}\nThe answer: ${answer}\n\nIt is on the card as a comment and the flag is cleared. Carry on from where you stopped.`);
+    };
+    const presenceTimer = setInterval(() => {
+        const due = presence.expire();
+        if (due.length) {
+            log('warn', `nobody answered here in ten minutes — ${due.length === 1 ? 'that question has' : `${due.length} questions have`} gone to your phone, and this pane is remote again. /local when you are back.`);
+            for (const a of due)
+                void sendOn(a);
+        }
+        if (due.length || state.asks?.length)
+            showPresence();
+    }, 15_000);
+    presenceTimer.unref();
     const steer = (text) => {
         // Mid sign-in, the next line is the redirect address — for the sign-in, never the agent.
         if (signingIn) {
             signInReader.emit('line', text);
             return;
         }
+        const mode = modeCommand(text);
+        if (mode) {
+            setMode(mode);
+            return;
+        }
+        presence.touch();
+        const held = presence.first();
+        const answer = held ? answerFrom(text, held) : null;
+        if (held && answer) {
+            void answerHeld(held, answer);
+            return;
+        }
         if (text.startsWith('!')) {
             const command = text.slice(1).trim();
             if (command)
@@ -1679,6 +1777,10 @@ export async function serve(opts) {
         // is what tells FlareDeck this agent stopped. Exiting here instead left the last record
         // saying "idle", which reads as a live agent doing nothing rather than one that is gone.
         stream.close();
+        // A question held for the person here must not be stranded by this pane closing.
+        for (const a of presence.release())
+            void sendOn(a);
+        clearInterval(presenceTimer);
         clearInterval(heartbeat);
         clearInterval(sweepTimer);
         clearInterval(worktreeTimer);
@@ -2084,7 +2186,9 @@ export async function serve(opts) {
     /** The one-line ask and its answer buttons — what the person actually sees on a phone. */
     ask, 
     /** Somewhere for the person to GO, which is what a sign-in request is mostly made of. */
-    links) => {
+    links, 
+    /** The person this would go to may be at this pane: flag it, and keep it off their phone. */
+    hold) => {
         const label = ref.code || ref.card || 'card';
         try {
             const out = await callFlaredeckTool(config.mcpUrl, await opts.auth(), 'set-needs-human', {
@@ -2095,6 +2199,7 @@ export async function serve(opts) {
                 ...(kind ? { kind } : {}),
                 ...(ask ? { question: ask.question, options: ask.options } : {}),
                 ...(links?.length ? { links } : {}),
+                ...(hold ? { hold: true } : {}),
             });
             if (out.trimStart().startsWith('\u274c') || out.trimStart().startsWith('\ud83d\udeab')) {
                 log('warn', `${label}: FlareDeck did not flag this card \u2014 ${out.split('\n')[0]}`);
@@ -2102,6 +2207,16 @@ export async function serve(opts) {
             }
             // Say who was told, which the tool reports back, so the pane shows whether anyone heard it.
             park(ref.card, reason.split('.')[0]?.slice(0, 60) || 'an agent asked for help');
+            const person = hold ? heldFor(out) : null;
+            if (person && ask) {
+                presence.hold({
+                    card: ref.card, ...(ref.board ? { board: ref.board } : {}), ...(ref.code ? { code: ref.code } : {}),
+                    question: ask.question, options: ask.options.map((o) => o.label), person, since: Date.now(),
+                });
+                showPresence();
+                log('warn', `${label}: a question for ${person}, shown here and kept off their phone — ${ask.question}`);
+                return `Shown to ${person} at this pane. It goes to their phone if nobody answers here within ten minutes.`;
+            }
             const told = out.split('\n').find((l) => l.startsWith('**Told**'))?.replace(/\*\*/g, '') ?? null;
             log('warn', `${label}: flagged needs-human \u2014 ${reason.split('.')[0]}${told ? ` \u00b7 ${told}` : ''}`);
             return told;
@@ -2144,6 +2259,8 @@ export async function serve(opts) {
                 return;
             }
             parked.delete(event.cardKey);
+            if (presence.take(event.cardKey))
+                showPresence();
             released.set(event.cardKey, byPerson ? `${event.actor} has answered` : stale ? 'it has been waiting a while' : 'an approval was decided');
             log('event', `${label}: ${byPerson ? `${event.actor} answered` : stale ? 'waited long enough' : 'an approval was decided'} — picking it back up`);
         }
@@ -3385,6 +3502,13 @@ export const MANAGER_BRIEF = '\n\nYou are a MANAGER, not a worker. Nobody above
     'behind. It runs under YOUR judgement, not the worker\'s guards, and every call is recorded.\n' +
     'Your job is to unblock: do not build a worker\'s card for it. When an agent is stuck, find out ' +
     'why and fix the cause, or tell its lead what you found.\n' +
+    'Your teams\' TECHNICAL, ACCESS and INFORMATION questions come to you before any person; ' +
+    'product, design and client questions go straight to the person the board names, and are not ' +
+    'yours. When one arrives, read the card and settle it if you can: look the answer up, fix the ' +
+    'machine, or answer from what the board already decided — then say so on the card and ' +
+    'clear-needs-human, so the agent carries on. If it turns out to need a person, pass it up: ' +
+    'set-needs-human on that card with the question, its options, your recommendation, and the kind ' +
+    'of question it really is. It goes to the person the board names for that kind.\n' +
     'NOT YET GUARDED HERE, so until it is, you do not do these without the person\'s say-so, asked ' +
     'for with set-needs-human naming the exact action: anything touching production; merging into a ' +
     'shared branch or promoting; deleting directories, checkouts or data on a shared machine; ' +