Dianel555/DSkills / skills/ace-tool
ace-tool
VerifiedSemantic codebase search, code indexing, and prompt enhancement via standalone CLI. Use when: (1) Semantic code search with natural language queries, (2) Code indexing for remote codebase retrieval, (3) Prompt enhancement with codebase context, (4) Before grep/find/glob operations for better accuracy, (5) Complex requirements clarification, (6) Large codebase navigation. Triggers: "search context", "enhance prompt", "find code that", "index project", "clarify requirements". IMPORTANT: Always use ace-tool BEFORE grep/find/glob for semantic-level code location.
scripts/client.py
View on GitHub"""ACE-Tool API client for semantic search and prompt enhancement."""
import json
import os
import re
import time
import uuid
import httpx
from tenacity import retry, retry_if_not_exception_type, stop_after_attempt, wait_exponential
try:
from .indexer import Indexer, IndexUploadError
from .secure_fs import FileTooLargeError, UnsafePathError
from .templates import (
DEFAULT_CLAUDE_MODEL,
DEFAULT_CODEX_MODEL,
DEFAULT_GEMINI_MODEL,
DEFAULT_MODEL,
DEFAULT_OPENAI_MODEL,
ENCODING_CHAIN,
ENHANCE_PROMPT_TEMPLATE,
ENV_ENHANCER_ENDPOINT,
ENV_ENHANCER_ENDPOINT_LEGACY,
ENV_ENHANCER_INCLUDE_SEARCH_CONTEXT,
ENV_ENHANCER_REASONING_EFFORT,
ITERATIVE_ENHANCE_TEMPLATE,
MAX_BLOB_SIZE,
NO_RELEVANT_CODE_CONTEXT,
RETRIEVAL_TIMEOUT,
SEARCH_CONTEXT_CHAR_LIMIT,
USER_AGENT,
)
from .utils import (
build_api_url,
decode_bytes,
get_session_id,
is_chinese_text,
load_session_auth,
parse_chat_history,
)
except ImportError:
from indexer import Indexer, IndexUploadError
from secure_fs import FileTooLargeError, UnsafePathError
from templates import (
DEFAULT_CLAUDE_MODEL,
DEFAULT_CODEX_MODEL,
DEFAULT_GEMINI_MODEL,
DEFAULT_MODEL,
DEFAULT_OPENAI_MODEL,
ENCODING_CHAIN,
ENHANCE_PROMPT_TEMPLATE,
ENV_ENHANCER_ENDPOINT,
ENV_ENHANCER_ENDPOINT_LEGACY,
ENV_ENHANCER_INCLUDE_SEARCH_CONTEXT,
ENV_ENHANCER_REASONING_EFFORT,
ITERATIVE_ENHANCE_TEMPLATE,
MAX_BLOB_SIZE,
NO_RELEVANT_CODE_CONTEXT,
RETRIEVAL_TIMEOUT,
SEARCH_CONTEXT_CHAR_LIMIT,
USER_AGENT,
)
from utils import (
build_api_url,
decode_bytes,
get_session_id,
is_chinese_text,
load_session_auth,
parse_chat_history,
)
import logging
log = logging.getLogger(__name__)
_ENHANCED_PROMPT_RE = re.compile(
r"<augment-enhanced-prompt(?:\s+[^>]*)?>\s*(.*?)\s*</augment-enhanced-prompt\s*>",
re.DOTALL,
)
_THIRD_PARTY_ENDPOINTS = frozenset({"claude", "openai", "gemini", "codex"})
_TRUE_ENV_VALUES = frozenset({"1", "true", "yes", "on"})
_EMPTY_OCE_RETRIEVAL = "The following code sections were retrieved:"
READINESS_TIMEOUT = 180.0
READINESS_POLL_INTERVAL = 1.0
class IndexReadinessError(ValueError):
"""The server cannot confirm that the requested index is ready."""
class AceToolClient:
"""Client for ACE-Tool API endpoints."""
def __init__(
self,
base_url: str | None = None,
token: str | None = None,
endpoint: str | None = None,
reasoning_effort: str | None = None,
):
# Determine auth source priority: constructor params > session auth
if base_url is not None or token is not None:
# Constructor params provided (full or partial override)
self.auth_source = "constructor"
loaded_base_url, loaded_token, _ = load_session_auth()
self.base_url = (base_url if base_url is not None else loaded_base_url or "").rstrip("/")
self.token = token if token is not None else loaded_token or ""
else:
# No constructor params, use load_session_auth()
loaded_base_url, loaded_token, auth_source = load_session_auth()
self.base_url = (loaded_base_url or "").rstrip("/")
self.token = loaded_token or ""
self.auth_source = auth_source
# Endpoint resolution: PROMPT_ENHANCER_ENDPOINT > ACE_ENHANCER_ENDPOINT > constructor arg > "new"
env_endpoint = os.getenv(ENV_ENHANCER_ENDPOINT, "") or os.getenv(ENV_ENHANCER_ENDPOINT_LEGACY, "")
resolved = env_endpoint or endpoint or "new"
self.endpoint = resolved.lower()
self.timeout = httpx.Timeout(180.0, connect=30.0)
self.third_party_base_url = os.getenv("PROMPT_ENHANCER_BASE_URL", "").rstrip("/")
self.third_party_token = os.getenv("PROMPT_ENHANCER_TOKEN", "")
self.third_party_model = os.getenv("PROMPT_ENHANCER_MODEL", "")
# Reasoning control: default none (enhancement needs no deep reasoning);
# empty string sends no reasoning parameter at all.
env_val = os.environ.get(ENV_ENHANCER_REASONING_EFFORT)
if reasoning_effort is not None:
self.reasoning_effort = reasoning_effort.strip().lower()
elif env_val is not None:
self.reasoning_effort = env_val.strip().lower()
else:
self.reasoning_effort = "none"
def _get_headers(self, use_third_party: bool = False) -> dict:
headers = {
"Content-Type": "application/json",
"User-Agent": USER_AGENT,
"x-request-id": str(uuid.uuid4()),
"x-request-session-id": get_session_id(),
}
if use_third_party and self.third_party_token:
headers["Authorization"] = f"Bearer {self.third_party_token}"
elif self.token:
headers["Authorization"] = f"Bearer {self.token}"
return headers
def _is_third_party(self) -> bool:
return self.endpoint in _THIRD_PARTY_ENDPOINTS
def _should_include_search_context(self) -> bool:
"""Check if search context injection is enabled via env var."""
val = os.environ.get(ENV_ENHANCER_INCLUDE_SEARCH_CONTEXT, "").strip().lower()
return val in _TRUE_ENV_VALUES
@staticmethod
def _normalize_search_context(text: str) -> str:
"""Normalize search context: placeholder for empty, truncate if over limit."""
stripped = text.strip()
if not stripped or stripped == NO_RELEVANT_CODE_CONTEXT:
return NO_RELEVANT_CODE_CONTEXT
if len(stripped) > SEARCH_CONTEXT_CHAR_LIMIT:
return stripped[:SEARCH_CONTEXT_CHAR_LIMIT] + "\n\n[codebase_context truncated for length]"
return stripped
@staticmethod
def _build_prompt_with_search_context(original: str, ctx: str) -> str:
"""Wrap original prompt with codebase context in XML tags."""
return f"<codebase_context>\n{ctx}\n</codebase_context>\n\n<original_request>\n{original}\n</original_request>"
@staticmethod
def _search_result_text(result: dict) -> str:
"""Render local file matches as text for prompt-context consumers."""
matches = result.get("results", "")
if isinstance(matches, str):
return matches
if result.get("mode") == "local_fallback" and isinstance(matches, list):
paths = [item["file"] for item in matches if isinstance(item, dict) and isinstance(item.get("file"), str)]
if paths:
return "Local keyword matches (file paths):\n" + "\n".join(f"- {path}" for path in paths)
return ""
def _remote_search_with_empty_fallback(self, project_root: str, query: str) -> dict:
result = self._remote_search(project_root, query)
text = result.get("results")
if text is None or (isinstance(text, str) and text.strip() in ("", _EMPTY_OCE_RETRIEVAL)):
log.info("Remote search returned no results; falling back to local keyword search")
return self._local_search(project_root, query)
return result
def _maybe_inject_search_context(self, endpoint: str, prompt: str, project_root: str | None) -> str:
"""Inject search context into prompt if enabled and applicable."""
if not self._is_third_party() or not self._should_include_search_context():
return prompt
if not project_root:
raise ValueError("project_root is required when search context injection is enabled")
if not self.base_url or not self.token:
raise ValueError(
"No authentication configured for search context injection. Set up session.json, AUGMENT_SESSION_AUTH, or ACE_API_URL/ACE_API_TOKEN"
)
result = self._remote_search_with_empty_fallback(project_root, prompt)
ctx = self._normalize_search_context(self._search_result_text(result))
return self._build_prompt_with_search_context(prompt, ctx)
def _get_third_party_model(self) -> str:
if self.third_party_model:
return self.third_party_model
return {
"claude": DEFAULT_CLAUDE_MODEL,
"openai": DEFAULT_OPENAI_MODEL,
"gemini": DEFAULT_GEMINI_MODEL,
"codex": DEFAULT_CODEX_MODEL,
}.get(self.endpoint, DEFAULT_MODEL)
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=2, max=10),
retry=retry_if_not_exception_type((IndexUploadError, IndexReadinessError)),
)
def search_context(self, project_root: str, query: str) -> dict:
"""Search codebase: remote via ACE API if available, else local fallback."""
if self.base_url and self.token:
try:
return self._remote_search_with_empty_fallback(project_root, query)
except (IndexUploadError, IndexReadinessError):
raise
except httpx.HTTPStatusError as e:
if e.response.status_code in (401, 403):
log.error("Auth failed (%d) for remote search: %s", e.response.status_code, e)
else:
log.warning("Remote search failed, falling back to local: %s", e)
except Exception as e:
log.warning("Remote search failed, falling back to local: %s", e)
return self._local_search(project_root, query)
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=2, max=10),
retry=retry_if_not_exception_type(ValueError),
)
def enhance_prompt(
self,
prompt: str,
conversation_history: str,
project_root: str | None = None,
) -> dict:
"""Enhance prompt with codebase context and conversation history."""
if self._is_third_party():
return self._call_third_party_api(prompt, conversation_history, project_root)
if not self.base_url:
return {"enhanced_prompt": prompt, "note": "No API configured, returning original"}
chat_history = parse_chat_history(conversation_history)
if self.endpoint == "old":
return self._call_old_endpoint(prompt, chat_history, project_root)
return self._call_new_endpoint(prompt, chat_history, project_root)
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=2, max=10),
retry=retry_if_not_exception_type(ValueError),
)
def iterative_enhance(
self,
original_prompt: str,
previous_enhanced: str,
current_prompt: str,
conversation_history: str,
project_root: str | None = None,
) -> dict:
"""Iteratively enhance an already-enhanced prompt, preserving user modifications."""
iterative_prompt = ITERATIVE_ENHANCE_TEMPLATE.format(
original_prompt=original_prompt,
previous_enhanced=previous_enhanced,
current_prompt=current_prompt,
)
if self._is_third_party():
return self._call_third_party_api_raw(iterative_prompt, conversation_history, project_root)
if not self.base_url:
return {"enhanced_prompt": current_prompt, "note": "No API configured, returning current"}
chat_history = parse_chat_history(conversation_history)
if self.endpoint == "old":
return self._call_old_endpoint_raw(iterative_prompt, chat_history, project_root)
return self._call_new_endpoint_raw(iterative_prompt, chat_history, project_root)
def _call_new_endpoint(self, prompt: str, chat_history: list[dict], project_root: str | None = None) -> dict:
"""Call /prompt-enhancer endpoint (new)."""
context = self._get_retrieval_context(project_root, prompt)
enriched_prompt = f"{context}{prompt}" if context else prompt
payload = {
"nodes": [{"id": 0, "type": 0, "text_node": {"content": enriched_prompt}}],
"chat_history": chat_history,
"conversation_id": None,
"model": DEFAULT_MODEL,
"mode": "CHAT",
}
data = self._post_json(
build_api_url(self.base_url, "/prompt-enhancer"),
payload,
headers=self._get_headers(),
)
return {"enhanced_prompt": data.get("text", prompt)}
def _call_new_endpoint_raw(
self, raw_prompt: str, chat_history: list[dict], project_root: str | None = None
) -> dict:
"""Call /prompt-enhancer with pre-built prompt."""
context = self._get_retrieval_context(project_root, raw_prompt)
enriched_prompt = f"{context}{raw_prompt}" if context else raw_prompt
payload = {
"nodes": [{"id": 0, "type": 0, "text_node": {"content": enriched_prompt}}],
"chat_history": chat_history,
"conversation_id": None,
"model": DEFAULT_MODEL,
"mode": "CHAT",
}
data = self._post_json(
build_api_url(self.base_url, "/prompt-enhancer"),
payload,
headers=self._get_headers(),
)
text = data.get("text", raw_prompt)
return {"enhanced_prompt": self._extract_enhanced_prompt(text)}
def _build_old_payload(
self, message: str, chat_history: list[dict], language_guideline: str, blob_names: list[str] | None = None
) -> dict:
"""Build payload for old endpoint."""
return {
"model": DEFAULT_MODEL,
"path": None,
"prefix": None,
"selected_code": None,
"suffix": None,
"message": message,
"chat_history": chat_history,
"lang": None,
"blobs": {"checkpoint_id": None, "added_blobs": blob_names or [], "deleted_blobs": []},
"user_guided_blobs": [],
"context_code_exchange_request_id": None,
"external_source_ids": [],
"disable_auto_external_sources": None,
"user_guidelines": language_guideline,
"workspace_guidelines": "",
"feature_detection_flags": {"support_parallel_tool_use": None},
"third_party_override": None,
"tool_definitions": [],
"nodes": [{"id": 1, "type": 0, "text_node": {"content": message}}],
"mode": "CHAT",
"agent_memories": None,
"persona_type": None,
"rules": [],
"silent": None,
"enable_parallel_tool_use": None,
"conversation_id": None,
"system_prompt": None,
}
def _get_blob_names(self, project_root: str | None) -> list[str] | None:
"""Get blob_names from indexer if API and project_root are available."""
if not project_root or not self.base_url or not self.token:
return None
with Indexer(project_root, self.base_url, self.token) as indexer:
names, _ = self._wait_for_index(indexer, indexer.get_blob_names())
if not names:
raise IndexReadinessError("Project has no indexable files; refusing an empty enhancement scope")
return names
def _get_retrieval_context(self, project_root: str | None, query: str) -> str:
"""Get cloud retrieval context to inject into prompts for non-old endpoints."""
if not project_root or not self.base_url or not self.token:
return ""
try:
result = self._remote_search_with_empty_fallback(project_root, query)
context = self._search_result_text(result)
if context:
return f"\n\n<codebase-context>\n{context}\n</codebase-context>\n\n"
except (IndexUploadError, IndexReadinessError):
raise
except httpx.HTTPStatusError as e:
if e.response.status_code in (401, 403):
log.error("Auth failed (%d) for cloud retrieval: %s", e.response.status_code, e)
else:
log.warning("Cloud retrieval failed, proceeding without context: %s", e)
except Exception as e:
log.warning("Cloud retrieval failed, proceeding without context: %s", e)
return ""
def _call_old_endpoint(self, prompt: str, chat_history: list[dict], project_root: str | None = None) -> dict:
"""Call /chat-stream endpoint (old, streaming)."""
final_prompt = ENHANCE_PROMPT_TEMPLATE.replace("{original_prompt}", prompt)
language_guideline = (
"Please respond in Chinese (Simplified Chinese). 请用中文回复。" if is_chinese_text(prompt) else ""
)
blob_names = self._get_blob_names(project_root)
payload = self._build_old_payload(final_prompt, chat_history, language_guideline, blob_names)
with httpx.Client(timeout=self.timeout) as client:
resp = client.post(
build_api_url(self.base_url, "/chat-stream"),
headers=self._get_headers(),
json=payload,
)
self._check_auth_error(resp.status_code)
resp.raise_for_status()
raw_text = self._parse_streaming_response(resp.text)
enhanced = self._extract_enhanced_prompt(raw_text)
enhanced = self._replace_tool_names(enhanced)
return {"enhanced_prompt": enhanced}
def _call_old_endpoint_raw(
self, raw_prompt: str, chat_history: list[dict], project_root: str | None = None
) -> dict:
"""Call /chat-stream with pre-built prompt."""
language_guideline = (
"Please respond in Chinese (Simplified Chinese). 请用中文回复。" if is_chinese_text(raw_prompt) else ""
)
blob_names = self._get_blob_names(project_root)
payload = self._build_old_payload(raw_prompt, chat_history, language_guideline, blob_names)
with httpx.Client(timeout=self.timeout) as client:
resp = client.post(
build_api_url(self.base_url, "/chat-stream"),
headers=self._get_headers(),
json=payload,
)
self._check_auth_error(resp.status_code)
resp.raise_for_status()
raw_text = self._parse_streaming_response(resp.text)
enhanced = self._extract_enhanced_prompt(raw_text)
enhanced = self._replace_tool_names(enhanced)
return {"enhanced_prompt": enhanced}
def _parse_streaming_response(self, body: str) -> str:
"""Parse streaming response from /chat-stream endpoint."""
combined = []
for line in body.split("\n"):
line = line.strip()
if not line or line.startswith("data:"):
line = line[5:].strip() if line.startswith("data:") else ""
if not line or line == "[DONE]":
continue
try:
data = json.loads(line)
if text := data.get("text"):
combined.append(text)
except json.JSONDecodeError:
continue
return "".join(combined) if combined else body
def _extract_enhanced_prompt(self, text: str) -> str:
"""Extract enhanced prompt from XML-like response."""
match = _ENHANCED_PROMPT_RE.search(text)
if match:
extracted = match.group(1).strip()
if extracted:
return extracted
return text
def _replace_tool_names(self, text: str) -> str:
"""Replace Augment-specific tool names with ace-tool names."""
return text.replace("codebase-retrieval", "search_context").replace("codebase_retrieval", "search_context")
def _post_json(
self,
url: str,
payload: dict,
*,
headers: dict,
provider: str = "API",
timeout: httpx.Timeout | None = None,
) -> dict:
with httpx.Client(timeout=timeout or self.timeout) as client:
resp = client.post(url, headers=headers, json=payload)
self._check_auth_error(resp.status_code, provider)
resp.raise_for_status()
return resp.json()
def _enhanced_prompt_from_text(self, text: str, fallback: str) -> dict:
enhanced = self._extract_enhanced_prompt(text) if text else fallback
return {"enhanced_prompt": self._replace_tool_names(enhanced)}
def _call_third_party_api(self, prompt: str, conversation_history: str, project_root: str | None = None) -> dict:
"""Call third-party API (Claude/OpenAI/Gemini/Codex)."""
if not self.third_party_base_url or not self.third_party_token:
raise ValueError(
f"PROMPT_ENHANCER_BASE_URL and PROMPT_ENHANCER_TOKEN required for '{self.endpoint}' endpoint"
)
chat_history = parse_chat_history(conversation_history)
model = self._get_third_party_model()
injected_prompt = self._maybe_inject_search_context(self.endpoint, prompt, project_root)
final_prompt = ENHANCE_PROMPT_TEMPLATE.replace("{original_prompt}", injected_prompt)
language_hint = "\n\n请用中文回复。" if is_chinese_text(prompt) else ""
full_prompt = f"{final_prompt}{language_hint}"
return self._dispatch_third_party(full_prompt, chat_history, model)
def _call_third_party_api_raw(
self, raw_prompt: str, conversation_history: str, project_root: str | None = None
) -> dict:
"""Call third-party API with pre-built prompt."""
if not self.third_party_base_url or not self.third_party_token:
raise ValueError(
f"PROMPT_ENHANCER_BASE_URL and PROMPT_ENHANCER_TOKEN required for '{self.endpoint}' endpoint"
)
chat_history = parse_chat_history(conversation_history)
model = self._get_third_party_model()
injected_prompt = self._maybe_inject_search_context(self.endpoint, raw_prompt, project_root)
language_hint = "\n\n请用中文回复。" if is_chinese_text(raw_prompt) else ""
full_prompt = f"{injected_prompt}{language_hint}"
return self._dispatch_third_party(full_prompt, chat_history, model)
def _dispatch_third_party(self, prompt: str, chat_history: list[dict], model: str) -> dict:
"""Dispatch to appropriate third-party API."""
if self.endpoint == "claude":
return self._call_claude_api(prompt, chat_history, model)
elif self.endpoint == "openai":
return self._call_openai_api(prompt, chat_history, model)
elif self.endpoint == "gemini":
return self._call_gemini_api(prompt, chat_history, model)
elif self.endpoint == "codex":
return self._call_codex_api(prompt, chat_history, model)
return {"error": f"Unknown endpoint: {self.endpoint}"}
@staticmethod
def _extract_codex_output_text(api_response: dict) -> str:
outputs = api_response.get("output", [])
final = [o for o in outputs if o.get("type") == "message" and o.get("phase") == "final_answer"]
candidates = final or [o for o in outputs if o.get("type") == "message"]
text_parts, refusal_parts = [], []
for msg in candidates:
for part in msg.get("content") or []:
t = part.get("type")
if t == "output_text":
txt = (part.get("text") or "").strip()
if txt:
text_parts.append(txt)
elif t == "refusal":
rf = (part.get("refusal") or "").strip()
if rf:
refusal_parts.append(rf)
if text_parts:
return "\n".join(text_parts)
if refusal_parts:
raise RuntimeError(f"Codex API refusal: {chr(10).join(refusal_parts)}")
raise RuntimeError("Codex API returned no output_text content")
def _call_codex_api(self, prompt: str, chat_history: list[dict], model: str) -> dict:
input_items = []
for msg in chat_history:
input_items.append({"role": msg["role"], "content": msg["content"]})
input_items.append({"role": "user", "content": prompt})
payload = {"model": model, "input": input_items}
if self.reasoning_effort:
payload["reasoning"] = {"effort": self.reasoning_effort}
url = build_api_url(self.third_party_base_url, "/v1/responses")
data = self._post_json(url, payload, headers=self._get_headers(use_third_party=True), provider="Codex")
text = self._extract_codex_output_text(data)
return self._enhanced_prompt_from_text(text, prompt)
def _call_claude_api(self, prompt: str, chat_history: list[dict], model: str) -> dict:
"""Call Claude API."""
messages = chat_history + [{"role": "user", "content": prompt}]
payload = {"model": model, "max_tokens": 4096, "messages": messages}
# ponytail: adaptive only; legacy thinking-enabled/budget models unmapped —
# unset effort if such an endpoint rejects adaptive.
if self.reasoning_effort:
if self.reasoning_effort == "none":
payload["thinking"] = {"type": "disabled"}
else:
payload["thinking"] = {"type": "adaptive"}
payload["output_config"] = {"effort": self.reasoning_effort}
url = build_api_url(self.third_party_base_url, "/v1/messages")
data = self._post_json(
url,
payload,
headers={
"Content-Type": "application/json",
"x-api-key": self.third_party_token,
"anthropic-version": "2023-06-01",
},
provider="Claude",
)
text = "".join(c.get("text", "") for c in data.get("content", []) if c.get("type") == "text")
return self._enhanced_prompt_from_text(text, prompt)
def _call_openai_api(self, prompt: str, chat_history: list[dict], model: str) -> dict:
"""Call OpenAI API."""
messages = chat_history + [{"role": "user", "content": prompt}]
payload = {"model": model, "messages": messages, "max_tokens": 4096}
if self.reasoning_effort:
payload["reasoning_effort"] = self.reasoning_effort
url = build_api_url(self.third_party_base_url, "/v1/chat/completions")
data = self._post_json(url, payload, headers=self._get_headers(use_third_party=True), provider="OpenAI")
text = data.get("choices", [{}])[0].get("message", {}).get("content", "")
return self._enhanced_prompt_from_text(text, prompt)
def _call_gemini_api(self, prompt: str, chat_history: list[dict], model: str) -> dict:
"""Call Gemini API."""
contents = []
for msg in chat_history:
role = "user" if msg["role"] == "user" else "model"
contents.append({"role": role, "parts": [{"text": msg["content"]}]})
contents.append({"role": "user", "parts": [{"text": prompt}]})
payload = {"contents": contents, "generationConfig": {"maxOutputTokens": 4096}}
# Gemini 3 has no "none" thinking level; "minimal" is its lowest.
if self.reasoning_effort:
level = "minimal" if self.reasoning_effort == "none" else self.reasoning_effort
payload["generationConfig"]["thinkingConfig"] = {"thinkingLevel": level}
url = build_api_url(self.third_party_base_url, f"/v1beta/models/{model}:generateContent")
data = self._post_json(
url,
payload,
headers={"Content-Type": "application/json", "x-goog-api-key": self.third_party_token},
provider="Gemini",
)
text = data.get("candidates", [{}])[0].get("content", {}).get("parts", [{}])[0].get("text", "")
return self._enhanced_prompt_from_text(text, prompt)
def _check_auth_error(self, status: int, provider: str = "API"):
if status == 401:
raise httpx.HTTPStatusError(
f"{provider} token invalid or expired",
request=None,
response=httpx.Response(status),
)
if status == 403:
raise httpx.HTTPStatusError(
f"{provider} access denied, token may be disabled",
request=None,
response=httpx.Response(status),
)
def _wait_for_index(
self, indexer: Indexer, blob_names: list[str], *, allow_rebuild: bool = True
) -> tuple[list[str], bool]:
"""Wait for all scoped blobs; recover missing blobs at most once."""
deadline = time.monotonic() + READINESS_TIMEOUT
rebuilt = False
while blob_names:
remaining = deadline - time.monotonic()
if remaining <= 0:
raise IndexReadinessError("Index readiness timed out while blobs were still pending")
payload = {"blobs": {"checkpoint_id": None, "added_blobs": blob_names, "deleted_blobs": []}}
timeout = httpx.Timeout(min(remaining, RETRIEVAL_TIMEOUT), connect=min(remaining, 15.0))
try:
status = self._post_json(
build_api_url(self.base_url, "/agents/blob-status"),
payload,
headers=self._get_headers(),
timeout=timeout,
)
except httpx.HTTPStatusError as e:
if e.response.status_code in (404, 405, 501):
raise IndexReadinessError("Server does not support the blob readiness status endpoint") from e
raise IndexReadinessError(
f"Blob readiness status request failed (HTTP {e.response.status_code})"
) from e
except (httpx.TransportError, ValueError) as e:
raise IndexReadinessError("Blob readiness status request failed or returned invalid JSON") from e
if time.monotonic() >= deadline:
raise IndexReadinessError("Index readiness timed out before the status response arrived")
if not isinstance(status, dict):
raise IndexReadinessError("Invalid blob readiness status response")
unknown = status.get("unknown_blob_names")
pending = status.get("nonindexed_blob_names")
checkpoint_not_found = status.get("checkpoint_not_found")
if (
not isinstance(unknown, list)
or not isinstance(pending, list)
or not all(isinstance(name, str) for name in unknown + pending)
or type(checkpoint_not_found) is not bool
or not set(unknown + pending).issubset(blob_names)
or set(unknown) & set(pending)
):
raise IndexReadinessError("Invalid blob readiness status response")
if checkpoint_not_found:
raise IndexReadinessError("Blob readiness checkpoint was not found")
if unknown:
if rebuilt or not allow_rebuild:
raise IndexReadinessError("Server still reports unknown blobs after index rebuild")
log.warning("Server reports unknown blobs; rebuilding index once")
blob_names = indexer.force_rebuild()
rebuilt = True
continue
if not pending:
return blob_names, rebuilt
remaining = deadline - time.monotonic()
if remaining > 0:
time.sleep(min(READINESS_POLL_INTERVAL, remaining))
return blob_names, rebuilt
def _remote_search(self, project_root: str, query: str) -> dict:
"""Search only after the scoped blobs have been confirmed ready."""
with Indexer(project_root, self.base_url, self.token) as indexer:
blob_names, rebuilt = self._wait_for_index(indexer, indexer.get_blob_names())
data = {}
if blob_names:
url = build_api_url(self.base_url, "/agents/codebase-retrieval")
payload = {
"information_request": query,
"blobs": {"checkpoint_id": None, "added_blobs": blob_names, "deleted_blobs": []},
"dialog": [],
"max_output_length": 0,
"disable_codebase_retrieval": False,
"enable_commit_retrieval": False,
}
timeout = httpx.Timeout(RETRIEVAL_TIMEOUT, connect=15.0)
try:
data = self._post_json(url, payload, headers=self._get_headers(), timeout=timeout)
except httpx.HTTPStatusError as e:
if e.response.status_code != 400 or "unknown blob" not in e.response.text.lower():
raise
if rebuilt:
raise IndexReadinessError("Server reports unknown blobs after index rebuild") from e
log.warning("Server reports unknown blobs; rebuilding index and retrying once")
blob_names, _ = self._wait_for_index(indexer, indexer.force_rebuild(), allow_rebuild=False)
if blob_names:
payload["blobs"]["added_blobs"] = blob_names
try:
data = self._post_json(url, payload, headers=self._get_headers(), timeout=timeout)
except httpx.HTTPStatusError as retry_error:
if (
retry_error.response.status_code == 400
and "unknown blob" in retry_error.response.text.lower()
):
raise IndexReadinessError(
"Server reports unknown blobs after index rebuild"
) from retry_error
raise
return {
"results": data.get("formatted_retrieval", ""),
"query": query,
"mode": "remote",
"blob_count": len(blob_names),
}
def _local_search(self, project_root: str, query: str) -> dict:
"""Fallback local search using keyword matching."""
results = []
keywords = [w.lower() for w in re.findall(r"\w+", query.lower()) if len(w) > 2]
# Share the indexer's filters and verified root, so fallback cannot expose
# files that the user excluded from the remote index.
with Indexer(project_root, "", "") as indexer:
for file_path in indexer._walk_files():
rel = file_path.relative_to(indexer.root).as_posix()
try:
with indexer._guard.open_verified(rel.split("/")) as safe:
raw = safe.read_bytes(MAX_BLOB_SIZE)
except (UnsafePathError, FileTooLargeError, OSError):
continue
content = decode_bytes(raw, ENCODING_CHAIN)
if content is None:
continue
content = content.lower()
score = sum(1 for kw in keywords if kw in content)
if score > 0:
results.append({"file": rel, "score": score})
results.sort(key=lambda x: x["score"], reverse=True)
return {"results": results[:10], "query": query, "mode": "local_fallback"}
def get_config(self) -> dict:
"""Get current configuration."""
return {
"base_url": self.base_url or "(not configured)",
"endpoint": self.endpoint,
"endpoint_effective": self.endpoint,
"endpoint_env_ready": bool(self.third_party_base_url and self.third_party_token)
if self._is_third_party()
else bool(self.base_url and self.token),
"token_configured": bool(self.token),
"third_party_configured": bool(self.third_party_base_url and self.third_party_token),
"auth_source": self.auth_source,
"search_context_injection": self._should_include_search_context(),
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |