acpagent

package
v0.6.1011 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package acpagent is the agent side of the Agent Client Protocol: it lets an editor or an orchestrating agent drive one QuickAgent over a pair of pipes, as the runner itself drives a harness (the other direction, in pkg/runner/adapter).

It speaks JSON-RPC 2.0 over newline-delimited frames: initialize, session/new, session/prompt, session/cancel and session/close, and one request of its own, session/request_permission, to ask the person for the run's consent. It offers its client nothing it did not have, and takes nothing from it that a run would not take from a person at a terminal:

  • One session per connection, and one run behind it. The first prompt starts the run; nothing is verified, installed or started before it, and the run's consent is asked of the client first. A client that cannot show the request, answers it with an error, cancels it, answers with an option the agent did not offer, or does not answer within ConsentTimeout has refused: consent is never assumed.
  • The client's own tools are not used. The agent never calls fs/* or terminal/*, answers a client's call of any method it does not serve with method-not-found, and refuses a session/new that names MCP servers: a QuickAgent's tools are the ones its release declares.
  • Prompts are text (a resource link is read as a note of what the client meant). One prompt is in flight at a time.
  • The connection is bounded: a frame over MaxFrame is refused, and a client that stops reading costs the run nothing (see outbox).

Index

Constants

View Source
const (
	InlineEach  = 256 << 10
	InlineTotal = 1 << 20
)

How much of a deliverable the agent puts in the message itself: a text file up to InlineEach bytes, and InlineTotal bytes of them in all. The rest are handed back as links to the file in the run's folder.

View Source
const (
	// MaxFrame bounds one inbound JSON-RPC line. A longer line is answered
	// with a parse error and read past, and the connection goes on.
	MaxFrame = 1 << 20
	// MaxBehind is how much progress the connection queues for a client that
	// reads slowly. Past it the progress notifications are dropped, so the run
	// never waits for a reader; the answers the client is owed are kept, up
	// to a further mustKeepHeadroom, past which the connection is given up.
	MaxBehind = 16 << 20
)

The bounds the agent side holds the connection to.

View Source
const ProtocolVersion = 1

ProtocolVersion is the protocol version the agent speaks.

Variables

View Source
var ConsentTimeout = 5 * time.Minute

ConsentTimeout is how long the agent waits for the client's answer to the consent request before it counts as refused. A variable so a test can shorten it.

View Source
var ErrConsentRefused = errors.New("the run was not consented to: the client declined it")

ErrConsentRefused is what Consent returns when the person declined the run.

View Source
var ErrConsentUnavailable = errors.New("the run was not consented to: the client did not answer the consent request")

ErrConsentUnavailable is what Consent returns when the client did not answer the request with a choice it was offered: it cannot show a consent request, or it did not answer. Nothing is run on it.

Functions

func Serve

func Serve(ctx context.Context, in io.Reader, out io.Writer, info Info, b Backend) error

Serve speaks the agent side over in and out until the client closes its end, or ends the session and the session's last answer is written. It returns after the run's teardown, which a client going away does not skip.

Types

type Backend

type Backend interface {
	// Run is called once, with the text of the session's first prompt. It
	// prepares the run, asks the person's consent through h, runs, and
	// reports what the client should see through h. It returns when the
	// session is over, after its teardown, and ctx ends when the client
	// cancels the session or goes away.
	Run(ctx context.Context, h *Host, first string) error
}

Backend runs the QuickAgent behind the connection's one session.

type Consent struct {
	// Title is one line: what is asked ("Run acme/weekly?").
	Title string
	// Text is what the person is asked to accept: the release, its
	// capabilities and where the run's output goes.
	Text string
}

Consent is the request the client shows the person before the run starts.

type Host

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

Host is what a Backend reports through.

func (*Host) Consent

func (h *Host) Consent(ctx context.Context, c Consent) error

Consent asks the client to show c and returns nil only if the person chose to run. Everything else — a refusal, a dismissed dialog, a client that answers with an error or with an option it was not offered, no answer in ConsentTimeout, a cancel — is an error, and the run does not start.

func (*Host) Converse

func (h *Host) Converse(ctx context.Context, sess session.Session) error

Converse serves an interactive session: the first prompt is the first turn, each later prompt another, and the session's events are the client's live updates. It returns when the person closes or cancels the session, the client goes away, or the session ends by itself (a budget, a cap, the harness exiting); the caller then ends the session and reports through Finish.

func (*Host) Event

func (h *Host) Event(ev adapter.Event)

Event reports one live event of an autonomous run: a tool call and its result, as the client's tool-call progress. It never blocks.

func (*Host) Finish

func (h *Host) Finish(env *receipt.Envelope, runErr error)

Finish reports the end of the run: for an autonomous run its result and its deliverables, answering the prompt that started it; for a session the deliverables its teardown listed, ahead of the answer to a session/close. env may be nil, and runErr is the run's own error. A run the client cancelled is answered as cancelled by the caller's return, not here.

func (*Host) Say

func (h *Host) Say(text string)

Say tells the person something as the agent's message.

type Info

type Info struct {
	Name    string
	Version string
}

Info names the agent to the client.

Jump to

Keyboard shortcuts

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