diff --git a/apps/backend/internal/agent/agents/agent.go b/apps/backend/internal/agent/agents/agent.go index 1a2690e6be..b4055717c4 100644 --- a/apps/backend/internal/agent/agents/agent.go +++ b/apps/backend/internal/agent/agents/agent.go @@ -463,9 +463,12 @@ type RemoteAuth struct { // RemoteAuthFileConflictPolicy defines how a credential transfer handles an existing target. type RemoteAuthFileConflictPolicy string +// RemoteAuthFileConflictPolicyMergeJSONObject preserves target-only keys and replaces collisions with source values. +const RemoteAuthFileConflictPolicyMergeJSONObject RemoteAuthFileConflictPolicy = "merge_json_object" + const ( - // RemoteAuthFileConflictPolicyMergeJSONObject preserves target-only keys and replaces collisions with source values. - RemoteAuthFileConflictPolicyMergeJSONObject RemoteAuthFileConflictPolicy = "merge_json_object" + remoteAuthMethodTypeFiles = "files" + remoteAuthLabelCopyFiles = "Copy auth files" ) // RemoteAuthMethod describes one way an agent can authenticate in a remote environment. diff --git a/apps/backend/internal/agent/agents/antigravity_acp.go b/apps/backend/internal/agent/agents/antigravity_acp.go index 9103dbdace..e9527b240b 100644 --- a/apps/backend/internal/agent/agents/antigravity_acp.go +++ b/apps/backend/internal/agent/agents/antigravity_acp.go @@ -178,7 +178,7 @@ func (a *AntigravityACP) RemoteAuth() *RemoteAuth { return &RemoteAuth{ Methods: []RemoteAuthMethod{ { - Type: "files", + Type: remoteAuthMethodTypeFiles, SourceFiles: map[string][]string{ "darwin": files, "linux": files, diff --git a/apps/backend/internal/agent/agents/auggie.go b/apps/backend/internal/agent/agents/auggie.go index a6495e9d38..1ccf0c755c 100644 --- a/apps/backend/internal/agent/agents/auggie.go +++ b/apps/backend/internal/agent/agents/auggie.go @@ -115,7 +115,7 @@ func (a *Auggie) RemoteAuth() *RemoteAuth { return &RemoteAuth{ Methods: []RemoteAuthMethod{ { - Type: "files", + Type: remoteAuthMethodTypeFiles, Label: "Copy session files", SourceFiles: map[string][]string{ "darwin": {".augment/session.json"}, diff --git a/apps/backend/internal/agent/agents/codex_acp.go b/apps/backend/internal/agent/agents/codex_acp.go index d1420d6a22..2c04d58d83 100644 --- a/apps/backend/internal/agent/agents/codex_acp.go +++ b/apps/backend/internal/agent/agents/codex_acp.go @@ -137,8 +137,8 @@ func (a *CodexACP) RemoteAuth() *RemoteAuth { return &RemoteAuth{ Methods: []RemoteAuthMethod{ { - Type: "files", - Label: "Copy auth files", + Type: remoteAuthMethodTypeFiles, + Label: remoteAuthLabelCopyFiles, SourceFiles: map[string][]string{ "darwin": {".codex/auth.json"}, "linux": {".codex/auth.json"}, diff --git a/apps/backend/internal/agent/agents/devin_acp.go b/apps/backend/internal/agent/agents/devin_acp.go index 36bca73e5c..0b57abbae7 100644 --- a/apps/backend/internal/agent/agents/devin_acp.go +++ b/apps/backend/internal/agent/agents/devin_acp.go @@ -122,7 +122,7 @@ func (a *DevinACP) RemoteAuth() *RemoteAuth { return &RemoteAuth{ Methods: []RemoteAuthMethod{ { - Type: "files", + Type: remoteAuthMethodTypeFiles, Label: "Copy Devin CLI credentials", SourceFiles: map[string][]string{ "darwin": {devinCredentialsRelPath}, diff --git a/apps/backend/internal/agent/agents/gemini.go b/apps/backend/internal/agent/agents/gemini.go index 99e8229218..f46a29f4a9 100644 --- a/apps/backend/internal/agent/agents/gemini.go +++ b/apps/backend/internal/agent/agents/gemini.go @@ -105,8 +105,8 @@ func (a *Gemini) RemoteAuth() *RemoteAuth { return &RemoteAuth{ Methods: []RemoteAuthMethod{ { - Type: "files", - Label: "Copy auth files", + Type: remoteAuthMethodTypeFiles, + Label: remoteAuthLabelCopyFiles, SourceFiles: map[string][]string{ "darwin": {".gemini/oauth_creds.json", ".gemini/settings.json", ".gemini/google_accounts.json"}, "linux": {".gemini/oauth_creds.json", ".gemini/settings.json", ".gemini/google_accounts.json"}, diff --git a/apps/backend/internal/agent/agents/goose_acp.go b/apps/backend/internal/agent/agents/goose_acp.go index 70dcb37dc7..92382e55c2 100644 --- a/apps/backend/internal/agent/agents/goose_acp.go +++ b/apps/backend/internal/agent/agents/goose_acp.go @@ -141,7 +141,7 @@ func (a *GooseACP) RemoteAuth() *RemoteAuth { return &RemoteAuth{ Methods: []RemoteAuthMethod{ { - Type: "files", + Type: remoteAuthMethodTypeFiles, Label: "Copy Goose config files", SourceFiles: map[string][]string{ "darwin": {".config/goose/config.yaml", ".config/goose/extensions.yaml", ".config/goose/secrets.yaml"}, diff --git a/apps/backend/internal/agent/agents/grok_acp.go b/apps/backend/internal/agent/agents/grok_acp.go index f22b877a75..ccccbfa2bf 100644 --- a/apps/backend/internal/agent/agents/grok_acp.go +++ b/apps/backend/internal/agent/agents/grok_acp.go @@ -95,8 +95,8 @@ func (a *GrokACP) RemoteAuth() *RemoteAuth { return &RemoteAuth{ Methods: []RemoteAuthMethod{ { - Type: "files", - Label: "Copy auth files", + Type: remoteAuthMethodTypeFiles, + Label: remoteAuthLabelCopyFiles, SourceFiles: map[string][]string{ "darwin": {".grok/auth.json"}, "linux": {".grok/auth.json"}, diff --git a/apps/backend/internal/agent/agents/hermes_acp.go b/apps/backend/internal/agent/agents/hermes_acp.go index 3117905cff..589d405b3a 100644 --- a/apps/backend/internal/agent/agents/hermes_acp.go +++ b/apps/backend/internal/agent/agents/hermes_acp.go @@ -114,8 +114,8 @@ func (a *HermesACP) RemoteAuth() *RemoteAuth { return &RemoteAuth{ Methods: []RemoteAuthMethod{ { - Type: "files", - Label: "Copy auth files", + Type: remoteAuthMethodTypeFiles, + Label: remoteAuthLabelCopyFiles, SourceFiles: map[string][]string{ "darwin": {".hermes/.env", ".hermes/config.yaml"}, "linux": {".hermes/.env", ".hermes/config.yaml"}, diff --git a/apps/backend/internal/agent/agents/mock.go b/apps/backend/internal/agent/agents/mock.go index 95148ea997..18e910d34c 100644 --- a/apps/backend/internal/agent/agents/mock.go +++ b/apps/backend/internal/agent/agents/mock.go @@ -189,8 +189,8 @@ func (a *MockAgent) RemoteAuth() *RemoteAuth { } return &RemoteAuth{Methods: []RemoteAuthMethod{ { - Type: "files", - Label: "Copy auth files", + Type: remoteAuthMethodTypeFiles, + Label: remoteAuthLabelCopyFiles, SourceFiles: map[string][]string{ "darwin": {".codex/auth.json"}, "linux": {".codex/auth.json"}, diff --git a/apps/backend/internal/agent/agents/opencode_acp.go b/apps/backend/internal/agent/agents/opencode_acp.go index 1962d7fb8c..8c7904d829 100644 --- a/apps/backend/internal/agent/agents/opencode_acp.go +++ b/apps/backend/internal/agent/agents/opencode_acp.go @@ -127,8 +127,8 @@ func (a *OpenCodeACP) RemoteAuth() *RemoteAuth { return &RemoteAuth{ Methods: []RemoteAuthMethod{ { - Type: "files", - Label: "Copy auth files", + Type: remoteAuthMethodTypeFiles, + Label: remoteAuthLabelCopyFiles, FileConflictPolicy: RemoteAuthFileConflictPolicyMergeJSONObject, SourceFiles: map[string][]string{ "darwin": {".local/share/opencode/auth.json"}, diff --git a/apps/backend/internal/agent/runtime/lifecycle/credential_uploader.go b/apps/backend/internal/agent/runtime/lifecycle/credential_uploader.go index c27795d785..c05bbb6c2c 100644 --- a/apps/backend/internal/agent/runtime/lifecycle/credential_uploader.go +++ b/apps/backend/internal/agent/runtime/lifecycle/credential_uploader.go @@ -27,7 +27,10 @@ type fileReader interface { ReadFile(ctx context.Context, path string) ([]byte, error) } -const credentialFileMode os.FileMode = 0o600 +const ( + credentialFileMode os.FileMode = 0o600 + fileReadOperation = "read" +) // UploadCredentialFiles reads local credential files and uploads them to the remote environment. func UploadCredentialFiles( diff --git a/apps/backend/internal/agent/runtime/lifecycle/executor_sprites.go b/apps/backend/internal/agent/runtime/lifecycle/executor_sprites.go index 55f2e371a0..7d9468b6be 100644 --- a/apps/backend/internal/agent/runtime/lifecycle/executor_sprites.go +++ b/apps/backend/internal/agent/runtime/lifecycle/executor_sprites.go @@ -50,7 +50,7 @@ func (u *spriteFileUploader) ReadFile(ctx context.Context, path string) ([]byte, return data, err } if isSpritesNotFound(err) { - return nil, &fs.PathError{Op: "read", Path: path, Err: fs.ErrNotExist} + return nil, &fs.PathError{Op: fileReadOperation, Path: path, Err: fs.ErrNotExist} } return data, err } diff --git a/apps/backend/internal/agent/runtime/lifecycle/executor_ssh_credentials.go b/apps/backend/internal/agent/runtime/lifecycle/executor_ssh_credentials.go index cb23b52d53..a07dc94019 100644 --- a/apps/backend/internal/agent/runtime/lifecycle/executor_ssh_credentials.go +++ b/apps/backend/internal/agent/runtime/lifecycle/executor_ssh_credentials.go @@ -290,7 +290,7 @@ func (u *sshFileUploader) ReadFile(ctx context.Context, path string) ([]byte, er data, err := readSFTPFileContext(ctx, c, path) if err != nil { if isSFTPNotExist(err) { - return nil, &fs.PathError{Op: "read", Path: path, Err: fs.ErrNotExist} + return nil, &fs.PathError{Op: fileReadOperation, Path: path, Err: fs.ErrNotExist} } return nil, fmt.Errorf("sftp: read %s: %w", path, err) } diff --git a/apps/backend/internal/agentctl/server/acp/connection.go b/apps/backend/internal/agentctl/server/acp/connection.go new file mode 100644 index 0000000000..dc687f2d2a --- /dev/null +++ b/apps/backend/internal/agentctl/server/acp/connection.go @@ -0,0 +1,41 @@ +package acp + +import ( + "io" + "log/slog" + + acpsdk "github.com/coder/acp-go-sdk" +) + +// NewClientSideConnectionWithLogger creates an ACP client connection and +// installs its logger before the SDK's receive goroutine can read from the +// peer. The SDK starts that goroutine in NewClientSideConnection, while +// SetLogger is not synchronized with it. +func NewClientSideConnectionWithLogger( + client acpsdk.Client, + peerInput io.Writer, + peerOutput io.Reader, + logger *slog.Logger, + opts ...acpsdk.ConnectionOption, +) *acpsdk.ClientSideConnection { + output := &loggerReadyReader{ + ready: make(chan struct{}), + reader: peerOutput, + } + conn := acpsdk.NewClientSideConnection(client, peerInput, output, opts...) + if logger != nil { + conn.SetLogger(logger) + } + close(output.ready) + return conn +} + +type loggerReadyReader struct { + ready chan struct{} + reader io.Reader +} + +func (r *loggerReadyReader) Read(p []byte) (int, error) { + <-r.ready + return r.reader.Read(p) +} diff --git a/apps/backend/internal/agentctl/server/adapter/transport/acp/adapter.go b/apps/backend/internal/agentctl/server/adapter/transport/acp/adapter.go index 9c8200df8d..d80ee4ca33 100644 --- a/apps/backend/internal/agentctl/server/adapter/transport/acp/adapter.go +++ b/apps/backend/internal/agentctl/server/adapter/transport/acp/adapter.go @@ -513,9 +513,13 @@ func (a *Adapter) Initialize(ctx context.Context) error { // queue and is drained by our update worker. Requires a coder/acp-go-sdk // fork with WithMaxQueuedNotifications; see go.mod replace directive. notifQueueCap := acpNotifQueueCapacity(a.cfg.NotificationQueueCapacity) - a.acpConn = acp.NewClientSideConnection(a.acpClient, a.stdin, a.stdout, - acp.WithMaxQueuedNotifications(notifQueueCap)) - a.acpConn.SetLogger(slog.Default().With("component", "acp-conn")) + a.acpConn = acpclient.NewClientSideConnectionWithLogger( + a.acpClient, + a.stdin, + a.stdout, + slog.Default().With("component", "acp-conn"), + acp.WithMaxQueuedNotifications(notifQueueCap), + ) a.logger.Debug("ACP connection notification queue sized", zap.Int("capacity", notifQueueCap)) diff --git a/apps/backend/internal/agentctl/server/api/workspace_state.go b/apps/backend/internal/agentctl/server/api/workspace_state.go index f277923cf0..324899ca61 100644 --- a/apps/backend/internal/agentctl/server/api/workspace_state.go +++ b/apps/backend/internal/agentctl/server/api/workspace_state.go @@ -8,6 +8,8 @@ import ( "go.uber.org/zap" ) +const defaultWorkspaceRefreshTrigger = "manual_refresh" + // SetPollModeRequest is the body for POST /api/v1/workspace/poll-mode. type SetPollModeRequest struct { Mode string `json:"mode"` @@ -67,7 +69,7 @@ func (s *Server) handleRefreshWorkspace(c *gin.Context) { } trigger := req.Trigger if trigger == "" { - trigger = "manual_refresh" + trigger = defaultWorkspaceRefreshTrigger } s.procMgr.RefreshWorkspace(c.Request.Context(), trigger) c.JSON(http.StatusOK, gin.H{"trigger": process.NormalizeWorkspaceTrigger(trigger)}) diff --git a/apps/backend/internal/agentctl/server/utility/acp_executor.go b/apps/backend/internal/agentctl/server/utility/acp_executor.go index 3654ea81b0..2ea3e3ef64 100644 --- a/apps/backend/internal/agentctl/server/utility/acp_executor.go +++ b/apps/backend/internal/agentctl/server/utility/acp_executor.go @@ -202,8 +202,12 @@ func (e *ACPInferenceExecutor) executeACPSession( client := acpclient.NewClient(clientOptions...) // Create ACP connection - conn := acp.NewClientSideConnection(client, stdin, stdout) - conn.SetLogger(slog.Default().With("component", "acp-inference")) + conn := acpclient.NewClientSideConnectionWithLogger( + client, + stdin, + stdout, + slog.Default().With("component", "acp-inference"), + ) // Initialize ACP handshake // Same client capabilities the session adapter and the probe send. This @@ -895,8 +899,12 @@ func (e *ACPInferenceExecutor) probeACPSessionWithContext( acpclient.WithUpdateHandler(updates.handle), ) - conn := acp.NewClientSideConnection(client, stdin, stdout) - conn.SetLogger(slog.Default().With("component", "acp-probe")) + conn := acpclient.NewClientSideConnectionWithLogger( + client, + stdin, + stdout, + slog.Default().With("component", "acp-probe"), + ) // Advertise the same model-picker capability the live session adapter sends. // cursor-agent picks its model picker mode from this handshake, so a probe diff --git a/apps/backend/internal/common/fsdiagnostics/context.go b/apps/backend/internal/common/fsdiagnostics/context.go index c4b9a19fc3..33a28155ed 100644 --- a/apps/backend/internal/common/fsdiagnostics/context.go +++ b/apps/backend/internal/common/fsdiagnostics/context.go @@ -13,7 +13,11 @@ import ( "go.uber.org/zap" ) -const defaultWarningInterval = 30 * time.Second +const ( + defaultWarningInterval = 30 * time.Second + runtimeDesktop = "desktop" + runtimeServer = "server" +) // Context identifies one filesystem operation in a structured log entry. // Empty identity fields are omitted because some operations run before a @@ -78,9 +82,9 @@ func CanonicalPath(path string) string { // labels used by diagnostics. func RuntimeMode(desktop bool) string { if desktop { - return "desktop" + return runtimeDesktop } - return "server" + return runtimeServer } // IsAccessDenied reports the deterministic permission class used by the diff --git a/apps/backend/internal/orchestrator/event_handlers_transient.go b/apps/backend/internal/orchestrator/event_handlers_transient.go index d2cbd1961d..bd27fe22ae 100644 --- a/apps/backend/internal/orchestrator/event_handlers_transient.go +++ b/apps/backend/internal/orchestrator/event_handlers_transient.go @@ -34,8 +34,8 @@ const ( metaKeyVariant = "variant" metaKeySessionID = "session_id" metaKeyTaskID = "task_id" - metaKeyNewState = "new_state" metaKeyAgentID = "agent_id" + metaKeyNewState = "new_state" metaKeyAgentProfileID = "agent_profile_id" metaKeyUpdatedAt = "updated_at" ) diff --git a/apps/backend/internal/orchestrator/step_handoff_carry.go b/apps/backend/internal/orchestrator/step_handoff_carry.go index 7172a73593..5bf367229d 100644 --- a/apps/backend/internal/orchestrator/step_handoff_carry.go +++ b/apps/backend/internal/orchestrator/step_handoff_carry.go @@ -46,7 +46,7 @@ func (s *Service) drainQueuedMessageForPromptableSessionWithHandoff( if err := s.checkSessionPromptable(session.TaskID, sessionID, session.State); err != nil { return false } - if s.messageQueue == nil || s.isQueuedDispatchInFlight(sessionID) || s.isSteerInFlight(sessionID) { + if !s.canDrainQueuedMessage(sessionID) { return false } identity := messagequeue.QueueSessionIdentity{ @@ -69,6 +69,12 @@ func (s *Service) drainQueuedMessageForPromptableSessionWithHandoff( return s.dispatchTakenQueuedMessageForSession(ctx, identity, queuedMsg, ok) } +func (s *Service) canDrainQueuedMessage(sessionID string) bool { + return s.messageQueue != nil && + !s.isQueuedDispatchInFlight(sessionID) && + !s.isSteerInFlight(sessionID) +} + // withStepHandoffMetadata returns a shallow copy of msg carrying handoffText // under messagequeue.MetadataStepHandoff, leaving the original message (and // its metadata map) untouched so a later drain of the same stored entry never diff --git a/apps/backend/internal/task/handlers/process_handlers.go b/apps/backend/internal/task/handlers/process_handlers.go index 8b49537e95..0c0f6fa5ef 100644 --- a/apps/backend/internal/task/handlers/process_handlers.go +++ b/apps/backend/internal/task/handlers/process_handlers.go @@ -23,8 +23,10 @@ import ( "github.com/kandev/kandev/internal/task/service" ) -// queryValueTrue is the string "true" used in query parameter comparisons. -const queryValueTrue = "true" +const ( + queryValueTrue = "true" + invalidRequestBody = "invalid request body" +) type ProcessHandlers struct { service *service.Service @@ -89,7 +91,7 @@ func (h *ProcessHandlers) httpStartProcess(c *gin.Context) { var body httpStartProcessRequest if err := c.ShouldBindJSON(&body); err != nil { h.logger.Warn("start process invalid request body", zap.String("session_id", sessionID), zap.Error(err)) - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } h.logger.Debug("start process request", diff --git a/apps/backend/internal/task/handlers/repository_branch_policy_handlers.go b/apps/backend/internal/task/handlers/repository_branch_policy_handlers.go index c0e6b4b40b..62e0013d8f 100644 --- a/apps/backend/internal/task/handlers/repository_branch_policy_handlers.go +++ b/apps/backend/internal/task/handlers/repository_branch_policy_handlers.go @@ -120,7 +120,7 @@ func (h *RepositoryBranchPolicyHandlers) httpList(c *gin.Context) { func (h *RepositoryBranchPolicyHandlers) httpCreate(c *gin.Context) { var body repositoryBranchPolicyCreateBody if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } policy, err := h.service.CreateRepositoryBranchPolicy(c.Request.Context(), &service.CreateRepositoryBranchPolicyRequest{ @@ -137,7 +137,7 @@ func (h *RepositoryBranchPolicyHandlers) httpCreate(c *gin.Context) { func (h *RepositoryBranchPolicyHandlers) httpGitflow(c *gin.Context) { var body repositoryBranchPolicyGitflowBody if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } policies, err := h.service.CreateGitflowRepositoryBranchPolicies(c.Request.Context(), &service.CreateGitflowRepositoryBranchPoliciesRequest{ @@ -162,7 +162,7 @@ func (h *RepositoryBranchPolicyHandlers) httpGet(c *gin.Context) { func (h *RepositoryBranchPolicyHandlers) httpUpdate(c *gin.Context) { var body repositoryBranchPolicyUpdateBody if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } policy, err := h.service.GetRepositoryBranchPolicy(c.Request.Context(), c.Param("id")) diff --git a/apps/backend/internal/task/handlers/repository_handlers.go b/apps/backend/internal/task/handlers/repository_handlers.go index 58aea48228..5f9a8b3f80 100644 --- a/apps/backend/internal/task/handlers/repository_handlers.go +++ b/apps/backend/internal/task/handlers/repository_handlers.go @@ -223,7 +223,7 @@ func (h *RepositoryHandlers) httpListDiscoveryRoots(c *gin.Context) { func (h *RepositoryHandlers) httpAddDiscoveryRoot(c *gin.Context) { var body discoveryRootRequest if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } root, err := h.service.AddDesktopDiscoveryRoot(c.Request.Context(), body.Path) @@ -242,7 +242,7 @@ func (h *RepositoryHandlers) httpAddDiscoveryRoot(c *gin.Context) { func (h *RepositoryHandlers) httpReconnectDiscoveryRoot(c *gin.Context) { var body discoveryRootRequest if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } root, err := h.service.ReconnectDesktopDiscoveryRoot(c.Request.Context(), body.Path, body.NewPath) @@ -306,7 +306,7 @@ type httpCreateDirectoryRequest struct { func (h *RepositoryHandlers) httpCreateDirectory(c *gin.Context) { var body httpCreateDirectoryRequest if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } result, err := h.service.CreateDirectory(c.Request.Context(), body.ParentPath, body.Name) @@ -525,7 +525,7 @@ func (h *RepositoryHandlers) readOnlyRepositoryMessage(ctx context.Context, repo func (h *RepositoryHandlers) httpInitializeLocalRepository(c *gin.Context) { var body httpInitializeLocalRepositoryRequest if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } if h.rejectReadOnlyWorkspaceHTTP(c, c.Param("id")) { @@ -556,7 +556,7 @@ func (h *RepositoryHandlers) httpInitializeLocalRepository(c *gin.Context) { func (h *RepositoryHandlers) httpCreateRepository(c *gin.Context) { var body httpCreateRepositoryRequest if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } if body.Name == "" { @@ -682,7 +682,7 @@ type httpUpdateRepositoryRequest struct { func (h *RepositoryHandlers) httpUpdateRepository(c *gin.Context) { var body httpUpdateRepositoryRequest if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } if h.rejectReadOnlyRepositoryHTTP(c, c.Param("id")) { diff --git a/apps/backend/internal/task/handlers/repository_script_handlers.go b/apps/backend/internal/task/handlers/repository_script_handlers.go index 63ceb4248b..8b1b7354f9 100644 --- a/apps/backend/internal/task/handlers/repository_script_handlers.go +++ b/apps/backend/internal/task/handlers/repository_script_handlers.go @@ -41,7 +41,7 @@ type httpCreateRepositoryScriptRequest struct { func (h *RepositoryHandlers) httpCreateRepositoryScript(c *gin.Context) { var body httpCreateRepositoryScriptRequest if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } if body.Name == "" || body.Command == "" { @@ -80,7 +80,7 @@ type httpUpdateRepositoryScriptRequest struct { func (h *RepositoryHandlers) httpUpdateRepositoryScript(c *gin.Context) { var body httpUpdateRepositoryScriptRequest if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } script, err := h.service.UpdateRepositoryScript(c.Request.Context(), c.Param("id"), &service.UpdateRepositoryScriptRequest{ diff --git a/apps/backend/internal/task/handlers/repository_set_handlers.go b/apps/backend/internal/task/handlers/repository_set_handlers.go index 144c2dd8a2..897e2be26a 100644 --- a/apps/backend/internal/task/handlers/repository_set_handlers.go +++ b/apps/backend/internal/task/handlers/repository_set_handlers.go @@ -153,7 +153,7 @@ func (h *RepositorySetHandlers) httpListRepositorySets(c *gin.Context) { func (h *RepositorySetHandlers) httpCreateRepositorySet(c *gin.Context) { var body repositorySetCreateBody if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } workspaceID := c.Param("id") @@ -185,7 +185,7 @@ func (h *RepositorySetHandlers) httpGetRepositorySet(c *gin.Context) { func (h *RepositorySetHandlers) httpUpdateRepositorySet(c *gin.Context) { var body repositorySetUpdateBody if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } set, err := h.service.GetRepositorySet(c.Request.Context(), c.Param("id")) diff --git a/apps/backend/internal/task/handlers/workflow_handlers.go b/apps/backend/internal/task/handlers/workflow_handlers.go index 8e55772df9..ea92071050 100644 --- a/apps/backend/internal/task/handlers/workflow_handlers.go +++ b/apps/backend/internal/task/handlers/workflow_handlers.go @@ -168,7 +168,7 @@ type httpCreateWorkflowRequest struct { func (h *WorkflowHandlers) httpCreateWorkflow(c *gin.Context) { var body httpCreateWorkflowRequest if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } if body.Name == "" || body.WorkspaceID == "" { @@ -281,7 +281,7 @@ type httpUpdateWorkflowRequest struct { func (h *WorkflowHandlers) httpUpdateWorkflow(c *gin.Context) { var body httpUpdateWorkflowRequest if err := c.ShouldBindJSON(&body); err != nil { - c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"}) + c.JSON(http.StatusBadRequest, gin.H{"error": invalidRequestBody}) return } id := c.Param("id") diff --git a/apps/web/e2e/tests/chat/mobile-markdown-wrap.spec.ts b/apps/web/e2e/tests/chat/mobile-markdown-wrap.spec.ts index 43c069c991..86e571040c 100644 --- a/apps/web/e2e/tests/chat/mobile-markdown-wrap.spec.ts +++ b/apps/web/e2e/tests/chat/mobile-markdown-wrap.spec.ts @@ -109,7 +109,8 @@ test.describe("mobile: Markdown table wrapping", () => { const table = markdown.locator("table"); const tableWrapper = table.locator("xpath=.."); - await expect(table).toBeVisible(); + // The expandable header renders before the streamed thinking body. + await expect(table).toBeVisible({ timeout: 30_000 }); await expect(markdown.getByTestId(/^markdown-table-resizer-/)).toHaveCount(0); expect( await tableWrapper.evaluate((element) => element.scrollWidth > element.clientWidth + 1), diff --git a/docs/public/configuration.md b/docs/public/configuration.md index daa1334d4b..7cbf8e6d65 100644 --- a/docs/public/configuration.md +++ b/docs/public/configuration.md @@ -69,33 +69,33 @@ Some common camelCase keys have explicit compatibility aliases. Use the document
Complete backend startup reference -| YAML key | Environment variable | Default | Current behavior | -|---|---|---|---| -| `homeDir` | `KANDEV_HOME_DIR` | `~/.kandev` | Root for data, tasks, worktrees, cloned repositories, sessions, and logs. A leading `~/` expands. | -| `server.host` | `KANDEV_SERVER_HOST` | `0.0.0.0` | HTTP listen address. It accepts one hostname/IP or a comma-separated list. Use `127.0.0.1` for local-only access. | -| `server.port` | `KANDEV_SERVER_PORT` (`KANDEV_BACKEND_PORT`, `KANDEV_PORT` aliases) | `38429` | UI, HTTP API, WebSocket, and MCP port; must be `1`-`65535`. The launcher normally supplies its selected port. | -| `server.readTimeout` | `KANDEV_SERVER_READTIMEOUT` | `30` | HTTP read timeout in seconds. | -| `server.writeTimeout` | `KANDEV_SERVER_WRITETIMEOUT` | `30` | HTTP write timeout in seconds. | -| `server.webInternalUrl` | `KANDEV_WEB_INTERNAL_URL` | empty | Development reverse-proxy target for a separately running web app. Installed releases normally serve embedded assets. | -| `server.webTitlePrefix` | `KANDEV_WEB_TITLE_PREFIX` | empty | Prefixes the browser tab title as ` Kandev` (for example `TEST` renders `TEST Kandev`), so several instances stay distinguishable in adjacent tabs. `make dev` defaults to `Dev`; `make start-debug` keeps production defaults, enables diagnostics, and defaults to `Debug`; PR previews use `Preview`. An explicit value overrides these defaults. Empty keeps the plain `Kandev` title. | -| `server.trustedProxies` | `KANDEV_TRUSTED_PROXIES` | empty list | IP addresses or CIDR ranges for proxies whose forwarded client headers Kandev accepts. See [Trusted proxies](#trusted-proxies-for-x-forwarded-for). | +| YAML key | Environment variable | Default | Current behavior | +| ----------------------- | ------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `homeDir` | `KANDEV_HOME_DIR` | `~/.kandev` | Root for data, tasks, worktrees, cloned repositories, sessions, and logs. A leading `~/` expands. | +| `server.host` | `KANDEV_SERVER_HOST` | `0.0.0.0` | HTTP listen address. It accepts one hostname/IP or a comma-separated list. Use `127.0.0.1` for local-only access. | +| `server.port` | `KANDEV_SERVER_PORT` (`KANDEV_BACKEND_PORT`, `KANDEV_PORT` aliases) | `38429` | UI, HTTP API, WebSocket, and MCP port; must be `1`-`65535`. The launcher normally supplies its selected port. | +| `server.readTimeout` | `KANDEV_SERVER_READTIMEOUT` | `30` | HTTP read timeout in seconds. | +| `server.writeTimeout` | `KANDEV_SERVER_WRITETIMEOUT` | `30` | HTTP write timeout in seconds. | +| `server.webInternalUrl` | `KANDEV_WEB_INTERNAL_URL` | empty | Development reverse-proxy target for a separately running web app. Installed releases normally serve embedded assets. | +| `server.webTitlePrefix` | `KANDEV_WEB_TITLE_PREFIX` | empty | Prefixes the browser tab title as ` Kandev` (for example `TEST` renders `TEST Kandev`), so several instances stay distinguishable in adjacent tabs. `make dev` defaults to `Dev`; `make start-debug` keeps production defaults, enables diagnostics, and defaults to `Debug`; PR previews use `Preview`. An explicit value overrides these defaults. Empty keeps the plain `Kandev` title. | +| `server.trustedProxies` | `KANDEV_TRUSTED_PROXIES` | empty list | IP addresses or CIDR ranges for proxies whose forwarded client headers Kandev accepts. See [Trusted proxies](#trusted-proxies-for-x-forwarded-for). | When `server.host` is unset, `server.hosts` may provide a YAML list of bind addresses. The launcher derives its health targets and access URL from this resolved set. It probes an IPv4 wildcard through `127.0.0.1` and keeps `localhost` as the default browser/access URL, while it probes and accesses an IPv6 wildcard through `[::1]`. The backend still listens on every interface for a wildcard bind. The current local product path must not be treated as an authenticated multi-user perimeter. For remote access, bind to loopback and use a trusted authenticated tunnel/proxy, or isolate the network at the deployment layer. ### Database -| YAML key | Environment variable | Default | Current behavior | -|---|---|---|---| -| `database.driver` | `KANDEV_DATABASE_DRIVER` | `sqlite` | `sqlite` or `postgres` (case-normalized). | -| `database.path` | `KANDEV_DATABASE_PATH` | `/data/kandev.db` | SQLite database path. Empty resolves to the default. | -| `database.host` | `KANDEV_DATABASE_HOST` | `localhost` | PostgreSQL only. | -| `database.port` | `KANDEV_DATABASE_PORT` | `5432` | PostgreSQL only; must be `1`-`65535`. | -| `database.user` | `KANDEV_DATABASE_USER` | `kandev` | Required and non-empty for PostgreSQL. | -| `database.password` | `KANDEV_DATABASE_PASSWORD` | empty | PostgreSQL password; requirement depends on server authentication policy. | -| `database.dbName` | `KANDEV_DATABASE_DBNAME` | `kandev` | Required and non-empty for PostgreSQL. | -| `database.sslMode` | `KANDEV_DATABASE_SSLMODE` | `disable` | `disable`, `require`, `verify-ca`, or `verify-full`. | -| `database.maxConns` | `KANDEV_DATABASE_MAXCONNS` | `25` | PostgreSQL maximum pool size. | -| `database.minConns` | `KANDEV_DATABASE_MINCONNS` | `5` | PostgreSQL minimum pool size. | +| YAML key | Environment variable | Default | Current behavior | +| ------------------- | -------------------------- | ----------------------- | ------------------------------------------------------------------------- | +| `database.driver` | `KANDEV_DATABASE_DRIVER` | `sqlite` | `sqlite` or `postgres` (case-normalized). | +| `database.path` | `KANDEV_DATABASE_PATH` | `/data/kandev.db` | SQLite database path. Empty resolves to the default. | +| `database.host` | `KANDEV_DATABASE_HOST` | `localhost` | PostgreSQL only. | +| `database.port` | `KANDEV_DATABASE_PORT` | `5432` | PostgreSQL only; must be `1`-`65535`. | +| `database.user` | `KANDEV_DATABASE_USER` | `kandev` | Required and non-empty for PostgreSQL. | +| `database.password` | `KANDEV_DATABASE_PASSWORD` | empty | PostgreSQL password; requirement depends on server authentication policy. | +| `database.dbName` | `KANDEV_DATABASE_DBNAME` | `kandev` | Required and non-empty for PostgreSQL. | +| `database.sslMode` | `KANDEV_DATABASE_SSLMODE` | `disable` | `disable`, `require`, `verify-ca`, or `verify-full`. | +| `database.maxConns` | `KANDEV_DATABASE_MAXCONNS` | `25` | PostgreSQL maximum pool size. | +| `database.minConns` | `KANDEV_DATABASE_MINCONNS` | `5` | PostgreSQL minimum pool size. | SQLite is the supported default and enables WAL mode. PostgreSQL deployments must provision the database, network policy, TLS trust, backups, and credentials before starting Kandev. Passing the password in an environment variable avoids putting it in YAML but still exposes it to processes/administrators allowed to inspect the environment; use your platform's secret injection controls. @@ -122,43 +122,43 @@ Database-only snapshots also omit `/data/master.key`, the AES-256 key used ### Event bus and NATS -| YAML key | Environment variable | Default | Current behavior | -|---|---|---|---| -| `nats.url` | `KANDEV_NATS_URL` | empty | Empty uses the in-process event bus; otherwise connect to NATS. | -| `nats.clusterId` | `KANDEV_NATS_CLUSTERID` | `kandev-cluster` | Accepted compatibility field; the current NATS client does not consume it. | -| `nats.clientId` | `KANDEV_NATS_CLIENTID` | `kandev-client` | NATS connection name. | -| `nats.maxReconnects` | `KANDEV_NATS_MAXRECONNECTS` | `10` | Reconnect limit; the client uses a two-second reconnect wait and a 5 MiB reconnect buffer. | -| `events.namespace` | `KANDEV_EVENTS_NAMESPACE` | derived | Queue-group namespace. Empty derives a stable, sanitized hash from database identity. | +| YAML key | Environment variable | Default | Current behavior | +| -------------------- | --------------------------- | ---------------- | ------------------------------------------------------------------------------------------ | +| `nats.url` | `KANDEV_NATS_URL` | empty | Empty uses the in-process event bus; otherwise connect to NATS. | +| `nats.clusterId` | `KANDEV_NATS_CLUSTERID` | `kandev-cluster` | Accepted compatibility field; the current NATS client does not consume it. | +| `nats.clientId` | `KANDEV_NATS_CLIENTID` | `kandev-client` | NATS connection name. | +| `nats.maxReconnects` | `KANDEV_NATS_MAXRECONNECTS` | `10` | Reconnect limit; the client uses a two-second reconnect wait and a 5 MiB reconnect buffer. | +| `events.namespace` | `KANDEV_EVENTS_NAMESPACE` | derived | Queue-group namespace. Empty derives a stable, sanitized hash from database identity. | An external NATS URL moves event traffic across the configured network and can embed credentials/TLS parameters. Protect it as a secret where applicable, require TLS for untrusted networks, and keep namespaces distinct when deployments share one NATS server. `clusterId` does not provide isolation in the current implementation. ### Docker runtime -| YAML key | Environment variable | Default | Current behavior | -|---|---|---|---| -| `docker.enabled` | `KANDEV_DOCKER_ENABLED` | `true` | Registers the local Docker executor. The client connects lazily, so startup can succeed without a daemon. | -| `docker.host` | `KANDEV_DOCKER_HOST` | `DOCKER_HOST`, otherwise platform socket | Docker endpoint used by the client. Defaults to `unix:///var/run/docker.sock` on Unix and `npipe:////./pipe/docker_engine` on Windows. | -| `docker.apiVersion` | `KANDEV_DOCKER_APIVERSION` | empty | Empty uses Docker API negotiation. | -| `docker.tlsVerify` | `KANDEV_DOCKER_TLSVERIFY` | `false` | Accepted compatibility field; not wired into the current client. | -| `docker.defaultNetwork` | `KANDEV_DOCKER_DEFAULTNETWORK` | `kandev-network` | Accepted compatibility field; not wired into current executor networking. | -| `docker.volumeBasePath` | `KANDEV_DOCKER_VOLUMEBASEPATH` | `/var/lib/kandev/volumes` on Unix; `%LOCALAPPDATA%\kandev\volumes` on Windows | Accepted compatibility field; not wired into current executor volume placement. | +| YAML key | Environment variable | Default | Current behavior | +| ----------------------- | ------------------------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `docker.enabled` | `KANDEV_DOCKER_ENABLED` | `true` | Registers the local Docker executor. The client connects lazily, so startup can succeed without a daemon. | +| `docker.host` | `KANDEV_DOCKER_HOST` | `DOCKER_HOST`, otherwise platform socket | Docker endpoint used by the client. Defaults to `unix:///var/run/docker.sock` on Unix and `npipe:////./pipe/docker_engine` on Windows. | +| `docker.apiVersion` | `KANDEV_DOCKER_APIVERSION` | empty | Empty uses Docker API negotiation. | +| `docker.tlsVerify` | `KANDEV_DOCKER_TLSVERIFY` | `false` | Accepted compatibility field; not wired into the current client. | +| `docker.defaultNetwork` | `KANDEV_DOCKER_DEFAULTNETWORK` | `kandev-network` | Accepted compatibility field; not wired into current executor networking. | +| `docker.volumeBasePath` | `KANDEV_DOCKER_VOLUMEBASEPATH` | `/var/lib/kandev/volumes` on Unix; `%LOCALAPPDATA%\kandev\volumes` on Windows | Accepted compatibility field; not wired into current executor volume placement. | The Docker socket is effectively root-equivalent on many hosts. Do not publish it or assume `docker.tlsVerify` secures a TCP daemon; it currently does not. Configure TLS through a supported Docker endpoint/environment and validate it independently, or keep the daemon local. See [Docker](docker.md) and [Executors](executors.md). ### Core agent service -| YAML key | Environment variable | Default | Current behavior | -|---|---|---|---| -| `agent.standaloneHost` | `KANDEV_AGENT_STANDALONE_HOST` | `localhost` | Host of the core `agentctl` control server. | -| `agent.standalonePort` | `AGENTCTL_PORT` or `KANDEV_AGENT_STANDALONE_PORT` | `39429` | Preferred control port. The launcher may supply a free fallback. | +| YAML key | Environment variable | Default | Current behavior | +| ---------------------- | ------------------------------------------------- | ----------- | ---------------------------------------------------------------- | +| `agent.standaloneHost` | `KANDEV_AGENT_STANDALONE_HOST` | `localhost` | Host of the core `agentctl` control server. | +| `agent.standalonePort` | `AGENTCTL_PORT` or `KANDEV_AGENT_STANDALONE_PORT` | `39429` | Preferred control port. The launcher may supply a free fallback. | The launcher starts `agentctl`, performs a one-time nonce handshake, and supplies the resulting per-launch token internally. Do not persist or proxy its bootstrap/auth state. Agent command, model, environment, permission, and MCP configuration belongs in agent profiles rather than this section. ### Setup and launch timing -| YAML key | Environment variable | Default | Current behavior | -|---|---|---|---| -| `tasks.preparationTimeout` | `KANDEV_TASK_PREPARATION_TIMEOUT` | `10m` | Positive Go duration for repository setup and executor-profile prepare scripts. | +| YAML key | Environment variable | Default | Current behavior | +| -------------------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------- | +| `tasks.preparationTimeout` | `KANDEV_TASK_PREPARATION_TIMEOUT` | `10m` | Positive Go duration for repository setup and executor-profile prepare scripts. | `tasks.preparationTimeout` controls how long Kandev allows repository setup and executor-profile prepare scripts to run. The value uses Go duration syntax, @@ -178,22 +178,22 @@ startup setting, not a database or Settings value. ### Capacity and managed-process startup settings -| YAML key | Environment variable | Type and default | Current behavior | -|---|---|---|---| -| `credentials.file` | `KANDEV_CREDENTIALS_FILE` | path, empty | Optional fallback JSON credential file. The file is read lazily and must be restricted to the Kandev service account. | -| `limits.ghMaxConcurrent` | `KANDEV_GH_MAX_CONCURRENT` | positive integer, `8` | Process-wide `gh` subprocess admission cap. | -| `limits.gitMaxConcurrent` | `KANDEV_GIT_MAX_CONCURRENT` | positive integer, `12` | Process-wide `git` subprocess admission cap. | -| `limits.lspMaxConnections` | `KANDEV_LSP_MAX_CONNECTIONS` | positive integer, `8` | Active browser-to-task-host language-server connection cap. | -| `messageQueue.maxPerSession` | `KANDEV_QUEUE_MAX_PER_SESSION` | integer `>= 0`, `10` | Per-session pending-message cap. Zero means unlimited. A non-negative YAML or environment value locks capacity in Settings; a negative environment value means unlimited, and invalid environment input falls through to the lower-precedence source. | -| `agentctl.idleTimeout` | `KANDEV_ACP_IDLE_TIMEOUT` | Go duration, `1h` | Idle managed-agent reaping timeout. Zero disables reaping. | -| `agentctl.idleReaperInterval` | `KANDEV_ACP_IDLE_REAPER_INTERVAL` | Go duration, `1m` | Interval between idle-agent scans. | -| `agentctl.notificationQueueCapacity` | `KANDEV_ACP_NOTIF_QUEUE` | integer `1024`-`131072`, `131072` | ACP inbound notification queue capacity. An out-of-range YAML value fails startup; an invalid or out-of-range environment value uses the built-in default. | -| `planning.coalesceWindowMs` | `KANDEV_PLAN_COALESCE_WINDOW_MS` | integer `>= 0`, `300000` | Same-author plan revision coalescing window in milliseconds. | -| `observability.otlpEndpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | URL, empty | OTLP tracing endpoint. Treat the value and emitted spans as sensitive. | -| `office.schedulerTickMs` | `KANDEV_OFFICE_SCHEDULER_TICK_MS` | positive integer, `5000` | Office queued/retry run safety-net interval in milliseconds. | -| `launcher.webPort` | `KANDEV_WEB_PORT` | automatic, `0` | Development web-server port. It is used with `dev` and ignored by embedded-asset launches. | -| `launcher.healthTimeoutMs` | `KANDEV_HEALTH_TIMEOUT_MS` | positive integer, `45000` | Launcher startup-health timeout in milliseconds. Development and E2E profiles use a longer default. | -| `launcher.noBrowser` | `KANDEV_NO_BROWSER` | `false` | Suppresses browser opening when true or `1`, depending on launch mode. | +| YAML key | Environment variable | Type and default | Current behavior | +| ------------------------------------ | --------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `credentials.file` | `KANDEV_CREDENTIALS_FILE` | path, empty | Optional fallback JSON credential file. The file is read lazily and must be restricted to the Kandev service account. | +| `limits.ghMaxConcurrent` | `KANDEV_GH_MAX_CONCURRENT` | positive integer, `8` | Process-wide `gh` subprocess admission cap. | +| `limits.gitMaxConcurrent` | `KANDEV_GIT_MAX_CONCURRENT` | positive integer, `12` | Process-wide `git` subprocess admission cap. | +| `limits.lspMaxConnections` | `KANDEV_LSP_MAX_CONNECTIONS` | positive integer, `8` | Active browser-to-task-host language-server connection cap. | +| `messageQueue.maxPerSession` | `KANDEV_QUEUE_MAX_PER_SESSION` | integer `>= 0`, `10` | Per-session pending-message cap. Zero means unlimited. A non-negative YAML or environment value locks capacity in Settings; a negative environment value means unlimited, and invalid environment input falls through to the lower-precedence source. | +| `agentctl.idleTimeout` | `KANDEV_ACP_IDLE_TIMEOUT` | Go duration, `1h` | Idle managed-agent reaping timeout. Zero disables reaping. | +| `agentctl.idleReaperInterval` | `KANDEV_ACP_IDLE_REAPER_INTERVAL` | Go duration, `1m` | Interval between idle-agent scans. | +| `agentctl.notificationQueueCapacity` | `KANDEV_ACP_NOTIF_QUEUE` | integer `1024`-`131072`, `131072` | ACP inbound notification queue capacity. An out-of-range YAML value fails startup; an invalid or out-of-range environment value uses the built-in default. | +| `planning.coalesceWindowMs` | `KANDEV_PLAN_COALESCE_WINDOW_MS` | integer `>= 0`, `300000` | Same-author plan revision coalescing window in milliseconds. | +| `observability.otlpEndpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | URL, empty | OTLP tracing endpoint. Treat the value and emitted spans as sensitive. | +| `office.schedulerTickMs` | `KANDEV_OFFICE_SCHEDULER_TICK_MS` | positive integer, `5000` | Office queued/retry run safety-net interval in milliseconds. | +| `launcher.webPort` | `KANDEV_WEB_PORT` | automatic, `0` | Development web-server port. It is used with `dev` and ignored by embedded-asset launches. | +| `launcher.healthTimeoutMs` | `KANDEV_HEALTH_TIMEOUT_MS` | positive integer, `45000` | Launcher startup-health timeout in milliseconds. Development and E2E profiles use a longer default. | +| `launcher.noBrowser` | `KANDEV_NO_BROWSER` | `false` | Suppresses browser opening when true or `1`, depending on launch mode. | These settings are read at startup. Their environment aliases remain compatible overrides, and a YAML value is not copied into a public process @@ -202,14 +202,15 @@ through a private process contract. ### Authentication, Office, Plugins, and feature flags -| YAML key | Environment variable | Default | Current behavior | -|---|---|---|---| -| `auth.jwtSecret` | `KANDEV_AUTH_JWTSECRET` | generated value | Accepted and validated compatibility configuration; the current main HTTP product path does not use it as an authentication boundary. | -| `auth.tokenDuration` | `KANDEV_AUTH_TOKENDURATION` | `3600` | Must be positive, but is not consumed by the current main HTTP product path. | -| `auth.sessionTTLHours` | `KANDEV_AUTH_SESSIONTTLHOURS` | `720` | Compatibility session lifetime setting. | -| `auth.cookieName` | `KANDEV_AUTH_COOKIE_NAME` | empty | Session cookie base name. Empty (default) means the effective name is derived from the request host: `kandev_session` on a default-port host, `kandev_session_` on a ported host. This isolates multiple instances on one host (see [authentication](authentication.md#multiple-instances-on-one-host)). A non-empty value is used verbatim (never port-suffixed) and disables automatic isolation, so it must be unique per cookie host. Precedence: environment over config file over default. | -| `office.jwtSigningKey` | `KANDEV_OFFICE_JWTSIGNINGKEY` | random per start | HMAC key for Office agent-runtime JWTs. Set a stable secret when Office tasks must survive restarts. | -| `githubCredentialBroker.publicBaseUrl` | `KANDEV_GITHUB_CREDENTIAL_BROKER_PUBLIC_BASE_URL` | empty | Public HTTPS base URL used by remote executors to resolve GitHub credentials. Loopback HTTP is allowed for development. | +| YAML key | Environment variable | Default | Current behavior | +| -------------------------------------- | ------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `auth.jwtSecret` | `KANDEV_AUTH_JWTSECRET` | generated value | Accepted and validated compatibility configuration; the current main HTTP product path does not use it as an authentication boundary. | +| `auth.tokenDuration` | `KANDEV_AUTH_TOKENDURATION` | `3600` | Must be positive, but is not consumed by the current main HTTP product path. | +| `auth.sessionTTLHours` | `KANDEV_AUTH_SESSIONTTLHOURS` | `720` | Compatibility session lifetime setting. | +| `auth.cookieName` | `KANDEV_AUTH_COOKIE_NAME` | empty | Session cookie base name. Empty (default) means the effective name is derived from the request host: `kandev_session` on a default-port host, `kandev_session_` on a ported host. This isolates multiple instances on one host (see [authentication](authentication.md#multiple-instances-on-one-host)). A non-empty value is used verbatim (never port-suffixed) and disables automatic isolation, so it must be unique per cookie host. Precedence: environment over config file over default. | +| `office.jwtSigningKey` | `KANDEV_OFFICE_JWTSIGNINGKEY` | random per start | HMAC key for Office agent-runtime JWTs. Set a stable secret when Office tasks must survive restarts. | +| `githubCredentialBroker.publicBaseUrl` | `KANDEV_GITHUB_CREDENTIAL_BROKER_PUBLIC_BASE_URL` | empty | Public HTTPS base URL used by remote executors to resolve GitHub credentials. Loopback HTTP is allowed for development. | + Runtime feature flags are documented in [Runtime feature toggles](#runtime-feature-toggles); they are profile, environment, and database-backed controls, not canonical YAML settings. Do not infer security from `auth.jwtSecret`: setting it currently does not turn the local server into an authenticated public service. Office's JWT key has a narrower, active purpose. Store both active secrets and third-party API keys in your deployment secret manager; never commit them in `config.yaml`. @@ -286,10 +287,10 @@ launch and is not an environment configuration source. ### Logging -| YAML key | Environment variable | Default | Current behavior | -|---|---|---|---| -| `logging.level` | `KANDEV_LOG_LEVEL` | `info` | File threshold: `debug`, `info`, `warn`, or `error`. `--debug` selects `debug`; normal and `--verbose` launches select `info`. | -| `logging.format` | `KANDEV_LOGGING_FORMAT` | `text`, or `json` in production/Kubernetes | `text` or `json`; `auto` is not accepted. | +| YAML key | Environment variable | Default | Current behavior | +| ---------------- | ----------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| `logging.level` | `KANDEV_LOG_LEVEL` | `info` | File threshold: `debug`, `info`, `warn`, or `error`. `--debug` selects `debug`; normal and `--verbose` launches select `info`. | +| `logging.format` | `KANDEV_LOGGING_FORMAT` | `text`, or `json` in production/Kubernetes | `text` or `json`; `auto` is not accepted. | Every backend launch writes to `/logs/backend-logs.log` and prints that resolved path at startup. The active file appends across same-day restarts and accepts at most 16 MiB. Before a new entry would exceed that limit, Kandev closes the file as `backend-logs-YYYY-MM-DD-NNNNNN.log` and opens a new active file. @@ -301,16 +302,16 @@ Debug output may contain repository paths, subprocess output, prompts, file cont ### Repository, worktree, and clone paths -| YAML key | Environment variable | Default | Current behavior | -|---|---|---|---| -| `repositoryDiscovery.roots` | `KANDEV_REPOSITORYDISCOVERY_ROOTS` | `[]` | Roots traversed by automatic repository discovery. Explicitly selected repository paths need not be included. Prefer absolute paths. Array encoding through environment variables is Viper-dependent; YAML is clearer. | -| `repositoryDiscovery.maxDepth` | `KANDEV_REPOSITORYDISCOVERY_MAXDEPTH` | `5` | Positive directory traversal depth. | -| `worktree.enabled` | `KANDEV_WORKTREE_ENABLED` | `true` | Enables the worktree provider. | -| `worktree.defaultBranch` | `KANDEV_WORKTREE_DEFAULTBRANCH` | `main` | Accepted compatibility field; current task behavior uses each repository's stored/detected default branch instead. | -| `worktree.cleanupOnRemove` | `KANDEV_WORKTREE_CLEANUPONREMOVE` | `true` | Accepted compatibility field; current lifecycle cleanup is controlled by repository/task operations, not this value. | -| `worktree.fetchTimeoutSeconds` | `KANDEV_WORKTREE_FETCHTIMEOUTSECONDS` | `60` | Git fetch timeout during worktree preparation. | -| `worktree.pullTimeoutSeconds` | `KANDEV_WORKTREE_PULLTIMEOUTSECONDS` | `60` | Git pull timeout during worktree preparation. | -| `repoClone.basePath` | `KANDEV_REPOCLONE_BASEPATH` | `/repos` | Base directory for provider-backed clones. A leading `~/` expands. | +| YAML key | Environment variable | Default | Current behavior | +| ------------------------------ | ------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `repositoryDiscovery.roots` | `KANDEV_REPOSITORYDISCOVERY_ROOTS` | `[]` | Roots traversed by automatic repository discovery. Explicitly selected repository paths need not be included. Prefer absolute paths. Array encoding through environment variables is Viper-dependent; YAML is clearer. | +| `repositoryDiscovery.maxDepth` | `KANDEV_REPOSITORYDISCOVERY_MAXDEPTH` | `5` | Positive directory traversal depth. | +| `worktree.enabled` | `KANDEV_WORKTREE_ENABLED` | `true` | Enables the worktree provider. | +| `worktree.defaultBranch` | `KANDEV_WORKTREE_DEFAULTBRANCH` | `main` | Accepted compatibility field; current task behavior uses each repository's stored/detected default branch instead. | +| `worktree.cleanupOnRemove` | `KANDEV_WORKTREE_CLEANUPONREMOVE` | `true` | Accepted compatibility field; current lifecycle cleanup is controlled by repository/task operations, not this value. | +| `worktree.fetchTimeoutSeconds` | `KANDEV_WORKTREE_FETCHTIMEOUTSECONDS` | `60` | Git fetch timeout during worktree preparation. | +| `worktree.pullTimeoutSeconds` | `KANDEV_WORKTREE_PULLTIMEOUTSECONDS` | `60` | Git pull timeout during worktree preparation. | +| `repoClone.basePath` | `KANDEV_REPOCLONE_BASEPATH` | `/repos` | Base directory for provider-backed clones. A leading `~/` expands. | Discovery roots bound automatic filesystem traversal, so scope them narrowly. They do not authorize explicitly selected repository paths: **Add Local Repository** validates and saves the exact accessible Git repository the user chooses without widening automatic scans. Worktrees and clones can contain credentials or generated files ignored by Git; review repository copy-file and setup/cleanup settings before remote execution. See [Git operations](git-operations.md). @@ -330,9 +331,9 @@ discovery policy. ### Debug configuration -| YAML key | Environment variable | Default | Current behavior | -|---|---|---|---| -| `debug.devMode` | `KANDEV_DEBUG_DEV_MODE` | `false` | Enables diagnostic endpoints and agent-message debug logging. | +| YAML key | Environment variable | Default | Current behavior | +| -------------------- | ---------------------------- | ------- | ------------------------------------------------------------------------------------------- | +| `debug.devMode` | `KANDEV_DEBUG_DEV_MODE` | `false` | Enables diagnostic endpoints and agent-message debug logging. | | `debug.pprofEnabled` | `KANDEV_DEBUG_PPROF_ENABLED` | `false` | Legacy diagnostics switch. It enables pprof behavior but does not select the `dev` profile. | `KANDEV_DEBUG_DEV_MODE=true` selects the `dev` profile. `make dev` sets that @@ -414,8 +415,8 @@ docker: enabled: true host: "unix:///var/run/docker.sock" # use the Windows named pipe on Windows apiVersion: "" - tlsVerify: false # compatibility-only today - defaultNetwork: "kandev-network" # compatibility-only today + tlsVerify: false # compatibility-only today + defaultNetwork: "kandev-network" # compatibility-only today volumeBasePath: "/var/lib/kandev/volumes" # compatibility-only today agent: @@ -453,7 +454,7 @@ launcher: noBrowser: false auth: - jwtSecret: "" # compatibility-only for the main HTTP product path + jwtSecret: "" # compatibility-only for the main HTTP product path tokenDuration: 3600 # compatibility-only for the main HTTP product path logging: @@ -461,13 +462,13 @@ logging: format: "text" repositoryDiscovery: - roots: [] # automatic scan roots; explicit paths need not be included + roots: [] # automatic scan roots; explicit paths need not be included maxDepth: 5 worktree: enabled: true - defaultBranch: "main" # compatibility-only today - cleanupOnRemove: true # compatibility-only today + defaultBranch: "main" # compatibility-only today + cleanupOnRemove: true # compatibility-only today fetchTimeoutSeconds: 60 pullTimeoutSeconds: 60 @@ -481,7 +482,6 @@ debug: office: jwtSigningKey: "" schedulerTickMs: 5000 - ``` Copying this entire file is unnecessary and can freeze old defaults in a deployment. Keep only deliberate overrides. On Windows, do not copy the Unix Docker host/path literals from this example. @@ -527,8 +527,8 @@ Plugins are part of the base product and are not a runtime toggle. The source checkout's `make dev` activates the embedded development profile, which enables Office, debug surfaces, ACP logging, and a mock agent; authentication, organizations, and Claude background prompt handoff remain opt-in. Installed `run`/desktop builds select the safe production profile unless the environment explicitly opts in. E2E mock variables and routes are test-only and must never be enabled on a public deployment. ## Credentials and product settings -The **Unread Messages** preference in **Settings > Preferences > Task Behavior** controls the Slack-style **New** divider in session transcripts. It defaults off for each user, persists with user settings, and takes effect immediately. Enabling it also allows that user's active transcript view to advance the session read cursor. +The **Unread Messages** preference in **Settings > Preferences > Task Behavior** controls the Slack-style **New** divider in session transcripts. It defaults off for each user, persists with user settings, and takes effect immediately. Enabling it also allows that user's active transcript view to advance the session read cursor. Most integrations, executor profiles, agent profiles, MCP servers, repository settings, and UI preferences are persistent database records edited under **Settings**. They are not fields in `config.yaml`. Secret values use an encrypted secret store backed by `/data/master.key`; filesystem permissions, database backups, and key backup are part of the security boundary. @@ -562,20 +562,20 @@ These settings are startup-only unless stated otherwise. Their YAML keys are the canonical file form; the environment aliases remain compatibility overrides. -| YAML key | Environment variable | Default | Parsing and effect | -|---|---|---:|---| -| `limits.ghMaxConcurrent` | `KANDEV_GH_MAX_CONCURRENT` | `8` | Positive integer process-wide cap for `gh` subprocesses; invalid/non-positive uses default. | -| `limits.gitMaxConcurrent` | `KANDEV_GIT_MAX_CONCURRENT` | `12` | Positive integer process-wide cap for `git` subprocesses; invalid/non-positive uses default. | -| `limits.lspMaxConnections` | `KANDEV_LSP_MAX_CONNECTIONS` | `8` | Positive integer cap for active browser-to-task-host language-server streams; invalid/non-positive uses default. | -| `messageQueue.maxPerSession` | `KANDEV_QUEUE_MAX_PER_SESSION` | `10` | Pending messages per session. A non-negative YAML value locks the saved UI capacity; a valid environment value overrides YAML and locks it; a negative environment value means unlimited; malformed environment input falls through to YAML, the saved setting, or default. | -| `agentctl.idleTimeout` | `KANDEV_ACP_IDLE_TIMEOUT` | `1h` | Go duration after which idle managed agentctl instances are reaped; `0` disables. Invalid uses default. | -| `agentctl.idleReaperInterval` | `KANDEV_ACP_IDLE_REAPER_INTERVAL` | `1m` | Go duration between idle scans. | -| `agentctl.notificationQueueCapacity` | `KANDEV_ACP_NOTIF_QUEUE` | `131072` | Per-connection ACP inbound notification capacity. YAML values outside `1024`-`131072` fail startup; invalid or out-of-range environment values use `131072`. | -| `planning.coalesceWindowMs` | `KANDEV_PLAN_COALESCE_WINDOW_MS` | `300000` | Non-negative milliseconds for same-author plan revision coalescing; invalid/negative uses five minutes. | -| `office.schedulerTickMs` | `KANDEV_OFFICE_SCHEDULER_TICK_MS` | `5000` | Positive integer safety-net interval for queued/retry run claiming. New-run signals are event-driven. | -| `observability.otlpEndpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | unset | Enables OTLP/HTTP tracing for backend and agentctl spans; unset uses a no-op tracer. | +| YAML key | Environment variable | Default | Parsing and effect | +| ------------------------------------ | --------------------------------- | -------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `limits.ghMaxConcurrent` | `KANDEV_GH_MAX_CONCURRENT` | `8` | Positive integer process-wide cap for `gh` subprocesses; invalid/non-positive uses default. | +| `limits.gitMaxConcurrent` | `KANDEV_GIT_MAX_CONCURRENT` | `12` | Positive integer process-wide cap for `git` subprocesses; invalid/non-positive uses default. | +| `limits.lspMaxConnections` | `KANDEV_LSP_MAX_CONNECTIONS` | `8` | Positive integer cap for active browser-to-task-host language-server streams; invalid/non-positive uses default. | +| `messageQueue.maxPerSession` | `KANDEV_QUEUE_MAX_PER_SESSION` | `10` | Pending messages per session. A non-negative YAML value locks the saved UI capacity; a valid environment value overrides YAML and locks it; a negative environment value means unlimited; malformed environment input falls through to YAML, the saved setting, or default. | +| `agentctl.idleTimeout` | `KANDEV_ACP_IDLE_TIMEOUT` | `1h` | Go duration after which idle managed agentctl instances are reaped; `0` disables. Invalid uses default. | +| `agentctl.idleReaperInterval` | `KANDEV_ACP_IDLE_REAPER_INTERVAL` | `1m` | Go duration between idle scans. | +| `agentctl.notificationQueueCapacity` | `KANDEV_ACP_NOTIF_QUEUE` | `131072` | Per-connection ACP inbound notification capacity. YAML values outside `1024`-`131072` fail startup; invalid or out-of-range environment values use `131072`. | +| `planning.coalesceWindowMs` | `KANDEV_PLAN_COALESCE_WINDOW_MS` | `300000` | Non-negative milliseconds for same-author plan revision coalescing; invalid/negative uses five minutes. | +| `office.schedulerTickMs` | `KANDEV_OFFICE_SCHEDULER_TICK_MS` | `5000` | Positive integer safety-net interval for queued/retry run claiming. New-run signals are event-driven. | +| `observability.otlpEndpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | unset | Enables OTLP/HTTP tracing for backend and agentctl spans; unset uses a no-op tracer. | -Changing concurrency values trades process pressure against throughput and requires a restart. Under **Settings > Task Behavior > Message Queue**, an admin can save an install-wide capacity and independently control manual and automatic merging. The merge switches apply live and persist across restarts. `messageQueue.maxPerSession` resolves as environment, YAML, saved setting, then default; a non-negative YAML value or any valid environment value locks only capacity. A negative environment value means unlimited, while malformed environment input falls through to the lower-precedence source. `0` means unlimited. Lowering the live limit does not prune existing rows; new admissions remain blocked until the pending count drops below the limit, while retries of already accepted work remain eligible. The default-on automatic switch affects only later admissions and never bypasses capacity or sweeps existing rows. +Changing concurrency values trades process pressure against throughput and requires a restart. Under **Settings > Task Behavior > Message Queue**, an admin can save an install-wide capacity and independently control manual and automatic merging. The merge switches apply live and persist across restarts. `messageQueue.maxPerSession` resolves as environment, YAML, saved setting, then default; a non-negative YAML value or any valid environment value locks only capacity. A negative environment value means unlimited. See [Operations](operations.md#message-queue-settings) for capacity and automatic-fold behavior. The current OTLP exporter strips an `http://` or `https://` prefix from the configured endpoint and always uses `WithInsecure()`. Treat this as implementation-bound cleartext transport: send it only to a trusted private collector over a protected network, not directly across an untrusted network. The service name is `kandev-agentctl`, and spans can include task/session/execution IDs plus raw agent-event JSON truncated to 8192 characters. That payload can contain prompts, files, and tool data. Use collector-side access controls and retention accordingly. @@ -583,12 +583,12 @@ The current OTLP exporter strips an `http://` or `https://` prefix from the conf These apply only when `KANDEV_DEBUG_AGENT_MESSAGES=true`: -| Variable | Default | -|---|---| -| `KANDEV_DEBUG_LOG_DIR` | `/logs/acp` | -| `KANDEV_DEBUG_ACP_MAX_FILES` | `200` | -| `KANDEV_DEBUG_ACP_RETENTION_HOURS` | `48` | -| `KANDEV_DEBUG_ACP_MAX_FILE_BYTES` | `8388608` (8 MiB) | +| Variable | Default | +| ---------------------------------- | ----------------- | +| `KANDEV_DEBUG_LOG_DIR` | `/logs/acp` | +| `KANDEV_DEBUG_ACP_MAX_FILES` | `200` | +| `KANDEV_DEBUG_ACP_RETENTION_HOURS` | `48` | +| `KANDEV_DEBUG_ACP_MAX_FILE_BYTES` | `8388608` (8 MiB) | Retention values must be positive integers; invalid/non-positive values use defaults. Directories and files use owner-only `0700`/`0600` modes on Unix. Rotation, age pruning, and file-count pruning bound normal growth, but these files remain highly sensitive and can exist inside a Docker executor rather than on the host. diff --git a/docs/public/operations.md b/docs/public/operations.md index 866d60aabd..6a223caac7 100644 --- a/docs/public/operations.md +++ b/docs/public/operations.md @@ -18,12 +18,12 @@ Kandev does not currently provide a user-login boundary for the web application, ## Choose an operating model -| Mode | Start and stop | Durable state | Update path | -| --- | --- | --- | --- | -| Desktop | Launch or quit Kandev | `~/.kandev` by default | **Settings > System > Updates** uses the signed desktop updater when supported | -| Interactive CLI | `kandev`, then `Ctrl-C` | `~/.kandev` by default | Upgrade the Homebrew or npm package, then restart | -| Managed service | `kandev service {start,stop,restart,status}` | `~/.kandev` for a user service, `/var/lib/kandev` for a system service, or the install-time `--home-dir` | A verified npm/npx user service can select and apply Stable or Nightly; other services use Stable and may require a package upgrade, reinstall, and restart | -| Docker or Kubernetes | Container or workload manager | Mounted Kandev home plus any external database/provider state | Replace the image and recreate the container or pod | +| Mode | Start and stop | Durable state | Update path | +| -------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Desktop | Launch or quit Kandev | `~/.kandev` by default | **Settings > System > Updates** uses the signed desktop updater when supported | +| Interactive CLI | `kandev`, then `Ctrl-C` | `~/.kandev` by default | Upgrade the Homebrew or npm package, then restart | +| Managed service | `kandev service {start,stop,restart,status}` | `~/.kandev` for a user service, `/var/lib/kandev` for a system service, or the install-time `--home-dir` | A verified npm/npx user service can select and apply Stable or Nightly; other services use Stable and may require a package upgrade, reinstall, and restart | +| Docker or Kubernetes | Container or workload manager | Mounted Kandev home plus any external database/provider state | Replace the image and recreate the container or pod | See [Desktop app](desktop-app.md), [CLI](cli.md), [Run as a service](run-as-a-service.md), [Docker](docker.md), and [Kubernetes](k8s.md) for mode-specific prerequisites and commands. @@ -69,7 +69,12 @@ curl -fsS http://127.0.0.1:38429/health It returns HTTP 200 as soon as the listener accepts connections, with: ```json -{"status":"ok","service":"kandev","mode":"websocket+http","version":"1.2.3"} +{ + "status": "ok", + "service": "kandev", + "mode": "websocket+http", + "version": "1.2.3" +} ``` `/health` never returns a non-2xx status while the process is alive, even mid-startup: it confirms the process is up, not that it can serve real traffic. Use the readiness endpoint instead when you need to know the backend can actually serve requests: @@ -565,24 +570,24 @@ drawer mirrors it as the saved left sequence followed by the saved right sequenc ## Troubleshooting -| Symptom | Check | Action | -| --- | --- | --- | -| `/health` cannot connect | Process-manager and launcher output | Confirm port ownership, database reachability, writable Kandev home, and required executables; then restart once | -| `/ready` stays at 503 while `/health` is 200 | Backend startup logs | Process is alive but still wiring routes, seeding the agent registry, or mounting test-harness routes; give it more time before restarting | -| Status page says unhealthy while `/ready` is 200 | `/api/v1/system/health` issue IDs | Fix Git, GitHub, agent discovery, or Linux inotify warning; readiness and application diagnostics have different meanings | -| Backups page reports a 15-second create timeout | Reload the backup list and inspect the `backup-create` job/log | Large `VACUUM INTO` jobs can still finish; avoid double-clicking and ensure free disk | -| Backup/maintenance fails on PostgreSQL | Active driver on Database page | Use `pg_dump`, provider snapshots, and PostgreSQL maintenance; System backup/vacuum/reset is SQLite-only | -| Restored data looks stale | Whether the backend was restarted immediately | Quit/restart; do not keep using the old open database connections | -| Diagnostic bundle is partial | `manifest.json` warnings, source status, and loss counters | Keep a Kandev browser open for frontend capture; use backend-only when browser evidence is unnecessary | -| Update check returns HTTP 429 | Time since last **Check now** | Wait at least 30 seconds; background checks retry every six hours | -| **Apply update** is absent | Install mode/method and `/service/install.json` | Expected for system, unmanaged, local-checkout, or invalid-metadata installs. A managed npm, npx, or Homebrew user service should offer Apply; reinstall it with the same flags to refresh its identity and metadata, or use the manual package-manager flow. | -| **Nightly** is disabled | Install mode/method and `/service/install.json` | Expected unless this is a verified managed npm/npx user service. Homebrew, Desktop, system-service, unmanaged, local-checkout, invalid-metadata, and unknown installs are Stable-only. | -| Nightly check or save fails | npm access and cached checked time | Verify access to `https://registry.npmjs.org/kandev`, retry after connectivity returns, or keep/select Stable. A malformed or missing npm `nightly` tag fails closed. | -| Metrics show unavailable | OS support, disk path, executor connectivity | Select supported metrics and verify permissions/network; the collector reports errors per sample | -| Disk total exceeds filesystem expectation | Separate `data` and `backups` rows | Backups are counted twice in the UI total; use volume metrics for capacity decisions | -| Legacy `/tmp/kandev-agent/*` uses disk | Process inventory and open-file references for the exact directory | This is data from older Kandev versions, not a current Storage resource. Stop Kandev, confirm no live process references the target, then remove only the confirmed-inactive legacy directory through host administration. | -| Archived task's remote resource remains | Backend, Docker/Kubernetes/SSH/Sprites, and provider logs | Cleanup is asynchronous and bounded. SSH task directories and existing Kubernetes claims are retained by design; for other leftovers, verify work is preserved, then remove the exact resource manually | -| Sprites reset removed the environment but not the sandbox | **Settings > Executors > Sprites.dev** | Current reset can omit the provider credential during destroy; find the old Kandev-named sandbox and destroy it explicitly | +| Symptom | Check | Action | +| --------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/health` cannot connect | Process-manager and launcher output | Confirm port ownership, database reachability, writable Kandev home, and required executables; then restart once | +| `/ready` stays at 503 while `/health` is 200 | Backend startup logs | Process is alive but still wiring routes, seeding the agent registry, or mounting test-harness routes; give it more time before restarting | +| Status page says unhealthy while `/ready` is 200 | `/api/v1/system/health` issue IDs | Fix Git, GitHub, agent discovery, or Linux inotify warning; readiness and application diagnostics have different meanings | +| Backups page reports a 15-second create timeout | Reload the backup list and inspect the `backup-create` job/log | Large `VACUUM INTO` jobs can still finish; avoid double-clicking and ensure free disk | +| Backup/maintenance fails on PostgreSQL | Active driver on Database page | Use `pg_dump`, provider snapshots, and PostgreSQL maintenance; System backup/vacuum/reset is SQLite-only | +| Restored data looks stale | Whether the backend was restarted immediately | Quit/restart; do not keep using the old open database connections | +| Diagnostic bundle is partial | `manifest.json` warnings, source status, and loss counters | Keep a Kandev browser open for frontend capture; use backend-only when browser evidence is unnecessary | +| Update check returns HTTP 429 | Time since last **Check now** | Wait at least 30 seconds; background checks retry every six hours | +| **Apply update** is absent | Install mode/method and `/service/install.json` | Expected for system, unmanaged, local-checkout, or invalid-metadata installs. A managed npm, npx, or Homebrew user service should offer Apply; reinstall it with the same flags to refresh its identity and metadata, or use the manual package-manager flow. | +| **Nightly** is disabled | Install mode/method and `/service/install.json` | Expected unless this is a verified managed npm/npx user service. Homebrew, Desktop, system-service, unmanaged, local-checkout, invalid-metadata, and unknown installs are Stable-only. | +| Nightly check or save fails | npm access and cached checked time | Verify access to `https://registry.npmjs.org/kandev`, retry after connectivity returns, or keep/select Stable. A malformed or missing npm `nightly` tag fails closed. | +| Metrics show unavailable | OS support, disk path, executor connectivity | Select supported metrics and verify permissions/network; the collector reports errors per sample | +| Disk total exceeds filesystem expectation | Separate `data` and `backups` rows | Backups are counted twice in the UI total; use volume metrics for capacity decisions | +| Legacy `/tmp/kandev-agent/*` uses disk | Process inventory and open-file references for the exact directory | This is data from older Kandev versions, not a current Storage resource. Stop Kandev, confirm no live process references the target, then remove only the confirmed-inactive legacy directory through host administration. | +| Archived task's remote resource remains | Backend, Docker/Kubernetes/SSH/Sprites, and provider logs | Cleanup is asynchronous and bounded. SSH task directories and existing Kubernetes claims are retained by design; for other leftovers, verify work is preserved, then remove the exact resource manually | +| Sprites reset removed the environment but not the sandbox | **Settings > Executors > Sprites.dev** | Current reset can omit the provider credential during destroy; find the old Kandev-named sandbox and destroy it explicitly | ## Related pages diff --git a/docs/public/sessions-and-review.md b/docs/public/sessions-and-review.md index ff8cf943b2..18a53ad429 100644 --- a/docs/public/sessions-and-review.md +++ b/docs/public/sessions-and-review.md @@ -34,11 +34,11 @@ The profile picker shows only profiles compatible with the task executor. If non ### Choose starting context -| Option | What the new session receives | When to use it | -|---|---|---| -| **Blank** | Only the prompt you enter | Independent work that needs no earlier discussion | +| Option | What the new session receives | When to use it | +| ----------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| **Blank** | Only the prompt you enter | Independent work that needs no earlier discussion | | **Copy initial prompt** | Copies the first user message from the currently active session into the editable prompt field | A parallel approach; it is not guaranteed to be the task's original description, so inspect and edit it before launch | -| **Summarize a session** | Inserts a utility-agent summary of the selected conversation into the editable prompt field | Continue or branch from work already discussed | +| **Summarize a session** | Inserts a utility-agent summary of the selected conversation into the editable prompt field | Continue or branch from work already discussed | **Handoff** from an existing session opens the same dialog and selects a summary of that session. Summarization requires a working `summarize-session` utility agent. Review generated summaries: they can omit constraints or decisions. @@ -48,16 +48,16 @@ Prompts support pasted, dropped, or selected attachments. A prompt can contain a Right-click an agent tab on desktop to manage it. Available actions depend on its current state. -| Action | Effect | -|---|---| -| **Rename** | Changes the session's display name | -| **Set as Primary** | Makes a stoppable session the task's primary target | -| **Stop** | Cancels the active agent turn for this session | -| **Resume** | Attempts to continue a completed, failed, or cancelled session | -| **Delete** | Permanently removes the conversation; if it was primary, another session is promoted when possible. The task workspace and its files are kept; a later session reuses them | -| **Share** | Opens the publishing preview for an eligible session | -| **Handoff** | Starts another session with a generated summary of this conversation | -| **Close Others** | Closes other visible agent panels without deleting their sessions | +| Action | Effect | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Rename** | Changes the session's display name | +| **Set as Primary** | Makes a stoppable session the task's primary target | +| **Stop** | Cancels the active agent turn for this session | +| **Resume** | Attempts to continue a completed, failed, or cancelled session | +| **Delete** | Permanently removes the conversation; if it was primary, another session is promoted when possible. The task workspace and its files are kept; a later session reuses them | +| **Share** | Opens the publishing preview for an eligible session | +| **Handoff** | Starts another session with a generated summary of this conversation | +| **Close Others** | Closes other visible agent panels without deleting their sessions | Stopping is not deletion. Resume succeeds only while the executor still has the session record needed to continue. A removed worktree, expired remote environment, restarted executor, removed profile, or missing runtime record can force a fresh session instead. The failure banner offers **Start fresh** when continuation is unavailable. diff --git a/docs/specs/INDEX.md b/docs/specs/INDEX.md index d15076bc5c..69b112dbeb 100644 --- a/docs/specs/INDEX.md +++ b/docs/specs/INDEX.md @@ -4,29 +4,29 @@ This catalog is the entry point for the system-oriented specification layout. Ea ## Systems -| System | Index | Migration | Canonical documents | -| --- | --- | --- | --- | -| Agents | [README](agents/README.md) | complete | 27 requirements, 17 designs | -| Auth | [README](auth/README.md) | complete | 7 requirements, 2 designs | -| CLI | [README](cli/README.md) | complete | 3 requirements, 1 designs | -| Costs | [README](costs/README.md) | complete | 2 requirements, 0 designs | -| Desktop | [README](desktop/README.md) | complete | 1 requirements, 1 designs | -| Executors | [README](executors/README.md) | complete | 3 requirements, 6 designs | -| Integrations | [README](integrations/README.md) | complete | 18 requirements, 21 designs | -| Office | [README](office/README.md) | complete | 19 requirements, 38 designs | -| Platform | [README](platform/README.md) | complete | 30 requirements, 10 designs | -| Plugins | [README](plugins/README.md) | complete | 7 requirements, 9 designs | -| Release | [README](release/README.md) | complete | 5 requirements, 0 designs | -| System page | [README](system-page/README.md) | complete | 3 requirements, 5 designs | -| Tasks | [README](tasks/README.md) | complete | 69 requirements, 12 designs | -| UI | [README](ui/README.md) | complete | 96 requirements, 12 designs | -| Workspaces | [README](workspaces/README.md) | complete | 11 requirements, 3 designs | +| System | Index | Migration | Canonical documents | +| ------------ | -------------------------------- | ----------- | ---------------------------- | +| Agents | [README](agents/README.md) | complete | 27 requirements, 17 designs | +| Auth | [README](auth/README.md) | complete | 7 requirements, 2 designs | +| CLI | [README](cli/README.md) | complete | 3 requirements, 1 designs | +| Costs | [README](costs/README.md) | complete | 2 requirements, 0 designs | +| Desktop | [README](desktop/README.md) | complete | 1 requirements, 1 designs | +| Executors | [README](executors/README.md) | complete | 3 requirements, 6 designs | +| Integrations | [README](integrations/README.md) | complete | 18 requirements, 21 designs | +| Office | [README](office/README.md) | complete | 19 requirements, 38 designs | +| Platform | [README](platform/README.md) | complete | 30 requirements, 10 designs | +| Plugins | [README](plugins/README.md) | complete | 7 requirements, 9 designs | +| Release | [README](release/README.md) | complete | 5 requirements, 0 designs | +| System page | [README](system-page/README.md) | complete | 3 requirements, 5 designs | +| Tasks | [README](tasks/README.md) | complete | 69 requirements, 12 designs | +| UI | [README](ui/README.md) | in_progress | 127 requirements, 56 designs | +| Workspaces | [README](workspaces/README.md) | complete | 11 requirements, 3 designs | ## Migration record The legacy specification sources were migrated from the unstructured root and category directories into the system-oriented layout. Task and workflow sources from PR #2957 remain under `tasks/`; three task-owned sources found outside that tree were folded into the same system during this migration. ----- +--- The former legacy size exceptions for migrated sources were removed. All canonical requirement and system-design documents now pass the repository specification linter. diff --git a/docs/specs/ui/README.md b/docs/specs/ui/README.md index ca735dd063..71e35a5eb1 100644 --- a/docs/specs/ui/README.md +++ b/docs/specs/ui/README.md @@ -6,11 +6,17 @@ migration: in_progress owners: - kandev --- + # UI + ## Scope + UI owns responsive behavior; other systems own behavior/state. + ## Map + ### Requirements + - [ACP model summary](requirements/acp-model-configuration-summary.md) - [ACP Shell Command Output](requirements/acp-shell-command-output.md) - [Adaptive Kanban](requirements/adaptive-kanban.md) @@ -141,6 +147,7 @@ UI owns responsive behavior; other systems own behavior/state. - [WebKit Task Dialog Rendering](requirements/webkit-task-dialog-rendering.md) - [Active workspace first in settings](requirements/workspace-active-first-order.md) - [WebSocket Connectivity Warning](requirements/ws-connectivity-warning.md) + ### Design - [Adaptive Kanban](system-design/adaptive-kanban.md) - [Clarification submit feedback](system-design/clarification-submit-feedback.md) @@ -200,5 +207,7 @@ UI owns responsive behavior; other systems own behavior/state. - [Settings Menu Default](system-design/settings-menu-default.md) - [Transcript history visibility](system-design/task-prompt-transcript-visibility.md) - [Transcript Auto-scroll Stability](system-design/transcript-auto-scroll.md) + ## Related + - [Platform](../platform/README.md)