core.tool_session module

Authenticated tool-call session records — the trust boundary for delegated execution.

The dedicated tools service runs the dangerous / UNSANDBOXED_EXEC / shell tools, and tools/alter_privileges.has_privilege keys authority off user_id. The request envelope carries a user_id, but the tools service must not trust it: anything able to XADD sg:stream:tools could otherwise forge an admin id and escalate.

Instead, the inference tier — which is processing an authenticated platform message — writes the real identity to a short-lived Redis record keyed by the call’s trace_id, and the tools service resolves identity (and therefore privileges) from that record, treating the envelope’s identity fields as an untrusted lookup. A forged request that references an unknown trace_id is rejected (fail-closed); one that references a real trace_id only ever gets that (legitimate, non-attacker) user’s identity. Defense-in-depth, paired with a Redis ACL that restricts XADD sg:stream:tools to inference workers (ops; see scripts/systemd/stargazer-tools.service).

exception core.tool_session.ToolSessionConflict

Bases: ValueError

A stable trace is already bound to a different authenticated identity.

core.tool_session.durable_tool_proof_ttl_seconds(config)

Return the validated shared Tools proof horizon.

The parent ledger, authenticated session, publisher proof, and abandoned reply-lane TTL all use this exact horizon. It must strictly outlive the outer turn checkpoint plus its final execution lease, and it must outlive every source-stream redelivery. Invalid or non-finite configuration is a startup error rather than a fallback to a shorter default.

Return type:

int

Parameters:

config (Any)

core.tool_session.durable_tool_parent_fingerprint(*, operation_id, trace_id, tool_name, tool_args, identity, context)

Bind one durable parent-tool execution to its authenticated payload.

Transport-only fields such as correlation_id and reply_to are deliberately excluded so a recovered outer checkpoint can ask the tools service to re-publish the cached terminal result onto a fresh process reply lane. The mutable catalog/schema generation is excluded for the same reason; stale new work is rejected separately by the service’s require_existing claim rule. Inference and the tools service share this helper so the reply reader can reject a crossed or forged result before it resolves a live waiter.

Return type:

str

Parameters:
async core.tool_session.write_session(redis, trace_id, identity, ttl=300, *, strict=False)

Persist the authenticated identity for trace_id (inference side).

identity should carry the real user_id / guild_id / channel_id / platform (and optional user_aliases) of the message being processed. No-op when trace_id is empty.

Return type:

None

Parameters:
async core.tool_session.read_session(redis, trace_id, *, strict=False)

Return the authenticated identity for trace_id, or None if absent.

Return type:

Optional[dict[str, Any]]

Parameters: