runkite-governance 0.8.0__tar.gz

runkite_governance-0.8.0/LICENSE

@@ -0,0 +1,180 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

runkite_governance-0.8.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE NOTICE README.md pyproject.toml __init__.py agent_framework.py py.typed
+global-exclude test_*.py e2e_*.py *.py[cod]
+prune tests
+prune build
+prune dist
+prune .venv

runkite_governance-0.8.0/NOTICE

@@ -0,0 +1,5 @@
+Runkite
+Copyright 2026 Sharan Harsoor
+
+Runkite's first-party code is licensed under the Apache License, Version 2.0.
+Third-party components retain their respective copyrights and license terms.

runkite_governance-0.8.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: runkite-governance
+Version: 0.8.0
+Summary: Small decide and pending-action helper for app-owned agent loops.
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/getrunkite/runkite
+Project-URL: Documentation, https://github.com/getrunkite/runkite/blob/main/docs/client-sdk.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: agent-framework
+Requires-Dist: agent-framework-core==1.23.0; extra == "agent-framework"
+Dynamic: license-file
+
+# Runkite governance helper
+
+A standard-library-only Python client for `POST /governance/decide` and `GET /governance/actions/{id}` on your self-hosted Runkite plane. It does not depend on the runner package or an agent framework.
+
+This helper has its own distribution, separate from `runkite-runner`. The
+published Runkite 0.7.0 release did not include it. Use the registry command
+only for a version whose publication has been verified:
+
+```sh
+python -m pip install runkite-governance
+```
+
+For source that has not been published, install from a checkout:
+
+```sh
+python -m pip install ./python/runkite_governance
+```
+
+The runtime requires Python 3.11 or newer. Installing a managed runner does not
+install this decision-only helper.
+
+```python
+from runkite_governance import GovernanceClient
+
+governance = GovernanceClient("http://localhost:2026", api_key="server-side-key", timeout_ms=10_000)
+decision = governance.decide(
+    agent_id="notes-app",
+    connector="workspace",
+    tool="createNote",
+    args={"title": "Release notes", "body": "A draft"},
+    run_id="stable-app-turn-and-tool-call-id",
+)
+```
+
+Your application executes after `allow`, refuses after `deny`, and persists the action ID and exact original arguments after `pending`. On a later application request, use `governance.action(action_id)` and execute only after `approved`. Rejected or consumed actions must not execute. Implement idempotency in the application's database: GET does not consume approval.
+
+`resolve(...)` performs a bounded wait and returns an allow/deny outcome. Its deadline covers the initial decision and every poll. `decide` and `action` accept `timeout_ms` and a `threading.Event` as `cancelled`. Cancellation stops the caller promptly. Blocking standard-library I/O unwinds separately with a socket timeout and response-chunk checks; a bounded shared worker pool prevents unlimited abandoned resolver/socket threads. Do not hold a serverless request open for long operator approval.
+
+Use a server-side key with `governance:decide`. Tenant identity comes from that key. The caller retains its model loop and tool execution. This path creates no Runkite thread or run and does not apply run kill switches, break-glass or spend caps. It is separate from the deliberately deferred full client SDK.
+
+## Optional Microsoft Agent Framework middleware
+
+For a verified registry release, install the optional middleware with:
+
+```sh
+python -m pip install 'runkite-governance[agent-framework]'
+```
+
+For unpublished source, install the extra from a checkout:
+
+```sh
+python -m pip install './python/runkite_governance[agent-framework]'
+```
+
+The extra pins the tested framework core; model-provider packages remain
+application choices.
+
+Import `GovernanceFunctionMiddleware`, `GovernedFunction`,
+`GovernanceBlockedError` and `PendingInvocation` from
+`runkite_governance.agent_framework`. Register exact local `FunctionTool` objects,
+server-owned policy identities and an application operation-ID callback. Install
+the guard last, after argument repair. It snapshots JSON arguments and Python
+defaults, decides once, and reaches native execution only after allow. Deny and
+pending stop the agent with a native `MiddlewareFailure`; an optional async
+`on_pending` callback persists the exact frozen proposal first.
+
+The app owns pending continuation and execution idempotency. Rich Python types,
+coercing validators and provider-executed tools are outside this adapter's scope.
+See the [framework example](https://github.com/getrunkite/runkite/tree/main/examples/governance_agent_framework/README.md)
+for a durable application transaction, offline streaming and non-streaming tests,
+and supported argument constraints. Execution retains native mutable containers;
+the app must not mutate invocation arguments after authorization. Importing the
+base client does not import the optional framework. This extra is not a runner
+adapter and creates no run.
+
+License: Apache-2.0. See `LICENSE` and `NOTICE`. Third-party dependencies retain
+their own licenses.

runkite_governance-0.8.0/README.md

@@ -0,0 +1,77 @@
+# Runkite governance helper
+
+A standard-library-only Python client for `POST /governance/decide` and `GET /governance/actions/{id}` on your self-hosted Runkite plane. It does not depend on the runner package or an agent framework.
+
+This helper has its own distribution, separate from `runkite-runner`. The
+published Runkite 0.7.0 release did not include it. Use the registry command
+only for a version whose publication has been verified:
+
+```sh
+python -m pip install runkite-governance
+```
+
+For source that has not been published, install from a checkout:
+
+```sh
+python -m pip install ./python/runkite_governance
+```
+
+The runtime requires Python 3.11 or newer. Installing a managed runner does not
+install this decision-only helper.
+
+```python
+from runkite_governance import GovernanceClient
+
+governance = GovernanceClient("http://localhost:2026", api_key="server-side-key", timeout_ms=10_000)
+decision = governance.decide(
+    agent_id="notes-app",
+    connector="workspace",
+    tool="createNote",
+    args={"title": "Release notes", "body": "A draft"},
+    run_id="stable-app-turn-and-tool-call-id",
+)
+```
+
+Your application executes after `allow`, refuses after `deny`, and persists the action ID and exact original arguments after `pending`. On a later application request, use `governance.action(action_id)` and execute only after `approved`. Rejected or consumed actions must not execute. Implement idempotency in the application's database: GET does not consume approval.
+
+`resolve(...)` performs a bounded wait and returns an allow/deny outcome. Its deadline covers the initial decision and every poll. `decide` and `action` accept `timeout_ms` and a `threading.Event` as `cancelled`. Cancellation stops the caller promptly. Blocking standard-library I/O unwinds separately with a socket timeout and response-chunk checks; a bounded shared worker pool prevents unlimited abandoned resolver/socket threads. Do not hold a serverless request open for long operator approval.
+
+Use a server-side key with `governance:decide`. Tenant identity comes from that key. The caller retains its model loop and tool execution. This path creates no Runkite thread or run and does not apply run kill switches, break-glass or spend caps. It is separate from the deliberately deferred full client SDK.
+
+## Optional Microsoft Agent Framework middleware
+
+For a verified registry release, install the optional middleware with:
+
+```sh
+python -m pip install 'runkite-governance[agent-framework]'
+```
+
+For unpublished source, install the extra from a checkout:
+
+```sh
+python -m pip install './python/runkite_governance[agent-framework]'
+```
+
+The extra pins the tested framework core; model-provider packages remain
+application choices.
+
+Import `GovernanceFunctionMiddleware`, `GovernedFunction`,
+`GovernanceBlockedError` and `PendingInvocation` from
+`runkite_governance.agent_framework`. Register exact local `FunctionTool` objects,
+server-owned policy identities and an application operation-ID callback. Install
+the guard last, after argument repair. It snapshots JSON arguments and Python
+defaults, decides once, and reaches native execution only after allow. Deny and
+pending stop the agent with a native `MiddlewareFailure`; an optional async
+`on_pending` callback persists the exact frozen proposal first.
+
+The app owns pending continuation and execution idempotency. Rich Python types,
+coercing validators and provider-executed tools are outside this adapter's scope.
+See the [framework example](https://github.com/getrunkite/runkite/tree/main/examples/governance_agent_framework/README.md)
+for a durable application transaction, offline streaming and non-streaming tests,
+and supported argument constraints. Execution retains native mutable containers;
+the app must not mutate invocation arguments after authorization. Importing the
+base client does not import the optional framework. This extra is not a runner
+adapter and creates no run.
+
+License: Apache-2.0. See `LICENSE` and `NOTICE`. Third-party dependencies retain
+their own licenses.

runkite_governance-0.8.0/__init__.py

@@ -0,0 +1,321 @@
+"""Calls POST /governance/decide, then polls GET /governance/actions/{id}
+when the effect is pending. The app executes the tool after allow.
+Runkite does not execute the tool and does not consume the approval
+on poll. This is not the deferred client SDK in docs/client-sdk.md.
+
+Stdlib only. Until the first registry publication is verified, install from
+the repository with ``python -m pip install ./python/runkite_governance``.
+The v0.8.0 source candidate prepares distribution; it does not publish it.
+The optional Microsoft middleware lives in ``runkite_governance.agent_framework``.
+The base client has the same decision boundary as typescript/runkite-governance.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import queue
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+DEFAULT_INTERVAL_MS = 500
+DEFAULT_TIMEOUT_MS = 60_000
+
+# Bound abandoned resolver/socket operations as well as the caller wait.
+_HTTP_WORKERS = threading.BoundedSemaphore(32)
+
+__all__ = ["DEFAULT_INTERVAL_MS", "DEFAULT_TIMEOUT_MS", "GovernanceClient", "GovernanceError"]
+
+
+class GovernanceError(Exception):
+    def __init__(self, message: str, status: int) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        # A decision must come from the configured plane. Do not forward its
+        # bearer credential or accept authorization from a redirected endpoint.
+        return None
+
+
+class GovernanceClient:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str | None = None,
+        interval_ms: int = DEFAULT_INTERVAL_MS,
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+    ) -> None:
+        self._base = base_url.rstrip("/")
+        self._api_key = api_key
+        self._interval_ms = interval_ms
+        self._timeout_ms = timeout_ms
+        self._opener = urllib.request.build_opener(_NoRedirect())
+
+    def decide(
+        self,
+        *,
+        agent_id: str,
+        connector: str,
+        tool: str,
+        args: dict[str, Any] | None = None,
+        run_id: str = "",
+        tenant_id: str | None = None,
+        cancelled: threading.Event | None = None,
+        timeout_ms: float | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "agent_id": agent_id,
+            "connector": connector,
+            "tool": tool,
+            "args": {} if args is None else args,
+            "run_id": run_id,
+        }
+        if tenant_id:
+            body["tenant_id"] = tenant_id
+        return _as_decision(
+            self._request("POST", "/governance/decide", body, cancelled=cancelled, timeout_ms=timeout_ms)
+        )
+
+    def action(
+        self, action_id: str, *, cancelled: threading.Event | None = None, timeout_ms: float | None = None
+    ) -> dict[str, Any]:
+        path = "/governance/actions/" + urllib.parse.quote(action_id, safe="")
+        return _as_action(self._request("GET", path, cancelled=cancelled, timeout_ms=timeout_ms))
+
+    def resolve(
+        self,
+        *,
+        agent_id: str,
+        connector: str,
+        tool: str,
+        args: dict[str, Any] | None = None,
+        run_id: str = "",
+        tenant_id: str | None = None,
+        interval_ms: int | None = None,
+        timeout_ms: int | None = None,
+        cancelled: threading.Event | None = None,
+    ) -> dict[str, Any]:
+        """Poll until the row settles. Set cancelled from another thread to stop, including during the wait."""
+        _raise_if_cancelled(cancelled)
+        limit = self._timeout_ms if timeout_ms is None else timeout_ms
+        if not math.isfinite(limit) or limit <= 0:
+            raise GovernanceError("governance poll timed out", 408)
+        deadline = time.monotonic() + limit / 1000
+        decision = self.decide(
+            agent_id=agent_id,
+            connector=connector,
+            tool=tool,
+            args=args,
+            run_id=run_id,
+            tenant_id=tenant_id,
+            cancelled=cancelled,
+            timeout_ms=_remaining(deadline, cancelled) * 1000,
+        )
+        if decision["effect"] != "pending":
+            return _compact(
+                {
+                    "effect": decision["effect"],
+                    "reason": decision.get("reason"),
+                    "reason_code": decision.get("reason_code"),
+                }
+            )
+        action_id = decision.get("action_id")
+        if not isinstance(action_id, str) or not action_id:
+            raise GovernanceError("pending decision missing action_id", 502)
+        every = self._interval_ms if interval_ms is None else interval_ms
+        if not math.isfinite(every) or every < 0:
+            raise GovernanceError("interval_ms must be non-negative", 400)
+        while True:
+            action = self.action(action_id, cancelled=cancelled, timeout_ms=_remaining(deadline, cancelled) * 1000)
+            if action["status"] != "pending":
+                return _outcome(action)
+            pause = min(every / 1000, _remaining(deadline, cancelled))
+            if cancelled is not None and cancelled.wait(pause):
+                raise GovernanceError("governance poll aborted", 499)
+            if cancelled is None:
+                time.sleep(pause)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+        *,
+        cancelled: threading.Event | None = None,
+        timeout_ms: float | None = None,
+    ) -> Any:
+        """Bound the caller's entire request, including headers and response body.
+
+        urllib is blocking. A daemon transport worker lets cancellation stop
+        the caller immediately. Its socket deadline and chunk checks bound
+        cleanup without replaying a decision that the plane may have received.
+        """
+        limit = self._timeout_ms if timeout_ms is None else timeout_ms
+        if not math.isfinite(limit) or limit <= 0:
+            raise GovernanceError("governance poll timed out", 408)
+        deadline = time.monotonic() + limit / 1000
+        _remaining(deadline, cancelled)
+        data = None
+        headers = {"Accept": "application/json"}
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["Content-Type"] = "application/json"
+        if self._api_key:
+            headers["Authorization"] = "Bearer " + self._api_key
+        req = urllib.request.Request(self._base + path, data=data, headers=headers, method=method)
+        results: queue.Queue = queue.Queue(maxsize=1)
+        workers = _HTTP_WORKERS
+
+        def read_body(resp) -> bytes:
+            chunks = []
+            while True:
+                _remaining(deadline, cancelled)
+                chunk = resp.read1(64 * 1024)
+                if not chunk:
+                    return b"".join(chunks)
+                chunks.append(chunk)
+
+        def transport() -> None:
+            try:
+                with self._opener.open(req, timeout=_remaining(deadline, cancelled)) as resp:
+                    if not 200 <= resp.status < 300:
+                        raise GovernanceError(f"governance request failed: HTTP {resp.status}", resp.status)
+                    raw = read_body(resp)
+                results.put((True, json.loads(raw) if raw else None))
+            except urllib.error.HTTPError as exc:
+                # Error bodies are subject to the same outer wall-clock limit.
+                try:
+                    message = _message(read_body(exc), exc.reason or "")
+                    results.put((False, GovernanceError(message, exc.code)))
+                except Exception as error:
+                    results.put((False, error))
+                finally:
+                    exc.close()
+            except json.JSONDecodeError:
+                results.put((True, None))
+            except Exception as exc:
+                results.put((False, exc))
+            finally:
+                workers.release()
+
+        while not workers.acquire(timeout=min(_remaining(deadline, cancelled), 0.025)):
+            pass
+        try:
+            _remaining(deadline, cancelled)
+            threading.Thread(target=transport, daemon=True, name="runkite-governance-http").start()
+        except BaseException:
+            workers.release()
+            raise
+        while True:
+            remaining = _remaining(deadline, cancelled)
+            try:
+                ok, value = results.get(timeout=min(remaining, 0.025))
+            except queue.Empty:
+                continue
+            _remaining(deadline, cancelled)
+            if ok:
+                return value
+            if (
+                isinstance(value, (TimeoutError,))
+                or isinstance(value, urllib.error.URLError)
+                and isinstance(value.reason, TimeoutError)
+            ):
+                raise GovernanceError("governance poll timed out", 408) from value
+            raise value
+
+
+def _as_decision(raw: Any) -> dict[str, Any]:
+    row = _object(raw)
+    effect = row.get("effect")
+    if effect not in ("allow", "deny", "pending"):
+        raise GovernanceError("governance decide response missing effect", 502)
+    return _compact(
+        {
+            "effect": effect,
+            "reason": _optional_str(row.get("reason")),
+            "reason_code": _optional_str(row.get("reason_code")),
+            "action_id": _optional_str(row.get("action_id")),
+        }
+    )
+
+
+def _as_action(raw: Any) -> dict[str, Any]:
+    row = _object(raw)
+    status = row.get("status")
+    if status not in ("pending", "approved", "rejected", "consumed"):
+        raise GovernanceError("governance action response missing status", 502)
+    action_id = _optional_str(row.get("action_id"))
+    if not action_id:
+        raise GovernanceError("governance action response missing action_id", 502)
+    return _compact(
+        {
+            "action_id": action_id,
+            "status": status,
+            "reason": _optional_str(row.get("reason")),
+            "reason_code": _optional_str(row.get("reason_code")),
+        }
+    )
+
+
+def _outcome(action: dict[str, Any]) -> dict[str, Any]:
+    return _compact(
+        {
+            "effect": "allow" if action["status"] == "approved" else "deny",
+            "reason": action.get("reason"),
+            "reason_code": action.get("reason_code"),
+            "action_id": action["action_id"],
+            "status": action["status"],
+        }
+    )
+
+
+def _object(raw: Any) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        raise GovernanceError("governance response was not JSON", 502)
+    return raw
+
+
+def _optional_str(value: Any) -> str | None:
+    if isinstance(value, str) and value != "":
+        return value
+    return None
+
+
+def _compact(row: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in row.items() if value is not None}
+
+
+def _raise_if_cancelled(cancelled: threading.Event | None) -> None:
+    if cancelled is not None and cancelled.is_set():
+        raise GovernanceError("governance poll aborted", 499)
+
+
+def _remaining(deadline: float, cancelled: threading.Event | None) -> float:
+    _raise_if_cancelled(cancelled)
+    remaining = deadline - time.monotonic()
+    if remaining <= 0:
+        raise GovernanceError("governance poll timed out", 408)
+    return remaining
+
+
+def _message(raw: bytes, fallback: str) -> str:
+    text = raw.decode("utf-8", errors="replace").strip()
+    if not text:
+        return fallback or "governance request failed"
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        return text
+    if isinstance(parsed, dict):
+        message = parsed.get("message")
+        if isinstance(message, str) and message:
+            return message
+    return text

runkite_governance-0.8.0/agent_framework.py

@@ -0,0 +1,319 @@
+"""Optional Microsoft Agent Framework function middleware.
+
+Install this last, after argument-repair middleware. Only JSON-native function
+arguments and JSON defaults stable under native validation are supported. The
+application retains its loop, execution idempotency and approval continuation.
+Importing runkite_governance itself does not import this optional dependency.
+
+Execution arguments remain ordinary native dict/list containers. The framework
+may reuse prepared argument aliases, so the application, middleware and tool
+must not mutate invocation data after authorization. This is a pre-execution
+gate, not an immutable execution environment. Pending records are immutable.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import math
+import threading
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any
+
+from agent_framework import FunctionInvocationContext, FunctionMiddleware, FunctionTool, MiddlewareFailure
+
+from . import GovernanceClient
+
+__all__ = [
+    "GovernedFunction",
+    "GovernanceFunctionMiddleware",
+    "GovernanceBlockedError",
+    "PendingInvocation",
+]
+
+
+@dataclass(frozen=True)
+class GovernedFunction:
+    function: FunctionTool
+    connector: str
+    tool: str | None = None
+
+
+@dataclass(frozen=True)
+class PendingInvocation:
+    action_id: str
+    agent_id: str
+    connector: str
+    tool: str
+    run_id: str
+    arguments: Mapping[str, Any]
+
+
+class GovernanceBlockedError(MiddlewareFailure):
+    """A denied or pending operation. Arguments are never attached to this error."""
+
+    def __init__(self, decision: Mapping[str, str]) -> None:
+        copied = _decision(dict(decision))
+        if copied["effect"] == "allow":
+            raise MiddlewareFailure("A blocked governance decision cannot allow execution")
+        super().__init__(
+            "Runkite tool execution is pending approval"
+            if copied["effect"] == "pending"
+            else "Runkite tool execution was denied"
+        )
+        self.decision = copied
+
+
+@dataclass(frozen=True)
+class _Binding:
+    function: FunctionTool
+    connector: str
+    tool: str
+    name: str
+    func: Callable[..., Any]
+    model: Any
+    signature: inspect.Signature
+    properties: tuple[str, ...]
+    schema: bytes
+
+
+def _identifier(value: Any) -> str:
+    if type(value) is not str or not value or value != value.strip():
+        raise ValueError("Governance identifiers must be canonical nonempty strings")
+    encoded = value.encode("utf-8", errors="strict")
+    if len(encoded) > 256:
+        raise ValueError("Governance identifiers must be at most 256 UTF-8 bytes")
+    return value
+
+
+def _snapshot(value: Any, *, root: bool = True) -> Any:
+    """Copy exact JSON types without custom serialization or coercion."""
+    ancestors: set[int] = set()
+
+    def copy(item: Any) -> Any:
+        kind = type(item)
+        if item is None or kind is bool:
+            return item
+        if kind is str:
+            item.encode("utf-8", errors="strict")
+            return item
+        if kind is int:
+            if abs(item) > 2**53 - 1:
+                raise ValueError("Tool integers must be in the safe JSON integer range")
+            return item
+        if kind is float:
+            if not math.isfinite(item) or item == 0 and math.copysign(1, item) < 0:
+                raise ValueError("Tool numbers must be lossless finite JSON values")
+            return item
+        if kind not in (dict, list) or id(item) in ancestors:
+            raise ValueError("Tool arguments must contain exact JSON types without cycles")
+        ancestors.add(id(item))
+        try:
+            if kind is list:
+                return [copy(part) for part in item]
+            result = {}
+            for key, part in item.items():
+                if type(key) is not str:
+                    raise ValueError("Tool argument keys must be strings")
+                key.encode("utf-8", errors="strict")
+                result[key] = copy(part)
+            return result
+        finally:
+            ancestors.remove(id(item))
+
+    if root and type(value) is not dict:
+        raise ValueError("Tool arguments must be a JSON object")
+    return copy(value)
+
+
+def _encoded(value: Any) -> bytes:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False).encode("utf-8")
+
+
+def _freeze(value: Any) -> Any:
+    if type(value) is dict:
+        return MappingProxyType({key: _freeze(part) for key, part in value.items()})
+    if type(value) is list:
+        return tuple(_freeze(part) for part in value)
+    return value
+
+
+def _decision(raw: Any) -> Mapping[str, str]:
+    if type(raw) is not dict:
+        raise ValueError("Governance decision must be an object")
+    copied = raw.copy()
+    effect = copied.get("effect")
+    if type(effect) is not str or effect not in ("allow", "deny", "pending"):
+        raise ValueError("Governance decision is missing a valid effect")
+    result = {"effect": effect}
+    for key in ("reason", "reason_code", "action_id"):
+        if key in copied:
+            if type(copied[key]) is not str:
+                raise ValueError("Governance decision metadata must be strings")
+            result[key] = copied[key]
+    if effect == "pending":
+        _identifier(result.get("action_id"))
+    return MappingProxyType(result)
+
+
+def _binding(config: GovernedFunction) -> _Binding:
+    function = config.function
+    if not isinstance(function, FunctionTool) or not (
+        inspect.isfunction(function.func) or inspect.ismethod(function.func)
+    ):
+        raise ValueError("Governed functions must wrap ordinary Python callables")
+    signature = inspect.signature(function.func)
+    if any(
+        parameter.kind
+        in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD, inspect.Parameter.POSITIONAL_ONLY)
+        for parameter in signature.parameters.values()
+    ):
+        raise ValueError("Variadic and positional-only governed functions are unsupported")
+    schema = _snapshot(function.parameters())
+    properties = schema.get("properties", {})
+    if type(properties) is not dict or any(name not in signature.parameters for name in properties):
+        raise ValueError("Governed function schemas must name declared Python parameters")
+    return _Binding(
+        function,
+        _identifier(config.connector),
+        _identifier(function.name if config.tool is None else config.tool),
+        _identifier(function.name),
+        function.func,
+        function.input_model,
+        signature,
+        tuple(properties),
+        _encoded(schema),
+    )
+
+
+def _projection(binding: _Binding, source: dict[str, Any]) -> dict[str, Any]:
+    if any(name not in binding.properties for name in source):
+        raise ValueError("Tool arguments must name declared tool parameters")
+    bound = binding.signature.bind_partial(**source)
+    bound.apply_defaults()
+    projected = _snapshot({name: bound.arguments[name] for name in binding.properties if name in bound.arguments})
+    if any(
+        name not in projected
+        for name in binding.properties
+        if binding.signature.parameters[name].default is inspect.Parameter.empty
+    ):
+        raise ValueError("Tool arguments are missing a required parameter")
+    if binding.model is not None:
+        validated = binding.model.model_validate(_snapshot(projected)).model_dump(mode="python", exclude_unset=True)
+        if _encoded(_snapshot(validated)) != _encoded(projected):
+            raise ValueError("Tool normalization must preserve the governed JSON arguments")
+    return projected
+
+
+def _unchanged(binding: _Binding, context: FunctionInvocationContext, original: Any, before: bytes) -> None:
+    if (
+        context.function is not binding.function
+        or binding.function.name != binding.name
+        or binding.function.func is not binding.func
+        or binding.function.input_model is not binding.model
+        or context.arguments is not original
+        or _encoded(_snapshot(original)) != before
+        or _encoded(_snapshot(context.arguments)) != before
+        or _encoded(_snapshot(binding.function.parameters())) != binding.schema
+    ):
+        raise ValueError("The governed function or its arguments changed during the decision")
+
+
+def _check_cancellation() -> None:
+    task = asyncio.current_task()
+    if task is not None and task.cancelling():
+        raise asyncio.CancelledError
+
+
+class GovernanceFunctionMiddleware(FunctionMiddleware):
+    """Decide once before native execution. Install last, after argument repair.
+
+    No polling, approval replay or model-loop ownership is provided. Pending
+    persistence and exactly-once application side effects remain app concerns.
+    """
+
+    def __init__(
+        self,
+        client: GovernanceClient,
+        *,
+        agent_id: str,
+        functions: Sequence[GovernedFunction],
+        operation_id: Callable[[FunctionInvocationContext], str],
+        on_pending: Callable[[PendingInvocation], Awaitable[None]] | None = None,
+    ) -> None:
+        try:
+            self._agent_id = _identifier(agent_id)
+            self._decide = client.decide
+            if not callable(self._decide) or not callable(operation_id):
+                raise ValueError("Governance decision and operation ID callbacks must be callable")
+            if on_pending is not None and not callable(on_pending):
+                raise ValueError("The pending callback must be callable")
+            self._bindings = tuple(_binding(config) for config in functions)
+            if len({id(binding.function) for binding in self._bindings}) != len(self._bindings):
+                raise ValueError("Governed function objects must be unique")
+            self._operation_id = operation_id
+            self._on_pending = on_pending
+            self._bridges = asyncio.Semaphore(32)
+        except Exception as exc:
+            raise MiddlewareFailure("Invalid Runkite governance middleware configuration") from exc
+
+    async def process(self, context: FunctionInvocationContext, call_next: Callable[[], Awaitable[None]]) -> None:
+        cancelled = threading.Event()
+        try:
+            _check_cancellation()
+            binding = next((item for item in self._bindings if context.function is item.function), None)
+            if binding is None:
+                raise ValueError("This function object is not registered for governance")
+            original = context.arguments
+            source = _snapshot(original)
+            before = _encoded(source)
+            projected = _projection(binding, source)
+            run_id = _identifier(self._operation_id(context))
+            _unchanged(binding, context, original, before)
+            request_args = _snapshot(projected)
+            async with self._bridges:
+                raw = await asyncio.to_thread(
+                    self._decide,
+                    agent_id=self._agent_id,
+                    connector=binding.connector,
+                    tool=binding.tool,
+                    args=request_args,
+                    run_id=run_id,
+                    cancelled=cancelled,
+                )
+            _check_cancellation()
+            decision = _decision(raw)
+            _unchanged(binding, context, original, before)
+            if _encoded(_snapshot(request_args)) != _encoded(projected):
+                raise ValueError("Governance request arguments changed during the decision")
+            if decision["effect"] == "pending" and self._on_pending is not None:
+                await self._on_pending(
+                    PendingInvocation(
+                        decision["action_id"],
+                        self._agent_id,
+                        binding.connector,
+                        binding.tool,
+                        run_id,
+                        _freeze(projected),
+                    )
+                )
+            if decision["effect"] != "allow":
+                raise GovernanceBlockedError(decision)
+            _check_cancellation()
+            # Preserve ordinary dict/list semantics, including nested Any values.
+            # Native prepared-argument caches may reuse checked original aliases.
+            context.arguments = _snapshot(projected)
+        except asyncio.CancelledError:
+            cancelled.set()
+            raise
+        except MiddlewareFailure:
+            raise
+        except Exception as exc:
+            raise MiddlewareFailure("Runkite governance check failed") from exc
+        finally:
+            cancelled.set()
+        # Native tool failures retain the framework's handling. Never retry them.
+        await call_next()

runkite_governance-0.8.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runkite-governance"
+version = "0.8.0"
+description = "Small decide and pending-action helper for app-owned agent loops."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+agent-framework = ["agent-framework-core==1.23.0"]
+
+[project.urls]
+Repository = "https://github.com/getrunkite/runkite"
+Documentation = "https://github.com/getrunkite/runkite/blob/main/docs/client-sdk.md"
+
+[tool.setuptools]
+packages = ["runkite_governance"]
+package-dir = { runkite_governance = "." }
+
+[tool.setuptools.package-data]
+runkite_governance = ["py.typed"]

runkite_governance-0.8.0/runkite_governance.egg-info/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: runkite-governance
+Version: 0.8.0
+Summary: Small decide and pending-action helper for app-owned agent loops.
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/getrunkite/runkite
+Project-URL: Documentation, https://github.com/getrunkite/runkite/blob/main/docs/client-sdk.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: agent-framework
+Requires-Dist: agent-framework-core==1.23.0; extra == "agent-framework"
+Dynamic: license-file
+
+# Runkite governance helper
+
+A standard-library-only Python client for `POST /governance/decide` and `GET /governance/actions/{id}` on your self-hosted Runkite plane. It does not depend on the runner package or an agent framework.
+
+This helper has its own distribution, separate from `runkite-runner`. The
+published Runkite 0.7.0 release did not include it. Use the registry command
+only for a version whose publication has been verified:
+
+```sh
+python -m pip install runkite-governance
+```
+
+For source that has not been published, install from a checkout:
+
+```sh
+python -m pip install ./python/runkite_governance
+```
+
+The runtime requires Python 3.11 or newer. Installing a managed runner does not
+install this decision-only helper.
+
+```python
+from runkite_governance import GovernanceClient
+
+governance = GovernanceClient("http://localhost:2026", api_key="server-side-key", timeout_ms=10_000)
+decision = governance.decide(
+    agent_id="notes-app",
+    connector="workspace",
+    tool="createNote",
+    args={"title": "Release notes", "body": "A draft"},
+    run_id="stable-app-turn-and-tool-call-id",
+)
+```
+
+Your application executes after `allow`, refuses after `deny`, and persists the action ID and exact original arguments after `pending`. On a later application request, use `governance.action(action_id)` and execute only after `approved`. Rejected or consumed actions must not execute. Implement idempotency in the application's database: GET does not consume approval.
+
+`resolve(...)` performs a bounded wait and returns an allow/deny outcome. Its deadline covers the initial decision and every poll. `decide` and `action` accept `timeout_ms` and a `threading.Event` as `cancelled`. Cancellation stops the caller promptly. Blocking standard-library I/O unwinds separately with a socket timeout and response-chunk checks; a bounded shared worker pool prevents unlimited abandoned resolver/socket threads. Do not hold a serverless request open for long operator approval.
+
+Use a server-side key with `governance:decide`. Tenant identity comes from that key. The caller retains its model loop and tool execution. This path creates no Runkite thread or run and does not apply run kill switches, break-glass or spend caps. It is separate from the deliberately deferred full client SDK.
+
+## Optional Microsoft Agent Framework middleware
+
+For a verified registry release, install the optional middleware with:
+
+```sh
+python -m pip install 'runkite-governance[agent-framework]'
+```
+
+For unpublished source, install the extra from a checkout:
+
+```sh
+python -m pip install './python/runkite_governance[agent-framework]'
+```
+
+The extra pins the tested framework core; model-provider packages remain
+application choices.
+
+Import `GovernanceFunctionMiddleware`, `GovernedFunction`,
+`GovernanceBlockedError` and `PendingInvocation` from
+`runkite_governance.agent_framework`. Register exact local `FunctionTool` objects,
+server-owned policy identities and an application operation-ID callback. Install
+the guard last, after argument repair. It snapshots JSON arguments and Python
+defaults, decides once, and reaches native execution only after allow. Deny and
+pending stop the agent with a native `MiddlewareFailure`; an optional async
+`on_pending` callback persists the exact frozen proposal first.
+
+The app owns pending continuation and execution idempotency. Rich Python types,
+coercing validators and provider-executed tools are outside this adapter's scope.
+See the [framework example](https://github.com/getrunkite/runkite/tree/main/examples/governance_agent_framework/README.md)
+for a durable application transaction, offline streaming and non-streaming tests,
+and supported argument constraints. Execution retains native mutable containers;
+the app must not mutate invocation arguments after authorization. Importing the
+base client does not import the optional framework. This extra is not a runner
+adapter and creates no run.
+
+License: Apache-2.0. See `LICENSE` and `NOTICE`. Third-party dependencies retain
+their own licenses.

runkite_governance-0.8.0/runkite_governance.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+NOTICE
+README.md
+__init__.py
+agent_framework.py
+py.typed
+pyproject.toml
+./__init__.py
+./agent_framework.py
+./py.typed
+runkite_governance.egg-info/PKG-INFO
+runkite_governance.egg-info/SOURCES.txt
+runkite_governance.egg-info/dependency_links.txt
+runkite_governance.egg-info/requires.txt
+runkite_governance.egg-info/top_level.txt

runkite_governance-0.8.0/runkite_governance.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

runkite_governance-0.8.0/runkite_governance.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[agent-framework]
+agent-framework-core==1.23.0

runkite_governance-0.8.0/runkite_governance.egg-info/top_level.txt

@@ -0,0 +1 @@
+runkite_governance

runkite_governance-0.8.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+