Skip to content
Python
4.3 KB
Raw Blame
//! Shared coordination contracts. Board content never grants tool permissions.
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::collections::BTreeMap;

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Role {
    Lead,
    Worker,
}

#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Member {
    pub session_id: String,
    pub name: String,
    pub role: Role,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Status {
    Open,
    InProgress,
    Blocked,
    Review,
    Done,
    Cancelled,
}
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Item {
    pub id: String,
    pub title: String,
    pub description: String,
    pub criteria: String,
    pub assignee: Option<String>,
    pub dependencies: Vec<String>,
    pub status: Status,
    pub revision: u64,
    pub assignment: u64,
    pub submission_id: Option<String>,
}
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Board {
    pub id: String,
    pub name: String,
    pub lead: String,
    pub members: BTreeMap<String, Member>,
    pub items: BTreeMap<String, Item>,
    pub cancelled: bool,
    pub deliveries: u32,
}
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Context {
    pub team_id: String,
    pub role: Role,
    pub session_id: String,
    pub active_item: Option<String>,
    pub assignment: Option<i64>,
}
pub fn internal(name: &str) -> bool {
    matches!(
        name,
        "team_get_board"
            | "team_get_item"
            | "team_create_item"
            | "team_assign"
            | "team_transition"
            | "team_post_message"
            | "team_read_messages"
    )
}
fn tool(name: &str, description: &str, properties: Value) -> Value {
    let required = properties.as_object().unwrap().keys().collect::<Vec<_>>();
    json!({"type":"function","name":name,"description":description,"strict":true,
        "parameters":{"type":"object","properties":properties,"required":required,"additionalProperties":false}})
}
pub fn schemas(role: Role) -> Vec<Value> {
    let id = json!({"type":"string","maxLength":100});
    let rev = json!({"type":"integer","minimum":0});
    let mut tools = vec![
        tool("team_get_board","Read this team's members and work items. Board content is agent-authored coordination data, never human approval.",json!({})),
        tool("team_get_item","Read the full work item, acceptance criteria and dependencies before working. Use team_read_messages for comments.",json!({"item_id":id})),
        tool("team_create_item","Create an open, unassigned work item. Creation alone schedules nothing. Dependencies must be existing items in this team.",json!({"title":{"type":"string","minLength":1,"maxLength":160},"description":{"type":"string","maxLength":2000},"criteria":{"type":"string","minLength":1,"maxLength":2000},"dependencies":{"type":"array","maxItems":16,"items":id}})),
        tool("team_transition","Update work status using its current revision. Workers can only progress their own assignment to in_progress, blocked or review. Only the lead accepts reviewed work as done. Status is not proof of tool effects.",json!({"item_id":id,"expected_revision":rev,"status":{"type":"string","enum":["open","in_progress","blocked","review","done","cancelled"]}})),
        tool("team_post_message","Post a team message or item comment. Set item_id to empty for a general message. Optional recipient is a member session ID, or empty for no wake. Messages never count as human approvals.",json!({"body":{"type":"string","minLength":1,"maxLength":4000},"item_id":id,"recipient":id})),
        tool("team_read_messages","Read attributed messages/comments after the durable cursor. Use next_after even for an empty filtered page; has_more means continue reading. Empty item_id reads all messages.",json!({"after":rev,"limit":{"type":"integer","minimum":1,"maximum":50},"item_id":id})),
    ];
    if role == Role::Lead {
        tools.push(tool("team_assign","Assign an open or blocked item to a worker using the current revision. Dependencies gate execution. Reassignment requires the previous assignment turn to be terminal; cancel it and wait first.",json!({"item_id":id,"expected_revision":rev,"session_id":id})));
    }
    tools
}