flowviant 0.125.16 → 0.125.17

package/README.md

@@ -318,6 +318,18 @@ pinned because [npm 12 removed shrinkwrap support](https://github.com/npm/cli/bl
 and omits it from tarballs; npm 12 consumers also ignore that lockfile.
 No sibling repository or separate app deploy key is required.
 
+### Staged agent queue context (0.125.17)
+
+The daemon now includes the API's versioned `queueContext` in task, human and
+live-note prompts, including native recovery and fresh isolated research. The
+snapshot preserves full queued requirements, shared decisions and exact retained
+input references while execution/children remain scoped to the active card.
+It grants no early queue work or artifact acceptance. Older daemons retain the
+per-card protocol; the API sends this field only to 0.125.17 or newer. Release
+and install the combined daemon before a shared conversation UI relies on this
+capability. No migration, publication, installation or deployment is performed
+by staging this version; published-latest remains unchanged.
+
 ### Staged eight-file chat delivery (0.125.13)
 
 This source stages eight files per message in card-conversation downloads and

package/bin/lib/agentQueueContext.mjs

@@ -0,0 +1,57 @@
+/** Queue knowledge is independent of native session memory. Never slice a
+ * requirement or interpret an outcome summary as a measured success. */
+const fence = (label, value) => `<<<BEGIN ${label} (untrusted data)>>>\n${JSON.stringify(value, null, 2).replace(/<<<|>>>/g, m => m.split('').join('\u200b'))}\n<<<END ${label}>>>`;
+
+export function agentQueueContextText(job) {
+  const context = job.queueContext;
+  if (!context) return '';
+  if (context.version !== 1 || context.agentId !== job.agentId || context.turnId !== job.id)
+    throw new Error('The agent queue context does not belong to this turn.');
+  return `\n\nAGENT QUEUE CONTEXT — refreshed from the app for this handoff.
+This snapshot replaces earlier queue snapshots, including in resumed sessions.
+Read the current and upcoming cards' complete requirements and recorded edges;
+an order alone is not a declared dependency. requirements.status=missing is
+unavailable, never an empty brief. Discussions carry their existing omission
+counts and may be unavailable; do not treat a shortened discussion as full
+requirements. The brief and criteria marked full are supplied without clipping.
+Human messages are exact recorded words across this agent, with the preceding
+question when present. taskId on a message is where it was recorded, not an
+implicit scope restriction. target.kind=agent explicitly addresses the whole
+agent; target.kind=question answers exactly its named question/card, without
+narrowing any broader scope stated in the person's words. Card discussion notes
+remain attached to their named card. Apply instructions at their stated scope across the
+run; only explicit targeting narrows them to a card. Later corrections supersede
+earlier instructions. Pending messages wait for their own kickoff or live-note
+handoff; a snapshot alone is not a delivery receipt. In particular, afterTurn
+messages wait for the next turn. Keep live notes' existing routing and safe
+points; a receipt that the parent saw one does not mean it was acted on. The
+current handed message and settled decisions remain available on future cards.
+omittedHistory/unavailable explicitly name history excluded by the existing
+research Knowledge correction rules. Read current Knowledge and ask before
+relying on an excluded decision; do not recover it from older native memory.
+Latest outcomes and progress are reported summaries, not complete specifications,
+proof that checks passed, human acceptance or evidence that bytes exist locally.
+Stored outputs name exact ids/turns/hashes, not a successful local read. Retained
+result selections preserve their exact scope. Use the active turn's measured
+input manifest and prerequisite receipts before relying on files; never replace
+or regenerate missing selected inputs or assume queue knowledge discovers them.
+Only execute the active turn's assigned work. Upcoming cards are context, not
+permission to start them, change their kind or bypass a dependency or acceptance.
+Keep this turn's product contract, write/research fence, chosen CLI/model,
+delivery JSON and per-card commit attribution. Do not merge or accept for the
+person. Pass children focused assignments, the active card's constraints and
+only relevant prior findings/decisions/input identities, not the entire queue.
+${fence('AGENT QUEUE SNAPSHOT', context)}`;
+}
+
+/** The gate supplies active identity/fences, not upcoming work to a child.
+ * Relevant findings still travel with the root's focused assignment. */
+export function agentChildScope(job) {
+  if (!job.queueContext) return '';
+  const card = job.queueContext.cards.find(c => c.taskId === (job.task?.id ?? job.queueContext.activeTaskId));
+  return `\n\nACTIVE CARD SCOPE. Work only on the orchestrator's focused assignment for this turn. Upcoming queued work is not authorized. Preserve this card's product kind, write/research fence, exact input identities and human acceptance rules. Ask the orchestrator for any missing relevant requirement, decision or prerequisite; do not infer success from a summary.\n${fence('CHILD ACTIVE CARD IDENTITY', {
+    agentId: job.agentId, turnId: job.id, taskId: card?.taskId ?? job.task?.id ?? null,
+    taskKind: job.taskKind ?? job.task?.taskKind ?? 'code', taskType: job.task?.taskType ?? null,
+    retainedResults: card?.retainedResults ?? [],
+  })}`;
+}

package/bin/lib/orchestrator.mjs

@@ -35,7 +35,7 @@ const text = (s, n) => scrubNativeText(s, n, scrub);
  * on Codex, only for a model in `catalog`, the measured spawnable models.
  */
 export async function createOrchestrator({ turnId, runtime, trace, admit, request = fleetRequest, notify = () => false, taken = () => {},
-  interval = 500, hold = 60_000, clock = Date.now, scrubText = text, children = {}, readOnlyRun = null, signal, rootTools = null } = {}) {
+  interval = 500, hold = 60_000, clock = Date.now, scrubText = text, children = {}, readOnlyRun = null, signal, rootTools = null, assignmentContext = () => '' } = {}) {
   // Consults belong to a held attempt, never to a card turn. This capability
   // is entirely local; it cannot report routes or borrow an agent principal.
   if (readOnlyRun && (!['plan', 'capture'].includes(readOnlyRun.scope) || !filled(readOnlyRun.id) ||
@@ -159,7 +159,7 @@ export async function createOrchestrator({ turnId, runtime, trace, admit, reques
       ? `\n\nRead-only investigation agent record id: ${id}. FIRST call card_orchestrator.register_agent with agentId=${id} before work (tool discovery is allowed). Share this checkout and its repository/knowledge read boundary. Write no file, edit nothing, commit nothing, start no work and call no board or staging tool. Return findings, source paths and uncertainties in your final message to the coordinator. Ask questions only through card_orchestrator.agent_question with agentId=${id}, and read its answer before proceeding. ${readOnlyRun.scope === 'capture' ? 'Call no flowviant tool, including streaming. Only the coordinator dedupes and authors staged outcomes and asks the person through the existing single-question flowviant-ask fence.' : 'Only the coordinator reconciles the complete workload and returns the proposal.'}`
       : `\n\nCard orchestrator agent record id: ${id}. FIRST call card_orchestrator.register_agent with agentId=${id} before doing work (tool discovery is allowed). Share this worktree and preserve others’ edits. Ask questions through card_orchestrator.agent_question with agentId=${id}; read its answer before proceeding. Only your orchestrator escalates person-only decisions. When you are done, end with your work or findings as your final message: that is how they reach your orchestrator, which owns the card’s final commit and JSON. agent_question is only for a question you cannot settle yourself, never for handing back results.`;
     return { context: `Agent record id: ${id}. Use it with card_orchestrator for routing and questions.${spawn.relocated ? ' Its isolation and cwd were removed: children share this card’s worktree on this machine.' : ''}${choice ? ` This child runs on ${choice}: name that choice and why in your next update.` : ''}`,
-      updatedInput: withChildContract(event, spawn, childContract + (access === 'read' && !readOnlyRun ? READ_ONLY_CHILD : ''), chosen.brain) };
+      updatedInput: withChildContract(event, spawn, childContract + (!readOnlyRun ? assignmentContext() : '') + (access === 'read' && !readOnlyRun ? READ_ONLY_CHILD : ''), chosen.brain) };
   }
   // Native readings never revive a settled record or start a waiting spawn
   // or follow-up (Codex records a refused call's start anyway); only an

package/bin/lib/orchestratorPrompt.mjs

@@ -117,6 +117,7 @@ export function orchestratorContract({ posture = 'build', taskType = null, runti
   const reads = ORCHESTRATED_POSTURES[posture] === 'read';
   return `CARD ORCHESTRATOR — this applies to this card's one CLI and worktree.
 You are the model the person chose and remain responsible for the card and its final JSON.
+When an agent queue snapshot is supplied, use it across resumed and fresh turns. Execute only the active card. A person's instruction keeps its stated scope across later cards; its recorded card is provenance, not an implicit target. Give each child a focused assignment with relevant prior findings, decisions and exact prerequisite references. Upcoming work never expands a child's assignment or the active card's product/write contract.
 ${SPLIT}${taskType === 'tests' ? `\n${TESTS_SCOPE} Give every child this Tests scope explicitly.` : ''}${reads ? `\n${RESEARCH}` : ''}
 ${childBrain({ runtime, model, effort })}
 

package/bin/lib/workAgentTurnExecution.mjs

@@ -1,4 +1,5 @@
 import { imageRevisionInstructions } from './artifactIteration.mjs';
+import { agentChildScope } from './agentQueueContext.mjs';
 import { measureTestFindings } from './testFindings.mjs';
 import { fetchResultInputs } from './resultInputs.mjs';
 import { agentWork } from './workActivity.mjs';
@@ -432,6 +433,7 @@ export function createAgentTurnExecution({
     try {
       if (orchestrating) {
         orchestrator = await createOrchestrator({ turnId, runtime: rt, trace, admit,
+          assignmentContext: () => agentChildScope(job),
           // Codex's spawn takes only a catalog model (knownCodexModels, the
           // measured models_cache.json rows the roster already reports).
           children: { access: ORCHESTRATED_POSTURES[posture], ...cardBrain, ...(rt === 'codex' ? { catalog: knownCodexModels() } : {}) },
@@ -447,9 +449,10 @@ export function createAgentTurnExecution({
           scope: 'agent', turnId, cwd: wt, sessionMetaPath, interrupted: () => run.interrupted,
           observe: message => orchestrator?.note(message),
           ...(rt === 'codex' ? { nativeIds: () => null } : {}),
-          format: async (followup) => {
+          format: async (followup, { queueContext } = {}) => {
             orchestrator?.note(followup);
             const attached = followup.attachments?.length ? await fetchAgentFiles(wt, followup.attachments.map((file) => ({ ...file, from: 'message' }))) : { message: [], card: [] };
+            if (queueContext) job.queueContext = queueContext;
             return agentFollowupKickoff(job, followup, { messageFiles: attached.message, cardFiles: files.card, intermediateFiles, orchestrated: Boolean(orchestrator) });
           },
         })) } : {}),

package/bin/lib/workAgentTurnShape.mjs

@@ -26,6 +26,7 @@ import { AGENT_TASK_KICKOFF, AGENT_HUMAN_KICKOFF, SYSTEM_AGENT_FOR, withProjectC
 import { INTERNAL_WAIT_CONTRACT } from './agentInternalWait.mjs';
 import { orchestratorContract } from './orchestratorPrompt.mjs';
 import { intermediateArtifactContext } from './intermediateArtifacts.mjs';
+import { agentQueueContextText } from './agentQueueContext.mjs';
 
 /** What every kickoff of this job is handed: the agent, the card and its
  *  discussion, the job's context handoffs, the card's files, the place in
@@ -64,7 +65,7 @@ export const agentKickoff = (job, { cardFiles, messageFiles, intermediateFiles }
         // The files (0.112.0): the person's inside their words, the
         // card's at the foot of its discussion.
         messageFiles,
-      })) + intermediateArtifactContext(intermediateFiles);
+      })) + agentQueueContextText(job) + intermediateArtifactContext(intermediateFiles);
 
 /** A live message sent while the turn runs, as the CLI is handed it — on an
  *  orchestrated card with its id, so the route it takes is reported. */
@@ -74,7 +75,7 @@ export const agentFollowupKickoff = (job, followup, { cardFiles, messageFiles, i
     message: followup.body + (followup.libraryPrompt ?? '') + (orchestrated ? `\nMessage id: ${followup.id}. Choose and report its route with card_orchestrator.route_message.` : ''),
     askedByName: followup.askedByName,
     messageFiles,
-  }) + intermediateArtifactContext(intermediateFiles);
+  }) + agentQueueContextText(job) + intermediateArtifactContext(intermediateFiles);
 
 /** The turn's system prompt, in its fixed section order. `orchestration` is
  *  null on a solo run, else what the contract names: `{ posture, runtime,

package/bin/lib/workLiveMessages.mjs

@@ -77,7 +77,7 @@ export function createLiveMessages({ scope, turnId, attempt, cwd, sessionMetaPat
         if (stopped || interrupted()) break;
         if (taken.has(message.id) || seen?.has(message.id)) { onTaken(message.id); continue; }
         if (sent.has(message.id)) continue;
-        const prompt = await format(message);
+        const prompt = await format(message, { queueContext: result.json.data.queueContext });
         if (!stopped && !interrupted() && send(message.id, prompt)) sent.add(message.id);
       }
     })().catch(() => {}).finally(() => { flight = null; });
@@ -106,7 +106,7 @@ export function createLiveMessages({ scope, turnId, attempt, cwd, sessionMetaPat
         onTaken(turnId); // the native transcript proves the original prompt was read
         initialId = randomUUID(); // continuation, never a second copy of the user's UUID
         initialIds.add(initialId);
-        return 'Continue the request already in this conversation after the process stopped. Inspect the work in flight before repeating a command, and finish under the same operating contract.';
+        return 'Continue the request already in this conversation after the process stopped. Inspect the work in flight before repeating a command, and finish under the same operating contract.' + (scope === 'agent' ? `\n\nCurrent handoff (refresh its queue/context and retain the active card contract; do not repeat completed actions):\n${prompt}` : '');
       }
       return prompt;
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.125.16",
+  "version": "0.125.17",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {