tether-sdk 0.0.2__py3-none-any.whl

tether/__init__.py

@@ -0,0 +1,35 @@
+"""Tether: General-purpose, headless-first LLM-Native micro-harness."""
+
+from __future__ import annotations
+
+from tether.decorator import ToolSpec, tool
+from tether.harness import Harness
+from tether.providers import (
+    ActionCall,
+    ModelProvider,
+    ModelResponse,
+    extract_fallback_action,
+    register_provider,
+)
+from tether.sandbox import SandboxPolicy, SandboxViolationError
+from tether.skills import Skill, SkillLoader
+from tether.store import SessionRecord, SQLiteStore
+
+__version__ = "0.0.2"
+
+__all__ = [
+    "ActionCall",
+    "Harness",
+    "ModelProvider",
+    "ModelResponse",
+    "SQLiteStore",
+    "SandboxPolicy",
+    "SandboxViolationError",
+    "SessionRecord",
+    "Skill",
+    "SkillLoader",
+    "ToolSpec",
+    "extract_fallback_action",
+    "register_provider",
+    "tool",
+]

tether/cli.py

@@ -0,0 +1,235 @@
+"""Headless-capable CLI entrypoint for Tether (`tether run|status|read|query|send|wait|list`)."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+from tether.harness import Harness
+from tether.sandbox import SandboxPolicy
+from tether.store import SQLiteStore
+
+_KNOWN_SUBCOMMANDS = {"run", "status", "read", "query", "send", "wait", "list", "_worker"}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tether",
+        description="Tether: Headless-first LLM-Native Micro-Harness",
+    )
+    sub = parser.add_subparsers(dest="subcommand")
+
+    # `tether run`
+    p_run = sub.add_parser("run", help="Run a task inline or as a detached headless session")
+    p_run.add_argument(
+        "--headless", action="store_true", help="Run detached in background and print session ID"
+    )
+    p_run.add_argument(
+        "--model", type=str, default=None, help="Model (e.g. ollama/qwen3.5:9b, openai/gpt-4o-mini)"
+    )
+    p_run.add_argument(
+        "--skill", type=str, default=None, help="Skill name from ./skills/ or ~/.tether/skills/"
+    )
+    p_run.add_argument(
+        "--tools", type=str, default=None, help="Comma-separated tools (e.g. web,mem,bash or all)"
+    )
+    p_run.add_argument(
+        "--sandbox",
+        type=str,
+        default="workspace-write",
+        choices=["workspace-write", "read-only"],
+        help="Deterministic sandbox profile",
+    )
+    p_run.add_argument("--max-steps", type=int, default=15, help="Max reasoning steps")
+    p_run.add_argument(
+        "--db", type=str, default=None, help="SQLite DB path (default .tether/tether.db)"
+    )
+    p_run.add_argument("goal", nargs="+", help="Task goal or instruction")
+
+    # `tether status`
+    p_status = sub.add_parser("status", help="Show live session status and token metrics")
+    p_status.add_argument("session_id", help="Session ID (e.g. ses_...)")
+    p_status.add_argument("--db", type=str, default=None)
+
+    # `tether read`
+    p_read = sub.add_parser("read", help="Read session final result, compact digest, or step log")
+    p_read.add_argument("session_id", help="Session ID")
+    p_read.add_argument("--digest", action="store_true", help="Show compact ~50-token digest card")
+    p_read.add_argument("--steps", action="store_true", help="Show step-by-step work log")
+    p_read.add_argument("--db", type=str, default=None)
+
+    # `tether query`
+    p_query = sub.add_parser(
+        "query", help="BM25 FTS5 RAG query over session deliverables & observations"
+    )
+    p_query.add_argument("session_id", help="Session ID")
+    p_query.add_argument("query", nargs="+", help="Search keywords")
+    p_query.add_argument("--top", type=int, default=3, help="Top K chunks to return")
+    p_query.add_argument("--db", type=str, default=None)
+
+    # `tether send`
+    p_send = sub.add_parser(
+        "send", help="Send a follow-up message to a running or completed session"
+    )
+    p_send.add_argument("session_id", help="Session ID")
+    p_send.add_argument("--headless", action="store_true", help="Resume in background if completed")
+    p_send.add_argument("--db", type=str, default=None)
+    p_send.add_argument("message", nargs="+", help="Follow-up instruction")
+
+    # `tether wait`
+    p_wait = sub.add_parser("wait", help="Wait for one or more headless sessions to finish")
+    p_wait.add_argument("session_ids", nargs="+", help="Session ID(s)")
+    p_wait.add_argument("--timeout", type=float, default=120.0)
+    p_wait.add_argument("--db", type=str, default=None)
+
+    # `tether list`
+    p_list = sub.add_parser("list", help="List recent sessions")
+    p_list.add_argument("--limit", type=int, default=20)
+    p_list.add_argument("--db", type=str, default=None)
+
+    # Internal `_worker`
+    p_worker = sub.add_parser("_worker")
+    p_worker.add_argument("session_id")
+    p_worker.add_argument("--db", type=str, default=None)
+
+    return parser
+
+
+async def _async_main(argv: list[str]) -> int:
+    # Support shorthand `tether --headless "Goal"` by inserting `run` if needed
+    effective_argv = list(argv)
+    if (
+        effective_argv
+        and effective_argv[0] not in _KNOWN_SUBCOMMANDS
+        and effective_argv[0] not in ("-h", "--help")
+    ):
+        effective_argv.insert(0, "run")
+
+    parser = build_parser()
+    if not effective_argv:
+        parser.print_help()
+        return 0
+
+    ns = parser.parse_args(effective_argv)
+    cmd = ns.subcommand
+
+    if cmd == "_worker":
+        harness = Harness(db_path=ns.db)
+        await harness.execute_session(ns.session_id)
+        return 0
+
+    if cmd == "run":
+        goal = " ".join(ns.goal).strip()
+        sandbox = SandboxPolicy(profile=ns.sandbox, workspace_root=Path.cwd())
+        harness = Harness(
+            model=ns.model,
+            skill=ns.skill,
+            tools=ns.tools,
+            sandbox=sandbox,
+            db_path=ns.db,
+            max_steps=ns.max_steps,
+        )
+        if ns.headless:
+            sid = harness.spawn(goal)
+            print(sid)
+            return 0
+        rec = await harness.run(goal)
+        if rec.result:
+            print(rec.result)
+        return 0 if rec.status == "COMPLETED" else 1
+
+    store = SQLiteStore(db_path=getattr(ns, "db", None))
+
+    if cmd == "status":
+        srec = store.get_session(ns.session_id)
+        if not srec:
+            print(f"Error: session `{ns.session_id}` not found.", file=sys.stderr)
+            return 1
+        turns = store.get_turns(srec.id)
+        last_cmd = next((t.tool_cmd for t in reversed(turns) if t.tool_cmd), "-")
+        print(
+            f"{'ID':<14} {'STATUS':<10} {'MODEL':<22} {'STEP':<7} {'PEAK_TOK':<9} LAST_CMD\n"
+            f"{srec.id:<14} {srec.status:<10} {srec.model:<22} "
+            f"{srec.step_count}/{srec.max_steps:<4} {srec.peak_tokens:<9} {last_cmd}"
+        )
+        return 0
+
+    if cmd == "read":
+        srec = store.get_session(ns.session_id)
+        if not srec:
+            print(f"Error: session `{ns.session_id}` not found.", file=sys.stderr)
+            return 1
+        if ns.steps:
+            turns = store.get_turns(srec.id)
+            for t in turns:
+                if t.tool_cmd:
+                    print(f"[step {t.step}] act({t.tool_cmd!r})")
+                else:
+                    print(f"[step {t.step} {t.role}] {t.content[:200]}")
+            return 0
+        if ns.digest:
+            print(store.get_session_digest(srec.id))
+            return 0
+        print(srec.result or store.get_session_digest(srec.id))
+        return 0
+
+    if cmd == "query":
+        q = " ".join(ns.query).strip()
+        hits = store.search_chunks(q, session_ids=[ns.session_id], top_k=ns.top)
+        if not hits:
+            print(f"No BM25 RAG chunks matched `{q}`.")
+            return 0
+        for h in hits:
+            print(f"[{h.session_id} {h.source_type}:{h.source_id}#{h.chunk_index}]\n{h.content}\n")
+        return 0
+
+    if cmd == "send":
+        msg = " ".join(ns.message).strip()
+        harness = Harness(db_path=ns.db)
+        rec = await harness.send(ns.session_id, msg, headless=ns.headless)
+        if ns.headless or rec.status in ("RUNNING", "PENDING"):
+            print(f"Message queued for `{rec.id}` [{rec.status}].")
+        else:
+            print(rec.result or f"[{rec.id} {rec.status}]")
+        return 0
+
+    if cmd == "wait":
+        elapsed = 0.0
+        while elapsed < ns.timeout:
+            if all(
+                (r := store.get_session(sid)) is None or r.status in ("COMPLETED", "FAILED")
+                for sid in ns.session_ids
+            ):
+                break
+            await asyncio.sleep(0.05)
+            elapsed += 0.05
+        for sid in ns.session_ids:
+            print(store.get_session_digest(sid))
+        return 0
+
+    if cmd == "list":
+        sessions = store.list_sessions(limit=ns.limit)
+        if not sessions:
+            print("No sessions recorded.")
+            return 0
+        print(f"{'ID':<14} {'STATUS':<10} {'MODEL':<22} {'STEP':<7} GOAL")
+        for s in sessions:
+            g = s.goal.replace("\n", " ")[:48]
+            print(f"{s.id:<14} {s.status:<10} {s.model:<22} {s.step_count}/{s.max_steps:<4} {g}")
+        return 0
+
+    parser.print_help()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = sys.argv[1:] if argv is None else argv
+    code = asyncio.run(_async_main(args))
+    if argv is None:
+        raise SystemExit(code)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

tether/context.py

@@ -0,0 +1,170 @@
+"""State Plane: ContextAssembler, Ephemeral Observation Folding, and Token Estimator."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from tether.store import ObservationRecord, TurnRecord
+
+ACT_TOOL_SCHEMA: dict[str, Any] = {
+    "type": "function",
+    "function": {
+        "name": "act",
+        "description": "Run a CLI command from the toolbox.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "cmd": {"type": "string", "description": "CLI command or `<cmd> --help`"},
+                "stdin": {"type": "string", "description": "Optional multiline input"},
+            },
+            "required": ["cmd"],
+        },
+    },
+}
+
+
+def estimate_tokens(text: str) -> int:
+    """Fast deterministic token approximation (~4 chars per token)."""
+    if not text:
+        return 0
+    return max(1, (len(text) + 3) // 4)
+
+
+def estimate_messages_tokens(
+    messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None = None
+) -> int:
+    """Estimate total tokens across messages and tool schema payload."""
+    total = 0
+    for msg in messages:
+        total += 4  # framing overhead per message
+        total += estimate_tokens(str(msg.get("content") or ""))
+        if msg.get("tool_calls"):
+            total += estimate_tokens(json.dumps(msg["tool_calls"]))
+    if tools:
+        total += estimate_tokens(json.dumps(tools))
+    return total
+
+
+def elide_active_observation(obs_id: str, raw_output: str, max_chars: int = 2400) -> str:
+    """Slice oversized active observations into Head + Tail in L1."""
+    if len(raw_output) <= max_chars:
+        return f"[{obs_id}] {raw_output}"
+    head_len = int(max_chars * 0.6)
+    tail_len = max_chars - head_len
+    elided_count = len(raw_output) - (head_len + tail_len)
+    head = raw_output[:head_len].rstrip()
+    tail = raw_output[-tail_len:].lstrip()
+    marker = (
+        f"\n... [{obs_id}: {elided_count:,} middle chars elided in L1 | "
+        f"use `mem search <query>` or `mem recall {obs_id}`] ...\n"
+    )
+    return f"[{obs_id}] {head}{marker}{tail}"
+
+
+class ContextAssembler:
+    """Assembles KV-cache-friendly prompts with deterministic observation folding."""
+
+    def __init__(
+        self,
+        *,
+        fold_after_turns: int = 2,
+        fold_char_threshold: int = 200,
+        active_char_cap: int = 2400,
+        max_context_tokens: int = 8192,
+    ) -> None:
+        self.fold_after_turns = fold_after_turns
+        self.fold_char_threshold = fold_char_threshold
+        self.active_char_cap = active_char_cap
+        self.max_context_tokens = max_context_tokens
+        self._static_system_prompt: str | None = None
+
+    def build_system_prompt(
+        self,
+        toolbox_index: str,
+        skill_instructions: str | None = None,
+    ) -> str:
+        """Build the immutable system prompt prefix once per session."""
+        if self._static_system_prompt is not None:
+            return self._static_system_prompt
+
+        parts = [
+            "You are an autonomous agent on Tether.",
+            "Use `act(cmd, stdin)` to run commands. Run `<cmd> --help` for flags.",
+            'Call `act("done", stdin="<final answer>")` when finished.',
+            "",
+            "[TOOLBOX]",
+            toolbox_index,
+        ]
+        if skill_instructions and skill_instructions.strip():
+            parts.extend(["", "[SKILL]", skill_instructions.strip()])
+
+        self._static_system_prompt = "\n".join(parts)
+        return self._static_system_prompt
+
+    def assemble(
+        self,
+        *,
+        system_prompt: str,
+        goal: str,
+        turns: list[TurnRecord],
+        observations: dict[str, ObservationRecord],
+        pins: dict[str, str],
+        current_step: int,
+    ) -> list[dict[str, Any]]:
+        """Assemble the message array while preserving the static prefix and folding old outputs."""
+        messages: list[dict[str, Any]] = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": f"Goal: {goal}"},
+        ]
+
+        history_msgs: list[dict[str, Any]] = []
+        for turn in turns:
+            content = turn.content
+            if turn.obs_id and turn.obs_id in observations:
+                obs = observations[turn.obs_id]
+                age = current_step - turn.step
+                if age >= self.fold_after_turns and obs.char_len >= self.fold_char_threshold:
+                    content = obs.summary
+                else:
+                    content = elide_active_observation(
+                        obs.id, obs.raw_output, max_chars=self.active_char_cap
+                    )
+
+            if turn.role == "assistant" and turn.tool_cmd:
+                call_preview = f"act({turn.tool_cmd!r})"
+                if turn.tool_stdin:
+                    call_preview = f"act({turn.tool_cmd!r}, stdin=<{len(turn.tool_stdin)} chars>)"
+                text = f"{content}\n{call_preview}".strip() if content else call_preview
+                history_msgs.append({"role": "assistant", "content": text})
+            elif turn.role == "tool":
+                history_msgs.append({"role": "user", "content": f"Observation:\n{content}"})
+            else:
+                history_msgs.append({"role": turn.role, "content": content})
+
+        pin_block = ""
+        if pins:
+            pin_lines = ["[PINNED MEMORY]"] + [f"- {k}: {v}" for k, v in pins.items()]
+            pin_block = "\n".join(pin_lines)
+
+        # Enforce max_context_tokens by dropping oldest turns if needed
+        base_tokens = estimate_messages_tokens(messages, [ACT_TOOL_SCHEMA]) + estimate_tokens(
+            pin_block
+        )
+        while len(history_msgs) > 2:
+            total = base_tokens + estimate_messages_tokens(history_msgs)
+            if total <= self.max_context_tokens:
+                break
+            history_msgs.pop(0)
+
+        if pin_block:
+            if history_msgs and history_msgs[-1]["role"] == "user":
+                history_msgs[-1] = {
+                    "role": "user",
+                    "content": f"{history_msgs[-1]['content']}\n\n{pin_block}",
+                }
+            else:
+                history_msgs.append({"role": "user", "content": pin_block})
+
+        messages.extend(history_msgs)
+        return messages