Skip to content

docket-runtime API Reference

docket-runtime is the embeddable, policy-gated tool runtime shipped from the same source as the docket CLI (see packages/docket-runtime). It is a library a host application embeds, not a second CLI or a hosted service — see DOCKET.md for the embedding model this facade exists to support.

Only the names in docket_runtime.__all__ are the supported public surface; everything else (including the docket_runtime._internal tree a wheel build generates from docket's own core/edges modules) is private and may change without notice.

docket_runtime

The stable, embeddable Docket runtime facade.

Only the names exported here are public. The implementation remains private so embedding applications keep one supported path to Docket's policy and tool dispatch chokepoint.

Runtime dataclass

One embedding-owned registry that always dispatches through Docket's gate.

approval_stub is intentionally a test/host seam, not a second driver: it answers a token created by the existing approval store, then the normal dispatch path continues to audit and execute (or deny) the call.

Source code in packages/docket-runtime/src/docket_runtime/__init__.py
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
88
89
@dataclass
class Runtime:
    """One embedding-owned registry that always dispatches through Docket's gate.

    ``approval_stub`` is intentionally a test/host seam, not a second driver:
    it answers a token created by the existing approval store, then the normal
    dispatch path continues to audit and execute (or deny) the call.
    """

    approval_stub: ApprovalStub | None = None
    _registry: ToolRegistry = field(default_factory=ToolRegistry, init=False, repr=False)

    def register(self, tool: Tool) -> None:
        self._registry.register(tool)

    def tool_specs(self) -> tuple[ToolSpec, ...]:
        return tuple(self._registry.specs())

    def dispatch(self, call: ToolCall, context: ToolContext) -> ToolResult:
        with self._approval_stubbed():
            return _dispatch_tool(call, context, self._registry)

    def start_execution(self, context: ToolContext, limits: ExecutionLimits) -> GovernedExecution:
        return GovernedExecution(self.dispatch, context, limits)

    @contextmanager
    def _approval_stubbed(self) -> Iterator[None]:
        if self.approval_stub is None:
            yield
            return

        with _APPROVAL_STUB_LOCK:
            original = _approval.wait_for_approval

            def respond(token: str) -> object:
                if self.approval_stub is not None and self.approval_stub(token):
                    _approval.approval_grant(token, channel="runtime")
                else:
                    _approval.approval_deny(token, channel="runtime")
                return original(token)

            _approval.wait_for_approval = respond
            try:
                yield
            finally:
                _approval.wait_for_approval = original

Execution limits and results

docket_runtime._execution

Bounded execution state for external runtime adapters.

ExecutionLimits dataclass

Measured token and admitted tool-call limits for one execution.

Source code in packages/docket-runtime/src/docket_runtime/_execution.py
19
20
21
22
23
24
25
26
27
28
29
30
@dataclass(frozen=True)
class ExecutionLimits:
    """Measured token and admitted tool-call limits for one execution."""

    token_budget: int
    max_tool_calls: int

    def __post_init__(self) -> None:
        if self.token_budget <= 0:
            raise ValueError("token_budget must be positive")
        if self.max_tool_calls <= 0:
            raise ValueError("max_tool_calls must be positive")

ExecutionResult dataclass

The single immutable terminal result of a governed execution.

Source code in packages/docket-runtime/src/docket_runtime/_execution.py
33
34
35
36
37
38
39
40
41
42
43
@dataclass(frozen=True)
class ExecutionResult:
    """The single immutable terminal result of a governed execution."""

    ok: bool
    output: str
    stop_reason: ExecutionStopReason
    usage: TokenUsage
    tool_calls_executed: int
    handoff: HandoffArtifact
    error: str = ""

GovernedExecution

Bind reported responses to bounded, sequential tool dispatches.

Source code in packages/docket-runtime/src/docket_runtime/_execution.py
 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
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
class GovernedExecution:
    """Bind reported responses to bounded, sequential tool dispatches."""

    def __init__(
        self,
        dispatch: Dispatch,
        context: ToolContext,
        limits: ExecutionLimits,
    ) -> None:
        self._dispatch = dispatch
        self._context = context
        self._limits = limits
        self._usage = TokenUsage()
        self._pending: list[ToolCall] = []
        self._tool_calls_executed = 0
        self._terminal: ExecutionResult | None = None

    def record_response(
        self, usage: TokenUsage, tool_calls: Sequence[ToolCall]
    ) -> ExecutionResult | None:
        """Accumulate measured usage and admit one complete ordered call batch."""
        self._require_active()
        if self._pending:
            raise RuntimeError("the prior response still has pending tool calls")
        if not isinstance(usage, TokenUsage):
            raise TypeError("usage must be endpoint-reported TokenUsage")

        calls = tuple(tool_calls)
        self._usage = TokenUsage(
            input_tokens=self._usage.input_tokens + usage.input_tokens,
            output_tokens=self._usage.output_tokens + usage.output_tokens,
            cached_tokens=self._usage.cached_tokens + usage.cached_tokens,
        )
        if self._usage.total_tokens > self._limits.token_budget:
            return self._stop("token_budget", "reported token budget exceeded")
        if self._tool_calls_executed + len(calls) > self._limits.max_tool_calls:
            return self._stop("max_tool_calls", "tool-call budget exceeded")

        self._pending.extend(calls)
        return None

    def dispatch(self, call: ToolCall) -> ToolResult:
        """Dispatch the next exact admitted call through the runtime facade."""
        self._require_active()
        if not self._pending:
            raise RuntimeError("no tool call is pending")
        if call != self._pending[0]:
            raise RuntimeError("tool calls must be dispatched in admitted order")

        trace_event(
            self._context.project,
            self._context.session_key,
            self._context.role,
            "tool_call",
            json.dumps({"tool": call.name, "callId": call.id, "arguments": call.arguments}),
        )
        result = self._dispatch(call, self._context)
        self._pending.pop(0)
        if result.denial_kind != "run_cancelled":
            self._tool_calls_executed += 1
        payload = {
            "tool": call.name,
            "callId": call.id,
            "decision": result.decision,
            "ok": result.ok,
            "executed": result.executed,
        }
        if result.denial_kind is not None:
            payload["denialKind"] = result.denial_kind
        trace_event(
            self._context.project,
            self._context.session_key,
            self._context.role,
            "tool_result",
            json.dumps(payload),
        )
        return result

    def finish(self, summary: str) -> ExecutionResult:
        """Finish successfully once all admitted calls have been dispatched."""
        self._require_active()
        if self._pending:
            raise RuntimeError("cannot finish while tool calls remain pending")
        self._terminal = ExecutionResult(
            ok=True,
            output=summary,
            stop_reason="final_message",
            usage=self._usage,
            tool_calls_executed=self._tool_calls_executed,
            handoff=HandoffArtifact(summary=summary),
        )
        return self._terminal

    def _require_active(self) -> None:
        if self._terminal is not None:
            raise RuntimeError("execution is already terminal")

    def _stop(self, reason: ExecutionStopReason, error: str) -> ExecutionResult:
        self._terminal = ExecutionResult(
            ok=False,
            output="",
            stop_reason=reason,
            usage=self._usage,
            tool_calls_executed=self._tool_calls_executed,
            handoff=HandoffArtifact(summary=""),
            error=error,
        )
        return self._terminal

dispatch(call)

Dispatch the next exact admitted call through the runtime facade.

Source code in packages/docket-runtime/src/docket_runtime/_execution.py
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def dispatch(self, call: ToolCall) -> ToolResult:
    """Dispatch the next exact admitted call through the runtime facade."""
    self._require_active()
    if not self._pending:
        raise RuntimeError("no tool call is pending")
    if call != self._pending[0]:
        raise RuntimeError("tool calls must be dispatched in admitted order")

    trace_event(
        self._context.project,
        self._context.session_key,
        self._context.role,
        "tool_call",
        json.dumps({"tool": call.name, "callId": call.id, "arguments": call.arguments}),
    )
    result = self._dispatch(call, self._context)
    self._pending.pop(0)
    if result.denial_kind != "run_cancelled":
        self._tool_calls_executed += 1
    payload = {
        "tool": call.name,
        "callId": call.id,
        "decision": result.decision,
        "ok": result.ok,
        "executed": result.executed,
    }
    if result.denial_kind is not None:
        payload["denialKind"] = result.denial_kind
    trace_event(
        self._context.project,
        self._context.session_key,
        self._context.role,
        "tool_result",
        json.dumps(payload),
    )
    return result

finish(summary)

Finish successfully once all admitted calls have been dispatched.

Source code in packages/docket-runtime/src/docket_runtime/_execution.py
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def finish(self, summary: str) -> ExecutionResult:
    """Finish successfully once all admitted calls have been dispatched."""
    self._require_active()
    if self._pending:
        raise RuntimeError("cannot finish while tool calls remain pending")
    self._terminal = ExecutionResult(
        ok=True,
        output=summary,
        stop_reason="final_message",
        usage=self._usage,
        tool_calls_executed=self._tool_calls_executed,
        handoff=HandoffArtifact(summary=summary),
    )
    return self._terminal

record_response(usage, tool_calls)

Accumulate measured usage and admit one complete ordered call batch.

Source code in packages/docket-runtime/src/docket_runtime/_execution.py
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def record_response(
    self, usage: TokenUsage, tool_calls: Sequence[ToolCall]
) -> ExecutionResult | None:
    """Accumulate measured usage and admit one complete ordered call batch."""
    self._require_active()
    if self._pending:
        raise RuntimeError("the prior response still has pending tool calls")
    if not isinstance(usage, TokenUsage):
        raise TypeError("usage must be endpoint-reported TokenUsage")

    calls = tuple(tool_calls)
    self._usage = TokenUsage(
        input_tokens=self._usage.input_tokens + usage.input_tokens,
        output_tokens=self._usage.output_tokens + usage.output_tokens,
        cached_tokens=self._usage.cached_tokens + usage.cached_tokens,
    )
    if self._usage.total_tokens > self._limits.token_budget:
        return self._stop("token_budget", "reported token budget exceeded")
    if self._tool_calls_executed + len(calls) > self._limits.max_tool_calls:
        return self._stop("max_tool_calls", "tool-call budget exceeded")

    self._pending.extend(calls)
    return None