agentcat-go-sdk: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

This is a Go workspace (go.work) with three published modules plus the examples. The root module go.agentcat.com/sdk/v2 exposes its public surface in mcpcat.go, types.go, custom_event.go, context_description.go, diagnostics.go, and metadata.go, and keeps all shared logic under internal/. The two adapter modules — mcpgo/ (mark3labs/mcp-go) and officialsdk/ (modelcontextprotocol/go-sdk) — have their own go.mod, cannot import internal/ across the module boundary, and therefore consume root re-exports. Each adapter owns its Track() entry point and Options, its tools/list injection and tools/call capture path, and a get_more_tools.go that registers the optional tool.

Key internal packages: internal/constants pins the agent-facing copy, injected parameter names, wire keys, and event tags byte-for-byte against the other AgentCat SDKs; internal/handles mints, derives, extracts, and resolves task and agent handles; internal/inject is the pure, deterministic schema-injection engine (build, registries, strip, structured mirror); internal/core holds Options, Event, AgentCatInstance, and UserIdentity; internal/registry keeps a thread-safe server→AgentCatInstance map keyed by pointer address and released via runtime.AddCleanup; internal/publisher and internal/exporters fan events out; internal/logging centralizes file-backed logging to ~/agentcat.log. There is no internal/session, internal/sessionmap, or internal/testutil — v2 removed transport sessions entirely.

MIGRATION.md is the source of truth for the v1→v2 delta and the list of removed APIs; keep other docs consistent with it rather than restating it.

Build, Test, and Development Commands

Run everything from the repo root. The full gate is make check && make test-mcpgo && make test-officialsdk && make build-examples. Do not shorten it to make check && make build-examples: make check's test step is go test ./... from the root, and a root-level ./... does not reach nested modules, with or without go.work — so it runs 17 root packages and zero adapter tests. That is why test-mcpgo and test-officialsdk exist as separate targets, and why make vet iterates every module rather than calling go vet ./... once. CI (.github/workflows/ci.yml) covers the same ground in four jobs: a gofmt check, go test -race per module across a Go 1.24/stable matrix, make vet, and make build-examples. Use go test -race ./... when touching shared-memory code, and go test -v -run TestName ./path/... for a focused run. Apply make tidy only when dependencies truly change so the module files stay stable. Because go.work is gitignored, every example must also build standalone (cd examples/<x>/<y> && GOWORK=off go build .).