Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity
20ce1dcda9
yoi/crates/ticket/src/tool.rs

2311 lines
81 KiB
Rust
Raw Blame History

//! LLM tool implementations for typed Ticket backend operations.
//!
//! These tools are intentionally owned by the `ticket` crate so Pod features can
//! install Ticket behavior without reimplementing domain/backend logic or
//! granting generic filesystem write authority.
use std::sync::Arc;
use async_trait::async_trait;
use llm_worker::tool::{Tool, ToolDefinition, ToolError, ToolMeta, ToolOutput};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use crate::{
AcceptedOrchestrationPlan, LocalTicketBackend, MarkdownText, NewOrchestrationPlanRecord,
NewTicket, NewTicketEvent, NewTicketRelation, OrchestrationPlanKind, Ticket, TicketBackend,
TicketDoctorDiagnostic, TicketDoctorReport, TicketDoctorSeverity, TicketError, TicketEventKind,
TicketIdOrSlug, TicketIntakeSummary, TicketRelationKind, TicketReview, TicketReviewResult,
TicketStateChange, TicketSummary, TicketWorkflowState,
};
const DEFAULT_LIST_LIMIT: usize = 50;
const MAX_LIST_LIMIT: usize = 100;
const LIST_TITLE_MAX_CHARS: usize = 96;
const LIST_HINT_MAX_CHARS: usize = 80;
const DEFAULT_EVENT_LIMIT: usize = 20;
const MAX_EVENT_LIMIT: usize = 100;
const DEFAULT_ARTIFACT_LIMIT: usize = 50;
const MAX_ARTIFACT_LIMIT: usize = 200;
const DEFAULT_BODY_MAX_BYTES: usize = 16 * 1024;
const MAX_BODY_MAX_BYTES: usize = 64 * 1024;
const DEFAULT_DIAGNOSTIC_LIMIT: usize = 100;
const MAX_DIAGNOSTIC_LIMIT: usize = 500;
pub const TICKET_BASE_TOOL_NAMES: [&str; 9] = [
"TicketCreate",
"TicketList",
"TicketShow",
"TicketComment",
"TicketReview",
"TicketIntakeReady",
"TicketWorkflowState",
"TicketClose",
"TicketDoctor",
];
pub const TICKET_BASE_READ_ONLY_TOOL_NAMES: [&str; 3] =
["TicketList", "TicketShow", "TicketDoctor"];
pub const TICKET_ORCHESTRATION_TOOL_NAMES: [&str; 4] = [
"TicketRelationRecord",
"TicketRelationQuery",
"TicketOrchestrationPlanRecord",
"TicketOrchestrationPlanQuery",
];
pub const TICKET_ORCHESTRATION_READ_ONLY_TOOL_NAMES: [&str; 2] =
["TicketRelationQuery", "TicketOrchestrationPlanQuery"];
pub const TICKET_TOOL_NAMES: [&str; 13] = [
"TicketCreate",
"TicketList",
"TicketShow",
"TicketComment",
"TicketReview",
"TicketIntakeReady",
"TicketWorkflowState",
"TicketClose",
"TicketRelationRecord",
"TicketRelationQuery",
"TicketOrchestrationPlanRecord",
"TicketOrchestrationPlanQuery",
"TicketDoctor",
];
pub const TICKET_READ_ONLY_TOOL_NAMES: [&str; 5] = [
"TicketList",
"TicketShow",
"TicketRelationQuery",
"TicketOrchestrationPlanQuery",
"TicketDoctor",
];
pub const TICKET_MUTATING_TOOL_NAMES: [&str; 8] = [
"TicketCreate",
"TicketComment",
"TicketReview",
"TicketIntakeReady",
"TicketWorkflowState",
"TicketClose",
"TicketRelationRecord",
"TicketOrchestrationPlanRecord",
];
const CREATE_DESCRIPTION: &str = "Create a Ticket through the configured typed Ticket backend. \
Inputs mirror the Ticket `item.md` fields; `title` is required, `body` is Markdown, and the \
backend assigns the id and writes the local Ticket file layout under the configured backend root.";
const LIST_DESCRIPTION: &str = "List Tickets from the configured typed Ticket backend as a \
lightweight bounded overview for selection only. Filter by state (`planning`, `ready`, `queued`, \
`inprogress`, `done`, `closed`, or `all`). Output is short summaries only; use TicketShow before \
routing, closing, planning, or implementation decisions.";
const SHOW_DESCRIPTION: &str = "Show one Ticket by id or exact query through the configured \
typed Ticket backend. Output includes bounded Markdown body, recent thread events, resolution, and \
artifact metadata.";
const COMMENT_DESCRIPTION: &str = "Append a typed Ticket thread event. `role` must be `comment`, \
`plan`, `decision`, or `implementation_report`; `body` is Markdown. Writes stay inside the \
configured Ticket backend root.";
const REVIEW_DESCRIPTION: &str = "Append a Ticket review event. `result` must be `approve` or \
`request_changes`; `body` is Markdown. Writes stay inside the configured Ticket backend root.";
const INTAKE_READY_DESCRIPTION: &str = "Mark an existing Ticket planning lane ready through the typed \
Ticket backend. The tool appends a bounded `intake_summary`, appends a typed `state_changed` event \
for `state`, and transitions state to `ready`.";
const WORKFLOW_STATE_DESCRIPTION: &str = "Transition Ticket `state` through the typed \
Ticket backend with a bounded `state_changed` event. Treat `queued -> inprogress` \
as the implementation acceptance step: implementation side effects should happen only after that \
transition is accepted and recorded. Orchestrator may return `ready` or `queued` Tickets to `planning` only with a concrete missing decision/information reason.";
const CLOSE_DESCRIPTION: &str = "Close a Ticket with a Markdown resolution through the typed Ticket \
backend. The backend sets `state: closed`, writes resolution.md, updates item.md, and appends \
a close event.";
const RELATION_RECORD_DESCRIPTION: &str = "Record a forward typed Ticket-to-Ticket relation as durable \
project-level metadata. Supported kinds are depends_on, blocks, related, supersedes, and duplicate_of; \
inverse views are derived, not stored.";
const RELATION_QUERY_DESCRIPTION: &str = "Query durable typed Ticket relation metadata. When a Ticket \
is provided, both outgoing records owned by it and incoming forward records that target it are returned.";
const ORCHESTRATION_PLAN_RECORD_DESCRIPTION: &str = "Append a typed Ticket orchestration plan record \
for ordering, dependency, conflict, waiting/capacity, or accepted-plan decisions. Records are durable \
Ticket artifacts and do not move state, reorder queues, or start work.";
const ORCHESTRATION_PLAN_QUERY_DESCRIPTION: &str = "Query durable Ticket orchestration plan records by \
Ticket id and/or relation kind. This is read-only planning context; Orchestrator must still make \
explicit state decisions.";
const DOCTOR_DESCRIPTION: &str = "Run typed Ticket backend consistency checks and return bounded \
diagnostics through the typed backend without shelling out to external commands.";
fn base_tool_description(name: &str) -> &'static str {
match name {
"TicketCreate" => CREATE_DESCRIPTION,
"TicketList" => LIST_DESCRIPTION,
"TicketShow" => SHOW_DESCRIPTION,
"TicketComment" => COMMENT_DESCRIPTION,
"TicketReview" => REVIEW_DESCRIPTION,
"TicketIntakeReady" => INTAKE_READY_DESCRIPTION,
"TicketWorkflowState" => WORKFLOW_STATE_DESCRIPTION,
"TicketClose" => CLOSE_DESCRIPTION,
"TicketRelationRecord" => RELATION_RECORD_DESCRIPTION,
"TicketRelationQuery" => RELATION_QUERY_DESCRIPTION,
"TicketOrchestrationPlanRecord" => ORCHESTRATION_PLAN_RECORD_DESCRIPTION,
"TicketOrchestrationPlanQuery" => ORCHESTRATION_PLAN_QUERY_DESCRIPTION,
"TicketDoctor" => DOCTOR_DESCRIPTION,
_ => "Ticket backend tool.",
}
}
/// Build the model-visible Ticket tool description for a configured Ticket backend.
///
/// `record_language` is the durable Ticket record/tool-body language, distinct from
/// worker response language and Memory/Knowledge language. Keeping this on the tool
/// surface ensures every Ticket-capable Pod sees the policy without hidden context
/// injection or role-launch-only prose.
pub fn ticket_tool_description(name: &str, record_language: Option<&str>) -> String {
let mut description = base_tool_description(name).to_string();
if let Some(language) = record_language.filter(|language| !language.trim().is_empty()) {
description.push_str("\n\nTicket record language: ");
description.push_str(language.trim());
description.push_str(". Use this language for durable Ticket record and Ticket tool body text, including Ticket item bodies, thread comments/plans/decisions/implementation reports, reviews, resolutions, intake summaries, and orchestration plan notes. This policy is distinct from worker.language for normal prose and memory.language for Memory/Knowledge. Preserve protocol literals, file paths, commands, logs, identifiers, and quoted external text when translation would reduce fidelity.");
}
description
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketCreateParams {
/// Ticket title. Must not be empty.
title: String,
/// Markdown body for item.md. If omitted, a small default body is used.
#[serde(default)]
body: Option<String>,
/// Optional thread author for the create event.
#[serde(default)]
author: Option<String>,
/// Optional assignee frontmatter value.
#[serde(default)]
assignee: Option<String>,
/// Optional readiness frontmatter value.
#[serde(default)]
readiness: Option<String>,
/// Optional risk flag frontmatter values.
#[serde(default)]
risk_flags: Vec<String>,
/// Optional state frontmatter value. Defaults to `planning`.
#[serde(default)]
state: Option<TicketWorkflowStateParam>,
/// Optional queued_by frontmatter value.
#[serde(default)]
queued_by: Option<String>,
/// Optional queued_at frontmatter value.
#[serde(default)]
queued_at: Option<String>,
}
#[derive(Debug, Clone, Copy, Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "snake_case")]
enum TicketWorkflowStateParam {
Planning,
Ready,
Queued,
Inprogress,
Done,
Closed,
}
impl TicketWorkflowStateParam {
fn into_state(self) -> TicketWorkflowState {
match self {
Self::Planning => TicketWorkflowState::Planning,
Self::Ready => TicketWorkflowState::Ready,
Self::Queued => TicketWorkflowState::Queued,
Self::Inprogress => TicketWorkflowState::InProgress,
Self::Done => TicketWorkflowState::Done,
Self::Closed => TicketWorkflowState::Closed,
}
}
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "snake_case")]
enum TicketListStateParam {
Planning,
Ready,
Queued,
Inprogress,
Done,
Closed,
All,
}
impl TicketListStateParam {
fn as_filter(self) -> (crate::TicketFilter, &'static str) {
match self {
Self::Planning => (
crate::TicketFilter::state(TicketWorkflowState::Planning),
"planning",
),
Self::Ready => (
crate::TicketFilter::state(TicketWorkflowState::Ready),
"ready",
),
Self::Queued => (
crate::TicketFilter::state(TicketWorkflowState::Queued),
"queued",
),
Self::Inprogress => (
crate::TicketFilter::state(TicketWorkflowState::InProgress),
"inprogress",
),
Self::Done => (
crate::TicketFilter::state(TicketWorkflowState::Done),
"done",
),
Self::Closed => (
crate::TicketFilter::state(TicketWorkflowState::Closed),
"closed",
),
Self::All => (crate::TicketFilter::all(), "all"),
}
}
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketListParams {
/// State filter. Defaults to all Tickets.
#[serde(default)]
state: Option<TicketListStateParam>,
/// Maximum number of summaries to return. Defaults to 50, max 100.
#[serde(default)]
limit: Option<usize>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketShowParams {
/// Ticket id. Exactly one of `id` or `query` must be provided.
#[serde(default)]
id: Option<String>,
/// Exact ticket id query. Exactly one of `id` or `query` must be provided.
#[serde(default)]
query: Option<String>,
/// Maximum number of most-recent thread events to return. Defaults to 20, max 100.
#[serde(default)]
event_limit: Option<usize>,
/// Maximum number of artifact metadata entries to return. Defaults to 50, max 200.
#[serde(default)]
artifact_limit: Option<usize>,
/// Maximum bytes for each Markdown body field before adding a truncation marker. Defaults to 16 KiB, max 64 KiB.
#[serde(default)]
body_max_bytes: Option<usize>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "snake_case")]
enum TicketCommentRoleParam {
Comment,
Plan,
Decision,
ImplementationReport,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketCommentParams {
/// Ticket id.
ticket: String,
/// Thread event role: `comment`, `plan`, `decision`, or `implementation_report`.
role: TicketCommentRoleParam,
/// Markdown event body.
body: String,
/// Optional thread author.
#[serde(default)]
author: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "snake_case")]
enum TicketReviewResultParam {
Approve,
RequestChanges,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketReviewParams {
/// Ticket id.
ticket: String,
/// Review result: `approve` or `request_changes`.
result: TicketReviewResultParam,
/// Markdown review body.
body: String,
/// Optional thread author.
#[serde(default)]
author: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketIntakeReadyParams {
/// Ticket id.
ticket: String,
/// Concise bounded intake summary to append as a typed intake_summary event.
intake_summary: String,
/// Optional author for both intake_summary and state_changed events.
#[serde(default)]
author: Option<String>,
/// Reason attached to the state_changed event. Defaults to `planning_ready`.
#[serde(default)]
reason: Option<String>,
/// Optional state_changed body. If omitted, a concise default is used.
#[serde(default)]
state_change_body: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketWorkflowStateParams {
/// Ticket id.
ticket: String,
/// Expected current state. The backend rejects stale transitions.
from: TicketWorkflowStateParam,
/// Target state.
to: TicketWorkflowStateParam,
/// Reason attached to the typed state_changed event.
reason: String,
/// Markdown body for the typed state_changed event.
body: String,
/// Optional thread author.
#[serde(default)]
author: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketCloseParams {
/// Ticket id.
ticket: String,
/// Markdown resolution written to resolution.md and thread.md.
resolution: String,
}
#[derive(Debug, Clone, Copy, Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "snake_case")]
enum TicketRelationKindParam {
DependsOn,
Blocks,
Related,
Supersedes,
DuplicateOf,
}
impl TicketRelationKindParam {
fn into_kind(self) -> TicketRelationKind {
match self {
Self::DependsOn => TicketRelationKind::DependsOn,
Self::Blocks => TicketRelationKind::Blocks,
Self::Related => TicketRelationKind::Related,
Self::Supersedes => TicketRelationKind::Supersedes,
Self::DuplicateOf => TicketRelationKind::DuplicateOf,
}
}
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketRelationRecordParams {
/// Ticket id that owns the forward relation.
ticket: String,
/// Forward relation kind: depends_on, blocks, related, supersedes, or duplicate_of.
kind: TicketRelationKindParam,
/// Target canonical Ticket id. Title/slug words are not accepted as relation authority.
target: String,
/// Optional bounded rationale/note.
#[serde(default)]
note: Option<String>,
/// Optional record author.
#[serde(default)]
author: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketRelationQueryParams {
/// Optional Ticket id to query. Includes outgoing and incoming forward records for that id.
#[serde(default)]
ticket: Option<String>,
/// Optional forward relation kind filter.
#[serde(default)]
kind: Option<TicketRelationKindParam>,
/// Maximum records to return. Defaults to 100, max 200.
#[serde(default)]
limit: Option<usize>,
}
#[derive(Debug, Serialize)]
struct TicketRelationQueryOutput {
count: usize,
returned: usize,
truncated: bool,
relations: Vec<Value>,
}
#[derive(Debug, Clone, Copy, Deserialize, schemars::JsonSchema)]
#[serde(rename_all = "snake_case")]
enum OrchestrationPlanKindParam {
Before,
After,
BlockedBy,
Blocks,
ConflictsWith,
DoNotParallelize,
WaitingCapacityNote,
AcceptedPlan,
}
impl OrchestrationPlanKindParam {
fn into_kind(self) -> OrchestrationPlanKind {
match self {
Self::Before => OrchestrationPlanKind::Before,
Self::After => OrchestrationPlanKind::After,
Self::BlockedBy => OrchestrationPlanKind::BlockedBy,
Self::Blocks => OrchestrationPlanKind::Blocks,
Self::ConflictsWith => OrchestrationPlanKind::ConflictsWith,
Self::DoNotParallelize => OrchestrationPlanKind::DoNotParallelize,
Self::WaitingCapacityNote => OrchestrationPlanKind::WaitingCapacityNote,
Self::AcceptedPlan => OrchestrationPlanKind::AcceptedPlan,
}
}
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct AcceptedOrchestrationPlanParams {
/// Bounded project-relevant accepted plan summary.
summary: String,
/// Optional branch name for the accepted plan. Do not include runtime/session/socket details.
#[serde(default)]
branch: Option<String>,
/// Optional worktree path for the accepted plan. Do not include runtime/session/socket details.
#[serde(default)]
worktree: Option<String>,
/// Optional bounded role/work allocation plan. Do not include raw model output or private runtime details.
#[serde(default)]
role_plan: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketOrchestrationPlanRecordParams {
/// Ticket id that owns this orchestration plan record.
ticket: String,
/// Record kind: before/after, blocked_by/blocks, conflicts_with/do_not_parallelize, waiting_capacity_note, or accepted_plan.
kind: OrchestrationPlanKindParam,
/// Related Ticket id for ordering, dependency, and conflict records.
#[serde(default)]
related_ticket: Option<String>,
/// Optional bounded rationale/note. Required for waiting_capacity_note.
#[serde(default)]
note: Option<String>,
/// Accepted plan fields. Required for accepted_plan and invalid for other kinds.
#[serde(default)]
accepted_plan: Option<AcceptedOrchestrationPlanParams>,
/// Optional record author.
#[serde(default)]
author: Option<String>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketOrchestrationPlanQueryParams {
/// Optional Ticket id to query. Omit to query across the backend root.
#[serde(default)]
ticket: Option<String>,
/// Optional relation kind filter.
#[serde(default)]
relation_kind: Option<OrchestrationPlanKindParam>,
/// Maximum records to return. Defaults to 100, max 200.
#[serde(default)]
limit: Option<usize>,
}
#[derive(Debug, Serialize)]
struct TicketOrchestrationPlanQueryOutput {
count: usize,
returned: usize,
truncated: bool,
records: Vec<Value>,
}
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct TicketDoctorParams {
/// Maximum diagnostics to return. Defaults to 100, max 500.
#[serde(default)]
limit: Option<usize>,
}
#[derive(Debug, Serialize)]
struct TicketRefOutput {
id: String,
state: String,
}
#[derive(Debug, Serialize)]
struct TicketListOutput {
state_filter: String,
count: usize,
returned: usize,
truncated: bool,
limit: usize,
tickets: Vec<TicketListTicketOutput>,
}
#[derive(Debug, Serialize)]
struct TicketListTicketOutput {
id: String,
title: String,
state: String,
updated_at: Option<String>,
#[serde(skip_serializing_if = "Vec::is_empty")]
hints: Vec<String>,
}
#[derive(Debug, Serialize)]
struct TicketDoctorOutput {
ok: bool,
error_count: usize,
diagnostic_count: usize,
returned: usize,
truncated: bool,
diagnostics: Vec<Value>,
}
#[derive(Clone)]
struct TicketCreateTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketListTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketShowTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketCommentTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketReviewTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketIntakeReadyTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketWorkflowStateTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketCloseTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketRelationRecordTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketRelationQueryTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketOrchestrationPlanRecordTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketOrchestrationPlanQueryTool {
backend: LocalTicketBackend,
}
#[derive(Clone)]
struct TicketDoctorTool {
backend: LocalTicketBackend,
}
#[async_trait]
impl Tool for TicketCreateTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketCreateParams = parse_input("TicketCreate", input_json)?;
let mut input = NewTicket::new(params.title);
if let Some(body) = params.body {
input.body = MarkdownText::new(body);
}
input.author = params.author;
input.assignee = params.assignee;
input.readiness = params.readiness;
input.risk_flags = params.risk_flags;
input.workflow_state = params.state.map(TicketWorkflowStateParam::into_state);
input.queued_by = params.queued_by;
input.queued_at = params.queued_at;
let created = self
.backend
.create(input)
.map_err(|error| backend_error("TicketCreate", error))?;
Ok(json_output(
format!("Created ticket {}", created.id),
json!(TicketRefOutput {
id: created.id,
state: "planning".to_string(),
}),
))
}
}
#[async_trait]
impl Tool for TicketListTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketListParams = parse_input("TicketList", input_json)?;
let state = params.state.unwrap_or(TicketListStateParam::All);
let (filter, state_filter) = state.as_filter();
let limit = bounded(params.limit, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT);
let tickets = self
.backend
.list(filter)
.map_err(|error| backend_error("TicketList", error))?;
let count = tickets.len();
let returned_tickets: Vec<_> = tickets
.into_iter()
.take(limit)
.map(ticket_summary_json)
.collect();
let output = TicketListOutput {
state_filter: state_filter.to_string(),
count,
returned: returned_tickets.len(),
truncated: count > returned_tickets.len(),
limit,
tickets: returned_tickets,
};
Ok(json_output(
format!(
"Listed {} ticket(s) for state {state_filter}{}",
output.returned,
if output.truncated { " (truncated)" } else { "" }
),
output,
))
}
}
#[async_trait]
impl Tool for TicketShowTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketShowParams = parse_input("TicketShow", input_json)?;
let query = id_or_query(params.id, params.query)?;
let event_limit = bounded(params.event_limit, DEFAULT_EVENT_LIMIT, MAX_EVENT_LIMIT);
let artifact_limit = bounded(
params.artifact_limit,
DEFAULT_ARTIFACT_LIMIT,
MAX_ARTIFACT_LIMIT,
);
let body_max_bytes = bounded(
params.body_max_bytes,
DEFAULT_BODY_MAX_BYTES,
MAX_BODY_MAX_BYTES,
);
let ticket = self
.backend
.show(query)
.map_err(|error| backend_error("TicketShow", error))?;
let summary = format!(
"Ticket {} state {}",
ticket.meta.id,
ticket.meta.workflow_state.as_str()
);
Ok(json_output(
summary,
ticket_json(&ticket, event_limit, artifact_limit, body_max_bytes),
))
}
}
#[async_trait]
impl Tool for TicketCommentTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketCommentParams = parse_input("TicketComment", input_json)?;
let kind = match params.role {
TicketCommentRoleParam::Comment => TicketEventKind::Comment,
TicketCommentRoleParam::Plan => TicketEventKind::Plan,
TicketCommentRoleParam::Decision => TicketEventKind::Decision,
TicketCommentRoleParam::ImplementationReport => TicketEventKind::ImplementationReport,
};
let role = kind.as_str().to_string();
let mut event = NewTicketEvent::new(kind, params.body);
event.author = params.author;
self.backend
.add_event(TicketIdOrSlug::Query(params.ticket.clone()), event)
.map_err(|error| backend_error("TicketComment", error))?;
Ok(json_output(
format!("Appended {role} event to ticket {}", params.ticket),
json!({ "ticket": params.ticket, "event": role, "ok": true }),
))
}
}
#[async_trait]
impl Tool for TicketReviewTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketReviewParams = parse_input("TicketReview", input_json)?;
let result = match params.result {
TicketReviewResultParam::Approve => TicketReviewResult::Approve,
TicketReviewResultParam::RequestChanges => TicketReviewResult::RequestChanges,
};
let result_str = result.as_str().to_string();
let review = TicketReview {
result,
author: params.author,
body: MarkdownText::new(params.body),
};
self.backend
.review(TicketIdOrSlug::Query(params.ticket.clone()), review)
.map_err(|error| backend_error("TicketReview", error))?;
Ok(json_output(
format!("Appended {result_str} review to ticket {}", params.ticket),
json!({ "ticket": params.ticket, "review": result_str, "ok": true }),
))
}
}
#[async_trait]
impl Tool for TicketIntakeReadyTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketIntakeReadyParams = parse_input("TicketIntakeReady", input_json)?;
let from = TicketWorkflowState::Planning;
let reason = params
.reason
.unwrap_or_else(|| "planning_ready".to_string());
let body = params.state_change_body.unwrap_or_else(|| {
self.backend
.default_intake_ready_state_change_body(from.as_str())
});
let mut summary = TicketIntakeSummary::new(params.intake_summary);
summary.author = params.author.clone();
let mut change = TicketStateChange::new(
from.as_str(),
TicketWorkflowState::Ready.as_str(),
reason,
body,
);
change.author = params.author;
self.backend
.mark_intake_ready(
TicketIdOrSlug::Query(params.ticket.clone()),
summary,
change,
)
.map_err(|error| backend_error("TicketIntakeReady", error))?;
Ok(json_output(
format!("Marked ticket {} state ready", params.ticket),
json!({ "ticket": params.ticket, "state": "ready", "ok": true }),
))
}
}
#[async_trait]
impl Tool for TicketWorkflowStateTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketWorkflowStateParams = parse_input("TicketWorkflowState", input_json)?;
let from = params.from.into_state();
let to = params.to.into_state();
if from == to {
return Err(ToolError::InvalidArgument(
"state transition must change state".to_string(),
));
}
let mut change =
TicketStateChange::new(from.as_str(), to.as_str(), params.reason, params.body);
change.author = params.author;
self.backend
.set_workflow_state(TicketIdOrSlug::Query(params.ticket.clone()), change)
.map_err(|error| backend_error("TicketWorkflowState", error))?;
Ok(json_output(
format!(
"Transitioned ticket {} state {} -> {}",
params.ticket,
from.as_str(),
to.as_str()
),
json!({
"ticket": params.ticket,
"from": from.as_str(),
"to": to.as_str(),
"state": to.as_str(),
"ok": true
}),
))
}
}
#[async_trait]
impl Tool for TicketCloseTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketCloseParams = parse_input("TicketClose", input_json)?;
self.backend
.close(
TicketIdOrSlug::Query(params.ticket.clone()),
MarkdownText::new(params.resolution),
)
.map_err(|error| backend_error("TicketClose", error))?;
Ok(json_output(
format!("Closed ticket {}", params.ticket),
json!({ "ticket": params.ticket, "state": "closed", "ok": true }),
))
}
}
#[async_trait]
impl Tool for TicketRelationRecordTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketRelationRecordParams = parse_input("TicketRelationRecord", input_json)?;
let relation = NewTicketRelation {
kind: params.kind.into_kind(),
target: params.target.clone(),
note: params.note,
author: params.author,
};
let output = self
.backend
.add_ticket_relation(TicketIdOrSlug::Id(params.ticket.clone()), relation)
.map_err(|error| backend_error("TicketRelationRecord", error))?;
Ok(json_output(
format!(
"Recorded ticket relation {} {} {}",
output.ticket_id, output.kind, output.target
),
ticket_relation_json(&output),
))
}
}
#[async_trait]
impl Tool for TicketRelationQueryTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketRelationQueryParams = parse_input("TicketRelationQuery", input_json)?;
let limit = bounded(params.limit, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT);
let ticket = params.ticket.clone().map(TicketIdOrSlug::Id);
let kind = params.kind.map(TicketRelationKindParam::into_kind);
let relations = self
.backend
.query_ticket_relations(ticket, kind)
.map_err(|error| backend_error("TicketRelationQuery", error))?;
let count = relations.len();
let truncated = count > limit;
let returned_relations = relations
.into_iter()
.take(limit)
.map(|relation| ticket_relation_json(&relation))
.collect::<Vec<_>>();
Ok(json_output(
format!(
"Found {} ticket relation(s){}",
count,
if truncated { " (truncated)" } else { "" }
),
TicketRelationQueryOutput {
count,
returned: returned_relations.len(),
truncated,
relations: returned_relations,
},
))
}
}
#[async_trait]
impl Tool for TicketOrchestrationPlanRecordTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketOrchestrationPlanRecordParams =
parse_input("TicketOrchestrationPlanRecord", input_json)?;
let accepted_plan = params.accepted_plan.map(|plan| AcceptedOrchestrationPlan {
summary: plan.summary,
branch: plan.branch,
worktree: plan.worktree,
role_plan: plan.role_plan,
});
let record = NewOrchestrationPlanRecord {
kind: params.kind.into_kind(),
related_ticket: params.related_ticket,
note: params.note,
accepted_plan,
author: params.author,
};
let output = self
.backend
.add_orchestration_plan_record(TicketIdOrSlug::Query(params.ticket.clone()), record)
.map_err(|error| backend_error("TicketOrchestrationPlanRecord", error))?;
Ok(json_output(
format!(
"Recorded orchestration plan {} for ticket {}",
output.kind, params.ticket
),
output,
))
}
}
#[async_trait]
impl Tool for TicketOrchestrationPlanQueryTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketOrchestrationPlanQueryParams =
parse_input("TicketOrchestrationPlanQuery", input_json)?;
let limit = bounded(params.limit, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT);
let ticket = params.ticket.clone().map(TicketIdOrSlug::Query);
let kind = params
.relation_kind
.map(OrchestrationPlanKindParam::into_kind);
let records = self
.backend
.query_orchestration_plan_records(ticket, kind)
.map_err(|error| backend_error("TicketOrchestrationPlanQuery", error))?;
let count = records.len();
let truncated = count > limit;
let returned_records = records
.into_iter()
.take(limit)
.map(|record| serde_json::to_value(record).unwrap_or_else(|_| json!({})))
.collect::<Vec<_>>();
Ok(json_output(
format!(
"Found {} orchestration plan record(s){}",
count,
if truncated { " (truncated)" } else { "" }
),
TicketOrchestrationPlanQueryOutput {
count,
returned: returned_records.len(),
truncated,
records: returned_records,
},
))
}
}
#[async_trait]
impl Tool for TicketDoctorTool {
async fn execute(
&self,
input_json: &str,
_ctx: llm_worker::tool::ToolExecutionContext,
) -> Result<ToolOutput, ToolError> {
let params: TicketDoctorParams = parse_input("TicketDoctor", input_json)?;
let limit = bounded(params.limit, DEFAULT_DIAGNOSTIC_LIMIT, MAX_DIAGNOSTIC_LIMIT);
let report = self
.backend
.doctor()
.map_err(|error| backend_error("TicketDoctor", error))?;
let output = doctor_output(report, limit);
Ok(json_output(
format!(
"Ticket doctor: {} error(s), {} diagnostic(s){}",
output.error_count,
output.diagnostic_count,
if output.truncated { " (truncated)" } else { "" }
),
output,
))
}
}
fn parse_input<T: for<'de> Deserialize<'de>>(tool: &str, input_json: &str) -> Result<T, ToolError> {
serde_json::from_str(input_json)
.map_err(|error| ToolError::InvalidArgument(format!("invalid {tool} input: {error}")))
}
fn backend_error(tool: &str, error: TicketError) -> ToolError {
ToolError::ExecutionFailed(format!("{tool} failed: {error}"))
}
fn bounded(value: Option<usize>, default: usize, max: usize) -> usize {
value.unwrap_or(default).clamp(1, max)
}
fn id_or_query(id: Option<String>, query: Option<String>) -> Result<TicketIdOrSlug, ToolError> {
let provided = id.iter().chain(query.iter()).count();
if provided != 1 {
return Err(ToolError::InvalidArgument(
"exactly one of id or query must be provided".to_string(),
));
}
if let Some(id) = id {
Ok(TicketIdOrSlug::Id(id))
} else {
Ok(TicketIdOrSlug::Query(
query.expect("provided count checked"),
))
}
}
fn ticket_summary_json(ticket: TicketSummary) -> TicketListTicketOutput {
let hints = ticket_list_hints(&ticket);
TicketListTicketOutput {
id: ticket.id,
title: truncate_inline(ticket.title.as_str(), LIST_TITLE_MAX_CHARS),
state: ticket.workflow_state.as_str().to_string(),
updated_at: ticket.updated_at,
hints,
}
}
fn ticket_list_hints(ticket: &TicketSummary) -> Vec<String> {
let mut hints = Vec::new();
if let Some(readiness) = ticket.readiness.as_deref() {
hints.push(format!(
"readiness:{}",
truncate_inline(readiness, LIST_HINT_MAX_CHARS)
));
}
hints
}
fn ticket_relation_json(relation: &crate::TicketRelation) -> Value {
json!({
"ticket_id": relation.ticket_id,
"kind": relation.kind.as_str(),
"target": relation.target,
"note": relation.note,
"author": relation.author,
"at": relation.at,
})
}
fn ticket_relations_json(ticket: &Ticket) -> Value {
let outgoing: Vec<_> = ticket
.relations
.outgoing
.iter()
.map(ticket_relation_json)
.collect();
let incoming: Vec<_> = ticket
.relations
.incoming
.iter()
.map(|relation| {
json!({
"source_ticket": relation.source_ticket,
"inverse_kind": relation.inverse_kind,
"forward_kind": relation.forward_kind.as_str(),
"note": relation.note,
"author": relation.author,
"at": relation.at,
})
})
.collect();
let blockers: Vec<_> = ticket
.relations
.blockers
.iter()
.map(|blocker| {
json!({
"blocking_ticket": blocker.blocking_ticket,
"reason_kind": blocker.reason_kind,
"relation_kind": blocker.relation_kind.as_str(),
"note": blocker.note,
"blocking_state": blocker.blocking_state.as_str(),
})
})
.collect();
let notices: Vec<_> = ticket
.relations
.notices
.iter()
.map(|notice| {
json!({
"related_ticket": notice.related_ticket,
"kind": notice.kind.as_str(),
"message": notice.message,
})
})
.collect();
json!({
"outgoing": outgoing,
"incoming": incoming,
"blockers": blockers,
"notices": notices,
})
}
fn ticket_json(
ticket: &Ticket,
event_limit: usize,
artifact_limit: usize,
body_max_bytes: usize,
) -> Value {
let event_count = ticket.events.len();
let events: Vec<_> = ticket
.events
.iter()
.skip(event_count.saturating_sub(event_limit))
.map(|event| {
json!({
"kind": event.kind.as_str(),
"author": event.author,
"at": event.at,
"state": event.status,
"from": event.from,
"to": event.to,
"reason": event.reason,
"state_field": event.state_field,
"attributes": event.attributes,
"heading": event.heading,
"body": truncate_text(event.body.as_str(), body_max_bytes),
})
})
.collect();
let artifact_count = ticket.artifacts.len();
let artifacts: Vec<_> = ticket
.artifacts
.iter()
.take(artifact_limit)
.map(|artifact| artifact.relative_path.display().to_string())
.collect();
json!({
"meta": {
"id": ticket.meta.id,
"title": ticket.meta.title,
"state": ticket.meta.workflow_state.as_str(),
"created_at": ticket.meta.created_at,
"updated_at": ticket.meta.updated_at,
"assignee": ticket.meta.assignee,
"readiness": ticket.meta.readiness,
"risk_flags": ticket.meta.risk_flags,
"queued_by": ticket.meta.queued_by,
"queued_at": ticket.meta.queued_at,
},
"body": truncate_text(ticket.document.body.as_str(), body_max_bytes),
"events": {
"count": event_count,
"returned": events.len(),
"truncated": event_count > events.len(),
"items": events,
},
"artifacts": {
"count": artifact_count,
"returned": artifacts.len(),
"truncated": artifact_count > artifacts.len(),
"items": artifacts,
},
"relations": ticket_relations_json(ticket),
"resolution": ticket.resolution.as_ref().map(|resolution| truncate_text(resolution.as_str(), body_max_bytes)),
})
}
fn doctor_output(report: TicketDoctorReport, limit: usize) -> TicketDoctorOutput {
let diagnostic_count = report.diagnostics.len();
let error_count = report.error_count();
let diagnostics = report
.diagnostics
.into_iter()
.take(limit)
.map(diagnostic_json)
.collect::<Vec<_>>();
TicketDoctorOutput {
ok: error_count == 0,
error_count,
diagnostic_count,
returned: diagnostics.len(),
truncated: diagnostic_count > diagnostics.len(),
diagnostics,
}
}
fn diagnostic_json(diagnostic: TicketDoctorDiagnostic) -> Value {
let severity = match diagnostic.severity {
TicketDoctorSeverity::Error => "error",
TicketDoctorSeverity::Warning => "warning",
};
json!({
"severity": severity,
"message": diagnostic.message,
"path": diagnostic.path.map(|path| path.display().to_string()),
})
}
fn truncate_inline(text: &str, max_chars: usize) -> String {
let normalized = text.split_whitespace().collect::<Vec<_>>().join(" ");
if normalized.chars().count() <= max_chars {
return normalized;
}
let marker = "...";
let take = max_chars.saturating_sub(marker.chars().count());
let mut out = normalized.chars().take(take).collect::<String>();
out.push_str(marker);
out
}
fn truncate_text(text: &str, max_bytes: usize) -> String {
if text.len() <= max_bytes {
return text.to_string();
}
let marker = format!("\n\n[truncated: {} bytes dropped]", text.len() - max_bytes);
let mut cut = max_bytes.saturating_sub(marker.len());
while cut > 0 && !text.is_char_boundary(cut) {
cut -= 1;
}
let mut out = text[..cut].to_string();
out.push_str(&marker);
out
}
fn json_output(summary: String, value: impl Serialize) -> ToolOutput {
ToolOutput {
summary,
content: Some(serde_json::to_string_pretty(&value).unwrap_or_else(|_| "{}".to_string())),
}
}
fn tool_definition<T>(name: &'static str, backend: LocalTicketBackend) -> ToolDefinition
where
T: Tool + From<LocalTicketBackend> + 'static,
{
let description = ticket_tool_description(name, backend.record_language());
Arc::new(move || {
let schema_value = input_schema(name);
let meta = ToolMeta::new(name)
.description(description.clone())
.input_schema(schema_value);
let tool: Arc<dyn Tool> = Arc::new(T::from(backend.clone()));
(meta, tool)
})
}
fn input_schema(name: &str) -> Value {
match name {
"TicketCreate" => serde_json::to_value(schemars::schema_for!(TicketCreateParams)),
"TicketList" => serde_json::to_value(schemars::schema_for!(TicketListParams)),
"TicketShow" => serde_json::to_value(schemars::schema_for!(TicketShowParams)),
"TicketComment" => serde_json::to_value(schemars::schema_for!(TicketCommentParams)),
"TicketReview" => serde_json::to_value(schemars::schema_for!(TicketReviewParams)),
"TicketIntakeReady" => serde_json::to_value(schemars::schema_for!(TicketIntakeReadyParams)),
"TicketWorkflowState" => {
serde_json::to_value(schemars::schema_for!(TicketWorkflowStateParams))
}
"TicketClose" => serde_json::to_value(schemars::schema_for!(TicketCloseParams)),
"TicketRelationRecord" => {
serde_json::to_value(schemars::schema_for!(TicketRelationRecordParams))
}
"TicketRelationQuery" => {
serde_json::to_value(schemars::schema_for!(TicketRelationQueryParams))
}
"TicketOrchestrationPlanRecord" => {
serde_json::to_value(schemars::schema_for!(TicketOrchestrationPlanRecordParams))
}
"TicketOrchestrationPlanQuery" => {
serde_json::to_value(schemars::schema_for!(TicketOrchestrationPlanQueryParams))
}
"TicketDoctor" => serde_json::to_value(schemars::schema_for!(TicketDoctorParams)),
_ => Ok(json!({})),
}
.unwrap_or_else(|_| json!({}))
}
macro_rules! impl_from_backend {
($tool:ident) => {
impl From<LocalTicketBackend> for $tool {
fn from(backend: LocalTicketBackend) -> Self {
Self { backend }
}
}
};
}
impl_from_backend!(TicketCreateTool);
impl_from_backend!(TicketListTool);
impl_from_backend!(TicketShowTool);
impl_from_backend!(TicketCommentTool);
impl_from_backend!(TicketReviewTool);
impl_from_backend!(TicketIntakeReadyTool);
impl_from_backend!(TicketWorkflowStateTool);
impl_from_backend!(TicketCloseTool);
impl_from_backend!(TicketRelationRecordTool);
impl_from_backend!(TicketRelationQueryTool);
impl_from_backend!(TicketOrchestrationPlanRecordTool);
impl_from_backend!(TicketOrchestrationPlanQueryTool);
impl_from_backend!(TicketDoctorTool);
/// Build all MVP Ticket tool definitions over one local backend root.
pub fn ticket_tools(backend: LocalTicketBackend) -> Vec<ToolDefinition> {
vec![
tool_definition::<TicketCreateTool>("TicketCreate", backend.clone()),
tool_definition::<TicketListTool>("TicketList", backend.clone()),
tool_definition::<TicketShowTool>("TicketShow", backend.clone()),
tool_definition::<TicketCommentTool>("TicketComment", backend.clone()),
tool_definition::<TicketReviewTool>("TicketReview", backend.clone()),
tool_definition::<TicketIntakeReadyTool>("TicketIntakeReady", backend.clone()),
tool_definition::<TicketWorkflowStateTool>("TicketWorkflowState", backend.clone()),
tool_definition::<TicketCloseTool>("TicketClose", backend.clone()),
tool_definition::<TicketRelationRecordTool>("TicketRelationRecord", backend.clone()),
tool_definition::<TicketRelationQueryTool>("TicketRelationQuery", backend.clone()),
tool_definition::<TicketOrchestrationPlanRecordTool>(
"TicketOrchestrationPlanRecord",
backend.clone(),
),
tool_definition::<TicketOrchestrationPlanQueryTool>(
"TicketOrchestrationPlanQuery",
backend.clone(),
),
tool_definition::<TicketDoctorTool>("TicketDoctor", backend),
]
}
#[cfg(test)]
mod tests {
use super::*;
use tempfile::TempDir;
fn backend(temp: &TempDir) -> LocalTicketBackend {
LocalTicketBackend::new(temp.path().join("tickets"))
}
fn tool(definition: ToolDefinition) -> Arc<dyn Tool> {
let (_, tool) = definition();
tool
}
fn tool_by_name(backend: LocalTicketBackend, name: &str) -> Arc<dyn Tool> {
ticket_tools(backend)
.into_iter()
.find_map(|definition| {
let (meta, tool) = definition();
(meta.name == name).then_some(tool)
})
.expect("tool exists")
}
fn tool_description_by_name(backend: LocalTicketBackend, name: &str) -> String {
ticket_tools(backend)
.into_iter()
.find_map(|definition| {
let (meta, _) = definition();
(meta.name == name).then_some(meta.description)
})
.expect("tool exists")
}
#[test]
fn ticket_tool_name_partitions_are_explicit() {
assert_eq!(
TICKET_READ_ONLY_TOOL_NAMES,
[
"TicketList",
"TicketShow",
"TicketRelationQuery",
"TicketOrchestrationPlanQuery",
"TicketDoctor"
]
);
assert_eq!(
TICKET_MUTATING_TOOL_NAMES,
[
"TicketCreate",
"TicketComment",
"TicketReview",
"TicketIntakeReady",
"TicketWorkflowState",
"TicketClose",
"TicketRelationRecord",
"TicketOrchestrationPlanRecord"
]
);
for name in TICKET_READ_ONLY_TOOL_NAMES {
assert!(TICKET_TOOL_NAMES.contains(&name));
assert!(!TICKET_MUTATING_TOOL_NAMES.contains(&name));
}
for name in TICKET_MUTATING_TOOL_NAMES {
assert!(TICKET_TOOL_NAMES.contains(&name));
assert!(!TICKET_READ_ONLY_TOOL_NAMES.contains(&name));
}
assert_eq!(
TICKET_READ_ONLY_TOOL_NAMES.len() + TICKET_MUTATING_TOOL_NAMES.len(),
TICKET_TOOL_NAMES.len()
);
}
#[test]
fn state_tool_description_explains_queued_acceptance() {
let temp = TempDir::new().unwrap();
let definition = ticket_tools(backend(&temp))
.into_iter()
.find(|definition| definition().0.name == "TicketWorkflowState")
.expect("state tool exists");
let (meta, _) = definition();
assert!(meta.description.contains("queued -> inprogress"));
assert!(meta.description.contains("implementation side effects"));
}
#[test]
fn tool_descriptions_include_configured_ticket_record_language_guidance() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp).with_record_language(Some("Japanese"));
let description = tool_description_by_name(backend, "TicketComment");
assert!(description.contains("Ticket record language: Japanese"));
assert!(description.contains("durable Ticket record and Ticket tool body text"));
assert!(description.contains("distinct from worker.language"));
assert!(description.contains("memory.language"));
assert!(description.contains("Preserve protocol literals"));
assert!(description.contains("file paths, commands, logs, identifiers"));
}
#[test]
fn tool_descriptions_omit_ticket_record_language_guidance_when_unset() {
let temp = TempDir::new().unwrap();
let description = tool_description_by_name(backend(&temp), "TicketComment");
assert!(!description.contains("Ticket record language:"));
assert!(!description.contains("worker.language"));
}
#[tokio::test]
async fn ticket_tools_create_list_show_and_doctor() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let create = tool_by_name(backend.clone(), "TicketCreate");
let list = tool_by_name(backend.clone(), "TicketList");
let show = tool_by_name(backend.clone(), "TicketShow");
let doctor = tool_by_name(backend.clone(), "TicketDoctor");
let created = create
.execute(
&json!({
"title": "Tool Created",
"body": "## Background\n\nCreated by tool.\n"
})
.to_string(),
Default::default(),
)
.await
.unwrap();
assert!(created.summary.contains("Created ticket"));
let created_json: Value = serde_json::from_str(&created.content.unwrap()).unwrap();
let id = created_json["id"].as_str().unwrap().to_string();
let created_text = created_json.to_string();
assert!(!created_text.contains("legacy_ticket"));
assert!(!created_text.contains("needs_preflight"));
assert!(!created_text.contains("action_required"));
assert!(!created_text.contains("attention_required"));
let listed = list
.execute(
&json!({ "state": "planning" }).to_string(),
Default::default(),
)
.await
.unwrap();
assert!(listed.summary.contains("Listed 1 ticket"));
let listed_content = listed.content.unwrap();
assert!(listed_content.contains("Tool Created"));
assert!(!listed_content.contains("legacy_ticket"));
assert!(!listed_content.contains("needs_preflight"));
let shown = show
.execute(
&json!({ "id": id, "event_limit": 10 }).to_string(),
Default::default(),
)
.await
.unwrap();
assert!(shown.summary.contains(&id));
let shown_content = shown.content.unwrap();
assert!(shown_content.contains("Created by tool"));
assert!(!shown_content.contains("legacy_ticket"));
assert!(!shown_content.contains("needs_preflight"));
assert!(!shown_content.contains("action_required"));
assert!(!shown_content.contains("attention_required"));
let report = doctor
.execute(&json!({}).to_string(), Default::default())
.await
.unwrap();
assert!(report.summary.contains("0 error(s)"));
}
#[tokio::test]
async fn ticket_list_tool_truncates_long_titles_and_hints() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let list = tool_by_name(backend.clone(), "TicketList");
let mut ticket = NewTicket::new(format!(
"Long Title {}",
"x".repeat(LIST_TITLE_MAX_CHARS + 40)
));
ticket.readiness = Some(format!(
"Ready after review {}",
"a".repeat(LIST_HINT_MAX_CHARS + 40)
));
backend.create(ticket).unwrap();
let listed = list
.execute(&json!({}).to_string(), Default::default())
.await
.unwrap();
let listed_json: Value = serde_json::from_str(&listed.content.unwrap()).unwrap();
let title = listed_json["tickets"][0]["title"].as_str().unwrap();
assert!(title.chars().count() <= LIST_TITLE_MAX_CHARS);
assert!(title.ends_with("..."));
let hint = listed_json["tickets"][0]["hints"][0].as_str().unwrap();
assert!(hint.chars().count() <= "readiness:".chars().count() + LIST_HINT_MAX_CHARS);
assert!(hint.ends_with("..."));
}
#[tokio::test]
async fn ticket_list_tool_default_and_max_limits_are_bounded() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let list = tool_by_name(backend.clone(), "TicketList");
for index in 0..(MAX_LIST_LIMIT + 5) {
backend
.create(NewTicket::new(format!("Ticket {index:03}")))
.unwrap();
}
let default_list = list
.execute(&json!({}).to_string(), Default::default())
.await
.unwrap();
let default_json: Value = serde_json::from_str(&default_list.content.unwrap()).unwrap();
assert_eq!(
default_json["count"].as_u64(),
Some((MAX_LIST_LIMIT + 5) as u64)
);
assert_eq!(
default_json["returned"].as_u64(),
Some(DEFAULT_LIST_LIMIT as u64)
);
assert_eq!(
default_json["limit"].as_u64(),
Some(DEFAULT_LIST_LIMIT as u64)
);
assert_eq!(default_json["truncated"].as_bool(), Some(true));
assert_eq!(
default_json["tickets"].as_array().unwrap().len(),
DEFAULT_LIST_LIMIT
);
let high_limit = list
.execute(
&json!({ "limit": MAX_LIST_LIMIT + 500 }).to_string(),
Default::default(),
)
.await
.unwrap();
let high_json: Value = serde_json::from_str(&high_limit.content.unwrap()).unwrap();
assert_eq!(high_json["returned"].as_u64(), Some(MAX_LIST_LIMIT as u64));
assert_eq!(high_json["limit"].as_u64(), Some(MAX_LIST_LIMIT as u64));
assert_eq!(high_json["truncated"].as_bool(), Some(true));
assert_eq!(
high_json["tickets"].as_array().unwrap().len(),
MAX_LIST_LIMIT
);
}
#[tokio::test]
async fn ticket_list_tool_caps_all_and_closed_default_listing() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let list = tool_by_name(backend.clone(), "TicketList");
for index in 0..(DEFAULT_LIST_LIMIT + 3) {
let mut ticket = NewTicket::new(format!("Closed Ticket {index:03}"));
ticket.workflow_state = Some(TicketWorkflowState::Closed);
backend.create(ticket).unwrap();
}
for index in 0..3 {
backend
.create(NewTicket::new(format!("Planning Ticket {index:03}")))
.unwrap();
}
let all = list
.execute(&json!({ "state": "all" }).to_string(), Default::default())
.await
.unwrap();
let all_json: Value = serde_json::from_str(&all.content.unwrap()).unwrap();
assert_eq!(all_json["state_filter"], "all");
assert_eq!(
all_json["returned"].as_u64(),
Some(DEFAULT_LIST_LIMIT as u64)
);
assert_eq!(all_json["truncated"].as_bool(), Some(true));
let closed = list
.execute(
&json!({ "state": "closed" }).to_string(),
Default::default(),
)
.await
.unwrap();
let closed_json: Value = serde_json::from_str(&closed.content.unwrap()).unwrap();
assert_eq!(closed_json["state_filter"], "closed");
assert_eq!(
closed_json["count"].as_u64(),
Some((DEFAULT_LIST_LIMIT + 3) as u64)
);
assert_eq!(
closed_json["returned"].as_u64(),
Some(DEFAULT_LIST_LIMIT as u64)
);
assert_eq!(closed_json["truncated"].as_bool(), Some(true));
}
#[tokio::test]
async fn ticket_list_tool_omits_body_thread_artifact_and_resolution_content() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let list = tool_by_name(backend.clone(), "TicketList");
let close = tool_by_name(backend.clone(), "TicketClose");
let body_secret = "ITEM_BODY_SECRET_DO_NOT_LIST";
let thread_secret = "THREAD_SECRET_DO_NOT_LIST";
let artifact_secret = "ARTIFACT_SECRET_DO_NOT_LIST";
let resolution_secret = "RESOLUTION_SECRET_DO_NOT_LIST";
let mut ticket = NewTicket::new("Leak Probe");
ticket.body = MarkdownText::new(format!("Item body {body_secret}"));
ticket.workflow_state = Some(TicketWorkflowState::Done);
let created = backend.create(ticket).unwrap();
backend
.add_event(
TicketIdOrSlug::Id(created.id.clone()),
NewTicketEvent::new(TicketEventKind::Comment, format!("Thread {thread_secret}")),
)
.unwrap();
std::fs::write(
temp.path()
.join("tickets")
.join(&created.id)
.join("artifacts")
.join("secret.txt"),
artifact_secret,
)
.unwrap();
close
.execute(
&json!({
"ticket": created.id,
"resolution": format!("Resolution {resolution_secret}")
})
.to_string(),
Default::default(),
)
.await
.unwrap();
let listed = list
.execute(
&json!({ "state": "closed" }).to_string(),
Default::default(),
)
.await
.unwrap();
let listed_content = listed.content.unwrap();
for secret in [
body_secret,
thread_secret,
artifact_secret,
resolution_secret,
] {
assert!(!listed_content.contains(secret));
}
let listed_json: Value = serde_json::from_str(&listed_content).unwrap();
let ticket = listed_json["tickets"][0].as_object().unwrap();
for forbidden_key in [
"body",
"document",
"events",
"thread",
"artifacts",
"resolution",
] {
assert!(!ticket.contains_key(forbidden_key));
}
}
#[tokio::test]
async fn ticket_relation_tools_record_query_and_show_derived_view() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let source = backend.create(NewTicket::new("Relation Source")).unwrap();
let target = backend.create(NewTicket::new("Relation Target")).unwrap();
let record = tool_by_name(backend.clone(), "TicketRelationRecord");
let query = tool_by_name(backend.clone(), "TicketRelationQuery");
let show = tool_by_name(backend.clone(), "TicketShow");
let recorded = record
.execute(
&json!({
"ticket": source.id.clone(),
"kind": "depends_on",
"target": target.id.clone(),
"note": "target first",
"author": "test"
})
.to_string(),
Default::default(),
)
.await
.unwrap();
assert!(recorded.summary.contains("Recorded ticket relation"));
let recorded_json: Value = serde_json::from_str(&recorded.content.unwrap()).unwrap();
assert_eq!(recorded_json["kind"], "depends_on");
assert_eq!(recorded_json["target"], target.id);
let queried = query
.execute(
&json!({ "ticket": target.id.clone() }).to_string(),
Default::default(),
)
.await
.unwrap();
let queried_json: Value = serde_json::from_str(&queried.content.unwrap()).unwrap();
assert_eq!(queried_json["count"], 1);
assert_eq!(queried_json["relations"][0]["ticket_id"], source.id);
let shown = show
.execute(
&json!({ "id": target.id.clone() }).to_string(),
Default::default(),
)
.await
.unwrap();
let shown_json: Value = serde_json::from_str(&shown.content.unwrap()).unwrap();
assert_eq!(
shown_json["relations"]["incoming"][0]["inverse_kind"],
"dependency_of"
);
}
#[tokio::test]
async fn ticket_tools_comment_review_state_and_close_are_doctor_clean() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let created = backend.create(NewTicket::new("Flow Tool")).unwrap();
let comment = tool_by_name(backend.clone(), "TicketComment");
let review = tool_by_name(backend.clone(), "TicketReview");
let close = tool_by_name(backend.clone(), "TicketClose");
let doctor = tool_by_name(backend.clone(), "TicketDoctor");
comment
.execute(
&json!({
"ticket": created.id.clone(),
"role": "implementation_report",
"body": "Implemented."
})
.to_string(),
Default::default(),
)
.await
.unwrap();
review
.execute(
&json!({
"ticket": created.id.clone(),
"result": "approve",
"body": "Looks good."
})
.to_string(),
Default::default(),
)
.await
.unwrap();
close
.execute(
&json!({ "ticket": created.id, "resolution": "Done via TicketClose.\n" })
.to_string(),
Default::default(),
)
.await
.unwrap();
let report = doctor
.execute(&json!({}).to_string(), Default::default())
.await
.unwrap();
assert!(report.summary.contains("0 error(s)"));
let closed = backend.show(TicketIdOrSlug::Id(created.id)).unwrap();
assert!(closed.resolution.is_some());
assert!(
closed
.events
.iter()
.any(|event| event.kind == TicketEventKind::ImplementationReport)
);
assert!(
closed
.events
.iter()
.any(|event| event.kind == TicketEventKind::Review)
);
assert!(
closed
.events
.iter()
.any(|event| event.kind == TicketEventKind::StateChanged)
);
}
#[tokio::test]
async fn ticket_workflow_tools_mark_ready_and_transition_state() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let created = backend.create(NewTicket::new("Workflow Tool")).unwrap();
let intake_ready = tool_by_name(backend.clone(), "TicketIntakeReady");
let workflow = tool_by_name(backend.clone(), "TicketWorkflowState");
intake_ready
.execute(
&json!({
"ticket": created.id.clone(),
"intake_summary": "Requirements accepted; implementation can be queued.",
"author": "intake-pod"
})
.to_string(),
Default::default(),
)
.await
.unwrap();
backend
.queue_ready(TicketIdOrSlug::Id(created.id.clone()), "panel")
.unwrap();
workflow
.execute(
&json!({
"ticket": created.id.clone(),
"from": "queued",
"to": "inprogress",
"reason": "orchestrator_started",
"body": "Orchestrator started implementation.\n",
"author": "orchestrator"
})
.to_string(),
Default::default(),
)
.await
.unwrap();
workflow
.execute(
&json!({
"ticket": created.id.clone(),
"from": "inprogress",
"to": "done",
"reason": "implementation_complete",
"body": "Implementation finished and is ready for close.\n",
"author": "orchestrator"
})
.to_string(),
Default::default(),
)
.await
.unwrap();
let record = backend.show(TicketIdOrSlug::Id(created.id)).unwrap();
assert_eq!(record.meta.workflow_state, TicketWorkflowState::Done);
assert!(
record
.events
.iter()
.any(|event| event.kind == TicketEventKind::IntakeSummary)
);
let transitions = record
.events
.iter()
.filter(|event| {
event.kind == TicketEventKind::StateChanged
&& event.state_field.as_deref() == Some("state")
})
.map(|event| (event.from.as_deref(), event.to.as_deref()))
.collect::<Vec<_>>();
assert_eq!(
transitions,
vec![
(Some("planning"), Some("ready")),
(Some("ready"), Some("queued")),
(Some("queued"), Some("inprogress")),
(Some("inprogress"), Some("done"))
]
);
}
#[tokio::test]
async fn ticket_workflow_tool_allows_return_to_planning_from_ready_and_queued() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let workflow = tool_by_name(backend.clone(), "TicketWorkflowState");
let mut ready_input = NewTicket::new("Ready Needs Planning");
ready_input.workflow_state = Some(TicketWorkflowState::Ready);
let ready = backend.create(ready_input).unwrap();
workflow
.execute(
&json!({
"ticket": ready.id,
"from": "ready",
"to": "planning",
"reason": "missing_acceptance_decision",
"body": "Missing decision: clarify acceptance criteria before queueing.\n",
"author": "orchestrator"
})
.to_string(),
Default::default(),
)
.await
.unwrap();
let ready_record = backend.show(TicketIdOrSlug::Id(ready.id)).unwrap();
assert_eq!(
ready_record.meta.workflow_state,
TicketWorkflowState::Planning
);
assert!(ready_record.events.iter().any(|event| {
event.kind == TicketEventKind::StateChanged
&& event.from.as_deref() == Some("ready")
&& event.to.as_deref() == Some("planning")
&& event.reason.as_deref() == Some("missing_acceptance_decision")
}));
let mut queued_input = NewTicket::new("Queued Needs Planning");
queued_input.workflow_state = Some(TicketWorkflowState::Queued);
let queued = backend.create(queued_input).unwrap();
workflow
.execute(
&json!({
"ticket": queued.id,
"from": "queued",
"to": "planning",
"reason": "missing_authority_decision",
"body": "Missing decision: define authority boundary before implementation side effects.\n",
"author": "orchestrator"
})
.to_string(),
Default::default(),
)
.await
.unwrap();
let queued_record = backend.show(TicketIdOrSlug::Id(queued.id)).unwrap();
assert_eq!(
queued_record.meta.workflow_state,
TicketWorkflowState::Planning
);
assert!(queued_record.events.iter().any(|event| {
event.kind == TicketEventKind::StateChanged
&& event.from.as_deref() == Some("queued")
&& event.to.as_deref() == Some("planning")
&& event.reason.as_deref() == Some("missing_authority_decision")
}));
}
#[tokio::test]
async fn ticket_workflow_tool_rejects_stale_transition_without_state_move() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let created = backend
.create(NewTicket::new("Stale Workflow Tool"))
.unwrap();
let workflow = tool_by_name(backend.clone(), "TicketWorkflowState");
let error = workflow
.execute(
&json!({
"ticket": created.id.clone(),
"from": "queued",
"to": "inprogress",
"reason": "orchestrator_started",
"body": "Should not apply.\n"
})
.to_string(),
Default::default(),
)
.await
.unwrap_err();
assert!(error.to_string().contains("state changed concurrently"));
let record = backend.show(TicketIdOrSlug::Id(created.id)).unwrap();
assert_eq!(record.meta.workflow_state, TicketWorkflowState::Planning);
assert!(!record.events.iter().any(|event| {
event.kind == TicketEventKind::StateChanged
&& event.state_field.as_deref() == Some("state")
}));
}
#[tokio::test]
async fn ticket_workflow_tool_rejects_disallowed_transition_graph_edges() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let workflow = tool_by_name(backend.clone(), "TicketWorkflowState");
let mut ready_input = NewTicket::new("Ready Bypass");
ready_input.workflow_state = Some(TicketWorkflowState::Ready);
let ready = backend.create(ready_input).unwrap();
let ready_error = workflow
.execute(
&json!({
"ticket": ready.id,
"from": "ready",
"to": "inprogress",
"reason": "bypass_queue",
"body": "Should not bypass Queue.\n"
})
.to_string(),
Default::default(),
)
.await
.unwrap_err();
assert!(ready_error.to_string().contains("not allowed"));
let mut done_input = NewTicket::new("Backward Bypass");
done_input.workflow_state = Some(TicketWorkflowState::Done);
let done = backend.create(done_input).unwrap();
let backward_error = workflow
.execute(
&json!({
"ticket": done.id,
"from": "done",
"to": "planning",
"reason": "backwards",
"body": "Should not move backwards.\n"
})
.to_string(),
Default::default(),
)
.await
.unwrap_err();
assert!(backward_error.to_string().contains("not allowed"));
let mut queued_input = NewTicket::new("Skip Bypass");
queued_input.workflow_state = Some(TicketWorkflowState::Queued);
let queued = backend.create(queued_input).unwrap();
let skip_error = workflow
.execute(
&json!({
"ticket": queued.id,
"from": "queued",
"to": "done",
"reason": "skip_inprogress",
"body": "Should not skip inprogress.\n"
})
.to_string(),
Default::default(),
)
.await
.unwrap_err();
assert!(skip_error.to_string().contains("not allowed"));
}
#[tokio::test]
async fn ticket_intake_ready_tool_rejects_non_planning_ticket() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let mut input = NewTicket::new("Already Ready");
input.workflow_state = Some(TicketWorkflowState::Ready);
let created = backend.create(input).unwrap();
let intake_ready = tool_by_name(backend.clone(), "TicketIntakeReady");
let error = intake_ready
.execute(
&json!({
"ticket": created.id.clone(),
"intake_summary": "Should not rewrite ready ticket."
})
.to_string(),
Default::default(),
)
.await
.unwrap_err();
assert!(error.to_string().contains("state changed concurrently"));
let record = backend.show(TicketIdOrSlug::Id(created.id)).unwrap();
assert_eq!(record.meta.workflow_state, TicketWorkflowState::Ready);
assert!(!record.events.iter().any(|event| {
event.kind == TicketEventKind::StateChanged
&& event.state_field.as_deref() == Some("state")
}));
}
#[tokio::test]
async fn ticket_orchestration_plan_tools_record_and_query_without_state_changes() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let first = backend.create(NewTicket::new("Plan Tool First")).unwrap();
let second = backend.create(NewTicket::new("Plan Tool Second")).unwrap();
let record = tool_by_name(backend.clone(), "TicketOrchestrationPlanRecord");
let query = tool_by_name(backend.clone(), "TicketOrchestrationPlanQuery");
let recorded = record
.execute(
&json!({
"ticket": first.id.clone(),
"kind": "blocked_by",
"related_ticket": second.id.clone(),
"note": "Wait for the second Ticket's API boundary decision.",
"author": "orchestrator"
})
.to_string(),
Default::default(),
)
.await
.unwrap();
assert!(
recorded
.summary
.contains("Recorded orchestration plan blocked_by")
);
let found = query
.execute(
&json!({
"ticket": first.id,
"relation_kind": "blocked_by"
})
.to_string(),
Default::default(),
)
.await
.unwrap();
let found_json: Value = serde_json::from_str(&found.content.unwrap()).unwrap();
assert_eq!(found_json["count"], 1);
assert_eq!(found_json["records"][0]["kind"], "blocked_by");
assert_eq!(found_json["records"][0]["related_ticket"], second.id);
let current = backend.show(TicketIdOrSlug::Id(first.id)).unwrap();
assert_eq!(current.meta.workflow_state, TicketWorkflowState::Planning);
}
#[tokio::test]
async fn ticket_show_requires_exactly_one_identifier() {
let temp = TempDir::new().unwrap();
let show = tool_by_name(backend(&temp), "TicketShow");
let error = show
.execute(
&json!({ "id": "a", "query": "b" }).to_string(),
Default::default(),
)
.await
.unwrap_err();
assert!(matches!(error, ToolError::InvalidArgument(_)));
}
#[tokio::test]
async fn ticket_create_uses_opaque_id_under_backend_root() {
let temp = TempDir::new().unwrap();
let backend = backend(&temp);
let create = tool_by_name(backend.clone(), "TicketCreate");
let output = create
.execute(
&json!({ "title": "Escape" }).to_string(),
Default::default(),
)
.await
.unwrap();
let value: Value = serde_json::from_str(&output.content.unwrap()).unwrap();
let id = value["id"].as_str().unwrap();
assert!(!id.contains("escape"));
assert!(!temp.path().join("escape").exists());
assert!(temp.path().join("tickets").join(id).is_dir());
assert_eq!(backend.list(crate::TicketFilter::all()).unwrap().len(), 1);
}
#[test]
fn ticket_tool_definitions_have_expected_names_and_schemas() {
let temp = TempDir::new().unwrap();
let tools = ticket_tools(backend(&temp));
let create_schema = tools
.iter()
.map(|definition| definition().0)
.find(|meta| meta.name == "TicketCreate")
.unwrap()
.input_schema
.to_string();
assert!(!create_schema.contains("legacy_ticket"));
assert!(!create_schema.contains("needs_preflight"));
assert!(!create_schema.contains("action_required"));
assert!(!create_schema.contains("attention_required"));
let plan_record_schema = tools
.iter()
.map(|definition| definition().0)
.find(|meta| meta.name == "TicketOrchestrationPlanRecord")
.unwrap()
.input_schema
.to_string();
assert!(plan_record_schema.contains("accepted_plan"));
assert!(plan_record_schema.contains("related_ticket"));
let plan_query_schema = tools
.iter()
.map(|definition| definition().0)
.find(|meta| meta.name == "TicketOrchestrationPlanQuery")
.unwrap()
.input_schema
.to_string();
assert!(plan_query_schema.contains("relation_kind"));
let names = tools
.into_iter()
.map(|definition| definition().0)
.map(|meta| {
assert_eq!(meta.input_schema["type"], "object");
meta.name
})
.collect::<Vec<_>>();
assert_eq!(names, TICKET_TOOL_NAMES);
}
#[test]
fn individual_tool_definition_factory_is_callable() {
let temp = TempDir::new().unwrap();
let create = tool(tool_definition::<TicketCreateTool>(
"TicketCreate",
backend(&temp),
));
let _ = create;
}
}
View Git Blame Copy Permalink