@onepointfour-packs/flaredeck-agent 0.1.0 → 0.2.1

package/python/sidecar.py

@@ -66,7 +66,19 @@ async def gate(data):
         "args": args,
     })
     if not verdict.get("allow", False):
-        return HookResult(allow=False, message=verdict.get("message", "Refused by the harness."))
+        # Either key. The harness grew a second set of guards that answer with `reason` while
+        # this read only `message`, so every one of them reached the model as the bare words
+        # "Refused by the harness." — no which-checkout, no use-push_branch, no the-card-is-not-
+        # finished. An agent that is told no and not told why cannot correct; it argues, or goes
+        # looking. Reading both means a new guard cannot be silent by picking the other word.
+        why = verdict.get("reason") or verdict.get("message")
+        return HookResult(
+            allow=False,
+            message=str(why) if why else (
+                "The harness refused this and gave no reason, which is a bug in the harness. "
+                "Do not retry it unchanged; say on the card what you were trying to do."
+            ),
+        )
     modified = verdict.get("modified_args")
     if modified:
         return HookResult(allow=True, modified_args=modified)
@@ -84,9 +96,178 @@ async def seen(data):
     return None
 
 
+# What a flush is worth saying on its own. Model text arrives in small pieces; one harness event
+# per piece would be a pane of fragments, and one event for the whole turn — which is what
+# `response.text()` gave — is a blank pane for minutes and then a wall.
+FLUSH_CHARS = 280
+
+# How long the model may say NOTHING before the turn is abandoned. It streams text, thinking and
+# tool calls, so a silence this long is a stalled stream rather than a long thought: HR-0622 sat
+# eleven minutes with an open connection to Google, zero CPU, and no chunk — and nothing noticed,
+# because the harness only ever waited. An unattended agent cannot wait forever.
+STALL_SECONDS = float(os.environ.get("FLAREDECK_AGENT_STALL_SECONDS", "300"))
+
+
+async def stdin_lines() -> asyncio.StreamReader:
+    """
+    stdin as an async stream.
+
+    Deliberately not `run_in_executor(sys.stdin.readline)`: that parks a thread in the default
+    executor, which `asyncio.run` waits for at shutdown — and since the harness holds the pipe open
+    for the life of the process, the read never returns and the sidecar hangs on exit instead of
+    dying. This also means ONE reader owns the fd, so the run message and any steer come off the
+    same stream and nothing is lost to buffering.
+    """
+    loop = asyncio.get_running_loop()
+    reader = asyncio.StreamReader()
+    await loop.connect_read_pipe(lambda: asyncio.StreamReaderProtocol(reader), sys.stdin)
+    return reader
+
+
+async def _steers(queue: "asyncio.Queue[str]", lines: asyncio.StreamReader) -> None:
+    """
+    Lines the harness sends while a turn is running. stdin was read once, for the run message, and
+    then never again, so anything typed into the pane had nowhere to go.
+    """
+    while True:
+        raw = await lines.readline()
+        if not raw:
+            return
+        try:
+            msg = json.loads(raw.decode())
+        except Exception:  # noqa: BLE001
+            continue
+        if msg.get("type") == "steer" and msg.get("text"):
+            await queue.put(str(msg["text"]))
+
+
+async def _drain(response, said: list[str]) -> None:
+    """
+    One turn's chunk stream, mapped onto harness events as it arrives.
+
+    `response.text()` waits for everything and returns a single string, which is why a Gemini turn
+    showed nothing at all until it was over. The same response exposes the semantic stream; this
+    reads that instead, so text, thinking and tool calls appear while they happen.
+    """
+    buffer: list[str] = []
+
+    def flush() -> None:
+        joined = "".join(buffer).strip()
+        buffer.clear()
+        if joined:
+            said.append(joined)
+            emit({"type": "event", "kind": "text", "text": joined})
+
+    # `chunks` is a PROPERTY returning a fresh cursor, not a method. Calling it raises
+    # "'async_generator' object is not callable" — which a hand-written fake that defines it as a
+    # method will never show you. Iterated by hand rather than with `async for`, so that every
+    # chunk has a deadline and a stalled stream ends the turn instead of hanging it.
+    cursor = response.chunks.__aiter__()
+    while True:
+        try:
+            chunk = await asyncio.wait_for(cursor.__anext__(), timeout=STALL_SECONDS)
+        except StopAsyncIteration:
+            break
+        except asyncio.TimeoutError:
+            emit({"type": "event", "kind": "tool",
+                  "name": f"no output from the model for {int(STALL_SECONDS // 60)}m — abandoning this turn"})
+            try:
+                response.cancel()
+            except Exception:  # noqa: BLE001
+                pass
+            break
+
+        kind = type(chunk).__name__
+        if kind == "Text":
+            buffer.append(chunk.text)
+            # On a paragraph break, or once it has said enough to be worth reading.
+            if "\n\n" in chunk.text or sum(len(x) for x in buffer) >= FLUSH_CHARS:
+                flush()
+        elif kind == "Thought":
+            # Its reasoning, one line of it: enough to tell a thinking agent from a stuck one
+            # without turning the pane into a transcript of everything it considered.
+            first_line = (chunk.text or "").strip().splitlines()
+            if first_line:
+                emit({"type": "event", "kind": "tool", "name": f"thinking · {first_line[0][:110]}"})
+        elif kind == "ToolCall":
+            name = str(getattr(chunk, "name", "") or "")
+            args = getattr(chunk, "args", None) or {}
+            if name == "run_command":
+                # The SDK has used more than one name for this; rather than guess, take the first
+                # string that looks like a command. A bare "run_command" in the pane says nothing.
+                command = ""
+                for key in ("CommandLine", "command", "Command", "cmd", "script"):
+                    if str(args.get(key, "") or "").strip():
+                        command = str(args[key]).strip()
+                        break
+                if not command:
+                    # Last resort, and it must not pick the WORKING DIRECTORY, which is the
+                    # longest string in these args and told you nothing: the pane read
+                    # "run_command · /Users/…/agent-xgv0osv9…" for every shell call.
+                    guesses = [
+                        v.strip() for k, v in args.items()
+                        if isinstance(v, str) and v.strip()
+                        and k.lower() not in ("cwd", "workingdirectory", "working_dir", "dir", "path")
+                        and not v.strip().startswith("/")
+                    ]
+                    command = max(guesses, key=len) if guesses else ""
+                if command:
+                    name = f"run_command · {command[:120]}"
+            server = str(getattr(chunk, "server_name", "") or "")
+            emit({"type": "event", "kind": "tool", "name": f"{server + ': ' if server else ''}{name}"})
+        elif kind == "ToolResult":
+            error = getattr(chunk, "error", None)
+            if error:
+                emit({"type": "event", "kind": "tool",
+                      "name": f"{getattr(chunk, 'name', 'tool')} failed · {str(error)[:140]}"})
+    flush()
+
+
+async def run_turn(agent, brief: str, lines: asyncio.StreamReader) -> str:
+    """
+    Run a turn, streaming it, and let the harness interrupt it.
+
+    A steer cancels the response in flight and sends what was typed as the next message. The
+    conversation keeps its history, so the model sees what it had already done and carries on from
+    there rather than starting over.
+    """
+    queue: "asyncio.Queue[str]" = asyncio.Queue()
+    reader = asyncio.create_task(_steers(queue, lines))
+    said: list[str] = []
+    prompt = brief
+    try:
+        while True:
+            response = await agent.chat(prompt)
+            drain = asyncio.create_task(_drain(response, said))
+            steer = asyncio.create_task(queue.get())
+            done, _ = await asyncio.wait({drain, steer}, return_when=asyncio.FIRST_COMPLETED)
+
+            if drain in done:
+                steer.cancel()
+                drain.result()  # re-raise anything the stream failed with
+                # Something typed while the turn was finishing is the next turn, not lost input.
+                if not queue.empty():
+                    prompt = queue.get_nowait()
+                    emit({"type": "event", "kind": "tool", "name": "picking up what you typed"})
+                    continue
+                return "\n\n".join(said).strip()
+
+            prompt = steer.result()
+            emit({"type": "event", "kind": "tool", "name": "interrupted — taking what you typed"})
+            response.cancel()
+            drain.cancel()
+            try:
+                await drain
+            except asyncio.CancelledError:
+                pass
+    finally:
+        reader.cancel()
+
+
 async def main() -> None:
     global GUARD_URL
-    first = json.loads(sys.stdin.readline())
+    lines = await stdin_lines()
+    first = json.loads((await lines.readline()).decode())
     if first.get("type") != "run":
         emit({"type": "fatal", "message": f"expected a run message, got {first.get('type')!r}"})
         return
@@ -96,7 +277,9 @@ async def main() -> None:
         "system_instructions": first.get("system_instructions") or "",
         "policies": [policy.allow_all()],   # the gate above is the policy; this just defers to it
         "hooks": [gate, seen],
-        "workspaces": [first["cwd"]],
+        # What it may CHANGE, which is not always where it starts: a turn with no card reads the
+        # shared checkout and writes only to scratch space.
+        "workspaces": first.get("workspaces") or [first["cwd"]],
     }
     # FlareDeck, reached over HTTP with the HARNESS's own token — so the model's tools act as the
     # same account the harness listens as. Two identities for one agent is a thing that has gone
@@ -114,6 +297,28 @@ async def main() -> None:
         kwargs["api_key"] = os.environ["GEMINI_API_KEY"]
     if first.get("model"):
         kwargs["model"] = first["model"]
+
+    # How hard it thinks. The option rides on the Gemini endpoint, which means naming the model as
+    # a ModelTarget rather than a bare string — so this is attempted and then abandoned quietly if
+    # the SDK disagrees: a tuning knob must never be the reason a card fails. Vertex is left alone
+    # because its endpoint is a different type and nothing here has exercised it.
+    level = first.get("thinking_level")
+    if level and kwargs.get("model") and not kwargs.get("vertex"):
+        try:
+            from google.antigravity.types import (
+                GeminiAPIEndpoint, GeminiModelOptions, ModelTarget, ModelType, ThinkingLevel,
+            )
+            kwargs["model"] = ModelTarget(
+                name=str(kwargs["model"]),
+                types=[ModelType.TEXT],
+                endpoint=GeminiAPIEndpoint(
+                    api_key=kwargs.get("api_key"),
+                    options=GeminiModelOptions(thinking_level=ThinkingLevel(level)),
+                ),
+            )
+        except Exception as e:  # noqa: BLE001
+            emit({"type": "event", "kind": "tool",
+                  "name": f"thinking level {level} not applied ({type(e).__name__}) — running at the default"})
     if first.get("resume"):
         kwargs["conversation_id"] = first["resume"]
 
@@ -151,10 +356,7 @@ async def main() -> None:
               "apiKeySource": "vertex" if kwargs.get("vertex") else "gemini-api-key",
               "permissionMode": "harness-gated",
               "sessionId": str(getattr(agent, "conversation_id", "") or "")})
-        response = await agent.chat(first["brief"])
-        text = await response.text()
-        if text:
-            emit({"type": "event", "kind": "text", "text": text})
+        text = await run_turn(agent, first["brief"], lines)
         # The session id only exists AFTER the first turn — conversation_id is None until then —
         # so the ready event above could never carry it, and the harness, finding no session,
         # skipped the handover entirely: "no session to write a handover from". That handover is