remote

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package remote runs an agent launched by the controller (cmd/controller) with the settings and the records of the controller, which alone reaches the database, through its internal API (see agentapi): the flags of its settings, its secrets, the switches of its control panel and the prompt of an LLM agent as they change while it runs, and the storage of its orders, of its decisions and of its journal.

Nothing of the flow of the agent waits for the controller: its records are written to an outbox of its own, a file sent to the controller as it answers, and read back from memory. The controller refusing its token, eg: the agent left running by a controller before, the agent stops.

Index

Constants

This section is empty.

Variables

View Source
var ErrOutboxCorrupt = errors.New("remote: the outbox can't be read")

ErrOutboxCorrupt is the error of an outbox whose file can't be read, see OpenOutbox.

View Source
var ErrUnauthorized = errors.New("remote: the controller refused the token: the agent isn't the one it started")

ErrUnauthorized is the answer of the controller to a token it didn't give, or gave to a start of the agent that ended: the agent isn't the one it runs, eg: left running by a controller before, and must stop.

Functions

This section is empty.

Types

type Agent

type Agent struct {
	Config           agentapi.Config
	APIKey           string
	QuarantineOutbox bool
	// contains filtered or unexported fields
}

Agent is an agent launched by the controller: its settings, the key of its API for this start (see ui.WithAPIKey), and what it keeps through the controller once Open. With QuarantineOutbox, eg: the flag -outbox-quarantine, Open moves an outbox that can't be read aside rather than failing, see OpenOutbox.

func Connect

func Connect(ctx context.Context) (*Agent, error)

Connect returns the agent launched by the controller, its settings read from it, nil when the agent runs on its own: without the token of the controller in its environment (agentapi.EnvToken).

func (*Agent) Args

func (a *Agent) Args() []string

Args returns the flags of the settings of the agent, see agentapi.Config.Args.

func (*Agent) ClaimEntry

func (a *Agent) ClaimEntry(pair string, side model.SideType) (bool, string)

ClaimEntry claims an entry of the bot on pair on side of the controller, while the exposure limit of the agents is on (see agentapi.Entries), before the bot sends it: whether it may go, and why not. A claim that can't be asked refuses the entry, the limit unknown.

func (*Agent) Close

func (a *Agent) Close() error

Close stops sending the records and watching the runtime, writes the orders the outbox failed to write a last time, sends the records left, flushTimeout at most, and closes the outbox. After Serve, the bot stopped.

func (*Agent) Decisions

func (a *Agent) Decisions(ctx context.Context) (*Decisions, error)

Decisions returns the store of the decisions of the LLM agent, see NewDecisions.

func (*Agent) Gate

func (a *Agent) Gate(gate *agentapi.PairGate)

Gate has the assets the strategy of the bot may open positions on follow the ones the controller tells (see agentapi.Entries.EntriesPairs): the ones of its settings at once, then the ones of its runtime as they change, with its entries. Before Run.

func (*Agent) Journal

func (a *Agent) Journal() *Journal

Journal returns the journal of the LLM agent.

func (*Agent) KeepBotStopped

func (a *Agent) KeepBotStopped(ctx context.Context, bot BotSwitch)

KeepBotStopped stops the bot of the agent once it starts, when a user left it stopped (see agentapi.Config.BotStopped): its process started again by a deploy, a reboot, a crash or Reiniciar never trades until a user starts it (Iniciar bot, /start), the bot starting with the agent (see xtrader.Run). Called before the bot runs, it returns at once; nothing without Config.BotStopped.

func (*Agent) Open

func (a *Agent) Open(dir string) error

Open opens the outbox of the agent in dir, eg: data/outbox, a file named after it and its ID, eg: llm-3.db: a new agent taking the name of one deleted never sends the records the other left. Before its records are kept. A file that can't be read fails with ErrOutboxCorrupt, unless QuarantineOutbox: then it is moved aside, to <file>.corrupt-<time>, and the agent starts with an empty outbox (the records of a file read but those it can't, set apart).

func (*Agent) Orders

func (a *Agent) Orders(ctx context.Context) (*Orders, error)

Orders returns the storage of the orders of the agent, see NewOrders, the orders it failed to write written again by Close.

func (*Agent) Prompt

func (a *Agent) Prompt() llm.Prompt

Prompt returns the prompt selected for the LLM agent, its default one when none is.

func (*Agent) Prompts

func (a *Agent) Prompts() *Prompts

Prompts returns the source of the prompts of the LLM agent, nil for an agent of another kind.

func (*Agent) Protect

func (a *Agent) Protect(protection Protection)

Protect has the protection of the positions of the bot follow the one the controller tells (see agentapi.Protection): the one of its settings at once, before the bot trades, then the one of its runtime as it changes, with its entries, before its prompt. Before Run.

func (*Agent) Run

func (a *Agent) Run(ctx context.Context, apply func(agentapi.Runtime)) context.Context

Run sends the records of the outbox to the controller, and applies the runtime of the agent as it changes: its prompt, kept by Prompts, and its switches, handed to apply with the rest, once at first. It returns the context of the agent: done with ctx, or when the controller refuses the agent, which must then stop, ErrUnauthorized its cause. After Open.

func (*Agent) Serve

func (a *Agent) Serve(ctx context.Context, apply func(agentapi.Runtime), run func(context.Context) error) error

Serve runs the agent (see Run) and its bot with run, until the bot ends or the context of the agent is done: a signal, or the controller refusing the agent, ErrUnauthorized then. Then the bot stops trading before Serve returns: run must return once its context is done, the orders it executed recorded in the outbox, as xtrader.XTrader.Run does, so that Close sends and closes an outbox nothing writes an order to any more.

func (*Agent) Supervise

func (a *Agent) Supervise(controller Entries)

Supervise has the entries of the bot of controller follow the ones the controller tells (see agentapi.Entries): the ones of its settings at once, before the bot trades, then the ones of its runtime as they change, before its prompt, whose switch may fail: a block never waits for it. Before Run.

type BotSwitch

type BotSwitch interface {
	Status() order.Status
	Stop()
}

BotSwitch is the bot of an agent, stopped by KeepBotStopped, see order.Controller.

type Client

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

Client calls the internal API of the controller for an agent, with the token of its start (see agentapi).

func NewClient

func NewClient(baseURL, token string) (*Client, error)

NewClient returns the client of the internal API at baseURL, eg: http://127.0.0.1:8090, authenticated with token.

func (*Client) Attachment

func (c *Client) Attachment(ctx context.Context, id string, index int) (string, []byte, error)

Attachment returns the attachment index of the decision id and its media type, ui.ErrUnknownDecision when there is none.

func (*Client) CheckOutbox

func (c *Client) CheckOutbox(ctx context.Context, records []agentapi.Record) error

CheckOutbox asks the controller whether it writes the records, none written: nil when it does, a *RefusedError naming the one it refuses for good.

func (*Client) ClaimEntry

func (c *Client) ClaimEntry(ctx context.Context, pair, side string) (agentapi.ExposureAnswer, error)

ClaimEntry claims an entry on pair on side against the exposure limit of the agents, see agentapi.ExposureClaim.

func (*Client) Config

func (c *Client) Config(ctx context.Context) (agentapi.Config, error)

Config returns the settings of the agent, its secrets included.

func (*Client) Decision

func (c *Client) Decision(ctx context.Context, id string) (ui.Decision, bool, error)

Decision returns the decision of id, false when unknown.

func (c *Client) DecisionLinks(ctx context.Context) (map[int64]string, error)

DecisionLinks returns the decision that placed each order of the agent.

func (*Client) Decisions

func (c *Client) Decisions(ctx context.Context, pair string, limit int) ([]ui.Decision, error)

Decisions returns the last decisions of pair, of every pair when empty, newest first, limit at most.

func (*Client) DecisionsPerPair

func (c *Client) DecisionsPerPair(ctx context.Context, perPair int) ([]ui.Decision, error)

DecisionsPerPair returns the last decisions of each pair, perPair of them.

func (*Client) Discards

func (c *Client) Discards(ctx context.Context) ([]model.Discard, error)

Discards returns the positions the order controller of the agent discarded, by the fill after which each one was.

func (*Client) JournalMemory

func (c *Client) JournalMemory(ctx context.Context, perPair int) ([]agentapi.Remembered, error)

JournalMemory returns the last decisions of each pair of the journal of the agent, perPair of them.

func (*Client) LeaseOrderIDs

func (c *Client) LeaseOrderIDs(ctx context.Context, count int64) (agentapi.OrderIDs, error)

LeaseOrderIDs leases count order IDs.

func (*Client) Orders

func (c *Client) Orders(ctx context.Context, after int64, limit int) ([]model.Order, error)

Orders returns the orders of the agent after the ID after, by ID, limit at most.

func (*Client) Outbox

func (c *Client) Outbox(ctx context.Context, request agentapi.OutboxRequest) (uint64, error)

Outbox writes the records of request, and returns the Seq of the last one written: a *RefusedError names the record refused, none written.

func (*Client) Prompt

func (c *Client) Prompt(ctx context.Context) (agentapi.Prompt, bool, error)

Prompt returns the prompt selected for the agent, false for its default one.

func (*Client) Runtime

func (c *Client) Runtime(ctx context.Context, version int64, wait time.Duration) (agentapi.Runtime, bool,
	error)

Runtime returns what the agent applies while it runs: with version, the one it applies, it waits up to wait for a change, changed false without one.

type Decisions

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

Decisions is the store of the decisions of an LLM agent launched by the controller (llm.DecisionStore): each saved through the outbox, the last ones held in memory with the decisions that placed the orders, which the chart reads holding its lock, the older ones read from the controller.

func NewDecisions

func NewDecisions(ctx context.Context, client *Client, outbox *Outbox) (*Decisions, error)

NewDecisions returns the decisions of the agent: the last ones of the controller, and the ones of the outbox not sent yet, newer.

func (*Decisions) Attachment

func (s *Decisions) Attachment(id string, index int) (string, []byte, error)

Attachment implements llm.DecisionStore.

func (*Decisions) Decision

func (s *Decisions) Decision(id string) (ui.Decision, bool, error)

Decision implements llm.DecisionStore.

func (*Decisions) Decisions

func (s *Decisions) Decisions(pair string, limit int) ([]ui.Decision, error)

Decisions implements llm.DecisionStore: the ones held, with the older ones of the controller when they are too few, or else alone while the controller is out of reach.

func (*Decisions) OrderDecision

func (s *Decisions) OrderDecision(orderID int64) string

OrderDecision implements llm.DecisionStore, from memory.

func (*Decisions) Save

func (s *Decisions) Save(d ui.Decision, attachments []llm.Attachment) error

Save implements llm.DecisionStore.

type Entries

type Entries interface {
	BlockEntries(revision int64, reason string) bool
	AllowEntries(revision int64) bool
}

Entries is the order controller of a bot whose entries the controller blocks and allows again, eg: *order.Controller, see Supervise.

type Journal

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

Journal is the journal of an LLM agent launched by the controller (llm.Journal): each call to the model written through the outbox, the memory of its prompt read back from the controller.

func NewJournal

func NewJournal(client *Client, outbox *Outbox) *Journal

NewJournal returns the journal of the agent.

func (*Journal) Append

func (j *Journal) Append(entry llm.JournalEntry) error

Append implements llm.Journal.

func (*Journal) Recent

func (j *Journal) Recent(perPair int) ([]llm.Remembered, error)

Recent implements llm.Journal: the decisions of the controller, then the ones of the outbox not sent yet.

type Notifier

type Notifier interface {
	Notify(message string)
	OnError(err error)
}

Notifier is told of the orders the outbox fails to write and of their write at last, eg: the chart of the bot, which the controller relays to Telegram.

type Orders

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

Orders is the storage of the orders of an agent launched by the controller (storage.Storage): in memory, each change written through the outbox, the orders numbered with IDs leased from the controller ahead of their need, so CreateOrder never waits for it: the order is at the broker already when it is called. The orders are handed as copies. A state of an order older than the one kept is neither kept nor written, as the controller would refuse it (see model.Order.Supersedes), eg: the copy of a move written after a fill.

The order at the broker already, a failure of the outbox, eg: a full disk, is never an error of CreateOrder nor of UpdateOrder: the order kept in memory is followed by the bot all the same, the failure logged and notified, and its last state written again until the outbox takes it, see Close.

func NewOrders

func NewOrders(ctx context.Context, client *Client, outbox *Outbox) (_ *Orders, err error)

NewOrders returns the orders of the agent: the ones of the controller, and the ones of the outbox not sent yet, newer, with the IDs leased to it; so are the positions its order controller discarded. The next IDs are leased until ctx is done or Close, see lease.

func (*Orders) Close

func (o *Orders) Close() error

Close stops leasing the next order IDs and writing the orders unwritten again, after a last attempt, as the agent stops, before its outbox is flushed: it returns the error of the ones still unwritten, never sent to the controller.

func (*Orders) CreateDiscard

func (o *Orders) CreateDiscard(discard model.Discard) error

CreateDiscard keeps a position the order controller discarded, written through the outbox, once: the controller keeps it once too. A failure of the outbox is its error, the discard kept in memory for this run only.

func (*Orders) CreateOrder

func (o *Orders) CreateOrder(order *model.Order) error

CreateOrder numbers the order and keeps it. It never fails: the order is at the broker already, see Orders.

func (*Orders) Discards

func (o *Orders) Discards() ([]model.Discard, error)

Discards returns the positions the order controller discarded.

func (*Orders) Orders

func (o *Orders) Orders(filters ...storage.OrderFilter) ([]*model.Order, error)

Orders returns copies of the orders the filters keep, by their update, as the storage of the files did.

func (*Orders) SetNotifier

func (o *Orders) SetNotifier(notifier Notifier)

SetNotifier sets who is told of the orders the outbox fails to write.

func (*Orders) UpdateOrder

func (o *Orders) UpdateOrder(order *model.Order) error

UpdateOrder keeps the order as it is, its UpdatedAt the one of the order controller, unless older than the one kept (see Orders). It never fails, see CreateOrder.

type Outbox

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

Outbox is the queue of the records an agent keeps through the controller: each written to a file of its own before Add returns, in order, then sent to the controller in batches as it answers (see Run), so the agent neither waits for the controller nor loses a record while it is out of reach. A record the controller refuses for good is set apart, and one it fails again and again alone while it writes the next ones of its kind, held apart (see send): the next ones sent.

The file is a buntdb synced by the outbox itself after each write, whose failure is an error of the write, and never rewritten by buntdb, whose rewrite syncs neither the new file nor its directory: the outbox compacts it itself, durably (see compact). A record written is lost only with the disk or a machine that lies about its syncs.

func OpenOutbox

func OpenOutbox(file string, client sender) (*Outbox, error)

OpenOutbox opens the outbox of file, eg: data/outbox/llm-3.db, its records sent with client, locked for this process: another process of the agent, eg: left running by a controller before, holds it. A file that can't be read, eg: written over in the middle, fails with ErrOutboxCorrupt, left as it is, see openOutboxFile; one cut short, eg: the agent killed in the middle of a write, opens with the records before the cut.

func (*Outbox) Add

func (o *Outbox) Add(kind, key string, payload any) error

Add writes the record of kind and key, of the JSON of payload, at the end of the outbox, on disk when it returns, and wakes the sender. A record the file fails to sync is an error, sent all the same while the agent runs.

func (*Outbox) Close

func (o *Outbox) Close() error

Close closes the outbox and releases its lock.

func (*Outbox) Flush

func (o *Outbox) Flush(ctx context.Context) error

Flush sends the records left until none is, the controller refusing the agent, or ctx done, eg: as the agent stops: then it fails, telling how many are left, sent by the next start.

func (*Outbox) Pending

func (o *Outbox) Pending(kind string) ([]agentapi.Record, error)

Pending returns the records of kind not sent yet, the ones held apart (see hold) included, in order, eg: the orders of a run before that didn't reach the controller.

func (*Outbox) Run

func (o *Outbox) Run(ctx context.Context) error

Run sends the records to the controller as they come, until ctx is done: after a failure, the same batch again after a wait (see send). It returns ErrUnauthorized when the controller refuses the agent.

type Prompts

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

Prompts is the source of the prompts of an LLM agent launched by the controller (llm.PromptSource): the prompt selected for it, kept as the runtime of the agent changes (see Agent.Run), so the Trader reads it without a request. What comes of each prompt is told to the controller through the outbox (llm.PromptReporter).

func (*Prompts) Current

func (p *Prompts) Current(known ui.DecisionPrompt) (llm.Prompt, bool)

Current implements llm.PromptSource.

func (*Prompts) Prompt

func (p *Prompts) Prompt() llm.Prompt

Prompt returns the prompt selected for the agent.

func (*Prompts) ReportPrompt

func (p *Prompts) ReportPrompt(ref ui.DecisionPrompt, err error)

ReportPrompt implements llm.PromptReporter.

type Protection

type Protection interface {
	Apply(settings *ui.ProtectionSettings, arms []ui.ProtectionArm)
	ApplyDailyStops(stops []ui.DailyStop)
}

Protection is the protection of the positions of the bot as the controller sets it, see agentapi.Protection and protect.Manager.

type RefusedError

type RefusedError struct {
	Index   int
	Message string
}

RefusedError is the answer of the controller to a batch of the outbox whose record at Index it refuses for good, none of them written.

func (*RefusedError) Error

func (e *RefusedError) Error() string

type StatusError

type StatusError struct {
	Status  int
	Message string
}

StatusError is an answer of the controller other than a success.

func (*StatusError) Error

func (e *StatusError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL