api

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Jul 11, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package api provides an HTTP client for the reef-core REST API.

Authentication

Most endpoints that mutate state (spawn, kill, send_task) require an Authorization: Bearer <base64-session-token> header. The session token is a 32-byte secret base64-encoded. Get one in dev via: 

cd reef-core && mix reef_core.dev_session -q

Production auth is not yet wired (reef-core's :require_session_token plug is currently the only gate). Real OAuth/passkey will layer on top.

Package api provides an HTTP client for the reef-core REST API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Error string `json:"error"`
}

APIError wraps a JSON error response body from reef-core.

type Agent 

type Agent struct {
	ID           string `json:"id"`
	Name         string `json:"name"`
	Status       string `json:"status"`
	StartedAt    string `json:"started_at,omitempty"`
	LastActivity string `json:"last_activity,omitempty"`
}

Agent is a summary row returned by GET /api/agents.

This shape is loose — reef-core's list endpoint is still a dev/debug view and its fields may evolve. Only ID and Name are stable.

type AgentEvent 

type AgentEvent struct {
	Event   string         `json:"event"`
	Payload map[string]any `json:"payload"`
	At      string         `json:"at"`
}

AgentEvent is a single event from an agent's buffered log.

type AgentsResponse 

type AgentsResponse struct {
	Agents []Agent `json:"agents"`
}

AgentsResponse wraps GET /api/agents.

type Budget 

type Budget struct {
	TotalBudget int64            `json:"total_budget"`
	TotalSpent  int64            `json:"total_spent"`
	Remaining   int64            `json:"remaining"`
	Utilization float64          `json:"utilization"`
	AgentSpend  map[string]int64 `json:"agent_spend"`
}

Budget is the pod-wide budget summary from GET /api/budget.

type Client 

type Client struct {
	BaseURL      string
	SessionToken string
	HTTPClient   *http.Client
}

Client talks to a reef-core instance over HTTP.

Set SessionToken to the base64-encoded session token to authenticate mutating requests. Leaving it empty is fine for read-only calls (list agents, get budget, get proofs).

func NewClient 

func NewClient(baseURL string) *Client

NewClient creates a Client pointing at the given reef-core base URL.

func (*Client) DownloadDeliverable added in v0.1.2 

func (c *Client) DownloadDeliverable(agentID, path string) ([]byte, error)

DownloadDeliverable fetches the raw bytes of a single deliverable. path must be one of the paths returned by ListDeliverables (its "output/" prefix included) — its content is passed to reef-core verbatim, but each "/"-separated segment is URL-escaped first (see escapePathSegments) so a hostile or malformed listed path can't reinterpret the request's path structure. reef-core additionally resolves the decoded path against the agent's own workspace and rejects any attempt to escape it.

Requires a session token.

func (*Client) GetBudget 

func (c *Client) GetBudget() (*Budget, error)

GetBudget returns the pod-wide budget summary.

func (*Client) GetEventLog 

func (c *Client) GetEventLog(agentID string) ([]AgentEvent, error)

GetEventLog returns the buffered event log for an agent. Events are in chronological order (oldest first), up to 200 entries.

func (*Client) GetProofs 

func (c *Client) GetProofs(limit int) ([]Proof, error)

GetProofs returns the most recent proof commitments, up to limit.

func (*Client) GetProofsByAgent 

func (c *Client) GetProofsByAgent(agentID string) ([]Proof, error)

GetProofsByAgent returns all proof commitments for a specific agent, including the spawn-time links (structured_bundle, openbrain_snapshot) that don't carry a task_id.

func (*Client) GetProofsByTask 

func (c *Client) GetProofsByTask(taskID string) ([]Proof, error)

GetProofsByTask returns the chain of proof commitments for a specific task. For a completed task this will be the full 4-link custody chain: structured_bundle → openbrain_snapshot → [capture_commitment] → custody.

Note: the structured_bundle and openbrain_snapshot proofs are tagged with agent_id (not task_id) because they're emitted at spawn time before the task exists. GetProofsByTask only returns the task-scoped links (capture_commitment + custody). Use GetProofsByAgent to walk the whole chain.

func (*Client) KillAgent 

func (c *Client) KillAgent(id string) error

KillAgent stops and removes an agent by ID.

Requires a session token.

func (*Client) ListAgents 

func (c *Client) ListAgents() ([]Agent, error)

ListAgents returns all agents in the pod.

func (*Client) ListDeliverables added in v0.1.2 

func (c *Client) ListDeliverables(agentID string) ([]Deliverable, error)

ListDeliverables returns the output files an agent's run produced (reef-core's agent-deliverables-api, MR !21). Paths carry the "output/" workspace prefix; pass them verbatim to DownloadDeliverable.

Requires a session token.

func (*Client) ListMemoryEntries 

func (c *Client) ListMemoryEntries(filter MemoryFilter) ([]MemoryEntry, error)

ListMemoryEntries returns Layer 1 / Layer 2 knowledge entries from reef-core's knowledge store, filtered by the optional fields in the MemoryFilter argument. Empty fields are omitted from the query string.

Used by the lifecycle smoke (--memory-roundtrip) to verify that structural extraction actually persisted entries after agent_exited.

func (*Client) SendTask 

func (c *Client) SendTask(id, task string) error

SendTask dispatches a task string to a running agent.

NOTE: with the current one-shot spawn model, a pod's task is set at spawn time and the runtime exits after it completes. This endpoint remains for future long-running dolphin pods that can accept additional tasks; for lobster pods in v1 it is rarely useful.

Requires a session token.

func (*Client) SpawnAgent 

func (c *Client) SpawnAgent(req SpawnRequest) (*SpawnResponse, error)

SpawnAgent creates a new pod with the given task and returns the full spawn response (all five IDs + bundle metadata).

Requires a session token.

func (*Client) SpawnPod added in v0.1.2 

func (c *Client) SpawnPod(req SpawnPodRequest) (*SpawnResponse, error)

SpawnPod spawns a pod straight from a manifest + content files (Mode A, POST /api/pods/spawn) — the path `konareef pod run` uses against a locally installed pod, as opposed to SpawnAgent's free-form task string (Mode B, POST /api/agents).

Requires a session token.

func (*Client) WithToken 

func (c *Client) WithToken(token string) *Client

WithToken returns a copy of the client with the given session token set.

type Deliverable added in v0.1.2 

type Deliverable struct {
	Path string `json:"path"`
	Size int64  `json:"size"`
}

Deliverable is a single output-file row from GET /api/agents/:id/deliverables (reef-core's agent-deliverables-api, MR !21). Path carries the "output/" workspace prefix verbatim; pass it unmodified to DownloadDeliverable.

type DeliverablesResponse added in v0.1.2 

type DeliverablesResponse struct {
	Deliverables []Deliverable `json:"deliverables"`
}

DeliverablesResponse wraps GET /api/agents/:id/deliverables.

type EventLogResponse 

type EventLogResponse struct {
	Events []AgentEvent `json:"events"`
}

EventLogResponse wraps GET /api/agents/:id/log.

type MemoryEntriesResponse 

type MemoryEntriesResponse struct {
	Entries []MemoryEntry `json:"entries"`
}

MemoryEntriesResponse wraps the {"entries": [...]} envelope returned by GET /api/memory/entries.

type MemoryEntry 

type MemoryEntry struct {
	ID              string   `json:"id"`
	Category        string   `json:"category"`
	Layer           string   `json:"layer"`
	FlaggedCategory string   `json:"flagged_category,omitempty"`
	Tags            []string `json:"tags"`
	Content         string   `json:"content"`
	Why             string   `json:"why,omitempty"`
	Source          string   `json:"source"`
	Project         string   `json:"project,omitempty"`
	PodRunID        string   `json:"pod_run_id,omitempty"`
	SourceSessionID string   `json:"source_session_id,omitempty"`
	ProofHash       string   `json:"proof_hash,omitempty"`
	InsertedAt      string   `json:"inserted_at"`
	UpdatedAt       string   `json:"updated_at"`
}

MemoryEntry is a single Layer 1 / Layer 2 knowledge entry returned by reef-core's GET /api/memory/entries endpoint. It mirrors the fields of ReefCore.Knowledge.KnowledgeEntry serialized by MemoryController.

type MemoryFilter 

type MemoryFilter struct {
	PodRunID string // ?pod_run_id=...
	Project  string // ?project=...
	Layer    string // "structural" | "flagged" | ""
	Limit    int    // 0 means server default (50)
}

MemoryFilter applies optional query-string filters when listing memory entries. Empty fields are omitted from the request.

type PodAttestation 

type PodAttestation struct {
	PodHash            string `json:"pod_hash"`
	PodVersion         string `json:"pod_version"`
	PublisherID        string `json:"publisher_id"`
	PublisherSignature string `json:"publisher_signature"`
	PublisherPubkey    string `json:"publisher_pubkey"`
}

PodAttestation is the wire shape reef-core's spawn endpoint expects. Binary fields ride as: pod_hash → 64-char lowercase hex; publisher_signature, publisher_pubkey → standard base64.

All five fields are required when PodAttestation is non-nil; reef-core's AttestationParser returns 422 with `pod_attestation_invalid` + the offending field name on any missing or malformed subfield.

type Proof 

type Proof struct {
	ID              string `json:"id"`
	ProofType       string `json:"proof_type"`
	Hash            string `json:"hash"`
	PrevHash        string `json:"prev_hash"`
	Data            string `json:"data"`
	Timestamp       string `json:"timestamp"`
	Txid            string `json:"txid"`
	BroadcastStatus string `json:"broadcast_status"`
	AgentID         string `json:"agent_id"`
	TaskID          string `json:"task_id"`
	InsertedAt      string `json:"inserted_at"`
}

Proof is a proof commitment row from GET /api/proofs.

Matches reef-core's v3 custody chain shape emitted by ReefCoreWeb.ProofController.serialize/1.

type ProofsResponse 

type ProofsResponse struct {
	Proofs []Proof `json:"proofs"`
}

ProofsResponse wraps GET /api/proofs.

type SpawnPodRequest added in v0.1.2 

type SpawnPodRequest struct {
	PodToml        string            `json:"pod_toml"`
	Inputs         map[string]string `json:"inputs,omitempty"`
	Files          map[string]string `json:"files"`
	PodAttestation *PodAttestation   `json:"pod_attestation,omitempty"`
}

SpawnPodRequest is the JSON body for POST /api/pods/spawn (Mode A): spawn straight from a pod manifest + its content files, rather than the free-form task string POST /api/agents (SpawnRequest) expects.

Used by `konareef pod run` against a pod previously installed and signature-verified by `konareef install`: PodToml + Files come from the install cache's content/ directory, Inputs are the buyer's --input k=v flags, and PodAttestation is attached when the cache also holds a signed manifest (nil for an unsigned/dev pod).

type SpawnRequest 

type SpawnRequest struct {
	Task             string            `json:"task"`
	PodKind          string            `json:"pod_kind,omitempty"`
	Model            string            `json:"model,omitempty"`
	BudgetSats       int64             `json:"budget_sats,omitempty"`
	MaxIterations    int               `json:"max_iterations,omitempty"`
	StructuredMemory map[string]string `json:"structured_memory,omitempty"`

	// PodAttestation, when non-nil, carries the publisher signing
	// metadata for a cached signed pod. reef-core's spawn flow
	// populates the resulting structured_bundle commitment's
	// pod_hash, pod_version, publisher_id, publisher_signature
	// columns so the custody chain can be tied back to a signed
	// manifest. Absence is the v0 unsigned-spawn path. See
	// prd-p0-3-spawn-attestation-wiring.md §"Required request shape".
	PodAttestation *PodAttestation `json:"pod_attestation,omitempty"`
}

SpawnRequest is the JSON body for POST /api/agents.

Requires a valid session token in the Authorization header.

type SpawnResponse 

type SpawnResponse struct {
	AgentID         string `json:"agent_id"`
	PodID           string `json:"pod_id"`
	TaskID          string `json:"task_id"`
	SnapshotID      string `json:"snapshot_id"`
	BundleHash      string `json:"bundle_hash"`
	BundleFileCount int    `json:"bundle_file_count"`
}

SpawnResponse is the response body from POST /api/agents.

All five IDs are returned so the caller can audit and verify the resulting proof chain afterwards.

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.