[igalshilman]

Three pieces of work on restate.agents, in the order they landed. The TypeScript side is restatedev/sdk-sessions#24; the two SDKs must agree on the companion's name before either releases.

Each agent brings its own companion

signals was one virtual object for the whole endpoint, keyed <agent>:<key>. There is one service of that name in a Restate cluster, so a Python endpoint and a TypeScript endpoint registered against the same cluster take the name from each other: whichever registered last serves the companion for both SDKs' agents, with its own handler set and payload details, and nothing warns about it. Serving one agent per image has the same problem inside one language, since every image also serves signals.

Now each agent brings its own, <agent>.prebuilt.restate, keyed as the agent and served beside it through __restate_services__. A companion is as unique as its agent, and an agent's name is already unique in a cluster. agent in the suffix said nothing the agent's own name does not, so the marker is .prebuilt.restate; Restate refuses names that start with restate, so it stays a suffix.

The companion holds what it always held: the tools' waits, the message being answered, the steering inbox, and the conversation's revision. Its handler names and payloads are unchanged, including the camelCase awaitTurn that is wire-shared with the TypeScript SDK.

No migration. The shared signals and the per-agent companion are both preview, and the state does not move: the new object starts empty for every key. The conversation itself is untouched — it lives in the key's SQL database, and the companion holds none of it.

docs/agents/prebuilt.md records the decision and why the shared name could not stay. The companion's name is not guarded: an agent named support.prebuilt.restate would own agent support's companion name, and Endpoint.bind catches that only within one endpoint. The note says so.

The chat turn publishes; the conversation stores

Publishing belongs to the agent's chat turn rather than to answer_once: an agent's own handlers publish their steps and the turn's end, with one settle per commit. A retry that finds the turn already answered publishes its end too, so an attempt that died between the commit storing the answer and the publish does not leave followers waiting for a watch timeout. A signal wait from a handler of a plain session object now fails for good with NeedsAgent, as it does in TypeScript, rather than calling a service nobody serves and being retried until the turn hangs. docs/agents/turns.md says which layer stores and which publishes.

AgentContext and AgentViewContext

The agents' API and a session object's took the same context, so a handler reaching up a layer was only found out while the turn ran, after a model round-trip, looking like a tool failure.

The two protocols name the layer in the signature. They are a signpost, not a fence: the marker member is declared and never exists at runtime, nothing reads it, restate/sessions/ does not change, and NeedsAgent stays the guard that actually stops the wait. They are applied to the agent's registration surface — chat()'s answer, the built-in views, the private handlers (erase, settle, compact, steered, clear, sync, messages, steer), and the turn's publish helpers.

chat's TypeVar bound moves with it, which is the one strict signature on the public surface. Everything else is additive: parameter types are contravariant, so a handler annotated SessionContext still registers on an agent and still type-checks, and no existing user code breaks.

The conversation stays on SessionContext, deliberately. A handler of a plain session object drives answer_once — tests/agents_conversation.py registers it on a sessions.SessionObject, and each framework's public prompt(ctx: SessionContext, ...), the documented "for a handler of your own", funnels into it. The same holds for wait_for, take_steers, settings_of, companion_at and the LangGraph signal node, which are reached from a framework's prompt() or are the probes that find out which tier they are on. docs/agents/contexts.md says what narrowed and what could not, and why.

The tools (tool, call, send, workflow, subagent) and ToolCall.ctx stay on SessionContext too: a tool is a value a framework may run from either tier, so the type cannot reach through it.

Merging main's #310

main gained journal timing and the hiding of an agent's bookkeeping calls (ENTRY_NAME, hide_entries) while this branch was open, written against the shared signals and its <agent>:<key> addressing. The merge keeps this branch's per-agent companion calls and carries #310's entry name onto them, so every call main names is named here: the views, _stopped, steer, erase's reset, sync's reads, the turn's start/publish/close, and the taken send. main's naming test is kept whole, with its expected handlers re-pointed from signals/... to <agent>.prebuilt.restate/....

Two things left as main has them, worth a decision separately: ENTRY_NAME is still the literal "signals", now a stale label for an object of another name that deployed agents' metadata already carries; and the companion's wait calls are the one kind that stays unnamed, so a tool's wait is visible in the UI while every other bookkeeping call is hidden.

Verified

ruff check clean, pyright python/ 0 errors, pyright tests 0 errors, mypy clean. The agents and sessions suites run 560 passed, 0 failed.

The server-backed tests ran against a local restate-server binary rather than the Docker harness, since this environment has no Docker daemon; CI runs them the usual way.

Nothing under restate/sessions/ changed: git diff main...HEAD -- python/restate/sessions/ is empty.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RePHkSS8KRKmJ93hcd9asV

[pullfrog]

ℹ️ No critical issues. Two rough edges are flagged inline.

Reviewed changes

This review covers the full PR at e3ede15: the per-agent companion, the split between storing and publishing, and the new context protocols. The in-process suites agents_companion, agents_conversation and agents_publishes pass locally (81 passed).

• A companion for each agent: make_companion(agent) builds an ingress-private <agent>.prebuilt.restate virtual object keyed as the agent, and it replaces the shared signals. AgentObject.__restate_services__ serves it beside the agent, and Started.settles is gone because only chat_turn starts turns.
• The conversation only stores: answer_once now runs whatever its caller set through after_steps / after_answer. The AgentObject handler wrapper sets both. chat_turn keeps the per-step publishes but clears the end publish, because close already publishes the end. A plain SessionObject neither publishes nor looks up a companion.
• NeedsAgent: a signal wait from a plain session object now fails the turn for good. Tool.run and Pydantic AI's on_tool_execute_error let it propagate instead of returning it to the model as a tool result.
• AgentContext / AgentViewContext: these protocols mark the agent layer in signatures using a phantom _agent member. They now type chat()'s TypeVar bound, the built-in views, the private handlers and the turn's publish helpers.
• API changes in _signals and internal: companion_of(agent) no longer takes a key and returns the handlers. companion_at, companion_in and waits_in replace signals_of. signals is removed from internal.__all__.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}

[pullfrog]

✅ No new issues found. Both earlier findings are addressed.

Reviewed changes

This review covers f6d4d49, the one commit pushed since the last Pullfrog review. I re-ran the in-process agents_publishes, agents_conversation, agents_companion and agents_object suites: 82 passed. The 12 errors were Docker-harness tests, and there is no Docker in this environment. I also reproduced the retry directly. When ask is invoked again with the same invocation id, the turn's answer is already stored. The handler returns "done" and publishes exactly once, and that publish already shows the answer.

• A retry that finds the turn answered now publishes its end: answer_once reads after_answer_of(ctx) before the answer_in early return and awaits it there. An attempt that dies between committing the answer and publishing it no longer leaves followers waiting. chat is unaffected, because chat_turn clears the hook. The publish_end docstring now describes this path.
• docs/agents/prebuilt.md no longer describes a name guard: the doc now says that an agent named <x>.prebuilt.restate is deliberately not refused. Endpoint.bind catches the clash only within one endpoint. The "what must hold" list no longer includes the refusal.

  ^{｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}

[pullfrog]

✅ No new issues found. The merge of main carries #310's entry naming over to the per-agent companion completely.

Reviewed changes

This review covers 86f7556, the merge of upstream main (with #310) into the branch. I checked that the merge resolved the agents code correctly. The in-process agents_publishes, agents_conversation, agents_companion, agents_object and sessions_object suites pass (111 passed). The 12 errors are Docker-harness tests, which cannot run in this environment. ruff check is clean.

• Named the companion calls: every agent call to the companion that main names signals is named on the branch too. That covers the views (signal, pending, status, notifications, watch), _stopped, steer, the reset in erase, sync's watch and reads, the turn's start/publish/close, and the taken send. Tool waits stay unnamed, as they are on main.
• Merged the hiding metadata: AgentObject puts hide_entries(_signals.ENTRY_NAME) under any metadata the user passes, so an agent's own metadata still wins.
• Adapted the naming test: the new test_the_calls_to_the_companion_are_named_for_the_agents_metadata_to_hide_them now expects <agent>.prebuilt.restate/... handlers, not signals/....

  ^{｜ View workflow run ｜ Using claude-opus-5-5 ｜ 𝕏}

[github-actions]

Test Results

  8 files  ±0    8 suites  ±0   3m 30s ⏱️ -16s
 71 tests ±0   71 ✅ ±0  0 💤 ±0  0 ❌ ±0 
322 runs  ±0  322 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit 86f7556. ± Comparison against base commit 0cd30df.