Skip to content
Python
5.1 KB
Raw Blame
"""The `propose_plan` tool — the agent presents its plan and asks to start executing.

Registered only when the session starts in plan mode. Like `request_directory`, it is
intercepted by the TurnEngine: it emits a PLAN_PROPOSED event and waits for the user's
out-of-band decision. Approval flips the live PermissionEngine out of plan mode (same
session, full exploration context kept); rejection returns the user's feedback so the
agent can revise the plan. The callable here is only a schema carrier + a safe fallback
for surfaces without an approver.
"""

from __future__ import annotations

from aisuite.agents import ToolMetadata, tool


# OPE-237: with `auto_approve_plan_approval` on, the plan also carries its steps, so that
# in auto-approve an approved plan is evidence for exactly those actions. An explicit
# schema: an array of objects can't be generated from the signature. The key is `steps`
# (never `items`, which shadows a template engine's map method; see tools/todo.py).
_STEPS_DESCRIPTION = (
    "Present your plan to the user for approval. In plan mode, approval starts execution. "
    "In auto-approve mode, use it before work with several actions the user did not spell "
    "out (for example tasks from a file): give a one-line summary in `plan` and every "
    "action in `steps`. Each approved step then runs without an approval card for the "
    "rest of this request; anything not listed is reviewed as usual. Be exact: a step's "
    "target is only the file path, the exact command line, or the file name you will "
    "use, with nothing added; any explanation goes in `note`. Use `send` for a file "
    "leaving the machine and name its destination host plainly."
)

_STEPS_SCHEMA = {
    "type": "function",
    "function": {
        "name": "propose_plan",
        "description": _STEPS_DESCRIPTION,
        "parameters": {
            "type": "object",
            "properties": {
                "plan": {"type": "string", "description": "What you will do, in a sentence or two."},
                "steps": {
                    "type": "array",
                    "description": "Auto-approve mode: every action, exactly as you will perform it.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "kind": {
                                "type": "string",
                                "enum": ["write", "delete", "run", "send"],
                                "description": "write or delete a file, run a command, send a file or message somewhere",
                            },
                            "target": {
                                "type": "string",
                                "description": "write/delete: the file path only; run: the exact command line only; send: the file name only (or, for a message, what it is). No description here.",
                            },
                            "destination": {
                                "type": "string",
                                "description": "send only: the host (example.com) or the connector recipient",
                            },
                            "note": {
                                "type": "string",
                                "description": "optional: a few words for the user on what or why; never checked",
                            },
                        },
                        "required": ["kind", "target"],
                    },
                },
            },
            "required": ["plan"],
        },
    },
}


_NO_APPROVER = {"approved": False, "error": "plan approval isn't available in this surface"}


def propose_plan_tool(steps: bool = False) -> object:
    """The tool; `steps=True` (flag `auto_approve_plan_approval`) adds the step list."""

    # Real handling lives in the engine (it needs the out-of-band approval round-trip).
    # These bodies only run if no approver is wired (e.g. a headless surface).
    def propose_plan(plan: str) -> dict:
        """Present your implementation plan to the user for approval. Use this once you
        have explored enough to commit to an approach: summarize what you'll change, in
        which files, and how you'll verify it. If approved, the session switches out of
        read-only plan mode and you implement the plan; if rejected, revise it using the
        feedback in the result. Don't start describing implementation steps as if you
        were doing them — propose first.
        """
        return dict(_NO_APPROVER)

    def propose_plan_with_steps(plan: str, steps: list = None) -> dict:
        return dict(_NO_APPROVER)

    func = propose_plan
    if steps:
        func = propose_plan_with_steps
        func.__name__ = "propose_plan"
        func.__doc__ = _STEPS_DESCRIPTION
        func.__coworker_schema__ = _STEPS_SCHEMA

    return tool(
        func,
        metadata=ToolMetadata(
            category="planning",
            risk_level="low",
            capabilities=["plan"],
            description=(
                "Present the implementation plan for user approval; approval exits "
                "read-only plan mode and starts execution."
            ),
        ),
    )