vinc-agent-framework 0.1.0__tar.gz

vinc_agent_framework-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+# 예외: 디자인 허브 산출물은 **계약**이라 추적한다. 소비 리포의 사본
+# (app/src/tokens.*.css·theme.ts)이 커밋돼 있으므로 그 비교 대상도 리포에 있어야
+# `sync_out.py --check`(CI 드리프트 게이트)가 성립한다. 없으면 게이트가
+# "[MISSING·허브]" 로 죽는다 — 2026-08-08 CI 실패의 원인.
+!design-hub/dist/
+# 단, Claude Design 푸시 번들은 제외 — 업로드 직전에 만드는 임시 산출물이고
+# 대조할 커밋된 소비 사본이 없다(그쪽은 claude.ai 프로젝트에 산다).
+design-hub/dist/claude-design/
+build/
+*.egg-info/
+models/
+vinc_store
+*.lbug
+vinc_e2e/
+node_modules/
+app/src-tauri/target/
+app/src-tauri/binaries/
+app/src-tauri/gen/
+# .claude/ 는 기기별 설정(launch.json·ui-events.jsonl·worktrees)이라 **어느 깊이에서도**
+# 추적하지 않는다. 예외는 이제 없다. 역할 껍데기는 `agents/shells/` 에서 추적되고
+# (`agents_sync.py --check` 가 CI 에서 대조), 하네스가 읽는 사본은 리포 밖 워크스페이스
+# 루트에 `--install` 이 쓴다. 리포 안 `.claude/agents` 는 체크아웃의 브랜치를 따라
+# 수가 달라지는 두 번째 로스터였다.
+# ⚠ 전에는 루트의 `.claude/agents/` 만 되살리려고 네 줄을 겹쳐 썼다(한 줄로는 예외가
+# 사문이 되거나 `_migration/**/.claude/` 중첩본이 새어 나갔다, 2026-08-23 PR #69).
+# 예외가 사라졌으니 모든 깊이를 잡는 이 한 줄이면 된다.
+.claude/
+# 서명·접속 키 — 커밋되면 되돌릴 수 없다. 지금 키들은 리포 **바깥**(워크스페이스
+# 루트)에 있어 커밋된 적이 없지만, 누가 안으로 옮겨도 막히도록 패턴을 박아 둔다.
+# 업데이터 개인키를 잃으면 배포된 전 사용자가 자동 업데이트에서 영구 이탈한다
+# (복구 경로 없음 — DEPLOYMENT.md §1.6 백업 절차 참조).
+*.key
+*.pem
+*.p12
+*.pfx
+
+# uv 캐시 락파일 — 로컬 테스트 실행(`uv run`)이 만든다. 정본 의존성은
+# pyproject.toml 이고, 이 락은 기기별 파생물이라 추적하지 않는다.
+uv.lock
+
+# 평가·리허설 부산물 — 모델 가중치 수백 MB 가 여기 앉는다.
+# 이 워킹트리는 세션 공유라 남의 `git add -A` 가 이것을 집는다.
+.cache/
+work/
+
+# design-hub capture PNGs are build products of scripts/capture_*.mjs; the manifests are committed
+design-hub/reports/captures/**/*.png

vinc_agent_framework-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: vinc-agent-framework
+Version: 0.1.0
+Summary: Vinc for Microsoft Agent Framework: bring decisions and records from your knowledge graph into each agent run, without writing anything on its own.
+Project-URL: Homepage, https://vincs.io
+Project-URL: Documentation, https://vincs.io/docs/
+Author: Vinculums
+License-Expression: MIT
+Keywords: agent-framework,context-provider,knowledge-graph,memory,vinc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: agent-framework-core>=1.8.1
+Requires-Dist: vinc-client<0.2,>=0.1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# vinc-agent-framework
+
+[Vinc](https://vincs.io) for [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/). Vinc is a knowledge graph you share with AI: the decisions, records and documents your team wrote, with the reasons attached. This package brings the relevant part of it into each agent run.
+
+## Install
+
+```bash
+pip install vinc-agent-framework
+```
+
+## Add context to every run
+
+```python
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient
+from vinc_agent_framework import VincContextProvider
+
+vinc = VincContextProvider()              # reads VINC_API_KEY; use a vinc_ro_ key
+agent = Agent(
+    client=OpenAIChatClient(),
+    instructions="You review design changes.",
+    context_providers=[vinc],
+)
+await agent.run("Why are our colour tokens stored as OKLCH?")
+```
+
+Before each run the provider looks up the newest user message in Vinc and, when something matches, adds a block to the instructions. The block is marked as data, not instructions, and it cites node ids the model can quote back.
+
+- One call per run; two when the lookup found nothing or several nodes tied, because it then widens with a search (`search_fallback=False` turns that off).
+- If Vinc is unreachable or the daily limit is spent, the run goes on without the block. A wrong key or space raises.
+- For a team's graph pass `space="<team id>"`.
+
+## Let the model look things up
+
+```python
+vinc = VincContextProvider(expose_tools=True)
+```
+
+adds two read-only tools, `vinc_brief` and `vinc_search`. You can also build them yourself with `create_vinc_tools(client)`.
+
+## Writing, on purpose
+
+The provider never stores the conversation: `after_run` does nothing. Record what happened when a person approved it, with a `vinc_sk_` key:
+
+```python
+from vinc_client import AsyncVincClient
+from vinc_agent_framework import record_episode
+
+writer = AsyncVincClient(api_key=WRITE_KEY)
+await record_episode(
+    writer,
+    "Fixed contrast on the dark secondary button",
+    summary="text-secondary now passes 4.5:1 on the dark surface.",
+    about=["decision:tokens-are-oklch"],
+)
+```
+
+## License
+
+MIT

vinc_agent_framework-0.1.0/README.md

@@ -0,0 +1,60 @@
+# vinc-agent-framework
+
+[Vinc](https://vincs.io) for [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/). Vinc is a knowledge graph you share with AI: the decisions, records and documents your team wrote, with the reasons attached. This package brings the relevant part of it into each agent run.
+
+## Install
+
+```bash
+pip install vinc-agent-framework
+```
+
+## Add context to every run
+
+```python
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient
+from vinc_agent_framework import VincContextProvider
+
+vinc = VincContextProvider()              # reads VINC_API_KEY; use a vinc_ro_ key
+agent = Agent(
+    client=OpenAIChatClient(),
+    instructions="You review design changes.",
+    context_providers=[vinc],
+)
+await agent.run("Why are our colour tokens stored as OKLCH?")
+```
+
+Before each run the provider looks up the newest user message in Vinc and, when something matches, adds a block to the instructions. The block is marked as data, not instructions, and it cites node ids the model can quote back.
+
+- One call per run; two when the lookup found nothing or several nodes tied, because it then widens with a search (`search_fallback=False` turns that off).
+- If Vinc is unreachable or the daily limit is spent, the run goes on without the block. A wrong key or space raises.
+- For a team's graph pass `space="<team id>"`.
+
+## Let the model look things up
+
+```python
+vinc = VincContextProvider(expose_tools=True)
+```
+
+adds two read-only tools, `vinc_brief` and `vinc_search`. You can also build them yourself with `create_vinc_tools(client)`.
+
+## Writing, on purpose
+
+The provider never stores the conversation: `after_run` does nothing. Record what happened when a person approved it, with a `vinc_sk_` key:
+
+```python
+from vinc_client import AsyncVincClient
+from vinc_agent_framework import record_episode
+
+writer = AsyncVincClient(api_key=WRITE_KEY)
+await record_episode(
+    writer,
+    "Fixed contrast on the dark secondary button",
+    summary="text-secondary now passes 4.5:1 on the dark surface.",
+    about=["decision:tokens-are-oklch"],
+)
+```
+
+## License
+
+MIT

vinc_agent_framework-0.1.0/constraints-min.txt

@@ -0,0 +1,2 @@
+# 선언한 최소 버전. CI 가 이 제약으로 한 번 더 돈다(.github/workflows/ci.yml core-pkns).
+agent-framework-core==1.8.1

vinc_agent_framework-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vinc-agent-framework"
+version = "0.1.0"
+description = "Vinc for Microsoft Agent Framework: bring decisions and records from your knowledge graph into each agent run, without writing anything on its own."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Vinculums" }]
+keywords = ["vinc", "agent-framework", "context-provider", "knowledge-graph", "memory"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = ["vinc-client>=0.1,<0.2", "agent-framework-core>=1.8.1"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://vincs.io"
+Documentation = "https://vincs.io/docs/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vinc_agent_framework"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vinc_agent_framework-0.1.0/src/vinc_agent_framework/__init__.py

@@ -0,0 +1,9 @@
+"""Vinc for Microsoft Agent Framework.
+
+Design and scope: [[vinc.plan.framework-integration-packages-2026-09-28]].
+"""
+__version__ = "0.1.0"
+
+from .provider import VincContextProvider, create_vinc_tools, record_episode  # noqa: E402
+
+__all__ = ["__version__", "VincContextProvider", "create_vinc_tools", "record_episode"]

vinc_agent_framework-0.1.0/src/vinc_agent_framework/provider.py

@@ -0,0 +1,125 @@
+"""A context provider and read tools that connect an Agent Framework agent to Vinc.
+
+Reading happens on every run, before the model is called. Writing happens only
+when your code calls :func:`record_episode`; the provider never stores the
+conversation.
+"""
+from __future__ import annotations
+
+from typing import Annotated, Any, Iterable, Sequence
+
+from agent_framework import AgentSession, ContextProvider, FunctionTool, SessionContext, tool
+from pydantic import Field
+from vinc_client import (AsyncVincClient, VincQuotaExceeded, VincUnavailable, format_brief,
+                         format_search)
+from vinc_client.context import DEFAULT_MAX_CHARS
+
+DEFAULT_SOURCE_ID = "vinc"
+
+
+def _last_user_text(messages: Sequence[Any]) -> str:
+    """The text of the newest user message; the question the run is about."""
+    for message in reversed(list(messages or [])):
+        if str(getattr(message, "role", "")).lower().endswith("user"):
+            return (getattr(message, "text", "") or "").strip()
+    return ""
+
+
+def create_vinc_tools(client: AsyncVincClient, *,
+                      max_chars: int = DEFAULT_MAX_CHARS) -> list[FunctionTool]:
+    """Two read-only tools the model may call: ``vinc_brief`` and ``vinc_search``.
+
+    Nothing here can write. When Vinc is unavailable or the quota is spent the
+    tool answers with a sentence saying so instead of failing the run.
+    """
+
+    @tool(name="vinc_brief",
+          description="Look up one node in the user's Vinc knowledge graph: a decision, record "
+                      "or concept with its summary, document excerpts and relations. Pass a "
+                      "question or an exact node id such as decision:some-slug.")
+    async def vinc_brief(
+        query: Annotated[str, Field(description="A question, or an exact node id.")],
+    ) -> str:
+        try:
+            return (format_brief(await client.brief(query), max_chars=max_chars)
+                    or "Vinc has no single node for that; try vinc_search.")
+        except (VincUnavailable, VincQuotaExceeded) as exc:
+            return f"Vinc is not available right now ({exc.code}); answer without it."
+
+    @tool(name="vinc_search",
+          description="Search the user's Vinc knowledge graph by text and meaning; returns "
+                      "matching nodes and document passages with their ids.")
+    async def vinc_search(
+        query: Annotated[str, Field(description="What to look for.")],
+        limit: Annotated[int, Field(description="How many matches of each kind.", ge=1,
+                                    le=20)] = 5,
+    ) -> str:
+        try:
+            return (format_search(await client.search(query, limit=limit), max_chars=max_chars,
+                                  limit=limit)
+                    or "No matches in Vinc.")
+        except (VincUnavailable, VincQuotaExceeded) as exc:
+            return f"Vinc is not available right now ({exc.code}); answer without it."
+
+    return [vinc_brief, vinc_search]
+
+
+class VincContextProvider(ContextProvider):
+    """Adds Vinc context to the instructions of every agent run.
+
+    ``before_run`` briefs the newest user message and, when something matched,
+    appends a fenced block marked as data. With ``search_fallback`` (the default)
+    a tie or a miss is widened with a search, so a run costs one call, or two.
+    ``after_run`` does nothing: unlike memory providers that store each turn,
+    this one never writes. Use :func:`record_episode` after a person approved
+    what happened.
+    """
+
+    def __init__(self, client: AsyncVincClient | None = None, *, api_key: str | None = None,
+                 base_url: str | None = None, space: str | None = None,
+                 source_id: str = DEFAULT_SOURCE_ID, search_fallback: bool = True,
+                 max_chars: int = DEFAULT_MAX_CHARS, max_excerpts: int = 3,
+                 min_query_chars: int = 3, expose_tools: bool = False) -> None:
+        super().__init__(source_id)
+        self.client = client or AsyncVincClient(api_key, base_url=base_url, space=space)
+        self._owns_client = client is None
+        self.search_fallback = search_fallback
+        self.max_chars = max_chars
+        self.max_excerpts = max_excerpts
+        self.min_query_chars = min_query_chars
+        self._tools = create_vinc_tools(self.client, max_chars=max_chars) if expose_tools else []
+
+    async def before_run(self, *, agent: Any, session: AgentSession, context: SessionContext,
+                         state: dict[str, Any]) -> None:
+        block = await self.client.get_context(
+            _last_user_text(context.input_messages), search_fallback=self.search_fallback,
+            max_chars=self.max_chars, max_excerpts=self.max_excerpts,
+            min_query_chars=self.min_query_chars)
+        if block:
+            context.extend_instructions(self.source_id, block)
+        if self._tools:
+            context.extend_tools(self.source_id, self._tools)
+
+    async def after_run(self, *, agent: Any, session: AgentSession, context: SessionContext,
+                        state: dict[str, Any]) -> None:
+        # 의도적으로 비어 있다. 대화를 그래프에 쓰지 않는다 — 쓰기는 record_episode 뿐.
+        # 근거: [[decision:framework-integrations-ship-zep-shaped-knowledge-packages-first-2026-09-28]]
+        return None
+
+    async def aclose(self) -> None:
+        """Close the HTTP client if this provider created it."""
+        if self._owns_client:
+            await self.client.aclose()
+
+
+async def record_episode(client: AsyncVincClient, title: str, *, summary: str = "",
+                         about: Iterable[str] = (), date: str | None = None,
+                         domain: str | None = None, tags: Iterable[str] | None = None,
+                         space: str | None = None) -> dict[str, Any]:
+    """Write one Episode about existing concepts or decisions. Needs a ``vinc_sk_`` key.
+
+    Call it after a person approved what the agent did; see
+    :meth:`vinc_client.AsyncVincClient.record_episode`.
+    """
+    return await client.record_episode(title, summary=summary, about=about, date=date,
+                                       domain=domain, tags=tags, space=space)

vinc_agent_framework-0.1.0/tests/test_provider.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+import httpx
+import pytest
+from agent_framework import Agent, BaseChatClient, ChatResponse, Message, SessionContext
+
+from vinc_agent_framework import VincContextProvider, create_vinc_tools, record_episode
+from vinc_client import AsyncVincClient, VincAuthError
+
+RO_KEY = "vinc_ro_" + "a" * 32
+SK_KEY = "vinc_sk_" + "b" * 32
+
+RESOLVED = {
+    "status": "resolved",
+    "node": {"id": "decision:tokens-are-oklch", "title": "Colour tokens are stored as OKLCH"},
+    "one_liner": "Tokens keep OKLCH so contrast can be checked per theme.",
+    "grounds": ["decision:tokens-are-oklch"],
+}
+
+
+def vinc(routes: dict[tuple[str, str], Any], key: str = RO_KEY) -> tuple[AsyncVincClient, list]:
+    seen: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        answer = routes.get((request.method, request.url.path))
+        if answer is None:
+            return httpx.Response(404, json={"error": {"code": "route_not_found", "message": ""}})
+        status, body = answer if isinstance(answer, tuple) else (200, answer)
+        return httpx.Response(status, json=body)
+
+    return AsyncVincClient(key, transport=httpx.MockTransport(handler)), seen
+
+
+class RecordingChatClient(BaseChatClient):
+    """Answers "ok" and keeps what the agent sent, so a test can read the instructions."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.calls: list[dict[str, Any]] = []
+
+    async def _inner_get_response(self, *, messages, stream, options, **kwargs):  # type: ignore[override]
+        self.calls.append({"messages": list(messages), "options": dict(options)})
+        return ChatResponse(messages=Message("assistant", ["ok"]))
+
+    def sent_text(self) -> str:
+        call = self.calls[-1]
+        parts = [str(call["options"].get("instructions") or "")]
+        parts += [m.text or "" for m in call["messages"]]
+        return "\n".join(parts)
+
+
+def context_for(*messages: Message) -> SessionContext:
+    return SessionContext(input_messages=list(messages))
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def run_agent(agent: Agent, prompt: str):
+    """실제 사용처럼 이벤트 루프 안에서 부른다. 루프 밖에서 agent.run() 을 만들어 넘기면
+    1.8.x 의 관측 코드가 컨텍스트 변수를 다른 컨텍스트에서 되돌리려다 실패한다."""
+    async def go():
+        return await agent.run(prompt)
+    return asyncio.run(go())
+
+
+def tool_text(result: Any) -> str:
+    """버전에 따라 invoke 는 문자열이나 Content 목록을 돌려준다(1.19 는 목록)."""
+    if isinstance(result, str):
+        return result
+    return "".join(getattr(part, "text", None) or str(part) for part in result)
+
+
+# ── before_run ────────────────────────────────────────────────────────────────
+
+def test_before_run_adds_the_fenced_block_to_the_instructions():
+    client, seen = vinc({("POST", "/v1/brief"): RESOLVED})
+    provider = VincContextProvider(client)
+    ctx = context_for(Message("user", ["Why are colour tokens OKLCH?"]))
+    run(provider.before_run(agent=None, session=None, context=ctx, state={}))
+    assert len(ctx.instructions) == 1
+    assert "decision:tokens-are-oklch" in ctx.instructions[0] and "DATA" in ctx.instructions[0]
+    assert json.loads(seen[0].content)["query"] == "Why are colour tokens OKLCH?"
+
+
+def test_the_newest_user_message_is_the_query():
+    client, seen = vinc({("POST", "/v1/brief"): RESOLVED})
+    ctx = context_for(Message("user", ["first question"]), Message("assistant", ["an answer"]),
+                      Message("user", ["the follow-up question"]))
+    run(VincContextProvider(client).before_run(agent=None, session=None, context=ctx, state={}))
+    assert json.loads(seen[0].content)["query"] == "the follow-up question"
+
+
+def test_nothing_matched_adds_nothing():
+    client, _ = vinc({("POST", "/v1/brief"): {"status": "none"},
+                      ("POST", "/v1/search"): {"rows": [], "node_hits": []}})
+    ctx = context_for(Message("user", ["nothing like this exists"]))
+    run(VincContextProvider(client).before_run(agent=None, session=None, context=ctx, state={}))
+    assert ctx.instructions == []
+
+
+def test_vinc_down_never_fails_the_run():
+    client, _ = vinc({("POST", "/v1/brief"): (503, {"error": {"code": "upstream_unavailable",
+                                                             "message": "down"}})})
+    ctx = context_for(Message("user", ["why are tokens oklch"]))
+    run(VincContextProvider(client).before_run(agent=None, session=None, context=ctx, state={}))
+    assert ctx.instructions == []
+
+
+def test_a_key_problem_is_raised_not_hidden():
+    client, _ = vinc({("POST", "/v1/brief"): (401, {"error": {"code": "not_authenticated",
+                                                             "message": ""}})})
+    ctx = context_for(Message("user", ["why are tokens oklch"]))
+    with pytest.raises(VincAuthError):
+        run(VincContextProvider(client).before_run(agent=None, session=None, context=ctx,
+                                                   state={}))
+
+
+def test_tools_are_added_only_when_asked_and_are_read_only():
+    client, _ = vinc({("POST", "/v1/brief"): RESOLVED})
+    plain = context_for(Message("user", ["why are tokens oklch"]))
+    run(VincContextProvider(client).before_run(agent=None, session=None, context=plain, state={}))
+    assert plain.tools == []
+    with_tools = context_for(Message("user", ["why are tokens oklch"]))
+    run(VincContextProvider(client, expose_tools=True).before_run(
+        agent=None, session=None, context=with_tools, state={}))
+    assert sorted(t.name for t in with_tools.tools) == ["vinc_brief", "vinc_search"]
+
+
+# ── after_run 은 아무것도 쓰지 않는다 ───────────────────────────────────────────
+
+def test_after_run_sends_nothing():
+    client, seen = vinc({}, key=SK_KEY)
+    ctx = context_for(Message("user", ["we merged the contrast fix"]))
+    run(VincContextProvider(client).after_run(agent=None, session=None, context=ctx, state={}))
+    assert seen == []
+
+
+# ── 실제 Agent 를 거쳐서 ───────────────────────────────────────────────────────
+
+def test_an_agent_run_carries_the_block_to_the_model_and_writes_nothing():
+    client, seen = vinc({("POST", "/v1/brief"): RESOLVED})
+    chat = RecordingChatClient()
+    agent = Agent(chat, instructions="You review design changes.",
+                  context_providers=[VincContextProvider(client)])
+    result = run_agent(agent, "Why are colour tokens OKLCH?")
+    assert result.text == "ok"
+    sent = chat.sent_text()
+    assert "You review design changes." in sent and "decision:tokens-are-oklch" in sent
+    assert [r.url.path for r in seen] == ["/v1/brief"]
+
+
+def test_an_agent_run_goes_on_when_vinc_is_down():
+    client, _ = vinc({("POST", "/v1/brief"): (502, {"error": {"code": "upstream_unavailable",
+                                                             "message": ""}})})
+    chat = RecordingChatClient()
+    agent = Agent(chat, context_providers=[VincContextProvider(client)])
+    assert run_agent(agent, "why are tokens oklch").text == "ok"
+    assert "DATA" not in chat.sent_text()
+
+
+# ── 도구 ───────────────────────────────────────────────────────────────────────
+
+def test_brief_tool_returns_the_block_and_degrades_to_a_sentence():
+    client, _ = vinc({("POST", "/v1/brief"): RESOLVED})
+    brief_tool = {t.name: t for t in create_vinc_tools(client)}["vinc_brief"]
+    assert "decision:tokens-are-oklch" in tool_text(run(brief_tool.invoke(query="tokens")))
+    down, _ = vinc({("POST", "/v1/brief"): (429, {"error": {"code": "quota_exceeded",
+                                                           "message": ""}})})
+    down_tool = {t.name: t for t in create_vinc_tools(down)}["vinc_brief"]
+    assert "not available" in tool_text(run(down_tool.invoke(query="tokens")))
+
+
+def test_search_tool_passes_the_limit():
+    client, seen = vinc({("POST", "/v1/search"): {"rows": [], "node_hits": [
+        {"id": "concept:spacing", "title": "Spacing", "kind": "concept"}]}})
+    search_tool = {t.name: t for t in create_vinc_tools(client)}["vinc_search"]
+    assert "concept:spacing" in tool_text(run(search_tool.invoke(query="spacing", limit=3)))
+    assert json.loads(seen[0].content)["limit"] == 3
+
+
+# ── 쓰기 ───────────────────────────────────────────────────────────────────────
+
+def test_record_episode_needs_a_write_key():
+    client, seen = vinc({})
+    with pytest.raises(VincAuthError):
+        run(record_episode(client, "Merged", about=["decision:tokens-are-oklch"]))
+    assert seen == []
+
+
+def test_record_episode_writes_one_fragment():
+    client, seen = vinc({("GET", "/v1/nodes/decision:tokens-are-oklch"): RESOLVED,
+                         ("POST", "/v1/fragments"): {"warnings": [], "stored": []}}, key=SK_KEY)
+    run(record_episode(client, "Merged the contrast fix", about=["decision:tokens-are-oklch"],
+                       date="2026-09-28"))
+    assert [r.url.path for r in seen] == ["/v1/nodes/decision:tokens-are-oklch", "/v1/fragments"]