dsh-ops 0.0.0-stage → 0.2.2

package/vendor/fastctx/src/skip_report.rs

@@ -0,0 +1,83 @@
+//! Shared wording for whatever a tool could not reach, read, or search.
+//!
+//! Two kinds of gap reach a response and they mean different things to the
+//! caller. A skipped *file* was found and then could not be used, so the count
+//! is exact and the next move is usually a decoding or size decision. An
+//! unreachable *path* was never entered, so it hides an unknown number of files
+//! and the result set has a hole in it — "not found" stops meaning "not there".
+//! Every tool states both through this module so one reading works everywhere.
+
+/// One line of skip detail: the path, and why it did not contribute.
+pub(crate) fn detail_line(path: &str, reason: &str) -> String {
+    format!("{path} — {reason}")
+}
+
+/// What a response has to disclose about the gaps in its own coverage.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub(crate) struct SkipTally {
+    /// Files reached but not used, e.g. undecodable or changed mid-search.
+    pub(crate) files: usize,
+    /// Paths never entered, each hiding an unknown amount of the tree.
+    pub(crate) unreachable: usize,
+    /// Detail lines available to show, across both kinds.
+    pub(crate) listed: usize,
+}
+
+impl SkipTally {
+    pub(crate) fn is_empty(&self) -> bool {
+        self.files == 0 && self.unreachable == 0
+    }
+
+    /// The clause appended inside a terminal note, without its punctuation.
+    ///
+    /// `shown` is how many detail lines survived the budget; a value below
+    /// `listed` adds the hint that narrowing the request reveals the rest.
+    fn clause(&self, shown: usize) -> Option<String> {
+        if self.is_empty() {
+            return None;
+        }
+        let mut clause = String::new();
+        if self.files > 0 {
+            clause.push_str(&format!("{} skipped", counted(self.files, "file", "files")));
+        }
+        if self.unreachable > 0 {
+            if !clause.is_empty() {
+                clause.push_str(", ");
+            }
+            // "unreachable" carries the consequence on its own: a path the walk
+            // never entered is one these results cannot speak for. Spelling that
+            // out again collides with the truncation hint that may follow.
+            clause.push_str(&format!(
+                "{} unreachable",
+                counted(self.unreachable, "path", "paths")
+            ));
+        }
+        if shown < self.listed {
+            clause.push_str(&format!(
+                ", showing {shown} — narrow path/glob to inspect the rest"
+            ));
+        }
+        Some(clause)
+    }
+}
+
+/// Folds a skip clause into a terminal note that ends in `.)`.
+///
+/// Returns `None` only when the note has no such ending, which is a rendering
+/// bug rather than a state a caller can recover from.
+pub(crate) fn terminal_with_skips(
+    terminal: &str,
+    tally: &SkipTally,
+    shown: usize,
+) -> Option<String> {
+    let Some(clause) = tally.clause(shown) else {
+        return Some(terminal.to_string());
+    };
+    let stem = terminal.strip_suffix(".)")?;
+    Some(format!("{stem}; {clause}.)"))
+}
+
+fn counted(count: usize, singular: &str, plural: &str) -> String {
+    let noun = if count == 1 { singular } else { plural };
+    format!("{count} {noun}")
+}

package/vendor/fastctx/src/stdio_transport.rs

@@ -0,0 +1,177 @@
+//! Process-stdio adapters whose reader lifetime does not pin the async runtime.
+
+use std::io::Read;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::io::{AsyncRead, ReadBuf};
+use tokio::sync::{mpsc, watch};
+
+const STDIN_CHUNK_BYTES: usize = 8 * 1024;
+const STDIN_QUEUE_DEPTH: usize = 16;
+
+/// Async stdin backed by a detached operating-system reader thread.
+///
+/// Tokio's global stdin adapter uses the runtime blocking pool. A leaked writer can keep that
+/// pool thread blocked forever after the MCP service is cancelled, preventing parent-death
+/// shutdown from completing. This adapter deliberately owns an ordinary detached thread instead:
+/// EOF still closes the transport normally, while process shutdown never waits for a blocked read.
+pub(crate) struct DetachedStdin {
+    receiver: mpsc::Receiver<std::io::Result<Vec<u8>>>,
+    pending: Vec<u8>,
+    pending_offset: usize,
+    read_error: watch::Receiver<Option<String>>,
+}
+
+impl DetachedStdin {
+    /// Starts the sole stdin reader for the stdio MCP transport.
+    pub(crate) fn start() -> Result<Self, String> {
+        Self::spawn_reader(|sender, read_error_sender| {
+            let stdin = std::io::stdin();
+            forward_reader(stdin.lock(), sender, read_error_sender);
+        })
+    }
+
+    fn spawn_reader(
+        reader: impl FnOnce(mpsc::Sender<std::io::Result<Vec<u8>>>, watch::Sender<Option<String>>)
+        + Send
+        + 'static,
+    ) -> Result<Self, String> {
+        let (sender, receiver) = mpsc::channel(STDIN_QUEUE_DEPTH);
+        let (read_error_sender, read_error) = watch::channel(None);
+        std::thread::Builder::new()
+            .name("fastctx-stdin".to_string())
+            .spawn(move || reader(sender, read_error_sender))
+            .map_err(|error| format!("Cannot start the MCP stdin reader: {error}"))?;
+        Ok(Self {
+            receiver,
+            pending: Vec::new(),
+            pending_offset: 0,
+            read_error,
+        })
+    }
+
+    /// Reports an operating-system read failure independently of rmcp's EOF-shaped transport API.
+    pub(crate) fn read_error_receiver(&self) -> watch::Receiver<Option<String>> {
+        self.read_error.clone()
+    }
+}
+
+fn forward_reader(
+    mut input: impl Read,
+    sender: mpsc::Sender<std::io::Result<Vec<u8>>>,
+    read_error_sender: watch::Sender<Option<String>>,
+) {
+    loop {
+        let mut bytes = vec![0; STDIN_CHUNK_BYTES];
+        match input.read(&mut bytes) {
+            Ok(0) => break,
+            Ok(read) => {
+                bytes.truncate(read);
+                if sender.blocking_send(Ok(bytes)).is_err() {
+                    break;
+                }
+            }
+            Err(error) => {
+                read_error_sender.send_replace(Some(format!("Cannot read MCP stdin: {error}")));
+                let _ = sender.blocking_send(Err(error));
+                break;
+            }
+        }
+    }
+}
+
+impl AsyncRead for DetachedStdin {
+    fn poll_read(
+        mut self: Pin<&mut Self>,
+        context: &mut Context<'_>,
+        output: &mut ReadBuf<'_>,
+    ) -> Poll<std::io::Result<()>> {
+        loop {
+            if self.pending_offset < self.pending.len() {
+                let available = &self.pending[self.pending_offset..];
+                let copied = available.len().min(output.remaining());
+                output.put_slice(&available[..copied]);
+                self.pending_offset += copied;
+                if self.pending_offset == self.pending.len() {
+                    self.pending.clear();
+                    self.pending_offset = 0;
+                }
+                return Poll::Ready(Ok(()));
+            }
+            match self.receiver.poll_recv(context) {
+                Poll::Ready(Some(Ok(bytes))) => {
+                    self.pending = bytes;
+                    self.pending_offset = 0;
+                }
+                Poll::Ready(Some(Err(error))) => return Poll::Ready(Err(error)),
+                // A zero-byte read is the transport's end of input; the reader thread only closes
+                // the channel once every byte it read has been handed over.
+                Poll::Ready(None) => return Poll::Ready(Ok(())),
+                Poll::Pending => return Poll::Pending,
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::DetachedStdin;
+    use tokio::io::AsyncReadExt;
+    use tokio::sync::{mpsc, watch};
+
+    fn adapter(
+        receiver: mpsc::Receiver<std::io::Result<Vec<u8>>>,
+        read_error: watch::Receiver<Option<String>>,
+    ) -> DetachedStdin {
+        DetachedStdin {
+            receiver,
+            pending: Vec::new(),
+            pending_offset: 0,
+            read_error,
+        }
+    }
+
+    #[test]
+    fn stdin_adapter_is_send_for_the_rmcp_transport() {
+        fn assert_send<T: Send>() {}
+        assert_send::<DetachedStdin>();
+    }
+
+    #[tokio::test]
+    async fn end_of_input_follows_all_buffered_input() {
+        let (sender, receiver) = mpsc::channel(1);
+        sender.send(Ok(b"complete frame".to_vec())).await.unwrap();
+        drop(sender);
+        let (_read_error_sender, read_error) = watch::channel(None);
+        let mut input = adapter(receiver, read_error);
+
+        let mut prefix = [0; 4];
+        input.read_exact(&mut prefix).await.unwrap();
+        assert_eq!(&prefix, b"comp");
+
+        let mut suffix = Vec::new();
+        input.read_to_end(&mut suffix).await.unwrap();
+
+        assert_eq!(suffix, b"lete frame");
+        assert_eq!(input.read(&mut [0; 4]).await.unwrap(), 0);
+    }
+
+    #[tokio::test]
+    async fn read_error_is_not_reported_as_clean_eof() {
+        let (sender, receiver) = mpsc::channel(1);
+        sender
+            .send(Err(std::io::Error::new(
+                std::io::ErrorKind::BrokenPipe,
+                "injected stdin failure",
+            )))
+            .await
+            .unwrap();
+        drop(sender);
+        let (_read_error_sender, read_error) = watch::channel(None);
+        let mut input = adapter(receiver, read_error);
+
+        let error = input.read_to_end(&mut Vec::new()).await.unwrap_err();
+
+        assert_eq!(error.kind(), std::io::ErrorKind::BrokenPipe);
+    }
+}

package/vendor/fastctx/src/tool_schema.rs

@@ -0,0 +1,204 @@
+//! Wire-format normalization for the tool input schemas FastCtx publishes.
+//!
+//! # Why this exists
+//!
+//! MCP lets a server publish any JSON Schema, and SEP-2106 widened that further.
+//! The LLM APIs that ultimately consume a tool declaration do not: each accepts a
+//! narrow, and differently narrow, subset. A declaration one of them rejects is not
+//! degraded but fatal — the provider answers 400 for the whole request, so every
+//! FastCtx tool disappears from that turn rather than just the offending parameter.
+//!
+//! Hosts do not absorb the difference for us. Codex forwards `$ref` and the
+//! composition keywords untouched, and rewrites every local `$ref` to `{}` once a
+//! tool schema crosses its compaction budget, which silently erases the accepted
+//! values of an enum parameter. Other hosts each grew their own partial lowering.
+//! FastCtx therefore publishes the intersection of the provider subsets instead of
+//! the union of what MCP permits.
+//!
+//! # The published subset
+//!
+//! Every node carries a single scalar `type`. No published schema contains `$ref`,
+//! `$defs`, `oneOf`, `anyOf`, `allOf`, `const`, `$schema`, `additionalProperties`,
+//! `format`, or a `"null"` type. Only these keywords appear: `type`, `description`,
+//! `properties`, `required`, `items`, `enum`, `default`, `minimum`, `maximum`,
+//! `minItems`, `maxItems`.
+//!
+//! This is a published contract, not a local style choice. It is enforced by
+//! `server_contract::published_tool_schemas_stay_inside_the_portable_subset`, which
+//! walks every published tool instead of a named list of parameters, so neither a
+//! new tool nor a new parameter type can reintroduce a rejected construct unnoticed.
+//! Widening the subset means answering, for each provider, why the addition is safe.
+//!
+//! # Deserialization is untouched
+//!
+//! Normalization rewrites only what the model is told. Serde still parses the
+//! original Rust types, so a parameter may accept more than its schema advertises.
+//! That direction is safe: every input the schema describes is still accepted.
+
+use serde_json::{Map, Value};
+
+/// Keys removed from every node.
+///
+/// - `$schema` is metadata no consumer needs, and hosts strip it anyway.
+/// - `additionalProperties` does not exist in the Gemini API `Schema` type, where an
+///   unrecognized key is an `Unknown name` 400. Removing it costs no runtime
+///   strictness: `serde(deny_unknown_fields)` still rejects unknown input at call time.
+/// - `format` carries our numeric widths (`uint`, `uint64`, `int64`), which sit
+///   outside every provider's accepted format set while `minimum`/`maximum` already
+///   express the same bound.
+const STRIPPED_KEYS: [&str; 3] = ["$schema", "additionalProperties", "format"];
+
+/// Bounds `$ref` inlining so a future self-referential type cannot spin here.
+/// Exceeding it leaves the `$ref` in place, which the published-shape guard reports.
+const MAX_INLINE_DEPTH: usize = 32;
+
+/// Rewrites one tool's input schema into the portable subset described above.
+pub(crate) fn normalize_published_schema(schema: &Map<String, Value>) -> Map<String, Value> {
+    let definitions = schema
+        .get("$defs")
+        .and_then(Value::as_object)
+        .cloned()
+        .unwrap_or_default();
+    let mut root = schema.clone();
+    root.remove("$defs");
+    match normalize_node(Value::Object(root), &definitions, 0) {
+        Value::Object(normalized) => normalized,
+        // A tool schema is an object by construction; anything else means the router
+        // handed us something we do not publish, so pass the original through
+        // untouched rather than invent a shape.
+        _ => schema.clone(),
+    }
+}
+
+fn normalize_node(node: Value, definitions: &Map<String, Value>, depth: usize) -> Value {
+    let Value::Object(mut map) = node else {
+        return node;
+    };
+    for key in STRIPPED_KEYS {
+        map.remove(key);
+    }
+    if let Some(inlined) = inlined_reference(&map, definitions, depth) {
+        map = inlined;
+    }
+    collapse_nullable_union(&mut map, definitions, depth);
+    collapse_const_variants(&mut map);
+    collapse_nullable_type(&mut map);
+
+    if let Some(Value::Object(properties)) = map.remove("properties") {
+        let normalized = properties
+            .into_iter()
+            .map(|(name, value)| (name, normalize_node(value, definitions, depth + 1)))
+            .collect();
+        map.insert("properties".to_string(), Value::Object(normalized));
+    }
+    if let Some(items) = map.remove("items") {
+        map.insert(
+            "items".to_string(),
+            normalize_node(items, definitions, depth + 1),
+        );
+    }
+    Value::Object(map)
+}
+
+/// Replaces a local `$ref` with the definition body it points at.
+///
+/// The referring node's own keys win, so a parameter's `description` outranks the
+/// shared description on the type it names. Only `#/$defs/<name>` is resolved:
+/// SEP-2106 requires that a remote `$ref` never be dereferenced.
+fn inlined_reference(
+    map: &Map<String, Value>,
+    definitions: &Map<String, Value>,
+    depth: usize,
+) -> Option<Map<String, Value>> {
+    if depth >= MAX_INLINE_DEPTH {
+        return None;
+    }
+    let name = map.get("$ref")?.as_str()?.strip_prefix("#/$defs/")?;
+    let Value::Object(mut merged) =
+        normalize_node(definitions.get(name)?.clone(), definitions, depth + 1)
+    else {
+        return None;
+    };
+    for (key, value) in map {
+        if key != "$ref" {
+            merged.insert(key.clone(), value.clone());
+        }
+    }
+    Some(merged)
+}
+
+/// Collapses the `Option<T>` shape `anyOf: [T, {"type": "null"}]` down to `T`.
+///
+/// The `required` list already says which parameters may be omitted, so the union
+/// spells optionality a second time in the one form no provider subset accepts. A
+/// union with more than one non-null branch is left intact on purpose: guessing a
+/// branch would silently narrow what the model may send, so the published-shape
+/// guard fails instead and the choice gets made at the Rust type.
+fn collapse_nullable_union(
+    map: &mut Map<String, Value>,
+    definitions: &Map<String, Value>,
+    depth: usize,
+) {
+    let Some(Value::Array(branches)) = map.get("anyOf") else {
+        return;
+    };
+    let mut kept: Vec<Value> = branches
+        .iter()
+        .map(|branch| normalize_node(branch.clone(), definitions, depth + 1))
+        .filter(|branch| branch.get("type").and_then(Value::as_str) != Some("null"))
+        .collect();
+    if kept.len() != 1 {
+        return;
+    }
+    let Value::Object(branch) = kept.remove(0) else {
+        return;
+    };
+    map.remove("anyOf");
+    for (key, value) in branch {
+        map.entry(key).or_insert(value);
+    }
+}
+
+/// Rewrites the `oneOf` of `const` variants schemars derives for a fieldless enum
+/// into `type: "string"` with `enum`.
+///
+/// No provider subset accepts `oneOf` or `const`; all of them accept a string enum.
+/// The per-variant doc comments are dropped along with the `oneOf`, so every such
+/// parameter states its accepted values in its own `description`.
+fn collapse_const_variants(map: &mut Map<String, Value>) {
+    let Some(Value::Array(variants)) = map.get("oneOf") else {
+        return;
+    };
+    let mut values = Vec::with_capacity(variants.len());
+    for variant in variants {
+        match variant.get("const") {
+            Some(Value::String(value)) => values.push(Value::String(value.clone())),
+            _ => return,
+        }
+    }
+    if values.is_empty() {
+        return;
+    }
+    map.remove("oneOf");
+    map.insert("type".to_string(), Value::String("string".to_string()));
+    map.insert("enum".to_string(), Value::Array(values));
+}
+
+/// Rewrites `type: ["string", "null"]` as `type: "string"`.
+///
+/// Gemini's schema type is a single scalar rather than a list, so a type array is
+/// rejected outright; `required` already carries which parameters are optional.
+fn collapse_nullable_type(map: &mut Map<String, Value>) {
+    let Some(Value::Array(members)) = map.get("type") else {
+        return;
+    };
+    let mut kept: Vec<Value> = members
+        .iter()
+        .filter(|member| member.as_str() != Some("null"))
+        .cloned()
+        .collect();
+    if kept.len() != 1 {
+        return;
+    }
+    map.insert("type".to_string(), kept.remove(0));
+}