Skip to content

About

Apache-2.0 Go SDK for building applications around the Obey daemon

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

29 Commits

Folders and files

Repository files navigation

Obey Go SDK

Build Go applications around the Obey daemon.

Go 1.24+ Go Reference License: Apache 2.0 Built with Festival

Installation · Quick start · Examples · API reference

Submit prompts, stream activity, and manage durable sessions from your Go application. The SDK uses the installed Obey CLI as its transport and has standard-library-only runtime dependencies.

The SDK is open source under Apache-2.0. The Obey daemon is proprietary and runs separately. See platform support for the verified runtime scope.

Installation

Requires Go 1.24+, a compatible Obey CLI on PATH, and a running Obey daemon with your camp, provider, and model configured.

go get github.com/Obedience-Corp/obey-go-sdk@v0.2.0

Import the public package:

import "github.com/Obedience-Corp/obey-go-sdk/pkg/obey"

The version is recorded in your application's go.mod. See compatibility for capability discovery and supported machine protocols.

Install Obey through the Festival installer. Stable Obey 0.5.0 supports one-shot prompts through protocol v1. Persistent SDK APIs require a daemon and CLI that advertise the corresponding machine protocols; unsupported operations return a typed error before creating a session.

Use Providers, Models, RefreshModels and Preflight with Obey 0.5.0+ to populate route selectors and check the selected route. Catalogs retain freshness, unknown capabilities and raw IDs. Older CLIs return a typed unsupported_protocol error; preserve manual route entry. When offering Obey alongside other backends, construct its client only after Obey is selected. See optional provider integration for routing, readiness, permissions and streaming limits.

Quick start

Replace the camp, provider, and model below with values configured in your daemon.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/Obedience-Corp/obey-go-sdk/pkg/obey"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	client, err := obey.NewClientFromPath(obey.WithCamp("my-camp"))
	if err != nil {
		return err
	}
	defer client.Close()

	result, err := client.RunPrompt(ctx, "Summarize the current project", &obey.RunOptions{
		SessionOptions: obey.SessionOptions{
			Provider: "your-provider",
			Model:    "your-model",
		},
	})
	if err != nil {
		return err
	}

	fmt.Println(result.Text)
	return nil
}

Daemon requests accept a context.Context, so HTTP request contexts and application cancellation can flow through to the CLI operation.

API overview

On stable Obey 0.5.0, use RunPrompt or StreamPrompt with final-result fidelity. The persistent workflows below require additional advertised machine protocols; current stable Obey returns a typed unsupported_protocol error before mutation.

Workflow API
Discover daemon routes Client.Providers, Client.Models, Client.RefreshModels
Check selected route requirements Client.Preflight
Run a prompt Client.RunPrompt, Client.StreamPrompt
Create or reopen a session Client.CreateSession, Client.OpenSession
Submit durable work Session.Send
Inspect or recover a turn Client.OpenTurn, Turn.State, Turn.Wait
Read history and activity Session.Transcript, Session.Attach, Client.Observe
Handle approvals Session.PendingApprovals, Session.RespondApproval
Control work explicitly Turn.Cancel, Session.Stop

One-shot runs own their new session and attempt cleanup when they finish. Persistent sessions have a different lifetime: closing the client detaches, and your application decides when to cancel a turn or stop a session.

For durable submissions, persist your application's idempotency key before calling Session.Send. Retain returned references, including partial references on errors, for recovery. Send acknowledges acceptance; Turn.Wait retrieves the original turn's result. Applications control mutation retries and approval decisions explicitly.

See lifecycle and recovery for ownership, cancellation, acceptance uncertainty, observation cursors, and retained-result behavior.

Examples

Example Demonstrates
Basic prompt A one-shot prompt with explicit provider and model
Streaming Incremental events and final results
Observation Scoped activity streams and caller-controlled reconnect
Approvals Inspecting pending calls and submitting explicit decisions
HTTP service Using request contexts in a Go HTTP handler

The persistent HTTP integration fixture demonstrates application-owned key/ref journaling, process restart, and explicit session controls. Its integration evidence records the tested scenarios.

Platform support

Platform Status
Linux amd64 and arm64 Festival-installed CLI/daemon integration verified
macOS arm64 Isolated native SDK process lifecycle verified; see evidence
Windows Unsupported

The operator manages daemon startup, authentication, and provider configuration. See release notes for the current verification limits.

Development

just build
just lint
just test unit

Subprocess tests run in disposable Docker containers:

just test process

Keep filesystem, socket, database, and child-process fixtures in the isolated test lanes. See integration evidence for real-daemon consumer checks.

Run the public-release integration with Docker and network access:

just test installed

This installs Obey through released Festival, exercises the SDK against the actual daemon with a deterministic loopback provider, and verifies persisted session state. It needs no private Obey checkout or provider credentials. CI runs it on pull requests, pushes to main, and nightly to catch release compatibility regressions.

For SDK maintainers, release instructions describe source checks, immutable tags, automated publication and clean external import verification.

License

Apache License 2.0. The license covers this SDK; the Obey daemon is distributed separately under its own terms.

About

Apache-2.0 Go SDK for building applications around the Obey daemon

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages