Typed plans, preconditions, and action schemas

A plan is a proposed sequence or partial order of actions expected to transform an initial state into one satisfying a goal. Natural-language checklists are useful for people but ambiguous for execution. Typed plans make action names, arguments, preconditions, effects, risks, evidence needs, and success checks machine-readable. They let the system reject impossible or unauthorized steps before a tool call.

Classical planning formalisms such as PDDL separate a domain of action schemas from a problem containing initial facts and goals. PDDL2.1 extends this approach with durative actions and numeric quantities. A language-model agent need not implement a full planner to benefit from the discipline. Define predicates for relevant state, action schemas with required conditions, and effects that the controller expects to observe—not effects it merely assumes occurred.

Types constrain arguments. createChangeRequest may require a Service, Environment, and EvidenceBundle, while sendMessage requires a Channel and approved Recipient. Use stable entity identifiers rather than user-facing labels. Validate model output with JSON Schema or an equivalent typed interface. Enumerations should come from a tool registry or ontology release so the model cannot invent an action or scope.

Preconditions include world state and policy. A deployment proposal may require a passing build, approved change window, service ownership, and an authorized operator. Some conditions are static within the task; others must be read immediately before execution. Mark freshness. An approval checked yesterday may be stale when a write executes today.

Effects are hypotheses until verified. An API returning 202 Accepted proves request acceptance, not completion. The action schema should define an observation query and a success predicate. It should also define possible failure and ambiguous outcomes. If a timeout occurs after sending a request, retrying without an idempotency key can duplicate a write. The controller first queries status by request key.

Plans need causal links. If step 4 depends on evidence from step 2, encode that dependency and required output type. A directed acyclic plan can run independent reads concurrently while serializing risky actions. Dynamic replanning is allowed when observations invalidate assumptions, but the new plan is validated under the same policy and remaining budget.

Goal decomposition should preserve user intent. A subgoal includes its contribution to the parent goal, evidence of satisfaction, and constraints inherited from the task. The model may propose optional improvements, but the controller cannot expand scope into new external effects without authority. A request to analyze data does not imply permission to email findings or update the source.

Risk annotations support control. Classify actions as read, reversible write, irreversible write, communication, permission change, financial, or code execution. Map risk classes to approvals, sandboxes, rate limits, and evidence. Risk derives from tool plus arguments and environment: reading a public catalog differs from retrieving a private patient record with the same search interface.

Validate plans at three levels. Structural validation checks schema and known identifiers. Semantic validation checks types, preconditions, goal relevance, and dependency closure. Policy validation checks authority, data scope, budgets, and approval. Then simulate expected state changes where practical. Planning does not eliminate runtime checks because the environment can change between validation and execution.

Plan quality metrics include valid-step rate, precondition failure, unnecessary action count, parallelizable work, replans, irreversible actions avoided, cost estimate error, and verified goal completion. Prefer short plans with explicit evidence over elaborate prose that hides untestable assumptions.