Skip to content

runtime.md

Latest commit

 

History

History
100 lines (77 loc) · 3.17 KB

runtime.md

File metadata and controls

100 lines (77 loc) · 3.17 KB
Raw

Runtime API

Import the public facade:

import agentruntime "github.com/colinagent/opagent/opagent-runtime/runtime"

Lifecycle

rt, err := agentruntime.New(agentruntime.Options{})
if err != nil {
    return err
}
defer rt.Close(context.Background())

runErr := make(chan error, 1)
go func() { runErr <- rt.Run(ctx) }()

select {
case <-rt.Ready():
    if err := rt.Err(); err != nil {
        return err
    }
case err := <-runErr:
    return err
}

Run initializes the Runtime and blocks until shutdown or failure. It may be called once. Close(ctx) cancels work, closes endpoint connections, and waits for cleanup. v0.1 allows one Runtime instance per process; a second New returns ErrRuntimeAlreadyExists.

Handlers require a ready Runtime:

result, err := rt.HandleNode(ctx, &op.OpNodeRequest{Params: params})
agentResult, err := rt.HandleAgent(ctx, &op.OpAgentRequest{Params: agentParams})

Handler contexts are cancelled by either the request context or Runtime shutdown.

Trusted standalone hosts that atomically update files under configs/user/ may call ReloadUserConfig(ctx) to make model changes visible before the filesystem watcher debounce completes. Host-managed deployments using ConfigLoader should keep configuration ownership in that loader instead of mixing both paths.

Events

events, unsubscribe := rt.Subscribe(128)
defer unsubscribe()
for event := range events {
    // event is *op.InfoNotificationParams
}

Subscriptions are bounded. A slow subscriber drops its own notifications and never blocks the Agent loop. Durable reconstruction must use the thread snapshot/JSONL rather than assuming the event stream is lossless.

Options and host ownership

Option Host responsibility
BaseDir, Env, Debug Process-local storage and diagnostics
ConfigLoader Supply complete host-managed system/user config
ApprovalReviewer Review an out-of-policy action; absence falls back to user approval
HeaderResolver Resolve host-owned placeholders for remote endpoints
SystemServiceAuthorizer Explicitly authorize a privileged system service
RemoteNodeAuthorizer Explicitly authorize a remote node before connection
PromptAugmenter Add bounded host context to the system prompt
ToolScope Transform or constrain tool arguments before execution
CronPolicy Accept or reject scheduled operations
BackgroundServices Run host services under the Runtime lifecycle context

Unknown system services and remote nodes are denied by default. User files cannot grant the trust represented by these hooks.

Base directory

Resolution order is Options.BaseDir, OPAGENT_BASE_DIR, then ~/.opagent. The result is normalized to an absolute path and all token, thread, log, object, sandbox, and package paths derive from it. No deprecated directory is read, moved, deleted, or used as a fallback.

Direct executable

The standalone command uses the same core:

go run ./opagent-runtime/cmd/opagent-runtime --help

Embedding is preferred when a host must supply policy hooks. For a small HTTP host, use opagent-server instead of recreating lifecycle and event bridging.