doubleoh 0.1.0__tar.gz

doubleoh-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.worktrees/
+.superpowers/
+
+# Claude Code: .claude/skills/ is shared, the rest is local state
+.claude/worktrees/
+.claude/settings.local.json
+docs/superpowers/
+
+docs/specs/
+docs/plans/
+.env
+.env.*
+!.env.example
+node_modules/
+**/dist/
+app/src/lib/generated/application-config.ts
+.logs/
+.demo-logs/
+**/.impeccable
+.wave-state.md
+
+# TanStack Router scratch output
+app/.tanstack/
+openbot.apk
+# Generated by `bunx cap add android`; rebuilt from capacitor.config.ts.
+# Kept: `cap sync` regenerates the manifest, and the microphone permission lives here.
+!app/android-overrides/
+app/android/

doubleoh-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: doubleoh
+Version: 0.1.0
+Summary: Your agents learn from every fix. Stop failing the same way twice.
+License: Proprietary
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# doubleoh
+
+**Your agents learn from every fix. Stop failing the same way twice.**
+
+When your agent gets stuck on a real website, one of *your* people fixes it once in a live
+browser. That fix compiles into a skill. The next time any agent in your fleet hits the same
+wall, it follows the skill instead of asking a human.
+
+```bash
+pip install doubleoh
+```
+
+Zero dependencies — it is `urllib` and dataclasses.
+
+## The loop, in code
+
+```python
+from doubleoh import DoubleOh
+
+doubleoh = DoubleOh(api_key=os.environ["DOUBLEOH_API_KEY"])
+
+# 1. Before your agent tries something it has failed at before, ask what has been learned.
+skills = doubleoh.skills_for("check out on the supplier portal")
+if skills and skills[0].times_worked > skills[0].times_failed:
+    prompt += f"\n\nA colleague has done this before:\n{skills[0].instructions}"
+
+# 2. Your agent runs. When it gets stuck, ask for a human.
+fix = doubleoh.request_fix(url=page.url, task="Check out on the supplier portal")
+if fix.deflected:
+    # Nobody was paged: the fleet already knows this wall. Retry with the skill.
+    prompt += fix.skill.instructions
+elif fix.fix_url:
+    slack.send(f"An agent needs a hand: {fix.fix_url}")
+# fix.duplicate_of set? The wall is already waiting on a human — fix.blocked_runs says
+# how many runs are stuck on it. Your retry loop needs no change; nobody gets re-paged.
+
+# 3. Close the loop: say whether the skill worked. This is what makes the counts mean
+#    something, and a skill followed three times that never works retires itself.
+doubleoh.report_skill(skills[0].name, worked=True)
+```
+
+You decide what "stuck" means — a timeout, a retry count, a model that says it cannot
+proceed. Only you know your agent.
+
+## API
+
+- `skills_for(task) -> list[LearnedSkill]` — what has been learned; put `instructions` in
+  your agent's context. `times_worked` / `times_failed` are raw counts on purpose: 5 for 5
+  is worth following, 1 for 1 is a guess that happened to work once.
+- `request_fix(url, task) -> Intervention` — ask for help. Three possible shapes: a
+  `fix_url` (a human was paged), `deflected=True` with `skill` (nobody was paged — you
+  already know the answer), or `duplicate_of` with `blocked_runs` (already waiting; triage
+  by the count). `url` must be a public page; private and loopback addresses are refused.
+- `report_skill(name, worked)` — one boolean; wire it to whatever already tells you a run
+  succeeded.
+- `intervention(id)` / `interventions()` — status; `skill_name` is the receipt.
+- `retire_skill(name, reason)` — stop serving a skill immediately.
+
+Errors raise `DoubleOhError` carrying the server's own message and the HTTP `status`.
+
+## What is recorded
+
+Fix sessions keep screenshots and the shape of each action. **Typed text is never
+recorded** — a fix session is exactly where a password gets typed, so keystrokes stay off
+the record entirely.
+
+## Framework adapters
+
+Every adapter serves the same three tools; pick your framework's line.
+
+```python
+from doubleoh import DoubleOh
+client = DoubleOh(api_key=os.environ["DOUBLEOH_API_KEY"])
+
+# LangChain / LangGraph
+from doubleoh.langchain import doubleoh_tools
+graph = create_react_agent(model, tools=doubleoh_tools(client))
+
+# CrewAI
+from doubleoh.crewai import doubleoh_tools
+agent = Agent(role="operator", tools=doubleoh_tools(client))
+
+# LlamaIndex
+from doubleoh.llamaindex import doubleoh_tools
+agent = ReActAgent.from_tools(doubleoh_tools(client), llm=llm)
+
+# OpenAI Agents SDK, AutoGen, Pydantic AI — all accept plain functions:
+from doubleoh.tools import build_tools
+skills_for, request_fix, report_skill = build_tools(client)
+agent = Agent(tools=[function_tool(skills_for), function_tool(request_fix), function_tool(report_skill)])
+```
+
+No framework is a dependency of this package: each adapter imports its framework lazily
+and, if it is missing, raises one sentence naming what to `pip install`.
+
+Using Claude or another MCP-capable agent? Skip the SDK entirely — `doubleoh-mcp` serves
+the same three tools over MCP.

doubleoh-0.1.0/README.md

@@ -0,0 +1,97 @@
+# doubleoh
+
+**Your agents learn from every fix. Stop failing the same way twice.**
+
+When your agent gets stuck on a real website, one of *your* people fixes it once in a live
+browser. That fix compiles into a skill. The next time any agent in your fleet hits the same
+wall, it follows the skill instead of asking a human.
+
+```bash
+pip install doubleoh
+```
+
+Zero dependencies — it is `urllib` and dataclasses.
+
+## The loop, in code
+
+```python
+from doubleoh import DoubleOh
+
+doubleoh = DoubleOh(api_key=os.environ["DOUBLEOH_API_KEY"])
+
+# 1. Before your agent tries something it has failed at before, ask what has been learned.
+skills = doubleoh.skills_for("check out on the supplier portal")
+if skills and skills[0].times_worked > skills[0].times_failed:
+    prompt += f"\n\nA colleague has done this before:\n{skills[0].instructions}"
+
+# 2. Your agent runs. When it gets stuck, ask for a human.
+fix = doubleoh.request_fix(url=page.url, task="Check out on the supplier portal")
+if fix.deflected:
+    # Nobody was paged: the fleet already knows this wall. Retry with the skill.
+    prompt += fix.skill.instructions
+elif fix.fix_url:
+    slack.send(f"An agent needs a hand: {fix.fix_url}")
+# fix.duplicate_of set? The wall is already waiting on a human — fix.blocked_runs says
+# how many runs are stuck on it. Your retry loop needs no change; nobody gets re-paged.
+
+# 3. Close the loop: say whether the skill worked. This is what makes the counts mean
+#    something, and a skill followed three times that never works retires itself.
+doubleoh.report_skill(skills[0].name, worked=True)
+```
+
+You decide what "stuck" means — a timeout, a retry count, a model that says it cannot
+proceed. Only you know your agent.
+
+## API
+
+- `skills_for(task) -> list[LearnedSkill]` — what has been learned; put `instructions` in
+  your agent's context. `times_worked` / `times_failed` are raw counts on purpose: 5 for 5
+  is worth following, 1 for 1 is a guess that happened to work once.
+- `request_fix(url, task) -> Intervention` — ask for help. Three possible shapes: a
+  `fix_url` (a human was paged), `deflected=True` with `skill` (nobody was paged — you
+  already know the answer), or `duplicate_of` with `blocked_runs` (already waiting; triage
+  by the count). `url` must be a public page; private and loopback addresses are refused.
+- `report_skill(name, worked)` — one boolean; wire it to whatever already tells you a run
+  succeeded.
+- `intervention(id)` / `interventions()` — status; `skill_name` is the receipt.
+- `retire_skill(name, reason)` — stop serving a skill immediately.
+
+Errors raise `DoubleOhError` carrying the server's own message and the HTTP `status`.
+
+## What is recorded
+
+Fix sessions keep screenshots and the shape of each action. **Typed text is never
+recorded** — a fix session is exactly where a password gets typed, so keystrokes stay off
+the record entirely.
+
+## Framework adapters
+
+Every adapter serves the same three tools; pick your framework's line.
+
+```python
+from doubleoh import DoubleOh
+client = DoubleOh(api_key=os.environ["DOUBLEOH_API_KEY"])
+
+# LangChain / LangGraph
+from doubleoh.langchain import doubleoh_tools
+graph = create_react_agent(model, tools=doubleoh_tools(client))
+
+# CrewAI
+from doubleoh.crewai import doubleoh_tools
+agent = Agent(role="operator", tools=doubleoh_tools(client))
+
+# LlamaIndex
+from doubleoh.llamaindex import doubleoh_tools
+agent = ReActAgent.from_tools(doubleoh_tools(client), llm=llm)
+
+# OpenAI Agents SDK, AutoGen, Pydantic AI — all accept plain functions:
+from doubleoh.tools import build_tools
+skills_for, request_fix, report_skill = build_tools(client)
+agent = Agent(tools=[function_tool(skills_for), function_tool(request_fix), function_tool(report_skill)])
+```
+
+No framework is a dependency of this package: each adapter imports its framework lazily
+and, if it is missing, raises one sentence naming what to `pip install`.
+
+Using Claude or another MCP-capable agent? Skip the SDK entirely — `doubleoh-mcp` serves
+the same three tools over MCP.

doubleoh-0.1.0/doubleoh/__init__.py

@@ -0,0 +1,224 @@
+"""The DoubleOh client, for an agent that would rather learn than fail twice.
+
+The whole SDK is three moments: before you try something, ask what has been learned
+(``skills_for``); when you get stuck, ask a human (``request_fix``); when you know how a
+skill went, say so (``report_skill``). Everything else an integrator writes — the retry
+loop, the "am I stuck" heuristic — is theirs, because only they know their agent.
+
+No dependencies. It is ``urllib`` and dataclasses, readable in one sitting: a reliability
+tool that drags a dependency tree into your build is a reliability problem.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Optional
+from urllib.parse import quote
+
+__all__ = [
+    "DoubleOh",
+    "DoubleOhError",
+    "LearnedSkill",
+    "Intervention",
+    "InterventionStatus",
+]
+
+_DEFAULT_BASE_URL = "https://api.doubleoh.ai"
+
+
+class DoubleOhError(Exception):
+    """The server refused, and this is its own sentence about why."""
+
+    def __init__(self, message: str, status: int):
+        super().__init__(message)
+        self.status = status
+
+
+@dataclass(frozen=True)
+class LearnedSkill:
+    """A procedure learned from a past human fix, ready to hand to your agent."""
+
+    name: str
+    description: str
+    #: The steps, as prose. Put this in your agent's context before it tries the task.
+    instructions: str
+    #: How many agents followed this and reported it worked / did not. Raw counts on
+    #: purpose: 5 for 5 is worth following, 1 for 1 is a guess that happened to work
+    #: once, and a rate cannot tell those two apart.
+    times_worked: int = 0
+    times_failed: int = 0
+
+
+@dataclass(frozen=True)
+class Intervention:
+    """What came back from asking for help.
+
+    Exactly one of three shapes:
+      - ``fix_url`` is set: a human has been asked; send the link where your team lives.
+      - ``deflected`` is True: nobody was paged — ``skill`` already answers this wall.
+        Retry with its instructions in context; if that still fails, ask again (the same
+        wall deflects only once, so the second ask reaches a human).
+      - ``duplicate_of`` is set: this wall is already waiting on a human. ``blocked_runs``
+        says how many runs are stuck on it, yours included — triage by it.
+    """
+
+    id: Optional[str]
+    fix_url: Optional[str]
+    prepared: bool
+    duplicate_of: Optional[str] = None
+    waiting_since: Optional[str] = None
+    blocked_runs: Optional[int] = None
+    deflected: bool = False
+    skill: Optional[LearnedSkill] = None
+
+
+@dataclass(frozen=True)
+class InterventionStatus:
+    id: str
+    url: str
+    task: str
+    #: ``open``, ``resolved``, ``abandoned``, or ``expired``.
+    status: str
+    #: The skill this fix produced, once it has. None until then, or if nothing was learned.
+    skill_name: Optional[str]
+    #: How many runs hit this wall while it was open. The triage number.
+    blocked_runs: int
+    created_at: str
+
+
+def _skill_from(payload: dict[str, Any]) -> LearnedSkill:
+    return LearnedSkill(
+        name=payload["name"],
+        description=payload.get("description", ""),
+        instructions=payload.get("instructions", ""),
+        times_worked=payload.get("timesWorked", 0),
+        times_failed=payload.get("timesFailed", 0),
+    )
+
+
+class DoubleOh:
+    """One customer's handle on the loop.
+
+    >>> doubleoh = DoubleOh(api_key="oo_live_...")
+    >>> skills = doubleoh.skills_for("check out on the supplier portal")
+    >>> if skills:
+    ...     prompt += skills[0].instructions
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ):
+        if not api_key or not api_key.startswith("oo_"):
+            raise ValueError("A DoubleOh API key is required (it starts with oo_).")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    # ---- the three moments -------------------------------------------------
+
+    def skills_for(self, task: str) -> list[LearnedSkill]:
+        """What has been learned that helps with this task.
+
+        Call this BEFORE your agent attempts something it has failed at before. If a
+        skill comes back, put its ``instructions`` in the agent's context — that is the
+        whole point of the loop, the moment a past human's fix saves this run.
+        """
+        body = self._get(f"/v1/skills?task={quote(task)}")
+        return [_skill_from(skill) for skill in body["skills"]]
+
+    def request_fix(self, url: str, task: str) -> Intervention:
+        """Ask a human to finish what your agent could not.
+
+        ``url`` must be a public http(s) page — the page your agent is stuck on. ``task``
+        is one sentence (max 500 chars); phrase it the same way each time so repeated
+        fixes of one wall stay one skill.
+        """
+        body = self._post("/v1/interventions", {"url": url, "task": task})
+        raw = body["intervention"]
+        skill = raw.get("skill")
+        return Intervention(
+            id=raw.get("id"),
+            fix_url=raw.get("fixUrl"),
+            prepared=bool(raw.get("prepared", False)),
+            duplicate_of=raw.get("duplicateOf"),
+            waiting_since=raw.get("waitingSince"),
+            blocked_runs=raw.get("blockedRuns"),
+            deflected=bool(raw.get("deflected", False)),
+            skill=_skill_from(skill) if skill else None,
+        )
+
+    def report_skill(self, name: str, worked: bool) -> None:
+        """Say whether a skill worked.
+
+        This closes the loop, and it is the one call people are tempted to skip. Without
+        it a skill compiled from a single recording is served forever with nothing
+        checking it. One boolean, so it costs nothing to wire into whatever already tells
+        you a run succeeded. A skill followed three times that never works retires itself.
+        """
+        self._post(f"/v1/skills/{quote(name, safe='')}/outcome", {"worked": worked})
+
+    # ---- the rest ------------------------------------------------------------
+
+    def intervention(self, intervention_id: str) -> InterventionStatus:
+        """How one fix is going, and — once resolved — the skill it produced."""
+        body = self._get(f"/v1/interventions/{quote(intervention_id, safe='')}")
+        return self._status_from(body["intervention"])
+
+    def interventions(self) -> list[InterventionStatus]:
+        """Recent fixes across your fleet, newest first."""
+        body = self._get("/v1/interventions")
+        return [self._status_from(row) for row in body["interventions"]]
+
+    def retire_skill(self, name: str, reason: str) -> None:
+        """Stop serving a learned skill that turned out to be wrong, immediately."""
+        self._post(f"/v1/skills/{quote(name, safe='')}/retire", {"reason": reason})
+
+    # ---- wire ------------------------------------------------------------------
+
+    @staticmethod
+    def _status_from(raw: dict[str, Any]) -> InterventionStatus:
+        return InterventionStatus(
+            id=raw["id"],
+            url=raw["url"],
+            task=raw["task"],
+            status=raw["status"],
+            skill_name=raw.get("skillName"),
+            blocked_runs=raw.get("blockedRuns", 1),
+            created_at=raw.get("createdAt", ""),
+        )
+
+    def _get(self, path: str) -> dict[str, Any]:
+        return self._request("GET", path, None)
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", path, payload)
+
+    def _request(self, method: str, path: str, payload: Optional[dict[str, Any]]) -> dict[str, Any]:
+        request = urllib.request.Request(
+            f"{self._base_url}{path}",
+            method=method,
+            headers={
+                "x-api-key": self._api_key,
+                "content-type": "application/json",
+            },
+            data=json.dumps(payload).encode() if payload is not None else None,
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                return json.loads(response.read().decode() or "{}")
+        except urllib.error.HTTPError as error:
+            # The server's own message names what went wrong; the status is the fallback.
+            try:
+                detail = json.loads(error.read().decode())
+                message = detail.get("error") or f"DoubleOh answered {error.code}"
+            except Exception:
+                message = f"DoubleOh answered {error.code}"
+            raise DoubleOhError(message, error.code) from None
+        except urllib.error.URLError as error:
+            raise DoubleOhError(f"Could not reach DoubleOh: {error.reason}", 0) from None

doubleoh-0.1.0/doubleoh/crewai.py

@@ -0,0 +1,29 @@
+"""CrewAI adapter: the three tools for a crew's agents.
+
+::
+
+    from doubleoh import DoubleOh
+    from doubleoh.crewai import doubleoh_tools
+
+    agent = Agent(role=..., tools=doubleoh_tools(DoubleOh(api_key=...)))
+
+CrewAI's ``tool`` decorator builds a tool from a plain function's name, signature, and
+docstring — which is exactly what ``doubleoh.tools`` provides, so this module is only the
+wrapping.
+"""
+
+from __future__ import annotations
+
+from . import DoubleOh
+from .tools import build_tools
+
+
+def doubleoh_tools(client: DoubleOh) -> list:
+    try:
+        from crewai.tools import tool
+    except ImportError as error:  # pragma: no cover - exercised only without crewai
+        raise ImportError(
+            "The CrewAI adapter needs crewai: pip install crewai"
+        ) from error
+
+    return [tool(func) for func in build_tools(client)]

doubleoh-0.1.0/doubleoh/langchain.py

@@ -0,0 +1,34 @@
+"""LangChain / LangGraph adapter: the three tools as LangChain ``Tool`` objects.
+
+LangGraph agents consume LangChain tools, so this one module covers both::
+
+    from doubleoh import DoubleOh
+    from doubleoh.langchain import doubleoh_tools
+
+    tools = doubleoh_tools(DoubleOh(api_key=...))
+    graph = create_react_agent(model, tools=tools)   # LangGraph
+    agent = initialize_agent(tools, llm, ...)         # classic LangChain
+
+The framework import happens inside the call, so importing this module costs nothing and
+failing is a sentence about what to install rather than an ImportError from the middle of
+somebody's dependency tree.
+"""
+
+from __future__ import annotations
+
+from . import DoubleOh
+from .tools import build_tools
+
+
+def doubleoh_tools(client: DoubleOh) -> list:
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError as error:  # pragma: no cover - exercised only without langchain
+        raise ImportError(
+            "The LangChain adapter needs langchain-core: pip install langchain-core"
+        ) from error
+
+    return [
+        StructuredTool.from_function(func)
+        for func in build_tools(client)
+    ]

doubleoh-0.1.0/doubleoh/llamaindex.py

@@ -0,0 +1,25 @@
+"""LlamaIndex adapter: the three tools as ``FunctionTool`` objects.
+
+::
+
+    from doubleoh import DoubleOh
+    from doubleoh.llamaindex import doubleoh_tools
+
+    agent = ReActAgent.from_tools(doubleoh_tools(DoubleOh(api_key=...)), llm=llm)
+"""
+
+from __future__ import annotations
+
+from . import DoubleOh
+from .tools import build_tools
+
+
+def doubleoh_tools(client: DoubleOh) -> list:
+    try:
+        from llama_index.core.tools import FunctionTool
+    except ImportError as error:  # pragma: no cover - exercised only without llama-index
+        raise ImportError(
+            "The LlamaIndex adapter needs llama-index-core: pip install llama-index-core"
+        ) from error
+
+    return [FunctionTool.from_defaults(fn=func) for func in build_tools(client)]

doubleoh-0.1.0/doubleoh/tools.py

@@ -0,0 +1,109 @@
+"""The loop as agent tools — plain functions, which is what most frameworks now want.
+
+The OpenAI Agents SDK, AutoGen, and Pydantic AI all accept ordinary Python callables as
+tools, reading the name, signature, and docstring. So the base adapter is exactly that:
+``build_tools(client)`` returns three well-documented functions, and those three
+frameworks need nothing else::
+
+    from doubleoh import DoubleOh
+    from doubleoh.tools import build_tools
+
+    tools = build_tools(DoubleOh(api_key=...))
+
+    # OpenAI Agents SDK:   Agent(tools=[function_tool(f) for f in tools])
+    # AutoGen:             AssistantAgent(tools=list(tools))
+    # Pydantic AI:         Agent(tools=list(tools))
+
+The functions return STRINGS written for a model to read: a tool result is context, not
+an API payload, and "A colleague has done this before: …" steers a model where a JSON
+blob does not. LangChain/LangGraph, CrewAI, and LlamaIndex have their own modules that
+wrap these same functions in each framework's tool class.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from . import DoubleOh, DoubleOhError, LearnedSkill
+
+
+def _skill_lines(skill: LearnedSkill) -> str:
+    return (
+        f'Skill "{skill.name}" (worked {skill.times_worked}×, failed {skill.times_failed}×):\n'
+        f"{skill.description}\n{skill.instructions}"
+    )
+
+
+def build_tools(client: DoubleOh) -> tuple[Callable, Callable, Callable]:
+    """The three tools, bound to one client, in the order an agent uses them."""
+
+    def doubleoh_skills_for(task: str) -> str:
+        """BEFORE attempting a task you have failed at before, ask what has been learned.
+
+        Returns step-by-step procedures compiled from past human fixes, with how often
+        each has worked. Follow a returned procedure instead of improvising.
+
+        Args:
+            task: The task, in one sentence. Phrase it the same way each time — the
+                phrasing is part of the skill's identity.
+        """
+        skills = client.skills_for(task)
+        if not skills:
+            return (
+                "Nothing has been learned about this task yet. Proceed, and if you get "
+                "stuck, use doubleoh_request_fix."
+            )
+        rendered = "\n\n".join(_skill_lines(skill) for skill in skills)
+        return f"A colleague has done this before. Follow these steps:\n\n{rendered}"
+
+    def doubleoh_request_fix(url: str, task: str) -> str:
+        """When you are STUCK on a web page, ask a human to fix it.
+
+        A login wall, a changed layout, a step you cannot complete — a person fixes it
+        once in a live browser and the fix becomes a skill the whole fleet reuses. If the
+        fleet already knows this wall, the learned procedure is returned instantly
+        instead and nobody is paged: follow it and retry. Do not call this for tasks you
+        have not attempted.
+
+        Args:
+            url: The public http(s) page you are stuck on.
+            task: What you were trying to do, in one sentence (max 500 characters).
+        """
+        try:
+            fix = client.request_fix(url=url, task=task)
+        except DoubleOhError as error:
+            # A refusal is an answer the model should read, not an exception to crash on.
+            return f"DoubleOh refused ({error.status}): {error}"
+        if fix.deflected and fix.skill:
+            return (
+                "No human was needed — this wall is already known. Follow this procedure "
+                f"and retry:\n\n{_skill_lines(fix.skill)}\n\n"
+                "If it still fails, call doubleoh_request_fix again: the second ask "
+                "reaches a human."
+            )
+        if fix.duplicate_of:
+            blocked = fix.blocked_runs or "several"
+            return (
+                f"A human has already been asked about this exact wall ({blocked} runs "
+                "are blocked on it). Do not ask again; move to other work or wait."
+            )
+        return (
+            f"A human has been asked to fix this. Fix link (already sent to the team if "
+            f"a webhook is configured): {fix.fix_url}. Move on to other work; the fix "
+            "becomes a reusable skill once a person completes it."
+        )
+
+    def doubleoh_report_skill(name: str, worked: bool) -> str:
+        """AFTER following a skill, report whether it worked.
+
+        This keeps the skill's track record honest; a skill that keeps failing stops
+        being served. Always call this when you used a skill.
+
+        Args:
+            name: The skill's name, exactly as returned.
+            worked: True if following the skill completed the task.
+        """
+        client.report_skill(name, worked)
+        return "Recorded. Thank you — the skill's track record is what the next agent trusts."
+
+    return doubleoh_skills_for, doubleoh_request_fix, doubleoh_report_skill

doubleoh-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "doubleoh"
+version = "0.1.0"
+description = "Your agents learn from every fix. Stop failing the same way twice."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["doubleoh"]

doubleoh-0.1.0/tests/test_client.py

@@ -0,0 +1,132 @@
+"""The Python SDK against a real HTTP server — stdlib only, run with `python3 -m unittest`.
+
+A stub server rather than mocked urllib, because what the SDK owns is the wire: paths,
+headers, encoding, and how a refusal becomes an exception. A mock of urllib would pass
+while the wire was wrong.
+"""
+
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import sys
+import pathlib
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
+from doubleoh import Intervention, DoubleOh, DoubleOhError  # noqa: E402
+
+RECORDED: list[dict] = []
+
+
+class Stub(BaseHTTPRequestHandler):
+    def log_message(self, *args):  # quiet
+        pass
+
+    def _reply(self, status, payload):
+        body = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        RECORDED.append({"method": "GET", "path": self.path, "key": self.headers.get("x-api-key")})
+        if self.path.startswith("/v1/skills"):
+            self._reply(200, {"skills": [{
+                "name": "checkout-finish-2afd60",
+                "description": "Use when finishing checkout.",
+                "instructions": "1. Click checkout.",
+                "timesWorked": 5,
+                "timesFailed": 0,
+            }]})
+        elif self.path == "/v1/interventions":
+            self._reply(200, {"interventions": [{
+                "id": "i-1", "url": "https://shop.example", "task": "t",
+                "status": "resolved", "skillName": "checkout-finish-2afd60",
+                "blockedRuns": 3, "createdAt": "2026-08-28T00:00:00Z",
+            }]})
+        else:
+            self._reply(404, {"error": "Not found."})
+
+    def do_POST(self):
+        length = int(self.headers.get("content-length", 0))
+        body = json.loads(self.rfile.read(length) or b"{}")
+        RECORDED.append({"method": "POST", "path": self.path, "body": body,
+                         "key": self.headers.get("x-api-key")})
+        if self.path == "/v1/interventions":
+            if body.get("task") == "a known wall":
+                self._reply(200, {"intervention": {
+                    "id": None, "fixUrl": None, "prepared": False, "deflected": True,
+                    "skill": {"name": "s", "description": "d", "instructions": "1. x",
+                              "timesWorked": 2, "timesFailed": 0},
+                }})
+            elif body.get("url", "").startswith("http://localhost"):
+                self._reply(400, {"error": "That address is not reachable for a fix."})
+            else:
+                self._reply(200, {"intervention": {
+                    "id": "i-9", "fixUrl": "https://fix.example/fix/tok",
+                    "prepared": True,
+                }})
+        elif self.path.endswith("/outcome"):
+            self._reply(200, {"recorded": True, "retired": False})
+        else:
+            self._reply(404, {"error": "No skill of yours by that name."})
+
+
+class SdkTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = HTTPServer(("127.0.0.1", 0), Stub)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.client = DoubleOh(api_key="oo_test_1", base_url=f"http://127.0.0.1:{cls.server.server_port}")
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def test_rejects_a_key_that_is_not_a_doubleoh_key(self):
+        with self.assertRaises(ValueError):
+            DoubleOh(api_key="sk-something-else")
+
+    def test_skills_for_returns_typed_skills_with_confidence(self):
+        skills = self.client.skills_for("finish checkout")
+        self.assertEqual(skills[0].name, "checkout-finish-2afd60")
+        self.assertEqual(skills[0].times_worked, 5)
+        # The key travels as a header, and the task travels URL-encoded.
+        sent = RECORDED[-1]
+        self.assertEqual(sent["key"], "oo_test_1")
+        self.assertIn("finish%20checkout", sent["path"])
+
+    def test_request_fix_returns_the_link(self):
+        fix = self.client.request_fix("https://shop.example/checkout", "finish checkout")
+        self.assertIsInstance(fix, Intervention)
+        self.assertEqual(fix.fix_url, "https://fix.example/fix/tok")
+        self.assertFalse(fix.deflected)
+
+    def test_a_deflection_carries_the_skill_instead_of_a_link(self):
+        fix = self.client.request_fix("https://shop.example/checkout", "a known wall")
+        self.assertTrue(fix.deflected)
+        self.assertIsNone(fix.fix_url)
+        self.assertEqual(fix.skill.instructions, "1. x")
+
+    def test_a_refusal_raises_the_servers_own_sentence(self):
+        with self.assertRaises(DoubleOhError) as caught:
+            self.client.request_fix("http://localhost:3001/admin", "reach the inside")
+        self.assertEqual(caught.exception.status, 400)
+        self.assertIn("not reachable", str(caught.exception))
+
+    def test_report_skill_sends_one_boolean(self):
+        self.client.report_skill("checkout-finish-2afd60", True)
+        self.assertEqual(RECORDED[-1]["body"], {"worked": True})
+        self.assertIn("/v1/skills/checkout-finish-2afd60/outcome", RECORDED[-1]["path"])
+
+    def test_interventions_carry_the_triage_number(self):
+        rows = self.client.interventions()
+        self.assertEqual(rows[0].blocked_runs, 3)
+        self.assertEqual(rows[0].skill_name, "checkout-finish-2afd60")
+
+
+if __name__ == "__main__":
+    unittest.main()

doubleoh-0.1.0/tests/test_tools.py

@@ -0,0 +1,120 @@
+"""The plain-function tools against the same stub server as the client tests.
+
+These functions are what every framework adapter serves, so what is asserted here is the
+contract all of them inherit: model-readable strings, refusals as answers, and the
+deflection path telling the agent to retry rather than wait.
+"""
+
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import sys
+import pathlib
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
+from doubleoh import DoubleOh  # noqa: E402
+from doubleoh.tools import build_tools  # noqa: E402
+
+
+class Stub(BaseHTTPRequestHandler):
+    def log_message(self, *args):
+        pass
+
+    def _reply(self, status, payload):
+        body = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        if "empty" in self.path:
+            self._reply(200, {"skills": []})
+        else:
+            self._reply(200, {"skills": [{
+                "name": "checkout-finish-2afd60",
+                "description": "Use when finishing checkout.",
+                "instructions": "1. Click checkout.",
+                "timesWorked": 5, "timesFailed": 0,
+            }]})
+
+    def do_POST(self):
+        length = int(self.headers.get("content-length", 0))
+        body = json.loads(self.rfile.read(length) or b"{}")
+        if self.path.endswith("/outcome"):
+            self._reply(200, {"recorded": True, "retired": False})
+        elif body.get("task") == "a known wall":
+            self._reply(200, {"intervention": {
+                "id": None, "fixUrl": None, "prepared": False, "deflected": True,
+                "skill": {"name": "s", "description": "d",
+                          "instructions": "1. Dismiss the wall.",
+                          "timesWorked": 2, "timesFailed": 0}}})
+        elif body.get("url", "").startswith("http://localhost"):
+            self._reply(400, {"error": "That address is not reachable for a fix."})
+        else:
+            self._reply(201, {"intervention": {
+                "id": "i-9", "fixUrl": "https://fix.example/fix/tok", "prepared": True}})
+
+
+class ToolsTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = HTTPServer(("127.0.0.1", 0), Stub)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        client = DoubleOh(api_key="oo_test_1", base_url=f"http://127.0.0.1:{cls.server.server_port}")
+        cls.skills_for, cls.request_fix, cls.report_skill = build_tools(client)
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def test_functions_carry_the_names_and_docs_frameworks_read(self):
+        # Plain-function frameworks (OpenAI Agents, AutoGen, Pydantic AI) build the tool
+        # from exactly these attributes; if they drift, every adapter drifts.
+        self.assertEqual(type(self).skills_for.__name__, "doubleoh_skills_for")
+        self.assertIn("BEFORE attempting", type(self).skills_for.__doc__)
+        self.assertIn("STUCK", type(self).request_fix.__doc__)
+        self.assertIn("AFTER following a skill", type(self).report_skill.__doc__)
+
+    def test_skills_render_as_context_to_follow(self):
+        text = type(self).skills_for("finish checkout")
+        self.assertIn("A colleague has done this before", text)
+        self.assertIn("worked 5×", text)
+
+    def test_no_skills_points_at_request_fix(self):
+        text = type(self).skills_for("empty task nothing knows")
+        self.assertIn("Nothing has been learned", text)
+        self.assertIn("doubleoh_request_fix", text)
+
+    def test_deflection_says_retry_not_wait(self):
+        text = type(self).request_fix("https://shop.example", "a known wall")
+        self.assertIn("No human was needed", text)
+        self.assertIn("1. Dismiss the wall.", text)
+
+    def test_a_fresh_fix_returns_the_link_and_says_move_on(self):
+        text = type(self).request_fix("https://shop.example", "a brand new wall")
+        self.assertIn("https://fix.example/fix/tok", text)
+        self.assertIn("Move on", text)
+
+    def test_a_refusal_is_an_answer_not_an_exception(self):
+        text = type(self).request_fix("http://localhost:3001/admin", "reach inside")
+        self.assertIn("DoubleOh refused (400)", text)
+        self.assertIn("not reachable", text)
+
+    def test_adapters_fail_with_an_installable_sentence(self):
+        # None of the frameworks are installed in this environment, which IS the test.
+        from doubleoh.langchain import doubleoh_tools as lc
+        from doubleoh.crewai import doubleoh_tools as cr
+        from doubleoh.llamaindex import doubleoh_tools as li
+        client = DoubleOh(api_key="oo_test_1", base_url="http://127.0.0.1:1")
+        for adapter, package in ((lc, "langchain-core"), (cr, "crewai"), (li, "llama-index-core")):
+            with self.assertRaises(ImportError) as caught:
+                adapter(client)
+            self.assertIn(f"pip install {package}", str(caught.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()