kami/hexis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Serve capabilities through one serializer and add GET /api/v1/executions

Browse Source 
The two "refactor later" items from REVIEW-2026-07-30.md; they share the wire
types, so they land together.

A capability had four divergent wire shapes — the HTTP handler, the MCP
adapter, pkg/client, and Maven's vendored copy of it. There is now a single
definition in pkg/client, mapped from domain by internal/wire and used by the
HTTP list/create/get paths and all four MCP surfaces. It lives in pkg/client
rather than internal so external consumers need not vendor internal/domain,
and so producer and consumer are literally the same type.

The unified shape is a strict superset of all four predecessors; nothing was
dropped. It adds enabled and requires_confirmation to the list responses
(never omitempty — an absent bool reads as unknown, not false), capability_id
to the MCP and client shapes, and the timing/attribute/version fields
previously only on get-by-ID. target_types and the list itself now serialize
as [] rather than null.

Both `id` and `capability_id` are deliberately kept, carrying the same value.
Maven decodes `id`; the spec and the rest of the API say `capability_id`.
Bearer auth is already a breaking change for that consumer, and stacking a
second silent one is the wrong trade — the redundancy stays until every
consumer is confirmed on capability_id, then `id` goes in an announced
removal. A test pins this and says so.

GET /api/v1/executions?entity_id=&since=&limit= implements spec §4.5, which
the Command Center needs. `since` reuses the changes-feed cursor convention
rather than inventing a second paging idiom. That cursor is the row's implicit
SQLite rowid, which is safe only while nothing deletes executions and nothing
VACUUMs — both would renumber and silently invalidate outstanding cursors. If
retention is ever added, this must become an explicit monotonic column first;
the constraint is documented at the query site.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uea55zaiWuEByEDC4UBSdd
This commit is contained in:
kami
2026-07-30 23:40:20 +04:00
parent 9e6b995538
commit dda4acfbb6
10 changed files with 926 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pkg/client/capability.go
+62
View File
@@ -0,0 +1,62 @@
package client
import "time"
// Capability is THE wire shape for a Hexis capability.
//
// There is exactly one definition of it, here, and every producer in this
// repository serializes through it: the HTTP handler (GET/POST
// /api/v1/capabilities, GET /api/v1/capabilities/{id}), the MCP adapter
// (hexis.list_capabilities), and this client's decode path. It lives in
// pkg/client rather than internal/ so that external consumers get the shape
// without vendoring internal packages; internal/wire holds the
// domain.Capability -> Capability conversion.
//
// Compatibility note — `id` and `capability_id` are BOTH emitted, deliberately.
// They always carry the same value. Maven's vendored consumer decodes `id`
// (cmd/mavend/voice.go matches on Capability.ID); the ECOSYSTEM-SPEC.md §4.1
// schema and the rest of the Hexis API name the column `capability_id`. Hexis
// is mid-rollout of bearer auth on /api/v1/, which is already one breaking
// change for that consumer; dropping either alias here would stack a second,
// silent one on top. Both stay until every consumer is confirmed to read
// `capability_id`, at which point `id` can be removed in a deliberate,
// announced change. Do not "clean this up" incidentally.
type Capability struct {
// CapabilityID is the canonical field (ECOSYSTEM-SPEC.md §4.1).
CapabilityID string `json:"capability_id"`
// ID is a deprecated alias for CapabilityID, kept for wire compatibility.
// Always identical to CapabilityID. Prefer CapabilityID in new code.
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
TargetTypes []string `json:"target_types"`
TargetEntityID string `json:"target_entity_id,omitempty"`
Provider string `json:"provider"`
Operation string `json:"operation"`
Risk string `json:"risk,omitempty"`
ReadOnly bool `json:"read_only"`
ExpectedSideEffects string `json:"expected_side_effects,omitempty"`
// RequiresConfirmation and Enabled are server-derived from the risk tier
// and are never settable by a caller. listCapabilities used to omit both,
// which left clients unable to tell a callable capability from one that
// would be rejected with 403; the unified shape always carries them.
RequiresConfirmation bool `json:"requires_confirmation"`
Enabled bool `json:"enabled"`
TimeoutSeconds int `json:"timeout_seconds,omitempty"`
Attributes map[string]any `json:"attributes,omitempty"`
CreatedAt time.Time `json:"created_at,omitempty"`
UpdatedAt time.Time `json:"updated_at,omitempty"`
Version int64 `json:"version,omitempty"`
}
// EffectiveID returns the capability ID, tolerating a peer that sends only one
// of the two aliases.
func (c Capability) EffectiveID() string {
if c.CapabilityID != "" {
return c.CapabilityID
}
return c.ID
}
pkg/client/client.go
+71 -39
View File
@@ -7,6 +7,8 @@ import (
"fmt"
"io"
"net/http"
"net/url"
"strconv"
"time"
)
@@ -42,6 +44,7 @@ func causationIDFrom(ctx context.Context) string {
type Client struct {
baseURL string
httpClient *http.Client
token string
}
func New(baseURL string) *Client {
@@ -51,6 +54,12 @@ func New(baseURL string) *Client {
}
}
// WithToken sets the shared bearer token sent on every /api/v1/ request.
func (c *Client) WithToken(token string) *Client {
c.token = token
return c
}
func (c *Client) do(ctx context.Context, method, path string, body, result any) error {
var reqBody io.Reader
if body != nil {
@@ -67,6 +76,9 @@ func (c *Client) do(ctx context.Context, method, path string, body, result any)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Hexis-Version", APIVersion)
if c.token != "" {
req.Header.Set("Authorization", "Bearer "+c.token)
}
if id := correlationIDFrom(ctx); id != "" {
req.Header.Set("X-Correlation-ID", id)
}
@@ -97,8 +109,37 @@ func (c *Client) do(ctx context.Context, method, path string, body, result any)
return nil
}
type Capability struct {
ID string `json:"id"`
// Capability is defined in capability.go — the single wire shape shared by
// the HTTP handler, the MCP adapter and this client.
type Execution struct {
// Seq is the pagination cursor for Executions; see the `since` parameter.
// Zero on single-execution reads.
Seq int64 `json:"seq,omitempty"`
ID string `json:"id"`
CapabilityID string `json:"capability_id"`
TargetEntityID string `json:"target_entity_id"`
Status string `json:"status"`
Result map[string]any `json:"result,omitempty"`
Error string `json:"error,omitempty"`
RequestedBy map[string]string `json:"requested_by,omitempty"`
CorrelationID string `json:"correlation_id,omitempty"`
CausationID string `json:"causation_id,omitempty"`
IdempotencyKey string `json:"idempotency_key,omitempty"`
}
type ExecuteRequest struct {
CapabilityID string `json:"capability_id"`
TargetEntityID string `json:"target_entity_id"`
Arguments map[string]any `json:"arguments,omitempty"`
RequestedBy map[string]string `json:"requested_by,omitempty"`
Origin map[string]string `json:"origin,omitempty"`
IdempotencyKey string `json:"idempotency_key,omitempty"`
CorrelationID string `json:"correlation_id,omitempty"`
CausationID string `json:"causation_id,omitempty"`
}
type CreateCapabilityRequest struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
TargetTypes []string `json:"target_types"`
@@ -110,47 +151,11 @@ type Capability struct {
ExpectedSideEffects string `json:"expected_side_effects,omitempty"`
}
type Execution struct {
ID string `json:"id"`
CapabilityID string `json:"capability_id"`
TargetEntityID string `json:"target_entity_id"`
Status string `json:"status"`
Result map[string]any `json:"result,omitempty"`
Error string `json:"error,omitempty"`
RequestedBy map[string]string `json:"requested_by,omitempty"`
CorrelationID string `json:"correlation_id,omitempty"`
CausationID string `json:"causation_id,omitempty"`
IdempotencyKey string `json:"idempotency_key,omitempty"`
}
type ExecuteRequest struct {
CapabilityID string `json:"capability_id"`
TargetEntityID string `json:"target_entity_id"`
Arguments map[string]any `json:"arguments,omitempty"`
RequestedBy map[string]string `json:"requested_by,omitempty"`
Origin map[string]string `json:"origin,omitempty"`
IdempotencyKey string `json:"idempotency_key,omitempty"`
CorrelationID string `json:"correlation_id,omitempty"`
CausationID string `json:"causation_id,omitempty"`
}
type CreateCapabilityRequest struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
TargetTypes []string `json:"target_types"`
TargetEntityID string `json:"target_entity_id,omitempty"`
Provider string `json:"provider"`
Operation string `json:"operation"`
Risk string `json:"risk,omitempty"`
ReadOnly bool `json:"read_only"`
ExpectedSideEffects string `json:"expected_side_effects,omitempty"`
}
func (c *Client) Capabilities(ctx context.Context, entityID string) ([]Capability, error) {
var result []Capability
path := "/api/v1/capabilities"
if entityID != "" {
path += "?entity_id=" + entityID
path += "?entity_id=" + url.QueryEscape(entityID)
}
if err := c.do(ctx, http.MethodGet, path, nil, &result); err != nil {
return nil, err
@@ -190,6 +195,33 @@ func (c *Client) GetExecution(ctx context.Context, id string) (*Execution, error
return &result, nil
}
// Executions returns execution history, newest last, ordered by ascending
// `seq` (ECOSYSTEM-SPEC.md §4.5).
//
// entityID, when non-empty, filters to executions against that target entity.
// since is an exclusive cursor: pass 0 for the first page, then the Seq of the
// last element returned. The server caps a page at 100 rows, so a full page
// means "call again with the new cursor".
func (c *Client) Executions(ctx context.Context, entityID string, since int64) ([]Execution, error) {
q := url.Values{}
if entityID != "" {
q.Set("entity_id", entityID)
}
if since > 0 {
q.Set("since", strconv.FormatInt(since, 10))
}
path := "/api/v1/executions"
if len(q) > 0 {
path += "?" + q.Encode()
}
var result []Execution
if err := c.do(ctx, http.MethodGet, path, nil, &result); err != nil {
return nil, err
}
return result, nil
}
func (c *Client) Health(ctx context.Context) error {
return c.do(ctx, http.MethodGet, "/health", nil, nil)
}