Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

42.6 KB
Raw Blame
//! Public local-trust Worker contracts.
//!
//! Requests are scoped to the local daemon instance. A workspace path and permission policy are
//! execution inputs, never caller identity or durable ambient authority.

use hiroute_domain::delegation::{
    MAX_RUN_DURATION_MS, MAX_WORKER_CONCURRENCY, RunStateV1, WorkerExecutionIntentV1,
    WorkerHarnessV1, WorkerNetworkV1, WorkerPermissionPolicyV1, WorkerToolV1, WorkspaceAccessV1,
};
use hiroute_domain::{
    AgentPlanId, CHANGE_SPEC_SCHEMA_V1, CanonicalDigest, ChangeSpecV1, RevisionSetV1,
    WorkerDependencySelectionChangeV1, WorkerDependencySelectionRecordV1,
};
use serde::{Deserialize, Serialize};

use crate::{
    DEFAULT_DELEGATION_LIST_LIMIT, DelegationSubmissionOperationV1, DelegationTaskInputV1,
    MAX_DELEGATION_INPUT_BYTES, MAX_DELEGATION_LIST_LIMIT, MAX_DELEGATION_RESULT_BYTES,
};

pub const WORKER_EXEC_SCHEMA_V1: &str = "hiroute.worker-exec-request/v1";
pub const WORKER_CONTINUE_SCHEMA_V1: &str = "hiroute.worker-continue-request/v1";
pub const WORKER_COMMAND_DATA_SCHEMA_V1: &str = "hiroute.worker-command-data/v1";
pub const WORKER_EXECUTOR_AVAILABILITY_OPERATION_V1: &str = "WorkerExecutorAvailability";
pub const WORKER_EXECUTOR_AVAILABILITY_SCHEMA_V1: &str =
    "hiroute.worker-executor-availability-list/v1";
pub const WORKER_SETTINGS_GET_OPERATION_V1: &str = "WorkerSettingsGet";
pub const WORKER_SETTINGS_SET_OPERATION_V1: &str = "WorkerSettingsSet";
pub const WORKER_SETTINGS_SCHEMA_V1: &str = "hiroute.worker-settings/v1";
pub const WORKER_DEPENDENCIES_DISCOVER_OPERATION_V1: &str = "WorkerDependenciesDiscover";
pub const WORKER_DEPENDENCIES_SELECT_OPERATION_V1: &str = "SelectWorkerDependencies";
pub const WORKER_DEPENDENCIES_VIEW_SCHEMA_V1: &str = "hiroute.worker-dependencies-view/v1";
pub const DEFAULT_WORKER_WAIT_SECS: u32 = 30;
pub const MAX_WORKER_WAIT_SECS: u32 = 30;
pub const DEFAULT_WORKER_RUN_SECS: u32 = 3_600;
pub const MAX_WORKER_RUN_SECS: u32 = (MAX_RUN_DURATION_MS / 1_000) as u32;
pub const DEFAULT_WORKER_READ_BYTES: u32 = 16 * 1024;
pub const MAX_WORKER_READ_BYTES: u32 = 32 * 1024;
pub const MAX_WORKER_CURSOR_BYTES: usize = 4 * 1024;
pub const MAX_WORKER_TITLE_INPUT_BYTES: usize = 4 * 1024;
pub const MAX_WORKER_TITLE_BYTES: usize = 1024;
pub const UNNAMED_WORKER_TASK_TITLE: &str = "未命名任务";

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerSettingsV1 {
    pub schema: String,
    pub max_concurrent: u16,
}

impl WorkerSettingsV1 {
    pub fn new(max_concurrent: u16) -> Self {
        Self {
            schema: WORKER_SETTINGS_SCHEMA_V1.to_owned(),
            max_concurrent,
        }
    }

    pub fn valid(&self) -> bool {
        self.schema == WORKER_SETTINGS_SCHEMA_V1
            && (1..=MAX_WORKER_CONCURRENCY).contains(&self.max_concurrent)
    }
}

#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerDependenciesDiscoverRequestV1 {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub harness: Option<WorkerHarnessV1>,
}

impl WorkerDependenciesDiscoverRequestV1 {
    pub fn valid(&self) -> bool {
        true
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerDependenciesSelectRequestV1 {
    pub harness: WorkerHarnessV1,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub adapter_path: Option<String>,
    pub cli_path: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub node_path: Option<String>,
    pub expected_selection_revision: u64,
}

impl WorkerDependenciesSelectRequestV1 {
    pub fn valid(&self) -> bool {
        hiroute_domain::delegation::WorkerLaunchFormV1::validate(
            self.harness,
            self.adapter_path.as_deref(),
            &self.cli_path,
            self.node_path.as_deref(),
        )
        .is_ok()
    }
}

/// Pure, shared preparation for the protected dependency-selection Operation. Callers must pass
/// paths already normalized by the native metadata validator; discovery candidates are
/// intentionally not part of the digest or CAS authority.
#[derive(Clone, Debug, PartialEq)]
pub struct WorkerDependencySelectionPlanV1 {
    pub spec: ChangeSpecV1,
    pub expected_revisions: RevisionSetV1,
    pub accept_digest: CanonicalDigest,
    pub idempotency_key: String,
    pub change: WorkerDependencySelectionChangeV1,
}

pub fn plan_worker_dependency_selection(
    request: &WorkerDependenciesSelectRequestV1,
) -> Option<WorkerDependencySelectionPlanV1> {
    if !request.valid() {
        return None;
    }
    let selection = WorkerDependencySelectionRecordV1::new(
        request.harness,
        request.adapter_path.clone(),
        request.cli_path.clone(),
        request.node_path.clone(),
    )
    .ok()?;
    let change =
        WorkerDependencySelectionChangeV1::new(request.expected_selection_revision, selection)
            .ok()?;
    let harness = match request.harness {
        WorkerHarnessV1::CodexCli => "codex_cli",
        WorkerHarnessV1::ClaudeCode => "claude_code",
        WorkerHarnessV1::QoderCli => "qoder_cli",
        WorkerHarnessV1::Pi => "pi",
        WorkerHarnessV1::OpenCode => "opencode",
        WorkerHarnessV1::DeepseekHarness => "deepseek_harness",
    };
    let spec = ChangeSpecV1 {
        schema_version: CHANGE_SPEC_SCHEMA_V1,
        command_id: "worker.dependencies.select".to_owned(),
        resource_id: Some(format!("worker-dependency-selection/{harness}")),
        desired_state: serde_json::to_value(&change.after_selection).ok()?,
    };
    let expected_revisions = RevisionSetV1 {
        target: request.expected_selection_revision,
        dependencies: std::collections::BTreeMap::new(),
    };
    let accept_digest = spec.canonical_digest(&expected_revisions).ok()?;
    let request_digest = CanonicalDigest::of(&serde_json::json!({
        "schema": "worker-dependency-selection-request/v1",
        "request": request,
    }))
    .ok()?;
    let idempotency_key = format!(
        "worker-dependency-selection:{}",
        &request_digest.as_str()["sha256:".len()..]
    );
    Some(WorkerDependencySelectionPlanV1 {
        spec,
        expected_revisions,
        accept_digest,
        idempotency_key,
        change,
    })
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerDependencyComponentV1 {
    Cli,
    Adapter,
    Node,
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerDependencyCandidateSourceV1 {
    Selected,
    Path,
    Common,
    NpmGlobal,
    NpxCache,
    Manual,
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerDependencyCandidateStateV1 {
    Found,
    Missing,
    Invalid,
    Unavailable,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerDependencyCandidateV1 {
    pub harness: WorkerHarnessV1,
    pub component: WorkerDependencyComponentV1,
    pub path: String,
    pub source: WorkerDependencyCandidateSourceV1,
    pub state: WorkerDependencyCandidateStateV1,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reason_code: Option<String>,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerDependencySelectionRevisionV1 {
    pub harness: WorkerHarnessV1,
    pub revision: u64,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerDependencySelectionV1 {
    pub harness: WorkerHarnessV1,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub adapter_path: Option<String>,
    pub cli_path: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub node_path: Option<String>,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerDependencyInstallHintV1 {
    pub harness: WorkerHarnessV1,
    pub component: WorkerDependencyComponentV1,
    pub platform: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub command: Option<String>,
    pub reason_code: String,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerDependenciesViewV1 {
    pub schema: String,
    pub selection_revisions: Vec<WorkerDependencySelectionRevisionV1>,
    pub candidates: Vec<WorkerDependencyCandidateV1>,
    pub selected: Vec<WorkerDependencySelectionV1>,
    pub install_hints: Vec<WorkerDependencyInstallHintV1>,
}

impl WorkerDependenciesViewV1 {
    pub fn valid(&self) -> bool {
        use std::collections::BTreeSet;
        let revisions = self
            .selection_revisions
            .iter()
            .map(|entry| entry.harness)
            .collect::<BTreeSet<_>>();
        let selections = self
            .selected
            .iter()
            .map(|entry| entry.harness)
            .collect::<BTreeSet<_>>();
        self.schema == WORKER_DEPENDENCIES_VIEW_SCHEMA_V1
            && !self.selection_revisions.is_empty()
            && self.selection_revisions.len() <= 6
            && revisions.len() == self.selection_revisions.len()
            && selections.len() == self.selected.len()
            && self.selected.iter().all(|selection| {
                hiroute_domain::delegation::WorkerLaunchFormV1::validate(
                    selection.harness,
                    selection.adapter_path.as_deref(),
                    &selection.cli_path,
                    selection.node_path.as_deref(),
                )
                .is_ok()
            })
            && self.candidates.len() <= 6 * 64
            && self.candidates.iter().all(|candidate| {
                absolute_path(&candidate.path)
                    && candidate
                        .reason_code
                        .as_ref()
                        .is_none_or(|reason| reference(reason))
            })
            && self.install_hints.len() <= 32
            && self.install_hints.iter().all(|hint| {
                reference(&hint.platform)
                    && reference(&hint.reason_code)
                    && hint.command.as_ref().is_none_or(|command| {
                        !command.is_empty()
                            && command.len() <= 4096
                            && !command.contains(char::is_control)
                    })
            })
    }
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerSubmissionStateV1 {
    Accepted,
    Unknown,
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerExecutorAvailabilityStateV1 {
    Ready,
    Unavailable,
    Unknown,
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerExecutorAvailabilityReasonV1 {
    RuntimeUnavailable,
    InstallationNotConfigured,
    CapabilityUnverified,
    ArtifactUnavailable,
    ResumeUnavailable,
    RestrictedPolicyUnverified,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerExecutorCapabilityAvailabilityV1 {
    pub state: WorkerExecutorAvailabilityStateV1,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reason: Option<WorkerExecutorAvailabilityReasonV1>,
}

impl WorkerExecutorCapabilityAvailabilityV1 {
    pub fn valid(&self) -> bool {
        matches!(
            (self.state, self.reason),
            (WorkerExecutorAvailabilityStateV1::Ready, None)
                | (
                    WorkerExecutorAvailabilityStateV1::Unavailable
                        | WorkerExecutorAvailabilityStateV1::Unknown,
                    Some(_)
                )
        )
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerExecutorAvailabilityV1 {
    pub harness: WorkerHarnessV1,
    pub state: WorkerExecutorAvailabilityStateV1,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reason: Option<WorkerExecutorAvailabilityReasonV1>,
    pub start_approve_all: WorkerExecutorCapabilityAvailabilityV1,
    pub cancel: WorkerExecutorCapabilityAvailabilityV1,
    pub continue_session: WorkerExecutorCapabilityAvailabilityV1,
    pub restricted_policy: WorkerExecutorCapabilityAvailabilityV1,
}

impl WorkerExecutorAvailabilityV1 {
    pub fn valid(&self) -> bool {
        let overall = WorkerExecutorCapabilityAvailabilityV1 {
            state: self.state,
            reason: self.reason,
        };
        overall.valid()
            && self.start_approve_all.valid()
            && self.cancel.valid()
            && self.continue_session.valid()
            && self.restricted_policy.valid()
            && (self.state != WorkerExecutorAvailabilityStateV1::Ready
                || (self.start_approve_all.state == WorkerExecutorAvailabilityStateV1::Ready
                    && self.cancel.state == WorkerExecutorAvailabilityStateV1::Ready))
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerExecutorAvailabilityListV1 {
    pub schema: String,
    pub executors: Vec<WorkerExecutorAvailabilityV1>,
}

impl WorkerExecutorAvailabilityListV1 {
    pub fn valid(&self) -> bool {
        self.schema == WORKER_EXECUTOR_AVAILABILITY_SCHEMA_V1
            && self.executors.len() == 6
            && self.executors[0].harness == WorkerHarnessV1::CodexCli
            && self.executors[1].harness == WorkerHarnessV1::ClaudeCode
            && self.executors[2].harness == WorkerHarnessV1::QoderCli
            && self.executors[3].harness == WorkerHarnessV1::Pi
            && self.executors[4].harness == WorkerHarnessV1::DeepseekHarness
            && self.executors[5].harness == WorkerHarnessV1::OpenCode
            && self
                .executors
                .iter()
                .all(WorkerExecutorAvailabilityV1::valid)
    }
}

#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerPlansRequestV1 {}

impl WorkerPlansRequestV1 {
    pub fn valid(&self) -> bool {
        true
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerListRequestV1 {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cursor: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limit: Option<u16>,
}

impl WorkerListRequestV1 {
    pub fn valid(&self) -> bool {
        self.title
            .as_ref()
            .is_none_or(|title| normalize_worker_title(title).is_ok())
            && self
                .cursor
                .as_ref()
                .is_none_or(|cursor| valid_opaque_cursor(cursor))
            && self
                .limit
                .is_none_or(|limit| limit != 0 && limit <= MAX_DELEGATION_LIST_LIMIT)
    }

    pub fn effective_limit(&self) -> u16 {
        self.limit.unwrap_or(DEFAULT_DELEGATION_LIST_LIMIT)
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerExecRequestV1 {
    pub schema: String,
    pub plan_id: AgentPlanId,
    pub cwd: String,
    #[serde(default)]
    pub permission_policy: WorkerPermissionPolicyV1,
    pub run_timeout_secs: u32,
    pub input: DelegationTaskInputV1,
    pub submission_key: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub parent_task_ref: Option<String>,
}

impl WorkerExecRequestV1 {
    pub fn valid(&self) -> bool {
        self.schema == WORKER_EXEC_SCHEMA_V1
            && AgentPlanId::parse(self.plan_id.as_str()).is_ok()
            && absolute_path(&self.cwd)
            && valid_run_timeout(self.run_timeout_secs)
            && self.input.valid()
            && self.input.prompt().len() <= MAX_DELEGATION_INPUT_BYTES
            && reference(&self.submission_key)
            && self
                .title
                .as_ref()
                .is_none_or(|title| normalize_worker_title(title).is_ok())
            && self
                .parent_task_ref
                .as_ref()
                .is_none_or(|value| reference(value))
    }

    pub fn execution(&self, root_identity: String) -> WorkerExecutionIntentV1 {
        WorkerExecutionIntentV1 {
            root_identity,
            access: WorkspaceAccessV1::TrustedNative,
            tools: vec![WorkerToolV1::Read, WorkerToolV1::Edit, WorkerToolV1::Shell],
            network: WorkerNetworkV1::Allowed,
            duration_ms: u64::from(self.run_timeout_secs) * 1_000,
            delegation_depth: 1,
        }
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerStatusRequestV1 {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub task_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub submission_key: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub submission_operation: Option<DelegationSubmissionOperationV1>,
}

impl WorkerStatusRequestV1 {
    pub fn valid(&self) -> bool {
        match (
            &self.task_id,
            &self.run_id,
            &self.submission_key,
            self.submission_operation,
        ) {
            (Some(task), run, None, None) => {
                reference(task) && run.as_ref().is_none_or(|run| reference(run))
            }
            (None, Some(run), None, None) => reference(run),
            (None, None, Some(key), Some(_)) => reference(key),
            _ => false,
        }
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerWaitRequestV1 {
    pub run_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub after_revision: Option<u64>,
    pub wait_timeout_secs: u32,
}

impl WorkerWaitRequestV1 {
    pub fn valid(&self) -> bool {
        reference(&self.run_id) && (1..=MAX_WORKER_WAIT_SECS).contains(&self.wait_timeout_secs)
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerResultRequestV1 {
    pub run_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub offset: Option<u32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_bytes: Option<u32>,
}

impl WorkerResultRequestV1 {
    pub fn valid(&self) -> bool {
        reference(&self.run_id)
            && self
                .max_bytes
                .is_none_or(|size| size != 0 && size <= MAX_DELEGATION_RESULT_BYTES)
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerCancelRequestV1 {
    pub run_id: String,
    pub idempotency_key: String,
    #[serde(default)]
    pub reason: String,
}

impl WorkerCancelRequestV1 {
    pub fn valid(&self) -> bool {
        reference(&self.run_id)
            && hiroute_domain::validate_idempotency_key(&self.idempotency_key).is_ok()
            && (self.reason.is_empty() || reference(&self.reason))
    }
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerContinueRequestV1 {
    pub schema: String,
    pub task_id: String,
    pub expected_latest_run_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cwd: Option<String>,
    #[serde(default)]
    pub permission_policy: WorkerPermissionPolicyV1,
    pub run_timeout_secs: u32,
    pub input: DelegationTaskInputV1,
    pub submission_key: String,
}

impl WorkerContinueRequestV1 {
    pub fn valid(&self) -> bool {
        self.schema == WORKER_CONTINUE_SCHEMA_V1
            && reference(&self.task_id)
            && reference(&self.expected_latest_run_id)
            && self.cwd.as_ref().is_none_or(|path| absolute_path(path))
            && valid_run_timeout(self.run_timeout_secs)
            && self.input.valid()
            && self.input.prompt().len() <= MAX_DELEGATION_INPUT_BYTES
            && reference(&self.submission_key)
    }

    pub fn execution(&self, root_identity: String) -> WorkerExecutionIntentV1 {
        WorkerExecutionIntentV1 {
            root_identity,
            access: WorkspaceAccessV1::TrustedNative,
            tools: vec![WorkerToolV1::Read, WorkerToolV1::Edit, WorkerToolV1::Shell],
            network: WorkerNetworkV1::Allowed,
            duration_ms: u64::from(self.run_timeout_secs) * 1_000,
            delegation_depth: 1,
        }
    }
}

/// CLI presentation data kept inside the normal machine-envelope/v2 transport. Pending is a
/// successful query/acceptance state, not a fabricated completed result.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerCommandDataV1 {
    pub schema: String,
    pub operation: String,
    pub submission_state: WorkerSubmissionStateV1,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub submission_key: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub task_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run_state: Option<RunStateV1>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    #[serde(default)]
    pub replayed: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub result: Option<String>,
    #[serde(default)]
    pub timed_out: bool,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerReadRequestV1 {
    pub run_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cursor: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_bytes: Option<u32>,
}

impl WorkerReadRequestV1 {
    pub fn valid(&self) -> bool {
        reference(&self.run_id)
            && self
                .cursor
                .as_ref()
                .is_none_or(|cursor| valid_opaque_cursor(cursor))
            && self
                .max_bytes
                .is_none_or(|size| (1..=MAX_WORKER_READ_BYTES).contains(&size))
    }

    pub fn effective_max_bytes(&self) -> u32 {
        self.max_bytes.unwrap_or(DEFAULT_WORKER_READ_BYTES)
    }
}

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum WorkerReadContentStateV1 {
    Pending,
    Available,
    Deleted,
    Expired,
}

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct WorkerReadDataV1 {
    pub task_id: String,
    pub run_id: String,
    pub run_state: RunStateV1,
    pub state_revision: u64,
    pub content_state: WorkerReadContentStateV1,
    pub segment: Option<String>,
    pub window_start: Option<String>,
    pub window_end: Option<String>,
    pub text: Option<String>,
    pub next_cursor: Option<String>,
    pub has_more: bool,
    pub truncated: Option<bool>,
}

impl WorkerReadDataV1 {
    pub fn valid(&self) -> bool {
        if !reference(&self.task_id) || !reference(&self.run_id) || self.state_revision == 0 {
            return false;
        }
        match self.content_state {
            WorkerReadContentStateV1::Pending => {
                self.segment.as_deref() == Some("0")
                    && self.window_start.as_deref() == Some("0")
                    && self.window_end.as_deref() == Some("0")
                    && self.text.as_deref() == Some("")
                    && self
                        .next_cursor
                        .as_ref()
                        .is_some_and(|cursor| valid_opaque_cursor(cursor))
                    && !self.has_more
                    && self.truncated == Some(false)
            }
            WorkerReadContentStateV1::Available => {
                let segment = self.segment.as_deref().and_then(canonical_position);
                let start = self.window_start.as_deref().and_then(canonical_position);
                let end = self.window_end.as_deref().and_then(canonical_position);
                segment.is_some()
                    && start.zip(end).is_some_and(|(start, end)| start <= end)
                    && self
                        .text
                        .as_ref()
                        .is_some_and(|text| text.len() <= MAX_WORKER_READ_BYTES as usize)
                    && self
                        .next_cursor
                        .as_ref()
                        .is_some_and(|cursor| valid_opaque_cursor(cursor))
                    && self.truncated.is_some()
            }
            WorkerReadContentStateV1::Deleted | WorkerReadContentStateV1::Expired => {
                self.segment.is_none()
                    && self.window_start.is_none()
                    && self.window_end.is_none()
                    && self.text.is_none()
                    && self.next_cursor.is_none()
                    && !self.has_more
                    && self.truncated.is_none()
            }
        }
    }
}

fn valid_run_timeout(run_timeout_secs: u32) -> bool {
    (1..=MAX_WORKER_RUN_SECS).contains(&run_timeout_secs)
}

pub(super) fn reference(value: &str) -> bool {
    !value.is_empty()
        && value.len() <= 256
        && !value.starts_with('/')
        && !value.contains("..")
        && value
            .bytes()
            .all(|byte| byte.is_ascii_alphanumeric() || b"_./:-".contains(&byte))
}

fn valid_opaque_cursor(value: &str) -> bool {
    !value.is_empty() && value.len() <= MAX_WORKER_CURSOR_BYTES && !value.contains(char::is_control)
}

fn canonical_position(value: &str) -> Option<u64> {
    if value.is_empty() || (value.len() > 1 && value.starts_with('0')) {
        return None;
    }
    value
        .parse::<u64>()
        .ok()
        .filter(|position| *position <= i64::MAX as u64)
}

/// Normalize the one public task-title contract without locale-dependent trimming.
pub fn normalize_worker_title(value: &str) -> Result<String, WorkerTitleError> {
    if value.len() > MAX_WORKER_TITLE_INPUT_BYTES {
        return Err(WorkerTitleError::InputTooLarge);
    }
    normalize_title_chars(value.chars(), false).and_then(|normalized| {
        if normalized.is_empty() {
            Err(WorkerTitleError::Empty)
        } else if normalized.len() > MAX_WORKER_TITLE_BYTES {
            Err(WorkerTitleError::NormalizedTooLarge)
        } else {
            Ok(normalized)
        }
    })
}

/// Derive a deterministic title from the first usable Goal line. Forbidden formatting controls
/// are omitted from automatic presentation rather than making otherwise valid task input fail.
pub fn derive_worker_title(goal: &str) -> String {
    for line in goal.split('\n') {
        let line = line.strip_suffix('\r').unwrap_or(line);
        if let Ok(normalized) = normalize_title_chars(line.chars(), true)
            && !normalized.is_empty()
        {
            return truncate_utf8(&normalized, MAX_WORKER_TITLE_BYTES);
        }
    }
    UNNAMED_WORKER_TASK_TITLE.to_owned()
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
pub enum WorkerTitleError {
    #[error("task title input exceeds its bound")]
    InputTooLarge,
    #[error("task title contains a forbidden control character")]
    ForbiddenCharacter,
    #[error("task title is empty after normalization")]
    Empty,
    #[error("normalized task title exceeds its bound")]
    NormalizedTooLarge,
}

fn normalize_title_chars(
    characters: impl IntoIterator<Item = char>,
    omit_forbidden: bool,
) -> Result<String, WorkerTitleError> {
    let mut normalized = String::new();
    let mut pending_space = false;
    for character in characters {
        if forbidden_title_character(character) {
            if omit_forbidden {
                continue;
            }
            return Err(WorkerTitleError::ForbiddenCharacter);
        }
        if unicode_white_space(character) {
            pending_space = !normalized.is_empty();
            continue;
        }
        if pending_space {
            normalized.push(' ');
            pending_space = false;
        }
        normalized.push(character);
    }
    Ok(normalized)
}

fn forbidden_title_character(character: char) -> bool {
    (matches!(character as u32, 0x00..=0x1f) && !matches!(character, '\t' | '\n' | '\r'))
        || matches!(character as u32, 0x7f..=0x9f)
        || matches!(
            character,
            '\u{061c}'
                | '\u{200e}'
                | '\u{200f}'
                | '\u{202a}'..='\u{202e}'
                | '\u{2066}'..='\u{2069}'
        )
}

fn unicode_white_space(character: char) -> bool {
    matches!(
        character,
        '\u{0009}'..='\u{000d}'
            | '\u{0020}'
            | '\u{0085}'
            | '\u{00a0}'
            | '\u{1680}'
            | '\u{2000}'..='\u{200a}'
            | '\u{2028}'
            | '\u{2029}'
            | '\u{202f}'
            | '\u{205f}'
            | '\u{3000}'
    )
}

fn truncate_utf8(value: &str, max_bytes: usize) -> String {
    if value.len() <= max_bytes {
        return value.to_owned();
    }
    let mut end = max_bytes;
    while !value.is_char_boundary(end) {
        end -= 1;
    }
    value[..end].trim_end().to_owned()
}

fn absolute_path(value: &str) -> bool {
    !value.is_empty()
        && value.len() <= 4096
        && !value.contains(char::is_control)
        && std::path::Path::new(value).is_absolute()
}

#[cfg(test)]
mod tests {
    use super::*;

    fn dependency_selection() -> WorkerDependenciesSelectRequestV1 {
        let (adapter, cli, node) = if cfg!(windows) {
            (
                "C:/opt/acp/codex-acp.js",
                "C:/opt/bin/codex",
                "C:/opt/bin/node",
            )
        } else {
            ("/opt/acp/codex-acp.js", "/opt/bin/codex", "/opt/bin/node")
        };
        WorkerDependenciesSelectRequestV1 {
            harness: WorkerHarnessV1::CodexCli,
            adapter_path: Some(adapter.into()),
            cli_path: cli.into(),
            node_path: Some(node.into()),
            expected_selection_revision: 7,
        }
    }

    fn exec() -> WorkerExecRequestV1 {
        WorkerExecRequestV1 {
            schema: WORKER_EXEC_SCHEMA_V1.into(),
            plan_id: AgentPlanId::parse("worker").unwrap(),
            cwd: std::env::current_dir()
                .unwrap()
                .to_string_lossy()
                .into_owned(),
            permission_policy: WorkerPermissionPolicyV1::ApproveAll,
            run_timeout_secs: DEFAULT_WORKER_RUN_SECS,
            input: DelegationTaskInputV1 {
                goal: "implement the change".into(),
                context: String::new(),
                constraints: String::new(),
                acceptance_criteria: String::new(),
            },
            submission_key: "worker/start-one".into(),
            title: None,
            parent_task_ref: None,
        }
    }

    #[test]
    fn worker_settings_are_strict_and_bounded() {
        assert!(WorkerSettingsV1::new(10).valid());
        assert!(WorkerSettingsV1::new(1_000).valid());
        assert!(!WorkerSettingsV1::new(0).valid());
        let mut value = serde_json::to_value(WorkerSettingsV1::new(10)).unwrap();
        value["revision"] = serde_json::json!(1);
        assert!(serde_json::from_value::<WorkerSettingsV1>(value).is_err());
    }

    #[test]
    fn dependency_selection_plan_binds_only_the_normalized_tuple_and_target_revision() {
        let request = dependency_selection();
        let first = plan_worker_dependency_selection(&request).unwrap();
        let second = plan_worker_dependency_selection(&request).unwrap();
        assert_eq!(first, second);
        assert_eq!(first.expected_revisions.target, 7);
        assert!(first.expected_revisions.dependencies.is_empty());
        assert_eq!(
            first.spec.resource_id.as_deref(),
            Some("worker-dependency-selection/codex_cli")
        );
        assert_eq!(first.accept_digest, second.accept_digest);
        assert_eq!(first.idempotency_key, second.idempotency_key);

        let mut another_harness = request.clone();
        another_harness.harness = WorkerHarnessV1::ClaudeCode;
        assert_ne!(
            plan_worker_dependency_selection(&another_harness)
                .unwrap()
                .accept_digest,
            first.accept_digest
        );
        let mut another_revision = request;
        another_revision.expected_selection_revision = 8;
        let changed = plan_worker_dependency_selection(&another_revision).unwrap();
        assert_ne!(changed.accept_digest, first.accept_digest);
        assert_ne!(changed.idempotency_key, first.idempotency_key);
    }

    #[test]
    fn dependency_selection_plan_rejects_relative_or_control_character_paths() {
        let valid = dependency_selection();
        assert!(plan_worker_dependency_selection(&valid).is_some());
        let request = WorkerDependenciesSelectRequestV1 {
            adapter_path: Some("relative/adapter".into()),
            expected_selection_revision: 0,
            ..valid.clone()
        };
        assert!(plan_worker_dependency_selection(&request).is_none());
        let invalid = WorkerDependenciesSelectRequestV1 {
            adapter_path: Some(format!("{}\nacp", valid.adapter_path.unwrap())),
            ..request
        };
        assert!(plan_worker_dependency_selection(&invalid).is_none());
    }

    #[test]
    fn worker_exec_is_instance_scoped_and_rejects_authority_injection_fields() {
        let request = exec();
        assert!(request.valid());
        let value = serde_json::to_value(request).unwrap();
        for forbidden in [
            "caller",
            "agent_id",
            "permit_id",
            "permit_generation",
            "root_identity",
            "grant_id",
            "grant_generation",
            "access",
            "tools",
            "network",
        ] {
            assert!(value.get(forbidden).is_none(), "{forbidden}");
        }
        let mut injected = value;
        injected["caller"] = serde_json::json!({"context_id":"forged"});
        assert!(serde_json::from_value::<WorkerExecRequestV1>(injected).is_err());
    }

    #[test]
    fn permission_policy_defaults_to_approve_all_and_old_fields_are_rejected() {
        let mut value = serde_json::to_value(exec()).unwrap();
        value.as_object_mut().unwrap().remove("permission_policy");
        let decoded: WorkerExecRequestV1 = serde_json::from_value(value).unwrap();
        assert_eq!(
            decoded.permission_policy,
            WorkerPermissionPolicyV1::ApproveAll
        );
        let mut old = serde_json::to_value(exec()).unwrap();
        old["agent_id"] = serde_json::json!("codex");
        assert!(serde_json::from_value::<WorkerExecRequestV1>(old).is_err());
    }

    #[test]
    fn worker_status_accepts_each_exact_selector_form() {
        assert!(
            WorkerStatusRequestV1 {
                task_id: None,
                run_id: Some("run/one".into()),
                submission_key: None,
                submission_operation: None,
            }
            .valid()
        );
        assert!(
            WorkerStatusRequestV1 {
                task_id: Some("task/one".into()),
                run_id: Some("run/one".into()),
                submission_key: None,
                submission_operation: None,
            }
            .valid()
        );
        assert!(
            WorkerStatusRequestV1 {
                task_id: None,
                run_id: None,
                submission_key: Some("worker/start-one".into()),
                submission_operation: Some(DelegationSubmissionOperationV1::Start),
            }
            .valid()
        );
    }

    #[test]
    fn worker_list_is_a_strict_instance_page_request() {
        let request = WorkerListRequestV1 {
            title: Some("  同一\u{00a0}标题  ".into()),
            cursor: Some("sequence/42".into()),
            limit: Some(25),
        };
        assert!(request.valid());
        assert_eq!(request.effective_limit(), 25);

        let mut invalid = request.clone();
        invalid.cursor = Some(String::new());
        assert!(!invalid.valid());
        invalid.cursor = None;
        invalid.limit = Some(0);
        assert!(!invalid.valid());

        let mut injected = serde_json::to_value(request).unwrap();
        injected["caller"] = serde_json::json!({"context_id":"forged"});
        assert!(serde_json::from_value::<WorkerListRequestV1>(injected).is_err());
    }

    #[test]
    fn task_title_normalization_is_bounded_deterministic_and_not_locale_dependent() {
        assert_eq!(
            normalize_worker_title("  设计\u{00a0}\u{2009}任务  ").unwrap(),
            "设计 任务"
        );
        assert_eq!(
            normalize_worker_title("  设计\t\r\n任务  ").unwrap(),
            "设计 任务"
        );
        assert_eq!(
            derive_worker_title("\n\r\n  第一\u{3000}行  \n第二行"),
            "第一 行"
        );
        assert_eq!(derive_worker_title("\n\r\n"), UNNAMED_WORKER_TASK_TITLE);
        assert_eq!(
            normalize_worker_title("unsafe\u{202e}title"),
            Err(WorkerTitleError::ForbiddenCharacter)
        );
        assert_eq!(
            normalize_worker_title("unsafe\u{0085}title"),
            Err(WorkerTitleError::ForbiddenCharacter)
        );
        let long = "界".repeat(MAX_WORKER_TITLE_BYTES);
        let derived = derive_worker_title(&long);
        assert!(derived.len() <= MAX_WORKER_TITLE_BYTES);
        assert!(derived.is_char_boundary(derived.len()));
    }

    #[test]
    fn worker_read_request_and_terminal_visibility_shapes_are_strict() {
        let request = WorkerReadRequestV1 {
            run_id: "run/one".into(),
            cursor: None,
            max_bytes: None,
        };
        assert!(request.valid());
        assert_eq!(request.effective_max_bytes(), DEFAULT_WORKER_READ_BYTES);
        let pending = WorkerReadDataV1 {
            task_id: "task/one".into(),
            run_id: "run/one".into(),
            run_state: RunStateV1::Accepted,
            state_revision: 1,
            content_state: WorkerReadContentStateV1::Pending,
            segment: Some("0".into()),
            window_start: Some("0".into()),
            window_end: Some("0".into()),
            text: Some(String::new()),
            next_cursor: Some("signed/pending".into()),
            has_more: false,
            truncated: Some(false),
        };
        assert!(pending.valid());
        let mut malformed_pending = pending;
        malformed_pending.has_more = true;
        assert!(!malformed_pending.valid());

        let available = WorkerReadDataV1 {
            task_id: "task/one".into(),
            run_id: "run/one".into(),
            run_state: RunStateV1::Running,
            state_revision: 2,
            content_state: WorkerReadContentStateV1::Available,
            segment: Some("1".into()),
            window_start: Some("0".into()),
            window_end: Some("2".into()),
            text: Some("ok".into()),
            next_cursor: Some("signed/available".into()),
            has_more: false,
            truncated: Some(false),
        };
        assert!(available.valid());
        let mut leading_zero = available.clone();
        leading_zero.segment = Some("01".into());
        assert!(!leading_zero.valid());
        let mut inverted = available.clone();
        inverted.window_start = Some("3".into());
        assert!(!inverted.valid());
        let mut outside_storage_range = available;
        outside_storage_range.window_end = Some((i64::MAX as u64 + 1).to_string());
        assert!(!outside_storage_range.valid());

        let deleted = WorkerReadDataV1 {
            task_id: "task/one".into(),
            run_id: "run/one".into(),
            run_state: RunStateV1::Succeeded,
            state_revision: 2,
            content_state: WorkerReadContentStateV1::Deleted,
            segment: None,
            window_start: None,
            window_end: None,
            text: None,
            next_cursor: None,
            has_more: false,
            truncated: None,
        };
        assert!(deleted.valid());
        let mut invalid = deleted;
        invalid.text = Some(String::new());
        assert!(!invalid.valid());
    }

    #[test]
    fn executor_availability_lists_all_supported_capability_scoped_harnesses() {
        let ready = WorkerExecutorCapabilityAvailabilityV1 {
            state: WorkerExecutorAvailabilityStateV1::Ready,
            reason: None,
        };
        let unknown_restricted = WorkerExecutorCapabilityAvailabilityV1 {
            state: WorkerExecutorAvailabilityStateV1::Unknown,
            reason: Some(WorkerExecutorAvailabilityReasonV1::RestrictedPolicyUnverified),
        };
        let unavailable_resume = WorkerExecutorCapabilityAvailabilityV1 {
            state: WorkerExecutorAvailabilityStateV1::Unavailable,
            reason: Some(WorkerExecutorAvailabilityReasonV1::ResumeUnavailable),
        };
        let executor = |harness| WorkerExecutorAvailabilityV1 {
            harness,
            state: WorkerExecutorAvailabilityStateV1::Ready,
            reason: None,
            start_approve_all: ready.clone(),
            cancel: ready.clone(),
            continue_session: unavailable_resume.clone(),
            restricted_policy: unknown_restricted.clone(),
        };
        let response = WorkerExecutorAvailabilityListV1 {
            schema: WORKER_EXECUTOR_AVAILABILITY_SCHEMA_V1.into(),
            executors: vec![
                executor(WorkerHarnessV1::CodexCli),
                executor(WorkerHarnessV1::ClaudeCode),
                executor(WorkerHarnessV1::QoderCli),
                executor(WorkerHarnessV1::Pi),
                executor(WorkerHarnessV1::DeepseekHarness),
                executor(WorkerHarnessV1::OpenCode),
            ],
        };
        assert!(response.valid());

        let mut incomplete = response.clone();
        incomplete.executors.pop();
        assert!(!incomplete.valid());
        let mut duplicate = response.clone();
        duplicate.executors[2].harness = WorkerHarnessV1::CodexCli;
        assert!(!duplicate.valid());
        let mut reordered = response.clone();
        reordered.executors.swap(0, 1);
        assert!(!reordered.valid());

        let mut overstated = response;
        overstated.executors[0].start_approve_all = unavailable_resume;
        assert!(!overstated.valid());
    }
}

#[cfg(test)]
#[path = "worker_selection_tests.rs"]
mod selection_tests;