Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Build-context exclusions for the repo-root images (api, worker, agent,
# railway-agent-worker, the two model sidecars).
#
# Every one of those Dockerfiles COPYs a handful of named paths, so anything
# here was being sent to the daemon and then ignored. The root context measured
# ~391 MB, most of it node_modules and .git.
#
# Nothing here is COPYed by any Dockerfile — check before adding a path that
# is, since the failure would be a missing file at build time rather than a
# slow build.

.git
.github
.gitignore

# Environments and secrets. .env is gitignored, but a build context is not a
# git operation: without this line it would be sent to the daemon and could
# land in an image layer.
.env
.env.*
!.env.example
!.env.production.example
.venv
venv/

# Caches and build output
__pycache__/
*.py[cod]
.pytest_cache/
.mypy_cache/
.ruff_cache/
.coverage
htmlcov/
*.egg-info/
node_modules/
dist/
build/
.vite/
coverage/
*.tsbuildinfo

# The frontend is built from its own context (apps/frontend); the backend
# images have no use for it.
apps/frontend/

# Documentation, prototypes, and 6.6 MB of recorded evaluation runs. The
# services read none of them at runtime — the figures are baked into the
# frontend bundle at build time by scripts/sync_eval_artifacts.py.
docs/
design/
results/
*.md

# Editor / OS
.idea/
.vscode/
.DS_Store
34 changes: 34 additions & 0 deletions .env.production.example
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,40 @@ REDIS_URL=redis://redis:6379/0
RABBITMQ_URL=amqp://__SET_PROD_RABBITMQ_USER__:__SET_PROD_RABBITMQ_PASSWORD__@rabbitmq:5672/
AGENT_URL=http://agent:8001

# ============================================================
# The shared-account gate (Deploy.md D-2 / D-6)
#
# docker-compose.prod.yml hardcodes AUTH_ENABLED=true, so production is gated
# whether or not this file says so, and the API refuses to start if the two
# required values below are missing. Both are secrets: they belong here, in a
# gitignored file, and never in a committed one.
#
# Generate the hash (prompts without echoing, never takes an argument, so the
# password stays out of shell history and the process list):
#
# python -m dcode_api.hash_password
#
# One shared account. There is no user table and no per-person revocation —
# to remove someone's access, rotate the password. That is the cost of D-6 and
# it is recorded there rather than discovered here.
# ============================================================
AUTH_USERNAME=reviewer
AUTH_PASSWORD_HASH=__SET_PROD_AUTH_PASSWORD_HASH__
AUTH_SESSION_SECRET=

# 12 hours. A reviewer session outliving a sitting is the intent.
# AUTH_SESSION_TTL_SECONDS=43200

# Leave true on Railway and anywhere else serving HTTPS. Set false ONLY for a
# plain-HTTP staging host: browsers silently drop a Secure cookie over http,
# so logins there appear to succeed and never stick.
# AUTH_COOKIE_SECURE=true

# The gate stops anonymous callers; it does nothing about a signed-in one
# looping a question through three metered APIs. Counted per session per UTC
# day, checked before the agent is reached.
# AUTH_DAILY_QUERY_LIMIT=200

# --- Internal service auth ---
# Protects every /internal/* retrieval and graph route. The code default is a
# placeholder published in this repository, so this must be set to a real
Expand Down
245 changes: 227 additions & 18 deletions Deploy.md

Large diffs are not rendered by default.

51 changes: 35 additions & 16 deletions apps/agent/src/dcode_agent/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ async def internal_query(
)
)
return StreamingResponse(
emitter.iter_bytes(),
emitter.iter_bytes(heartbeat_seconds=agent_settings.sse_heartbeat_seconds),
media_type="text/event-stream",
headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
)
Expand All @@ -119,23 +119,28 @@ async def _run_graph_pipeline(
llm_client: Any = None,
) -> None:
"""Invoke the compiled graph and flush terminal SSE events."""
budget = agent_settings.request_budget_seconds
try:
async with db_session_factory() as db:
final_state = await compiled_graph.ainvoke(
AgentState(
repo_id=state.repo_id,
query=state.query,
mode=state.mode,
history=state.history,
runtime={
"emitter": emitter,
"tool_registry": tool_registry,
"tool_cache": tool_cache,
"db": db,
"llm": llm_client,
},
# A ceiling on the whole walk, not just each hop. Without it a query
# can outlive the platform's request limit, and the reader sees a
# stream that stops rather than one that says why.
async with asyncio.timeout(budget if budget > 0 else None):
async with db_session_factory() as db:
final_state = await compiled_graph.ainvoke(
AgentState(
repo_id=state.repo_id,
query=state.query,
mode=state.mode,
history=state.history,
runtime={
"emitter": emitter,
"tool_registry": tool_registry,
"tool_cache": tool_cache,
"db": db,
"llm": llm_client,
},
)
)
)

state_dict = _state_dict(final_state)
citations = _citation_events(state_dict)
Expand All @@ -159,6 +164,20 @@ async def _run_graph_pipeline(
citations=citations,
groundedness=float(state_dict.get("groundedness_score") or 0.0),
)
except TimeoutError:
# Distinct from INTERNAL on purpose: "this took too long" is a
# different thing for a reader to know than "something broke", and the
# honest answer here is that no answer was produced. Nothing
# half-finished is emitted — a partial walk has not been through the
# groundedness verifier, so presenting it would claim a check that
# never ran (Honesty_Constraints §3).
await emitter.emit_error(
code="TIMEOUT",
message=(
f"the agent exceeded its {agent_settings.request_budget_seconds:.0f}s budget "
"for one question"
),
)
except Exception as exc: # noqa: BLE001 — surface any unexpected failure as SSE error
await emitter.emit_error(code="INTERNAL", message=str(exc))
finally:
Expand Down
15 changes: 15 additions & 0 deletions apps/agent/src/dcode_agent/settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,5 +24,20 @@ class AgentSettings(SharedSettings):
synthesis_max_tokens: int = 700
synthesis_temperature: float = 0.1

# --- Stream lifetime (Deploy.md R-2) ---
# A query had no overall ceiling: /internal/query spawns a task and returns
# a stream, and only the individual hops were bounded, so 14 steps x 30s
# plus rerank and synthesis could run past eight minutes with nothing to
# stop it. An abandoned request kept spending on three metered APIs with
# nobody draining the queue.
#
# 240s is chosen to expire *inside* the hosting platform's 5-minute cut, so
# the client gets a labelled `error` event instead of a connection that
# simply stops. 0 disables the ceiling.
request_budget_seconds: float = 240.0
# Comment frames while the queue is quiet. Below both the platform's
# 5-minute idle cut and the gateway client's 60s read timeout.
sse_heartbeat_seconds: float = 20.0


agent_settings = AgentSettings()
27 changes: 24 additions & 3 deletions apps/agent/src/dcode_agent/sse.py
Original file line number Diff line number Diff line change
Expand Up @@ -90,10 +90,31 @@ async def close(self) -> None:
"""Signal end-of-stream; iter_bytes() will exit on the next loop."""
await self._queue.put(None)

async def iter_bytes(self) -> AsyncIterator[bytes]:
"""Drain the queue. Caller streams these bytes to the client."""
async def iter_bytes(self, *, heartbeat_seconds: float = 0.0) -> AsyncIterator[bytes]:
"""Drain the queue. Caller streams these bytes to the client.

With `heartbeat_seconds` above zero, a comment frame is emitted
whenever the queue stays quiet that long. Two reasons it has to exist:
a hosting platform in front of this closes a request that transfers no
data for five minutes, and the gateway's own client has a 60-second
read timeout. The agent can legitimately be silent for longer than
either while a slow tool or a synthesis call runs.

A `:`-prefixed line is a comment in the SSE grammar. The frontend
parser already skips them (`src/api/client.ts`), so this changes no
client contract and adds no event type.
"""
while True:
chunk = await self._queue.get()
if heartbeat_seconds <= 0:
chunk = await self._queue.get()
else:
try:
chunk = await asyncio.wait_for(
self._queue.get(), timeout=heartbeat_seconds
)
except TimeoutError:
yield b": keep-alive\n\n"
continue
if chunk is None:
return
yield chunk
120 changes: 120 additions & 0 deletions apps/agent/tests/test_stream_lifetime.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
"""Stream keep-alive and the whole-request ceiling (Deploy.md R-2).

Both exist because of one platform fact: a request that transfers no data for
five minutes is closed, and even with data it is capped at about fifteen. The
agent previously had per-hop timeouts only, so a query could outlive both and
the reader would see a stream that simply stopped.
"""

import asyncio

import pytest
from dcode_agent.sse import SSEEmitter


async def _drain(emitter: SSEEmitter, *, heartbeat_seconds: float) -> list[bytes]:
return [chunk async for chunk in emitter.iter_bytes(heartbeat_seconds=heartbeat_seconds)]


async def test_no_heartbeat_when_disabled() -> None:
"""Zero keeps the original behaviour, so nothing changes where it is not wanted."""
emitter = SSEEmitter()
await emitter.emit_thought(1, "hello")
await emitter.close()

chunks = await _drain(emitter, heartbeat_seconds=0)

assert len(chunks) == 1
assert b"thought" in chunks[0]
assert not any(chunk.startswith(b":") for chunk in chunks)


async def test_a_quiet_stream_emits_comment_frames() -> None:
emitter = SSEEmitter()

async def finish_later() -> None:
await asyncio.sleep(0.25)
await emitter.emit_thought(1, "finally")
await emitter.close()

task = asyncio.create_task(finish_later())
chunks = await _drain(emitter, heartbeat_seconds=0.05)
await task

heartbeats = [chunk for chunk in chunks if chunk.startswith(b":")]
assert heartbeats, "a stream quiet for longer than the interval must be kept alive"
assert all(chunk == b": keep-alive\n\n" for chunk in heartbeats)
assert b"thought" in chunks[-1]


async def test_heartbeats_are_sse_comments_the_client_already_skips() -> None:
"""A `:`-prefixed line is a comment in the SSE grammar.

The frontend parser drops those already (src/api/client.ts), so this adds
no event type and changes no client contract. If the frame ever stops
starting with ':' it becomes an unparseable event instead.
"""
emitter = SSEEmitter()
await emitter.close()
assert b": keep-alive\n\n".startswith(b":")
assert (await _drain(emitter, heartbeat_seconds=10)) == []


async def test_heartbeat_does_not_swallow_the_end_of_stream() -> None:
"""close() must still terminate while the heartbeat loop is running."""
emitter = SSEEmitter()
await emitter.emit_partial_answer("x")
await emitter.close()

chunks = await asyncio.wait_for(_drain(emitter, heartbeat_seconds=0.01), timeout=2.0)

assert b"partial_answer" in chunks[0]


@pytest.mark.parametrize("budget", [0.05])
async def test_the_request_budget_emits_a_labelled_error(budget: float) -> None:
"""A query that overruns says so, rather than the connection just ending.

TIMEOUT is distinct from INTERNAL because "this took too long" is a
different thing for a reader to know than "something broke". Nothing
half-finished is emitted: a partial walk has not been through the
groundedness verifier, and presenting it would claim a check that never
ran (Honesty_Constraints §3).
"""
from dcode_agent import main as agent_main
from dcode_agent.settings import agent_settings
from dcode_agent.state import AgentState

class _NeverFinishes:
async def ainvoke(self, _state: object) -> object:
await asyncio.sleep(30)
raise AssertionError("should have been cancelled")

class _Session:
async def __aenter__(self) -> object:
return object()

async def __aexit__(self, *_: object) -> None:
return None

original = agent_settings.request_budget_seconds
agent_settings.request_budget_seconds = budget
try:
emitter = SSEEmitter()
await agent_main._run_graph_pipeline(
emitter,
AgentState(repo_id="r", query="q", mode="full", history=[]),
_NeverFinishes(),
None,
None,
_Session,
None,
)
chunks = await _drain(emitter, heartbeat_seconds=0)
finally:
agent_settings.request_budget_seconds = original

body = b"".join(chunks)
assert b"event: error" in body
assert b"TIMEOUT" in body
assert b"final_answer" not in body
Loading
Loading