Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,43 @@ version is 0, a minor bump may break the API.
## [Unreleased]

### Added
- `capability/gosource`: capabilities from typed Go functions.
`gosource.Func(name, description, access, func(ctx, In) (Out, error), options...)`
takes its schema from the request and response structs, decodes and encodes
for you, and needs no `switch` over RPC names. Access (`Public`, `Roles`,
`Permissions`) is a required argument; `ReadOnly` and `NeedsApproval` are options.
- `codemode.Source`, `codemode.Combine` (several sources as one, routed by RPC;
duplicates are an error) and `codemode.FromSource(source, caller)`, which
narrows to the caller and defaults to keyword search.
- Every capability call is validated against its input shape before
`ExecuteFunc` runs: unknown fields, kinds, enums, required fields and oneofs,
with errors that name the path so the model can repair the program.
`capability.Validate`, `capability.ValidateValue`.
- `capability.SchemaOf`: the neutral shape of a Go struct, following
`encoding/json`, with `desc` tags and `capability.Enum` string types.
- `TypeSchema.Required` and an `integer` kind, filled by `gosource` and
`mcpsource`.
- `agent.RunAs[T]`: the model is told `T`'s shape, the program's return value
is checked and decoded into `T`, and a mismatch is repaired like a failure.
- Approval: `Capability.NeedsApproval`, the `(codemode.needs_approval)` method
option and `gosource.NeedsApproval()`. A run holds that write and every later
one and returns `*agent.Pending`; `agent.PlanStore`, `agent.NewMemoryPlans` and
`agent.ApplyPlan(ctx, mode, store, owner, id)` apply a plan once, by ID, for its
owner. A write needing approval fails rather than runs outside `agent.Run`.
- `capability/jsonschema`: the JSON Schema converter `mcpsource` used, exported.
- `codemode/sourcetest.Run`: the contract every capability source passes.
- `examples/todo` serves its capabilities from Go functions by default;
`-source proto` keeps the proto path. `todos.delete` needs approval, and
`todo-mcp` shows `run_program` refusing it.
- `examples/taskreport` serves its 23 capabilities from typed Go functions by
default (`-source proto` keeps the protos, and a test holds both to the same
surface). `tasks.delete` needs approval: the chat shows held writes with
Approve and Reject, backed by `POST /api/plans/{id}/approve` and `/reject`.
- `examples/shop`, the quickstart as a runnable example, and
`examples/combined`, one program over Go, protobuf and MCP sources.
- Docs: a Go-structs quickstart, and pages for capability sources, types and
validation, and approving writes. The protobuf quickstart moved to
`docs/content/protobuf.md`.
- `capability.TypeSchema` carries `descriptions`, `optional`, `oneofs`, and, on
an enum, its `values`, and every dialect's prompt renders them. Protos fill
them from `(codemode.field_description)`, a new field option, proto3
Expand Down Expand Up @@ -80,6 +117,15 @@ version is 0, a minor bump may break the API.
longer tells the model about capabilities it cannot call.

### Changed
- A capability call whose input does not match the declared shape now fails
before `ExecuteFunc`. Hand-built capabilities with no input `Fields` are not
checked.
- `mcpsource` maps JSON Schema `integer` to `integer` rather than `number`,
records `required` fields, and falls back to a tool's title or name when it has
no description. `mcpsource.Source` is now an alias of `codemode.Source`.
- `agent.Apply` runs writes that need approval: applying is the approval.
- `mcpserver`'s `run_program` returns an error naming the writes held for
approval instead of reporting success.
- Docs lead with integrating codemode: a five-step summary on the landing page
and README, the sidebar ordered Get started → Ship it → How it works, and one
pre-production checklist. Fixed stale snippets, including a Dockerfile that
Expand Down
6 changes: 4 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

## What this is

Code mode: protobuf RPCs become capabilities a model composes inside a sandbox. The model writes one program (JS/Starlark/Lua) instead of N tool calls; the sandbox exposes only `codemode.execute(name, args)`, which calls back into Go, where the generated registry and role annotations are checked before anything runs.
Code mode: typed Go functions, protobuf RPCs or MCP tools become capabilities a model composes inside a sandbox. The model writes one program (JS/Starlark/Lua) instead of N tool calls; the sandbox exposes only `codemode.execute(name, args)`, which calls back into Go, where the generated registry and role annotations are checked before anything runs.

Flow: protos → `buf generate` (Go carries its own descriptors, so `registry.FromFiles` works at runtime) → registry → capability store/vector search picks relevant capabilities → LLM provider writes program → sandbox engine runs it → `agent/` orchestrates (with program caching and streaming). End-to-end walkthrough: `docs/content/flow.md`.
Flow: a source (typed Go functions via `capability/gosource`, protos via `buf generate` + `registry.FromFiles`, or MCP tools via `capability/mcpsource`) → `codemode.Source` → capability store/vector search picks relevant capabilities → LLM provider writes program → sandbox engine runs it, every call validated against its shape → `agent/` orchestrates (program caching, streaming, typed answers via `RunAs`, approval plans). End-to-end walkthrough: `docs/content/flow.md`.

## Ports and adapters

Expand All @@ -17,6 +17,7 @@ Flow: protos → `buf generate` (Go carries its own descriptors, so `registry.Fr
| `capability.Store` | `capability/sqlitestore`, `capability/pgstore` |
| `program.Cache` | `program.New` (semantic), `program.NewExactCache` |
| `program.Store` | `program.NewMemoryStore`, `capability/sqlitestore`, `capability/pgstore` |
| `agent.PlanStore` | `agent.NewMemoryPlans` |
| `llm.Client`, `llm.Streamer` | `llm/claude`, `llm/openai` |
| `sandbox.Runner` | `sandbox/goja`, `sandbox/starlark`, `sandbox/lua`, `sandbox/subprocess` |
| `sandbox.Isolation` (registered) | `sandbox/subprocess` (`process`); in-process is built in |
Expand All @@ -31,4 +32,5 @@ Flow: protos → `buf generate` (Go carries its own descriptors, so `registry.Fr
- Single test: `go test ./agent -run TestName -count=1`
- `make test-env` — library packages may read env only in their `env.go`
- `make demo-todo` — runs without API keys or DB (keyword search fallback, fixed program)
- `make demo-shop` / `make demo-combined` — the quickstart, and one program over Go, proto and MCP sources; both run without keys
- `make demo-web BASE_URL=... API_KEY=... MODEL=...` — taskreport web app on :8080
8 changes: 7 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -1,9 +1,15 @@
.PHONY: demo-todo mcp-todo worker worker-image test-container demo-report demo-web generate generate-go generate-registry test test-vector \
.PHONY: demo-todo demo-shop demo-combined mcp-todo worker worker-image test-container demo-report demo-web generate generate-go generate-registry test test-vector \
test-postgres test-consumer test-env docs docs-build docs-preview

demo-todo: generate
go run ./examples/todo

demo-shop:
go run ./examples/shop

demo-combined:
go run ./examples/combined

worker:
go build -o bin/codemode-worker ./cmd/codemode-worker

Expand Down
83 changes: 52 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Code Mode

Turn protobuf RPCs into capabilities a model can compose inside a sandbox.
Turn typed Go functions, protobuf RPCs or MCP tools into capabilities a model
composes inside a sandbox.

Ordinary tool use makes a model work one call at a time: fifty tasks, fifty round
trips, every intermediate result back through the model. Code mode has the model
Expand All @@ -24,36 +25,47 @@ before anything runs.
go get github.com/mukezhz/codemode
```

Annotate a protobuf service with `(codemode.namespace)` and a
`(codemode.description)` per method, then:
The Go functions you already have are the capabilities; their structs are the
schema:

```go
full, err := registry.FromFiles(ordersv1.File_orders_v1_orders_proto) // 1. registry from generated Go

// 2. your code: the only place that touches data
execute := func(ctx context.Context, rpc string, input json.RawMessage) (json.RawMessage, error) {
switch rpc {
case "orders.v1.OrderService/List":
return listOrders(ctx, input)
}
return nil, fmt.Errorf("RPC %q is not implemented", rpc)
type ListOrders struct {
Status string `json:"status,omitempty" desc:"only orders in this status"`
}

// 3. per request: only what this caller may call
allowed := full.For(capability.Caller{Roles: user.Roles, Permissions: user.Permissions})
mode, err := codemode.New(allowed, capability.Keyword(allowed), execute)

// 4. model writes a program, sandbox runs it
model, err := llm.NewFromEnv() // ANTHROPIC_API_KEY or OPENAI_API_KEY
runner, err := sandbox.NewFromEnv(sandbox.Options{}) // in-process JS by default
result, err := agent.Run(ctx, mode, model, "how much have paid orders brought in?",
agent.Options{Runner: runner})
fmt.Println(agent.Answer(result.Answer))
// 1. your code: typed functions, the only place that touches data
source, err := gosource.New(
gosource.Func("orders.list", "Lists orders", gosource.Public(), shop.List, gosource.ReadOnly()),
gosource.Func("orders.refund", "Refunds a paid order", gosource.Roles("support"), shop.Refund, gosource.NeedsApproval()),
)

// 2. per request: only what this caller may call
mode, err := codemode.FromSource(source, capability.Caller{Roles: user.Roles})

// 3. model writes a program, sandbox runs it, the answer comes back as your struct
model, err := llm.NewFromEnv() // ANTHROPIC_API_KEY or OPENAI_API_KEY
runner, err := sandbox.NewFromEnv(sandbox.Options{}) // in-process JS by default
revenue, result, err := agent.RunAs[Revenue](ctx, mode, model, "how much have paid orders brought in?",
agent.Options{Runner: runner, Plans: plans, PlanOwner: user.ID})

// 4. a refund waits for a person
var pending *agent.Pending
if errors.As(err, &pending) {
// show pending.Calls; on approval:
calls, err := agent.ApplyPlan(ctx, mode, plans, user.ID, pending.ID)
}
```

Blank-import the backends you want (`llm/claude`, `sandbox/goja`, …); nothing
else is linked. [**Quickstart**](docs/content/quickstart.md) builds this as
complete files in fifteen minutes.
No codegen and no `switch` over RPC names. Every call the program makes is
validated against your structs before your function runs; a bad call goes back
to the model to fix. Access is required on every capability, so nothing is
exposed by omission.

Already describe your API in protobuf, or have MCP servers? They are
[sources too](docs/content/sources.md), and `codemode.Combine` serves several at
once. Blank-import the backends you want (`llm/claude`, `sandbox/goja`, …);
nothing else is linked. [**Quickstart**](docs/content/quickstart.md) builds this
as complete files in ten minutes.

## Quick start

Expand Down Expand Up @@ -84,7 +96,10 @@ Ask it *"what is overdue, and which of it is high priority?"* and one model turn
produces one program, which returns a document the browser renders as stat
cards, a chart, and a table. Works against any OpenAI-compatible endpoint.

Each example has a step-by-step README: [`examples/todo`](examples/todo/README.md)
Two more show the new pieces in isolation: [`examples/shop`](examples/shop/README.md)
(the quickstart: typed answer, approved refund) and
[`examples/combined`](examples/combined/README.md) (Go functions, a proto service
and an MCP server in one program). Each example has a step-by-step README: [`examples/todo`](examples/todo/README.md)
(no key, no database, also an MCP server for Claude Code) and
[`examples/taskreport`](examples/taskreport/README.md) (web UI, roles, rate
limits, audit log). Both run programs in-process by default; add
Expand All @@ -95,14 +110,16 @@ limits, audit log). Both run programs in-process by default; add
Full docs are a VitePress site under [`docs/`](docs/content).

**Get started**
- [**Quickstart**](docs/content/quickstart.md) — an empty directory to a model answering, in eight steps
- [**Quickstart**](docs/content/quickstart.md) — an empty directory to a typed answer and an approved write, in six steps
- [Capability sources](docs/content/sources.md) — Go structs, protobuf, MCP, or several at once · [Capabilities from protobuf](docs/content/protobuf.md)
- [**Integration guide**](docs/content/using-it.md) — every integration choice, explained
- [Adding it to an existing app](docs/content/existing-app.md) — a CRM walked through: contract, adapter, roles, tenants, confirmed writes, and a non-Go CRM via a sidecar

**Ship it**
- [Development and production](docs/content/environments.md) · [Running the worker](docs/content/worker.md) — same binary, different isolation
- [What your binary links](docs/content/dependencies.md) — the blank imports, and why
- [Permissions](docs/content/permissions.md) · [Roles and tenants](docs/content/tenants.md) — roles in the contract, rows in your code
- [Types and validation](docs/content/types.md) · [Approving writes](docs/content/approval.md)
- [Writes and retries](docs/content/writes.md) · [Caching programs](docs/content/caching.md)

**Grow it**
Expand All @@ -127,13 +144,17 @@ make docs-build # build the static site
| `proto/` | `codemode.proto`: the service and method annotations (namespace, description, roles, permissions), embedded for consumers |
| `registry/` | Builds a registry from linked descriptors or a Buf descriptor set; CLI in `cmd/codemode-registry/` |
| `gen/` | Generated Go for `codemode.proto`. Each example generates into its own tree |
| `capability/` | Registry types and the vector index; backends in `sqlitestore/` and `pgstore/` |
| `codemode/` | The two-method public interface: `Search` and `Execute` |
| `capability/` | Registry types, validation and the vector index; backends in `sqlitestore/` and `pgstore/` |
| `capability/gosource/` | Capabilities from typed Go functions |
| `capability/mcpsource/` | Capabilities from an MCP server's tools |
| `codemode/` | The two-method public interface, `Search` and `Execute`, and `Source` / `Combine` |
| `llm/` | The `Client` interface; providers in `claude/` and `openai/` |
| `sandbox/` | The `Runner` interface; engines in `goja/`, `starlark/`, `lua/` |
| `agent/` | Search → prompt → model → sandbox, with a repair loop |
| `agent/` | Search → prompt → model → sandbox, with a repair loop, typed answers and approval plans |
| `examples/todo/` | The smallest end-to-end example, also served over MCP |
| `examples/taskreport/` | A complete app: SQLite tasks, 23 capabilities, roles, reporting |
| `examples/shop/` | The quickstart: Go-struct capabilities, a typed answer, an approved refund |
| `examples/combined/` | Go functions, a proto service and an MCP server in one program |
| `examples/taskreport/` | A complete app: SQLite tasks, 23 typed capabilities, roles, reporting, approval in the chat |
| `docs/` | The published documentation site |
| `notes/` | Internal writing: PRDs, milestones, decisions. Never published. |

Expand Down
32 changes: 29 additions & 3 deletions agent/agent.go
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,13 @@ type Options struct {
OnCall func(codemode.Call)
// Stops repair attempts once spent; zero disables. Only providers that report usage count.
MaxTokens int64
// Plans keeps writes held for approval so they can be applied by ID; nil returns them in Pending only.
Plans PlanStore
// PlanOwner scopes a saved plan to one caller, such as a user ID; ApplyPlan must pass the same.
PlanOwner string

// Set by RunAs: checks the returned value, so a mismatch is repaired like a failure.
check func(any) error
}

const (
Expand Down Expand Up @@ -171,7 +178,7 @@ func generate(ctx context.Context, mode codemode.CodeMode, model llm.Client, req
if err == nil {
result.Answer = answer
result.Planned = planned(recorder)
return result, nil
return result, pending(ctx, recorder, result.Planned, options)
}
if stop := unretryable(recorder, err); stop != nil {
return result, stop
Expand Down Expand Up @@ -246,9 +253,27 @@ func run(ctx context.Context, mode codemode.CodeMode, source string, options Opt
running := time.Now()
answer, err := options.Runner.Run(codemode.WithRecorder(ctx, recorder), mode, source)
timing.Run += time.Since(running)
if err == nil && options.check != nil {
err = options.check(answer)
}
return answer, recorder, err
}

func pending(ctx context.Context, recorder *codemode.Recorder, held []codemode.Call, options Options) error {
if !recorder.Pending() {
return nil
}
plan := &Pending{Calls: held}
if options.Plans != nil {
id, err := options.Plans.Save(ctx, options.PlanOwner, held)
if err != nil {
return fmt.Errorf("save plan: %w", err)
}
plan.ID = id
}
return plan
}

func unretryable(recorder *codemode.Recorder, err error) error {
if permanent := recorder.Permanent(); permanent != nil {
return fmt.Errorf("%w: %w", ErrNotRetried, permanent)
Expand All @@ -269,9 +294,10 @@ func planned(recorder *codemode.Recorder) []codemode.Call {
return writes
}

// Stops at the first failure; each write still passes the registry and the transport.
// Apply runs approved calls, including writes that need approval. It stops at the
// first failure; each call still passes validation, the registry and the transport.
func Apply(ctx context.Context, mode codemode.CodeMode, planned []codemode.Call) ([]codemode.Call, error) {
recorder := &codemode.Recorder{}
recorder := &codemode.Recorder{Approved: true}
ctx = codemode.WithRecorder(ctx, recorder)
for _, call := range planned {
if _, err := mode.Execute(ctx, call.Name, call.Input); err != nil {
Expand Down
Loading
Loading