synapse-orch-ai 1.6.0 → 1.6.2

package/backend/core/builder_tools.py

@@ -637,9 +637,10 @@ BUILDER_TOOL_SCHEMAS = [
                     "include_full_history": {
                         "type": "boolean",
                         "description": (
-                            "For agent/llm/tool steps: on re-invocation (evaluator loop-back or retry), "
-                            "include every prior turn's inputs, tools, and output instead of only the last attempt. "
-                            "Useful for feedback loops; increases prompt length."
+                            "For agent/llm/tool steps: controls revision-history rendering on re-runs. "
+                            "Default (unset) auto-enables full history whenever this step runs more than once. "
+                            "Set false to force last-attempt only (smaller prompt); set true is equivalent to default. "
+                            "Only relevant if you want to explicitly opt OUT of full history."
                         ),
                     },
                 },
@@ -698,7 +699,7 @@ BUILDER_TOOL_SCHEMAS = [
                                 "max_turns": {"type": "integer"},
                                 "timeout_seconds": {"type": "integer"},
                                 "model": {"type": "string"},
-                                "include_full_history": {"type": "boolean", "description": "Include full revision history on re-invocation (agent/llm/tool steps)"},
+                                "include_full_history": {"type": "boolean", "description": "Opt OUT of full revision history on re-runs (default: auto-on for any re-run). Set false to keep prompts small."},
                             },
                             "required": ["step_id", "name", "type"],
                         },

package/backend/core/cache/response_cache.py

@@ -93,6 +93,9 @@ def set_exact(
 # semantic hits limited to nearly-identical prompts.
 
 _semantic_collections: dict[str, Any] = {}
+# Track step IDs we've already warned about so the "embedding unavailable" log
+# fires at most once per step per process — avoids spamming during a long run.
+_warned_no_embed_steps: set[str] = set()
 
 
 def _get_memory_store():
@@ -132,6 +135,19 @@ def _embed(text: str) -> Optional[list[float]]:
         return None
 
 
+def _warn_no_embedding(step_id: str) -> None:
+    """One-shot log when the embedding provider is unreachable for this step."""
+    if step_id in _warned_no_embed_steps:
+        return
+    _warned_no_embed_steps.add(step_id)
+    print(
+        f"DEBUG cache: ⚠️  semantic cache disabled for step '{step_id}' — "
+        f"embedding provider unavailable. Start Ollama with `nomic-embed-text` "
+        f"or set `embedding_model` in Settings. Exact-match cache still works.",
+        flush=True,
+    )
+
+
 def get_semantic(
     step_id: str,
     model: str,
@@ -145,6 +161,7 @@ def get_semantic(
         return None
     emb = _embed((system or "") + "\n\n" + user_message)
     if emb is None:
+        _warn_no_embedding(step_id)
         return None
     try:
         res = coll.query(query_embeddings=[emb], n_results=1)
@@ -183,6 +200,7 @@ def set_semantic(
         return
     emb = _embed((system or "") + "\n\n" + user_message)
     if emb is None:
+        _warn_no_embedding(step_id)
         return
     # Reuse the exact-cache key as the Chroma document ID so storage stays unified.
     key = store.make_key("resp_semantic", model, step_id, user_message)

package/backend/core/mcp_client.py

@@ -441,6 +441,13 @@ class MCPClientManager:
             if session:
                 self._set_status(name, "connected")
                 await self._auto_register(name)   # ← register on startup
+            else:
+                # Remote servers without a bearer token use OAuth — failure likely means re-auth needed.
+                # Stdio and bearer-token servers just go disconnected.
+                if server_type == "remote" and not config.get("token"):
+                    self._set_status(name, "reauth_needed")
+                else:
+                    self._set_status(name, "disconnected")
         return self.sessions
 
     # ── add_server ─────────────────────────────────────────────────────────────

package/backend/core/models_orchestration.py

@@ -100,7 +100,9 @@ class StepConfig(BaseModel):
 
     # On re-invocation (evaluator feedback or loop), include every prior turn's
     # inputs/tools/output in the prompt instead of only the last attempt.
-    include_full_history: bool = False
+    # Tri-state: True = always include, False = always last-attempt only,
+    # None (default) = auto (full history on any re-run).
+    include_full_history: bool | None = None
 
     # Graph routing
     next_step_id: str | None = None  # Linear next step / loop "done" path

package/backend/core/native_builder/__init__.py

@@ -24,7 +24,7 @@ __all__ = [
 # their zero-defaults (`route_map: {}`, `parallel_branches: []`, etc.) so the
 # engine deserialises cleanly.
 STEP_TYPE_CHEATSHEET = """\
-- **agent**: runs a configured sub-agent with a prompt + its tool set. Required: `agent_id`, `prompt_template`. Optional: `include_full_history` (bool) — on re-invocation show every prior turn's inputs/tools/output instead of only the last attempt; useful for feedback/retry loops. Use for any step that needs multi-turn reasoning or tool use.
+- **agent**: runs a configured sub-agent with a prompt + its tool set. Required: `agent_id`, `prompt_template`. Optional: `include_full_history` (bool) — default behaviour auto-shows full revision history on any re-run; set this to `false` only if you need to keep the prompt small. Use for any step that needs multi-turn reasoning or tool use.
 - **llm**: single one-shot LLM call, no tools. Required: `prompt_template` (optional `model`). Use for lightweight summarisation, rewriting, or deterministic prose generation.
 - **tool**: forces a single tool call with no LLM reasoning. Required: `forced_tool` (+ `agent_id` for tool-resolution). Use when the arguments are already in state and just need forwarding.
 - **evaluator**: pure routing node. Required: `route_map_json` (JSON-encoded `{label: target_step_id}`), `route_descriptions_json` (JSON), `evaluator_prompt`. Output_key stores the bare route label. Use to fork on a classifier decision.

package/backend/core/orchestration/context.py

@@ -472,14 +472,22 @@ def _origin_label(origin: dict | None, execution: int) -> str:
     return otype or "re-invocation"
 
 
-def _render_full_history(memory: list[dict]) -> str:
-    """Render every recorded turn as inputs → tools → output."""
+def _render_full_history(memory: list[dict], skip_last_output: bool = False) -> str:
+    """Render every recorded turn as inputs -> tools -> output.
+
+    `skip_last_output`: when the caller is also rendering the most recent
+    turn's output as a standalone YOUR PREVIOUS OUTPUT section, set this to
+    True so the history doesn't duplicate that body. The last turn still
+    shows its tools/inputs/label; only the Output: block is replaced with
+    a pointer back to the standalone section.
+    """
     lines: list[str] = ["## REVISION HISTORY (all prior turns)"]
-    for entry in memory:
+    last_idx = len(memory) - 1
+    for idx, entry in enumerate(memory):
         execution = entry.get("execution", 0)
         origin = entry.get("origin") or {}
         label = _origin_label(origin, execution)
-        lines.append(f"\n### Turn {execution} — {label}")
+        lines.append(f"\n### Turn {execution} - {label}")
 
         # Inputs at the time of this turn
         inputs = entry.get("inputs") or {}
@@ -509,10 +517,13 @@ def _render_full_history(memory: list[dict]) -> str:
         # Final output produced on that turn
         final_out = str(trace.get("final_output") or "")
         if final_out:
-            if len(final_out) > 800:
-                from .summarizer import smart_truncate
-                final_out = smart_truncate(final_out, 800)
-            lines.append(f"Output:\n{final_out}")
+            if skip_last_output and idx == last_idx:
+                lines.append("Output: (see YOUR PREVIOUS OUTPUT section above)")
+            else:
+                if len(final_out) > 800:
+                    from .summarizer import smart_truncate
+                    final_out = smart_truncate(final_out, 800)
+                lines.append(f"Output:\n{final_out}")
 
     return "\n".join(lines)
 
@@ -603,18 +614,21 @@ def build_origin_aware_context(
     run: "OrchestrationRun",
     engine: "OrchestrationEngine",
     transition: TransitionContext,
-) -> tuple[str, str]:
+) -> tuple[str, str, str]:
     """
-    Build (prompt, system_prompt_extra) for an agent/tool/llm step using
-    the structured, origin-aware format.
-
-    Returns two strings:
-      prompt              — the full user-turn message to send to the LLM
-      system_prompt_extra — short orchestration-awareness block to append to
-                            the agent's system prompt (can be empty string)
+    Build (prompt, system_prompt_extra, system_prompt_prefix) for an
+    agent/tool/llm step using the structured, origin-aware format.
+
+    Returns three strings:
+      prompt               full user-turn message to send to the LLM
+      system_prompt_extra  short orchestration-awareness block APPENDED to
+                           the agent's system prompt (can be empty)
+      system_prompt_prefix iteration banner PREPENDED to the system prompt
+                           on re-runs (execution_number > 1); empty otherwise
     """
     import re
     sections: list[str] = []
+    is_rerun = transition.execution_number > 1
 
     # ------------------------------------------------------------------
     # Section: ROLE
@@ -659,36 +673,99 @@ def build_origin_aware_context(
     sections.append("\n".join(role_lines))
 
     # ------------------------------------------------------------------
-    # Section: EVALUATOR FEEDBACK (only on evaluator re-invocation)
+    # Section: MAIN GOAL (always present)
+    # The user's original request is the root of every step in this
+    # workflow. Keep it at the top of every prompt so re-runs, branching,
+    # and deep step chains do not lose sight of what we are ultimately
+    # solving for. Sourced from run.shared_state["user_input"] which
+    # the engine seeds on the first step.
     # ------------------------------------------------------------------
-    if transition.origin_type == "evaluator" and (
-        transition.routing_decision or transition.routing_reasoning
-    ):
-        feedback_lines = ["## EVALUATOR FEEDBACK"]
-        if transition.routing_decision:
-            feedback_lines.append(f"Decision: \"{transition.routing_decision}\"")
-        if transition.routing_reasoning:
-            feedback_lines.append(f"Reason: {transition.routing_reasoning}")
-
-        # Previous output summary
-        if step.output_key and step.output_key in run.shared_state:
-            prev_out = str(run.shared_state[step.output_key])
-            if len(prev_out) > 2000:
-                from .summarizer import smart_truncate
-                prev_out = smart_truncate(prev_out, 2000)
-            feedback_lines.append(f"\n### Your previous output\n{prev_out}")
+    main_goal = run.shared_state.get("user_input")
+    if main_goal:
+        goal_text = str(main_goal).strip()
+        if len(goal_text) > 2000:
+            from .summarizer import smart_truncate
+            goal_text = smart_truncate(goal_text, 2000)
+        sections.append(
+            "## MAIN GOAL (original user request)\n"
+            "Everything this workflow does exists to solve this. "
+            "Keep it in mind when deciding what to produce:\n\n"
+            f"{goal_text}"
+        )
 
-        sections.append("\n".join(feedback_lines))
+    # ------------------------------------------------------------------
+    # Section: WHY YOU ARE RUNNING AGAIN (any re-run, any origin)
+    # ------------------------------------------------------------------
+    if is_rerun:
+        why_lines = [
+            "## WHY YOU ARE RUNNING AGAIN",
+            f"This is execution #{transition.execution_number} of this step.",
+        ]
+        if transition.origin_type == "evaluator":
+            if transition.routing_decision:
+                why_lines.append(f"Evaluator decision: \"{transition.routing_decision}\"")
+            if transition.routing_reasoning:
+                why_lines.append(f"Evaluator reasoning: {transition.routing_reasoning}")
+            why_lines.append(
+                "An evaluator reviewed your previous output and routed you back. "
+                "See HOW TO PROCEED below."
+            )
+        elif transition.origin_type == "loop":
+            iter_str = (
+                f"iteration {transition.loop_iteration} of {transition.loop_total}"
+                if transition.loop_iteration and transition.loop_total
+                else f"iteration #{transition.execution_number}"
+            )
+            why_lines.append(
+                f"You are inside a loop ({iter_str}). See HOW TO PROCEED below."
+            )
+        else:
+            why_lines.append(
+                "The workflow has routed control back to this step. See HOW TO PROCEED below."
+            )
+        sections.append("\n".join(why_lines))
+
+    # ------------------------------------------------------------------
+    # Section: YOUR PREVIOUS OUTPUT (any re-run)
+    # ------------------------------------------------------------------
+    if is_rerun and step.output_key and step.output_key in run.shared_state:
+        prev_out = str(run.shared_state[step.output_key])
+        if len(prev_out) > 2000:
+            from .summarizer import smart_truncate
+            prev_out = smart_truncate(prev_out, 2000)
+        sections.append(
+            "## YOUR PREVIOUS OUTPUT\n"
+            "This is what you produced last turn. Read it before responding:\n\n"
+            f"{prev_out}"
+        )
 
     # ------------------------------------------------------------------
     # Section: YOUR PREVIOUS WORK / REVISION HISTORY (on any re-invocation)
     # ------------------------------------------------------------------
-    if transition.execution_number > 1:
+    if is_rerun:
         memory = get_execution_memory(run, step.id)
         if memory:
-            if step.include_full_history:
-                sections.append(_render_full_history(memory))
+            use_full = (
+                step.include_full_history
+                if step.include_full_history is not None
+                else True
+            )
+            # Detect whether the standalone YOUR PREVIOUS OUTPUT section was
+            # rendered above (same condition used there). If so, avoid
+            # duplicating the most recent turn's body in the history.
+            previous_output_rendered = bool(
+                step.output_key and step.output_key in run.shared_state
+            )
+            if use_full:
+                # With only one prior turn, the history would just restate
+                # YOUR PREVIOUS OUTPUT under a turn label. Skip it then.
+                if len(memory) > 1:
+                    sections.append(_render_full_history(
+                        memory, skip_last_output=previous_output_rendered
+                    ))
             else:
+                # Last-attempt mode shows only tools/inputs (no output body),
+                # so it never duplicates YOUR PREVIOUS OUTPUT.
                 sections.append(_render_last_attempt(memory[-1]))
 
     # ------------------------------------------------------------------
@@ -722,11 +799,10 @@ def build_origin_aware_context(
     # ------------------------------------------------------------------
     context_parts = []
 
-    # Always include user_input unless explicitly in input_keys
-    if "user_input" in run.shared_state and "user_input" not in (step.input_keys or []):
-        context_parts.append(
-            f"### user_input\nSource: initial input\n{run.shared_state['user_input']}"
-        )
+    # NOTE: user_input is rendered at the top under "## MAIN GOAL" so it is
+    # not duplicated here. If a step explicitly lists user_input in its
+    # input_keys, the explicit-input loop below will skip it for the same
+    # reason.
 
     # Human response keys (always inject unless already listed)
     human_keys = {"human_response"}
@@ -745,9 +821,9 @@ def build_origin_aware_context(
                 val = smart_truncate(val, 3000)
             context_parts.append(f"### {hkey}\nSource: human response\n{val}")
 
-    # Explicitly declared input_keys
+    # Explicitly declared input_keys (skip user_input — shown under MAIN GOAL)
     for key in (step.input_keys or []):
-        if key not in run.shared_state:
+        if key not in run.shared_state or key == "user_input":
             continue
         val = run.shared_state[key]
         label = key
@@ -755,14 +831,48 @@ def build_origin_aware_context(
             (s for s in engine.step_map.values() if s.output_key == key), None
         )
         if producer and producer.agent_id and producer.agent_id in engine.agent_names:
-            label = f"{engine.agent_names[producer.agent_id]} \u2192 {key}"
+            label = f"{engine.agent_names[producer.agent_id]} → {key}"
         context_parts.append(_format_context_value(key, val, label))
 
     if context_parts:
         sections.append("## CONTEXT FROM PREVIOUS STEPS\n" + "\n\n".join(context_parts))
 
     # ------------------------------------------------------------------
-    # Section: TASK
+    # Section: HOW TO PROCEED (any re-run)
+    # Loose framing: agent decides between refine / redo / push back. The
+    # only firm requirement is that the new output explain the change (or
+    # the deliberate non-change) relative to the previous attempt.
+    # ------------------------------------------------------------------
+    if is_rerun:
+        if transition.origin_type == "loop":
+            proceed_block = (
+                "## HOW TO PROCEED\n"
+                "This is another iteration of a loop. Your previous iteration's output and "
+                "any sibling iterations are shown above.\n\n"
+                "Use your judgement: produce the next item, refine, or take a different angle. "
+                "Just don't silently re-emit what you produced before.\n\n"
+                "At the top of your output, include a brief note (1-3 lines) explaining what "
+                "this iteration adds or changes relative to the previous one."
+            )
+        else:
+            proceed_block = (
+                "## HOW TO PROCEED\n"
+                "You are running this step again. Your previous output and the reason for re-running "
+                "are shown above. Read them before responding.\n\n"
+                "You decide how to respond — any of these are valid:\n"
+                "  - Refine the previous output (small targeted edits).\n"
+                "  - Redo it from scratch if it was fundamentally off.\n"
+                "  - Push back if you believe the feedback is mistaken: explain why and either "
+                "defend the previous output or propose a different correction.\n\n"
+                "Whichever path you take, include a brief reasoning note at the top of your output "
+                "(1-3 lines) that explains:\n"
+                "  - What changed from your previous output (or why you kept it), and\n"
+                "  - Why you believe this is the right response to the feedback."
+            )
+        sections.append(proceed_block)
+
+    # ------------------------------------------------------------------
+    # Section: TASK (first run) / ORIGINAL TASK reference (re-run)
     # ------------------------------------------------------------------
     prompt_template = step.prompt_template or run.shared_state.get("user_input", "")
 
@@ -773,12 +883,17 @@ def build_origin_aware_context(
 
     task_text = re.sub(r"\{state\.(\w+)\}", replace_ref, prompt_template)
 
-    task_header = "## TASK (REVISION)" if transition.origin_type == "evaluator" else "## TASK"
-    task_suffix = ""
-    if transition.origin_type == "evaluator" and transition.routing_reasoning:
-        task_suffix = "\n\nAddress the evaluator's feedback above in your revised output."
-    elif transition.origin_type == "human_response":
-        task_suffix = "\n\nIncorporate the human's input above."
+    if is_rerun:
+        task_header = "## ORIGINAL TASK (reference only)"
+        task_suffix = (
+            "\n\nThis is the original task statement, included for reference. "
+            "Use it together with YOUR PREVIOUS OUTPUT and HOW TO PROCEED above to decide your response."
+        )
+    else:
+        task_header = "## TASK"
+        task_suffix = ""
+        if transition.origin_type == "human_response":
+            task_suffix = "\n\nIncorporate the human's input above."
 
     sections.append(f"{task_header}\n{task_text}{task_suffix}")
 
@@ -799,7 +914,7 @@ def build_origin_aware_context(
         if sid:
             exec_counts[sid] = exec_counts.get(sid, 0) + 1
     # Use execution_number for the active step (counts this in-flight run).
-    if transition.execution_number > 1:
+    if is_rerun:
         exec_counts[step.id] = transition.execution_number
 
     graph_md = build_workflow_graph_markdown(engine.orch, step.id, exec_counts)
@@ -816,4 +931,26 @@ def build_origin_aware_context(
         )
     system_prompt_extra = "\n".join(sys_lines)
 
-    return prompt, system_prompt_extra
+    # ------------------------------------------------------------------
+    # System prompt PREFIX: iteration banner (re-runs only).
+    # Prepended to the system prompt so a long agent role description
+    # cannot drown out the iteration signal.
+    # ------------------------------------------------------------------
+    system_prompt_prefix = ""
+    if is_rerun:
+        why_short = ""
+        if transition.origin_type == "evaluator" and transition.routing_decision:
+            why_short = f" (evaluator routed back: \"{transition.routing_decision}\")"
+        elif transition.origin_type == "loop" and transition.loop_iteration:
+            why_short = f" (loop iteration {transition.loop_iteration})"
+        system_prompt_prefix = (
+            "ITERATION CONTEXT - READ BEFORE RESPONDING\n"
+            f"You are on execution #{transition.execution_number} of step "
+            f"\"{step_name}\"{why_short}. This is NOT your first attempt.\n"
+            "In the user message below, read YOUR PREVIOUS OUTPUT, WHY YOU ARE RUNNING AGAIN, "
+            "and HOW TO PROCEED. Then decide how to respond — refine, redo, or push back on the "
+            "feedback if you think it is mistaken. Whichever you choose, start your output with a "
+            "brief reasoning note explaining what changed (or why you kept the previous output)."
+        )
+
+    return prompt, system_prompt_extra, system_prompt_prefix

package/backend/core/orchestration/steps.py

@@ -52,13 +52,15 @@ class AgentStepExecutor:
         if transition is None:
             from .context import TransitionContext
             transition = TransitionContext(origin_type="entry", execution_number=1)
-        prompt, system_prompt_extra = build_origin_aware_context(
+        prompt, system_prompt_extra, system_prompt_prefix = build_origin_aware_context(
             step, run, engine, transition
         )
         inputs_snapshot = snapshot_inputs(step, run, engine)
 
         # Emit prompt for the orchestration logger (filtered out before SSE)
-        yield {"type": "_log_prompt", "orch_step_id": step.id, "prompt": prompt, "system_prompt_extra": system_prompt_extra}
+        yield {"type": "_log_prompt", "orch_step_id": step.id, "prompt": prompt,
+               "system_prompt_extra": system_prompt_extra,
+               "system_prompt_prefix": system_prompt_prefix}
 
         # ── Orchestrator-as-agent: delegate to a nested OrchestrationEngine ──
         target_agent = next(
@@ -99,6 +101,7 @@ class AgentStepExecutor:
                 source="orchestration",
                 run_id=run.run_id,
                 system_prompt_extra=system_prompt_extra,
+                system_prompt_prefix=system_prompt_prefix,
                 model_override=step.model,
             ):
                 execution_events.append(event)
@@ -271,10 +274,12 @@ class ToolStepExecutor:
         transition = getattr(engine, "current_transition", None)
         if transition is None:
             transition = TransitionContext(origin_type="entry", execution_number=1)
-        prompt, system_prompt_extra = build_origin_aware_context(step, run, engine, transition)
+        prompt, system_prompt_extra, system_prompt_prefix = build_origin_aware_context(step, run, engine, transition)
         inputs_snapshot = snapshot_inputs(step, run, engine)
 
-        yield {"type": "_log_prompt", "orch_step_id": step.id, "prompt": prompt, "system_prompt_extra": system_prompt_extra}
+        yield {"type": "_log_prompt", "orch_step_id": step.id, "prompt": prompt,
+               "system_prompt_extra": system_prompt_extra,
+               "system_prompt_prefix": system_prompt_prefix}
 
         # Model resolution — same pattern as EvaluatorStepExecutor and LLMStepExecutor
         settings = load_settings()
@@ -325,9 +330,12 @@ class ToolStepExecutor:
 
             print(f"DEBUG TOOL STEP: turn {turn + 1}/{max_turns} model={model} tool={tool_name}", flush=True)
             try:
+                tool_sys_prompt = "You are a tool-calling assistant. Output ONLY valid JSON."
+                if system_prompt_prefix:
+                    tool_sys_prompt = system_prompt_prefix + "\n\n" + tool_sys_prompt
                 response = await llm_generate(
                     prompt_msg=turn_prompt,
-                    sys_prompt="You are a tool-calling assistant. Output ONLY valid JSON.",
+                    sys_prompt=tool_sys_prompt,
                     mode=mode,
                     current_model=model,
                     current_settings=settings,
@@ -1178,10 +1186,12 @@ class LLMStepExecutor:
         if transition is None:
             from .context import TransitionContext
             transition = TransitionContext(origin_type="entry", execution_number=1)
-        prompt, system_prompt_extra = build_origin_aware_context(step, run, engine, transition)
+        prompt, system_prompt_extra, system_prompt_prefix = build_origin_aware_context(step, run, engine, transition)
         inputs_snapshot = snapshot_inputs(step, run, engine)
 
-        yield {"type": "_log_prompt", "orch_step_id": step.id, "prompt": prompt, "system_prompt_extra": system_prompt_extra}
+        yield {"type": "_log_prompt", "orch_step_id": step.id, "prompt": prompt,
+               "system_prompt_extra": system_prompt_extra,
+               "system_prompt_prefix": system_prompt_prefix}
         yield {
             "type": "thinking",
             "orch_step_id": step.id,
@@ -1196,7 +1206,11 @@ class LLMStepExecutor:
         mode = detect_mode_from_model(model)
 
         # system_prompt_extra already contains datetime + workflow graph + position.
+        # system_prompt_prefix is the iteration banner (re-runs only); prepend it
+        # so it appears at the top of the system prompt.
         sys_prompt = f"You are a helpful assistant. Be concise and accurate.\n\n{system_prompt_extra}"
+        if system_prompt_prefix:
+            sys_prompt = system_prompt_prefix + "\n\n" + sys_prompt
 
         try:
             response = await llm_generate(

package/backend/core/react_engine.py

@@ -512,6 +512,7 @@ async def run_agent_step(
     run_id: str | None = None,
     images: list[str] | None = None,
     system_prompt_extra: str | None = None,
+    system_prompt_prefix: str | None = None,
     # ── optional extension params (used by builder wrapper) ───────────────────
     agent_override: dict | None = None,   # skip _resolve_agent_by_id
     tools_override: list | None = None,   # skip aggregate_all_tools; list of OpenAI-format tool dicts
@@ -637,6 +638,10 @@ async def run_agent_step(
     # Inject orchestration-awareness block when called from an orchestration step
     if system_prompt_extra:
         system_prompt_text = system_prompt_text + "\n\n" + system_prompt_extra
+    # Iteration banner: prepended so it can't be drowned out by a long agent
+    # system prompt. Only set on re-runs (execution_number > 1).
+    if system_prompt_prefix:
+        system_prompt_text = system_prompt_prefix + "\n\n" + system_prompt_text
 
     async def generate_response(prompt_msg, sys_prompt, tools=None, history_messages=None, memory_context_text="", images_for_turn=None, tool_name_for_log=None):
         return await llm_generate_response(
@@ -719,6 +724,8 @@ async def run_agent_step(
             # step context, shared state, or turn-budget instructions.
             if system_prompt_extra:
                 active_sys_prompt = active_sys_prompt + "\n\n" + system_prompt_extra
+            if system_prompt_prefix:
+                active_sys_prompt = system_prompt_prefix + "\n\n" + active_sys_prompt
 
             # Determine prompt
             if turn == 0:

package/backend/core/routes/settings.py

@@ -307,10 +307,6 @@ async def get_config():
         # Mask: show only last 4 chars, e.g. ****h453
         masked_client_id = ("****" + client_id_full[-8:]) if len(client_id_full) > 8 else "****"
 
-        # Connected only if both the main token and the workspace-mcp token exist
-        mcp_token_file = os.path.join(DATA_DIR, "google-credentials", "token.json")
-        is_connected = os.path.exists(TOKEN_FILE) and os.path.exists(mcp_token_file)
-
         # Read user email from token.json if available
         user_email = None
         if has_token:
@@ -330,6 +326,20 @@ async def get_config():
             except Exception:
                 pass
 
+        # Real connectivity check: token must be valid (or refreshable) AND
+        # workspace-mcp must have a token file it can read. get_google_credentials()
+        # validates, auto-refreshes, and syncs to the MCP dir on success.
+        is_connected = False
+        try:
+            from services.google import get_google_credentials
+            if get_google_credentials() is not None:
+                mcp_dir = os.path.join(DATA_DIR, "google-credentials")
+                per_user = user_email and os.path.exists(os.path.join(mcp_dir, f"{user_email}.json"))
+                generic = os.path.exists(os.path.join(mcp_dir, "token.json"))
+                is_connected = bool(per_user or generic)
+        except Exception as e:
+            print(f"Warning: get_google_credentials() check failed: {e}")
+
         return {
             "has_credentials": True,
             "client_id": masked_client_id,
@@ -338,9 +348,7 @@ async def get_config():
             "user_email": user_email,
         }
     except Exception as e:
-        mcp_token_file = os.path.join(DATA_DIR, "google-credentials", "token.json")
-        is_connected = os.path.exists(TOKEN_FILE) and os.path.exists(mcp_token_file)
-        return {"has_credentials": True, "error": str(e), "is_connected": is_connected}
+        return {"has_credentials": True, "error": str(e), "is_connected": False}
 
 
 @router.get("/api/file")

package/backend/core/server.py

@@ -118,6 +118,15 @@ def _get_google_oauth_env() -> dict[str, str]:
     token_file = DATA_DIR / "token.json"
     if not creds_file.exists():
         return {}
+
+    # Refresh the Google token (if expired-but-refreshable) before launching
+    # workspace-mcp so the subprocess inherits valid creds and doesn't emit
+    # "ACTION REQUIRED: Google Authentication Needed" on the first tool call.
+    try:
+        from services.google import get_google_credentials
+        get_google_credentials()
+    except Exception as e:
+        print(f"Warning: Token refresh at startup failed: {e}")
     try:
         creds = json.loads(creds_file.read_text())
         installed = creds.get("installed", creds.get("web", {}))