orchagent

package module
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

README

orchagent

The orchestration stack for all your agent needs.

Install · Report Bug · Go Docs

CI   Go Reference   License

Contents

Define an agent in a .agent.md file, connect it to Slack, GitHub, Jira, cron or a webhook, and orchagent runs it: each run finishes exactly once despite crashes, touches only what its policy grants, and streams its events to every subscriber. It is a Go library. It starts no server and reads no configuration: you compose it with orchagent.New, and anything you do not pass is a complete in-memory implementation.

Features

  • One entry point: orchagent.New(ctx, opts...) returns an App with the bus, definitions, durable runtime, sandbox and connectors wired. app.Define stores an agent, app.Ask runs it and streams the reply.
  • Agents are documents: store a saige .agent.md and it runs, with no redeploy. A run pins its definition's version, so a retry never runs a newer prompt.
  • Durable runs: a ledger, a queue with leases and fencing, and a worker that resumes after a crash without re-executing recorded steps.
  • Sandboxed tools: tools see only the workspace their NGAC policy grants, in process or isolated with Docker, gVisor or Kubernetes.
  • Connectors in and out: an event can arrive from GitHub and its answer stream to Slack, while a webhook receives only the completion.
  • Backends are values: orchagent.WithPostgres(pool) and orchagent.WithBus(...) move every store to Postgres. No config files, no environment variables.
  • Each layer stands alone: import durable or sandbox without flow when you need only durable execution or sandboxing.

Installation

Prerequisites

Requirement Version
Go 1.26+
Docker for the Postgres and Redis adapters (compose.yaml)
go get github.com/urmzd/orchagent

The Kubernetes Job runner is its own module, so only programs that use it inherit client-go:

go get github.com/urmzd/orchagent/sandbox/runner/k8s

Quick Start

An agent with its own model provider and tool, answering one message, with no API key and no external services:

// Command downstream is what a team building on flow ships instead of a fork:
// its own program, composing flow in Go, plus what it registers.
//
// It adds three things in Go:
//
//   - a model provider named "house", standing in for an in-house model
//     client. Here it is saige's scripted provider, so the example runs with
//     no key and no network; a real one returns the team's own
//     saige Provider.
//   - an OpenAI-compatible endpoint named "fireworks", selected by the same
//     model.use field, with its key read from $FIREWORKS_API_KEY at run time.
//   - a tool, "lookup_runbook", that any agent can be granted by name.
//
// It stores the agent agents/oncall.agent.md defines, on the house provider, asks it one question in process and
// prints the answer:
//
//	go run ./examples/downstream
package main

import (
	"context"
	_ "embed"
	"errors"
	"fmt"
	"os"
	"os/signal"

	"github.com/urmzd/orchagent"
	"github.com/urmzd/orchagent/flow/turn/native/agenttest"
)

// oncall is the agent, as a saige definition file.
//
//go:embed agents/oncall.agent.md
var oncall string

func main() {
	if err := run(); err != nil {
		fmt.Fprintln(os.Stderr, "downstream:", err)
		os.Exit(1)
	}
}

func run() error {
	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
	defer cancel()

	// Everything is in memory unless an option says otherwise: a program
	// on Postgres adds orchagent.WithPostgres(pool) and orchagent.WithBus(...).
	app, err := orchagent.New(ctx,
		orchagent.WithTenant("acme"),
		orchagent.WithModelProvider("house", houseProvider),
		orchagent.WithOpenAICompatible(orchagent.OpenAICompatible{
			Name:    "fireworks",
			BaseURL: "https://api.fireworks.ai/inference/v1",
			KeyEnv:  "FIREWORKS_API_KEY",
		}),
		orchagent.WithTools(runbookTool{}),
	)
	if err != nil {
		return err
	}
	defer func() { _ = app.Close() }()

	// Delivery and execution, in this process, until ctx ends.
	done := make(chan error, 1)
	go func() { done <- app.Run(ctx) }()

	// Define is insert-only: storing the same file again is a no-op.
	if _, err := app.Define(ctx, oncall); err != nil {
		return err
	}

	// Ask runs the agent once and streams its reply.
	reply, err := app.Ask(ctx, "oncall", "api is down")
	if err != nil {
		return err
	}
	defer func() { _ = reply.Close() }()
	answer, err := reply.Text(ctx)
	if err != nil {
		return err
	}
	fmt.Printf("%s\nrun %s: completed\n", answer, reply.RunID)
	cancel()
	if err := <-done; err != nil && !errors.Is(err, context.Canceled) {
		return err
	}
	return nil
}

// houseProvider builds the model client for one agent version. It receives
// the whole spec, so it can key on the model name or the agent.
func houseProvider(spec orchagent.Spec) (orchagent.Provider, error) {
	p := &agenttest.ScriptedProvider{}
	p.Responses = append(p.Responses,
		agenttest.TextResponse(spec.Name+" answered on the house model ("+spec.Model+")."))
	return p, nil
}

// runbookTool is a tool the team owns. Any orchagent.Tool works.
type runbookTool struct{}

func (runbookTool) Definition() orchagent.ToolDef {
	return orchagent.ToolDef{
		Name:        "lookup_runbook",
		Description: "Look up the on-call runbook for a service.",
		Parameters: orchagent.ParameterSchema{
			Type:       "object",
			Properties: map[string]orchagent.PropertyDef{"service": {Type: "string"}},
			Required:   []string{"service"},
		},
	}
}

func (runbookTool) Execute(_ context.Context, args map[string]any) (string, error) {
	service, _ := args["service"].(string)
	return "Restart " + service + " with `make restart`, then page the owner.", nil
}
go run ./flow/examples/downstream

The agent it runs is a definition file:

---
apiVersion: saige/v1
name: oncall
version: 1.0.0
description: helps the on-call engineer
model:
  use: house/house-1
tools:
  registry:
    - lookup_runbook
---
Help the on-call engineer.

Examples

Example Description
flow/examples/downstream Your own program on orchagent: a model provider, an OpenAI-compatible endpoint and a tool
flow/examples/local The full stack offline: versioned agents, one run to two sinks, citations, replay
durable/examples/quickstart An order workflow on Postgres and Redis that survives a killed worker
durable/examples/chaos Cross-process chaos test that SIGKILLs a worker mid-activity
sandbox/examples/basic A sandboxed tool on a bounded pool, with metrics
sandbox/examples/ngac Access defined as an NGAC policy graph, including agent spawn
sandbox/examples/saige Saige agents run as sandbox workloads

The durable examples need Postgres and Redis:

docker compose up -d --wait
go run ./durable/examples/quickstart

Usage

Pick the import that matches the job:

You need Import Start with
Run an agent and read its reply orchagent orchagent.New, app.Define, app.Ask
Every option and store: connectors, memberships, knowledge orchagent/flow flow.With*, app.Publish, app.Memberships
Work that finishes once despite crashes orchagent/durable durable.New, durable.Start, durable.Exec
Tools confined by policy orchagent/sandbox/... controlplane.NewMemory, sandbox.Policy

Each component ships a CLI that validates it on its own:

Command Validates
go run ./flow/cmd/flow run an .agent.md against a message, printing its events
go run ./sandbox/cmd/sandbox run "go test ./..." a command under a sandbox policy
go run ./durable/adapters/postgres/cmd/durable a Postgres ledger: list, show, replay

Stored names

Names that live in databases or on the wire keep their original spelling so existing data stays readable: fiber_* tables, fiber:// channel URIs, fiber.* event kinds and the X-Fiber-Secret header. Renaming them needs a data migration.

Development

make init               # git hooks, download modules
make check              # fmt, vet, lint, race tests for both modules
make test-integration   # Postgres and Redis adapters (uses compose.yaml)

Documentation

Agent Skill

This repo's conventions are available as portable agent skills in skills/.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package orchagent is the orchestration stack for all your agent needs.

New composes the whole stack (agent definitions, the event bus, the durable runtime, the sandbox and the connectors) into an App, and Ask runs one agent and returns its reply:

app, err := orchagent.New(ctx,
	orchagent.WithTenant("acme"),
	orchagent.WithModelProvider("house", houseProvider),
	orchagent.WithTools(runbookTool{}),
)
if err != nil { ... }
defer app.Close()
go app.Run(ctx)
_, err = app.Define(ctx, oncallAgentMD) // an .agent.md file
reply, err := app.Ask(ctx, "oncall", "api is down")
if err != nil { ... }
defer reply.Close()
answer, err := reply.Text(ctx)

This package names the common path. Everything else is in its component: github.com/urmzd/orchagent/flow for every option and store, github.com/urmzd/orchagent/durable for durable execution on its own, and github.com/urmzd/orchagent/sandbox for sandboxed tools on their own.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrExists     = definition.ErrExists
	ErrRunFailed  = flow.ErrRunFailed
	ErrRunStopped = flow.ErrRunStopped
)

Errors from App.Define and Reply.Text.

View Source
var (
	WithTenant           = flow.WithTenant
	WithLogger           = flow.WithLogger
	WithPostgres         = flow.WithPostgres
	WithBus              = flow.WithBus
	WithModelProvider    = flow.WithModelProvider
	WithOpenAICompatible = flow.WithOpenAICompatible
	WithTools            = flow.WithTools
	WithConnector        = flow.WithConnector
)

The options most programs need. The rest are in package flow.

Functions

This section is empty.

Types

type App

type App = flow.App

App is the composed stack. See flow.App.

func New

func New(ctx context.Context, opts ...Option) (*App, error)

New composes the stack. Anything not passed as an Option is the complete in-memory implementation.

type Event

type Event = event.Envelope

Event is one event on the bus.

type OpenAICompatible

type OpenAICompatible = native.OpenAICompatible

Model provider types, for WithModelProvider and WithOpenAICompatible.

type Option

type Option = flow.Option

Option is one choice New is given. Every flow.With* option is an Option.

type ParameterSchema

type ParameterSchema = saigetypes.ParameterSchema

Tool definition types, for implementing Tool.

type PropertyDef

type PropertyDef = saigetypes.PropertyDef

Tool definition types, for implementing Tool.

type Provider

type Provider = saigetypes.Provider

Model provider types, for WithModelProvider and WithOpenAICompatible.

type ProviderFunc

type ProviderFunc = native.ProviderFunc

Model provider types, for WithModelProvider and WithOpenAICompatible.

type Reply

type Reply = flow.Reply

Reply is one run started by App.Ask.

type Spec

type Spec = native.Spec

Model provider types, for WithModelProvider and WithOpenAICompatible.

type Tool

type Tool = saigetypes.Tool

Tool is a tool an agent can be granted by name (WithTools).

type ToolDef

type ToolDef = saigetypes.ToolDef

Tool definition types, for implementing Tool.

Directories

Path Synopsis
Package durable makes existing Go code durable without rewrites.
Package durable makes existing Go code durable without rewrites.
adapters/postgres/cmd/durable command
Command durable inspects an durable ledger held in Postgres, to validate it: it lists runs, shows one run with its records, and replays a run's recorded calls through the replay frame a worker builds, executing nothing, to report where a worker would resume the run or that it is complete.
Command durable inspects an durable ledger held in Postgres, to validate it: it lists runs, shows one run with its records, and replays a run's recorded calls through the replay frame a worker builds, executing nothing, to report where a worker would resume the run or that it is complete.
adapters/postgres/internal/pgident
Package pgident validates and quotes SQL identifiers supplied through adapter mappings.
Package pgident validates and quotes SQL identifiers supplied through adapter mappings.
adapters/postgres/internal/pginspect
Package pginspect reads table shape out of the PostgreSQL catalogs so the adapters can validate a Mapping against the database the caller already owns.
Package pginspect reads table shape out of the PostgreSQL catalogs so the adapters can validate a Mapping against the database the caller already owns.
adapters/postgres/pgkit
Package pgkit is the Postgres plumbing the stack shares instead of each component hand-rolling it: Apply runs a component's schema statements once per database under an advisory lock, and Listener carries LISTEN/NOTIFY for a whole process over one dedicated connection.
Package pgkit is the Postgres plumbing the stack shares instead of each component hand-rolling it: Apply runs a component's schema statements once per database under an advisory lock, and Listener carries LISTEN/NOTIFY for a whole process over one dedicated connection.
adapters/postgres/pgledger
Package pgledger implements durable's ledger.Ledger on PostgreSQL tables the application already owns.
Package pgledger implements durable's ledger.Ledger on PostgreSQL tables the application already owns.
adapters/postgres/pgqueue
Package pgqueue implements durable's queue.Queue on a PostgreSQL table the application already owns.
Package pgqueue implements durable's queue.Queue on a PostgreSQL table the application already owns.
adapters/redis/redisqueue
Package redisqueue is durable's Redis queue backend: a sorted-set lease queue implementing queue.Queue, plus the queue.DeltaLog capability on Redis Streams.
Package redisqueue is durable's Redis queue backend: a sorted-set lease queue implementing queue.Queue, plus the queue.DeltaLog capability on Redis Streams.
examples/chaos command
Demo driver: submit one chaos run and wait for it.
Demo driver: submit one chaos run and wait for it.
examples/chaos/internal/chaoswf
Package chaoswf is the workflow shared by the chaos worker binary, the demo driver, and the kill test: four sequential activities, each folding its name into the output and emitting a progress delta.
Package chaoswf is the workflow shared by the chaos worker binary, the demo driver, and the kill test: four sequential activities, each folding its name into the output and emitting a progress delta.
examples/chaos/worker command
The chaos worker: a standalone process that registers the chaos workflow, builds the same Postgres ledger and Redis queue as the driver, and runs until killed.
The chaos worker: a standalone process that registers the chaos workflow, builds the same Postgres ledger and Redis queue as the driver, and runs until killed.
examples/quickstart command
The README hero, runnable: an order-processing workflow on Postgres (ledger) and Redis (queue), with the worker embedded in this very process.
The README hero, runnable: an order-processing workflow on Postgres (ledger) and Redis (queue), with the worker embedded in this very process.
ledger
Package ledger defines the durable-truth interface: where runs and their memoized records live.
Package ledger defines the durable-truth interface: where runs and their memoized records live.
ledger/ledgertest
Package ledgertest is the executable contract for ledger.Ledger: a conformance suite every implementation must pass.
Package ledgertest is the executable contract for ledger.Ledger: a conformance suite every implementation must pass.
queue
Package queue defines the flow-and-clock interface: delivery of run IDs to workers under time-bounded, fenced claims.
Package queue defines the flow-and-clock interface: delivery of run IDs to workers under time-bounded, fenced claims.
queue/queuetest
Package queuetest is the conformance suite every queue backend must pass.
Package queuetest is the conformance suite every queue backend must pass.
replay
Package replay is durable's correctness heart: the memoized re-execution of a run.
Package replay is durable's correctness heart: the memoized re-execution of a run.
run
Package run defines durable's leaf types: runs, records, deltas, and the sentinel errors every layer speaks.
Package run defines durable's leaf types: runs, records, deltas, and the sentinel errors every layer speaks.
worker
Package worker implements durable's consumer: the loop that claims runs from the queue, re-executes them under replay to their frontier, and persists exactly one outcome per claim.
Package worker implements durable's consumer: the loop that claims runs from the queue, re-executes them under replay to their frontier, and persists exactly one outcome per claim.
Package flow is an agent library you compose in Go.
Package flow is an agent library you compose in Go.
address
Package address is the naming layer of the mesh: a stable URI for any place a tag can come from or be delivered to.
Package address is the naming layer of the mesh: a stable URI for any place a tag can come from or be delivered to.
attachment
Package attachment is the typed reference to a file an agent was handed.
Package attachment is the typed reference to a file an agent was handed.
attachment/intake
Package intake is how a file's bytes get into the blob store and come out as an attachment.Attachment.
Package intake is how a file's bytes get into the blob store and come out as an attachment.Attachment.
attachment/resolve
Package resolve turns attachment references into model input.
Package resolve turns attachment references into model input.
attachment/resolve/resolvetest
Package resolvetest provides deterministic stand-ins for the backends pkg/attachment/resolve only defines interfaces for: a Transcriber, a FrameSampler and a Prober.
Package resolvetest provides deterministic stand-ins for the backends pkg/attachment/resolve only defines interfaces for: a Transcriber, a FrameSampler and a Prober.
blob
Package blob is a content-addressed store for the bytes of files an agent is handed: a screenshot pasted into a Slack thread, a log attached to a GitHub issue, a PDF on a Jira ticket.
Package blob is a content-addressed store for the bytes of files an agent is handed: a screenshot pasted into a Slack thread, a log attached to a GitHub issue, a PDF on a Jira ticket.
blob/blobtest
Package blobtest is the conformance suite every blob store must pass.
Package blobtest is the conformance suite every blob store must pass.
bus
Package bus is the broker: every event, from every surface and every run, is published once on a channel, and every subscriber that asked for that channel and type receives it.
Package bus is the broker: every event, from every surface and every run, is published once on a channel, and every subscriber that asked for that channel and type receives it.
bus/bustest
Package bustest is the conformance suite every bus backend must pass.
Package bustest is the conformance suite every bus backend must pass.
cmd/flow command
Command flow validates an agent definition locally: it runs the definition once, in this process, and prints what the run does.
Command flow validates an agent definition locally: it runs the definition once, in this process, and prints what the run does.
connector
Package connector defines what it means to participate in the mesh.
Package connector defines what it means to participate in the mesh.
connectors
Package connectors holds the mesh: the adapters that turn surfaces into typed events and render run events back onto them.
Package connectors holds the mesh: the adapters that turn surfaces into typed events and render run events back onto them.
connectors/author
Package author turns the agent control plane into tools an agent can call.
Package author turns the agent control plane into tools an agent can call.
connectors/cron
Package cron is the schedule peer in the mesh: a trigger, and only a trigger.
Package cron is the schedule peer in the mesh: a trigger, and only a trigger.
connectors/github
Package github is the GitHub peer in the mesh: trigger, sink and actor.
Package github is the GitHub peer in the mesh: trigger, sink and actor.
connectors/internal/files
Package files is the part of file intake every trigger shares: collecting a message's files onto its event under the per-event caps, logging what was left out, and publishing the event without discarding work the provider stopped waiting for.
Package files is the part of file intake every trigger shares: collecting a message's files onto its event under the per-event caps, logging what was left out, and publishing the event without discarding work the provider stopped waiting for.
connectors/internal/httpjson
Package httpjson is the JSON-over-HTTP client the connectors' real API implementations share.
Package httpjson is the JSON-over-HTTP client the connectors' real API implementations share.
connectors/internal/inbound
Package inbound is the front door every webhook trigger shares: authenticate the request, then hand the raw bytes to whoever knows how to read them.
Package inbound is the front door every webhook trigger shares: authenticate the request, then hand the raw bytes to whoever knows how to read them.
connectors/internal/render
Package render accumulates one run's event stream into a document a sink can draw, repeatedly, without ever drawing something stale.
Package render accumulates one run's event stream into a document a sink can draw, repeatedly, without ever drawing something stale.
connectors/internal/rendertest
Package rendertest checks that a connector's events render through the catalog as their request text, and render the same bytes after a JSON round trip, which is what a replay reads back.
Package rendertest checks that a connector's events render through the catalog as their request text, and render the same bytes after a JSON round trip, which is what a replay reads back.
connectors/internal/sink
Package sink is the delivery engine every human-facing connector shares: one message per run, edited as the run proceeds.
Package sink is the delivery engine every human-facing connector shares: one message per run, edited as the run proceeds.
connectors/jira
Package jira is the Jira peer in the mesh: trigger, sink and actor.
Package jira is the Jira peer in the mesh: trigger, sink and actor.
connectors/mention
Package mention finds the agent a human tagged and removes the mention from the text the agent will read.
Package mention finds the agent a human tagged and removes the mention from the text the agent will read.
connectors/slack
Package slack is the Slack peer in the mesh: trigger, sink and actor.
Package slack is the Slack peer in the mesh: trigger, sink and actor.
connectors/webhook
Package webhook is the outbound peer in the mesh: a sink, and only a sink.
Package webhook is the outbound peer in the mesh: a sink, and only a sink.
definition
Package definition is where flow's agents come from: saige definitions (.agent.md files) plus a flow Policy sidecar, kept per tenant in an insert-only Source, and pinned by a run so a replay never runs a newer prompt.
Package definition is where flow's agents come from: saige definitions (.agent.md files) plus a flow Policy sidecar, kept per tenant in an insert-only Source, and pinned by a run so a replay never runs a newer prompt.
definition/definitiontest
Package definitiontest is the conformance suite every definition.Source passes.
Package definitiontest is the conformance suite every definition.Source passes.
deliverystate
Package deliverystate keeps a sink's native message handle and accumulated rendering together across replica changes.
Package deliverystate keeps a sink's native message handle and accumulated rendering together across replica changes.
dispatch
Package dispatch wakes agents.
Package dispatch wakes agents.
egress
Package egress is the delivery half of the mesh: it turns "the agent said something" into "the surface shows it".
Package egress is the delivery half of the mesh: it turns "the agent said something" into "the surface shows it".
event
Package event is the one shape every event takes: an Envelope whose Data is a typed Body, chosen by the envelope's Type.
Package event is the one shape every event takes: an Envelope whose Data is a typed Body, chosen by the envelope's Type.
event/legacy
Package legacy reads data written before the event union: bus rows, journal entries and tags that carry an envelope.Kind or free text.
Package legacy reads data written before the event union: bus rows, journal entries and tags that carry an envelope.Kind or free text.
examples/downstream command
Command downstream is what a team building on flow ships instead of a fork: its own program, composing flow in Go, plus what it registers.
Command downstream is what a team building on flow ships instead of a fork: its own program, composing flow in Go, plus what it registers.
examples/local command
Command local is flow, end to end, in one process.
Command local is flow, end to end, in one process.
isolation
Package isolation is the seam between a run's tools and the isolated instance they execute in (RFC 0004, "The sandbox").
Package isolation is the seam between a run's tools and the isolated instance they execute in (RFC 0004, "The sandbox").
isolation/isolate
Package isolate is the isolation.Leaser over sandbox's pkg/isolate: a Pool of instances started by a sandbox Driver (docker with runsc or runc, or local).
Package isolate is the isolation.Leaser over sandbox's pkg/isolate: a Pool of instances started by a sandbox Driver (docker with runsc or runc, or local).
isolation/isolationtest
Package isolationtest is a Leaser for tests.
Package isolationtest is a Leaser for tests.
knowledge
Package knowledge is the retrieval layer: it indexes documents and answers a query with the passages most likely to contain the answer, each one carrying enough provenance to be cited.
Package knowledge is the retrieval layer: it indexes documents and answers a query with the passages most likely to contain the answer, each one carrying enough provenance to be cited.
knowledge/knowledgetest
Package knowledgetest is the conformance suite every knowledge.Store must pass: exact citations, idempotent and atomic reindexing, tenant and source confinement, deletion, hybrid fusion, reranking, limits, stable order, and refusing input or vectors the store cannot keep.
Package knowledgetest is the conformance suite every knowledge.Store must pass: exact citations, idempotent and atomic reindexing, tenant and source confinement, deletion, hybrid fusion, reranking, limits, stable order, and refusing input or vectors the store cannot keep.
mcptools
Package mcptools connects to the MCP servers pkg/toolprovider records and turns the tools an admin accepted into callables an agent can use.
Package mcptools connects to the MCP servers pkg/toolprovider records and turns the tools an admin accepted into callables an agent can use.
membership
Package membership records which agents are members of which channels, and what each member wakes for.
Package membership records which agents are members of which channels, and what each member wakes for.
membership/membershiptest
Package membershiptest holds every membership.Store to one contract.
Package membershiptest holds every membership.Store to one contract.
runschema
Package runschema owns the Postgres schema that durable's run ledger and queue are stored in, so a run in flight outlives the process that accepted it.
Package runschema owns the Postgres schema that durable's run ledger and queue are stored in, so a run in flight outlives the process that accepted it.
runtime
Package runtime is the durable turn: where an event becomes a run.
Package runtime is the durable turn: where an event becomes a run.
signature
Package signature authenticates inbound webhook requests.
Package signature authenticates inbound webhook requests.
thread
Package thread is the memory of a conversation: an append-only journal of what was said in one thread, kept so that the next run in that thread can be shown it.
Package thread is the memory of a conversation: an append-only journal of what was said in one thread, kept so that the next run in that thread can be shown it.
thread/threadtest
Package threadtest holds two things for tests of the thread journal: Run, the conformance suite every thread.Store must pass, and Surface, a thread.Lister that holds messages in memory and lets a test do to them what people do on a real surface, which is post, edit and delete.
Package threadtest holds two things for tests of the thread journal: Run, the conformance suite every thread.Store must pass, and Surface, a thread.Lister that holds messages in memory and lets a test do to them what people do on a real surface, which is post, edit and delete.
toolprovider
Package toolprovider is the control plane for external tool servers: the record of which MCP servers a tenant may reach, and the versioned list of tools an admin has accepted from each.
Package toolprovider is the control plane for external tool servers: the record of which MCP servers a tenant may reach, and the versioned list of tools an admin has accepted from each.
toolprovider/toolprovidertest
Package toolprovidertest is the conformance suite every toolprovider.Store must pass: versioned provider records with stale edits refused, tenant isolation, validation, a credential scope that reads back as written (and a person-scoped provider that can name no shared credential), nothing accepted until an admin accepts it, and numbered, immutable, pinnable snapshots whose schema hashes the store recomputes.
Package toolprovidertest is the conformance suite every toolprovider.Store must pass: versioned provider records with stale edits refused, tenant isolation, validation, a credential scope that reads back as written (and a person-scoped provider that can name no shared credential), nothing accepted until an admin accepts it, and numbered, immutable, pinnable snapshots whose schema hashes the store recomputes.
turn
Package turn is the seam between a run and whatever executes one turn of it.
Package turn is the seam between a run and whatever executes one turn of it.
turn/native
Package native is the turn.Runtime that runs on saige (Runtime), and the Runner it is built on.
Package native is the turn.Runtime that runs on saige (Runtime), and the Runner it is built on.
turn/native/agenttest
Package agenttest names saige's scripted provider and mock tool for tests and examples, so that saige is imported only under pkg/turn/native.
Package agenttest names saige's scripted provider and mock tool for tests and examples, so that saige is imported only under pkg/turn/native.
turn/native/ragtypes
Package ragtypes names the saige retrieval types and the text extractor the rest of flow uses, so that saige is imported only under pkg/turn/native.
Package ragtypes names the saige retrieval types and the text extractor the rest of flow uses, so that saige is imported only under pkg/turn/native.
turn/native/saigetypes
Package saigetypes names the saige agent types the rest of flow uses, so that saige is imported only under pkg/turn/native.
Package saigetypes names the saige agent types the rest of flow uses, so that saige is imported only under pkg/turn/native.
turn/runtimetest
Package runtimetest is the conformance suite every turn.Runtime passes.
Package runtimetest is the conformance suite every turn.Runtime passes.
turn/sandbox
Package sandbox runs any turn.Runtime inside playscape: each turn is a task in the deployment of its pinned definition, under that definition's policy (Policy.Spawn and Policy.WorkspaceAreas).
Package sandbox runs any turn.Runtime inside playscape: each turn is a task in the deployment of its pinned definition, under that definition's policy (Policy.Spawn and Policy.WorkspaceAreas).
Package sandbox confines what agents can touch.
Package sandbox confines what agents can touch.
cmd/sandbox command
Command sandbox validates a command in a sandbox sandbox, so a person can see what a policy lets it read, what it may change, and what failed.
Command sandbox validates a command in a sandbox sandbox, so a person can see what a policy lets it read, what it may change, and what failed.
controlplane
Package controlplane defines the deployment surface of playscape: deploy a service, size its pool of agent execution nodes, submit tasks to it, and observe the result.
Package controlplane defines the deployment surface of playscape: deploy a service, size its pool of agent execution nodes, submit tasks to it, and observe the result.
examples/basic command
Basic example: compose a control plane from the orthogonal pieces (a local workspace, a sandboxed tool, an in-process node factory, and an in-memory metrics recorder), then deploy a service, size its pool, submit tasks, and print the resulting metrics.
Basic example: compose a control plane from the orthogonal pieces (a local workspace, a sandboxed tool, an in-process node factory, and an in-memory metrics recorder), then deploy a service, size its pool, submit tasks, and print the resulting metrics.
examples/ngac command
NGAC example: define access as a policy graph instead of flat per-tool policies.
NGAC example: define access as a policy graph instead of flat per-tool policies.
examples/saige command
Saige integration example: run saige agents as sandbox workloads.
Saige integration example: run saige agents as sandbox workloads.
internal/procgroup
Package procgroup ends a command together with everything it started.
Package procgroup ends a command together with everything it started.
isolate
Package isolate defines the sandbox an agent run's tools execute in: an Instance, started by a Driver from a Spec, that runs commands behind a process isolation boundary and is destroyed when the run ends.
Package isolate defines the sandbox an agent run's tools execute in: an Instance, started by a Driver from a Spec, that runs commands behind a process isolation boundary and is destroyed when the run ends.
isolate/docker
Package docker is an isolate.Driver that runs each instance as Docker containers, driven through the docker CLI (no SDK dependency).
Package docker is an isolate.Driver that runs each instance as Docker containers, driven through the docker CLI (no SDK dependency).
isolate/egress
Package egress is the egress gate: an HTTP forward proxy that is an instance's only way out.
Package egress is the egress gate: an HTTP forward proxy that is an instance's only way out.
isolate/isolatetest
Package isolatetest is the conformance suite every isolate.Driver runs: the behavior an Instance promises whatever enforces it, and, for drivers that isolate, the boundary itself (read-only root and project, no network, a non-root user with no capabilities, resource limits, syscalls a workload has no use for failing with EPERM, and compartments that share only the socket directory).
Package isolatetest is the conformance suite every isolate.Driver runs: the behavior an Instance promises whatever enforces it, and, for drivers that isolate, the boundary itself (read-only root and project, no network, a non-root user with no capabilities, resource limits, syscalls a workload has no use for failing with EPERM, and compartments that share only the socket directory).
isolate/local
Package local is an isolate.Driver with NO isolation.
Package local is an isolate.Driver with NO isolation.
metrics
Package metrics defines the recording interface every sandbox component emits through.
Package metrics defines the recording interface every sandbox component emits through.
ngac
Package ngac implements a Next Generation Access Control (NGAC) policy machine in the style of NIST SP 800-178: a directed acyclic graph of users, user attributes, objects, object attributes, and policy classes, connected by assignments and granted capabilities through associations, with prohibitions as overriding denials.
Package ngac implements a Next Generation Access Control (NGAC) policy machine in the style of NIST SP 800-178: a directed acyclic graph of users, user attributes, objects, object attributes, and policy classes, connected by assignments and granted capabilities through associations, with prohibitions as overriding denials.
node
Package node defines the agent execution node: the unit that runs tasks by calling tools.
Package node defines the agent execution node: the unit that runs tasks by calling tools.
node/inproc
Package inproc provides an in-process node.Factory: each node executes tools on the calling goroutine, resolving them from a shared registry and confining each call through the deployment's policy decision point.
Package inproc provides an in-process node.Factory: each node executes tools on the calling goroutine, resolving them from a shared registry and confining each call through the deployment's policy decision point.
runner
Package runner defines the run executor: the seam that runs one command to completion somewhere, streams its logs back, and reports its exit code.
Package runner defines the run executor: the seam that runs one command to completion somewhere, streams its logs back, and reports its exit code.
task
Package task defines the unit of work that flows through playscape: submitted by a program or by an agent spawning a sub-task, and run by an agent execution node.
Package task defines the unit of work that flows through playscape: submitted by a program or by an agent spawning a sub-task, and run by an agent execution node.
tool
Package tool defines the unit of capability an agent execution node can invoke.
Package tool defines the unit of capability an agent execution node can invoke.
tool/cli
Package cli is the "cli" tool provider: each tool wraps one CLI binary behind a fixed argv template, an environment allowlist, a timeout, and output caps.
Package cli is the "cli" tool provider: each tool wraps one CLI binary behind a fixed argv template, an environment allowlist, a timeout, and output caps.
workspace
Package workspace defines the shared storage backend that every agent execution node mounts.
Package workspace defines the shared storage backend that every agent execution node mounts.

Jump to

Keyboard shortcuts

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