stark-ai-de/agent-skills / plugins/stark-ai-developer/skills/jev-capability-advisor
jev-capability-advisor
VerifiedRecommend available skills or MCP tools using TypeSafe Jev, or explicitly choose one next skill. Use when the user requests capability advice, candidate inspection, selection evaluation, or reusable host integration. Native client selection remains the default and fallback.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.6 KB |
| agents/openai.yaml | config | 615 B |
| assets/hook-guidance.txt | markdown | 1.1 KB |
| assets/openai-icon.png | binary | 15.2 KB |
| assets/openai-icon.svg | other | 504 B |
| assets/repository-hook-guidance.txt | markdown | 1.2 KB |
| references/contract.md | markdown | 24.8 KB |
| references/enabled-hook-entry.md | markdown | 3.6 KB |
| references/hook-catalog.md | markdown | 7.5 KB |
| references/hook-integration.md | markdown | 41.7 KB |
| references/network-access.md | markdown | 6.6 KB |
| references/script-inventory.md | markdown | 1.9 KB |
| references/session-integration.md | markdown | 10.7 KB |
| scripts/decision_cache.py | script | 4.5 KB |
| scripts/hook_catalog.py | script | 9.3 KB |
| scripts/https_transport.py | script | 14.0 KB |
| scripts/index_cache.py | script | 12.7 KB |
| scripts/jev_advisor.py | script | 48.2 KB |
| scripts/jev_hooks.py | script | 44.3 KB |
| scripts/jev_session.py | script | 18.5 KB |
| scripts/retrieval.py | script | 17.1 KB |
| scripts/routing_metadata.py | script | 3.3 KB |
scripts/https_transport.py
View on GitHub"""Session-scoped, fixed-endpoint JSON HTTPS transport; no automatic POST retry.
Use ``with JsonClient(key) as client: result = client(payload)``. Each instance
owns one credential, one verified TLS context and at most one direct connection.
Configured proxies use a fresh standard urllib opener instead of direct pooling.
Only safe transport metadata appears in ``last_receipt``; no logging is done.
"""
import http.client
import io
import json
import math
import ssl
import threading
import time
import urllib.error
import urllib.request
ENDPOINT = 'https://api.typesafe.ai/v1/systemone'
HOST = 'api.typesafe.ai'
PORT = 443
API_PATH = '/v1/systemone'
MAX_RESPONSE_BYTES = 2_000_000
MAX_REQUEST_BYTES = 90_000
def _remaining(deadline):
remaining = deadline - time.monotonic()
if remaining <= 0:
raise TimeoutError('request_timeout')
return remaining
def _check_context(context):
if not context.check_hostname or context.verify_mode != ssl.CERT_REQUIRED:
raise ValueError('unverified_tls_context')
class _DeadlineRaw(io.RawIOBase):
"""Keep socket-file ownership semantics while bounding every underlying read."""
def __init__(self, raw, sock, deadline):
super().__init__()
self._raw, self._sock, self._deadline = raw, sock, deadline
def readable(self):
return True
def readinto(self, buffer):
self._sock.settimeout(_remaining(self._deadline))
result = self._raw.readinto(buffer)
_remaining(self._deadline)
return result
def close(self):
try:
self._raw.close()
finally:
super().close()
class _DeadlineSocket:
"""HTTPResponse uses our bounded reader; its raw file retains the socket ref."""
def __init__(self, sock, deadline):
self._sock, self.deadline = sock, deadline
def __getattr__(self, name):
return getattr(self._sock, name)
def makefile(self, mode='rb', buffering=None):
if mode != 'rb':
raise ValueError('unsupported_response_file_mode')
raw = self._sock.makefile('rb', buffering=0)
return io.BufferedReader(_DeadlineRaw(raw, self._sock, self.deadline))
def sendall(self, data):
self._sock.settimeout(_remaining(self.deadline))
self._sock.sendall(data)
_remaining(self.deadline)
class _Connection(http.client.HTTPSConnection):
def __init__(self, context, deadline):
_check_context(context)
super().__init__(HOST, PORT, context=context, timeout=_remaining(deadline))
self.deadline = deadline
self._connected_once = False
def connect(self):
if self._connected_once or self.host != HOST or self.port != PORT or self._tunnel_host:
raise ValueError('unexpected_reconnect_or_endpoint')
self._connected_once = True
# Preserve HTTPConnection TCP_NODELAY, then give TLS only the budget
# remaining after TCP/DNS rather than the original socket timeout.
http.client.HTTPConnection.connect(self)
self.sock.settimeout(_remaining(self.deadline))
self.sock = self._context.wrap_socket(self.sock, server_hostname=HOST)
_remaining(self.deadline)
self.sock = _DeadlineSocket(self.sock, self.deadline)
# send() must raise NotConnected instead of opening/replaying implicitly.
self.auto_open = 0
def use_deadline(self, deadline):
self.deadline = deadline
if self.sock is None:
raise http.client.NotConnected()
self.sock.deadline = deadline
self.sock.settimeout(_remaining(deadline))
class _NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
def _safe_exception(error):
"""Do not preserve server echoes, proxy values, headers or exception strings."""
if isinstance(error, urllib.error.HTTPError):
return urllib.error.HTTPError(ENDPOINT, error.code, 'HTTP status error', None, None)
if isinstance(error, TimeoutError):
return TimeoutError('request_timeout')
if isinstance(error, urllib.error.URLError):
return urllib.error.URLError('network_error')
if isinstance(error, (json.JSONDecodeError, UnicodeError)):
return ValueError('invalid_response_json')
if isinstance(error, ValueError) and str(error) in {
'request_budget_exceeded', 'response_too_large', 'unverified_tls_context',
'unexpected_reconnect_or_endpoint', 'unsupported_response_file_mode', 'invalid_request_payload',
}:
return ValueError(str(error))
return urllib.error.URLError(type(error).__name__)
def _error_code(error):
if isinstance(error, urllib.error.HTTPError):
return 'http_' + str(error.code)
if isinstance(error, TimeoutError):
return 'request_timeout'
if isinstance(error, ValueError):
return str(error)
return 'network_error'
class JsonClient:
"""Reusable callable transport, serialized per instance; close after a session.
timeout_seconds covers lock acquisition, setup, I/O and decoding. Socket
operations and each direct header/body read use the remaining deadline.
System DNS and certificate-store calls retain the standard library's native
blocking behavior; there is no claim of forcibly interrupting those calls.
Request timeouts are never retried because server-side completion is unknown.
"""
transport_kind = 'https'
def __init__(self, key, *, timeout_seconds=30, idle_timeout_seconds=60):
if not isinstance(key, str) or not key.strip() or '\n' in key or '\r' in key:
raise ValueError('invalid_api_key')
if (isinstance(timeout_seconds, bool) or not isinstance(timeout_seconds, (int, float))
or not math.isfinite(timeout_seconds) or not 0 < timeout_seconds <= 300):
raise ValueError('invalid_timeout')
if (isinstance(idle_timeout_seconds, bool) or not isinstance(idle_timeout_seconds, (int, float))
or not math.isfinite(idle_timeout_seconds) or not 0 < idle_timeout_seconds <= 3600):
raise ValueError('invalid_idle_timeout')
self._key = key.strip()
self.timeout_seconds = float(timeout_seconds)
self.idle_timeout_seconds = float(idle_timeout_seconds)
self._lock = threading.Lock()
self._connection = None
self._context = None
self._last_used = None
self._closed = False
self.last_receipt = None
def __repr__(self):
return f'JsonClient(closed={self._closed})'
def __enter__(self):
if self._closed:
raise ValueError('client_closed')
return self
def __exit__(self, exc_type, exc, traceback):
self.close()
def _drop_connection(self):
if self._connection is not None:
try:
self._connection.close()
except OSError:
# A failed socket close must not replace the safe request error.
pass
finally:
self._connection = None
self._last_used = None
def close(self):
with self._lock:
self._drop_connection()
self._context = None
self._key = None
self._closed = True
def _direct(self, body, deadline, receipt):
if (self._connection is not None and (self._connection.sock is None or
(self._last_used is not None and time.monotonic() - self._last_used >= self.idle_timeout_seconds))):
self._drop_connection()
receipt['tls_context_reused'] = self._context is not None
if self._context is None:
self._context = ssl.create_default_context()
self._context.set_alpn_protocols(['http/1.1'])
_check_context(self._context)
_remaining(deadline)
reused = self._connection is not None
receipt.update(connection_reused=reused, connection_state='reused' if reused else 'cold')
if self._connection is None:
# Assign ownership before connect so a failed handshake is closed.
self._connection = _Connection(self._context, deadline)
self._connection.connect()
connection = self._connection
connection.use_deadline(deadline)
receipt['request_dispatched'] = True
connection.request('POST', API_PATH, body=body, headers={
'Authorization': 'Bearer ' + self._key,
'Content-Type': 'application/json',
'Connection': 'keep-alive',
})
connection.use_deadline(deadline)
response = connection.getresponse()
receipt['http_status'] = response.status
try:
if not 200 <= response.status < 300:
raise urllib.error.HTTPError(ENDPOINT, response.status, 'HTTP status error', None, None)
data = bytearray()
while True:
_remaining(deadline)
block = response.read1(min(65536, MAX_RESPONSE_BYTES + 1 - len(data)))
if not block:
break
data.extend(block)
receipt['response_bytes'] = len(data)
if len(data) > MAX_RESPONSE_BYTES:
raise ValueError('response_too_large')
if response.length is not None and response.length != 0:
raise http.client.IncompleteRead(bytes(data))
_remaining(deadline)
if response.will_close or connection.sock is None:
self._drop_connection()
return bytes(data)
finally:
response.close()
def _proxy(self, body, deadline, receipt, proxies):
# ProxyHandler honors the configured proxy and standard NO_PROXY rules.
# Do not put proxy URLs, authorization or returned headers in receipts.
self._drop_connection()
receipt.update(connection_state='proxy_fallback', connection_reused=False,
tls_context_reused=False)
context = ssl.create_default_context()
context.set_alpn_protocols(['http/1.1'])
_check_context(context)
opener = urllib.request.build_opener(
urllib.request.ProxyHandler(proxies), _NoRedirect(),
urllib.request.HTTPSHandler(context=context))
request = urllib.request.Request(ENDPOINT, data=body, method='POST', headers={
'Authorization': 'Bearer ' + self._key, 'Content-Type': 'application/json'})
receipt['request_dispatched'] = True
with opener.open(request, timeout=_remaining(deadline)) as response:
receipt['http_status'] = response.status
data = bytearray()
while True:
timeout = _remaining(deadline)
sock = getattr(getattr(getattr(response, 'fp', None), 'raw', None), '_sock', None)
if sock is not None:
sock.settimeout(timeout)
block = response.read1(min(65536, MAX_RESPONSE_BYTES + 1 - len(data)))
if not block:
break
data.extend(block)
receipt['response_bytes'] = len(data)
if len(data) > MAX_RESPONSE_BYTES:
raise ValueError('response_too_large')
if getattr(response, 'length', None) not in (None, 0):
raise http.client.IncompleteRead(bytes(data))
_remaining(deadline)
return bytes(data)
def __call__(self, payload, *, timeout_seconds=None):
started = time.monotonic()
budget = self.timeout_seconds if timeout_seconds is None else timeout_seconds
if (isinstance(budget, bool) or not isinstance(budget, (int, float))
or not math.isfinite(budget) or not 0 < budget <= 300):
raise ValueError('invalid_timeout')
deadline = started + budget
if not self._lock.acquire(timeout=_remaining(deadline)):
raise TimeoutError('request_timeout')
receipt = {'transport_kind': self.transport_kind, 'connection_state': 'none',
'connection_reused': False, 'tls_context_reused': False,
'request_dispatched': False, 'request_bytes': 0, 'response_bytes': 0,
'http_status': None, 'elapsed_ms': 0.0, 'timeout_seconds': budget, 'error': None}
try:
if self._closed:
raise ValueError('client_closed')
try:
body = json.dumps(payload, ensure_ascii=False, separators=(',', ':'),
sort_keys=True, allow_nan=False).encode('utf-8')
except (TypeError, ValueError, UnicodeError):
raise ValueError('invalid_request_payload') from None
receipt['request_bytes'] = len(body)
if len(body) > MAX_REQUEST_BYTES:
raise ValueError('request_budget_exceeded')
proxies = urllib.request.getproxies()
if proxies:
raw = self._proxy(body, deadline, receipt, proxies)
else:
raw = self._direct(body, deadline, receipt)
result = json.loads(raw.decode('utf-8'))
_remaining(deadline)
self._last_used = time.monotonic() if self._connection is not None else None
return result
except Exception as error:
self._drop_connection()
safe = ValueError('client_closed') if self._closed else _safe_exception(error)
if isinstance(error, urllib.error.HTTPError):
# urllib HTTP errors own a response stream even when redirects
# or status codes are rejected before entering a context manager.
try:
error.close()
except Exception:
pass # Cleanup cannot replace the sanitized error or expose its context.
receipt['error'] = _error_code(safe)
# Suppress implicit exception chaining, which could otherwise expose
# proxy credentials or upstream exception messages in tracebacks.
raise safe from None
finally:
receipt['elapsed_ms'] = (time.monotonic() - started) * 1000
self.last_receipt = receipt
self._lock.release()
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 |