Documentation
¶
Overview ¶
Package server hosts ARCP agents. Accept consumes a transport pair and runs one session over it; agents are registered via RegisterAgent / RegisterAgentVersion.
Index ¶
- type AgentFunc
- type Job
- type JobContext
- func (jc *JobContext) ArtifactRef(uri, contentType string, byteSize uint64, sha256 string)
- func (jc *JobContext) Budget() map[arcp.Currency]float64
- func (jc *JobContext) Context() context.Context
- func (jc *JobContext) JobID() string
- func (jc *JobContext) Lease() arcp.Lease
- func (jc *JobContext) Log(level slog.Level, msg string, attrs ...slog.Attr)
- func (jc *JobContext) Metric(name string, value float64, unit string, dims map[string]string)
- func (jc *JobContext) Progress(current uint64, total uint64, units, message string)
- func (jc *JobContext) RotateCredential(id, newValue string) error
- func (jc *JobContext) SessionID() string
- func (jc *JobContext) Status(phase, message string)
- func (jc *JobContext) StreamResult(encoding string) (io.WriteCloser, error)
- func (jc *JobContext) Thought(text string)
- func (jc *JobContext) ToolCall(tool string, args any) string
- func (jc *JobContext) ToolError(callID string, err error)
- func (jc *JobContext) ToolResult(callID string, result any)
- func (jc *JobContext) TraceID() string
- func (jc *JobContext) ValidateLeaseOp(cap arcp.Capability, target string) error
- type Options
- type Server
- func (s *Server) Accept(ctx context.Context, t transport.Transport) error
- func (s *Server) Close() error
- func (s *Server) RegisterAgent(name string, fn AgentFunc)
- func (s *Server) RegisterAgentVersion(name, version string, fn AgentFunc)
- func (s *Server) SetDefaultAgentVersion(name, version string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentFunc ¶
type AgentFunc func(ctx context.Context, input json.RawMessage, jc *JobContext) (any, error)
AgentFunc is the agent body. The runtime invokes it inside a job; returning (any, nil) produces job.result with the marshalled output, returning a non-nil error produces job.error. To stream results, call jc.StreamResult and return (nil, nil) after the writer is closed.
type Job ¶
type Job struct {
// contains filtered or unexported fields
}
Job is the runtime-side representation of an accepted job.
type JobContext ¶
type JobContext struct {
// contains filtered or unexported fields
}
JobContext is the agent-facing surface inside an AgentFunc. It is the only sanctioned way to emit events, validate lease ops, debit budget counters, and stream chunked results.
func (*JobContext) ArtifactRef ¶
func (jc *JobContext) ArtifactRef(uri, contentType string, byteSize uint64, sha256 string)
ArtifactRef emits an "artifact_ref" event.
func (*JobContext) Budget ¶
func (jc *JobContext) Budget() map[arcp.Currency]float64
Budget returns a snapshot of remaining per-currency budget.
func (*JobContext) Context ¶
func (jc *JobContext) Context() context.Context
Context returns the cancellable context bound to this job's lifecycle.
func (*JobContext) Lease ¶
func (jc *JobContext) Lease() arcp.Lease
Lease returns a snapshot of the job's lease grant.
func (*JobContext) Metric ¶
Metric emits a "metric" event. If name begins with "cost." and unit matches a budgeted currency, the runtime debits the counter and may emit a follow-up cost.budget.remaining metric.
func (*JobContext) Progress ¶
func (jc *JobContext) Progress(current uint64, total uint64, units, message string)
Progress emits a "progress" event.
func (*JobContext) RotateCredential ¶
func (jc *JobContext) RotateCredential(id, newValue string) error
RotateCredential updates a stored credential value, emits a submitter status event, and revokes the prior upstream credential.
func (*JobContext) SessionID ¶
func (jc *JobContext) SessionID() string
SessionID returns the owning session id.
func (*JobContext) Status ¶
func (jc *JobContext) Status(phase, message string)
Status emits a "status" event.
func (*JobContext) StreamResult ¶
func (jc *JobContext) StreamResult(encoding string) (io.WriteCloser, error)
StreamResult opens a writer that emits result_chunk events. Close terminates the stream; the runtime emits the final job.result with result_id and result_size when the AgentFunc returns.
func (*JobContext) Thought ¶
func (jc *JobContext) Thought(text string)
Thought emits a "thought" job event.
func (*JobContext) ToolCall ¶
func (jc *JobContext) ToolCall(tool string, args any) string
ToolCall emits a "tool_call" event and returns the generated call_id the agent should reuse in the matching ToolResult / ToolError.
func (*JobContext) ToolError ¶
func (jc *JobContext) ToolError(callID string, err error)
ToolError emits a failed "tool_result" event.
func (*JobContext) ToolResult ¶
func (jc *JobContext) ToolResult(callID string, result any)
ToolResult emits a successful "tool_result" event.
func (*JobContext) TraceID ¶
func (jc *JobContext) TraceID() string
TraceID returns the trace identifier propagated from job.submit.
func (*JobContext) ValidateLeaseOp ¶
func (jc *JobContext) ValidateLeaseOp(cap arcp.Capability, target string) error
ValidateLeaseOp checks that (cap, target) is permitted under the lease at the current clock time.
type Options ¶
type Options struct {
// Name is the runtime's advertised name in session.welcome.
Name string
// Version is the runtime's advertised version.
Version string
// HeartbeatInterval seeds heartbeat_interval_sec in welcome. Zero
// disables heartbeats unless the client negotiates them; default
// is 30s.
HeartbeatInterval time.Duration
// ResumeWindow seeds resume_window_sec; default 600s.
ResumeWindow time.Duration
// Verifier authenticates session.hello tokens. nil accepts no
// tokens.
Verifier auth.Verifier
// Logger is the slog.Logger used by the runtime. nil uses
// slog.Default().
Logger *slog.Logger
// Clock is the time source. nil uses clock.Real().
Clock clock.Clock
// AckLagThreshold is the number of unacked events that triggers a
// back_pressure status emission. Zero disables.
AckLagThreshold uint64
// Features overrides the advertised feature list. Empty uses the
// SDK default.
Features []string
// Provisioner mints lease-bound credentials for accepted jobs. When
// nil, provisioned_credentials is not advertised.
Provisioner credentials.Provisioner
// MaxResultBytes caps a single streamed result. Zero uses 32MiB.
MaxResultBytes int64
// ChunkSize caps an individual result_chunk body. Zero uses 1MiB.
ChunkSize int64
}
Options configures a Server.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the runtime. Construct with New and call Accept once per session.
func (*Server) Accept ¶
Accept runs one session over t. It blocks until t is closed, ctx is cancelled, or an unrecoverable error fires.
func (*Server) RegisterAgent ¶
RegisterAgent registers fn under the bare name.
func (*Server) RegisterAgentVersion ¶
RegisterAgentVersion registers fn under name@version.
func (*Server) SetDefaultAgentVersion ¶
SetDefaultAgentVersion records the version returned for bare-name resolution.
Source Files