protocol

package
v0.41.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 23, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package protocol is Kiln's canonical agent tool surface.

Each public method on Tools is one tool. Methods take typed Args, build a journal.Entry, push it through live.Live's Apply funnel, and return a structured Result with OK / Error / Kind / Hint. The same surface is later wrapped by transports — native Claude tool-use loop (Phase 7a), MCP server (Phase 7b), ACP adapter (Phase 7c) — without re-deriving behavior. Tests drive Tools directly without any LLM in the loop.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AddEntityArgs 

type AddEntityArgs struct {
	Entity *world.Entity `json:"entity"`
}

type AddFieldArgs 

type AddFieldArgs struct {
	Entity string      `json:"entity"`
	Field  world.Field `json:"field"`
}

type AddHookArgs 

type AddHookArgs struct {
	Hook *world.Hook `json:"hook"`
}

type AddPageArgs 

type AddPageArgs struct {
	Page *world.Page `json:"page"`
}

type AddRouteArgs 

type AddRouteArgs struct {
	Route *world.Route `json:"route"`
}

type AddSeedArgs 

type AddSeedArgs struct {
	Seed *world.Seed `json:"seed"`
}

type ApprovePlanArgs 

type ApprovePlanArgs struct {
	PlanID   string `json:"plan_id"`
	Modified bool   `json:"modified,omitempty"`
}

type ChatArgs 

type ChatArgs struct {
	Role string `json:"role"` // "user" | "assistant"
	Text string `json:"text"`
}

type DeleteEntityArgs 

type DeleteEntityArgs struct {
	Name string `json:"name"`
	// PlanID names an approved plan whose Targets list contains
	// {op:"delete_entity",name:<Name>}. Required — destructive ops do not
	// run without a plan-approved authorization.
	PlanID string `json:"plan_id,omitempty"`
}

type DeleteFieldArgs 

type DeleteFieldArgs struct {
	Entity string `json:"entity"`
	Field  string `json:"field"`
	PlanID string `json:"plan_id,omitempty"`
}

type DeleteHookArgs 

type DeleteHookArgs struct {
	ID     string `json:"id"`
	PlanID string `json:"plan_id,omitempty"`
}

type DeletePageArgs 

type DeletePageArgs struct {
	Path   string `json:"path"`
	PlanID string `json:"plan_id,omitempty"`
}

type DeleteRouteArgs 

type DeleteRouteArgs struct {
	Method string `json:"method"`
	Path   string `json:"path"`
	PlanID string `json:"plan_id,omitempty"`
}

type Descriptor 

type Descriptor struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Schema      map[string]any `json:"schema"`
	Destructive bool           `json:"destructive,omitempty"`
}

Descriptor is the public schema of one tool. Transports (MCP, ACP) expose Descriptor.Schema as the tool's input schema and Description as its description.

type PageElementOp 

type PageElementOp struct {
	Op       string         `json:"op"`
	SetProps map[string]any `json:"set_props,omitempty"`
	Element  *world.Node    `json:"element,omitempty"`
}

PageElementOp is the discriminated patch shape. Op selects which fields are read.

type ProposePlanArgs 

type ProposePlanArgs struct {
	PlanID  string               `json:"plan_id"`
	Steps   []string             `json:"steps"`
	Reason  string               `json:"reason,omitempty"`
	Targets []journal.PlanTarget `json:"targets,omitempty"`
}

type RejectPlanArgs 

type RejectPlanArgs struct {
	PlanID string `json:"plan_id"`
	Reason string `json:"reason,omitempty"`
}

type ResetSessionArgs 

type ResetSessionArgs struct{}

type Result 

type Result struct {
	OK     bool   `json:"ok"`
	Result any    `json:"result,omitempty"`
	Error  string `json:"error,omitempty"`
	Kind   string `json:"kind,omitempty"` // "validation" | "conflict" | "not_found" | "needs_plan" | ...
	Hint   string `json:"hint,omitempty"`
}

Result is the structured response every tool returns. The shape is the same as the on-the-wire payload exposed by the MCP / ACP transports.

type SetAppConfigArgs 

type SetAppConfigArgs struct {
	Config world.AppConfig `json:"config"`
}

type SetScaffoldArgs added in v0.27.0 

type SetScaffoldArgs struct {
	Nav        []world.NavItem       `json:"nav,omitempty"`
	Endpoints  []*world.EndpointStub `json:"endpoints,omitempty"`
	Middleware []world.NamedStub     `json:"middleware,omitempty"`
	Plugins    []world.NamedStub     `json:"plugins,omitempty"`
	Helpers    []world.NamedStub     `json:"helpers,omitempty"`
}

SetScaffoldArgs replaces the current blueprint-owned navigation and Go-stub declarations. These surfaces are preserved into gofastr.yml at freeze time; only navigation has a live visual representation.

type SetThemeArgs 

type SetThemeArgs struct {
	Theme map[string]string `json:"theme"`
}

SetThemeArgs replaces world.App.Theme. Keys are current semantic app-theme names such as "background", "primary", and "accent"; values are CSS color literals. An empty Theme map clears overrides and restores defaults.

type Tools 

type Tools struct {
	// contains filtered or unexported fields
}

Tools is the agent-facing tool surface. It is safe for concurrent use.

func New 

func New(l *live.Live) *Tools

New constructs Tools bound to a Live runtime.

func (*Tools) AddEntity 

func (t *Tools) AddEntity(_ context.Context, args AddEntityArgs) Result

func (*Tools) AddField 

func (t *Tools) AddField(_ context.Context, args AddFieldArgs) Result

func (*Tools) AddHook 

func (t *Tools) AddHook(_ context.Context, args AddHookArgs) Result

func (*Tools) AddPage 

func (t *Tools) AddPage(_ context.Context, args AddPageArgs) Result

func (*Tools) AddRoute 

func (t *Tools) AddRoute(_ context.Context, args AddRouteArgs) Result

func (*Tools) AddSeed 

func (t *Tools) AddSeed(_ context.Context, args AddSeedArgs) Result

func (*Tools) ApprovePlan 

func (t *Tools) ApprovePlan(_ context.Context, args ApprovePlanArgs) Result

func (*Tools) Chat 

func (t *Tools) Chat(_ context.Context, args ChatArgs) Result

func (*Tools) DeleteEntity 

func (t *Tools) DeleteEntity(_ context.Context, args DeleteEntityArgs) Result

func (*Tools) DeleteField 

func (t *Tools) DeleteField(_ context.Context, args DeleteFieldArgs) Result

func (*Tools) DeleteHook 

func (t *Tools) DeleteHook(_ context.Context, args DeleteHookArgs) Result

func (*Tools) DeletePage 

func (t *Tools) DeletePage(_ context.Context, args DeletePageArgs) Result

func (*Tools) DeleteRoute 

func (t *Tools) DeleteRoute(_ context.Context, args DeleteRouteArgs) Result

func (*Tools) Describe 

func (t *Tools) Describe(name string) (Descriptor, bool)

Describe returns the descriptor for a given tool name.

func (*Tools) List 

func (t *Tools) List() []Descriptor

List returns every tool the protocol exposes.

func (*Tools) Live 

func (t *Tools) Live() *live.Live

Live returns the bound runtime, useful for transports that need the current session, journal, or SSE bus.

func (*Tools) ProposePlan 

func (t *Tools) ProposePlan(_ context.Context, args ProposePlanArgs) Result

func (*Tools) RejectPlan 

func (t *Tools) RejectPlan(_ context.Context, args RejectPlanArgs) Result

func (*Tools) ResetSession 

func (t *Tools) ResetSession(_ context.Context, _ ResetSessionArgs) Result

ResetSession truncates the journal to zero entries and reloads the live runtime. The DB schema is rebuilt from scratch (empty world → empty migration set). In-memory plan-consumption tracking resets too. Used by the panel's "Reset" button when the user wants a clean slate without killing the process.

func (*Tools) SetAppConfig 

func (t *Tools) SetAppConfig(_ context.Context, args SetAppConfigArgs) Result

func (*Tools) SetScaffold added in v0.27.0 

func (t *Tools) SetScaffold(_ context.Context, args SetScaffoldArgs) Result

func (*Tools) SetTheme 

func (t *Tools) SetTheme(_ context.Context, args SetThemeArgs) Result

SetTheme writes world.App.Theme via a SetAppConfig journal entry. Current pages consume it through UIHost's /__gofastr/app.css; the compatibility /kiln/theme.css endpoint consumes the same palette for legacy embeds.

func (*Tools) Undo 

func (t *Tools) Undo(_ context.Context, _ UndoArgs) Result

func (*Tools) UpdateEntity 

func (t *Tools) UpdateEntity(_ context.Context, args UpdateEntityArgs) Result

func (*Tools) UpdatePageElement 

func (t *Tools) UpdatePageElement(_ context.Context, args UpdatePageElementArgs) Result

UpdatePageElement applies a single atomic patch to one element inside a page tree. See UpdatePageElementArgs for the patch op vocabulary. Always non-destructive (pages have no persisted state to lose; the previous tree lives in the journal for undo).

func (*Tools) WorldGet 

func (t *Tools) WorldGet(_ context.Context, args WorldGetArgs) Result

type UndoArgs 

type UndoArgs struct{}

type UpdateEntityArgs 

type UpdateEntityArgs struct {
	Entity *world.Entity `json:"entity"`
}

type UpdatePageElementArgs 

type UpdatePageElementArgs struct {
	Path      string        `json:"path"`
	ElementID string        `json:"element_id"`
	IfMatch   *int          `json:"if_match,omitempty"`
	Patch     PageElementOp `json:"patch"`
}

UpdatePageElementArgs is the surgical-edit alternative to delete-and- re-add. The agent fetches the page, locates the target by its stable _id (assigned by add_page), and ships a single patch op describing what to change. Non-destructive: page edits don't lose persisted data, so no plan is required.

Patch.Op is one of: 

"set_props"        — merge Patch.SetProps into the element's props
"replace_props"    — replace the element's props in full with SetProps
"replace_subtree"  — replace the element + its children with Patch.Element
"remove"           — drop the element from its parent (root not allowed)
"insert_before"    — insert Patch.Element as a sibling before this one
"insert_after"     — insert Patch.Element as a sibling after this one
"append_child"     — append Patch.Element as a child of this element

IfMatch, when set, is compared against Page.Version. Mismatch returns {ok:false,kind:"conflict",hint:"refetch"} so the agent re-reads the page and re-emits the patch against the current state.

type WorldGetArgs 

type WorldGetArgs struct {
	Path string `json:"path,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.