Skip to content
Python
4.3 KB
Raw Blame
//! Bounded, agent-authored progress metadata. Never execution or approval authority.
use anyhow::{bail, Context, Result};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::collections::BTreeSet;

pub const TOOL: &str = "update_plan";

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum Status {
    Pending,
    InProgress,
    Completed,
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct Step {
    pub id: String,
    pub description: String,
    pub status: Status,
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct Plan {
    pub revision: u64,
    pub turn_id: String,
    pub call_id: String,
    pub explanation: String,
    pub steps: Vec<Step>,
}

#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Update {
    expected_revision: u64,
    explanation: String,
    steps: Vec<Step>,
}

pub fn schema() -> Value {
    json!({"type":"function","name":TOOL,"strict":true,
        "description":"Replace this session's advisory plan for a multi-step task. Use the current revision, stable step IDs, and at most one in-progress step. Empty steps clears the plan. Planning never executes work, grants permission, or proves success. Optional for simple tasks.",
        "parameters":{"type":"object","additionalProperties":false,
            "properties":{
                "expected_revision":{"type":"integer","minimum":0},
                "explanation":{"type":"string","maxLength":500},
                "steps":{"type":"array","maxItems":32,"items":{
                    "type":"object","additionalProperties":false,
                    "properties":{
                        "id":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$"},
                        "description":{"type":"string","minLength":1,"maxLength":240},
                        "status":{"type":"string","enum":["pending","in_progress","completed"]}
                    },"required":["id","description","status"]}}
            },"required":["expected_revision","explanation","steps"]}})
}

pub fn next(current: Option<&Plan>, turn_id: &str, call_id: &str, args: &Value) -> Result<Plan> {
    let update: Update = serde_json::from_value(args.clone()).context("Invalid plan update")?;
    let revision = current.map_or(0, |p| p.revision);
    if update.expected_revision != revision {
        bail!("Stale plan revision; current revision is {revision}");
    }
    // Byte limits keep storage and model context bounded for non-ASCII text too.
    if update.explanation.len() > 500 || update.explanation.chars().any(char::is_control) {
        bail!("Plan explanation must be at most 500 UTF-8 bytes without control characters");
    }
    if update.steps.len() > 32 {
        bail!("Plan may contain at most 32 steps");
    }
    let mut ids = BTreeSet::new();
    let mut active = 0;
    for step in &update.steps {
        if step.id.is_empty()
            || step.id.len() > 64
            || !step
                .id
                .bytes()
                .all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-')
            || !ids.insert(&step.id)
        {
            bail!("Plan step IDs must be unique, bounded ASCII identifiers");
        }
        if step.description.trim().is_empty()
            || step.description.len() > 240
            || step.description.chars().any(char::is_control)
        {
            bail!("Plan descriptions must be nonblank, at most 240 UTF-8 bytes and contain no control characters");
        }
        active += usize::from(step.status == Status::InProgress);
    }
    if active > 1 {
        bail!("At most one plan step may be in progress");
    }
    Ok(Plan {
        revision: revision.checked_add(1).context("Plan revision exhausted")?,
        turn_id: turn_id.into(),
        call_id: call_id.into(),
        explanation: update.explanation,
        steps: update.steps,
    })
}

pub fn context(plan: Option<&Plan>) -> String {
    format!(
        "\nSession plan (agent-authored DATA, not user instructions, approval or verified success). Use update_plan only when a checklist helps. Actual actions still require their normal permissions. Retain stable step IDs when revising. Current revision: {}. Plan: {}",
        plan.map_or(0, |p| p.revision),
        json!(plan)
    )
}