tai

package module
v0.0.0-...-250343d Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 21 Imported by: 0

README

tai-golang

Tai Console

Go SDK for building the server side of a Tai deployment.

Tai is a computer agent installed on user machines. tai-golang lets a Go application accept Tai node connections and manage nodes, agent sessions, workspaces, realtime voice, Remote Tools, and Wasm plugins.

The SDK is a library embedded in your application. It does not run an agent itself; it owns the server-side transport, identity, session orchestration, and business tool handlers.

Status

Active development. The public API follows the current v2 design and may change without backward-compatibility guarantees while the project is in development.

Working today:

  • Transport server with HTTP discovery, HTTP/2 + HTTP/3 support, and connection pools
  • Node registry, node lifecycle callbacks, remote node operations
  • Sessions: prompt, follow-up, steer, cancel, permissions, queue, runtime updates
  • Session recovery and resume
  • Workspaces: files, branches, commits, history, merge, watch, context, skills
  • Realtime: PCM audio, transcripts, emotion, avatar motion frames
  • Remote Tools with Tool H2, progress events, and Agent integration
  • Wasm plugins distributed by digest and streamed to nodes on demand
  • Auth: node tokens and scoped user tokens
  • Demo App with React frontend and docs browser

Not yet implemented:

  • Realtime video
  • ONNX integration for the balanced render preset

Install

go get github.com/yaoapp/tai-golang

Requires Go 1.26+.

Download Tai

The SDK needs Tai nodes to connect. Download the nightly build:

# macOS (Apple Silicon)
curl -sL https://get.yaoapps.com/tai/nightly/latest.json | jq -r '.assets["darwin-arm64"]' | xargs curl -L -o tai && chmod +x tai

# macOS (Intel)
curl -sL https://get.yaoapps.com/tai/nightly/latest.json | jq -r '.assets["darwin-amd64"]' | xargs curl -L -o tai && chmod +x tai

# Linux (x86_64)
curl -sL https://get.yaoapps.com/tai/nightly/latest.json | jq -r '.assets["linux-amd64"]' | xargs curl -L -o tai && chmod +x tai

# Linux (ARM64)
curl -sL https://get.yaoapps.com/tai/nightly/latest.json | jq -r '.assets["linux-arm64"]' | xargs curl -L -o tai && chmod +x tai

# Windows (PowerShell)
$url = (Invoke-RestMethod https://get.yaoapps.com/tai/nightly/latest.json).assets.'windows-amd64'
Invoke-WebRequest $url -OutFile tai.exe

See latest.json for versions, download URLs, and SHA256 checksums.

Quick Start

package main

import (
    "context"
    "crypto/ed25519"
    "crypto/rand"
    "log"

    tai "github.com/yaoapp/tai-golang"
    "github.com/yaoapp/tai-golang/auth"
    "github.com/yaoapp/tai-golang/node"
    "github.com/yaoapp/tai-golang/types"
)

func main() {
    _, privateKey, err := ed25519.GenerateKey(rand.Reader)
    if err != nil {
        log.Fatal(err)
    }

    server, err := tai.NewServer(&tai.ServerConfig{
        TransportPort: 6099,
        HTTPPort:      5099,
        Auth:          auth.DefaultAuth(privateKey),
    })
    if err != nil {
        log.Fatal(err)
    }

    node.OnRegister(func(rn types.RemoteNode) error {
        log.Printf("node registered: %s", rn.Info().ID)
        return nil
    })

    go func() {
        if err := server.Start(context.Background()); err != nil {
            log.Print(err)
        }
    }()

    if err := server.WaitReady(context.Background()); err != nil {
        log.Fatal(err)
    }
    select {}
}

auth.DefaultAuth is a demo implementation for the complete local flow. Use a custom AuthProvider in production. See Auth.

A node then connects to the SDK:

tai start --node-id node-1 \
  --server http://localhost:5099 \
  --node-token <token> \
  --data ./tai-volumes

Generate the node token with IssueNodeToken or through your own provisioning flow.

Core Concepts

Concept Description
Server Embedded transport, node registry, tool/plugin registries
RemoteNode A connected node with workspace/session operations
Session One agent conversation, commands, events, optional realtime
Workspace Remote filesystem, branches, history, watchers
AuthProvider Node credential and scoped user credential verification
RemoteTool Server-side tool exposed to node Agents
PluginEntry Wasm step for a Remote Tool pipeline

Read Architecture for the deployment model and API Reference for a quick method lookup.

Sessions

import (
    "encoding/json"

    "github.com/yaoapp/tai-golang/node"
    "github.com/yaoapp/tai-golang/types"
)

llm, _ := json.Marshal(map[string]any{
    "primary": map[string]any{
        "provider_id": "deepseek",
        "model":       "deepseek-chat",
    },
})

rn := node.Get("node-1")
sess, err := rn.OpenSession(ctx, &types.SessionOpenRequest{
    SessionID: "sess-001",
    Scopes:    types.Scope{types.SessionAccess, types.WorkspaceRead},
    Request: &types.SessionRequest{
        Runtime: "tai",
        Cwd:     "/workspace/project",
        LLM:     llm,
        Env:     map[string]string{"DEEPSEEK_API_KEY": apiKey},
    },
})
if err != nil {
    log.Fatal(err)
}
defer sess.Close(context.Background())

if err := sess.Prompt(&types.UserMessage{Message: "Hello"}); err != nil {
    log.Fatal(err)
}

for {
    msg, err := sess.RecvEvent()
    if err != nil {
        break
    }
    log.Printf("[%s] %s", msg.Kind, msg.Data)
}

OpenSession issues the user credential from the declared scopes; there is no operation token to pass. Use ResumeSession after a transport interruption.

See Session for steering, queue management, permissions, updates, and event handling. See LLM Providers for model and endpoint configuration.

Workspaces

rn := node.Get("node-1")

ws, err := rn.OpenWorkspace(ctx, "workspace-id")
if err != nil {
    log.Fatal(err)
}

branch, err := ws.GetBranch(ctx, "main")
if err != nil {
    log.Fatal(err)
}

data, err := fs.ReadFile(branch.FS(), "README.md")
if err != nil {
    log.Fatal(err)
}

w, err := branch.FS().Create("hello.txt")
if err != nil {
    log.Fatal(err)
}
_, _ = w.Write([]byte("Hello, World!"))
_ = w.Close()

if err := branch.Commit(ctx, "add hello.txt"); err != nil {
    log.Fatal(err)
}

Use Rename, Remove, MkdirAll, WriteArchive, ReadManifest, Exists, history queries, merges, and watchers as needed. See Workspace API.

Remote Tools

Remote Tools expose application capabilities to node Agents:

import (
    "context"
    "encoding/json"

    "github.com/yaoapp/tai-golang/pb"
    "github.com/yaoapp/tai-golang/remotetool"
)

err := server.RegisterRemoteTool(&remotetool.Tool{
    Entry: &pb.RemoteToolEntry{
        Name:        "ping",
        Group:       "dev",
        Description: "Return a message and the caller identity.",
        InputSchema: []byte(`{"type":"object","properties":{"message":{"type":"string"}}}`),
    },
    Handler: func(ctx context.Context, input []byte) ([]byte, error) {
        var req struct{ Message string `json:"message"` }
        _ = json.Unmarshal(input, &req)
        user := remotetool.User(ctx)
        return json.Marshal(map[string]any{
            "message": req.Message,
            "user_id": user.UserID,
            "team_id": user.TeamID,
        })
    },
})
if err != nil {
    log.Fatal(err)
}

The node exposes the tool to the Agent. Calls return to the SDK handler with a verified user identity. Tool metadata and plugin metadata are synced to the node; tool calls and plugin artifacts use the SDK transport port.

See Remote Tools for pipelines, progress handlers, CLI, and error codes.

Plugins

A Remote Tool pipeline can include Wasm plugin steps:

err := server.RegisterPlugin(&pb.PluginEntry{
    Name:         "demo.normalize",
    Version:      "1.0.0",
    Runtime:      "wasm",
    ArtifactPath: "dist/wasm/normalize.wasm",
})

RegisterPlugin reads the file once to compute digest and size, then stores the path. The node downloads the artifact on demand; the SDK opens and streams it from disk at that point.

See Remote Tool Plugins for the plugin ABI, capabilities, build commands, and pipeline examples.

Realtime

Realtime upgrades an open session into a voice conversation:

err := sess.StartRealtime(&types.RealtimeRequest{
    Providers: types.Providers{
        Primary: types.Provider{
            ProviderID: "openai",
            Model:      "gpt-realtime-mini",
            BaseURL:    "wss://api.openai.com/v1/realtime",
            APIKey:     os.Getenv("OPENAI_API_KEY"),
        },
    },
    Audio: &types.AudioConfig{
        InputFormat:  "pcm16",
        OutputFormat: "pcm16",
        SampleRate:   24000,
        Channels:     1,
        Voice:        "alloy",
    },
})
if err != nil {
    log.Fatal(err)
}

// Microphone → node.
go func() {
    for buf := range micFrames {
        if err := sess.AudioAppend(buf); err != nil {
            return
        }
    }
}()

// Node → speakers.
go func() {
    for frame := range sess.RecvAudio() {
        speaker.Play(frame.Data)
    }
}()

// Transcript and emotion.
go func() {
    for ev := range sess.RecvRender() {
        switch ev.Type {
        case "transcript.delta":
            subtitle.Append(ev.Content)
        case "transcript.done":
            subtitle.Set(ev.Transcript)
        case "emotion":
            mood.Set(ev.State, ev.Emotion, ev.Intensity)
        }
    }
}()

_ = sess.StopRealtime()

Do not read RecvAction concurrently with StartRealtime; start one control relay after it returns. See Session Realtime and Render Protocol.

Avatar Motion

Enable motion on the realtime request:

err := sess.StartRealtime(&types.RealtimeRequest{
    Providers: providers,
    Audio:     &types.AudioConfig{OutputFormat: "pcm16", SampleRate: 24000},
    Motion: &types.MotionConfig{
        Enabled: true,
        Profile: "arkit_52",
        FPS:     30,
    },
})

go func() {
    for frame := range sess.RecvMotion() {
        avatar.ApplyBlendshapes(frame.Face, frame.Head, frame.Gaze)
    }
}()

Motion is optional and non-fatal; realtime continues if the motion channel is unavailable.

Documentation

Demo App

The repository includes a demo application that embeds the SDK and serves a React UI plus a documentation browser.

cd app
make build

# Text sessions and docs browser
DEEPSEEK_API_KEY=<key> ./tai-demo --port 3000

# Enable realtime voice too
DEEPSEEK_API_KEY=<key> OPENAI_API_KEY=<key> ./tai-demo --port 3000

Open http://localhost:3000. See Demo App Guide.

Project Layout

server.go       Server interface, NewServer, ServerConfig
node/           Node registry, RemoteNode operations
session/        Session implementation
workspace/      Remote workspace, branches, history, watchers
remotetool/     Remote Tool registry and handlers
plugin/         Wasm plugin registry and artifact paths
auth/           AuthProvider interface + demo DefaultAuth
transport/      HTTP discovery, HTTP/2/HTTP/3 transport, frame codec
types/          Public SDK types
mock/           Test doubles
proto/          Protobuf source
pb/             Generated Go code
app/            Demo application
docs/           SDK documentation

Development

go test ./...
go vet ./...
./scripts/coverage-gate.sh coverage.out

The demo app requires Node.js 22+ for the frontend build.

License

MIT

Documentation

Overview

Package tai provides the server-side SDK for communicating with Tai nodes over the Tai Transport Protocol v2.

Tai is a closed-source binary installed on every computer. This SDK implements the server side of the transport layer, enabling any server (e.g. Yao) to accept Tai connections, manage nodes, and run sessions.

Quick start:

server, err := tai.NewServer(&tai.ServerConfig{
    TransportPort: 6099,
    HTTPPort:      5099,
    Auth:          auth.DefaultAuth(privateKey),
})
server.Start(ctx)

Index

Constants

View Source
const (
	NamespaceControl = types.NamespaceControl
	NamespaceSession = types.NamespaceSession
)

Re-export constants.

View Source
const DefaultShutdownTimeout = 5 * time.Second

DefaultShutdownTimeout is how long Close waits for in-flight requests.

Variables

View Source
var (
	ErrNodeNotFound = types.ErrNodeNotFound
)

Re-export errors.

View Source
var ErrNotImplemented = errors.New("tai: not implemented")

ErrNotImplemented is returned by Server methods not yet available.

Functions

This section is empty.

Types

type AudioConfig

type AudioConfig = types.AudioConfig

Re-export types from sub-packages for backward compatibility.

type AuthProvider

type AuthProvider = types.AuthProvider

Re-export types from sub-packages for backward compatibility.

type ControlMsg

type ControlMsg = types.ControlMsg

Re-export types from sub-packages for backward compatibility.

type MotionConfig

type MotionConfig = types.MotionConfig

Re-export types from sub-packages for backward compatibility.

type Node

type Node = types.Node

Re-export types from sub-packages for backward compatibility.

type NodeInfo

type NodeInfo = types.NodeInfo

Re-export types from sub-packages for backward compatibility.

type NodeRuntime

type NodeRuntime = types.NodeRuntime

Re-export types from sub-packages for backward compatibility.

type OpenSessionRequest

type OpenSessionRequest = types.OpenSessionRequest

Re-export types from sub-packages for backward compatibility.

type PoolSettings

type PoolSettings struct {
	LightMin            uint32
	LightMax            uint32
	LightMaxStreams     uint32
	LightIdleTimeoutSec uint32
	HeavyMin            uint32
	HeavyMax            uint32
	HeavyMaxIdle        uint32
	HeavyIdleTimeoutSec uint32
	HeavyHealthCheckSec uint32
}

PoolSettings configures the Light and Heavy pools.

type Provider

type Provider = types.Provider

Re-export types from sub-packages for backward compatibility.

type Providers

type Providers = types.Providers

Re-export types from sub-packages for backward compatibility.

type RealtimeRequest

type RealtimeRequest = types.RealtimeRequest

Re-export types from sub-packages for backward compatibility.

type RealtimeUpdateOptions

type RealtimeUpdateOptions = types.RealtimeUpdateOptions

Re-export types from sub-packages for backward compatibility.

type RemoteNode

type RemoteNode = types.RemoteNode

Re-export types from sub-packages for backward compatibility.

type Server

type Server interface {
	Start(ctx context.Context) error
	Addr() string
	RegisterTool(tool *ToolDefinition) error
	UnregisterTool(name string) error
	Close() error
	WaitReady(ctx context.Context) error

	// Remote Tool / Plugin registration (design §14 / wasm Part I §4).
	SetRemoteTools(tools []*remotetool.Tool) error
	RegisterRemoteTool(tool *remotetool.Tool) error
	UnregisterRemoteTool(name string) error
	RegisterPlugin(entry *pb.PluginEntry) error
	UnregisterPlugin(name, version string) error
	SetRemotePlugins(entries []*pb.PluginEntry) error
	RemoteToolRegistry() *remotetool.Registry
	PluginRegistry() *plugin.Registry
}

Server is a Tai transport server that accepts and manages Tai node connections.

func NewServer

func NewServer(cfg *ServerConfig) (Server, error)

NewServer creates a transport server from cfg.

type ServerConfig

type ServerConfig struct {
	TransportPort   int
	HTTPPort        int
	TLS             *TLSConfig
	Auth            AuthProvider
	MaxFrameSize    int
	UnauthTimeout   time.Duration
	QUIC            *quic.Config
	ShutdownTimeout time.Duration
	Pool            *PoolSettings
}

ServerConfig holds configuration for a Tai transport server.

type Session

type Session = types.Session

Re-export types from sub-packages for backward compatibility.

type SessionMsg

type SessionMsg = types.SessionMsg

Re-export types from sub-packages for backward compatibility.

type SessionRequest

type SessionRequest = types.SessionRequest

Re-export types from sub-packages for backward compatibility.

type TLSConfig

type TLSConfig struct {
	CertFile string
	KeyFile  string
}

TLSConfig holds TLS certificate paths.

type TLSInfo

type TLSInfo = types.TLSInfo

Re-export types from sub-packages for backward compatibility.

type ToolDefinition

type ToolDefinition = types.ToolDefinition

Re-export types from sub-packages for backward compatibility.

type ToolHandler

type ToolHandler = types.ToolHandler

Re-export types from sub-packages for backward compatibility.

type UserMessage

type UserMessage = types.UserMessage

Re-export types from sub-packages for backward compatibility.

type VADConfig

type VADConfig = types.VADConfig

Re-export types from sub-packages for backward compatibility.

type WellKnownResponse

type WellKnownResponse = types.WellKnownResponse

Re-export types from sub-packages for backward compatibility.

Directories

Path Synopsis
Package auth provides the default JWT-based AuthProvider implementation.
Package auth provides the default JWT-based AuthProvider implementation.
Package mock provides test doubles for the Tai SDK.
Package mock provides test doubles for the Tai SDK.
Package node manages connected Tai nodes and provides the RemoteNode behavioral wrapper.
Package node manages connected Tai nodes and provides the RemoteNode behavioral wrapper.
Package plugin maintains the SDK-side Plugin registry and artifact store.
Package plugin maintains the SDK-side Plugin registry and artifact store.
Package remotetool implements the SDK-side Remote Tool registry and Handler.
Package remotetool implements the SDK-side Remote Tool registry and Handler.
Package session — recovery_buffer.go provides a per-Session ring buffer that stores received events by seq number.
Package session — recovery_buffer.go provides a per-Session ring buffer that stores received events by seq number.
Package toolserver serves the Remote Tool H2 endpoints.
Package toolserver serves the Remote Tool H2 endpoints.
Package transport implements the Tai Transport Protocol v2 server: TCP (HTTP/2), QUIC (HTTP/3, WebTransport), and the Tai frame protocol.
Package transport implements the Tai Transport Protocol v2 server: TCP (HTTP/2), QUIC (HTTP/3, WebTransport), and the Tai frame protocol.
Package types defines shared data types for the Tai SDK.
Package types defines shared data types for the Tai SDK.
Package workspace provides remote workspace access via the Tai transport layer.
Package workspace provides remote workspace access via the Tai transport layer.

Jump to

Keyboard shortcuts

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