flowdesk-omnigent-tool 0.1.0__tar.gz

flowdesk_omnigent_tool-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+.omc/
+.tools/
+.codegraph/
+.flowdesk/
+dist/
+packages/*/dist/
+*.tsbuildinfo

flowdesk_omnigent_tool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowDesk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

flowdesk_omnigent_tool-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: flowdesk-omnigent-tool
+Version: 0.1.0
+Summary: FlowDesk advisory selection tool for Omnigent.
+Project-URL: Homepage, https://github.com/astasdf1/flowdesk
+Project-URL: Repository, https://github.com/astasdf1/flowdesk
+Project-URL: Issues, https://github.com/astasdf1/flowdesk/issues
+Project-URL: Documentation, https://github.com/astasdf1/flowdesk/tree/main/docs/omnigent
+Author: FlowDesk
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-selection,flowdesk,mcp,model-selection,omnigent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# FlowDesk Omnigent Tool
+
+Experimental Omnigent integration package for FlowDesk advisory agent/model selection.
+
+This package implements the experimental Omnigent selection path from `docs/omnigent/OMNIGENT_DEVELOPMENT_DESIGN_OPTIONS.md`:
+
+- local Python function tool only;
+- advisory selection only;
+- no Omnigent dispatch calls;
+- no provider fallback/retry authority;
+- no credential/token file reads;
+- optional local debug JSONL only when explicitly requested by the caller.
+- post-run trace verification from Omnigent history/tool-call events;
+- optional fixture-level function policy guard for selector-provenance and binding consistency.
+
+Install into an Omnigent venv from PyPI:
+
+```bash
+uv pip install --python /path/to/omnigent/.venv/bin/python flowdesk-omnigent-tool
+```
+
+Development install from a FlowDesk checkout:
+
+```bash
+uv pip install --python /path/to/omnigent/.venv/bin/python -e packages/omnigent-tool
+```
+
+Release preflight from the FlowDesk repository:
+
+```bash
+npm run release:omnigent-tool
+```
+
+Publishing is explicit:
+
+```bash
+npm run release:omnigent-tool -- --test-pypi
+npm run release:omnigent-tool -- --publish
+```
+
+GitHub Actions Trusted Publishing is available through `.github/workflows/publish-omnigent-tool.yml`. Configure PyPI with workflow filename `publish-omnigent-tool.yml` and environment `pypi`; configure TestPyPI with environment `testpypi` if you want a TestPyPI dry run.
+
+Function path for Omnigent config:
+
+```text
+flowdesk_omnigent.selection.select_agent_model
+```
+
+The selector accepts optional `provider_usage` or `provider_health` snapshots. Exhausted, critical, stale, blocked, unavailable, non-dispatchable, or 0%-remaining provider rows are skipped when another allowed provider can satisfy the request. If every allowed provider is unavailable, the selector returns `selection_status=blocked` with `provider_usage_unavailable`.
+
+Trace verifier import path:
+
+```text
+flowdesk_omnigent.trace_verifier.verify_selection_dispatch_trace
+```
+
+Trace adapter import path:
+
+```text
+flowdesk_omnigent.trace_adapter.normalize_omnigent_trace_events
+```
+
+Minimal adapter/verifier flow:
+
+```python
+from flowdesk_omnigent.trace_adapter import normalize_omnigent_trace_events
+from flowdesk_omnigent.trace_verifier import verify_selection_dispatch_trace
+
+normalized = normalize_omnigent_trace_events(history_items)
+verification = verify_selection_dispatch_trace(normalized["events"])
+```
+
+The adapter returns redaction-safe normalized events only. It does not preserve raw prompts, full tool arguments, full tool outputs, provider payloads, or credentials.
+
+Optional MCP stdio server:
+
+```bash
+flowdesk-omnigent-mcp
+```
+
+Omnigent MCP config after PyPI install:
+
+```yaml
+tools:
+  flowdesk:
+    type: mcp
+    command: flowdesk-omnigent-mcp
+```
+
+The MCP server exposes only `flowdesk_select_agent_model`. It is selection-only and does not expose Omnigent dispatch, fallback, retry, write/apply, or provider-switch tools.
+
+Optional Omnigent function policy guard:
+
+```yaml
+guardrails:
+  policies:
+    flowdesk_selection_dispatch_guard:
+      type: function
+      on: [tool_call, tool_result]
+      function: flowdesk_omnigent.policies.omnigent_selection_dispatch_guard
+```
+
+The guard records FlowDesk selector calls in Omnigent policy state and, when Omnigent emits a selector `tool_result`, records exact selector output provenance. Guarded `sys_session_send` calls must match a recorded task/agent/harness/model binding and must not use expired selection records. This remains fixture-level policy enforcement only; it does not grant provider fallback, retry, write/apply, hard-chat/noReply, credential, or upstream Omnigent core-hook authority.

flowdesk_omnigent_tool-0.1.0/README.md

@@ -0,0 +1,103 @@
+# FlowDesk Omnigent Tool
+
+Experimental Omnigent integration package for FlowDesk advisory agent/model selection.
+
+This package implements the experimental Omnigent selection path from `docs/omnigent/OMNIGENT_DEVELOPMENT_DESIGN_OPTIONS.md`:
+
+- local Python function tool only;
+- advisory selection only;
+- no Omnigent dispatch calls;
+- no provider fallback/retry authority;
+- no credential/token file reads;
+- optional local debug JSONL only when explicitly requested by the caller.
+- post-run trace verification from Omnigent history/tool-call events;
+- optional fixture-level function policy guard for selector-provenance and binding consistency.
+
+Install into an Omnigent venv from PyPI:
+
+```bash
+uv pip install --python /path/to/omnigent/.venv/bin/python flowdesk-omnigent-tool
+```
+
+Development install from a FlowDesk checkout:
+
+```bash
+uv pip install --python /path/to/omnigent/.venv/bin/python -e packages/omnigent-tool
+```
+
+Release preflight from the FlowDesk repository:
+
+```bash
+npm run release:omnigent-tool
+```
+
+Publishing is explicit:
+
+```bash
+npm run release:omnigent-tool -- --test-pypi
+npm run release:omnigent-tool -- --publish
+```
+
+GitHub Actions Trusted Publishing is available through `.github/workflows/publish-omnigent-tool.yml`. Configure PyPI with workflow filename `publish-omnigent-tool.yml` and environment `pypi`; configure TestPyPI with environment `testpypi` if you want a TestPyPI dry run.
+
+Function path for Omnigent config:
+
+```text
+flowdesk_omnigent.selection.select_agent_model
+```
+
+The selector accepts optional `provider_usage` or `provider_health` snapshots. Exhausted, critical, stale, blocked, unavailable, non-dispatchable, or 0%-remaining provider rows are skipped when another allowed provider can satisfy the request. If every allowed provider is unavailable, the selector returns `selection_status=blocked` with `provider_usage_unavailable`.
+
+Trace verifier import path:
+
+```text
+flowdesk_omnigent.trace_verifier.verify_selection_dispatch_trace
+```
+
+Trace adapter import path:
+
+```text
+flowdesk_omnigent.trace_adapter.normalize_omnigent_trace_events
+```
+
+Minimal adapter/verifier flow:
+
+```python
+from flowdesk_omnigent.trace_adapter import normalize_omnigent_trace_events
+from flowdesk_omnigent.trace_verifier import verify_selection_dispatch_trace
+
+normalized = normalize_omnigent_trace_events(history_items)
+verification = verify_selection_dispatch_trace(normalized["events"])
+```
+
+The adapter returns redaction-safe normalized events only. It does not preserve raw prompts, full tool arguments, full tool outputs, provider payloads, or credentials.
+
+Optional MCP stdio server:
+
+```bash
+flowdesk-omnigent-mcp
+```
+
+Omnigent MCP config after PyPI install:
+
+```yaml
+tools:
+  flowdesk:
+    type: mcp
+    command: flowdesk-omnigent-mcp
+```
+
+The MCP server exposes only `flowdesk_select_agent_model`. It is selection-only and does not expose Omnigent dispatch, fallback, retry, write/apply, or provider-switch tools.
+
+Optional Omnigent function policy guard:
+
+```yaml
+guardrails:
+  policies:
+    flowdesk_selection_dispatch_guard:
+      type: function
+      on: [tool_call, tool_result]
+      function: flowdesk_omnigent.policies.omnigent_selection_dispatch_guard
+```
+
+The guard records FlowDesk selector calls in Omnigent policy state and, when Omnigent emits a selector `tool_result`, records exact selector output provenance. Guarded `sys_session_send` calls must match a recorded task/agent/harness/model binding and must not use expired selection records. This remains fixture-level policy enforcement only; it does not grant provider fallback, retry, write/apply, hard-chat/noReply, credential, or upstream Omnigent core-hook authority.

flowdesk_omnigent_tool-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flowdesk-omnigent-tool"
+version = "0.1.0"
+description = "FlowDesk advisory selection tool for Omnigent."
+requires-python = ">=3.12"
+readme = "README.md"
+license = "MIT"
+authors = [
+  { name = "FlowDesk" }
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed"
+]
+keywords = ["flowdesk", "omnigent", "mcp", "agent-selection", "model-selection"]
+
+[project.urls]
+Homepage = "https://github.com/astasdf1/flowdesk"
+Repository = "https://github.com/astasdf1/flowdesk"
+Issues = "https://github.com/astasdf1/flowdesk/issues"
+Documentation = "https://github.com/astasdf1/flowdesk/tree/main/docs/omnigent"
+
+[project.scripts]
+flowdesk-omnigent-mcp = "flowdesk_omnigent.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flowdesk_omnigent"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "README.md",
+  "LICENSE",
+  "src/flowdesk_omnigent/**/*.py",
+  "src/flowdesk_omnigent/py.typed",
+  "tests/**/*.py",
+  "tests/fixtures/**/*.json",
+  "pyproject.toml"
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

flowdesk_omnigent_tool-0.1.0/src/flowdesk_omnigent/__init__.py

@@ -0,0 +1,14 @@
+"""FlowDesk Omnigent integration package."""
+
+from .selection import flowdesk_select_agent_model, select_agent_model
+from .policies import omnigent_selection_dispatch_guard
+from .trace_adapter import normalize_omnigent_trace_events
+from .trace_verifier import verify_selection_dispatch_trace
+
+__all__ = [
+    "flowdesk_select_agent_model",
+    "normalize_omnigent_trace_events",
+    "omnigent_selection_dispatch_guard",
+    "select_agent_model",
+    "verify_selection_dispatch_trace",
+]

flowdesk_omnigent_tool-0.1.0/src/flowdesk_omnigent/mcp_server.py

@@ -0,0 +1,100 @@
+"""Minimal stdio MCP server for FlowDesk Omnigent advisory selection."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Mapping
+
+from .selection import select_agent_model
+
+MCP_PROTOCOL_VERSION = "2024-11-05"
+MCP_TOOL_NAME = "flowdesk_select_agent_model"
+
+
+def handle_mcp_request(request: Mapping[str, Any]) -> dict[str, Any] | None:
+    """Handle one JSON-RPC request without granting runtime authority."""
+
+    method = request.get("method")
+    request_id = request.get("id")
+    if method == "notifications/initialized":
+        return None
+    if method == "initialize":
+        return _result(
+            request_id,
+            {
+                "protocolVersion": MCP_PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "flowdesk-omnigent-mcp", "version": "0.1.0"},
+            },
+        )
+    if method == "tools/list":
+        return _result(request_id, {"tools": [_tool_definition()]})
+    if method == "tools/call":
+        params = request.get("params")
+        if not isinstance(params, Mapping) or params.get("name") != MCP_TOOL_NAME:
+            return _error(request_id, -32602, "unsupported tool")
+        arguments = params.get("arguments")
+        if not isinstance(arguments, Mapping):
+            arguments = {}
+        selection = select_agent_model(arguments, write_evidence=False)
+        return _result(
+            request_id,
+            {
+                "content": [{"type": "text", "text": json.dumps(selection, ensure_ascii=True, sort_keys=True, separators=(",", ":"))}],
+                "isError": False,
+            },
+        )
+    return _error(request_id, -32601, "method not found")
+
+
+def main() -> None:
+    """Run a line-delimited JSON-RPC stdio loop."""
+
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError:
+            response = _error(None, -32700, "parse error")
+        else:
+            response = handle_mcp_request(request) if isinstance(request, Mapping) else _error(None, -32600, "invalid request")
+        if response is not None:
+            sys.stdout.write(json.dumps(response, ensure_ascii=True, sort_keys=True, separators=(",", ":")))
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+
+
+def _tool_definition() -> dict[str, Any]:
+    return {
+        "name": MCP_TOOL_NAME,
+        "description": "Return advisory-only FlowDesk agent/model selection for an Omnigent subtask.",
+        "inputSchema": {
+            "type": "object",
+            "additionalProperties": False,
+            "properties": {
+                "task_id": {"type": "string"},
+                "task_role": {
+                    "type": "string",
+                    "enum": ["policy_security", "architecture", "implementation", "verification", "research", "general", "gemini_experimental"],
+                },
+                "allowed_provider_families": {"type": "array", "items": {"type": "string", "enum": ["claude", "openai", "gemini"]}},
+                "preferred_provider_family": {"type": "string", "enum": ["claude", "openai", "gemini"]},
+                "requires_headless": {"type": "boolean"},
+            },
+            "required": ["task_id", "task_role"],
+        },
+    }
+
+
+def _result(request_id: Any, result: Mapping[str, Any]) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "result": dict(result)}
+
+
+def _error(request_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
+
+
+if __name__ == "__main__":
+    main()

flowdesk_omnigent_tool-0.1.0/src/flowdesk_omnigent/policies.py

@@ -0,0 +1,251 @@
+"""Omnigent policy helpers for FlowDesk selection consistency."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+from typing import Any, Callable, Mapping, Sequence
+
+from .selection import select_agent_model
+
+DEFAULT_AGENT_MODEL_BINDINGS: Mapping[str, str | None] = {
+    "policy-security-agent": "claude-opus-4-8",
+    "architecture-agent": None,
+    "implementation-agent": None,
+    "verification-agent": None,
+}
+DEFAULT_AGENT_HARNESS_BINDINGS: Mapping[str, str] = {
+    "policy-security-agent": "claude-sdk",
+    "architecture-agent": "codex",
+    "implementation-agent": "codex",
+    "verification-agent": "codex",
+}
+FLOWDESK_SELECTION_STATE_KEY = "flowdesk_selection_events"
+FLOWDESK_SELECTOR_TARGETS = frozenset({"flowdesk_select_agent_model", "select_agent_model", "mcp__flowdesk__flowdesk_select_agent_model"})
+
+
+def make_omnigent_selection_dispatch_guard(
+    *,
+    guarded_agents: Sequence[str] | None = None,
+    allow_unknown_agents: bool = True,
+    require_selection_provenance: bool = True,
+) -> Callable[[Mapping[str, Any]], dict[str, Any] | None]:
+    """Create a tool_call policy that denies selection-incompatible dispatch.
+
+    This is a mechanical pre-dispatch guard for the FlowDesk Omnigent fixture.
+    It does not prove that a selector tool was called earlier; it only ensures
+    that guarded ``sys_session_send`` calls match FlowDesk's current static
+    advisory binding contract.
+    """
+
+    guarded = set(guarded_agents or DEFAULT_AGENT_MODEL_BINDINGS.keys())
+
+    def evaluate(event: Mapping[str, Any]) -> dict[str, Any] | None:
+        event_type = event.get("type")
+        if event_type not in {"tool_call", "tool_result"}:
+            return None
+        target = event.get("target")
+        if event_type == "tool_result" and isinstance(target, str) and _is_flowdesk_selector_target(target):
+            return _record_selection_output_event(event)
+        if event_type == "tool_result":
+            return None
+        if event_type == "tool_call" and isinstance(target, str) and _is_flowdesk_selector_target(target):
+            return _record_recomputed_selection_event(event)
+        if target != "sys_session_send":
+            return None
+        data = event.get("data")
+        if not isinstance(data, Mapping):
+            return {"result": "DENY", "reason": "FlowDesk dispatch guard: malformed tool_call data."}
+        arguments = data.get("arguments")
+        if not isinstance(arguments, Mapping):
+            return {"result": "DENY", "reason": "FlowDesk dispatch guard: malformed sys_session_send arguments."}
+        agent = arguments.get("agent")
+        if not isinstance(agent, str) or not agent:
+            return None
+        if agent not in guarded:
+            if allow_unknown_agents:
+                return None
+            return {"result": "DENY", "reason": "FlowDesk dispatch guard: unregistered sub-agent."}
+        if require_selection_provenance:
+            matching_selection = _matching_recorded_selection(event, arguments)
+            if matching_selection is None:
+                return {"result": "DENY", "reason": "FlowDesk dispatch guard: no matching FlowDesk selection was recorded for this dispatch."}
+            if matching_selection.get("selection_status") != "selected":
+                return {"result": "DENY", "reason": "FlowDesk dispatch guard: recorded selection was not dispatchable."}
+            if _selection_is_expired(matching_selection):
+                return {"result": "DENY", "reason": "FlowDesk dispatch guard: recorded selection has expired."}
+            expected_model = matching_selection.get("model")
+            expected_harness = matching_selection.get("harness")
+        else:
+            expected_model = DEFAULT_AGENT_MODEL_BINDINGS.get(agent)
+            expected_harness = DEFAULT_AGENT_HARNESS_BINDINGS.get(agent)
+        actual_harness = _dispatch_harness(arguments)
+        effective_harness = actual_harness or DEFAULT_AGENT_HARNESS_BINDINGS.get(agent)
+        if isinstance(expected_harness, str) and effective_harness != expected_harness:
+            return {"result": "DENY", "reason": "FlowDesk dispatch guard: harness does not match selected binding."}
+        actual_model = _dispatch_model(arguments)
+        if expected_model is None and actual_model is not None:
+            return {"result": "DENY", "reason": "FlowDesk dispatch guard: this sub-agent must use harness default model."}
+        if expected_model is not None and actual_model != expected_model:
+            return {"result": "DENY", "reason": "FlowDesk dispatch guard: model override does not match selected binding."}
+        return {"result": "ALLOW"}
+
+    return evaluate
+
+
+def omnigent_selection_dispatch_guard(event: Mapping[str, Any]) -> dict[str, Any] | None:
+    """Direct Omnigent policy callable for config.yaml function policies."""
+
+    return make_omnigent_selection_dispatch_guard()(event)
+
+
+def _dispatch_model(arguments: Mapping[str, Any]) -> str | None:
+    args = arguments.get("args")
+    if isinstance(args, Mapping):
+        model = args.get("model")
+        return model if isinstance(model, str) and model else None
+    return None
+
+
+def _dispatch_harness(arguments: Mapping[str, Any]) -> str | None:
+    harness = arguments.get("harness")
+    return harness if isinstance(harness, str) and harness else None
+
+
+def _record_recomputed_selection_event(event: Mapping[str, Any]) -> dict[str, Any] | None:
+    data = event.get("data")
+    if not isinstance(data, Mapping):
+        return None
+    arguments = data.get("arguments")
+    if not isinstance(arguments, Mapping):
+        arguments = {}
+    selection = select_agent_model(arguments, write_evidence=False)
+    record = _record_from_selection(selection, provenance_source="selector_args_recomputed")
+    if record is None:
+        return None
+    return {"result": "ALLOW", "state_updates": [{"key": FLOWDESK_SELECTION_STATE_KEY, "action": "append", "value": record}]}
+
+
+def _record_selection_output_event(event: Mapping[str, Any]) -> dict[str, Any] | None:
+    selection = _selection_from_tool_result(event)
+    if selection is None:
+        return {"result": "ALLOW"}
+    record = _record_from_selection(selection, provenance_source="selector_output")
+    if record is None:
+        return {"result": "ALLOW"}
+    return {"result": "ALLOW", "state_updates": [{"key": FLOWDESK_SELECTION_STATE_KEY, "action": "append", "value": record}]}
+
+
+def _selection_from_tool_result(event: Mapping[str, Any]) -> Mapping[str, Any] | None:
+    data = event.get("data")
+    payload: Any = None
+    if isinstance(data, Mapping):
+        payload = data.get("output") or data.get("result") or data.get("content")
+    elif isinstance(data, str):
+        payload = data
+    selection = _coerce_selection_payload(payload)
+    if selection is not None:
+        return selection
+    if isinstance(data, Mapping):
+        content = data.get("content")
+        if isinstance(content, list):
+            for item in content:
+                if isinstance(item, Mapping) and item.get("type") == "text":
+                    selection = _coerce_selection_payload(item.get("text"))
+                    if selection is not None:
+                        return selection
+    return None
+
+
+def _coerce_selection_payload(value: Any) -> Mapping[str, Any] | None:
+    if isinstance(value, Mapping):
+        payload = dict(value)
+    elif isinstance(value, str) and value.strip():
+        try:
+            parsed = json.loads(value)
+        except json.JSONDecodeError:
+            return None
+        if not isinstance(parsed, Mapping):
+            return None
+        payload = dict(parsed)
+    else:
+        return None
+    if isinstance(payload.get("result"), Mapping):
+        payload = dict(payload["result"])
+    if payload.get("schema_version") != "flowdesk.omnigent_selection.v1":
+        return None
+    if payload.get("authority") != "advisory_selection_only":
+        return None
+    return payload
+
+
+def _record_from_selection(selection: Mapping[str, Any], *, provenance_source: str) -> dict[str, Any] | None:
+    task_id = selection.get("task_id")
+    status = selection.get("selection_status")
+    if not isinstance(task_id, str) or not task_id or status not in {"selected", "blocked", "non_dispatchable"}:
+        return None
+    return {
+        "task_id": task_id,
+        "selection_status": status,
+        "agent": selection.get("agent"),
+        "harness": selection.get("harness"),
+        "model": selection.get("model"),
+        "selection_id": selection.get("selection_id"),
+        "expires_at": selection.get("expires_at"),
+        "provenance_source": provenance_source,
+    }
+
+
+def _matching_recorded_selection(event: Mapping[str, Any], arguments: Mapping[str, Any]) -> Mapping[str, Any] | None:
+    state = event.get("session_state")
+    if not isinstance(state, Mapping):
+        return None
+    records = state.get(FLOWDESK_SELECTION_STATE_KEY)
+    if not isinstance(records, list):
+        return None
+    task_id = _dispatch_task_id(arguments)
+    agent = arguments.get("agent")
+    model = _dispatch_model(arguments)
+    for raw in reversed(records):
+        if not isinstance(raw, Mapping):
+            continue
+        if task_id is not None and raw.get("task_id") != task_id:
+            continue
+        if raw.get("agent") != agent:
+            continue
+        if _selection_is_expired(raw):
+            continue
+        expected_model = raw.get("model")
+        if expected_model is None and model is not None:
+            continue
+        if expected_model is not None and expected_model != model:
+            continue
+        return raw
+    return None
+
+
+def _dispatch_task_id(arguments: Mapping[str, Any]) -> str | None:
+    args = arguments.get("args")
+    if isinstance(args, Mapping):
+        task_id = args.get("task_id")
+        if isinstance(task_id, str) and task_id:
+            return task_id
+    title = arguments.get("title")
+    return title if isinstance(title, str) and title else None
+
+
+def _is_flowdesk_selector_target(target: str) -> bool:
+    return target in FLOWDESK_SELECTOR_TARGETS or target.endswith("__flowdesk_select_agent_model")
+
+
+def _selection_is_expired(selection: Mapping[str, Any]) -> bool:
+    expires_at = selection.get("expires_at")
+    if not isinstance(expires_at, str) or not expires_at:
+        return False
+    try:
+        parsed = datetime.fromisoformat(expires_at.replace("Z", "+00:00"))
+    except ValueError:
+        return True
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed <= datetime.now(timezone.utc)