fsq-agent 0.1.0__py3-none-any.whl

fsq_agent/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from fsq_agent.agent import FsqAgent
+from fsq_agent.models import Task, TaskResult
+
+__all__ = ["FsqAgent", "Task", "TaskResult"]

fsq_agent/_capability_bootstrap.py

@@ -0,0 +1,72 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fsq_agent.core import (
+    CapabilityDefinitionFactory,
+    CapabilityRegistry,
+    CommonPlatformTools,
+)
+from fsq_agent.tools import DefaultAgentToolProvider, FileOps
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from fsq_agent.models import CapabilityDefinition, HarnessPlatform
+
+_CAPABILITY_DEFINITION_FACTORY = CapabilityDefinitionFactory()
+
+
+def common_capability_definitions() -> list[CapabilityDefinition]:
+    return CommonPlatformTools.capability_definitions()
+
+
+def build_capability_registry(*, platform: HarnessPlatform = "android", include_ai_assertion: bool = True) -> CapabilityRegistry:
+    return CapabilityRegistry.from_definitions(
+        [
+            *common_capability_definitions(),
+            *_platform_capability_definitions(platform, include_ai_assertion=include_ai_assertion),
+        ]
+    )
+
+
+def provider_required_capability_names(platform: HarnessPlatform) -> frozenset[str]:
+    full_snapshot = build_capability_registry(platform=platform, include_ai_assertion=True).snapshot()
+    provider_free_names = build_capability_registry(platform=platform, include_ai_assertion=False).snapshot().by_name()
+    return frozenset(capability.name for capability in full_snapshot.capabilities if capability.name not in provider_free_names)
+
+
+def steps_require_provider(
+    steps: list[Any],
+    registry_snapshot: Any,
+    provider_required_names: frozenset[str],
+) -> bool:
+    return any((capability := registry_snapshot.resolve(step.action_name)) is not None and capability.name in provider_required_names for step in steps)
+
+
+def _platform_capability_definitions(platform: HarnessPlatform, *, include_ai_assertion: bool) -> list[CapabilityDefinition]:
+    return _CAPABILITY_DEFINITION_FACTORY.platform_definitions(
+        platform=platform,
+        include_ai_assertion=include_ai_assertion,
+    )
+
+
+def build_agent_tool_provider(
+    *,
+    read_roots: list[Path] | None = None,
+    write_root: Path | None = None,
+    runtime_secret_settings: Any = None,
+    local_tool_output_settings: Any = None,
+    runs_dir: Path | None = None,
+    run_id: str = "",
+) -> DefaultAgentToolProvider:
+    return DefaultAgentToolProvider(
+        FileOps(read_roots=read_roots, write_root=write_root),
+        runtime_secret_settings=runtime_secret_settings,
+        local_tool_output_settings=local_tool_output_settings,
+        runs_dir=runs_dir,
+        run_id=run_id,
+    )

fsq_agent/_workspace_paths.py

@@ -0,0 +1,34 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from pathlib import Path
+
+from fsq_agent.models import ConfigurationError
+
+
+def resolve_discovered_case_path(path: str | Path, discovery_root: Path) -> Path:
+    root = discovery_root.expanduser().resolve()
+    resolved = Path(path).expanduser().resolve()
+    try:
+        resolved.relative_to(root)
+    except ValueError as exc:
+        raise ConfigurationError(
+            "Discovered case path must stay within the case directory.",
+            context={"path": str(path)},
+        ) from exc
+    return resolved
+
+
+def resolve_workspace_cases_path(path: str | Path, cases_dir: Path) -> Path:
+    root = cases_dir.expanduser().resolve()
+    requested = Path(path).expanduser()
+    candidate = requested if requested.is_absolute() else root / requested
+    resolved = candidate.resolve()
+    try:
+        resolved.relative_to(root)
+    except ValueError as exc:
+        raise ConfigurationError(
+            "Case path must stay within the workspace cases directory.",
+            context={"path": str(requested)},
+        ) from exc
+    return resolved

fsq_agent/adapters/SPEC.md

@@ -0,0 +1,48 @@
+# Module: adapters
+
+## Purpose
+
+Own external protocol adaptation for the public CLI, local Control Plane, and coding-agent runtimes. Adapters decode external inputs, invoke inward public contracts, and project safe output. They do not own Application validation, execution semantics, persistence formats, capability policy, or platform automation.
+
+## Dependencies
+
+Adapters may import public APIs from `application`, `execution`, `models`, `config`, `providers`, `agent`, `case_dsl`, `core`, and `report`. Inward modules must not import `adapters`. Adapter subpackages must not form cycles.
+
+## Public Interface
+
+- `adapters.cli` owns the `fsq` Click command tree and exports `main`.
+- `adapters.control_plane` owns `ControlPlaneServer`, `ControlPlaneServerOptions`, `run_control_plane`, and the documented HTTP/SSE/static API.
+- `adapters.coding_agent` owns the OpenAI Agents SDK implementation of public Agent runtime protocols. Its concrete runtime and SDK tool adapters are private; composition roots consume its public runtime factory.
+
+The installed scripts target canonical `fsq_agent.adapters.cli:main`. Existing `fsq_agent.cli` and `fsq_agent.control_plane` packages remain compatibility entries for documented public symbols only, and each compatibility symbol references the canonical adapter object. Old private transport submodule imports are unsupported and absent.
+
+## Internal Structure
+
+- `cli/`: CLI parsing, presentation, output modes, and exit mapping.
+- `control_plane/`: Control Plane HTTP/SSE/static transport, projections, and state.
+- `control_plane/static/`: Generated Control Plane package data.
+- `coding_agent/`: OpenAI Agents SDK runtime construction, SDK tool/schema conversion, stream-event/result adaptation, and public runtime factory.
+- Adapter-private `_*.py` files are not imported by inward modules.
+
+## Python Architecture
+
+- Architecture level: Level 3 Layered Application.
+- Public API: transport entry points plus the Coding Agent runtime factory consumed by composition roots.
+- Domain boundaries: external protocol decoding and presentation only.
+- Boundary models: Click values and HTTP/JSON/SSE dictionaries remain at adapter boundaries.
+- Dependency direction: adapters depend inward; Application and lower modules never import adapters.
+- Rationale: the entry surfaces coordinate frameworks, state, static delivery, and inward services without requiring another domain layer.
+
+## Error Handling
+
+Adapters map stable inward failures into documented exit codes or safe HTTP/SSE responses. Compatibility paths preserve exception identity, state identity, redaction, and output behavior.
+
+## Current Invariants
+
+- Public compatibility packages do not duplicate transport implementations, package data, or mutable state.
+- CLI and Control Plane business operations continue through Application.
+- Control Plane HTML, JavaScript, CSS, `entry-assets.json`, and all referenced generated assets are runtime package data included in both wheel and source distribution. Installed `fsq ui` resolves these resources from the installed package without a frontend source tree, Node.js, or runtime asset download.
+- CLI and Control Plane use the same public Execution services; adapter-private modules do not implement lifecycle or recording policy.
+- CLI and Control Plane composition roots inject the same Coding Agent runtime implementation into SDK-neutral Agent orchestration. Application and inward packages never import `adapters.coding_agent`.
+- CLI keeps this composition in a private helper rather than in command handlers. The helper may construct `FsqAgent` with the public Coding Agent runtime factory and return the SDK-neutral collaborator expected by Application, but it does not validate requests or own execution policy.
+- Module relocation does not change CLI, HTTP, SSE, frontend, workspace, Case, evidence, report, Provider, or Runs contracts.

fsq_agent/adapters/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+__all__: list[str] = []

fsq_agent/adapters/cli/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from fsq_agent.adapters.cli._main import main
+
+__all__ = ["main"]

fsq_agent/adapters/cli/_android_devices.py

@@ -0,0 +1,63 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fsq_agent.core import AndroidDeviceDiscovery
+from fsq_agent.models import AndroidDevice, ConfigurationError
+
+if TYPE_CHECKING:
+    from fsq_agent.config import Settings
+
+
+def select_android_serial(settings: Settings, requested_serial: str | None) -> str | None:
+    serial = requested_serial.strip() if requested_serial is not None else None
+    if requested_serial is not None and not serial:
+        raise ConfigurationError("--android-serial requires a non-empty serial.")
+    if settings.harness.platform != "android":
+        if serial is not None:
+            raise ConfigurationError("--android-serial is only supported for Android workspaces.")
+        return None
+
+    discovery = AndroidDeviceDiscovery().discover()
+    if discovery.error_code is not None:
+        raise ConfigurationError(
+            discovery.error_message or "ADB device discovery failed.",
+            context={"code": discovery.error_code},
+        )
+    devices = discovery.devices
+    if serial is not None:
+        matched = next((device for device in devices if device.serial == serial), None)
+        if matched is None:
+            raise ConfigurationError(
+                f"Android device {serial} was not discovered.",
+                context={"serial": serial, "devices": _device_states(devices)},
+            )
+        if matched.state != "device":
+            raise ConfigurationError(
+                f"Android device {serial} is not online (state: {matched.state}).",
+                context={"serial": serial, "state": matched.state},
+            )
+        settings.harness.android.serial = serial
+        return serial
+
+    online_devices = [device for device in devices if device.state == "device"]
+    if not online_devices:
+        raise ConfigurationError(
+            "No online Android devices were discovered.",
+            context={"devices": _device_states(devices)},
+        )
+    if len(online_devices) > 1:
+        raise ConfigurationError(
+            "Multiple online Android devices were discovered; select one with --android-serial.",
+            context={"serials": [device.serial for device in online_devices]},
+        )
+    selected_serial = online_devices[0].serial
+    settings.harness.android.serial = selected_serial
+    return selected_serial
+
+
+def _device_states(devices: list[AndroidDevice]) -> dict[str, str]:
+    return {device.serial: device.state for device in devices}

fsq_agent/adapters/cli/_capability_bootstrap.py

@@ -0,0 +1,18 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+from fsq_agent._capability_bootstrap import (
+    build_agent_tool_provider,
+    build_capability_registry,
+    common_capability_definitions,
+    provider_required_capability_names,
+    steps_require_provider,
+)
+
+__all__ = [
+    "build_agent_tool_provider",
+    "build_capability_registry",
+    "common_capability_definitions",
+    "provider_required_capability_names",
+    "steps_require_provider",
+]