@agentspan/agentspan 0.0.3

package/README.md

@@ -0,0 +1,227 @@
+# AgentSpan CLI
+
+Command-line interface for building, running, and managing AI agents powered by the AgentSpan runtime.
+
+## Install
+
+### npm (recommended)
+
+```bash
+npm install -g @agentspan/agentspan
+```
+
+### Homebrew
+
+```bash
+brew tap agentspan/agentspan
+brew install agentspan
+```
+
+### Shell script
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/agentspan/agentspan/main/cli/install.sh | sh
+```
+
+### From source
+
+```bash
+cd cli
+go build -o agentspan .
+```
+
+## Quickstart
+
+```bash
+# Start the runtime server (downloads automatically)
+agentspan server start
+
+# Create an agent config
+agentspan agent init mybot
+
+# Run an agent from a config file
+agentspan agent run --config mybot.yaml "What is the weather in NYC?"
+
+# Run a registered agent by name
+agentspan agent run --name mybot "What is the weather in NYC?"
+```
+
+## Commands
+
+### Server Management
+
+```bash
+# Start the server (downloads latest JAR if needed)
+agentspan server start
+
+# Start a specific version
+agentspan server start --version 0.1.0
+
+# Start on a custom port with a default model
+agentspan server start --port 9090 --model openai/gpt-4o
+
+# Stop the server
+agentspan server stop
+
+# View server logs
+agentspan server logs
+
+# Follow server logs in real-time
+agentspan server logs -f
+```
+
+The server JAR is downloaded from GitHub releases and cached in `~/.agentspan/server/`. On each `server start`, the CLI checks GitHub for updates and re-downloads if a newer version is available.
+
+### Agent Operations
+
+```bash
+# Create a new agent config file
+agentspan agent init mybot
+agentspan agent init mybot --model anthropic/claude-sonnet-4-20250514 --format json
+
+# Run an agent
+agentspan agent run --name mybot "Hello, what can you do?"
+agentspan agent run --config mybot.yaml "Hello, what can you do?"
+agentspan agent run --name mybot --no-stream "Fire and forget"
+
+# List all registered agents
+agentspan agent list
+
+# Get agent definition as JSON
+agentspan agent get mybot
+agentspan agent get mybot --version 2
+
+# Delete an agent
+agentspan agent delete mybot
+agentspan agent delete mybot --version 1
+
+# Check execution status
+agentspan agent status <execution-id>
+
+# Search execution history
+agentspan agent execution
+agentspan agent execution --name mybot
+agentspan agent execution --status COMPLETED --since 1h
+agentspan agent execution --since 7d
+agentspan agent execution --window now-30m
+
+# Stream events from a running agent
+agentspan agent stream <execution-id>
+
+# Respond to human-in-the-loop tasks
+agentspan agent respond <execution-id> --approve
+agentspan agent respond <execution-id> --deny --reason "Amount too high"
+
+# Compile agent config to workflow definition (inspect only)
+agentspan agent compile mybot.yaml
+```
+
+### Time Filters
+
+The `--since` and `--window` flags accept human-readable time specs:
+
+| Format | Meaning |
+|--------|---------|
+| `30s` | 30 seconds |
+| `5m` | 5 minutes |
+| `1h` | 1 hour |
+| `1d` | 1 day |
+| `7d` | 7 days |
+| `1mo` | 1 month (30 days) |
+| `1y` | 1 year (365 days) |
+
+### CLI Self-Update
+
+```bash
+agentspan update
+```
+
+### Configuration
+
+```bash
+# Set server URL and auth credentials
+agentspan configure --url http://myserver:8080
+agentspan configure --auth-key KEY --auth-secret SECRET
+
+# Override server URL for a single command
+agentspan --server http://other:8080 agent list
+```
+
+Configuration is stored in `~/.agentspan/config.json`. Environment variables take precedence:
+
+| Variable | Description |
+|----------|-------------|
+| `AGENT_SERVER_URL` | Server URL (default: `http://localhost:8080`) |
+| `CONDUCTOR_AUTH_KEY` | Auth key |
+| `CONDUCTOR_AUTH_SECRET` | Auth secret |
+
+### Version
+
+```bash
+agentspan version
+```
+
+## Agent Config Format
+
+YAML or JSON. See [examples/](examples/) for samples.
+
+```yaml
+name: my-agent
+description: A helpful assistant
+model: openai/gpt-4o
+instructions: You are a helpful assistant.
+maxTurns: 25
+tools:
+  - name: web_search
+    type: worker
+```
+
+## Distribution
+
+The CLI is distributed through three channels:
+
+1. **npm** (`@agentspan/agentspan`) -- Node.js wrapper downloads the Go binary on install
+2. **Homebrew** (`agentspan/agentspan` tap) -- Pre-built binaries for macOS and Linux
+3. **Shell installer** -- Direct binary download to `/usr/local/bin`
+4. **GitHub Releases** -- Pre-built binaries for all platforms
+
+### Supported Platforms
+
+| OS | Architecture |
+|----|-------------|
+| macOS | x86_64, ARM64 (Apple Silicon) |
+| Linux | x86_64, ARM64 |
+| Windows | x86_64, ARM64 |
+
+## Development
+
+### Building
+
+```bash
+cd cli
+go build -o agentspan .
+```
+
+### Cross-platform build
+
+```bash
+cd cli
+VERSION=0.1.0 ./build.sh
+```
+
+Produces binaries in `cli/dist/` for all 6 platform/arch combinations.
+
+### Release
+
+Push a tag matching `cli-v*` to trigger the release workflow:
+
+```bash
+git tag cli-v0.1.0
+git push origin cli-v0.1.0
+```
+
+This builds all binaries, creates a GitHub release, publishes to npm, and updates the Homebrew tap.
+
+## License
+
+Apache 2.0

package/build.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+set -e
+
+VERSION="${VERSION:-dev}"
+COMMIT="${COMMIT:-$(git rev-parse --short HEAD 2>/dev/null || echo 'none')}"
+DATE="${DATE:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}"
+LDFLAGS="-X github.com/agentspan/agentspan/cli/cmd.Version=${VERSION} -X github.com/agentspan/agentspan/cli/cmd.Commit=${COMMIT} -X github.com/agentspan/agentspan/cli/cmd.Date=${DATE}"
+
+mkdir -p dist
+
+echo "Building agentspan CLI v${VERSION}..."
+
+GOOS=darwin GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/agentspan_darwin_amd64 .
+echo "  Built: darwin/amd64"
+
+GOOS=darwin GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/agentspan_darwin_arm64 .
+echo "  Built: darwin/arm64"
+
+GOOS=linux GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/agentspan_linux_amd64 .
+echo "  Built: linux/amd64"
+
+GOOS=linux GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/agentspan_linux_arm64 .
+echo "  Built: linux/arm64"
+
+GOOS=windows GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/agentspan_windows_amd64.exe .
+echo "  Built: windows/amd64"
+
+GOOS=windows GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/agentspan_windows_arm64.exe .
+echo "  Built: windows/arm64"
+
+chmod +x dist/agentspan_*
+
+echo ""
+echo "Build complete! Binaries in dist/"
+ls -lh dist/

package/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+// Copyright (c) 2025 AgentSpan
+// Licensed under the MIT License. See LICENSE file in the project root for details.
+
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const platform = process.platform;
+const binaryName = platform === 'win32' ? 'agentspan.exe' : 'agentspan';
+const binaryPath = path.join(__dirname, 'bin', binaryName);
+
+// Check if binary exists
+if (!fs.existsSync(binaryPath)) {
+  console.error('Error: Binary not found. Please reinstall the package.');
+  console.error('Run: npm uninstall -g @agentspan/agentspan && npm install -g @agentspan/agentspan');
+  process.exit(1);
+}
+
+// Execute the binary with all arguments
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  shell: false
+});
+
+process.exit(result.status);

package/client/client.go

@@ -0,0 +1,365 @@
+// Copyright (c) 2025 AgentSpan
+// Licensed under the MIT License. See LICENSE file in the project root for details.
+
+package client
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/agentspan/agentspan/cli/config"
+)
+
+type Client struct {
+	baseURL    string
+	httpClient *http.Client
+	authKey    string
+	authSecret string
+}
+
+func New(cfg *config.Config) *Client {
+	return &Client{
+		baseURL:    strings.TrimRight(cfg.ServerURL, "/"),
+		httpClient: &http.Client{Timeout: 30 * time.Second},
+		authKey:    cfg.AuthKey,
+		authSecret: cfg.AuthSecret,
+	}
+}
+
+func (c *Client) doRequest(method, path string, body interface{}) (*http.Response, error) {
+	var bodyReader io.Reader
+	if body != nil {
+		data, err := json.Marshal(body)
+		if err != nil {
+			return nil, fmt.Errorf("marshal request: %w", err)
+		}
+		bodyReader = bytes.NewReader(data)
+	}
+
+	req, err := http.NewRequest(method, c.baseURL+path, bodyReader)
+	if err != nil {
+		return nil, err
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	if c.authKey != "" {
+		req.Header.Set("X-Auth-Key", c.authKey)
+	}
+	if c.authSecret != "" {
+		req.Header.Set("X-Auth-Secret", c.authSecret)
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	if resp.StatusCode >= 400 {
+		defer resp.Body.Close()
+		bodyBytes, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(bodyBytes))
+	}
+	return resp, nil
+}
+
+// HealthCheck pings the server
+func (c *Client) HealthCheck() error {
+	resp, err := c.doRequest("GET", "/api/agent", nil)
+	if err != nil {
+		return err
+	}
+	resp.Body.Close()
+	return nil
+}
+
+// StartRequest is the payload for starting an agent
+type StartRequest struct {
+	AgentConfig map[string]interface{} `json:"agentConfig,omitempty"`
+	Prompt      string                 `json:"prompt"`
+	SessionID   string                 `json:"sessionId,omitempty"`
+}
+
+// StartResponse from the runtime
+type StartResponse struct {
+	WorkflowID   string `json:"workflowId"`
+	WorkflowName string `json:"workflowName"`
+}
+
+// Start compiles, registers, and starts an agent workflow
+func (c *Client) Start(req *StartRequest) (*StartResponse, error) {
+	resp, err := c.doRequest("POST", "/api/agent/start", req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	var result StartResponse
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("decode response: %w", err)
+	}
+	return &result, nil
+}
+
+// Compile compiles an agent config to a workflow definition
+func (c *Client) Compile(agentConfig map[string]interface{}) (map[string]interface{}, error) {
+	body := map[string]interface{}{"agentConfig": agentConfig}
+	resp, err := c.doRequest("POST", "/api/agent/compile", body)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	var result map[string]interface{}
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("decode response: %w", err)
+	}
+	return result, nil
+}
+
+// AgentSummary represents a registered agent
+type AgentSummary struct {
+	Name        string   `json:"name"`
+	Version     int      `json:"version"`
+	Type        string   `json:"type"`
+	Tags        []string `json:"tags"`
+	CreateTime  *int64   `json:"createTime"`
+	UpdateTime  *int64   `json:"updateTime"`
+	Description string   `json:"description"`
+	Checksum    string   `json:"checksum"`
+}
+
+// ListAgents returns all registered agents
+func (c *Client) ListAgents() ([]AgentSummary, error) {
+	resp, err := c.doRequest("GET", "/api/agent/list", nil)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	var result []AgentSummary
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("decode response: %w", err)
+	}
+	return result, nil
+}
+
+// GetAgent returns the workflow definition for a named agent
+func (c *Client) GetAgent(name string, version *int) (map[string]interface{}, error) {
+	path := "/api/agent/get/" + url.PathEscape(name)
+	if version != nil {
+		path += fmt.Sprintf("?version=%d", *version)
+	}
+	resp, err := c.doRequest("GET", path, nil)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	var result map[string]interface{}
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("decode response: %w", err)
+	}
+	return result, nil
+}
+
+// DeleteAgent removes an agent workflow definition
+func (c *Client) DeleteAgent(name string, version *int) error {
+	path := "/api/agent/delete/" + url.PathEscape(name)
+	if version != nil {
+		path += fmt.Sprintf("?version=%d", *version)
+	}
+	resp, err := c.doRequest("DELETE", path, nil)
+	if err != nil {
+		return err
+	}
+	resp.Body.Close()
+	return nil
+}
+
+// ExecutionSearchResult from the search endpoint
+type ExecutionSearchResult struct {
+	TotalHits int64                   `json:"totalHits"`
+	Results   []AgentExecutionSummary `json:"results"`
+}
+
+// AgentExecutionSummary represents one execution in search results
+type AgentExecutionSummary struct {
+	WorkflowID    string `json:"workflowId"`
+	AgentName     string `json:"agentName"`
+	Version       int    `json:"version"`
+	Status        string `json:"status"`
+	StartTime     string `json:"startTime"`
+	EndTime       string `json:"endTime"`
+	UpdateTime    string `json:"updateTime"`
+	ExecutionTime int64  `json:"executionTime"`
+	Input         string `json:"input"`
+	Output        string `json:"output"`
+	CreatedBy     string `json:"createdBy"`
+}
+
+// SearchExecutions searches agent executions with optional filters
+func (c *Client) SearchExecutions(start, size int, agentName, status, freeText string) (*ExecutionSearchResult, error) {
+	params := url.Values{}
+	params.Set("start", fmt.Sprintf("%d", start))
+	params.Set("size", fmt.Sprintf("%d", size))
+	params.Set("sort", "startTime:DESC")
+	if agentName != "" {
+		params.Set("agentName", agentName)
+	}
+	if status != "" {
+		params.Set("status", status)
+	}
+	if freeText != "" {
+		params.Set("freeText", freeText)
+	}
+	resp, err := c.doRequest("GET", "/api/agent/executions?"+params.Encode(), nil)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	var result ExecutionSearchResult
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("decode response: %w", err)
+	}
+	return &result, nil
+}
+
+// ExecutionDetail represents detailed execution status
+type ExecutionDetail struct {
+	WorkflowID  string                 `json:"workflowId"`
+	AgentName   string                 `json:"agentName"`
+	Version     int                    `json:"version"`
+	Status      string                 `json:"status"`
+	Input       map[string]interface{} `json:"input"`
+	Output      map[string]interface{} `json:"output"`
+	CurrentTask *CurrentTask           `json:"currentTask"`
+}
+
+type CurrentTask struct {
+	TaskRefName string                 `json:"taskRefName"`
+	TaskType    string                 `json:"taskType"`
+	Status      string                 `json:"status"`
+	InputData   map[string]interface{} `json:"inputData"`
+	OutputData  map[string]interface{} `json:"outputData"`
+}
+
+// GetExecutionDetail returns detailed status for an execution
+func (c *Client) GetExecutionDetail(executionId string) (*ExecutionDetail, error) {
+	resp, err := c.doRequest("GET", "/api/agent/executions/"+url.PathEscape(executionId), nil)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	var result ExecutionDetail
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("decode response: %w", err)
+	}
+	return &result, nil
+}
+
+// Status gets the workflow execution status (legacy endpoint)
+func (c *Client) Status(workflowID string) (map[string]interface{}, error) {
+	resp, err := c.doRequest("GET", "/api/agent/"+workflowID+"/status", nil)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	var result map[string]interface{}
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return nil, fmt.Errorf("decode response: %w", err)
+	}
+	return result, nil
+}
+
+// Respond sends a HITL response
+func (c *Client) Respond(workflowID string, approved bool, reason, message string) error {
+	body := map[string]interface{}{
+		"approved": approved,
+		"reason":   reason,
+		"message":  message,
+	}
+	resp, err := c.doRequest("POST", "/api/agent/"+workflowID+"/respond", body)
+	if err != nil {
+		return err
+	}
+	resp.Body.Close()
+	return nil
+}
+
+// SSEEvent represents a server-sent event
+type SSEEvent struct {
+	ID    string
+	Event string
+	Data  string
+}
+
+// Stream opens an SSE connection and sends events to the channel
+func (c *Client) Stream(workflowID string, lastEventID string, events chan<- SSEEvent, done chan<- error) {
+	go func() {
+		defer close(events)
+		defer close(done)
+
+		streamClient := &http.Client{Timeout: 0} // no timeout for SSE
+
+		req, err := http.NewRequest("GET", c.baseURL+"/api/agent/stream/"+workflowID, nil)
+		if err != nil {
+			done <- err
+			return
+		}
+		req.Header.Set("Accept", "text/event-stream")
+		if lastEventID != "" {
+			req.Header.Set("Last-Event-ID", lastEventID)
+		}
+		if c.authKey != "" {
+			req.Header.Set("X-Auth-Key", c.authKey)
+		}
+
+		resp, err := streamClient.Do(req)
+		if err != nil {
+			done <- err
+			return
+		}
+		defer resp.Body.Close()
+
+		if resp.StatusCode >= 400 {
+			body, _ := io.ReadAll(resp.Body)
+			done <- fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(body))
+			return
+		}
+
+		scanner := bufio.NewScanner(resp.Body)
+		scanner.Buffer(make([]byte, 0, 1024*1024), 1024*1024)
+
+		var current SSEEvent
+		for scanner.Scan() {
+			line := scanner.Text()
+
+			if line == "" {
+				// Empty line = end of event
+				if current.Data != "" || current.Event != "" {
+					events <- current
+					current = SSEEvent{}
+				}
+				continue
+			}
+
+			if strings.HasPrefix(line, ":") {
+				// Comment (heartbeat), skip
+				continue
+			}
+
+			if strings.HasPrefix(line, "id:") {
+				current.ID = strings.TrimSpace(strings.TrimPrefix(line, "id:"))
+			} else if strings.HasPrefix(line, "event:") {
+				current.Event = strings.TrimSpace(strings.TrimPrefix(line, "event:"))
+			} else if strings.HasPrefix(line, "data:") {
+				current.Data = strings.TrimSpace(strings.TrimPrefix(line, "data:"))
+			}
+		}
+
+		done <- scanner.Err()
+	}()
+}