Skip to content

symfonic.capabilities.human.live_binding

live_binding

A :class:PauseBinding for the run that is pausing, read when it pauses.

human_interaction(binding=...) takes a zero-argument callable, and the pause stage calls it inside the run. Every field a deployment owns -- pin, scope, session, thread, checkpoint -- it can close over. The two it does not own are the run's own ids, and before this module the only way to read them was a kernel accessor no public package exports. A binding that guessed them, or named a run nobody issued, pauses fine and is refused at resume.

So this copies the two ids out of the active run and nothing else:

  • it takes no run_id or root_run_id. A caller cannot hand one in, so it can never be silently overridden;
  • it keeps the id strings, not the identity object, so a pause never extends the life of the run's lineage;
  • outside a run it refuses, rather than returning a binding with no run;
  • it proves nothing. A run whose lineage cannot be proven at resume is refused there exactly as before; this only stops the deployment from naming the wrong one.

Pin, scope, session, thread and checkpoint are copied through as given; only the two run ids come from the run. Those fields are deployment-owned: they are signed into the pause, but the signature, expiry, lineage admission and claim checks do not know which session or scope the resuming request expects. A wrong value is caught only where the deployment's own authority compares it (for example its continuation or scope wiring); nothing here checks it for you.

current_run_binding 

current_run_binding(*, pin: Any = None, scope: Any = None, session_id: str = '', thread_id: str = '', checkpoint_id: str | None = None) -> PauseBinding

Bind a pause to the active run, with the caller's own metadata.

human_interaction(
    signer=signer,
    encode_token=encode,
    binding=lambda: current_run_binding(scope=scope, session_id=session_id),
)

Call it from inside the binding callable, which the pause stage invokes while the turn is running. run_id is that turn's id and root_run_id is its root, or the run itself for a top-level turn.

Raises:

Type Description
InteractionConfigurationError

if no run is active in this context, as when the helper is called while composing the agent rather than from the binding.
Source code in src/symfonic/capabilities/human/live_binding.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def current_run_binding(
    *,
    pin: Any = None,
    scope: Any = None,
    session_id: str = "",
    thread_id: str = "",
    checkpoint_id: str | None = None,
) -> PauseBinding:
    """Bind a pause to the active run, with the caller's own metadata.

        human_interaction(
            signer=signer,
            encode_token=encode,
            binding=lambda: current_run_binding(scope=scope, session_id=session_id),
        )

    Call it from inside the ``binding`` callable, which the pause stage invokes
    while the turn is running. ``run_id`` is that turn's id and ``root_run_id``
    is its root, or the run itself for a top-level turn.

    Raises:
        InteractionConfigurationError: if no run is active in this context, as
            when the helper is called while composing the agent rather than
            from the binding.
    """
    # Function-local: the accessor is the kernel's declared read-only port, and
    # reading it here keeps the import off this package's eager graph.
    from symfonic.kernel.contracts.run_identity import current_run_identity

    identity = current_run_identity()
    run_id = str(identity.run_id) if identity is not None else ""
    if not run_id:
        raise InteractionConfigurationError(
            "current_run_binding() was called but no run is active in this "
            "context, so there is no run to bind the pause to; call it from "
            "the binding callable, which the pause stage invokes during a turn"
        )
    root_run_id = str(identity.root_run_id or run_id)
    del identity
    return PauseBinding(
        pin=pin,
        scope=scope,
        run_id=run_id,
        root_run_id=root_run_id,
        session_id=session_id,
        thread_id=thread_id,
        checkpoint_id=checkpoint_id,
    )