feat(artifact): add explicit folder transport (#1316)

Artifact publication and import now have durable local authority, but there was no safe way to move those normalized artifacts between independent AgentsView archives. Copying databases would duplicate origin authority, while ad hoc folder copying could expose partial writes, accept unrelated directories, or let corrupt peer content wedge later work.

This adds an explicit, opt-in folder transport through `agentsview sync --target`. Targets are positively marked and confined away from provider and data roots; immutable objects are verified on pull and installed atomically on push; checkpoint conflicts fail closed; deterministic corruption is quarantined; and each invocation performs bounded work. When a writable daemon owns SQLite, the CLI delegates exchange to its authenticated loopback endpoint so a second writer cannot bypass local sync authority.

Ordinary AgentsView behavior is unchanged unless `--target` is supplied. The folder contains sensitive normalized artifacts, not provider-owned JSONL, and this scope deliberately excludes raw-source archival or eviction, continuous watching, hosted/service transports, and mutable user curation. The public artifact-sync guide records those trust and lifecycle boundaries, replacing internal Superpowers planning documents with operator-facing documentation.

Co-authored-by: Wes McKinney <wesm@users.noreply.github.com>

Author: wesm

cmd/agentsview/artifact_sync.go

@@ -0,0 +1,343 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/url"
+	"path/filepath"
+	"strings"
+
+	"go.kenn.io/agentsview/internal/artifact"
+	"go.kenn.io/agentsview/internal/config"
+	"go.kenn.io/agentsview/internal/db"
+	"go.kenn.io/agentsview/internal/parser"
+	"go.kenn.io/agentsview/internal/server"
+	agentsync "go.kenn.io/agentsview/internal/sync"
+)
+
+var runArtifactSyncCLI = artifact.Sync
+
+const daemonArtifactExchangeResponseLimit = 1 << 20
+
+var daemonArtifactExchangeHTTPClient = newDaemonArtifactExchangeHTTPClient()
+
+func newDaemonArtifactExchangeHTTPClient() *http.Client {
+	transport := http.DefaultTransport.(*http.Transport).Clone()
+	transport.Proxy = nil
+	dialer := &net.Dialer{}
+	transport.DialContext = func(
+		ctx context.Context,
+		network string,
+		address string,
+	) (net.Conn, error) {
+		return dialLoopbackDaemon(ctx, dialer, network, address)
+	}
+	return &http.Client{
+		Transport: transport,
+		CheckRedirect: func(
+			*http.Request,
+			[]*http.Request,
+		) error {
+			return http.ErrUseLastResponse
+		},
+	}
+}
+
+func dialLoopbackDaemon(
+	ctx context.Context,
+	dialer *net.Dialer,
+	network string,
+	address string,
+) (net.Conn, error) {
+	host, port, err := net.SplitHostPort(address)
+	if err != nil || !strings.EqualFold(host, "localhost") {
+		return dialer.DialContext(ctx, network, address)
+	}
+	addresses, err := net.DefaultResolver.LookupIPAddr(ctx, host)
+	if err != nil {
+		return nil, err
+	}
+	if len(addresses) == 0 {
+		return nil, errors.New("localhost did not resolve to a loopback address")
+	}
+	for _, candidate := range addresses {
+		if !candidate.IP.IsLoopback() {
+			return nil, errors.New("localhost resolved to a non-loopback address")
+		}
+	}
+	var dialErr error
+	for _, candidate := range addresses {
+		connection, candidateErr := dialer.DialContext(
+			ctx,
+			network,
+			net.JoinHostPort(candidate.String(), port),
+		)
+		if candidateErr == nil {
+			return connection, nil
+		}
+		dialErr = errors.Join(dialErr, candidateErr)
+	}
+	return nil, dialErr
+}
+
+func validateArtifactSyncConfig(cfg SyncConfig) error {
+	if cfg.Target != "" && cfg.Host != "" {
+		return fmt.Errorf("--target cannot be combined with --host")
+	}
+	return nil
+}
+
+func runArtifactFolderSync(
+	ctx context.Context,
+	appCfg config.Config,
+	database *db.DB,
+	cfg SyncConfig,
+) (artifact.SyncResult, error) {
+	result, err := runArtifactSyncCLI(ctx, database, artifact.SyncOptions{
+		DataDir:        appCfg.DataDir,
+		Target:         cfg.Target,
+		ForbiddenRoots: artifactSyncForbiddenRoots(appCfg),
+		Full:           cfg.Full,
+	})
+	if err != nil {
+		return result, &artifactFolderSyncError{cause: err}
+	}
+	return result, nil
+}
+
+func newDaemonArtifactExchangeRunner(
+	appCfg config.Config,
+	database *db.DB,
+	engine *agentsync.Engine,
+	emitter agentsync.Emitter,
+) server.ArtifactExchangeRunner {
+	return func(
+		ctx context.Context,
+		request server.ArtifactExchangeRequest,
+	) (result artifact.SyncResult, err error) {
+		work := func() error {
+			result, err = runArtifactFolderSync(
+				ctx,
+				appCfg,
+				database,
+				SyncConfig{Target: request.Target, Full: request.Full},
+			)
+			return err
+		}
+		if engine == nil {
+			err = work()
+		} else {
+			err = engine.RunExclusiveFlushed(work)
+		}
+		if result.ImportedSessions > 0 && emitter != nil {
+			emitter.Emit("sessions")
+		}
+		return result, err
+	}
+}
+
+func runDaemonArtifactExchange(
+	ctx context.Context,
+	tr transport,
+	authToken string,
+	target string,
+	full bool,
+) (artifact.SyncResult, error) {
+	target, err := filepath.Abs(target)
+	if err != nil {
+		return artifact.SyncResult{}, &daemonArtifactExchangeError{cause: err}
+	}
+	baseURL, err := validatedLoopbackDaemonURL(tr.URL)
+	if err != nil {
+		return artifact.SyncResult{}, &daemonArtifactExchangeError{cause: err}
+	}
+	body, err := json.Marshal(server.ArtifactExchangeRequest{
+		Target: target,
+		Full:   full,
+	})
+	if err != nil {
+		return artifact.SyncResult{}, &daemonArtifactExchangeError{cause: err}
+	}
+	req, err := http.NewRequestWithContext(
+		ctx,
+		http.MethodPost,
+		baseURL+"/api/v1/artifacts/exchange",
+		strings.NewReader(string(body)),
+	)
+	if err != nil {
+		return artifact.SyncResult{}, &daemonArtifactExchangeError{cause: err}
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Origin", baseURL)
+	if authToken != "" {
+		req.Header.Set("Authorization", "Bearer "+authToken)
+	}
+
+	response, err := daemonArtifactExchangeHTTPClient.Do(req)
+	if err != nil {
+		return artifact.SyncResult{}, &daemonArtifactExchangeError{cause: err}
+	}
+	defer response.Body.Close()
+	if response.StatusCode != http.StatusOK {
+		return artifact.SyncResult{}, &daemonArtifactExchangeError{
+			cause: fmt.Errorf("daemon returned HTTP %d", response.StatusCode),
+		}
+	}
+
+	decoder := json.NewDecoder(io.LimitReader(
+		response.Body,
+		daemonArtifactExchangeResponseLimit+1,
+	))
+	decoder.DisallowUnknownFields()
+	var result artifact.SyncResult
+	if err := decoder.Decode(&result); err != nil {
+		return artifact.SyncResult{}, &daemonArtifactExchangeError{cause: err}
+	}
+	if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
+		if err == nil {
+			err = errors.New("daemon returned trailing JSON")
+		}
+		return artifact.SyncResult{}, &daemonArtifactExchangeError{cause: err}
+	}
+	return result, nil
+}
+
+func validatedLoopbackDaemonURL(rawURL string) (string, error) {
+	parsed, err := url.Parse(rawURL)
+	if err != nil {
+		return "", err
+	}
+	if parsed.Scheme != "http" ||
+		parsed.User != nil ||
+		parsed.Host == "" ||
+		(parsed.Path != "" && parsed.Path != "/") ||
+		parsed.RawQuery != "" ||
+		parsed.Fragment != "" {
+		return "", errors.New("unsafe daemon endpoint")
+	}
+	hostname := parsed.Hostname()
+	ip := net.ParseIP(hostname)
+	if !strings.EqualFold(hostname, "localhost") &&
+		(ip == nil || !ip.IsLoopback()) {
+		return "", errors.New("daemon endpoint is not loopback")
+	}
+	return strings.TrimSuffix(parsed.String(), "/"), nil
+}
+
+func runLocalAndArtifactFolderSync(
+	ctx context.Context,
+	appCfg config.Config,
+	database *db.DB,
+	cfg SyncConfig,
+) (artifact.SyncResult, error) {
+	if _, _, err := runLocalSyncResult(
+		ctx,
+		appCfg,
+		database,
+		cfg.Full,
+	); err != nil {
+		return artifact.SyncResult{}, err
+	}
+	return runArtifactFolderSync(ctx, appCfg, database, cfg)
+}
+
+func artifactSyncForbiddenRoots(appCfg config.Config) []string {
+	roots := make([]string, 0, 1+len(appCfg.AgentDirs))
+	seen := make(map[string]struct{}, 1+len(appCfg.AgentDirs))
+	appendRoot := func(root string) {
+		if strings.TrimSpace(root) == "" {
+			return
+		}
+		if isRemoteSourceRoot(root) {
+			return
+		}
+		root = filepath.Clean(root)
+		if _, ok := seen[root]; ok {
+			return
+		}
+		seen[root] = struct{}{}
+		roots = append(roots, root)
+	}
+	appendRoot(appCfg.DataDir)
+	for _, def := range parser.Registry {
+		for _, root := range appCfg.AgentDirs[def.Type] {
+			appendRoot(root)
+		}
+	}
+	return roots
+}
+
+type artifactFolderSyncError struct {
+	cause error
+}
+
+type daemonArtifactExchangeError struct {
+	cause error
+}
+
+func (e *daemonArtifactExchangeError) Error() string {
+	return "daemon artifact exchange failed"
+}
+
+func (e *daemonArtifactExchangeError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.cause
+}
+
+func (e *artifactFolderSyncError) Error() string {
+	return "artifact folder sync failed"
+}
+
+func (e *artifactFolderSyncError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.cause
+}
+
+func printArtifactSyncSummary(w io.Writer, result artifact.SyncResult) {
+	fmt.Fprintf(
+		w,
+		"Artifacts: exported %s; imported %s and %s; received %s; published %s",
+		artifactSyncCount(result.ExportedSessions, "session"),
+		artifactSyncCount(result.ImportedSessions, "session"),
+		artifactSyncCount(result.ImportedMessages, "message"),
+		artifactSyncCount(result.ReceivedArtifacts, "object"),
+		artifactSyncCount(result.PublishedArtifacts, "object"),
+	)
+	if result.RejectedSessions > 0 {
+		fmt.Fprintf(
+			w,
+			"; rejected %s",
+			artifactSyncCount(result.RejectedSessions, "session"),
+		)
+	}
+	if result.Quarantined > 0 {
+		fmt.Fprintf(
+			w,
+			"; quarantined %s",
+			artifactSyncCount(result.Quarantined, "object"),
+		)
+	}
+	fmt.Fprintln(w)
+	if result.More {
+		fmt.Fprintln(
+			w,
+			"Artifact work remains; run the sync command again.",
+		)
+	}
+}
+
+func artifactSyncCount(count int, noun string) string {
+	if count == 1 {
+		return fmt.Sprintf("%d %s", count, noun)
+	}
+	return fmt.Sprintf("%d %ss", count, noun)
+}