integrations

LangChain

Protect LangChain file tools with Klock's local repo coordination workflow.

LangChain is the canonical Klock OSS v1 integration.

The goal is simple: wrap cooperative file-mutating tools so multiple agents can touch the same repo without silent overwrite.

This is not yet filesystem-level enforcement against arbitrary processes.

Install

pip install klock klock-langchain langchain-core

For localhost workflows, KlockHttpClient auto-starts the local server when it can find a launch command.

When auto-start happens, the SDK logs the base URL, launch command, and PID.

Disable auto-start with:

  • KLOCK_DISABLE_AUTOSTART=1
  • autoStart: false in JavaScript
  • auto_start=False in Python

Canonical example

from klock import KlockHttpClient
from klock_langchain import KlockConflictError, klock_protected
from langchain_core.tools import BaseTool

klock = KlockHttpClient("http://localhost:3100")
klock.register_agent("agent-a", 100)

class WriteFileTool(BaseTool):
    name = "write_file"
    description = "Mutates a shared repo file."

    @klock_protected(
        klock_client=klock,
        agent_id="agent-a",
        session_id="repo-session-a",
        resource_type="FILE",
        resource_path_extractor=lambda kwargs: kwargs["path"],
        predicate="MUTATES",
    )
    def _run(self, path: str, content: str) -> str:
        with open(path, "w", encoding="utf-8") as handle:
            handle.write(content)
        return f"updated {path}"

Conflict behavior

  • GRANT: the tool enters the critical section
  • WAIT: the decorator backs off and retries
  • DIE: the decorator raises KlockConflictError

Example retry boundary:

try:
    tool.invoke({"path": "src/auth.js", "content": "..."})
except KlockConflictError as exc:
    if exc.reason == "DIE":
        # retry later
        ...

Proof scripts

The repo ships deterministic proof scripts built around the same local-server path:

  • without_klock.py
  • with_klock.py
  • wait_die_trace.py

Use them from the Quick Start before integrating Klock into a real agent.