agentic-project-kit 1.0.1__py3-none-any.whl

agentic_project_kit/gui_action_execution.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+
+BLOCKED_SAFETY_CLASSES = frozenset({
+    "destructive",
+    "local-only",
+    "mutation",
+    "release",
+    "remote",
+    "remote-mutation",
+})
+
+
+@dataclass(frozen=True)
+class GuiActionExecutionResult:
+    action_name: str
+    safety_class: str
+    allowed: bool
+    executed: bool
+    returncode: int
+    message: str
+    output: str = ""
+
+
+def _field(action: object, *names: str, default: object = "") -> object:
+    for name in names:
+        if hasattr(action, name):
+            return getattr(action, name)
+    return default
+
+
+def _value(value: object) -> str:
+    if value is None:
+        return ""
+    return str(value)
+
+
+def normalize_safety_class(value: object) -> str:
+    return _value(value).strip().lower().replace("_", "-").rsplit(".", 1)[-1]
+
+
+def action_identity(action: object) -> str:
+    return _value(_field(action, "name", "action_id", "id"))
+
+
+def action_safety_class(action: object) -> str:
+    return normalize_safety_class(_field(action, "safety_class", "safety", default="unknown"))
+
+
+def is_bounded_read_only_action(action: object) -> bool:
+    return action_safety_class(action) == "read-only"
+
+
+def find_action(actions: Iterable[object], action_name: str) -> object | None:
+    for action in actions:
+        if action_identity(action) == action_name:
+            return action
+    return None
+
+
+def run_bounded_read_only_action(
+    actions: Iterable[object],
+    action_name: str,
+    *,
+    executor: Callable[[object], tuple[int, str]] | None = None,
+) -> GuiActionExecutionResult:
+    action = find_action(actions, action_name)
+    if action is None:
+        return GuiActionExecutionResult(action_name, "unknown", False, False, 2, "Action not found.")
+
+    name = action_identity(action)
+    safety = action_safety_class(action)
+    if safety in BLOCKED_SAFETY_CLASSES or safety != "read-only":
+        return GuiActionExecutionResult(
+            name,
+            safety,
+            False,
+            False,
+            2,
+            "Action blocked: GUI MVP execution is limited to read-only actions.",
+        )
+
+    if executor is None:
+        return GuiActionExecutionResult(
+            name,
+            safety,
+            True,
+            False,
+            0,
+            "Action allowed but not executed: no executor was provided.",
+        )
+
+    returncode, output = executor(action)
+    return GuiActionExecutionResult(
+        name,
+        safety,
+        True,
+        True,
+        int(returncode),
+        "Action executed through bounded read-only executor.",
+        output,
+    )

agentic_project_kit/gui_action_renderer.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from agentic_project_kit.gui_viewmodel import (
+    BasicCockpitViewModel,
+    GuiActionViewModel,
+    GuiControllerViewModel,
+)
+
+
+def render_action_row(action: GuiActionViewModel, index: int) -> str:
+    state = "enabled" if action.enabled else "disabled"
+    confirmation = "confirm" if action.requires_confirmation else "no-confirm"
+    description = action.description.strip() or "no description"
+    return (
+        f"{index:02d}. {action.name} "
+        f"[{action.safety_class}; {state}; {confirmation}] - {description}"
+    )
+
+
+def render_action_rows(actions: Iterable[GuiActionViewModel]) -> tuple[str, ...]:
+    return tuple(render_action_row(action, index) for index, action in enumerate(actions, start=1))
+
+
+def render_controller_view_model(view_model: GuiControllerViewModel) -> str:
+    lines = [
+        view_model.title,
+        f"status={view_model.status}",
+        f"action_count={view_model.action_count}",
+        f"destructive_actions_enabled={str(view_model.destructive_actions_enabled).lower()}",
+        "actions:",
+    ]
+    rows = render_action_rows(view_model.actions)
+    if rows:
+        lines.extend(rows)
+    else:
+        lines.append("none")
+    return "\n".join(lines)
+
+
+def render_basic_cockpit_view_model(view_model: BasicCockpitViewModel) -> str:
+    lines = [
+        view_model.title,
+        f"traffic_light_state={view_model.traffic_light_state}",
+        f"traffic_light_color={view_model.traffic_light_color}",
+        f"communication_mode={view_model.communication_mode}",
+        f"mutation_allowed={str(view_model.mutation_allowed).lower()}",
+        f"state_source={view_model.state_source}",
+        f"reason={view_model.reason}",
+        f"next_safe_action={view_model.next_safe_action}",
+        f"recommended_action={view_model.recommended_action.label}",
+        f"recommended_action_kind={view_model.recommended_action.kind}",
+        f"evidence={view_model.evidence}",
+        f"last_result={view_model.last_result}",
+        "communication_modes:",
+    ]
+    for mode in view_model.communication_modes:
+        selected = "selected" if mode.selected else "available"
+        default = "default" if mode.is_default else "non-default"
+        lines.append(f"- {mode.mode_id} [{mode.role}; {selected}; {default}] {mode.safety_note}")
+    lines.append("buttons:")
+    for button in view_model.buttons:
+        state = "enabled" if button.enabled else "disabled"
+        command = " ".join(button.wrapper_command) if button.wrapper_command else "<no-wrapper>"
+        reason = button.disabled_reason or button.why
+        lines.append(
+            f"- {button.command_id} [{button.safety_class}; {state}] "
+            f"label={button.label}; tooltip={button.tooltip}; wrapper={command}; "
+            f"source={button.source}; why={reason}"
+        )
+    if view_model.button_groups:
+        lines.append("button_groups:")
+        for group in view_model.button_groups:
+            lines.append(
+                f"- {group.group_id}: {group.label}; buttons={','.join(group.button_ids)}"
+            )
+    if view_model.recovery_hint:
+        lines.append(f"recovery_hint={view_model.recovery_hint}")
+    lines.append(f"explanation={view_model.explanation}")
+    return "\n".join(lines)

agentic_project_kit/gui_action_run_intent.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class GuiActionLike(Protocol):
+    name: str
+    safety_class: object
+    description: str
+
+
+@dataclass(frozen=True)
+class GuiActionRunIntent:
+    action_name: str
+    known: bool
+    safety_class: str
+    enabled: bool
+    requires_confirmation: bool
+    confirmation_token: str
+    blocked_reason: str
+    output_target: str
+    terminal_log: str
+    would_execute: bool = False
+
+
+def _safety_name(value: object) -> str:
+    name = getattr(value, "value", value)
+    return str(name).replace("-", "_")
+
+
+def _confirmation_token(action_name: str, safety_class: str) -> str:
+    if safety_class in {"remote_mutation", "destructive"}:
+        return "confirm-" + action_name
+    return ""
+
+
+def build_gui_action_run_intent(
+    actions: list[GuiActionLike],
+    action_name: str,
+    *, confirmation: str = "",
+    allow_remote_mutation: bool = False,
+    allow_destructive: bool = False,
+    terminal_log: str = "NONE",
+) -> GuiActionRunIntent:
+    action_by_name = {action.name: action for action in actions}
+    action = action_by_name.get(action_name)
+    if action is None:
+        return GuiActionRunIntent(
+            action_name=action_name,
+            known=False,
+            safety_class="unknown",
+            enabled=False,
+            requires_confirmation=False,
+            confirmation_token="",
+            blocked_reason="unknown action",
+            output_target="output-status-panel",
+            terminal_log=terminal_log,
+        )
+    safety = _safety_name(action.safety_class)
+    token = _confirmation_token(action.name, safety)
+    needs_confirmation = bool(token)
+    blocked = ""
+    if safety == "remote_mutation" and not allow_remote_mutation:
+        blocked = "remote mutation disabled in GUI safe mode"
+    if safety == "destructive" and not allow_destructive:
+        blocked = "destructive action disabled in GUI safe mode"
+    if not blocked and needs_confirmation and confirmation != token:
+        blocked = "missing confirmation token"
+    enabled = blocked == ""
+    return GuiActionRunIntent(
+        action_name=action.name,
+        known=True,
+        safety_class=safety,
+        enabled=enabled,
+        requires_confirmation=needs_confirmation,
+        confirmation_token=token,
+        blocked_reason=blocked,
+        output_target="output-status-panel",
+        terminal_log=terminal_log,
+    )
+
+
+def render_gui_action_run_intent(intent: GuiActionRunIntent) -> str:
+    lines = [
+        "GUI ACTION RUN INTENT",
+        "action_name=" + intent.action_name,
+        "known=" + str(intent.known).lower(),
+        "safety_class=" + intent.safety_class,
+        "enabled=" + str(intent.enabled).lower(),
+        "requires_confirmation=" + str(intent.requires_confirmation).lower(),
+        "confirmation_token=" + (intent.confirmation_token or "NONE"),
+        "blocked_reason=" + (intent.blocked_reason or "NONE"),
+        "output_target=" + intent.output_target,
+        "terminal_log=" + intent.terminal_log,
+        "would_execute=" + str(intent.would_execute).lower(),
+    ]
+    return "\n".join(lines)

agentic_project_kit/gui_action_views.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agentic_project_kit.access_levels import DEFAULT_ACCESS_LEVEL
+from agentic_project_kit.cockpit import (
+    BOUNDED,
+    DESTRUCTIVE,
+    READ_ONLY,
+    CockpitAction,
+    CockpitActionResult,
+)
+from agentic_project_kit.gui_viewmodel import cockpit_actions_for_access_level
+
+
+SAFETY_SORT_ORDER = {READ_ONLY: 0, BOUNDED: 1, DESTRUCTIVE: 2}
+
+
+@dataclass(frozen=True)
+class GuiActionView:
+    action_id: str
+    label: str
+    category: str
+    safety: str
+    command: tuple[str, ...]
+    description: str
+    short_description: str
+    min_access_level: str
+    can_run_by_default: bool
+    structured_explanation: str | None = None
+
+
+@dataclass(frozen=True)
+class GuiActionGroupView:
+    group_id: str
+    label: str
+    description: str
+    actions: tuple[GuiActionView, ...]
+
+
+STRUCTURED_ACTION_EXPLANATIONS = {
+    "git.status": (
+        "PURPOSE: Show local repository dirty state.\n"
+        "EFFECT: Reads git status only.\n"
+        "WHEN: Use before any mutation or PR closeout.\n"
+        "BLOCKED WHEN: Git status cannot run.\n"
+        "AFTER PASS: Continue with the next safe action.\n"
+        "AFTER FAIL: Diagnose repository access."
+    ),
+    "workflow.state": (
+        "PURPOSE: Show workflow and gatekeeper readiness.\n"
+        "EFFECT: Reads workflow state only.\n"
+        "WHEN: Use when deciding whether the GUI may proceed.\n"
+        "BLOCKED WHEN: Workflow state files are unreadable.\n"
+        "AFTER PASS: Continue with the recommended action.\n"
+        "AFTER FAIL: Preserve evidence and diagnose workflow state."
+    ),
+    "dialog.rn": (
+        "PURPOSE: Run the next file-transfer work order through the wrapper.\n"
+        "EFFECT: Performs bounded local workflow mutation.\n"
+        "WHEN: Use only after READY state and valid work order.\n"
+        "BLOCKED WHEN: d2 is pending, state is dirty, or work order is invalid.\n"
+        "AFTER PASS: Read the generated result/evidence.\n"
+        "AFTER FAIL: Inspect the report before retrying."
+    ),
+    "dialog.rnc": (
+        "PURPOSE: Close out the last run through the fixed closeout wrapper.\n"
+        "EFFECT: Commits/pushes expected closeout paths when guarded.\n"
+        "WHEN: Use after a successful bounded run.\n"
+        "BLOCKED WHEN: Required evidence or clean state is missing.\n"
+        "AFTER PASS: Continue with handoff or next slice.\n"
+        "AFTER FAIL: Diagnose closeout evidence."
+    ),
+    "rules.communication-refresh": (
+        "PURPOSE: Publish the current communication rule capsule.\n"
+        "EFFECT: Writes generated rule artifacts and a local d2 pending state.\n"
+        "WHEN: Use when the assistant must reload communication rules.\n"
+        "BLOCKED WHEN: Local mutation is not safe.\n"
+        "AFTER PASS: Send d2 and require machine-readable ACK.\n"
+        "AFTER FAIL: Diagnose rule-refresh output."
+    ),
+}
+
+
+def build_gui_action_views(
+    actions: list[CockpitAction] | None = None,
+    *,
+    access_level: str = DEFAULT_ACCESS_LEVEL,
+) -> list[GuiActionView]:
+    selected = cockpit_actions_for_access_level(actions, access_level=access_level)
+    return [
+        GuiActionView(
+            action_id=action.action_id,
+            label=action.label,
+            category=action.category,
+            safety=action.safety,
+            command=action.command,
+            description=action.description,
+            short_description=action.short_description,
+            min_access_level=action.min_access_level,
+            can_run_by_default=action.safety == READ_ONLY,
+            structured_explanation=STRUCTURED_ACTION_EXPLANATIONS.get(action.action_id),
+        )
+        for action in selected
+    ]
+
+
+SAFETY_EXPLANATIONS = {
+    "read_only": "Safe default: this action may be executed from the GUI through the shared cockpit layer.",
+    "bounded": "Blocked by default: bounded workflow actions require an explicit non-GUI allow path.",
+    "destructive": "Blocked: destructive actions are not executable from the GUI cockpit.",
+}
+
+
+def explain_safety(safety: str) -> str:
+    return SAFETY_EXPLANATIONS.get(safety, f"Blocked: unknown safety class {safety}.")
+
+
+def ordered_action_views(
+    actions: list[GuiActionView] | None = None,
+    *,
+    access_level: str = DEFAULT_ACCESS_LEVEL,
+) -> list[GuiActionView]:
+    selected = actions if actions is not None else build_gui_action_views(access_level=access_level)
+    return sorted(
+        selected,
+        key=lambda action: (
+            SAFETY_SORT_ORDER.get(action.safety, len(SAFETY_SORT_ORDER)),
+            action.label.casefold(),
+            action.action_id,
+        ),
+    )
+
+
+def action_group_for(action: GuiActionView) -> tuple[str, str, str]:
+    if action.category in {"git", "workflow"} and action.safety == READ_ONLY:
+        return ("routine", "Routine", "Frequent read-only orientation checks.")
+    if action.category in {"dialog", "transfer"} or action.action_id == "workflow.go":
+        return ("transfer", "Transfer", "File-transfer work-order and closeout actions.")
+    if action.category in {"gate", "audit"}:
+        return ("diagnostics", "Diagnostics", "Read-only checks for blockers and drift.")
+    return ("advanced", "Advanced", "Release, handoff, and rule-refresh controls.")
+
+
+def grouped_action_views(actions: list[GuiActionView] | tuple[GuiActionView, ...]) -> tuple[GuiActionGroupView, ...]:
+    order = ("routine", "transfer", "diagnostics", "advanced")
+    labels: dict[str, tuple[str, str]] = {}
+    buckets: dict[str, list[GuiActionView]] = {}
+    for action in actions:
+        group_id, label, description = action_group_for(action)
+        labels[group_id] = (label, description)
+        buckets.setdefault(group_id, []).append(action)
+    groups: list[GuiActionGroupView] = []
+    for group_id in order:
+        actions_in_group = tuple(buckets.get(group_id, ()))
+        if not actions_in_group:
+            continue
+        label, description = labels[group_id]
+        groups.append(GuiActionGroupView(group_id, label, description, actions_in_group))
+    return tuple(groups)
+
+
+def format_action_details(action: GuiActionView) -> str:
+    lines = [
+        f"action_id={action.action_id}",
+        f"label={action.label}",
+        f"category={action.category}",
+        f"safety={action.safety}",
+        f"can_run_by_default={str(action.can_run_by_default).lower()}",
+        "command=" + " ".join(action.command),
+        f"description={action.description}",
+        f"short_description={action.short_description}",
+        f"min_access_level={action.min_access_level}",
+        f"safety_explanation={explain_safety(action.safety)}",
+    ]
+    if action.structured_explanation:
+        lines.extend(["", "structured_explanation:", action.structured_explanation])
+    return "\n".join(lines)
+
+
+def format_action_result(result: CockpitActionResult) -> str:
+    lines = [
+        f"action_id={result.action_id}",
+        "status=" + ("completed" if result.executed else "blocked"),
+        f"allowed={str(result.allowed).lower()}",
+        f"executed={str(result.executed).lower()}",
+        f"returncode={result.returncode}",
+    ]
+    if result.message:
+        lines.append(result.message)
+    if result.stdout:
+        lines.extend(["", "stdout:", result.stdout])
+    if result.stderr:
+        lines.extend(["", "stderr:", result.stderr])
+    return "\n".join(lines).rstrip()

agentic_project_kit/gui_activity_log.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Literal
+
+
+ActivityActor = Literal["user", "kit"]
+ActivityStatus = Literal["PASS", "BLOCKED", "ERROR", "INFO"]
+
+
+@dataclass(frozen=True)
+class ActivityEntry:
+    actor: ActivityActor
+    label: str
+    body: str
+    status: ActivityStatus
+    created_at_utc: str
+
+
+def _now_utc() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def normalize_activity_status(status: str | None, body: str = "") -> ActivityStatus:
+    if status is not None and str(status).strip():
+        normalized = str(status).strip().upper().replace("-", "_")
+        if normalized in {"PASS", "PASSED", "SUCCESS", "OK"}:
+            return "PASS"
+        if normalized in {"BLOCK", "BLOCKED", "WAIT", "WAIT_FOR_D2"}:
+            return "BLOCKED"
+        if normalized in {"FAIL", "FAILED", "ERROR"}:
+            return "ERROR"
+        return "INFO"
+
+    text = body.upper()
+    if "BLOCKED" in text or "RESULT_STATUS=BLOCK" in text or '"RESULT_STATUS": "BLOCK' in text:
+        return "BLOCKED"
+    if "TRACEBACK" in text or "ERROR" in text or "FAILED" in text or "RETURNCODE=127" in text:
+        return "ERROR"
+    if "RESULT_STATUS=PASS" in text or "STATE=PASS" in text or '"RESULT_STATUS": "PASS"' in text:
+        return "PASS"
+    return "INFO"
+
+
+class ActivityLog:
+    def __init__(self) -> None:
+        self._entries: list[ActivityEntry] = []
+
+    def log_action(self, label: str) -> ActivityEntry:
+        entry = ActivityEntry(
+            actor="user",
+            label=label.strip() or "Action",
+            body=f"You ran: {label.strip() or 'Action'}",
+            status="INFO",
+            created_at_utc=_now_utc(),
+        )
+        self._entries.append(entry)
+        return entry
+
+    def log_result(self, label: str, status: str | None, body: str) -> ActivityEntry:
+        entry = ActivityEntry(
+            actor="kit",
+            label=label.strip() or "Result",
+            body=body,
+            status=normalize_activity_status(status, body),
+            created_at_utc=_now_utc(),
+        )
+        self._entries.append(entry)
+        return entry
+
+    def entries(self) -> tuple[ActivityEntry, ...]:
+        return tuple(self._entries)
+
+    def clear(self) -> None:
+        self._entries.clear()