speccoder_runtime/substrate/

host.rs

//! `speccoder.skill.run`: an installed Agent Skill, hosted.
//!
//! The skill's `SKILL.md` body is the instruction; speccoder's governed tool
//! loop runs it with the planning policy (Spec Kit's artifacts and scripts;
//! anything else needs approval) and an `ask_person` tool for clarifying
//! questions. Everything it decides by is in the journaled input.

use crate::format::Wording;
use agentplane::prelude::*;
use serde_json::{Value, json};

use super::attempt::{Asker, LoopSpec, ask_person, tool_loop};
use crate::tools::policy::Policy;

/// The capability the skill provides.
pub const CAPABILITY: &str = "speccoder.skill.run";

/// What the host tells the model, before the skill itself.
pub fn policy(w: &Wording) -> String {
    format!(
        "You are speccoder, running the Agent Skill below for a person in their {product} \
project. Follow the skill's instructions. You can read the project, {authoring} with run_command \
(argv, no shell). Do not write source code — implementation is a separate step that \
speccoder runs with tests; other writes need a person's approval. When the skill says to \
ask the user, call ask_person with one question at a time; if nobody can answer, follow \
the skill's rule for unanswered questions. Skip steps about extension hooks, other \
agents' slash commands, committing, branching or pushing unless {authoring_tool} does it. \
Finish with the requested structured report.",
        product = w.product,
        authoring = w.authoring,
        authoring_tool = w.authoring_tool,
    )
}

/// What the host tells the model when it explores (`spec explore`).
pub fn explore_policy(w: &Wording) -> String {
    format!(
        "You are speccoder, exploring an idea with a person in their {product} project before any spec exists. You can read the project; you cannot write anything — the person chooses an approach afterwards, speccoder writes the brief, and *Start spec* writes the spec. When you need the person's view, call ask_person with one question at a time; if nobody can answer, list the question under open questions and go on. Look at how the project works today, then end with the structured report: approaches that really differ, each with what it gives up and what could go wrong, the constraints any of them must respect, and the questions still open. Your report is a proposal; you do not choose.",
        product = w.product,
    )
}

/// The instruction `speccoder.explore` runs when the format has no
/// exploration skill of its own.
pub const EXPLORE_FALLBACK: &str = "Explore the idea below with the person. Read what the project already has that it touches (code, specs, docs). Ask the person at most a few questions, one at a time, only where the answer changes which approach fits. Then propose at least three approaches that differ in kind, not degree — e.g. the smallest change, the cleanest design, a different way altogether — each with its trade-offs and its risks. Name the constraints any approach must respect and the questions still open. Do not choose: the person does.";

/// The closing report's schema when exploring. Strict decoding takes no
/// item counts, so how many approaches a report owes is checked after the
/// run (`explore::validate_fallback`), never trusted to the schema.
#[must_use]
pub fn explore_schema() -> Value {
    let strings = json!({ "type": "array", "items": { "type": "string" } });
    let some = strings.clone();
    json!({
        "type": "object",
        "properties": {
            "summary": { "type": "string" },
            "status": { "type": "string", "enum": ["done", "incomplete"] },
            "approaches": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "title": { "type": "string" },
                        "summary": { "type": "string" },
                        "tradeoffs": some,
                        "risks": some,
                    },
                    "required": ["title", "summary", "tradeoffs", "risks"],
                    "additionalProperties": false,
                },
            },
            "constraints": strings,
            "open_questions": strings,
        },
        "required": ["summary", "status", "approaches", "constraints", "open_questions"],
        "additionalProperties": false,
    })
}

/// The closing report's schema.
#[must_use]
pub fn schema() -> Value {
    let strings = json!({ "type": "array", "items": { "type": "string" } });
    json!({
        "type": "object",
        "properties": {
            "summary": { "type": "string" },
            "status": { "type": "string", "enum": ["done", "incomplete"] },
            "files_written": strings,
            "questions": strings,
        },
        "required": ["summary", "status", "files_written", "questions"],
        "additionalProperties": false,
    })
}

/// The run input.
#[must_use]
pub fn input(skill: &str, instruction: &str, root: &str, limits: (u32, u32), ask: bool) -> Value {
    json!({
        "skill": skill,
        "instruction": instruction,
        // With a person there, a question waits on a task they answer
        // inline; without one the skill writes [NEEDS CLARIFICATION].
        "settings": { "max_turns": limits.0, "max_tool_calls": limits.1, "asks": if ask { "tasks" } else { "stop" }, "root": root },
    })
}

/// The coded skill.
#[derive(Debug)]
pub struct Host {
    /// Prompt dialect.
    pub style: super::model_config::PromptStyle,
    /// Where live progress goes.
    pub progress: Option<std::sync::Arc<dyn crate::progress::Progress>>,
    /// The project's spec format.
    pub format: &'static dyn crate::format::Adapter,
    /// The sandbox, as a person asked about a command is told; live only.
    pub present: crate::approvals::PresentContext,
}

#[async_trait]
impl Skill for Host {
    fn descriptor(&self) -> SkillDescriptor {
        SkillDescriptor::new("speccoder.skill.run").provides(CAPABILITY)
    }

    async fn invoke(
        &self,
        cx: &mut StepCtx<'_>,
        input: Tainted<Value>,
    ) -> Result<Outcome, SkillError> {
        let style = self.style;
        let settings = input.peek()["settings"].clone();
        let skill = input.peek()["skill"]
            .as_str()
            .unwrap_or_default()
            .to_owned();
        let limit = |key: &str, default: u32| {
            settings[key]
                .as_u64()
                .map_or(default, |n| u32::try_from(n).unwrap_or(u32::MAX))
        };
        // Built from labelled parts, so `/system` stays speccoder's trusted
        // instruction after the conversation has read tool output.
        let label = input.label().clone();
        let exploring = settings["mode"] == "explore";
        let prompt = super::provenance::labelled_prompt(
            {
                let input = input.peek();
                let text = format!(
                    "# Skill `{}`\n\n{}",
                    input["skill"].as_str().unwrap_or_default(),
                    input["instruction"].as_str().unwrap_or_default()
                );
                let system = if exploring {
                    explore_policy(self.format.wording())
                } else {
                    policy(self.format.wording())
                };
                match style {
                    super::model_config::PromptStyle::OpenAi => json!({
                        "system": system,
                        "input": [{ "role": "user", "content": [{ "type": "input_text", "text": text }] }],
                    }),
                    super::model_config::PromptStyle::Anthropic
                    | super::model_config::PromptStyle::Chat => json!({
                        "system": system,
                        "messages": [{ "role": "user", "content": [{ "type": "text", "text": text }] }],
                    }),
                    super::model_config::PromptStyle::Parts { .. } => json!({
                        "system": system,
                        "input": [{ "type": "text", "text": text }],
                    }),
                }
            },
            &label,
        );
        let mut tools = crate::tools::declarations();
        tools.push(ask_person());
        let ask = Asker::from_settings(
            &settings,
            format!("skill/{skill}"),
            skill.clone(),
            self.present.clone(),
        );
        tool_loop(
            cx,
            &prompt,
            LoopSpec {
                // The account is shown for attempts; these read as documents.
                reasoning: false,
                tools,
                // A format's own bug step writes only its bug's directory;
                // exploring writes nothing but the format's own artifacts.
                policy: if exploring {
                    let planning = self.format.planning();
                    Policy::new(&[], &[]).rules(self.format.rules()).exploring(
                        crate::tools::policy::Exploring {
                            paths: planning.explore_paths,
                            commands: planning.explore_commands,
                        },
                    )
                } else {
                    Policy::new(&[], &[])
                        .rules(if settings["scope"] == "bug" {
                            self.format
                                .bug_step()
                                .map_or(self.format.rules(), |s| s.rules)
                        } else {
                            self.format.rules()
                        })
                        .authoring()
                },
                max_turns: limit("max_turns", 30).max(1),
                max_tool_calls: limit("max_tool_calls", 100),
                schema: Some(if exploring {
                    explore_schema()
                } else {
                    schema()
                }),
                max_tokens: None,
                reads: None,
                halt: None,
                routes: Vec::new(),
                root: settings["root"].as_str().map(str::to_owned),
                frozen_additions: false,
                ask,
                run_approved: Vec::new(),
                once: Vec::new(),
                run: None,
                asking: super::attempt::Asking::default(),
                parts: Vec::new(),
                mcp_digests: std::collections::BTreeMap::new(),
                stop: super::attempt::StopGate::default(),
                observer: self.progress.clone().map(|p| (skill.clone(), p)),
                finish: |report| {
                    if report["status"] == "incomplete" {
                        "incomplete"
                    } else {
                        "completed"
                    }
                },
            },
        )
        .await
    }
}